Debian Codegraph @

gcc/doc/md.texi

raw
1 @c Copyright (C) 1988-2025 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 * Compact Syntax:: Compact syntax for writing machine descriptors.
31 * Predicates:: Controlling what kinds of operands can be used
32 for an insn.
33 * Constraints:: Fine-tuning operand selection.
34 * Standard Names:: Names mark patterns to use for code generation.
35 * Pattern Ordering:: When the order of patterns makes a difference.
36 * Dependent Patterns:: Having one pattern may make you need another.
37 * Jump Patterns:: Special considerations for patterns for jump insns.
38 * Looping Patterns:: How to define patterns for special looping insns.
39 * Insn Canonicalizations::Canonicalization of Instructions
40 * Expander Definitions::Generating a sequence of several RTL insns
41 for a standard operation.
42 * Insn Splitting:: Splitting Instructions into Multiple Instructions.
43 * Including Patterns:: Including Patterns in Machine Descriptions.
44 * Peephole Definitions::Defining machine-specific peephole optimizations.
45 * Insn Attributes:: Specifying the value of attributes for generated insns.
46 * Conditional Execution::Generating @code{define_insn} patterns for
47 predication.
48 * Define Subst:: Generating @code{define_insn} and @code{define_expand}
49 patterns from other patterns.
50 * Constant Definitions::Defining symbolic constants that can be used in the
51 md file.
52 * Iterators:: Using iterators to generate patterns from a template.
53 @end menu
54
55 @node Overview
56 @section Overview of How the Machine Description is Used
57
58 There are three main conversions that happen in the compiler:
59
60 @enumerate
61
62 @item
63 The front end reads the source code and builds a parse tree.
64
65 @item
66 The parse tree is used to generate an RTL insn list based on named
67 instruction patterns.
68
69 @item
70 The insn list is matched against the RTL templates to produce assembler
71 code.
72
73 @end enumerate
74
75 For the generate pass, only the names of the insns matter, from either a
76 named @code{define_insn} or a @code{define_expand}. The compiler will
77 choose the pattern with the right name and apply the operands according
78 to the documentation later in this chapter, without regard for the RTL
79 template or operand constraints. Note that the names the compiler looks
80 for are hard-coded in the compiler---it will ignore unnamed patterns and
81 patterns with names it doesn't know about, but if you don't provide a
82 named pattern it needs, it will abort.
83
84 If a @code{define_insn} is used, the template given is inserted into the
85 insn list. If a @code{define_expand} is used, one of three things
86 happens, based on the condition logic. The condition logic may manually
87 create new insns for the insn list, say via @code{emit_insn()}, and
88 invoke @code{DONE}. For certain named patterns, it may invoke @code{FAIL} to tell the
89 compiler to use an alternate way of performing that task. If it invokes
90 neither @code{DONE} nor @code{FAIL}, the template given in the pattern
91 is inserted, as if the @code{define_expand} were a @code{define_insn}.
92
93 Once the insn list is generated, various optimization passes convert,
94 replace, and rearrange the insns in the insn list. This is where the
95 @code{define_split} and @code{define_peephole} patterns get used, for
96 example.
97
98 Finally, the insn list's RTL is matched up with the RTL templates in the
99 @code{define_insn} patterns, and those patterns are used to emit the
100 final assembly code. For this purpose, each named @code{define_insn}
101 acts like it's unnamed, since the names are ignored.
102
103 @node Patterns
104 @section Everything about Instruction Patterns
105 @cindex patterns
106 @cindex instruction patterns
107
108 @findex define_insn
109 A @code{define_insn} expression is used to define instruction patterns
110 to which insns may be matched. A @code{define_insn} expression contains
111 an incomplete RTL expression, with pieces to be filled in later, operand
112 constraints that restrict how the pieces can be filled in, and an output
113 template or C code to generate the assembler output.
114
115 A @code{define_insn} is an RTL expression containing four or five operands:
116
117 @enumerate
118 @item
119 An optional name @var{n}. When a name is present, the compiler
120 automically generates a C++ function @samp{gen_@var{n}} that takes
121 the operands of the instruction as arguments and returns the instruction's
122 rtx pattern. The compiler also assigns the instruction a unique code
123 @samp{CODE_FOR_@var{n}}, with all such codes belonging to an enum
124 called @code{insn_code}.
125
126 These names serve one of two purposes. The first is to indicate that the
127 instruction performs a certain standard job for the RTL-generation
128 pass of the compiler, such as a move, an addition, or a conditional
129 jump. The second is to help the target generate certain target-specific
130 operations, such as when implementing target-specific intrinsic functions.
131
132 It is better to prefix target-specific names with the name of the
133 target, to avoid any clash with current or future standard names.
134
135 The absence of a name is indicated by writing an empty string
136 where the name should go. Nameless instruction patterns are never
137 used for generating RTL code, but they may permit several simpler insns
138 to be combined later on.
139
140 For the purpose of debugging the compiler, you may also specify a
141 name beginning with the @samp{*} character. Such a name is used only
142 for identifying the instruction in RTL dumps; it is equivalent to having
143 a nameless pattern for all other purposes. Names beginning with the
144 @samp{*} character are not required to be unique.
145
146 The name may also have the form @samp{@@@var{n}}. This has the same
147 effect as a name @samp{@var{n}}, but in addition tells the compiler to
148 generate further helper functions; see @ref{Parameterized Names} for details.
149
150 @item
151 The @dfn{RTL template}: This is a vector of incomplete RTL expressions
152 which describe the semantics of the instruction (@pxref{RTL Template}).
153 It is incomplete because it may contain @code{match_operand},
154 @code{match_operator}, and @code{match_dup} expressions that stand for
155 operands of the instruction.
156
157 If the vector has multiple elements, the RTL template is treated as a
158 @code{parallel} expression.
159
160 @cindex pattern conditions
161 @cindex conditions, in patterns
162 @item
163 The condition: This is a string which contains a C expression. When the
164 compiler attempts to match RTL against a pattern, the condition is
165 evaluated. If the condition evaluates to @code{true}, the match is
166 permitted. The condition may be an empty string, which is treated
167 as always @code{true}.
168
169 @cindex named patterns and conditions
170 For a named pattern, the condition may not depend on the data in the
171 insn being matched, but only the target-machine-type flags. The compiler
172 needs to test these conditions during initialization in order to learn
173 exactly which named instructions are available in a particular run.
174
175 @findex operands
176 For nameless patterns, the condition is applied only when matching an
177 individual insn, and only after the insn has matched the pattern's
178 recognition template. The insn's operands may be found in the vector
179 @code{operands}.
180
181 An instruction condition cannot become more restrictive as compilation
182 progresses. If the condition accepts a particular RTL instruction at
183 one stage of compilation, it must continue to accept that instruction
184 until the final pass. For example, @samp{!reload_completed} and
185 @samp{can_create_pseudo_p ()} are both invalid instruction conditions,
186 because they are true during the earlier RTL passes and false during
187 the later ones. For the same reason, if a condition accepts an
188 instruction before register allocation, it cannot later try to control
189 register allocation by excluding certain register or value combinations.
190
191 Although a condition cannot become more restrictive as compilation
192 progresses, the condition for a nameless pattern @emph{can} become
193 more permissive. For example, a nameless instruction can require
194 @samp{reload_completed} to be true, in which case it only matches
195 after register allocation.
196
197 @item
198 The @dfn{output template} or @dfn{output statement}: This is either
199 a string, or a fragment of C code which returns a string.
200
201 When simple substitution isn't general enough, you can specify a piece
202 of C code to compute the output. @xref{Output Statement}.
203
204 @item
205 The @dfn{insn attributes}: This is an optional vector containing the values of
206 attributes for insns matching this pattern (@pxref{Insn Attributes}).
207 @end enumerate
208
209 @node Example
210 @section Example of @code{define_insn}
211 @cindex @code{define_insn} example
212
213 Here is an example of an instruction pattern, taken from the machine
214 description for the 68000/68020.
215
216 @smallexample
217 (define_insn "tstsi"
218 [(set (cc0)
219 (match_operand:SI 0 "general_operand" "rm"))]
220 ""
221 "*
222 @{
223 if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
224 return \"tstl %0\";
225 return \"cmpl #0,%0\";
226 @}")
227 @end smallexample
228
229 @noindent
230 This can also be written using braced strings:
231
232 @smallexample
233 (define_insn "tstsi"
234 [(set (cc0)
235 (match_operand:SI 0 "general_operand" "rm"))]
236 ""
237 @{
238 if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
239 return "tstl %0";
240 return "cmpl #0,%0";
241 @})
242 @end smallexample
243
244 This describes an instruction which sets the condition codes based on the
245 value of a general operand. It has no condition, so any insn with an RTL
246 description of the form shown may be matched to this pattern. The name
247 @samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL
248 generation pass that, when it is necessary to test such a value, an insn
249 to do so can be constructed using this pattern.
250
251 The output control string is a piece of C code which chooses which
252 output template to return based on the kind of operand and the specific
253 type of CPU for which code is being generated.
254
255 @samp{"rm"} is an operand constraint. Its meaning is explained below.
256
257 @node RTL Template
258 @section RTL Template
259 @cindex RTL insn template
260 @cindex generating insns
261 @cindex insns, generating
262 @cindex recognizing insns
263 @cindex insns, recognizing
264
265 The RTL template is used to define which insns match the particular pattern
266 and how to find their operands. For named patterns, the RTL template also
267 says how to construct an insn from specified operands.
268
269 Construction involves substituting specified operands into a copy of the
270 template. Matching involves determining the values that serve as the
271 operands in the insn being matched. Both of these activities are
272 controlled by special expression types that direct matching and
273 substitution of the operands.
274
275 @table @code
276 @findex match_operand
277 @item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint})
278 This expression is a placeholder for operand number @var{n} of
279 the insn. When constructing an insn, operand number @var{n}
280 will be substituted at this point. When matching an insn, whatever
281 appears at this position in the insn will be taken as operand
282 number @var{n}; but it must satisfy @var{predicate} or this instruction
283 pattern will not match at all.
284
285 Operand numbers must be chosen consecutively counting from zero in
286 each instruction pattern. There may be only one @code{match_operand}
287 expression in the pattern for each operand number. Usually operands
288 are numbered in the order of appearance in @code{match_operand}
289 expressions. In the case of a @code{define_expand}, any operand numbers
290 used only in @code{match_dup} expressions have higher values than all
291 other operand numbers.
292
293 @var{predicate} is a string that is the name of a function that
294 accepts two arguments, an expression and a machine mode.
295 @xref{Predicates}. During matching, the function will be called with
296 the putative operand as the expression and @var{m} as the mode
297 argument (if @var{m} is not specified, @code{VOIDmode} will be used,
298 which normally causes @var{predicate} to accept any mode). If it
299 returns zero, this instruction pattern fails to match.
300 @var{predicate} may be an empty string; then it means no test is to be
301 done on the operand, so anything which occurs in this position is
302 valid.
303
304 Most of the time, @var{predicate} will reject modes other than @var{m}---but
305 not always. For example, the predicate @code{address_operand} uses
306 @var{m} as the mode of memory ref that the address should be valid for.
307 Many predicates accept @code{const_int} nodes even though their mode is
308 @code{VOIDmode}.
309
310 @var{constraint} controls reloading and the choice of the best register
311 class to use for a value, as explained later (@pxref{Constraints}).
312 If the constraint would be an empty string, it can be omitted.
313
314 People are often unclear on the difference between the constraint and the
315 predicate. The predicate helps decide whether a given insn matches the
316 pattern. The constraint plays no role in this decision; instead, it
317 controls various decisions in the case of an insn which does match.
318
319 @findex match_scratch
320 @item (match_scratch:@var{m} @var{n} @var{constraint})
321 This expression is also a placeholder for operand number @var{n}
322 and indicates that operand must be a @code{scratch} or @code{reg}
323 expression.
324
325 When matching patterns, this is equivalent to
326
327 @smallexample
328 (match_operand:@var{m} @var{n} "scratch_operand" @var{constraint})
329 @end smallexample
330
331 but, when generating RTL, it produces a (@code{scratch}:@var{m})
332 expression.
333
334 If the last few expressions in a @code{parallel} are @code{clobber}
335 expressions whose operands are either a hard register or
336 @code{match_scratch}, the combiner can add or delete them when
337 necessary. @xref{Side Effects}.
338
339 @findex match_dup
340 @item (match_dup @var{n})
341 This expression is also a placeholder for operand number @var{n}.
342 It is used when the operand needs to appear more than once in the
343 insn.
344
345 In construction, @code{match_dup} acts just like @code{match_operand}:
346 the operand is substituted into the insn being constructed. But in
347 matching, @code{match_dup} behaves differently. It assumes that operand
348 number @var{n} has already been determined by a @code{match_operand}
349 appearing earlier in the recognition template, and it matches only an
350 identical-looking expression.
351
352 Note that @code{match_dup} should not be used to tell the compiler that
353 a particular register is being used for two operands (example:
354 @code{add} that adds one register to another; the second register is
355 both an input operand and the output operand). Use a matching
356 constraint (@pxref{Simple Constraints}) for those. @code{match_dup} is for the cases where one
357 operand is used in two places in the template, such as an instruction
358 that computes both a quotient and a remainder, where the opcode takes
359 two input operands but the RTL template has to refer to each of those
360 twice; once for the quotient pattern and once for the remainder pattern.
361
362 @findex match_operator
363 @item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}])
364 This pattern is a kind of placeholder for a variable RTL expression
365 code.
366
367 When constructing an insn, it stands for an RTL expression whose
368 expression code is taken from that of operand @var{n}, and whose
369 operands are constructed from the patterns @var{operands}.
370
371 When matching an expression, it matches an expression if the function
372 @var{predicate} returns nonzero on that expression @emph{and} the
373 patterns @var{operands} match the operands of the expression.
374
375 Suppose that the function @code{commutative_operator} is defined as
376 follows, to match any expression whose operator is one of the
377 commutative arithmetic operators of RTL and whose mode is @var{mode}:
378
379 @smallexample
380 int
381 commutative_operator (x, mode)
382 rtx x;
383 machine_mode mode;
384 @{
385 enum rtx_code code = GET_CODE (x);
386 if (GET_MODE (x) != mode)
387 return 0;
388 return (GET_RTX_CLASS (code) == RTX_COMM_ARITH
389 || code == EQ || code == NE);
390 @}
391 @end smallexample
392
393 Then the following pattern will match any RTL expression consisting
394 of a commutative operator applied to two general operands:
395
396 @smallexample
397 (match_operator:SI 3 "commutative_operator"
398 [(match_operand:SI 1 "general_operand" "g")
399 (match_operand:SI 2 "general_operand" "g")])
400 @end smallexample
401
402 Here the vector @code{[@var{operands}@dots{}]} contains two patterns
403 because the expressions to be matched all contain two operands.
404
405 When this pattern does match, the two operands of the commutative
406 operator are recorded as operands 1 and 2 of the insn. (This is done
407 by the two instances of @code{match_operand}.) Operand 3 of the insn
408 will be the entire commutative expression: use @code{GET_CODE
409 (operands[3])} to see which commutative operator was used.
410
411 The machine mode @var{m} of @code{match_operator} works like that of
412 @code{match_operand}: it is passed as the second argument to the
413 predicate function, and that function is solely responsible for
414 deciding whether the expression to be matched ``has'' that mode.
415
416 When constructing an insn, argument 3 of the gen-function will specify
417 the operation (i.e.@: the expression code) for the expression to be
418 made. It should be an RTL expression, whose expression code is copied
419 into a new expression whose operands are arguments 1 and 2 of the
420 gen-function. The subexpressions of argument 3 are not used;
421 only its expression code matters.
422
423 When @code{match_operator} is used in a pattern for matching an insn,
424 it usually best if the operand number of the @code{match_operator}
425 is higher than that of the actual operands of the insn. This improves
426 register allocation because the register allocator often looks at
427 operands 1 and 2 of insns to see if it can do register tying.
428
429 There is no way to specify constraints in @code{match_operator}. The
430 operand of the insn which corresponds to the @code{match_operator}
431 never has any constraints because it is never reloaded as a whole.
432 However, if parts of its @var{operands} are matched by
433 @code{match_operand} patterns, those parts may have constraints of
434 their own.
435
436 @findex match_op_dup
437 @item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}])
438 Like @code{match_dup}, except that it applies to operators instead of
439 operands. When constructing an insn, operand number @var{n} will be
440 substituted at this point. But in matching, @code{match_op_dup} behaves
441 differently. It assumes that operand number @var{n} has already been
442 determined by a @code{match_operator} appearing earlier in the
443 recognition template, and it matches only an identical-looking
444 expression.
445
446 @findex match_parallel
447 @item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}])
448 This pattern is a placeholder for an insn that consists of a
449 @code{parallel} expression with a variable number of elements. This
450 expression should only appear at the top level of an insn pattern.
451
452 When constructing an insn, operand number @var{n} will be substituted at
453 this point. When matching an insn, it matches if the body of the insn
454 is a @code{parallel} expression with at least as many elements as the
455 vector of @var{subpat} expressions in the @code{match_parallel}, if each
456 @var{subpat} matches the corresponding element of the @code{parallel},
457 @emph{and} the function @var{predicate} returns nonzero on the
458 @code{parallel} that is the body of the insn. It is the responsibility
459 of the predicate to validate elements of the @code{parallel} beyond
460 those listed in the @code{match_parallel}.
461
462 A typical use of @code{match_parallel} is to match load and store
463 multiple expressions, which can contain a variable number of elements
464 in a @code{parallel}. For example,
465
466 @smallexample
467 (define_insn ""
468 [(match_parallel 0 "load_multiple_operation"
469 [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
470 (match_operand:SI 2 "memory_operand" "m"))
471 (use (reg:SI 179))
472 (clobber (reg:SI 179))])]
473 ""
474 "loadm 0,0,%1,%2")
475 @end smallexample
476
477 This example comes from @file{a29k.md}. The function
478 @code{load_multiple_operation} is defined in @file{a29k.c} and checks
479 that subsequent elements in the @code{parallel} are the same as the
480 @code{set} in the pattern, except that they are referencing subsequent
481 registers and memory locations.
482
483 An insn that matches this pattern might look like:
484
485 @smallexample
486 (parallel
487 [(set (reg:SI 20) (mem:SI (reg:SI 100)))
488 (use (reg:SI 179))
489 (clobber (reg:SI 179))
490 (set (reg:SI 21)
491 (mem:SI (plus:SI (reg:SI 100)
492 (const_int 4))))
493 (set (reg:SI 22)
494 (mem:SI (plus:SI (reg:SI 100)
495 (const_int 8))))])
496 @end smallexample
497
498 @findex match_par_dup
499 @item (match_par_dup @var{n} [@var{subpat}@dots{}])
500 Like @code{match_op_dup}, but for @code{match_parallel} instead of
501 @code{match_operator}.
502
503 @end table
504
505 @node Output Template
506 @section Output Templates and Operand Substitution
507 @cindex output templates
508 @cindex operand substitution
509
510 @cindex @samp{%} in template
511 @cindex percent sign
512 The @dfn{output template} is a string which specifies how to output the
513 assembler code for an instruction pattern. Most of the template is a
514 fixed string which is output literally. The character @samp{%} is used
515 to specify where to substitute an operand; it can also be used to
516 identify places where different variants of the assembler require
517 different syntax.
518
519 In the simplest case, a @samp{%} followed by a digit @var{n} says to output
520 operand @var{n} at that point in the string.
521
522 @samp{%} followed by a letter and a digit says to output an operand in an
523 alternate fashion. Four letters have standard, built-in meanings described
524 below. The machine description macro @code{PRINT_OPERAND} can define
525 additional letters with nonstandard meanings.
526
527 @samp{%c@var{digit}} can be used to substitute an operand that is a
528 constant value without the syntax that normally indicates an immediate
529 operand.
530
531 @samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of
532 the constant is negated before printing.
533
534 @samp{%a@var{digit}} can be used to substitute an operand as if it were a
535 memory reference, with the actual operand treated as the address. This may
536 be useful when outputting a ``load address'' instruction, because often the
537 assembler syntax for such an instruction requires you to write the operand
538 as if it were a memory reference.
539
540 @samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump
541 instruction.
542
543 @samp{%=} outputs a number which is unique to each instruction in the
544 entire compilation. This is useful for making local labels to be
545 referred to more than once in a single template that generates multiple
546 assembler instructions.
547
548 @samp{%} followed by a punctuation character specifies a substitution that
549 does not use an operand. Only one case is standard: @samp{%%} outputs a
550 @samp{%} into the assembler code. Other nonstandard cases can be
551 defined in the @code{PRINT_OPERAND} macro. You must also define
552 which punctuation characters are valid with the
553 @code{PRINT_OPERAND_PUNCT_VALID_P} macro.
554
555 @cindex \
556 @cindex backslash
557 The template may generate multiple assembler instructions. Write the text
558 for the instructions, with @samp{\;} between them.
559
560 @cindex matching operands
561 When the RTL contains two operands which are required by constraint to match
562 each other, the output template must refer only to the lower-numbered operand.
563 Matching operands are not always identical, and the rest of the compiler
564 arranges to put the proper RTL expression for printing into the lower-numbered
565 operand.
566
567 One use of nonstandard letters or punctuation following @samp{%} is to
568 distinguish between different assembler languages for the same machine; for
569 example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax
570 requires periods in most opcode names, while MIT syntax does not. For
571 example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
572 syntax. The same file of patterns is used for both kinds of output syntax,
573 but the character sequence @samp{%.} is used in each place where Motorola
574 syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax
575 defines the sequence to output a period; the macro for MIT syntax defines
576 it to do nothing.
577
578 @cindex @code{#} in template
579 As a special case, a template consisting of the single character @code{#}
580 instructs the compiler to first split the insn, and then output the
581 resulting instructions separately. This helps eliminate redundancy in the
582 output templates. If you have a @code{define_insn} that needs to emit
583 multiple assembler instructions, and there is a matching @code{define_split}
584 already defined, then you can simply use @code{#} as the output template
585 instead of writing an output template that emits the multiple assembler
586 instructions.
587
588 Note that @code{#} only has an effect while generating assembly code;
589 it does not affect whether a split occurs earlier. An associated
590 @code{define_split} must exist and it must be suitable for use after
591 register allocation.
592
593 If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct
594 of the form @samp{@{option0|option1|option2@}} in the templates. These
595 describe multiple variants of assembler language syntax.
596 @xref{Instruction Output}.
597
598 @node Output Statement
599 @section C Statements for Assembler Output
600 @cindex output statements
601 @cindex C statements for assembler output
602 @cindex generating assembler output
603
604 Often a single fixed template string cannot produce correct and efficient
605 assembler code for all the cases that are recognized by a single
606 instruction pattern. For example, the opcodes may depend on the kinds of
607 operands; or some unfortunate combinations of operands may require extra
608 machine instructions.
609
610 If the output control string starts with a @samp{@@}, then it is actually
611 a series of templates, each on a separate line. (Blank lines and
612 leading spaces and tabs are ignored.) The templates correspond to the
613 pattern's constraint alternatives (@pxref{Multi-Alternative}). For example,
614 if a target machine has a two-address add instruction @samp{addr} to add
615 into a register and another @samp{addm} to add a register to memory, you
616 might write this pattern:
617
618 @smallexample
619 (define_insn "addsi3"
620 [(set (match_operand:SI 0 "general_operand" "=r,m")
621 (plus:SI (match_operand:SI 1 "general_operand" "0,0")
622 (match_operand:SI 2 "general_operand" "g,r")))]
623 ""
624 "@@
625 addr %2,%0
626 addm %2,%0")
627 @end smallexample
628
629 @cindex @code{*} in template
630 @cindex asterisk in template
631 If the output control string starts with a @samp{*}, then it is not an
632 output template but rather a piece of C program that should compute a
633 template. It should execute a @code{return} statement to return the
634 template-string you want. Most such templates use C string literals, which
635 require doublequote characters to delimit them. To include these
636 doublequote characters in the string, prefix each one with @samp{\}.
637
638 If the output control string is written as a brace block instead of a
639 double-quoted string, it is automatically assumed to be C code. In that
640 case, it is not necessary to put in a leading asterisk, or to escape the
641 doublequotes surrounding C string literals.
642
643 The operands may be found in the array @code{operands}, whose C data type
644 is @code{rtx []}.
645
646 It is very common to select different ways of generating assembler code
647 based on whether an immediate operand is within a certain range. Be
648 careful when doing this, because the result of @code{INTVAL} is an
649 integer on the host machine. If the host machine has more bits in an
650 @code{int} than the target machine has in the mode in which the constant
651 will be used, then some of the bits you get from @code{INTVAL} will be
652 superfluous. For proper results, you must carefully disregard the
653 values of those bits.
654
655 @findex output_asm_insn
656 It is possible to output an assembler instruction and then go on to output
657 or compute more of them, using the subroutine @code{output_asm_insn}. This
658 receives two arguments: a template-string and a vector of operands. The
659 vector may be @code{operands}, or it may be another array of @code{rtx}
660 that you declare locally and initialize yourself.
661
662 @findex which_alternative
663 When an insn pattern has multiple alternatives in its constraints, often
664 the appearance of the assembler code is determined mostly by which alternative
665 was matched. When this is so, the C code can test the variable
666 @code{which_alternative}, which is the ordinal number of the alternative
667 that was actually satisfied (0 for the first, 1 for the second alternative,
668 etc.).
669
670 For example, suppose there are two opcodes for storing zero, @samp{clrreg}
671 for registers and @samp{clrmem} for memory locations. Here is how
672 a pattern could use @code{which_alternative} to choose between them:
673
674 @smallexample
675 (define_insn ""
676 [(set (match_operand:SI 0 "general_operand" "=r,m")
677 (const_int 0))]
678 ""
679 @{
680 return (which_alternative == 0
681 ? "clrreg %0" : "clrmem %0");
682 @})
683 @end smallexample
684
685 The example above, where the assembler code to generate was
686 @emph{solely} determined by the alternative, could also have been specified
687 as follows, having the output control string start with a @samp{@@}:
688
689 @smallexample
690 @group
691 (define_insn ""
692 [(set (match_operand:SI 0 "general_operand" "=r,m")
693 (const_int 0))]
694 ""
695 "@@
696 clrreg %0
697 clrmem %0")
698 @end group
699 @end smallexample
700
701 If you just need a little bit of C code in one (or a few) alternatives,
702 you can use @samp{*} inside of a @samp{@@} multi-alternative template:
703
704 @smallexample
705 @group
706 (define_insn ""
707 [(set (match_operand:SI 0 "general_operand" "=r,<,m")
708 (const_int 0))]
709 ""
710 "@@
711 clrreg %0
712 * return stack_mem_p (operands[0]) ? \"push 0\" : \"clrmem %0\";
713 clrmem %0")
714 @end group
715 @end smallexample
716
717 @node Compact Syntax
718 @section Compact Syntax
719 @cindex compact syntax
720
721 When a @code{define_insn} or @code{define_insn_and_split} has multiple
722 alternatives it may be beneficial to use the compact syntax when specifying
723 alternatives.
724
725 This syntax puts the constraints and attributes on the same horizontal line as
726 the instruction assembly template.
727
728 As an example
729
730 @smallexample
731 @group
732 (define_insn_and_split ""
733 [(set (match_operand:SI 0 "nonimmediate_operand" "=r,k,r,r,r,r")
734 (match_operand:SI 1 "aarch64_mov_operand" " r,r,k,M,n,Usv"))]
735 ""
736 "@@
737 mov\\t%w0, %w1
738 mov\\t%w0, %w1
739 mov\\t%w0, %w1
740 mov\\t%w0, %1
741 #
742 * return aarch64_output_sve_cnt_immediate ('cnt', '%x0', operands[1]);"
743 "&& true"
744 [(const_int 0)]
745 @{
746 aarch64_expand_mov_immediate (operands[0], operands[1]);
747 DONE;
748 @}
749 [(set_attr "type" "mov_reg,mov_reg,mov_reg,mov_imm,mov_imm,mov_imm")
750 (set_attr "arch" "*,*,*,*,*,sve")
751 (set_attr "length" "4,4,4,4,*, 4")
752 ]
753 )
754 @end group
755 @end smallexample
756
757 can be better expressed as:
758
759 @smallexample
760 @group
761 (define_insn_and_split ""
762 [(set (match_operand:SI 0 "nonimmediate_operand")
763 (match_operand:SI 1 "aarch64_mov_operand"))]
764 ""
765 @{@@ [cons: =0, 1; attrs: type, arch, length]
766 [r , r ; mov_reg , * , 4] mov\t%w0, %w1
767 [k , r ; mov_reg , * , 4] ^
768 [r , k ; mov_reg , * , 4] ^
769 [r , M ; mov_imm , * , 4] mov\t%w0, %1
770 [r , n ; mov_imm , * , *] #
771 [r , Usv; mov_imm , sve , 4] << aarch64_output_sve_cnt_immediate ("cnt", "%x0", operands[1]);
772 @}
773 "&& true"
774 [(const_int 0)]
775 @{
776 aarch64_expand_mov_immediate (operands[0], operands[1]);
777 DONE;
778 @}
779 )
780 @end group
781 @end smallexample
782
783 The syntax rules are as follows:
784 @itemize @bullet
785 @item
786 Templates must start with @samp{@{@@} to use the new syntax.
787
788 @item
789 @samp{@{@@} is followed by a layout in square brackets which is @samp{cons:}
790 followed by a comma-separated list of @code{match_operand}/@code{match_scratch}
791 operand numbers, then a semicolon, followed by the same for attributes
792 (@samp{attrs:}). Operand modifiers like @code{=} and @code{+} can be placed
793 before an operand number.
794 Both sections are optional (so you can use only @samp{cons}, or only
795 @samp{attrs}, or both), and @samp{cons} must come before @samp{attrs} if
796 present.
797
798 @item
799 Each alternative begins with any amount of whitespace.
800
801 @item
802 Following the whitespace is a comma-separated list of "constraints" and/or
803 "attributes" within brackets @code{[]}, with sections separated by a semicolon.
804
805 @item
806 Should you want to copy the previous asm line, the symbol @code{^} can be used.
807 This allows less copy pasting between alternative and reduces the number of
808 lines to update on changes.
809
810 @item
811 When using C functions for output, the idiom @samp{* return @var{function};}
812 can be replaced with the shorthand @samp{<< @var{function};}.
813
814 @item
815 Following the closing @samp{]} is any amount of whitespace, and then the actual
816 asm output.
817
818 @item
819 Spaces are allowed in the list (they will simply be removed).
820
821 @item
822 All constraint alternatives should be specified. For example, a list of
823 of three blank alternatives should be written @samp{[,,]} rather than
824 @samp{[]}.
825
826 @item
827 All attribute alternatives should be non-empty, with @samp{*}
828 representing the default attribute value. For example, a list of three
829 default attribute values should be written @samp{[*,*,*]} rather than
830 @samp{[]}.
831
832 @item
833 Within an @samp{@{@@} block both multiline and singleline C comments are
834 allowed, but when used outside of a C block they must be the only non-whitespace
835 blocks on the line.
836
837 @item
838 Within an @samp{@{@@} block, any iterators that do not get expanded will result
839 in an error. If for some reason it is required to have @code{<} or @code{>} in
840 the output then these must be escaped using @samp{\}.
841
842 @item
843 It is possible to use the @samp{attrs} list to specify some attributes and to
844 use the normal @code{set_attr} syntax to specify other attributes. There must
845 not be any overlap between the two lists.
846
847 In other words, the following is valid:
848 @smallexample
849 @group
850 (define_insn_and_split ""
851 [(set (match_operand:SI 0 "nonimmediate_operand")
852 (match_operand:SI 1 "aarch64_mov_operand"))]
853 ""
854 @{@@ [cons: 0, 1; attrs: type, arch, length]@}
855 @dots{}
856 [(set_attr "foo" "mov_imm")]
857 )
858 @end group
859 @end smallexample
860
861 but this is not valid:
862 @smallexample
863 @group
864 (define_insn_and_split ""
865 [(set (match_operand:SI 0 "nonimmediate_operand")
866 (match_operand:SI 1 "aarch64_mov_operand"))]
867 ""
868 @{@@ [cons: 0, 1; attrs: type, arch, length]@}
869 @dots{}
870 [(set_attr "arch" "bar")
871 (set_attr "foo" "mov_imm")]
872 )
873 @end group
874 @end smallexample
875
876 because it specifies @code{arch} twice.
877 @end itemize
878
879 @node Predicates
880 @section Predicates
881 @cindex predicates
882 @cindex operand predicates
883 @cindex operator predicates
884
885 A predicate determines whether a @code{match_operand} or
886 @code{match_operator} expression matches, and therefore whether the
887 surrounding instruction pattern will be used for that combination of
888 operands. GCC has a number of machine-independent predicates, and you
889 can define machine-specific predicates as needed. By convention,
890 predicates used with @code{match_operand} have names that end in
891 @samp{_operand}, and those used with @code{match_operator} have names
892 that end in @samp{_operator}.
893
894 All predicates are boolean functions (in the mathematical sense) of
895 two arguments: the RTL expression that is being considered at that
896 position in the instruction pattern, and the machine mode that the
897 @code{match_operand} or @code{match_operator} specifies. In this
898 section, the first argument is called @var{op} and the second argument
899 @var{mode}. Predicates can be called from C as ordinary two-argument
900 functions; this can be useful in output templates or other
901 machine-specific code.
902
903 Operand predicates can allow operands that are not actually acceptable
904 to the hardware, as long as the constraints give reload the ability to
905 fix them up (@pxref{Constraints}). However, GCC will usually generate
906 better code if the predicates specify the requirements of the machine
907 instructions as closely as possible. Reload cannot fix up operands
908 that must be constants (``immediate operands''); you must use a
909 predicate that allows only constants, or else enforce the requirement
910 in the extra condition.
911
912 @cindex predicates and machine modes
913 @cindex normal predicates
914 @cindex special predicates
915 Most predicates handle their @var{mode} argument in a uniform manner.
916 If @var{mode} is @code{VOIDmode} (unspecified), then @var{op} can have
917 any mode. If @var{mode} is anything else, then @var{op} must have the
918 same mode, unless @var{op} is a @code{CONST_INT} or integer
919 @code{CONST_DOUBLE}. These RTL expressions always have
920 @code{VOIDmode}, so it would be counterproductive to check that their
921 mode matches. Instead, predicates that accept @code{CONST_INT} and/or
922 integer @code{CONST_DOUBLE} check that the value stored in the
923 constant will fit in the requested mode.
924
925 Predicates with this behavior are called @dfn{normal}.
926 @command{genrecog} can optimize the instruction recognizer based on
927 knowledge of how normal predicates treat modes. It can also diagnose
928 certain kinds of common errors in the use of normal predicates; for
929 instance, it is almost always an error to use a normal predicate
930 without specifying a mode.
931
932 Predicates that do something different with their @var{mode} argument
933 are called @dfn{special}. The generic predicates
934 @code{address_operand} and @code{pmode_register_operand} are special
935 predicates. @command{genrecog} does not do any optimizations or
936 diagnosis when special predicates are used.
937
938 @menu
939 * Machine-Independent Predicates:: Predicates available to all back ends.
940 * Defining Predicates:: How to write machine-specific predicate
941 functions.
942 @end menu
943
944 @node Machine-Independent Predicates
945 @subsection Machine-Independent Predicates
946 @cindex machine-independent predicates
947 @cindex generic predicates
948
949 These are the generic predicates available to all back ends. They are
950 defined in @file{recog.cc}. The first category of predicates allow
951 only constant, or @dfn{immediate}, operands.
952
953 @defun immediate_operand
954 This predicate allows any sort of constant that fits in @var{mode}.
955 It is an appropriate choice for instructions that take operands that
956 must be constant.
957 @end defun
958
959 @defun const_int_operand
960 This predicate allows any @code{CONST_INT} expression that fits in
961 @var{mode}. It is an appropriate choice for an immediate operand that
962 does not allow a symbol or label.
963 @end defun
964
965 @defun const_double_operand
966 This predicate accepts any @code{CONST_DOUBLE} expression that has
967 exactly @var{mode}. If @var{mode} is @code{VOIDmode}, it will also
968 accept @code{CONST_INT}. It is intended for immediate floating point
969 constants.
970 @end defun
971
972 @noindent
973 The second category of predicates allow only some kind of machine
974 register.
975
976 @defun register_operand
977 This predicate allows any @code{REG} or @code{SUBREG} expression that
978 is valid for @var{mode}. It is often suitable for arithmetic
979 instruction operands on a RISC machine.
980 @end defun
981
982 @defun pmode_register_operand
983 This is a slight variant on @code{register_operand} which works around
984 a limitation in the machine-description reader.
985
986 @smallexample
987 (match_operand @var{n} "pmode_register_operand" @var{constraint})
988 @end smallexample
989
990 @noindent
991 means exactly what
992
993 @smallexample
994 (match_operand:P @var{n} "register_operand" @var{constraint})
995 @end smallexample
996
997 @noindent
998 would mean, if the machine-description reader accepted @samp{:P}
999 mode suffixes. Unfortunately, it cannot, because @code{Pmode} is an
1000 alias for some other mode, and might vary with machine-specific
1001 options. @xref{Misc}.
1002 @end defun
1003
1004 @defun scratch_operand
1005 This predicate allows hard registers and @code{SCRATCH} expressions,
1006 but not pseudo-registers. It is used internally by @code{match_scratch};
1007 it should not be used directly.
1008 @end defun
1009
1010 @noindent
1011 The third category of predicates allow only some kind of memory reference.
1012
1013 @defun memory_operand
1014 This predicate allows any valid reference to a quantity of mode
1015 @var{mode} in memory, as determined by the weak form of
1016 @code{GO_IF_LEGITIMATE_ADDRESS} (@pxref{Addressing Modes}).
1017 @end defun
1018
1019 @defun address_operand
1020 This predicate is a little unusual; it allows any operand that is a
1021 valid expression for the @emph{address} of a quantity of mode
1022 @var{mode}, again determined by the weak form of
1023 @code{GO_IF_LEGITIMATE_ADDRESS}. To first order, if
1024 @samp{@w{(mem:@var{mode} (@var{exp}))}} is acceptable to
1025 @code{memory_operand}, then @var{exp} is acceptable to
1026 @code{address_operand}. Note that @var{exp} does not necessarily have
1027 the mode @var{mode}.
1028 @end defun
1029
1030 @defun indirect_operand
1031 This is a stricter form of @code{memory_operand} which allows only
1032 memory references with a @code{general_operand} as the address
1033 expression. New uses of this predicate are discouraged, because
1034 @code{general_operand} is very permissive, so it's hard to tell what
1035 an @code{indirect_operand} does or does not allow. If a target has
1036 different requirements for memory operands for different instructions,
1037 it is better to define target-specific predicates which enforce the
1038 hardware's requirements explicitly.
1039 @end defun
1040
1041 @defun push_operand
1042 This predicate allows a memory reference suitable for pushing a value
1043 onto the stack. This will be a @code{MEM} which refers to
1044 @code{stack_pointer_rtx}, with a side effect in its address expression
1045 (@pxref{Incdec}); which one is determined by the
1046 @code{STACK_PUSH_CODE} macro (@pxref{Frame Layout}).
1047 @end defun
1048
1049 @defun pop_operand
1050 This predicate allows a memory reference suitable for popping a value
1051 off the stack. Again, this will be a @code{MEM} referring to
1052 @code{stack_pointer_rtx}, with a side effect in its address
1053 expression. However, this time @code{STACK_POP_CODE} is expected.
1054 @end defun
1055
1056 @noindent
1057 The fourth category of predicates allow some combination of the above
1058 operands.
1059
1060 @defun nonmemory_operand
1061 This predicate allows any immediate or register operand valid for @var{mode}.
1062 @end defun
1063
1064 @defun nonimmediate_operand
1065 This predicate allows any register or memory operand valid for @var{mode}.
1066 @end defun
1067
1068 @defun general_operand
1069 This predicate allows any immediate, register, or memory operand
1070 valid for @var{mode}.
1071 @end defun
1072
1073 @noindent
1074 Finally, there are two generic operator predicates.
1075
1076 @defun comparison_operator
1077 This predicate matches any expression which performs an arithmetic
1078 comparison in @var{mode}; that is, @code{COMPARISON_P} is true for the
1079 expression code.
1080 @end defun
1081
1082 @defun ordered_comparison_operator
1083 This predicate matches any expression which performs an arithmetic
1084 comparison in @var{mode} and whose expression code is valid for integer
1085 modes; that is, the expression code will be one of @code{eq}, @code{ne},
1086 @code{lt}, @code{ltu}, @code{le}, @code{leu}, @code{gt}, @code{gtu},
1087 @code{ge}, @code{geu}.
1088 @end defun
1089
1090 @node Defining Predicates
1091 @subsection Defining Machine-Specific Predicates
1092 @cindex defining predicates
1093 @findex define_predicate
1094 @findex define_special_predicate
1095
1096 Many machines have requirements for their operands that cannot be
1097 expressed precisely using the generic predicates. You can define
1098 additional predicates using @code{define_predicate} and
1099 @code{define_special_predicate} expressions. These expressions have
1100 three operands:
1101
1102 @itemize @bullet
1103 @item
1104 The name of the predicate, as it will be referred to in
1105 @code{match_operand} or @code{match_operator} expressions.
1106
1107 @item
1108 An RTL expression which evaluates to true if the predicate allows the
1109 operand @var{op}, false if it does not. This expression can only use
1110 the following RTL codes:
1111
1112 @table @code
1113 @item MATCH_OPERAND
1114 When written inside a predicate expression, a @code{MATCH_OPERAND}
1115 expression evaluates to true if the predicate it names would allow
1116 @var{op}. The operand number and constraint are ignored. Due to
1117 limitations in @command{genrecog}, you can only refer to generic
1118 predicates and predicates that have already been defined.
1119
1120 @item MATCH_CODE
1121 This expression evaluates to true if @var{op} or a specified
1122 subexpression of @var{op} has one of a given list of RTX codes.
1123
1124 The first operand of this expression is a string constant containing a
1125 comma-separated list of RTX code names (in lower case). These are the
1126 codes for which the @code{MATCH_CODE} will be true.
1127
1128 The second operand is a string constant which indicates what
1129 subexpression of @var{op} to examine. If it is absent or the empty
1130 string, @var{op} itself is examined. Otherwise, the string constant
1131 must be a sequence of digits and/or lowercase letters. Each character
1132 indicates a subexpression to extract from the current expression; for
1133 the first character this is @var{op}, for the second and subsequent
1134 characters it is the result of the previous character. A digit
1135 @var{n} extracts @samp{@w{XEXP (@var{e}, @var{n})}}; a letter @var{l}
1136 extracts @samp{@w{XVECEXP (@var{e}, 0, @var{n})}} where @var{n} is the
1137 alphabetic ordinal of @var{l} (0 for `a', 1 for 'b', and so on). The
1138 @code{MATCH_CODE} then examines the RTX code of the subexpression
1139 extracted by the complete string. It is not possible to extract
1140 components of an @code{rtvec} that is not at position 0 within its RTX
1141 object.
1142
1143 @item MATCH_TEST
1144 This expression has one operand, a string constant containing a C
1145 expression. The predicate's arguments, @var{op} and @var{mode}, are
1146 available with those names in the C expression. The @code{MATCH_TEST}
1147 evaluates to true if the C expression evaluates to a nonzero value.
1148 @code{MATCH_TEST} expressions must not have side effects.
1149
1150 @item AND
1151 @itemx IOR
1152 @itemx NOT
1153 @itemx IF_THEN_ELSE
1154 The basic @samp{MATCH_} expressions can be combined using these
1155 logical operators, which have the semantics of the C operators
1156 @samp{&&}, @samp{||}, @samp{!}, and @samp{@w{? :}} respectively. As
1157 in Common Lisp, you may give an @code{AND} or @code{IOR} expression an
1158 arbitrary number of arguments; this has exactly the same effect as
1159 writing a chain of two-argument @code{AND} or @code{IOR} expressions.
1160 @end table
1161
1162 @item
1163 An optional block of C code, which should execute
1164 @samp{@w{return true}} if the predicate is found to match and
1165 @samp{@w{return false}} if it does not. It must not have any side
1166 effects. The predicate arguments, @var{op} and @var{mode}, are
1167 available with those names.
1168
1169 If a code block is present in a predicate definition, then the RTL
1170 expression must evaluate to true @emph{and} the code block must
1171 execute @samp{@w{return true}} for the predicate to allow the operand.
1172 The RTL expression is evaluated first; do not re-check anything in the
1173 code block that was checked in the RTL expression.
1174 @end itemize
1175
1176 The program @command{genrecog} scans @code{define_predicate} and
1177 @code{define_special_predicate} expressions to determine which RTX
1178 codes are possibly allowed. You should always make this explicit in
1179 the RTL predicate expression, using @code{MATCH_OPERAND} and
1180 @code{MATCH_CODE}.
1181
1182 Here is an example of a simple predicate definition, from the IA64
1183 machine description:
1184
1185 @smallexample
1186 @group
1187 ;; @r{True if @var{op} is a @code{SYMBOL_REF} which refers to the sdata section.}
1188 (define_predicate "small_addr_symbolic_operand"
1189 (and (match_code "symbol_ref")
1190 (match_test "SYMBOL_REF_SMALL_ADDR_P (op)")))
1191 @end group
1192 @end smallexample
1193
1194 @noindent
1195 And here is another, showing the use of the C block.
1196
1197 @smallexample
1198 @group
1199 ;; @r{True if @var{op} is a register operand that is (or could be) a GR reg.}
1200 (define_predicate "gr_register_operand"
1201 (match_operand 0 "register_operand")
1202 @{
1203 unsigned int regno;
1204 if (GET_CODE (op) == SUBREG)
1205 op = SUBREG_REG (op);
1206
1207 regno = REGNO (op);
1208 return (regno >= FIRST_PSEUDO_REGISTER || GENERAL_REGNO_P (regno));
1209 @})
1210 @end group
1211 @end smallexample
1212
1213 Predicates written with @code{define_predicate} automatically include
1214 a test that @var{mode} is @code{VOIDmode}, or @var{op} has the same
1215 mode as @var{mode}, or @var{op} is a @code{CONST_INT} or
1216 @code{CONST_DOUBLE}. They do @emph{not} check specifically for
1217 integer @code{CONST_DOUBLE}, nor do they test that the value of either
1218 kind of constant fits in the requested mode. This is because
1219 target-specific predicates that take constants usually have to do more
1220 stringent value checks anyway. If you need the exact same treatment
1221 of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic predicates
1222 provide, use a @code{MATCH_OPERAND} subexpression to call
1223 @code{const_int_operand}, @code{const_double_operand}, or
1224 @code{immediate_operand}.
1225
1226 Predicates written with @code{define_special_predicate} do not get any
1227 automatic mode checks, and are treated as having special mode handling
1228 by @command{genrecog}.
1229
1230 The program @command{genpreds} is responsible for generating code to
1231 test predicates. It also writes a header file containing function
1232 declarations for all machine-specific predicates. It is not necessary
1233 to declare these predicates in @file{@var{cpu}-protos.h}.
1234 @end ifset
1235
1236 @c Most of this node appears by itself (in a different place) even
1237 @c when the INTERNALS flag is clear. Passages that require the internals
1238 @c manual's context are conditionalized to appear only in the internals manual.
1239 @ifset INTERNALS
1240 @node Constraints
1241 @section Operand Constraints
1242 @cindex operand constraints
1243 @cindex constraints
1244
1245 Each @code{match_operand} in an instruction pattern can specify
1246 constraints for the operands allowed. The constraints allow you to
1247 fine-tune matching within the set of operands allowed by the
1248 predicate.
1249
1250 @end ifset
1251 @ifclear INTERNALS
1252 @node Constraints
1253 @section Constraints for @code{asm} Operands
1254 @cindex operand constraints, @code{asm}
1255 @cindex constraints, @code{asm}
1256 @cindex @code{asm} constraints
1257
1258 Here are specific details on what constraint letters you can use with
1259 @code{asm} operands.
1260 @end ifclear
1261 Constraints can say whether
1262 an operand may be in a register, and which kinds of register; whether the
1263 operand can be a memory reference, and which kinds of address; whether the
1264 operand may be an immediate constant, and which possible values it may
1265 have. Constraints can also require two operands to match.
1266 Side-effects aren't allowed in operands of inline @code{asm}, unless
1267 @samp{<} or @samp{>} constraints are used, because there is no guarantee
1268 that the side effects will happen exactly once in an instruction that can update
1269 the addressing register.
1270
1271 @ifset INTERNALS
1272 @menu
1273 * Simple Constraints:: Basic use of constraints.
1274 * Multi-Alternative:: When an insn has two alternative constraint-patterns.
1275 * Class Preferences:: Constraints guide which hard register to put things in.
1276 * Modifiers:: More precise control over effects of constraints.
1277 * Machine Constraints:: Existing constraints for some particular machines.
1278 * Disable Insn Alternatives:: Disable insn alternatives using attributes.
1279 * Define Constraints:: How to define machine-specific constraints.
1280 * C Constraint Interface:: How to test constraints from C code.
1281 @end menu
1282 @end ifset
1283
1284 @ifclear INTERNALS
1285 @menu
1286 * Simple Constraints:: Basic use of constraints.
1287 * Multi-Alternative:: When an insn has two alternative constraint-patterns.
1288 * Modifiers:: More precise control over effects of constraints.
1289 * Machine Constraints:: Special constraints for some particular machines.
1290 @end menu
1291 @end ifclear
1292
1293 @node Simple Constraints
1294 @subsection Simple Constraints
1295 @cindex simple constraints
1296
1297 The simplest kind of constraint is a string full of letters, each of
1298 which describes one kind of operand that is permitted. Here are
1299 the letters that are allowed:
1300
1301 @table @asis
1302 @item whitespace
1303 Whitespace characters are ignored and can be inserted at any position
1304 except the first. This enables each alternative for different operands to
1305 be visually aligned in the machine description even if they have different
1306 number of constraints and modifiers.
1307
1308 @cindex @samp{m} in constraint
1309 @cindex memory references in constraints
1310 @item @samp{m}
1311 A memory operand is allowed, with any kind of address that the machine
1312 supports in general.
1313 Note that the letter used for the general memory constraint can be
1314 re-defined by a back end using the @code{TARGET_MEM_CONSTRAINT} macro.
1315
1316 @cindex offsettable address
1317 @cindex @samp{o} in constraint
1318 @item @samp{o}
1319 A memory operand is allowed, but only if the address is
1320 @dfn{offsettable}. This means that adding a small integer (actually,
1321 the width in bytes of the operand, as determined by its machine mode)
1322 may be added to the address and the result is also a valid memory
1323 address.
1324
1325 @cindex autoincrement/decrement addressing
1326 For example, an address which is constant is offsettable; so is an
1327 address that is the sum of a register and a constant (as long as a
1328 slightly larger constant is also within the range of address-offsets
1329 supported by the machine); but an autoincrement or autodecrement
1330 address is not offsettable. More complicated indirect/indexed
1331 addresses may or may not be offsettable depending on the other
1332 addressing modes that the machine supports.
1333
1334 Note that in an output operand which can be matched by another
1335 operand, the constraint letter @samp{o} is valid only when accompanied
1336 by both @samp{<} (if the target machine has predecrement addressing)
1337 and @samp{>} (if the target machine has preincrement addressing).
1338
1339 @cindex @samp{V} in constraint
1340 @item @samp{V}
1341 A memory operand that is not offsettable. In other words, anything that
1342 would fit the @samp{m} constraint but not the @samp{o} constraint.
1343
1344 @cindex @samp{<} in constraint
1345 @item @samp{<}
1346 A memory operand with autodecrement addressing (either predecrement or
1347 postdecrement) is allowed. In inline @code{asm} this constraint is only
1348 allowed if the operand is used exactly once in an instruction that can
1349 handle the side effects. Not using an operand with @samp{<} in constraint
1350 string in the inline @code{asm} pattern at all or using it in multiple
1351 instructions isn't valid, because the side effects wouldn't be performed
1352 or would be performed more than once. Furthermore, on some targets
1353 the operand with @samp{<} in constraint string must be accompanied by
1354 special instruction suffixes like @code{%U0} instruction suffix on PowerPC
1355 or @code{%P0} on IA-64.
1356
1357 @cindex @samp{>} in constraint
1358 @item @samp{>}
1359 A memory operand with autoincrement addressing (either preincrement or
1360 postincrement) is allowed. In inline @code{asm} the same restrictions
1361 as for @samp{<} apply.
1362
1363 @cindex @samp{r} in constraint
1364 @cindex registers in constraints
1365 @item @samp{r}
1366 A register operand is allowed provided that it is in a general
1367 register.
1368
1369 @cindex constants in constraints
1370 @cindex @samp{i} in constraint
1371 @item @samp{i}
1372 An immediate integer operand (one with constant value) is allowed.
1373 This includes symbolic constants whose values will be known only at
1374 assembly time or later.
1375
1376 @cindex @samp{n} in constraint
1377 @item @samp{n}
1378 An immediate integer operand with a known numeric value is allowed.
1379 Many systems cannot support assembly-time constants for operands less
1380 than a word wide. Constraints for these operands should use @samp{n}
1381 rather than @samp{i}.
1382
1383 @cindex @samp{I} in constraint
1384 @item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}
1385 Other letters in the range @samp{I} through @samp{P} may be defined in
1386 a machine-dependent fashion to permit immediate integer operands with
1387 explicit integer values in specified ranges. For example, on the
1388 68000, @samp{I} is defined to stand for the range of values 1 to 8.
1389 This is the range permitted as a shift count in the shift
1390 instructions.
1391
1392 @cindex @samp{E} in constraint
1393 @item @samp{E}
1394 An immediate floating operand (expression code @code{const_double}) is
1395 allowed, but only if the target floating point format is the same as
1396 that of the host machine (on which the compiler is running).
1397
1398 @cindex @samp{F} in constraint
1399 @item @samp{F}
1400 An immediate floating operand (expression code @code{const_double} or
1401 @code{const_vector}) is allowed.
1402
1403 @cindex @samp{G} in constraint
1404 @cindex @samp{H} in constraint
1405 @item @samp{G}, @samp{H}
1406 @samp{G} and @samp{H} may be defined in a machine-dependent fashion to
1407 permit immediate floating operands in particular ranges of values.
1408
1409 @cindex @samp{s} in constraint
1410 @item @samp{s}
1411 An immediate integer operand whose value is not an explicit integer is
1412 allowed.
1413
1414 This might appear strange; if an insn allows a constant operand with a
1415 value not known at compile time, it certainly must allow any known
1416 value. So why use @samp{s} instead of @samp{i}? Sometimes it allows
1417 better code to be generated.
1418
1419 For example, on the 68000 in a fullword instruction it is possible to
1420 use an immediate operand; but if the immediate value is between @minus{}128
1421 and 127, better code results from loading the value into a register and
1422 using the register. This is because the load into the register can be
1423 done with a @samp{moveq} instruction. We arrange for this to happen
1424 by defining the letter @samp{K} to mean ``any integer outside the
1425 range @minus{}128 to 127'', and then specifying @samp{Ks} in the operand
1426 constraints.
1427
1428 @cindex @samp{g} in constraint
1429 @item @samp{g}
1430 Any register, memory or immediate integer operand is allowed, except for
1431 registers that are not general registers.
1432
1433 @cindex @samp{X} in constraint
1434 @item @samp{X}
1435 @ifset INTERNALS
1436 Any operand whatsoever is allowed, even if it does not satisfy
1437 @code{general_operand}. This is normally used in the constraint of
1438 a @code{match_scratch} when certain alternatives will not actually
1439 require a scratch register.
1440 @end ifset
1441 @ifclear INTERNALS
1442 Any operand whatsoever is allowed.
1443 @end ifclear
1444
1445 @cindex @samp{0} in constraint
1446 @cindex digits in constraint
1447 @item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{9}
1448 An operand that matches the specified operand number is allowed. If a
1449 digit is used together with letters within the same alternative, the
1450 digit should come last.
1451
1452 This number is allowed to be more than a single digit. If multiple
1453 digits are encountered consecutively, they are interpreted as a single
1454 decimal integer. There is scant chance for ambiguity, since to-date
1455 it has never been desirable that @samp{10} be interpreted as matching
1456 either operand 1 @emph{or} operand 0. Should this be desired, one
1457 can use multiple alternatives instead.
1458
1459 @cindex matching constraint
1460 @cindex constraint, matching
1461 This is called a @dfn{matching constraint} and what it really means is
1462 that the assembler has only a single operand that fills two roles
1463 @ifset INTERNALS
1464 considered separate in the RTL insn. For example, an add insn has two
1465 input operands and one output operand in the RTL, but on most CISC
1466 @end ifset
1467 @ifclear INTERNALS
1468 which @code{asm} distinguishes. For example, an add instruction uses
1469 two input operands and an output operand, but on most CISC
1470 @end ifclear
1471 machines an add instruction really has only two operands, one of them an
1472 input-output operand:
1473
1474 @smallexample
1475 addl #35,r12
1476 @end smallexample
1477
1478 Matching constraints are used in these circumstances.
1479 More precisely, the two operands that match must include one input-only
1480 operand and one output-only operand. Moreover, the digit must be a
1481 smaller number than the number of the operand that uses it in the
1482 constraint.
1483
1484 @ifset INTERNALS
1485 For operands to match in a particular case usually means that they
1486 are identical-looking RTL expressions. But in a few special cases
1487 specific kinds of dissimilarity are allowed. For example, @code{*x}
1488 as an input operand will match @code{*x++} as an output operand.
1489 For proper results in such cases, the output template should always
1490 use the output-operand's number when printing the operand.
1491 @end ifset
1492
1493 @cindex load address instruction
1494 @cindex push address instruction
1495 @cindex address constraints
1496 @cindex @samp{p} in constraint
1497 @item @samp{p}
1498 An operand that is a valid memory address is allowed. This is
1499 for ``load address'' and ``push address'' instructions.
1500
1501 @findex address_operand
1502 @samp{p} in the constraint must be accompanied by @code{address_operand}
1503 as the predicate in the @code{match_operand}. This predicate interprets
1504 the mode specified in the @code{match_operand} as the mode of the memory
1505 reference for which the address would be valid.
1506
1507 @cindex @samp{:} in constraint
1508 @item @samp{:}
1509 This constraint, allowed only in input operands, says the inline @code{asm}
1510 pattern defines specific function or variable symbol. The constraint
1511 shouldn't be mixed with other constraints on the same operand and
1512 the operand should be address of a function or non-automatic variable.
1513 Best used with the @samp{cc} modifier when printing the operand, so that
1514 even in position independent code it prints as a label.
1515
1516 @smallexample
1517 void foo (void);
1518 asm (".globl %cc0; %cc0: ret" : : ":" (foo));
1519 @end smallexample
1520
1521 @cindex other register constraints
1522 @cindex extensible constraints
1523 @item @var{other-letters}
1524 Other letters can be defined in machine-dependent fashion to stand for
1525 particular classes of registers or other arbitrary operand types.
1526 @samp{d}, @samp{a} and @samp{f} are defined on the 68000/68020 to stand
1527 for data, address and floating point registers.
1528 @end table
1529
1530 @ifset INTERNALS
1531 In order to have valid assembler code, each operand must satisfy
1532 its constraint. But a failure to do so does not prevent the pattern
1533 from applying to an insn. Instead, it directs the compiler to modify
1534 the code so that the constraint will be satisfied. Usually this is
1535 done by copying an operand into a register.
1536
1537 Contrast, therefore, the two instruction patterns that follow:
1538
1539 @smallexample
1540 (define_insn ""
1541 [(set (match_operand:SI 0 "general_operand" "=r")
1542 (plus:SI (match_dup 0)
1543 (match_operand:SI 1 "general_operand" "r")))]
1544 ""
1545 "@dots{}")
1546 @end smallexample
1547
1548 @noindent
1549 which has two operands, one of which must appear in two places, and
1550
1551 @smallexample
1552 (define_insn ""
1553 [(set (match_operand:SI 0 "general_operand" "=r")
1554 (plus:SI (match_operand:SI 1 "general_operand" "0")
1555 (match_operand:SI 2 "general_operand" "r")))]
1556 ""
1557 "@dots{}")
1558 @end smallexample
1559
1560 @noindent
1561 which has three operands, two of which are required by a constraint to be
1562 identical. If we are considering an insn of the form
1563
1564 @smallexample
1565 (insn @var{n} @var{prev} @var{next}
1566 (set (reg:SI 3)
1567 (plus:SI (reg:SI 6) (reg:SI 109)))
1568 @dots{})
1569 @end smallexample
1570
1571 @noindent
1572 the first pattern would not apply at all, because this insn does not
1573 contain two identical subexpressions in the right place. The pattern would
1574 say, ``That does not look like an add instruction; try other patterns''.
1575 The second pattern would say, ``Yes, that's an add instruction, but there
1576 is something wrong with it''. It would direct the reload pass of the
1577 compiler to generate additional insns to make the constraint true. The
1578 results might look like this:
1579
1580 @smallexample
1581 (insn @var{n2} @var{prev} @var{n}
1582 (set (reg:SI 3) (reg:SI 6))
1583 @dots{})
1584
1585 (insn @var{n} @var{n2} @var{next}
1586 (set (reg:SI 3)
1587 (plus:SI (reg:SI 3) (reg:SI 109)))
1588 @dots{})
1589 @end smallexample
1590
1591 It is up to you to make sure that each operand, in each pattern, has
1592 constraints that can handle any RTL expression that could be present for
1593 that operand. (When multiple alternatives are in use, each pattern must,
1594 for each possible combination of operand expressions, have at least one
1595 alternative which can handle that combination of operands.) The
1596 constraints don't need to @emph{allow} any possible operand---when this is
1597 the case, they do not constrain---but they must at least point the way to
1598 reloading any possible operand so that it will fit.
1599
1600 @itemize @bullet
1601 @item
1602 If the constraint accepts whatever operands the predicate permits,
1603 there is no problem: reloading is never necessary for this operand.
1604
1605 For example, an operand whose constraints permit everything except
1606 registers is safe provided its predicate rejects registers.
1607
1608 An operand whose predicate accepts only constant values is safe
1609 provided its constraints include the letter @samp{i}. If any possible
1610 constant value is accepted, then nothing less than @samp{i} will do;
1611 if the predicate is more selective, then the constraints may also be
1612 more selective.
1613
1614 @item
1615 Any operand expression can be reloaded by copying it into a register.
1616 So if an operand's constraints allow some kind of register, it is
1617 certain to be safe. It need not permit all classes of registers; the
1618 compiler knows how to copy a register into another register of the
1619 proper class in order to make an instruction valid.
1620
1621 @cindex nonoffsettable memory reference
1622 @cindex memory reference, nonoffsettable
1623 @item
1624 A nonoffsettable memory reference can be reloaded by copying the
1625 address into a register. So if the constraint uses the letter
1626 @samp{o}, all memory references are taken care of.
1627
1628 @item
1629 A constant operand can be reloaded by allocating space in memory to
1630 hold it as preinitialized data. Then the memory reference can be used
1631 in place of the constant. So if the constraint uses the letters
1632 @samp{o} or @samp{m}, constant operands are not a problem.
1633
1634 @item
1635 If the constraint permits a constant and a pseudo register used in an insn
1636 was not allocated to a hard register and is equivalent to a constant,
1637 the register will be replaced with the constant. If the predicate does
1638 not permit a constant and the insn is re-recognized for some reason, the
1639 compiler will crash. Thus the predicate must always recognize any
1640 objects allowed by the constraint.
1641 @end itemize
1642
1643 If the operand's predicate can recognize registers, but the constraint does
1644 not permit them, it can make the compiler crash. When this operand happens
1645 to be a register, the reload pass will be stymied, because it does not know
1646 how to copy a register temporarily into memory.
1647
1648 If the predicate accepts a unary operator, the constraint applies to the
1649 operand. For example, the MIPS processor at ISA level 3 supports an
1650 instruction which adds two registers in @code{SImode} to produce a
1651 @code{DImode} result, but only if the registers are correctly sign
1652 extended. This predicate for the input operands accepts a
1653 @code{sign_extend} of an @code{SImode} register. Write the constraint
1654 to indicate the type of register that is required for the operand of the
1655 @code{sign_extend}.
1656 @end ifset
1657
1658 @node Multi-Alternative
1659 @subsection Multiple Alternative Constraints
1660 @cindex multiple alternative constraints
1661
1662 Sometimes a single instruction has multiple alternative sets of possible
1663 operands. For example, on the 68000, a logical-or instruction can combine
1664 register or an immediate value into memory, or it can combine any kind of
1665 operand into a register; but it cannot combine one memory location into
1666 another.
1667
1668 These constraints are represented as multiple alternatives. An alternative
1669 can be described by a series of letters for each operand. The overall
1670 constraint for an operand is made from the letters for this operand
1671 from the first alternative, a comma, the letters for this operand from
1672 the second alternative, a comma, and so on until the last alternative.
1673 All operands for a single instruction must have the same number of
1674 alternatives.
1675 @ifset INTERNALS
1676 Here is how it is done for fullword logical-or on the 68000:
1677
1678 @smallexample
1679 (define_insn "iorsi3"
1680 [(set (match_operand:SI 0 "general_operand" "=m,d")
1681 (ior:SI (match_operand:SI 1 "general_operand" "%0,0")
1682 (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
1683 @dots{})
1684 @end smallexample
1685
1686 The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
1687 operand 1 (meaning it must match operand 0), and @samp{dKs} for operand
1688 2. The second alternative has @samp{d} (data register) for operand 0,
1689 @samp{0} for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and
1690 @samp{%} in the constraints apply to all the alternatives; their
1691 meaning is explained in a later section (@pxref{Modifiers}).
1692
1693 If all the operands fit any one alternative, the instruction is valid.
1694 Otherwise, for each alternative, the compiler counts how many instructions
1695 must be added to copy the operands so that that alternative applies.
1696 The alternative requiring the least copying is chosen. If two alternatives
1697 need the same amount of copying, the one that comes first is chosen.
1698 These choices can be altered with the @samp{?} and @samp{!} characters:
1699
1700 @table @code
1701 @cindex @samp{?} in constraint
1702 @cindex question mark
1703 @item ?
1704 Disparage slightly the alternative that the @samp{?} appears in,
1705 as a choice when no alternative applies exactly. The compiler regards
1706 this alternative as one unit more costly for each @samp{?} that appears
1707 in it.
1708
1709 @cindex @samp{!} in constraint
1710 @cindex exclamation point
1711 @item !
1712 Disparage severely the alternative that the @samp{!} appears in.
1713 This alternative can still be used if it fits without reloading,
1714 but if reloading is needed, some other alternative will be used.
1715
1716 @cindex @samp{^} in constraint
1717 @cindex caret
1718 @item ^
1719 This constraint is analogous to @samp{?} but it disparages slightly
1720 the alternative only if the operand with the @samp{^} needs a reload.
1721
1722 @cindex @samp{$} in constraint
1723 @cindex dollar sign
1724 @item $
1725 This constraint is analogous to @samp{!} but it disparages severely
1726 the alternative only if the operand with the @samp{$} needs a reload.
1727 @end table
1728
1729 When an insn pattern has multiple alternatives in its constraints, often
1730 the appearance of the assembler code is determined mostly by which
1731 alternative was matched. When this is so, the C code for writing the
1732 assembler code can use the variable @code{which_alternative}, which is
1733 the ordinal number of the alternative that was actually satisfied (0 for
1734 the first, 1 for the second alternative, etc.). @xref{Output Statement}.
1735 @end ifset
1736 @ifclear INTERNALS
1737
1738 So the first alternative for the 68000's logical-or could be written as
1739 @code{"+m" (output) : "ir" (input)}. The second could be @code{"+r"
1740 (output): "irm" (input)}. However, the fact that two memory locations
1741 cannot be used in a single instruction prevents simply using @code{"+rm"
1742 (output) : "irm" (input)}. Using multi-alternatives, this might be
1743 written as @code{"+m,r" (output) : "ir,irm" (input)}. This describes
1744 all the available alternatives to the compiler, allowing it to choose
1745 the most efficient one for the current conditions.
1746
1747 There is no way within the template to determine which alternative was
1748 chosen. However you may be able to wrap your @code{asm} statements with
1749 builtins such as @code{__builtin_constant_p} to achieve the desired results.
1750 @end ifclear
1751
1752 @ifset INTERNALS
1753 @node Class Preferences
1754 @subsection Register Class Preferences
1755 @cindex class preference constraints
1756 @cindex register class preference constraints
1757
1758 @cindex voting between constraint alternatives
1759 The operand constraints have another function: they enable the compiler
1760 to decide which kind of hardware register a pseudo register is best
1761 allocated to. The compiler examines the constraints that apply to the
1762 insns that use the pseudo register, looking for the machine-dependent
1763 letters such as @samp{d} and @samp{a} that specify classes of registers.
1764 The pseudo register is put in whichever class gets the most ``votes''.
1765 The constraint letters @samp{g} and @samp{r} also vote: they vote in
1766 favor of a general register. The machine description says which registers
1767 are considered general.
1768
1769 Of course, on some machines all registers are equivalent, and no register
1770 classes are defined. Then none of this complexity is relevant.
1771 @end ifset
1772
1773 @node Modifiers
1774 @subsection Constraint Modifier Characters
1775 @cindex modifiers in constraints
1776 @cindex constraint modifier characters
1777
1778 @c prevent bad page break with this line
1779 Here are constraint modifier characters.
1780
1781 @table @samp
1782 @cindex @samp{=} in constraint
1783 @item =
1784 Means that this operand is written to by this instruction:
1785 the previous value is discarded and replaced by new data.
1786
1787 @cindex @samp{+} in constraint
1788 @item +
1789 Means that this operand is both read and written by the instruction.
1790
1791 When the compiler fixes up the operands to satisfy the constraints,
1792 it needs to know which operands are read by the instruction and
1793 which are written by it. @samp{=} identifies an operand which is only
1794 written; @samp{+} identifies an operand that is both read and written; all
1795 other operands are assumed to only be read.
1796
1797 If you specify @samp{=} or @samp{+} in a constraint, you put it in the
1798 first character of the constraint string.
1799
1800 @cindex @samp{&} in constraint
1801 @cindex earlyclobber operand
1802 @item &
1803 Means (in a particular alternative) that this operand is an
1804 @dfn{earlyclobber} operand, which is written before the instruction is
1805 finished using the input operands. Therefore, this operand may not lie
1806 in a register that is read by the instruction or as part of any memory
1807 address.
1808
1809 @samp{&} applies only to the alternative in which it is written. In
1810 constraints with multiple alternatives, sometimes one alternative
1811 requires @samp{&} while others do not. See, for example, the
1812 @samp{movdf} insn of the 68000.
1813
1814 An operand which is read by the instruction can be tied to an earlyclobber
1815 operand if its only use as an input occurs before the early result is
1816 written. Adding alternatives of this form often allows GCC to produce
1817 better code when only some of the read operands can be affected by the
1818 earlyclobber. See, for example, the @samp{mulsi3} insn of the ARM@.
1819
1820 Furthermore, if the @dfn{earlyclobber} operand is also a read/write
1821 operand, then that operand is written only after it's used.
1822
1823 @samp{&} does not obviate the need to write @samp{=} or @samp{+}. As
1824 @dfn{earlyclobber} operands are always written, a read-only
1825 @dfn{earlyclobber} operand is ill-formed and will be rejected by the
1826 compiler.
1827
1828 @cindex @samp{%} in constraint
1829 @item %
1830 Declares the instruction to be commutative for this operand and the
1831 following operand. This means that the compiler may interchange the
1832 two operands if that is the cheapest way to make all operands fit the
1833 constraints. @samp{%} applies to all alternatives and must appear as
1834 the first character in the constraint. Only read-only operands can use
1835 @samp{%}.
1836
1837 @ifset INTERNALS
1838 This is often used in patterns for addition instructions
1839 that really have only two operands: the result must go in one of the
1840 arguments. Here for example, is how the 68000 halfword-add
1841 instruction is defined:
1842
1843 @smallexample
1844 (define_insn "addhi3"
1845 [(set (match_operand:HI 0 "general_operand" "=m,r")
1846 (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
1847 (match_operand:HI 2 "general_operand" "di,g")))]
1848 @dots{})
1849 @end smallexample
1850 @end ifset
1851 GCC can only handle one commutative pair in an asm; if you use more,
1852 the compiler may fail. Note that you need not use the modifier if
1853 the two alternatives are strictly identical; this would only waste
1854 time in the reload pass.
1855 @ifset INTERNALS
1856 The modifier is not operational after
1857 register allocation, so the result of @code{define_peephole2}
1858 and @code{define_split}s performed after reload cannot rely on
1859 @samp{%} to make the intended insn match.
1860
1861 @cindex @samp{#} in constraint
1862 @item #
1863 Says that all following characters, up to the next comma, are to be
1864 ignored as a constraint. They are significant only for choosing
1865 register preferences.
1866
1867 @cindex @samp{*} in constraint
1868 @item *
1869 Says that the following character should be ignored when choosing
1870 register preferences. @samp{*} has no effect on the meaning of the
1871 constraint as a constraint, and no effect on reloading. For LRA
1872 @samp{*} additionally disparages slightly the alternative if the
1873 following character matches the operand.
1874
1875 Here is an example: the 68000 has an instruction to sign-extend a
1876 halfword in a data register, and can also sign-extend a value by
1877 copying it into an address register. While either kind of register is
1878 acceptable, the constraints on an address-register destination are
1879 less strict, so it is best if register allocation makes an address
1880 register its goal. Therefore, @samp{*} is used so that the @samp{d}
1881 constraint letter (for data register) is ignored when computing
1882 register preferences.
1883
1884 @smallexample
1885 (define_insn "extendhisi2"
1886 [(set (match_operand:SI 0 "general_operand" "=*d,a")
1887 (sign_extend:SI
1888 (match_operand:HI 1 "general_operand" "0,g")))]
1889 @dots{})
1890 @end smallexample
1891 @end ifset
1892
1893 @cindex @samp{-} in constraint
1894 @item -
1895 Says that the selected following constraints within the same alternative
1896 should be matched differently. Normally in PIC code symbolic operands
1897 in constraints like @samp{i}, @samp{s} or @samp{n} are not allowed at all
1898 or severely restricted. The @samp{-} modifier, which is only allowed
1899 outside of functions, allows symbolic operands even in PIC code. This
1900 modifier is usually used together with the @code{cc} operand modifier.
1901
1902 @smallexample
1903 extern void foo (void), bar (void);
1904 int v;
1905 extern int w;
1906 asm (".globl %cc0, %cc2; .text; %cc0: call %cc1; ret; .data; %cc2: .word %cc3"
1907 :: ":" (foo), "-s" (&bar), ":" (&w), "-i" (&v));
1908 @end smallexample
1909
1910 This asm declaration tells the compiler it defines function @code{foo} and
1911 variable @code{w} and uses function @code{bar} and variable @code{v}. This
1912 will compile even with PIC, but it is up to the user to ensure it will
1913 assemble correctly and have the expected behavior.
1914 @end table
1915
1916 @node Machine Constraints
1917 @subsection Constraints for Particular Machines
1918 @cindex machine specific constraints
1919 @cindex constraints, machine specific
1920
1921 Whenever possible, you should use the general-purpose constraint letters
1922 in @code{asm} arguments, since they will convey meaning more readily to
1923 people reading your code. Failing that, use the constraint letters
1924 that usually have very similar meanings across architectures. The most
1925 commonly used constraints are @samp{m} and @samp{r} (for memory and
1926 general-purpose registers respectively; @pxref{Simple Constraints}), and
1927 @samp{I}, usually the letter indicating the most common
1928 immediate-constant format.
1929
1930 Each architecture defines additional constraints. These constraints
1931 are used by the compiler itself for instruction generation, as well as
1932 for @code{asm} statements; therefore, some of the constraints are not
1933 particularly useful for @code{asm}. Here is a summary of some of the
1934 machine-dependent constraints available on some particular machines;
1935 it includes both constraints that are useful for @code{asm} and
1936 constraints that aren't. The compiler source file mentioned in the
1937 table heading for each architecture is the definitive reference for
1938 the meanings of that architecture's constraints.
1939
1940 @c Please keep this table alphabetized by target!
1941 @table @emph
1942 @item AArch64 family---@file{config/aarch64/constraints.md}
1943 @table @code
1944 @item k
1945 The stack pointer register (@code{SP})
1946
1947 @item w
1948 Floating point register, Advanced SIMD vector register or SVE vector register
1949
1950 @item x
1951 Like @code{w}, but restricted to registers 0 to 15 inclusive.
1952
1953 @item y
1954 Like @code{w}, but restricted to registers 0 to 7 inclusive.
1955
1956 @item Upl
1957 One of the low eight SVE predicate registers (@code{P0} to @code{P7})
1958
1959 @item Upa
1960 Any of the SVE predicate registers (@code{P0} to @code{P15})
1961
1962 @item I
1963 Integer constant that is valid as an immediate operand in an @code{ADD}
1964 instruction
1965
1966 @item J
1967 Integer constant that is valid as an immediate operand in a @code{SUB}
1968 instruction (once negated)
1969
1970 @item K
1971 Integer constant that can be used with a 32-bit logical instruction
1972
1973 @item L
1974 Integer constant that can be used with a 64-bit logical instruction
1975
1976 @item M
1977 Integer constant that is valid as an immediate operand in a 32-bit @code{MOV}
1978 pseudo instruction. The @code{MOV} may be assembled to one of several different
1979 machine instructions depending on the value
1980
1981 @item N
1982 Integer constant that is valid as an immediate operand in a 64-bit @code{MOV}
1983 pseudo instruction
1984
1985 @item S
1986 An absolute symbolic address or a label reference
1987
1988 @item Y
1989 Floating point constant zero
1990
1991 @item Z
1992 Integer constant zero
1993
1994 @item Ush
1995 The high part (bits 12 and upwards) of the pc-relative address of a symbol
1996 within 4GB of the instruction
1997
1998 @item Q
1999 A memory address which uses a single base register with no offset
2000
2001 @item Ump
2002 A memory address suitable for a load/store pair instruction in SI, DI, SF and
2003 DF modes
2004
2005 @end table
2006
2007
2008 @item AMD GCN ---@file{config/gcn/constraints.md}
2009 @table @code
2010 @item I
2011 Immediate integer in the range @minus{}16 to 64
2012
2013 @item J
2014 Immediate 16-bit signed integer
2015
2016 @item Kf
2017 Immediate constant @minus{}1
2018
2019 @item L
2020 Immediate 15-bit unsigned integer
2021
2022 @item A
2023 Immediate constant that can be inlined in an instruction encoding: integer
2024 @minus{}16..64, or float 0.0, +/@minus{}0.5, +/@minus{}1.0, +/@minus{}2.0,
2025 +/@minus{}4.0, 1.0/(2.0*PI)
2026
2027 @item B
2028 Immediate 32-bit signed integer that can be attached to an instruction encoding
2029
2030 @item C
2031 Immediate 32-bit integer in range @minus{}16..4294967295 (i.e. 32-bit unsigned
2032 integer or @samp{A} constraint)
2033
2034 @item DA
2035 Immediate 64-bit constant that can be split into two @samp{A} constants
2036
2037 @item DB
2038 Immediate 64-bit constant that can be split into two @samp{B} constants
2039
2040 @item U
2041 Any @code{unspec}
2042
2043 @item Y
2044 Any @code{symbol_ref} or @code{label_ref}
2045
2046 @item v
2047 VGPR register
2048
2049 @item a
2050 Accelerator VGPR register (CDNA1 onwards)
2051
2052 @item Sg
2053 SGPR register
2054
2055 @item SD
2056 SGPR registers valid for instruction destinations, including VCC, M0 and EXEC
2057
2058 @item SS
2059 SGPR registers valid for instruction sources, including VCC, M0, EXEC and SCC
2060
2061 @item Sm
2062 SGPR registers valid as a source for scalar memory instructions (excludes M0
2063 and EXEC)
2064
2065 @item Sv
2066 SGPR registers valid as a source or destination for vector instructions
2067 (excludes EXEC)
2068
2069 @item ca
2070 All condition registers: SCC, VCCZ, EXECZ
2071
2072 @item cs
2073 Scalar condition register: SCC
2074
2075 @item cV
2076 Vector condition register: VCC, VCC_LO, VCC_HI
2077
2078 @item e
2079 EXEC register (EXEC_LO and EXEC_HI)
2080
2081 @item RB
2082 Memory operand with address space suitable for @code{buffer_*} instructions
2083
2084 @item RF
2085 Memory operand with address space suitable for @code{flat_*} instructions
2086
2087 @item RS
2088 Memory operand with address space suitable for @code{s_*} instructions
2089
2090 @item RL
2091 Memory operand with address space suitable for @code{ds_*} LDS instructions
2092
2093 @item RG
2094 Memory operand with address space suitable for @code{ds_*} GDS instructions
2095
2096 @item RD
2097 Memory operand with address space suitable for any @code{ds_*} instructions
2098
2099 @item RM
2100 Memory operand with address space suitable for @code{global_*} instructions
2101
2102 @end table
2103
2104
2105 @item ARC ---@file{config/arc/constraints.md}
2106 @table @code
2107 @item q
2108 Registers usable in ARCompact 16-bit instructions: @code{r0}-@code{r3},
2109 @code{r12}-@code{r15}. This constraint can only match when the @option{-mq}
2110 option is in effect.
2111
2112 @item e
2113 Registers usable as base-regs of memory addresses in ARCompact 16-bit memory
2114 instructions: @code{r0}-@code{r3}, @code{r12}-@code{r15}, @code{sp}.
2115 This constraint can only match when the @option{-mq}
2116 option is in effect.
2117 @item D
2118 ARC FPX (dpfp) 64-bit registers. @code{D0}, @code{D1}.
2119
2120 @item I
2121 A signed 12-bit integer constant.
2122
2123 @item Cal
2124 constant for arithmetic/logical operations. This might be any constant
2125 that can be put into a long immediate by the assmbler or linker without
2126 involving a PIC relocation.
2127
2128 @item K
2129 A 3-bit unsigned integer constant.
2130
2131 @item L
2132 A 6-bit unsigned integer constant.
2133
2134 @item CnL
2135 One's complement of a 6-bit unsigned integer constant.
2136
2137 @item CmL
2138 Two's complement of a 6-bit unsigned integer constant.
2139
2140 @item M
2141 A 5-bit unsigned integer constant.
2142
2143 @item O
2144 A 7-bit unsigned integer constant.
2145
2146 @item P
2147 A 8-bit unsigned integer constant.
2148
2149 @item H
2150 Any const_double value.
2151 @end table
2152
2153 @item ARM family---@file{config/arm/constraints.md}
2154 @table @code
2155
2156 @item h
2157 In Thumb state, the core registers @code{r8}-@code{r15}.
2158
2159 @item k
2160 The stack pointer register.
2161
2162 @item l
2163 In Thumb State the core registers @code{r0}-@code{r7}. In ARM state this
2164 is an alias for the @code{r} constraint.
2165
2166 @item t
2167 VFP floating-point registers @code{s0}-@code{s31}. Used for 32 bit values.
2168
2169 @item w
2170 VFP floating-point registers @code{d0}-@code{d31} and the appropriate
2171 subset @code{d0}-@code{d15} based on command line options.
2172 Used for 64 bit values only. Not valid for Thumb1.
2173
2174 @item y
2175 The iWMMX co-processor registers.
2176
2177 @item z
2178 The iWMMX GR registers.
2179
2180 @item G
2181 The floating-point constant 0.0
2182
2183 @item I
2184 Integer that is valid as an immediate operand in a data processing
2185 instruction. That is, an integer in the range 0 to 255 rotated by a
2186 multiple of 2
2187
2188 @item J
2189 Integer in the range @minus{}4095 to 4095
2190
2191 @item K
2192 Integer that satisfies constraint @samp{I} when inverted (ones complement)
2193
2194 @item L
2195 Integer that satisfies constraint @samp{I} when negated (twos complement)
2196
2197 @item M
2198 Integer in the range 0 to 32
2199
2200 @item Q
2201 A memory reference where the exact address is in a single register
2202 (`@samp{m}' is preferable for @code{asm} statements)
2203
2204 @item R
2205 An item in the constant pool
2206
2207 @item S
2208 A symbol in the text segment of the current file
2209
2210 @item Uv
2211 A memory reference suitable for VFP load/store insns (reg+constant offset)
2212
2213 @item Uy
2214 A memory reference suitable for iWMMXt load/store instructions.
2215
2216 @item Uq
2217 A memory reference suitable for the ARMv4 ldrsb instruction.
2218 @end table
2219
2220 @item AVR family---@file{config/avr/constraints.md}
2221 @table @code
2222 @item l
2223 Registers from r0 to r15
2224
2225 @item a
2226 Registers from r16 to r23
2227
2228 @item d
2229 Registers from r16 to r31
2230
2231 @item w
2232 Registers from r24 to r31. These registers can be used in @samp{adiw} command
2233
2234 @item e
2235 Pointer register (r26--r31)
2236
2237 @item b
2238 Base pointer register (r28--r31)
2239
2240 @item q
2241 Stack pointer register (SPH:SPL)
2242
2243 @item t
2244 Temporary register r0
2245
2246 @item x
2247 Register pair X (r27:r26)
2248
2249 @item y
2250 Register pair Y (r29:r28)
2251
2252 @item z
2253 Register pair Z (r31:r30)
2254
2255 @item I
2256 Constant greater than @minus{}1, less than 64
2257
2258 @item J
2259 Constant greater than @minus{}64, less than 1
2260
2261 @item K
2262 Constant integer 2
2263
2264 @item L
2265 Constant integer 0
2266
2267 @item M
2268 Constant that fits in 8 bits
2269
2270 @item N
2271 Constant integer @minus{}1
2272
2273 @item O
2274 Constant integer 8, 16, or 24
2275
2276 @item P
2277 Constant integer 1
2278
2279 @item G
2280 A floating point constant 0.0
2281
2282 @item Q
2283 A memory address based on Y or Z pointer with displacement.
2284 @end table
2285
2286 @item Blackfin family---@file{config/bfin/constraints.md}
2287 @table @code
2288 @item a
2289 P register
2290
2291 @item d
2292 D register
2293
2294 @item z
2295 A call clobbered P register.
2296
2297 @item q@var{n}
2298 A single register. If @var{n} is in the range 0 to 7, the corresponding D
2299 register. If it is @code{A}, then the register P0.
2300
2301 @item D
2302 Even-numbered D register
2303
2304 @item W
2305 Odd-numbered D register
2306
2307 @item e
2308 Accumulator register.
2309
2310 @item A
2311 Even-numbered accumulator register.
2312
2313 @item B
2314 Odd-numbered accumulator register.
2315
2316 @item b
2317 I register
2318
2319 @item v
2320 B register
2321
2322 @item f
2323 M register
2324
2325 @item c
2326 Registers used for circular buffering, i.e.@: I, B, or L registers.
2327
2328 @item C
2329 The CC register.
2330
2331 @item t
2332 LT0 or LT1.
2333
2334 @item k
2335 LC0 or LC1.
2336
2337 @item u
2338 LB0 or LB1.
2339
2340 @item x
2341 Any D, P, B, M, I or L register.
2342
2343 @item y
2344 Additional registers typically used only in prologues and epilogues: RETS,
2345 RETN, RETI, RETX, RETE, ASTAT, SEQSTAT and USP.
2346
2347 @item w
2348 Any register except accumulators or CC.
2349
2350 @item Ksh
2351 Signed 16 bit integer (in the range @minus{}32768 to 32767)
2352
2353 @item Kuh
2354 Unsigned 16 bit integer (in the range 0 to 65535)
2355
2356 @item Ks7
2357 Signed 7 bit integer (in the range @minus{}64 to 63)
2358
2359 @item Ku7
2360 Unsigned 7 bit integer (in the range 0 to 127)
2361
2362 @item Ku5
2363 Unsigned 5 bit integer (in the range 0 to 31)
2364
2365 @item Ks4
2366 Signed 4 bit integer (in the range @minus{}8 to 7)
2367
2368 @item Ks3
2369 Signed 3 bit integer (in the range @minus{}3 to 4)
2370
2371 @item Ku3
2372 Unsigned 3 bit integer (in the range 0 to 7)
2373
2374 @item P@var{n}
2375 Constant @var{n}, where @var{n} is a single-digit constant in the range 0 to 4.
2376
2377 @item PA
2378 An integer equal to one of the MACFLAG_XXX constants that is suitable for
2379 use with either accumulator.
2380
2381 @item PB
2382 An integer equal to one of the MACFLAG_XXX constants that is suitable for
2383 use only with accumulator A1.
2384
2385 @item M1
2386 Constant 255.
2387
2388 @item M2
2389 Constant 65535.
2390
2391 @item J
2392 An integer constant with exactly a single bit set.
2393
2394 @item L
2395 An integer constant with all bits set except exactly one.
2396
2397 @item H
2398 @itemx Q
2399 Any SYMBOL_REF.
2400 @end table
2401
2402 @item C-SKY---@file{config/csky/constraints.md}
2403 @table @code
2404
2405 @item a
2406 The mini registers r0 - r7.
2407
2408 @item b
2409 The low registers r0 - r15.
2410
2411 @item c
2412 C register.
2413
2414 @item y
2415 HI and LO registers.
2416
2417 @item l
2418 LO register.
2419
2420 @item h
2421 HI register.
2422
2423 @item v
2424 Vector registers.
2425
2426 @item z
2427 Stack pointer register (SP).
2428
2429 @item Q
2430 A memory address which uses a base register with a short offset
2431 or with a index register with its scale.
2432
2433 @item W
2434 A memory address which uses a base register with a index register
2435 with its scale.
2436 @end table
2437
2438 @ifset INTERNALS
2439 The C-SKY back end supports a large set of additional constraints
2440 that are only useful for instruction selection or splitting rather
2441 than inline asm, such as constraints representing constant integer
2442 ranges accepted by particular instruction encodings.
2443 Refer to the source code for details.
2444 @end ifset
2445
2446 @item Epiphany---@file{config/epiphany/constraints.md}
2447 @table @code
2448 @item U16
2449 An unsigned 16-bit constant.
2450
2451 @item K
2452 An unsigned 5-bit constant.
2453
2454 @item L
2455 A signed 11-bit constant.
2456
2457 @item Cm1
2458 A signed 11-bit constant added to @minus{}1.
2459 Can only match when the @option{-m1reg-@var{reg}} option is active.
2460
2461 @item Cl1
2462 Left-shift of @minus{}1, i.e., a bit mask with a block of leading ones, the rest
2463 being a block of trailing zeroes.
2464 Can only match when the @option{-m1reg-@var{reg}} option is active.
2465
2466 @item Cr1
2467 Right-shift of @minus{}1, i.e., a bit mask with a trailing block of ones, the
2468 rest being zeroes. Or to put it another way, one less than a power of two.
2469 Can only match when the @option{-m1reg-@var{reg}} option is active.
2470
2471 @item Cal
2472 Constant for arithmetic/logical operations.
2473 This is like @code{i}, except that for position independent code,
2474 no symbols / expressions needing relocations are allowed.
2475
2476 @item Csy
2477 Symbolic constant for call/jump instruction.
2478
2479 @item Rcs
2480 The register class usable in short insns. This is a register class
2481 constraint, and can thus drive register allocation.
2482 This constraint won't match unless @option{-mprefer-short-insn-regs} is
2483 in effect.
2484
2485 @item Rsc
2486 The register class of registers that can be used to hold a
2487 sibcall call address. I.e., a caller-saved register.
2488
2489 @item Rct
2490 Core control register class.
2491
2492 @item Rgs
2493 The register group usable in short insns.
2494 This constraint does not use a register class, so that it only
2495 passively matches suitable registers, and doesn't drive register allocation.
2496
2497 @ifset INTERNALS
2498 @item Car
2499 Constant suitable for the addsi3_r pattern. This is a valid offset
2500 For byte, halfword, or word addressing.
2501 @end ifset
2502
2503 @item Rra
2504 Matches the return address if it can be replaced with the link register.
2505
2506 @item Rcc
2507 Matches the integer condition code register.
2508
2509 @item Sra
2510 Matches the return address if it is in a stack slot.
2511
2512 @item Cfm
2513 Matches control register values to switch fp mode, which are encapsulated in
2514 @code{UNSPEC_FP_MODE}.
2515 @end table
2516
2517 @item FRV---@file{config/frv/frv.h}
2518 @table @code
2519 @item a
2520 Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}).
2521
2522 @item b
2523 Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}).
2524
2525 @item c
2526 Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and
2527 @code{icc0} to @code{icc3}).
2528
2529 @item d
2530 Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}).
2531
2532 @item e
2533 Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}).
2534 Odd registers are excluded not in the class but through the use of a machine
2535 mode larger than 4 bytes.
2536
2537 @item f
2538 Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}).
2539
2540 @item h
2541 Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}).
2542 Odd registers are excluded not in the class but through the use of a machine
2543 mode larger than 4 bytes.
2544
2545 @item l
2546 Register in the class @code{LR_REG} (the @code{lr} register).
2547
2548 @item q
2549 Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}).
2550 Register numbers not divisible by 4 are excluded not in the class but through
2551 the use of a machine mode larger than 8 bytes.
2552
2553 @item t
2554 Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}).
2555
2556 @item u
2557 Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}).
2558
2559 @item v
2560 Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}).
2561
2562 @item w
2563 Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}).
2564
2565 @item x
2566 Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}).
2567 Register numbers not divisible by 4 are excluded not in the class but through
2568 the use of a machine mode larger than 8 bytes.
2569
2570 @item z
2571 Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}).
2572
2573 @item A
2574 Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}).
2575
2576 @item B
2577 Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}).
2578
2579 @item C
2580 Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}).
2581
2582 @item G
2583 Floating point constant zero
2584
2585 @item I
2586 6-bit signed integer constant
2587
2588 @item J
2589 10-bit signed integer constant
2590
2591 @item L
2592 16-bit signed integer constant
2593
2594 @item M
2595 16-bit unsigned integer constant
2596
2597 @item N
2598 12-bit signed integer constant that is negative---i.e.@: in the
2599 range of @minus{}2048 to @minus{}1
2600
2601 @item O
2602 Constant zero
2603
2604 @item P
2605 12-bit signed integer constant that is greater than zero---i.e.@: in the
2606 range of 1 to 2047.
2607
2608 @end table
2609
2610 @item FT32---@file{config/ft32/constraints.md}
2611 @table @code
2612 @item A
2613 An absolute address
2614
2615 @item B
2616 An offset address
2617
2618 @item W
2619 A register indirect memory operand
2620
2621 @item e
2622 An offset address.
2623
2624 @item f
2625 An offset address.
2626
2627 @item O
2628 The constant zero or one
2629
2630 @item I
2631 A 16-bit signed constant (@minus{}32768 @dots{} 32767)
2632
2633 @item w
2634 A bitfield mask suitable for bext or bins
2635
2636 @item x
2637 An inverted bitfield mask suitable for bext or bins
2638
2639 @item L
2640 A 16-bit unsigned constant, multiple of 4 (0 @dots{} 65532)
2641
2642 @item S
2643 A 20-bit signed constant (@minus{}524288 @dots{} 524287)
2644
2645 @item b
2646 A constant for a bitfield width (1 @dots{} 16)
2647
2648 @item KA
2649 A 10-bit signed constant (@minus{}512 @dots{} 511)
2650
2651 @end table
2652
2653 @item Hewlett-Packard PA-RISC---@file{config/pa/pa.h}
2654 @table @code
2655 @item a
2656 General register 1
2657
2658 @item f
2659 Floating point register
2660
2661 @item q
2662 Shift amount register
2663
2664 @item x
2665 Floating point register (deprecated)
2666
2667 @item y
2668 Upper floating point register (32-bit), floating point register (64-bit)
2669
2670 @item Z
2671 Any register
2672
2673 @item I
2674 Signed 11-bit integer constant
2675
2676 @item J
2677 Signed 14-bit integer constant
2678
2679 @item K
2680 Integer constant that can be deposited with a @code{zdepi} instruction
2681
2682 @item L
2683 Signed 5-bit integer constant
2684
2685 @item M
2686 Integer constant 0
2687
2688 @item N
2689 Integer constant that can be loaded with a @code{ldil} instruction
2690
2691 @item O
2692 Integer constant whose value plus one is a power of 2
2693
2694 @item P
2695 Integer constant that can be used for @code{and} operations in @code{depi}
2696 and @code{extru} instructions
2697
2698 @item S
2699 Integer constant 31
2700
2701 @item U
2702 Integer constant 63
2703
2704 @item G
2705 Floating-point constant 0.0
2706
2707 @item A
2708 A @code{lo_sum} data-linkage-table memory operand
2709
2710 @item Q
2711 A memory operand that can be used as the destination operand of an
2712 integer store instruction
2713
2714 @item R
2715 A scaled or unscaled indexed memory operand
2716
2717 @item T
2718 A memory operand for floating-point loads and stores
2719
2720 @item W
2721 A register indirect memory operand
2722 @end table
2723
2724 @item Intel IA-64---@file{config/ia64/ia64.h}
2725 @table @code
2726 @item a
2727 General register @code{r0} to @code{r3} for @code{addl} instruction
2728
2729 @item b
2730 Branch register
2731
2732 @item c
2733 Predicate register (@samp{c} as in ``conditional'')
2734
2735 @item d
2736 Application register residing in M-unit
2737
2738 @item e
2739 Application register residing in I-unit
2740
2741 @item f
2742 Floating-point register
2743
2744 @item m
2745 Memory operand. If used together with @samp{<} or @samp{>},
2746 the operand can have postincrement and postdecrement which
2747 require printing with @samp{%Pn} on IA-64.
2748
2749 @item G
2750 Floating-point constant 0.0 or 1.0
2751
2752 @item I
2753 14-bit signed integer constant
2754
2755 @item J
2756 22-bit signed integer constant
2757
2758 @item K
2759 8-bit signed integer constant for logical instructions
2760
2761 @item L
2762 8-bit adjusted signed integer constant for compare pseudo-ops
2763
2764 @item M
2765 6-bit unsigned integer constant for shift counts
2766
2767 @item N
2768 9-bit signed integer constant for load and store postincrements
2769
2770 @item O
2771 The constant zero
2772
2773 @item P
2774 0 or @minus{}1 for @code{dep} instruction
2775
2776 @item Q
2777 Non-volatile memory for floating-point loads and stores
2778
2779 @item R
2780 Integer constant in the range 1 to 4 for @code{shladd} instruction
2781
2782 @item S
2783 Memory operand except postincrement and postdecrement. This is
2784 now roughly the same as @samp{m} when not used together with @samp{<}
2785 or @samp{>}.
2786 @end table
2787
2788 @item M32C---@file{config/m32c/m32c.cc}
2789 @table @code
2790 @item Rsp
2791 @itemx Rfb
2792 @itemx Rsb
2793 @samp{$sp}, @samp{$fb}, @samp{$sb}.
2794
2795 @item Rcr
2796 Any control register, when they're 16 bits wide (nothing if control
2797 registers are 24 bits wide)
2798
2799 @item Rcl
2800 Any control register, when they're 24 bits wide.
2801
2802 @item R0w
2803 @itemx R1w
2804 @itemx R2w
2805 @itemx R3w
2806 $r0, $r1, $r2, $r3.
2807
2808 @item R02
2809 $r0 or $r2, or $r2r0 for 32 bit values.
2810
2811 @item R13
2812 $r1 or $r3, or $r3r1 for 32 bit values.
2813
2814 @item Rdi
2815 A register that can hold a 64 bit value.
2816
2817 @item Rhl
2818 $r0 or $r1 (registers with addressable high/low bytes)
2819
2820 @item R23
2821 $r2 or $r3
2822
2823 @item Raa
2824 Address registers
2825
2826 @item Raw
2827 Address registers when they're 16 bits wide.
2828
2829 @item Ral
2830 Address registers when they're 24 bits wide.
2831
2832 @item Rqi
2833 Registers that can hold QI values.
2834
2835 @item Rad
2836 Registers that can be used with displacements ($a0, $a1, $sb).
2837
2838 @item Rsi
2839 Registers that can hold 32 bit values.
2840
2841 @item Rhi
2842 Registers that can hold 16 bit values.
2843
2844 @item Rhc
2845 Registers chat can hold 16 bit values, including all control
2846 registers.
2847
2848 @item Rra
2849 $r0 through R1, plus $a0 and $a1.
2850
2851 @item Rfl
2852 The flags register.
2853
2854 @item Rmm
2855 The memory-based pseudo-registers $mem0 through $mem15.
2856
2857 @item Rpi
2858 Registers that can hold pointers (16 bit registers for r8c, m16c; 24
2859 bit registers for m32cm, m32c).
2860
2861 @item Rpa
2862 Matches multiple registers in a PARALLEL to form a larger register.
2863 Used to match function return values.
2864
2865 @item Is3
2866 @minus{}8 @dots{} 7
2867
2868 @item IS1
2869 @minus{}128 @dots{} 127
2870
2871 @item IS2
2872 @minus{}32768 @dots{} 32767
2873
2874 @item IU2
2875 0 @dots{} 65535
2876
2877 @item In4
2878 @minus{}8 @dots{} @minus{}1 or 1 @dots{} 8
2879
2880 @item In5
2881 @minus{}16 @dots{} @minus{}1 or 1 @dots{} 16
2882
2883 @item In6
2884 @minus{}32 @dots{} @minus{}1 or 1 @dots{} 32
2885
2886 @item IM2
2887 @minus{}65536 @dots{} @minus{}1
2888
2889 @item Ilb
2890 An 8 bit value with exactly one bit set.
2891
2892 @item Ilw
2893 A 16 bit value with exactly one bit set.
2894
2895 @item Sd
2896 The common src/dest memory addressing modes.
2897
2898 @item Sa
2899 Memory addressed using $a0 or $a1.
2900
2901 @item Si
2902 Memory addressed with immediate addresses.
2903
2904 @item Ss
2905 Memory addressed using the stack pointer ($sp).
2906
2907 @item Sf
2908 Memory addressed using the frame base register ($fb).
2909
2910 @item Ss
2911 Memory addressed using the small base register ($sb).
2912
2913 @item S1
2914 $r1h
2915 @end table
2916
2917 @item LoongArch---@file{config/loongarch/constraints.md}
2918 @table @code
2919 @item f
2920 A floating-point or vector register (if available).
2921 @item k
2922 A memory operand whose address is formed by a base register and
2923 (optionally scaled) index register.
2924 @item l
2925 A signed 16-bit constant.
2926 @item m
2927 A memory operand whose address is formed by a base register and offset
2928 that is suitable for use in instructions with the same addressing mode
2929 as @code{st.w} and @code{ld.w}.
2930 @item I
2931 A signed 12-bit constant (for arithmetic instructions).
2932 @item K
2933 An unsigned 12-bit constant (for logic instructions).
2934 @item M
2935 A constant that cannot be loaded using @code{lui}, @code{addiu}
2936 or @code{ori}.
2937 @item N
2938 A constant in the range -65535 to -1 (inclusive).
2939 @item O
2940 A signed 15-bit constant.
2941 @item P
2942 A constant in the range 1 to 65535 (inclusive).
2943 @item R
2944 An address that can be used in a non-macro load or store.
2945 @item ZB
2946 An address that is held in a general-purpose register.
2947 The offset is zero.
2948 @item ZC
2949 A memory operand whose address is formed by a base register and offset
2950 that is suitable for use in instructions with the same addressing mode
2951 as @code{ll.w} and @code{sc.w}.
2952 @end table
2953
2954 @item MicroBlaze---@file{config/microblaze/constraints.md}
2955 @table @code
2956 @item d
2957 A general register (@code{r0} to @code{r31}).
2958
2959 @item z
2960 A status register (@code{rmsr}, @code{$fcc1} to @code{$fcc7}).
2961
2962 @end table
2963
2964 @item MIPS---@file{config/mips/constraints.md}
2965 @table @code
2966 @item d
2967 A general-purpose register. This is equivalent to @code{r} unless
2968 generating MIPS16 code, in which case the MIPS16 register set is used.
2969
2970 @item f
2971 A floating-point register (if available).
2972
2973 @item h
2974 Formerly the @code{hi} register. This constraint is no longer supported.
2975
2976 @item l
2977 The @code{lo} register. Use this register to store values that are
2978 no bigger than a word.
2979
2980 @item x
2981 The concatenated @code{hi} and @code{lo} registers. Use this register
2982 to store doubleword values.
2983
2984 @item c
2985 A register suitable for use in an indirect jump. This will always be
2986 @code{$25} for @option{-mabicalls}.
2987
2988 @item v
2989 Register @code{$3}. Do not use this constraint in new code;
2990 it is retained only for compatibility with glibc.
2991
2992 @item y
2993 Equivalent to @code{r}; retained for backwards compatibility.
2994
2995 @item z
2996 A floating-point condition code register.
2997
2998 @item I
2999 A signed 16-bit constant (for arithmetic instructions).
3000
3001 @item J
3002 Integer zero.
3003
3004 @item K
3005 An unsigned 16-bit constant (for logic instructions).
3006
3007 @item L
3008 A signed 32-bit constant in which the lower 16 bits are zero.
3009 Such constants can be loaded using @code{lui}.
3010
3011 @item M
3012 A constant that cannot be loaded using @code{lui}, @code{addiu}
3013 or @code{ori}.
3014
3015 @item N
3016 A constant in the range @minus{}65535 to @minus{}1 (inclusive).
3017
3018 @item O
3019 A signed 15-bit constant.
3020
3021 @item P
3022 A constant in the range 1 to 65535 (inclusive).
3023
3024 @item G
3025 Floating-point zero.
3026
3027 @item R
3028 An address that can be used in a non-macro load or store.
3029
3030 @item ZC
3031 A memory operand whose address is formed by a base register and offset
3032 that is suitable for use in instructions with the same addressing mode
3033 as @code{ll} and @code{sc}.
3034
3035 @item ZD
3036 An address suitable for a @code{prefetch} instruction, or for any other
3037 instruction with the same addressing mode as @code{prefetch}.
3038 @end table
3039
3040 @item Motorola 680x0---@file{config/m68k/constraints.md}
3041 @table @code
3042 @item a
3043 Address register
3044
3045 @item d
3046 Data register
3047
3048 @item f
3049 68881 floating-point register, if available
3050
3051 @item I
3052 Integer in the range 1 to 8
3053
3054 @item J
3055 16-bit signed number
3056
3057 @item K
3058 Signed number whose magnitude is greater than 0x80
3059
3060 @item L
3061 Integer in the range @minus{}8 to @minus{}1
3062
3063 @item M
3064 Signed number whose magnitude is greater than 0x100
3065
3066 @item N
3067 Range 24 to 31, rotatert:SI 8 to 1 expressed as rotate
3068
3069 @item O
3070 16 (for rotate using swap)
3071
3072 @item P
3073 Range 8 to 15, rotatert:HI 8 to 1 expressed as rotate
3074
3075 @item R
3076 Numbers that mov3q can handle
3077
3078 @item G
3079 Floating point constant that is not a 68881 constant
3080
3081 @item S
3082 Operands that satisfy 'm' when -mpcrel is in effect
3083
3084 @item T
3085 Operands that satisfy 's' when -mpcrel is not in effect
3086
3087 @item Q
3088 Address register indirect addressing mode
3089
3090 @item U
3091 Register offset addressing
3092
3093 @item W
3094 const_call_operand
3095
3096 @item Cs
3097 symbol_ref or const
3098
3099 @item Ci
3100 const_int
3101
3102 @item C0
3103 const_int 0
3104
3105 @item Cj
3106 Range of signed numbers that don't fit in 16 bits
3107
3108 @item Cmvq
3109 Integers valid for mvq
3110
3111 @item Capsw
3112 Integers valid for a moveq followed by a swap
3113
3114 @item Cmvz
3115 Integers valid for mvz
3116
3117 @item Cmvs
3118 Integers valid for mvs
3119
3120 @item Ap
3121 push_operand
3122
3123 @item Ac
3124 Non-register operands allowed in clr
3125
3126 @end table
3127
3128 @item Moxie---@file{config/moxie/constraints.md}
3129 @table @code
3130 @item A
3131 An absolute address
3132
3133 @item B
3134 An offset address
3135
3136 @item W
3137 A register indirect memory operand
3138
3139 @item I
3140 A constant in the range of 0 to 255.
3141
3142 @item N
3143 A constant in the range of 0 to @minus{}255.
3144
3145 @end table
3146
3147 @item MSP430--@file{config/msp430/constraints.md}
3148 @table @code
3149
3150 @item R12
3151 Register R12.
3152
3153 @item R13
3154 Register R13.
3155
3156 @item K
3157 Integer constant 1.
3158
3159 @item L
3160 Integer constant -1^20..1^19.
3161
3162 @item M
3163 Integer constant 1-4.
3164
3165 @item Ya
3166 Memory references which do not require an extended MOVX instruction.
3167
3168 @item Yl
3169 Memory reference, labels only.
3170
3171 @item Ys
3172 Memory reference, stack only.
3173
3174 @end table
3175
3176 @item NDS32---@file{config/nds32/constraints.md}
3177 @table @code
3178 @item w
3179 LOW register class $r0 to $r7 constraint for V3/V3M ISA.
3180 @item l
3181 LOW register class $r0 to $r7.
3182 @item d
3183 MIDDLE register class $r0 to $r11, $r16 to $r19.
3184 @item h
3185 HIGH register class $r12 to $r14, $r20 to $r31.
3186 @item t
3187 Temporary assist register $ta (i.e.@: $r15).
3188 @item k
3189 Stack register $sp.
3190 @item Iu03
3191 Unsigned immediate 3-bit value.
3192 @item In03
3193 Negative immediate 3-bit value in the range of @minus{}7--0.
3194 @item Iu04
3195 Unsigned immediate 4-bit value.
3196 @item Is05
3197 Signed immediate 5-bit value.
3198 @item Iu05
3199 Unsigned immediate 5-bit value.
3200 @item In05
3201 Negative immediate 5-bit value in the range of @minus{}31--0.
3202 @item Ip05
3203 Unsigned immediate 5-bit value for movpi45 instruction with range 16--47.
3204 @item Iu06
3205 Unsigned immediate 6-bit value constraint for addri36.sp instruction.
3206 @item Iu08
3207 Unsigned immediate 8-bit value.
3208 @item Iu09
3209 Unsigned immediate 9-bit value.
3210 @item Is10
3211 Signed immediate 10-bit value.
3212 @item Is11
3213 Signed immediate 11-bit value.
3214 @item Is15
3215 Signed immediate 15-bit value.
3216 @item Iu15
3217 Unsigned immediate 15-bit value.
3218 @item Ic15
3219 A constant which is not in the range of imm15u but ok for bclr instruction.
3220 @item Ie15
3221 A constant which is not in the range of imm15u but ok for bset instruction.
3222 @item It15
3223 A constant which is not in the range of imm15u but ok for btgl instruction.
3224 @item Ii15
3225 A constant whose compliment value is in the range of imm15u
3226 and ok for bitci instruction.
3227 @item Is16
3228 Signed immediate 16-bit value.
3229 @item Is17
3230 Signed immediate 17-bit value.
3231 @item Is19
3232 Signed immediate 19-bit value.
3233 @item Is20
3234 Signed immediate 20-bit value.
3235 @item Ihig
3236 The immediate value that can be simply set high 20-bit.
3237 @item Izeb
3238 The immediate value 0xff.
3239 @item Izeh
3240 The immediate value 0xffff.
3241 @item Ixls
3242 The immediate value 0x01.
3243 @item Ix11
3244 The immediate value 0x7ff.
3245 @item Ibms
3246 The immediate value with power of 2.
3247 @item Ifex
3248 The immediate value with power of 2 minus 1.
3249 @item U33
3250 Memory constraint for 333 format.
3251 @item U45
3252 Memory constraint for 45 format.
3253 @item U37
3254 Memory constraint for 37 format.
3255 @end table
3256
3257 @item OpenRISC---@file{config/or1k/constraints.md}
3258 @table @code
3259 @item I
3260 Integer that is valid as an immediate operand in an
3261 instruction taking a signed 16-bit number. Range
3262 @minus{}32768 to 32767.
3263
3264 @item K
3265 Integer that is valid as an immediate operand in an
3266 instruction taking an unsigned 16-bit number. Range
3267 0 to 65535.
3268
3269 @item M
3270 Signed 16-bit constant shifted left 16 bits. (Used with @code{l.movhi})
3271
3272 @item O
3273 Zero
3274
3275 @ifset INTERNALS
3276 @item c
3277 Register usable for sibcalls.
3278 @end ifset
3279
3280 @end table
3281
3282 @item PDP-11---@file{config/pdp11/constraints.md}
3283 @table @code
3284 @item a
3285 Floating point registers AC0 through AC3. These can be loaded from/to
3286 memory with a single instruction.
3287
3288 @item d
3289 Odd numbered general registers (R1, R3, R5). These are used for
3290 16-bit multiply operations.
3291
3292 @item D
3293 A memory reference that is encoded within the opcode, but not
3294 auto-increment or auto-decrement.
3295
3296 @item f
3297 Any of the floating point registers (AC0 through AC5).
3298
3299 @item G
3300 Floating point constant 0.
3301
3302 @item h
3303 Floating point registers AC4 and AC5. These cannot be loaded from/to
3304 memory with a single instruction.
3305
3306 @item I
3307 An integer constant that fits in 16 bits.
3308
3309 @item J
3310 An integer constant whose low order 16 bits are zero.
3311
3312 @item K
3313 An integer constant that does not meet the constraints for codes
3314 @samp{I} or @samp{J}.
3315
3316 @item L
3317 The integer constant 1.
3318
3319 @item M
3320 The integer constant @minus{}1.
3321
3322 @item N
3323 The integer constant 0.
3324
3325 @item O
3326 Integer constants 0 through 3; shifts by these
3327 amounts are handled as multiple single-bit shifts rather than a single
3328 variable-length shift.
3329
3330 @item Q
3331 A memory reference which requires an additional word (address or
3332 offset) after the opcode.
3333
3334 @item R
3335 A memory reference that is encoded within the opcode.
3336
3337 @end table
3338
3339 @item PowerPC and IBM RS6000---@file{config/rs6000/constraints.md}
3340 @table @code
3341 @item r
3342 A general purpose register (GPR), @code{r0}@dots{}@code{r31}.
3343
3344 @item b
3345 A base register. Like @code{r}, but @code{r0} is not allowed, so
3346 @code{r1}@dots{}@code{r31}.
3347
3348 @item f
3349 A floating point register (FPR), @code{f0}@dots{}@code{f31}.
3350
3351 @item d
3352 A floating point register. This is the same as @code{f} nowadays;
3353 historically @code{f} was for single-precision and @code{d} was for
3354 double-precision floating point.
3355
3356 @item v
3357 An Altivec vector register (VR), @code{v0}@dots{}@code{v31}.
3358
3359 @item wa
3360 A VSX register (VSR), @code{vs0}@dots{}@code{vs63}. This is either an
3361 FPR (@code{vs0}@dots{}@code{vs31} are @code{f0}@dots{}@code{f31}) or a VR
3362 (@code{vs32}@dots{}@code{vs63} are @code{v0}@dots{}@code{v31}).
3363
3364 When using @code{wa}, you should use the @code{%x} output modifier, so that
3365 the correct register number is printed. For example:
3366
3367 @smallexample
3368 asm ("xvadddp %x0,%x1,%x2"
3369 : "=wa" (v1)
3370 : "wa" (v2), "wa" (v3));
3371 @end smallexample
3372
3373 You should not use @code{%x} for @code{v} operands:
3374
3375 @smallexample
3376 asm ("xsaddqp %0,%1,%2"
3377 : "=v" (v1)
3378 : "v" (v2), "v" (v3));
3379 @end smallexample
3380
3381 @ifset INTERNALS
3382 @item h
3383 A special register (@code{vrsave}, @code{ctr}, or @code{lr}).
3384 @end ifset
3385
3386 @item c
3387 The count register, @code{ctr}.
3388
3389 @item l
3390 The link register, @code{lr}.
3391
3392 @item x
3393 Condition register field 0, @code{cr0}.
3394
3395 @item y
3396 Any condition register field, @code{cr0}@dots{}@code{cr7}.
3397
3398 @ifset INTERNALS
3399 @item z
3400 The carry bit, @code{XER[CA]}.
3401
3402 @item we
3403 Like @code{wa}, if this is a POWER9 or later and @option{-mvsx}
3404 and @option{-m64} are used; otherwise, @code{NO_REGS}.
3405
3406 @item wn
3407 No register (@code{NO_REGS}).
3408
3409 @item wr
3410 Like @code{r}, if @option{-mpowerpc64} is used; otherwise, @code{NO_REGS}.
3411
3412 @item wx
3413 Like @code{d}, if @option{-mpowerpc-gfxopt} is used; otherwise, @code{NO_REGS}.
3414
3415 @item wA
3416 Like @code{b}, if @option{-mpowerpc64} is used; otherwise, @code{NO_REGS}.
3417
3418 @item wB
3419 Signed 5-bit constant integer that can be loaded into an Altivec register.
3420
3421 @item wE
3422 Vector constant that can be loaded with the XXSPLTIB instruction.
3423
3424 @item wF
3425 Memory operand suitable for power8 GPR load fusion.
3426
3427 @item wL
3428 Int constant that is the element number mfvsrld accesses in a vector.
3429
3430 @item wM
3431 Match vector constant with all 1's if the XXLORC instruction is available.
3432
3433 @item wO
3434 Memory operand suitable for the ISA 3.0 vector d-form instructions.
3435
3436 @item wQ
3437 Memory operand suitable for the load/store quad instructions.
3438
3439 @item wS
3440 Vector constant that can be loaded with XXSPLTIB & sign extension.
3441
3442 @item wY
3443 A memory operand for a DS-form instruction.
3444
3445 @item wZ
3446 An indexed or indirect memory operand, ignoring the bottom 4 bits.
3447 @end ifset
3448
3449 @item I
3450 A signed 16-bit constant.
3451
3452 @item J
3453 An unsigned 16-bit constant shifted left 16 bits (use @code{L} instead
3454 for @code{SImode} constants).
3455
3456 @item K
3457 An unsigned 16-bit constant.
3458
3459 @item L
3460 A signed 16-bit constant shifted left 16 bits.
3461
3462 @ifset INTERNALS
3463 @item M
3464 An integer constant greater than 31.
3465
3466 @item N
3467 An exact power of 2.
3468
3469 @item O
3470 The integer constant zero.
3471
3472 @item P
3473 A constant whose negation is a signed 16-bit constant.
3474 @end ifset
3475
3476 @item eI
3477 A signed 34-bit integer constant if prefixed instructions are supported.
3478
3479 @item eP
3480 A scalar floating point constant or a vector constant that can be
3481 loaded to a VSX register with one prefixed instruction.
3482
3483 @item eQ
3484 An IEEE 128-bit constant that can be loaded into a VSX register with
3485 the @code{lxvkq} instruction.
3486
3487 @ifset INTERNALS
3488 @item G
3489 A floating point constant that can be loaded into a register with one
3490 instruction per word.
3491
3492 @item H
3493 A floating point constant that can be loaded into a register using
3494 three instructions.
3495 @end ifset
3496
3497 @item m
3498 A memory operand.
3499 Normally, @code{m} does not allow addresses that update the base register.
3500 If the @code{<} or @code{>} constraint is also used, they are allowed and
3501 therefore on PowerPC targets in that case it is only safe
3502 to use @code{m<>} in an @code{asm} statement if that @code{asm} statement
3503 accesses the operand exactly once. The @code{asm} statement must also
3504 use @code{%U@var{<opno>}} as a placeholder for the ``update'' flag in the
3505 corresponding load or store instruction. For example:
3506
3507 @smallexample
3508 asm ("st%U0 %1,%0" : "=m<>" (mem) : "r" (val));
3509 @end smallexample
3510
3511 is correct but:
3512
3513 @smallexample
3514 asm ("st %1,%0" : "=m<>" (mem) : "r" (val));
3515 @end smallexample
3516
3517 is not.
3518
3519 @ifset INTERNALS
3520 @item es
3521 A ``stable'' memory operand; that is, one which does not include any
3522 automodification of the base register. This used to be useful when
3523 @code{m} allowed automodification of the base register, but as those
3524 are now only allowed when @code{<} or @code{>} is used, @code{es} is
3525 basically the same as @code{m} without @code{<} and @code{>}.
3526 @end ifset
3527
3528 @item Q
3529 A memory operand addressed by just a base register.
3530
3531 @ifset INTERNALS
3532 @item Y
3533 A memory operand for a DQ-form instruction.
3534 @end ifset
3535
3536 @item Z
3537 A memory operand accessed with indexed or indirect addressing.
3538
3539 @ifset INTERNALS
3540 @item R
3541 An AIX TOC entry.
3542 @end ifset
3543
3544 @item a
3545 An indexed or indirect address.
3546
3547 @ifset INTERNALS
3548 @item U
3549 A V.4 small data reference.
3550
3551 @item W
3552 A vector constant that does not require memory.
3553
3554 @item j
3555 The zero vector constant.
3556 @end ifset
3557
3558 @end table
3559
3560 @item PRU---@file{config/pru/constraints.md}
3561 @table @code
3562 @item I
3563 An unsigned 8-bit integer constant.
3564
3565 @item J
3566 An unsigned 16-bit integer constant.
3567
3568 @item L
3569 An unsigned 5-bit integer constant (for shift counts).
3570
3571 @item T
3572 A text segment (program memory) constant label.
3573
3574 @item Z
3575 Integer constant zero.
3576
3577 @end table
3578
3579 @item RL78---@file{config/rl78/constraints.md}
3580 @table @code
3581
3582 @item Int3
3583 An integer constant in the range 1 @dots{} 7.
3584 @item Int8
3585 An integer constant in the range 0 @dots{} 255.
3586 @item J
3587 An integer constant in the range @minus{}255 @dots{} 0
3588 @item K
3589 The integer constant 1.
3590 @item L
3591 The integer constant -1.
3592 @item M
3593 The integer constant 0.
3594 @item N
3595 The integer constant 2.
3596 @item O
3597 The integer constant -2.
3598 @item P
3599 An integer constant in the range 1 @dots{} 15.
3600 @item Qbi
3601 The built-in compare types--eq, ne, gtu, ltu, geu, and leu.
3602 @item Qsc
3603 The synthetic compare types--gt, lt, ge, and le.
3604 @item Wab
3605 A memory reference with an absolute address.
3606 @item Wbc
3607 A memory reference using @code{BC} as a base register, with an optional offset.
3608 @item Wca
3609 A memory reference using @code{AX}, @code{BC}, @code{DE}, or @code{HL} for the address, for calls.
3610 @item Wcv
3611 A memory reference using any 16-bit register pair for the address, for calls.
3612 @item Wd2
3613 A memory reference using @code{DE} as a base register, with an optional offset.
3614 @item Wde
3615 A memory reference using @code{DE} as a base register, without any offset.
3616 @item Wfr
3617 Any memory reference to an address in the far address space.
3618 @item Wh1
3619 A memory reference using @code{HL} as a base register, with an optional one-byte offset.
3620 @item Whb
3621 A memory reference using @code{HL} as a base register, with @code{B} or @code{C} as the index register.
3622 @item Whl
3623 A memory reference using @code{HL} as a base register, without any offset.
3624 @item Ws1
3625 A memory reference using @code{SP} as a base register, with an optional one-byte offset.
3626 @item Y
3627 Any memory reference to an address in the near address space.
3628 @item A
3629 The @code{AX} register.
3630 @item B
3631 The @code{BC} register.
3632 @item D
3633 The @code{DE} register.
3634 @item R
3635 @code{A} through @code{L} registers.
3636 @item S
3637 The @code{SP} register.
3638 @item T
3639 The @code{HL} register.
3640 @item Z08W
3641 The 16-bit @code{R8} register.
3642 @item Z10W
3643 The 16-bit @code{R10} register.
3644 @item Zint
3645 The registers reserved for interrupts (@code{R24} to @code{R31}).
3646 @item a
3647 The @code{A} register.
3648 @item b
3649 The @code{B} register.
3650 @item c
3651 The @code{C} register.
3652 @item d
3653 The @code{D} register.
3654 @item e
3655 The @code{E} register.
3656 @item h
3657 The @code{H} register.
3658 @item l
3659 The @code{L} register.
3660 @item v
3661 The virtual registers.
3662 @item w
3663 The @code{PSW} register.
3664 @item x
3665 The @code{X} register.
3666
3667 @end table
3668
3669 @item RISC-V---@file{config/riscv/constraints.md}
3670 @table @code
3671
3672 @item f
3673 A floating-point register (if available).
3674
3675 @item I
3676 An I-type 12-bit signed immediate.
3677
3678 @item J
3679 Integer zero.
3680
3681 @item K
3682 A 5-bit unsigned immediate for CSR access instructions.
3683
3684 @item A
3685 An address that is held in a general-purpose register.
3686
3687 @item S
3688 A constraint that matches an absolute symbolic address.
3689
3690 @item vr
3691 A vector register (if available)..
3692
3693 @item vd
3694 A vector register, excluding v0 (if available).
3695
3696 @item vm
3697 A vector register, only v0 (if available).
3698
3699 @item cr
3700 RVC general purpose register (x8-x15).
3701
3702 @item cf
3703 RVC floating-point registers (f8-f15), if available, reuse GPR as FPR when use
3704 zfinx.
3705
3706 @item R
3707 Even-odd general purpose register pair.
3708
3709 @end table
3710
3711 @item RX---@file{config/rx/constraints.md}
3712 @table @code
3713 @item Q
3714 An address which does not involve register indirect addressing or
3715 pre/post increment/decrement addressing.
3716
3717 @item Symbol
3718 A symbol reference.
3719
3720 @item Int08
3721 A constant in the range @minus{}256 to 255, inclusive.
3722
3723 @item Sint08
3724 A constant in the range @minus{}128 to 127, inclusive.
3725
3726 @item Sint16
3727 A constant in the range @minus{}32768 to 32767, inclusive.
3728
3729 @item Sint24
3730 A constant in the range @minus{}8388608 to 8388607, inclusive.
3731
3732 @item Uint04
3733 A constant in the range 0 to 15, inclusive.
3734
3735 @end table
3736
3737 @item S/390 and zSeries---@file{config/s390/s390.h}
3738 @table @code
3739 @item a
3740 Address register (general purpose register except r0)
3741
3742 @item c
3743 Condition code register
3744
3745 @item d
3746 Data register (arbitrary general purpose register)
3747
3748 @item f
3749 Floating-point register
3750
3751 @item I
3752 Unsigned 8-bit constant (0--255)
3753
3754 @item J
3755 Unsigned 12-bit constant (0--4095)
3756
3757 @item K
3758 Signed 16-bit constant (@minus{}32768--32767)
3759
3760 @item L
3761 Value appropriate as displacement.
3762 @table @code
3763 @item (0..4095)
3764 for short displacement
3765 @item (@minus{}524288..524287)
3766 for long displacement
3767 @end table
3768
3769 @item M
3770 Constant integer with a value of 0x7fffffff.
3771
3772 @item N
3773 Multiple letter constraint followed by 4 parameter letters.
3774 @table @code
3775 @item 0..9:
3776 number of the part counting from most to least significant
3777 @item H,Q:
3778 mode of the part
3779 @item D,S,H:
3780 mode of the containing operand
3781 @item 0,F:
3782 value of the other parts (F---all bits set)
3783 @end table
3784 The constraint matches if the specified part of a constant
3785 has a value different from its other parts.
3786
3787 @item Q
3788 Memory reference without index register and with short displacement.
3789
3790 @item R
3791 Memory reference with index register and short displacement.
3792
3793 @item S
3794 Memory reference without index register but with long displacement.
3795
3796 @item T
3797 Memory reference with index register and long displacement.
3798
3799 @item U
3800 Pointer with short displacement.
3801
3802 @item W
3803 Pointer with long displacement.
3804
3805 @item Y
3806 Shift count operand.
3807
3808 @end table
3809
3810 @need 1000
3811 @item SPARC---@file{config/sparc/sparc.h}
3812 @table @code
3813 @item f
3814 Floating-point register on the SPARC-V8 architecture and
3815 lower floating-point register on the SPARC-V9 architecture.
3816
3817 @item e
3818 Floating-point register. It is equivalent to @samp{f} on the
3819 SPARC-V8 architecture and contains both lower and upper
3820 floating-point registers on the SPARC-V9 architecture.
3821
3822 @item c
3823 Floating-point condition code register.
3824
3825 @item d
3826 Lower floating-point register. It is only valid on the SPARC-V9
3827 architecture when the Visual Instruction Set is available.
3828
3829 @item b
3830 Floating-point register. It is only valid on the SPARC-V9 architecture
3831 when the Visual Instruction Set is available.
3832
3833 @item h
3834 64-bit global or out register for the SPARC-V8+ architecture.
3835
3836 @item C
3837 The constant all-ones, for floating-point.
3838
3839 @item A
3840 Signed 5-bit constant
3841
3842 @item D
3843 A vector constant
3844
3845 @item I
3846 Signed 13-bit constant
3847
3848 @item J
3849 Zero
3850
3851 @item K
3852 32-bit constant with the low 12 bits clear (a constant that can be
3853 loaded with the @code{sethi} instruction)
3854
3855 @item L
3856 A constant in the range supported by @code{movcc} instructions (11-bit
3857 signed immediate)
3858
3859 @item M
3860 A constant in the range supported by @code{movrcc} instructions (10-bit
3861 signed immediate)
3862
3863 @item N
3864 Same as @samp{K}, except that it verifies that bits that are not in the
3865 lower 32-bit range are all zero. Must be used instead of @samp{K} for
3866 modes wider than @code{SImode}
3867
3868 @item O
3869 The constant 4096
3870
3871 @item G
3872 Floating-point zero
3873
3874 @item H
3875 Signed 13-bit constant, sign-extended to 32 or 64 bits
3876
3877 @item P
3878 The constant -1
3879
3880 @item Q
3881 Floating-point constant whose integral representation can
3882 be moved into an integer register using a single sethi
3883 instruction
3884
3885 @item R
3886 Floating-point constant whose integral representation can
3887 be moved into an integer register using a single mov
3888 instruction
3889
3890 @item S
3891 Floating-point constant whose integral representation can
3892 be moved into an integer register using a high/lo_sum
3893 instruction sequence
3894
3895 @item T
3896 Memory address aligned to an 8-byte boundary
3897
3898 @item W
3899 Memory address for @samp{e} constraint registers
3900
3901 @item w
3902 Memory address with only a base register
3903
3904 @item Y
3905 Vector zero
3906
3907 @end table
3908
3909 @item TI C6X family---@file{config/c6x/constraints.md}
3910 @table @code
3911 @item a
3912 Register file A (A0--A31).
3913
3914 @item b
3915 Register file B (B0--B31).
3916
3917 @item A
3918 Predicate registers in register file A (A0--A2 on C64X and
3919 higher, A1 and A2 otherwise).
3920
3921 @item B
3922 Predicate registers in register file B (B0--B2).
3923
3924 @item C
3925 A call-used register in register file B (B0--B9, B16--B31).
3926
3927 @item Da
3928 Register file A, excluding predicate registers (A3--A31,
3929 plus A0 if not C64X or higher).
3930
3931 @item Db
3932 Register file B, excluding predicate registers (B3--B31).
3933
3934 @item Iu4
3935 Integer constant in the range 0 @dots{} 15.
3936
3937 @item Iu5
3938 Integer constant in the range 0 @dots{} 31.
3939
3940 @item In5
3941 Integer constant in the range @minus{}31 @dots{} 0.
3942
3943 @item Is5
3944 Integer constant in the range @minus{}16 @dots{} 15.
3945
3946 @item I5x
3947 Integer constant that can be the operand of an ADDA or a SUBA insn.
3948
3949 @item IuB
3950 Integer constant in the range 0 @dots{} 65535.
3951
3952 @item IsB
3953 Integer constant in the range @minus{}32768 @dots{} 32767.
3954
3955 @item IsC
3956 Integer constant in the range @math{-2^{20}} @dots{} @math{2^{20} - 1}.
3957
3958 @item Jc
3959 Integer constant that is a valid mask for the clr instruction.
3960
3961 @item Js
3962 Integer constant that is a valid mask for the set instruction.
3963
3964 @item Q
3965 Memory location with A base register.
3966
3967 @item R
3968 Memory location with B base register.
3969
3970 @ifset INTERNALS
3971 @item S0
3972 On C64x+ targets, a GP-relative small data reference.
3973
3974 @item S1
3975 Any kind of @code{SYMBOL_REF}, for use in a call address.
3976
3977 @item Si
3978 Any kind of immediate operand, unless it matches the S0 constraint.
3979
3980 @item T
3981 Memory location with B base register, but not using a long offset.
3982
3983 @item W
3984 A memory operand with an address that cannot be used in an unaligned access.
3985
3986 @end ifset
3987 @item Z
3988 Register B14 (aka DP).
3989
3990 @end table
3991
3992 @item Visium---@file{config/visium/constraints.md}
3993 @table @code
3994 @item b
3995 EAM register @code{mdb}
3996
3997 @item c
3998 EAM register @code{mdc}
3999
4000 @item f
4001 Floating point register
4002
4003 @ifset INTERNALS
4004 @item k
4005 Register for sibcall optimization
4006 @end ifset
4007
4008 @item l
4009 General register, but not @code{r29}, @code{r30} and @code{r31}
4010
4011 @item t
4012 Register @code{r1}
4013
4014 @item u
4015 Register @code{r2}
4016
4017 @item v
4018 Register @code{r3}
4019
4020 @item G
4021 Floating-point constant 0.0
4022
4023 @item J
4024 Integer constant in the range 0 .. 65535 (16-bit immediate)
4025
4026 @item K
4027 Integer constant in the range 1 .. 31 (5-bit immediate)
4028
4029 @item L
4030 Integer constant in the range @minus{}65535 .. @minus{}1 (16-bit negative immediate)
4031
4032 @item M
4033 Integer constant @minus{}1
4034
4035 @item O
4036 Integer constant 0
4037
4038 @item P
4039 Integer constant 32
4040 @end table
4041
4042 @item x86 family---@file{config/i386/constraints.md}
4043 @table @code
4044 @item R
4045 Legacy register---the eight integer registers available on all
4046 i386 processors (@code{a}, @code{b}, @code{c}, @code{d},
4047 @code{si}, @code{di}, @code{bp}, @code{sp}).
4048
4049 @item q
4050 Any register accessible as @code{@var{r}l}. In 32-bit mode, @code{a},
4051 @code{b}, @code{c}, and @code{d}; in 64-bit mode, any integer register.
4052
4053 @item Q
4054 Any register accessible as @code{@var{r}h}: @code{a}, @code{b},
4055 @code{c}, and @code{d}.
4056
4057 @ifset INTERNALS
4058 @item l
4059 Any register that can be used as the index in a base+index memory
4060 access: that is, any general register except the stack pointer.
4061 @end ifset
4062
4063 @item a
4064 The @code{a} register.
4065
4066 @item b
4067 The @code{b} register.
4068
4069 @item c
4070 The @code{c} register.
4071
4072 @item d
4073 The @code{d} register.
4074
4075 @item S
4076 The @code{si} register.
4077
4078 @item D
4079 The @code{di} register.
4080
4081 @item A
4082 The @code{a} and @code{d} registers. This class is used for instructions
4083 that return double word results in the @code{ax:dx} register pair. Single
4084 word values will be allocated either in @code{ax} or @code{dx}.
4085 For example on i386 the following implements @code{rdtsc}:
4086
4087 @smallexample
4088 unsigned long long rdtsc (void)
4089 @{
4090 unsigned long long tick;
4091 __asm__ __volatile__("rdtsc":"=A"(tick));
4092 return tick;
4093 @}
4094 @end smallexample
4095
4096 This is not correct on x86-64 as it would allocate tick in either @code{ax}
4097 or @code{dx}. You have to use the following variant instead:
4098
4099 @smallexample
4100 unsigned long long rdtsc (void)
4101 @{
4102 unsigned int tickl, tickh;
4103 __asm__ __volatile__("rdtsc":"=a"(tickl),"=d"(tickh));
4104 return ((unsigned long long)tickh << 32)|tickl;
4105 @}
4106 @end smallexample
4107
4108 @item U
4109 The call-clobbered integer registers.
4110
4111 @item f
4112 Any 80387 floating-point (stack) register.
4113
4114 @item t
4115 Top of 80387 floating-point stack (@code{%st(0)}).
4116
4117 @item u
4118 Second from top of 80387 floating-point stack (@code{%st(1)}).
4119
4120 @ifset INTERNALS
4121 @item Yk
4122 Any mask register that can be used as a predicate, i.e.@: @code{k1-k7}.
4123
4124 @item k
4125 Any mask register.
4126 @end ifset
4127
4128 @item y
4129 Any MMX register.
4130
4131 @item x
4132 Any SSE register.
4133
4134 @item v
4135 Any EVEX encodable SSE register (@code{%xmm0-%xmm31}).
4136
4137 @ifset INTERNALS
4138 @item w
4139 Any bound register.
4140 @end ifset
4141
4142 @item Yz
4143 First SSE register (@code{%xmm0}).
4144
4145 @ifset INTERNALS
4146 @item Yi
4147 Any SSE register, when SSE2 and inter-unit moves are enabled.
4148
4149 @item Yj
4150 Any SSE register, when SSE2 and inter-unit moves from vector registers are enabled.
4151
4152 @item Ym
4153 Any MMX register, when inter-unit moves are enabled.
4154
4155 @item Yn
4156 Any MMX register, when inter-unit moves from vector registers are enabled.
4157
4158 @item Yp
4159 Any integer register when @code{TARGET_PARTIAL_REG_STALL} is disabled.
4160
4161 @item Ya
4162 Any integer register when zero extensions with @code{AND} are disabled.
4163
4164 @item Yb
4165 Any register that can be used as the GOT base when calling@*
4166 @code{___tls_get_addr}: that is, any general register except @code{a}
4167 and @code{sp} registers, for @option{-fno-plt} if linker supports it.
4168 Otherwise, @code{b} register.
4169
4170 @item Yf
4171 Any x87 register when 80387 floating-point arithmetic is enabled.
4172
4173 @item Yr
4174 Lower SSE register when avoiding REX prefix and all SSE registers otherwise.
4175
4176 @item Yv
4177 For AVX512VL, any EVEX-encodable SSE register (@code{%xmm0-%xmm31}),
4178 otherwise any SSE register.
4179
4180 @item Yh
4181 Any EVEX-encodable SSE register, that has number factor of four.
4182
4183 @item Bf
4184 Flags register operand.
4185
4186 @item Bg
4187 GOT memory operand.
4188
4189 @item Bm
4190 Vector memory operand.
4191
4192 @item Bc
4193 Constant memory operand.
4194
4195 @item Bn
4196 Memory operand without REX prefix.
4197
4198 @item Bs
4199 Sibcall memory operand.
4200
4201 @item Bw
4202 Call memory operand.
4203
4204 @item Bz
4205 Constant call address operand.
4206
4207 @item BC
4208 SSE constant -1 operand.
4209 @end ifset
4210
4211 @item I
4212 Integer constant in the range 0 @dots{} 31, for 32-bit shifts.
4213
4214 @item J
4215 Integer constant in the range 0 @dots{} 63, for 64-bit shifts.
4216
4217 @item K
4218 Signed 8-bit integer constant.
4219
4220 @item L
4221 @code{0xFF} or @code{0xFFFF}, for andsi as a zero-extending move.
4222
4223 @item M
4224 0, 1, 2, or 3 (shifts for the @code{lea} instruction).
4225
4226 @item N
4227 Unsigned 8-bit integer constant (for @code{in} and @code{out}
4228 instructions).
4229
4230 @ifset INTERNALS
4231 @item O
4232 Integer constant in the range 0 @dots{} 127, for 128-bit shifts.
4233 @end ifset
4234
4235 @item G
4236 Standard 80387 floating point constant.
4237
4238 @item C
4239 SSE constant zero operand.
4240
4241 @item e
4242 32-bit signed integer constant, or a symbolic reference known
4243 to fit that range (for immediate operands in sign-extending x86-64
4244 instructions).
4245
4246 @item We
4247 32-bit signed integer constant, or a symbolic reference known
4248 to fit that range (for sign-extending conversion operations that
4249 require non-@code{VOIDmode} immediate operands).
4250
4251 @item Wz
4252 32-bit unsigned integer constant, or a symbolic reference known
4253 to fit that range (for zero-extending conversion operations that
4254 require non-@code{VOIDmode} immediate operands).
4255
4256 @item Wd
4257 128-bit integer constant where both the high and low 64-bit word
4258 satisfy the @code{e} constraint.
4259
4260 @item Ws
4261 A symbolic reference or label reference.
4262 You can use the @code{%p} modifier to print the raw symbol.
4263
4264 @item Z
4265 32-bit unsigned integer constant, or a symbolic reference known
4266 to fit that range (for immediate operands in zero-extending x86-64
4267 instructions).
4268
4269 @item Tv
4270 VSIB address operand.
4271
4272 @item Ts
4273 Address operand without segment register.
4274
4275 @end table
4276
4277 @item Xstormy16---@file{config/stormy16/stormy16.h}
4278 @table @code
4279 @item a
4280 Register r0.
4281
4282 @item b
4283 Register r1.
4284
4285 @item c
4286 Register r2.
4287
4288 @item d
4289 Register r8.
4290
4291 @item e
4292 Registers r0 through r7.
4293
4294 @item t
4295 Registers r0 and r1.
4296
4297 @item y
4298 The carry register.
4299
4300 @item z
4301 Registers r8 and r9.
4302
4303 @item I
4304 A constant between 0 and 3 inclusive.
4305
4306 @item J
4307 A constant that has exactly one bit set.
4308
4309 @item K
4310 A constant that has exactly one bit clear.
4311
4312 @item L
4313 A constant between 0 and 255 inclusive.
4314
4315 @item M
4316 A constant between @minus{}255 and 0 inclusive.
4317
4318 @item N
4319 A constant between @minus{}3 and 0 inclusive.
4320
4321 @item O
4322 A constant between 1 and 4 inclusive.
4323
4324 @item P
4325 A constant between @minus{}4 and @minus{}1 inclusive.
4326
4327 @item Q
4328 A memory reference that is a stack push.
4329
4330 @item R
4331 A memory reference that is a stack pop.
4332
4333 @item S
4334 A memory reference that refers to a constant address of known value.
4335
4336 @item T
4337 The register indicated by Rx (not implemented yet).
4338
4339 @item U
4340 A constant that is not between 2 and 15 inclusive.
4341
4342 @item Z
4343 The constant 0.
4344
4345 @end table
4346
4347 @item Xtensa---@file{config/xtensa/constraints.md}
4348 @table @code
4349 @item a
4350 General-purpose 32-bit register
4351
4352 @item b
4353 One-bit boolean register
4354
4355 @item A
4356 MAC16 40-bit accumulator register
4357
4358 @item I
4359 Signed 12-bit integer constant, for use in MOVI instructions
4360
4361 @item J
4362 Signed 8-bit integer constant, for use in ADDI instructions
4363
4364 @item K
4365 Integer constant valid for BccI instructions
4366
4367 @item L
4368 Unsigned constant valid for BccUI instructions
4369
4370 @end table
4371
4372 @end table
4373
4374 @ifset INTERNALS
4375 @node Disable Insn Alternatives
4376 @subsection Disable insn alternatives using the @code{enabled} attribute
4377 @cindex enabled
4378
4379 There are three insn attributes that may be used to selectively disable
4380 instruction alternatives:
4381
4382 @table @code
4383 @item enabled
4384 Says whether an alternative is available on the current subtarget.
4385
4386 @item preferred_for_size
4387 Says whether an enabled alternative should be used in code that is
4388 optimized for size.
4389
4390 @item preferred_for_speed
4391 Says whether an enabled alternative should be used in code that is
4392 optimized for speed.
4393 @end table
4394
4395 All these attributes should use @code{(const_int 1)} to allow an alternative
4396 or @code{(const_int 0)} to disallow it. The attributes must be a static
4397 property of the subtarget; they cannot for example depend on the
4398 current operands, on the current optimization level, on the location
4399 of the insn within the body of a loop, on whether register allocation
4400 has finished, or on the current compiler pass.
4401
4402 The @code{enabled} attribute is a correctness property. It tells GCC to act
4403 as though the disabled alternatives were never defined in the first place.
4404 This is useful when adding new instructions to an existing pattern in
4405 cases where the new instructions are only available for certain cpu
4406 architecture levels (typically mapped to the @code{-march=} command-line
4407 option).
4408
4409 In contrast, the @code{preferred_for_size} and @code{preferred_for_speed}
4410 attributes are strong optimization hints rather than correctness properties.
4411 @code{preferred_for_size} tells GCC which alternatives to consider when
4412 adding or modifying an instruction that GCC wants to optimize for size.
4413 @code{preferred_for_speed} does the same thing for speed. Note that things
4414 like code motion can lead to cases where code optimized for size uses
4415 alternatives that are not preferred for size, and similarly for speed.
4416
4417 Although @code{define_insn}s can in principle specify the @code{enabled}
4418 attribute directly, it is often clearer to have subsiduary attributes
4419 for each architectural feature of interest. The @code{define_insn}s
4420 can then use these subsiduary attributes to say which alternatives
4421 require which features. The example below does this for @code{cpu_facility}.
4422
4423 E.g. the following two patterns could easily be merged using the @code{enabled}
4424 attribute:
4425
4426 @smallexample
4427
4428 (define_insn "*movdi_old"
4429 [(set (match_operand:DI 0 "register_operand" "=d")
4430 (match_operand:DI 1 "register_operand" " d"))]
4431 "!TARGET_NEW"
4432 "lgr %0,%1")
4433
4434 (define_insn "*movdi_new"
4435 [(set (match_operand:DI 0 "register_operand" "=d,f,d")
4436 (match_operand:DI 1 "register_operand" " d,d,f"))]
4437 "TARGET_NEW"
4438 "@@
4439 lgr %0,%1
4440 ldgr %0,%1
4441 lgdr %0,%1")
4442
4443 @end smallexample
4444
4445 to:
4446
4447 @smallexample
4448
4449 (define_insn "*movdi_combined"
4450 [(set (match_operand:DI 0 "register_operand" "=d,f,d")
4451 (match_operand:DI 1 "register_operand" " d,d,f"))]
4452 ""
4453 "@@
4454 lgr %0,%1
4455 ldgr %0,%1
4456 lgdr %0,%1"
4457 [(set_attr "cpu_facility" "*,new,new")])
4458
4459 @end smallexample
4460
4461 with the @code{enabled} attribute defined like this:
4462
4463 @smallexample
4464
4465 (define_attr "cpu_facility" "standard,new" (const_string "standard"))
4466
4467 (define_attr "enabled" ""
4468 (cond [(eq_attr "cpu_facility" "standard") (const_int 1)
4469 (and (eq_attr "cpu_facility" "new")
4470 (ne (symbol_ref "TARGET_NEW") (const_int 0)))
4471 (const_int 1)]
4472 (const_int 0)))
4473
4474 @end smallexample
4475
4476 @end ifset
4477
4478 @ifset INTERNALS
4479 @node Define Constraints
4480 @subsection Defining Machine-Specific Constraints
4481 @cindex defining constraints
4482 @cindex constraints, defining
4483
4484 Machine-specific constraints fall into two categories: register and
4485 non-register constraints. Within the latter category, constraints
4486 which allow subsets of all possible memory or address operands should
4487 be specially marked, to give @code{reload} more information.
4488
4489 Machine-specific constraints can be given names of arbitrary length,
4490 but they must be entirely composed of letters, digits, underscores
4491 (@samp{_}), and angle brackets (@samp{< >}). Like C identifiers, they
4492 must begin with a letter or underscore.
4493
4494 In order to avoid ambiguity in operand constraint strings, no
4495 constraint can have a name that begins with any other constraint's
4496 name. For example, if @code{x} is defined as a constraint name,
4497 @code{xy} may not be, and vice versa. As a consequence of this rule,
4498 no constraint may begin with one of the generic constraint letters:
4499 @samp{E F V X g i m n o p r s}.
4500
4501 Register constraints correspond directly to register classes.
4502 @xref{Register Classes}. There is thus not much flexibility in their
4503 definitions.
4504
4505 @deffn {MD Expression} define_register_constraint name regclass docstring [filter]
4506 All arguments are string constants.
4507 @var{name} is the name of the constraint, as it will appear in
4508 @code{match_operand} expressions. If @var{name} is a multi-letter
4509 constraint its length shall be the same for all constraints starting
4510 with the same letter. @var{regclass} can be either the
4511 name of the corresponding register class (@pxref{Register Classes}),
4512 or a C expression which evaluates to the appropriate register class.
4513 If it is an expression, it must have no side effects, and it cannot
4514 look at the operand. The usual use of expressions is to map some
4515 register constraints to @code{NO_REGS} when the register class
4516 is not available on a given subarchitecture.
4517
4518 If an operand occupies multiple hard registers, the constraint
4519 requires all of those registers to belong to @var{regclass}.
4520 For example, if @var{regclass} is @code{GENERAL_REGS} and
4521 @code{GENERAL_REGS} contains registers @code{r0} to @code{r15},
4522 the constraint does not allow @var{r15} to be used for modes
4523 that occupy more than one register.
4524
4525 @cindex @code{TARGET_HARD_REGNO_MODE_OK} and constraints
4526 The choice of register is also constrained by @code{TARGET_HARD_REGNO_MODE_OK}.
4527 For example, if @code{TARGET_HARD_REGNO_MODE_OK} disallows @samp{(reg:DI r1)},
4528 that requirement applies to all constraints whose classes include @code{r1}.
4529
4530 However, it is sometimes useful to impose extra operand-specific
4531 requirements on the register number. For example, a target might not
4532 want to prevent @emph{all} odd-even pairs from holding @code{DImode}
4533 values, but it might still need to prevent specific operands from
4534 having an odd-numbered register. The optional @var{filter} argument
4535 exists for such cases. When given, @var{filter} is a C++ expression
4536 that evaluates to true if @code{regno} is a valid register for the
4537 operand. If an operand occupies multiple registers, the condition
4538 applies only to the first register.
4539
4540 For example:
4541
4542 @smallexample
4543 (define_register_constraint "e" "GENERAL_REGS" "..." "regno % 2 == 0")
4544 @end smallexample
4545
4546 defines a constraint that requires an even-numbered general register.
4547
4548 Filter conditions that impose an alignment are encouraged to test
4549 the alignment of @code{regno} itself, as in the example, rather than
4550 calculate an offset relative to the start of the class. If it is
4551 sometimes necessary for a register of class @var{c} to be aligned
4552 to @var{n}, the first register in @var{c} should itself by divisible
4553 by @var{n}.
4554
4555 @var{docstring} is a sentence documenting the meaning of the
4556 constraint. Docstrings are explained further below.
4557 @end deffn
4558
4559 Non-register constraints are more like predicates: the constraint
4560 definition gives a boolean expression which indicates whether the
4561 constraint matches.
4562
4563 @deffn {MD Expression} define_constraint name docstring exp
4564 The @var{name} and @var{docstring} arguments are the same as for
4565 @code{define_register_constraint}, but note that the docstring comes
4566 immediately after the name for these expressions. @var{exp} is an RTL
4567 expression, obeying the same rules as the RTL expressions in predicate
4568 definitions. @xref{Defining Predicates}, for details. If it
4569 evaluates true, the constraint matches; if it evaluates false, it
4570 doesn't. Constraint expressions should indicate which RTL codes they
4571 might match, just like predicate expressions.
4572
4573 @code{match_test} C expressions have access to the
4574 following variables:
4575
4576 @table @var
4577 @item op
4578 The RTL object defining the operand.
4579 @item mode
4580 The machine mode of @var{op}.
4581 @item ival
4582 @samp{INTVAL (@var{op})}, if @var{op} is a @code{const_int}.
4583 @item hval
4584 @samp{CONST_DOUBLE_HIGH (@var{op})}, if @var{op} is an integer
4585 @code{const_double}.
4586 @item lval
4587 @samp{CONST_DOUBLE_LOW (@var{op})}, if @var{op} is an integer
4588 @code{const_double}.
4589 @item rval
4590 @samp{CONST_DOUBLE_REAL_VALUE (@var{op})}, if @var{op} is a floating-point
4591 @code{const_double}.
4592 @end table
4593
4594 The @var{*val} variables should only be used once another piece of the
4595 expression has verified that @var{op} is the appropriate kind of RTL
4596 object.
4597 @end deffn
4598
4599 Most non-register constraints should be defined with
4600 @code{define_constraint}. The remaining two definition expressions
4601 are only appropriate for constraints that should be handled specially
4602 by @code{reload} if they fail to match.
4603
4604 @deffn {MD Expression} define_memory_constraint name docstring exp
4605 Use this expression for constraints that match a subset of all memory
4606 operands: that is, @code{reload} can make them match by converting the
4607 operand to the form @samp{@w{(mem (reg @var{X}))}}, where @var{X} is a
4608 base register (from the register class specified by
4609 @code{BASE_REG_CLASS}, @pxref{Register Classes}).
4610
4611 For example, on the S/390, some instructions do not accept arbitrary
4612 memory references, but only those that do not make use of an index
4613 register. The constraint letter @samp{Q} is defined to represent a
4614 memory address of this type. If @samp{Q} is defined with
4615 @code{define_memory_constraint}, a @samp{Q} constraint can handle any
4616 memory operand, because @code{reload} knows it can simply copy the
4617 memory address into a base register if required. This is analogous to
4618 the way an @samp{o} constraint can handle any memory operand.
4619
4620 The syntax and semantics are otherwise identical to
4621 @code{define_constraint}.
4622 @end deffn
4623
4624 @deffn {MD Expression} define_special_memory_constraint name docstring exp
4625 Use this expression for constraints that match a subset of all memory
4626 operands: that is, @code{reload} cannot make them match by reloading
4627 the address as it is described for @code{define_memory_constraint} or
4628 such address reload is undesirable with the performance point of view.
4629
4630 For example, @code{define_special_memory_constraint} can be useful if
4631 specifically aligned memory is necessary or desirable for some insn
4632 operand.
4633
4634 The syntax and semantics are otherwise identical to
4635 @code{define_memory_constraint}.
4636 @end deffn
4637
4638 @deffn {MD Expression} define_relaxed_memory_constraint name docstring exp
4639 The test expression in a @code{define_memory_constraint} can assume
4640 that @code{TARGET_LEGITIMATE_ADDRESS_P} holds for the address inside
4641 a @code{mem} rtx and so it does not need to test this condition itself.
4642 In other words, a @code{define_memory_constraint} test of the form:
4643
4644 @smallexample
4645 (match_test "mem")
4646 @end smallexample
4647
4648 is enough to test whether an rtx is a @code{mem} @emph{and} whether
4649 its address satisfies @code{TARGET_MEM_CONSTRAINT} (which is usually
4650 @samp{'m'}). Thus the conditions imposed by a @code{define_memory_constraint}
4651 always apply on top of the conditions imposed by @code{TARGET_MEM_CONSTRAINT}.
4652
4653 However, it is sometimes useful to define memory constraints that allow
4654 addresses beyond those accepted by @code{TARGET_LEGITIMATE_ADDRESS_P}.
4655 @code{define_relaxed_memory_constraint} exists for this case.
4656 The test expression in a @code{define_relaxed_memory_constraint} is
4657 applied with no preconditions, so that the expression can determine
4658 ``from scratch'' exactly which addresses are valid and which are not.
4659
4660 The syntax and semantics are otherwise identical to
4661 @code{define_memory_constraint}.
4662 @end deffn
4663
4664 @deffn {MD Expression} define_address_constraint name docstring exp
4665 Use this expression for constraints that match a subset of all address
4666 operands: that is, @code{reload} can make the constraint match by
4667 converting the operand to the form @samp{@w{(reg @var{X})}}, again
4668 with @var{X} a base register.
4669
4670 Constraints defined with @code{define_address_constraint} can only be
4671 used with the @code{address_operand} predicate, or machine-specific
4672 predicates that work the same way. They are treated analogously to
4673 the generic @samp{p} constraint.
4674
4675 The syntax and semantics are otherwise identical to
4676 @code{define_constraint}.
4677 @end deffn
4678
4679 For historical reasons, names beginning with the letters @samp{G H}
4680 are reserved for constraints that match only @code{const_double}s, and
4681 names beginning with the letters @samp{I J K L M N O P} are reserved
4682 for constraints that match only @code{const_int}s. This may change in
4683 the future. For the time being, constraints with these names must be
4684 written in a stylized form, so that @code{genpreds} can tell you did
4685 it correctly:
4686
4687 @smallexample
4688 @group
4689 (define_constraint "[@var{GHIJKLMNOP}]@dots{}"
4690 "@var{doc}@dots{}"
4691 (and (match_code "const_int") ; @r{@code{const_double} for G/H}
4692 @var{condition}@dots{})) ; @r{usually a @code{match_test}}
4693 @end group
4694 @end smallexample
4695 @c the semicolons line up in the formatted manual
4696
4697 It is fine to use names beginning with other letters for constraints
4698 that match @code{const_double}s or @code{const_int}s.
4699
4700 Each docstring in a constraint definition should be one or more complete
4701 sentences, marked up in Texinfo format. @emph{They are currently unused.}
4702 In the future they will be copied into the GCC manual, in @ref{Machine
4703 Constraints}, replacing the hand-maintained tables currently found in
4704 that section. Also, in the future the compiler may use this to give
4705 more helpful diagnostics when poor choice of @code{asm} constraints
4706 causes a reload failure.
4707
4708 If you put the pseudo-Texinfo directive @samp{@@internal} at the
4709 beginning of a docstring, then (in the future) it will appear only in
4710 the internals manual's version of the machine-specific constraint tables.
4711 Use this for constraints that should not appear in @code{asm} statements.
4712
4713 @node C Constraint Interface
4714 @subsection Testing constraints from C
4715 @cindex testing constraints
4716 @cindex constraints, testing
4717
4718 It is occasionally useful to test a constraint from C code rather than
4719 implicitly via the constraint string in a @code{match_operand}. The
4720 generated file @file{tm_p.h} declares a few interfaces for working
4721 with constraints. At present these are defined for all constraints
4722 except @code{g} (which is equivalent to @code{general_operand}).
4723
4724 Some valid constraint names are not valid C identifiers, so there is a
4725 mangling scheme for referring to them from C@. Constraint names that
4726 do not contain angle brackets or underscores are left unchanged.
4727 Underscores are doubled, each @samp{<} is replaced with @samp{_l}, and
4728 each @samp{>} with @samp{_g}. Here are some examples:
4729
4730 @c the @c's prevent double blank lines in the printed manual.
4731 @example
4732 @multitable {Original} {Mangled}
4733 @item @strong{Original} @tab @strong{Mangled} @c
4734 @item @code{x} @tab @code{x} @c
4735 @item @code{P42x} @tab @code{P42x} @c
4736 @item @code{P4_x} @tab @code{P4__x} @c
4737 @item @code{P4>x} @tab @code{P4_gx} @c
4738 @item @code{P4>>} @tab @code{P4_g_g} @c
4739 @item @code{P4_g>} @tab @code{P4__g_g} @c
4740 @end multitable
4741 @end example
4742
4743 Throughout this section, the variable @var{c} is either a constraint
4744 in the abstract sense, or a constant from @code{enum constraint_num};
4745 the variable @var{m} is a mangled constraint name (usually as part of
4746 a larger identifier).
4747
4748 @deftp Enum constraint_num
4749 For each constraint except @code{g}, there is a corresponding
4750 enumeration constant: @samp{CONSTRAINT_} plus the mangled name of the
4751 constraint. Functions that take an @code{enum constraint_num} as an
4752 argument expect one of these constants.
4753 @end deftp
4754
4755 @deftypefun {inline bool} satisfies_constraint_@var{m} (rtx @var{exp})
4756 For each non-register constraint @var{m} except @code{g}, there is
4757 one of these functions; it returns @code{true} if @var{exp} satisfies the
4758 constraint. These functions are only visible if @file{rtl.h} was included
4759 before @file{tm_p.h}.
4760 @end deftypefun
4761
4762 @deftypefun bool constraint_satisfied_p (rtx @var{exp}, enum constraint_num @var{c})
4763 Like the @code{satisfies_constraint_@var{m}} functions, but the
4764 constraint to test is given as an argument, @var{c}. If @var{c}
4765 specifies a register constraint, this function will always return
4766 @code{false}.
4767 @end deftypefun
4768
4769 @deftypefun {enum reg_class} reg_class_for_constraint (enum constraint_num @var{c})
4770 Returns the register class associated with @var{c}. If @var{c} is not
4771 a register constraint, or those registers are not available for the
4772 currently selected subtarget, returns @code{NO_REGS}.
4773 @end deftypefun
4774
4775 Here is an example use of @code{satisfies_constraint_@var{m}}. In
4776 peephole optimizations (@pxref{Peephole Definitions}), operand
4777 constraint strings are ignored, so if there are relevant constraints,
4778 they must be tested in the C condition. In the example, the
4779 optimization is applied if operand 2 does @emph{not} satisfy the
4780 @samp{K} constraint. (This is a simplified version of a peephole
4781 definition from the i386 machine description.)
4782
4783 @smallexample
4784 (define_peephole2
4785 [(match_scratch:SI 3 "r")
4786 (set (match_operand:SI 0 "register_operand" "")
4787 (mult:SI (match_operand:SI 1 "memory_operand" "")
4788 (match_operand:SI 2 "immediate_operand" "")))]
4789
4790 "!satisfies_constraint_K (operands[2])"
4791
4792 [(set (match_dup 3) (match_dup 1))
4793 (set (match_dup 0) (mult:SI (match_dup 3) (match_dup 2)))]
4794
4795 "")
4796 @end smallexample
4797
4798 @node Standard Names
4799 @section Standard Pattern Names For Generation
4800 @cindex standard pattern names
4801 @cindex pattern names
4802 @cindex names, pattern
4803
4804 Here is a table of the instruction names that are meaningful in the RTL
4805 generation pass of the compiler. Giving one of these names to an
4806 instruction pattern tells the RTL generation pass that it can use the
4807 pattern to accomplish a certain task.
4808
4809 @table @asis
4810 @cindex @code{mov@var{m}} instruction pattern
4811 @item @samp{mov@var{m}}
4812 Here @var{m} stands for a two-letter machine mode name, in lowercase.
4813 This instruction pattern moves data with that machine mode from operand
4814 1 to operand 0. For example, @samp{movsi} moves full-word data.
4815
4816 If operand 0 is a @code{subreg} with mode @var{m} of a register whose
4817 own mode is wider than @var{m}, the effect of this instruction is
4818 to store the specified value in the part of the register that corresponds
4819 to mode @var{m}. Bits outside of @var{m}, but which are within the
4820 same target word as the @code{subreg} are undefined. Bits which are
4821 outside the target word are left unchanged.
4822
4823 This class of patterns is special in several ways. First of all, each
4824 of these names up to and including full word size @emph{must} be defined,
4825 because there is no other way to copy a datum from one place to another.
4826 If there are patterns accepting operands in larger modes,
4827 @samp{mov@var{m}} must be defined for integer modes of those sizes.
4828
4829 Second, these patterns are not used solely in the RTL generation pass.
4830 Even the reload pass can generate move insns to copy values from stack
4831 slots into temporary registers. When it does so, one of the operands is
4832 a hard register and the other is an operand that can need to be reloaded
4833 into a register.
4834
4835 @findex force_reg
4836 Therefore, when given such a pair of operands, the pattern must generate
4837 RTL which needs no reloading and needs no temporary registers---no
4838 registers other than the operands. For example, if you support the
4839 pattern with a @code{define_expand}, then in such a case the
4840 @code{define_expand} mustn't call @code{force_reg} or any other such
4841 function which might generate new pseudo registers.
4842
4843 This requirement exists even for subword modes on a RISC machine where
4844 fetching those modes from memory normally requires several insns and
4845 some temporary registers.
4846
4847 @findex change_address
4848 During reload a memory reference with an invalid address may be passed
4849 as an operand. Such an address will be replaced with a valid address
4850 later in the reload pass. In this case, nothing may be done with the
4851 address except to use it as it stands. If it is copied, it will not be
4852 replaced with a valid address. No attempt should be made to make such
4853 an address into a valid address and no routine (such as
4854 @code{change_address}) that will do so may be called. Note that
4855 @code{general_operand} will fail when applied to such an address.
4856
4857 @findex reload_in_progress
4858 The global variable @code{reload_in_progress} (which must be explicitly
4859 declared if required) can be used to determine whether such special
4860 handling is required.
4861
4862 The variety of operands that have reloads depends on the rest of the
4863 machine description, but typically on a RISC machine these can only be
4864 pseudo registers that did not get hard registers, while on other
4865 machines explicit memory references will get optional reloads.
4866
4867 If a scratch register is required to move an object to or from memory,
4868 it can be allocated using @code{gen_reg_rtx} prior to life analysis.
4869
4870 If there are cases which need scratch registers during or after reload,
4871 you must provide an appropriate secondary_reload target hook.
4872
4873 @findex can_create_pseudo_p
4874 The macro @code{can_create_pseudo_p} can be used to determine if it
4875 is unsafe to create new pseudo registers. If this variable is nonzero, then
4876 it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo.
4877
4878 The constraints on a @samp{mov@var{m}} must permit moving any hard
4879 register to any other hard register provided that
4880 @code{TARGET_HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and
4881 @code{TARGET_REGISTER_MOVE_COST} applied to their classes returns a value
4882 of 2.
4883
4884 It is obligatory to support floating point @samp{mov@var{m}}
4885 instructions into and out of any registers that can hold fixed point
4886 values, because unions and structures (which have modes @code{SImode} or
4887 @code{DImode}) can be in those registers and they may have floating
4888 point members.
4889
4890 There may also be a need to support fixed point @samp{mov@var{m}}
4891 instructions in and out of floating point registers. Unfortunately, I
4892 have forgotten why this was so, and I don't know whether it is still
4893 true. If @code{TARGET_HARD_REGNO_MODE_OK} rejects fixed point values in
4894 floating point registers, then the constraints of the fixed point
4895 @samp{mov@var{m}} instructions must be designed to avoid ever trying to
4896 reload into a floating point register.
4897
4898 @cindex @code{reload_in} instruction pattern
4899 @cindex @code{reload_out} instruction pattern
4900 @item @samp{reload_in@var{m}}
4901 @itemx @samp{reload_out@var{m}}
4902 These named patterns have been obsoleted by the target hook
4903 @code{secondary_reload}.
4904
4905 Like @samp{mov@var{m}}, but used when a scratch register is required to
4906 move between operand 0 and operand 1. Operand 2 describes the scratch
4907 register. See the discussion of the @code{SECONDARY_RELOAD_CLASS}
4908 macro in @pxref{Register Classes}.
4909
4910 There are special restrictions on the form of the @code{match_operand}s
4911 used in these patterns. First, only the predicate for the reload
4912 operand is examined, i.e., @code{reload_in} examines operand 1, but not
4913 the predicates for operand 0 or 2. Second, there may be only one
4914 alternative in the constraints. Third, only a single register class
4915 letter may be used for the constraint; subsequent constraint letters
4916 are ignored. As a special exception, an empty constraint string
4917 matches the @code{ALL_REGS} register class. This may relieve ports
4918 of the burden of defining an @code{ALL_REGS} constraint letter just
4919 for these patterns.
4920
4921 @cindex @code{movstrict@var{m}} instruction pattern
4922 @item @samp{movstrict@var{m}}
4923 Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg}
4924 with mode @var{m} of a register whose natural mode is wider,
4925 the @samp{movstrict@var{m}} instruction is guaranteed not to alter
4926 any of the register except the part which belongs to mode @var{m}.
4927
4928 @cindex @code{movmisalign@var{m}} instruction pattern
4929 @item @samp{movmisalign@var{m}}
4930 This variant of a move pattern is designed to load or store a value
4931 from a memory address that is not naturally aligned for its mode.
4932 For a store, the memory will be in operand 0; for a load, the memory
4933 will be in operand 1. The other operand is guaranteed not to be a
4934 memory, so that it's easy to tell whether this is a load or store.
4935
4936 This pattern is used by the autovectorizer, and when expanding a
4937 @code{MISALIGNED_INDIRECT_REF} expression.
4938
4939 @cindex @code{load_multiple} instruction pattern
4940 @item @samp{load_multiple}
4941 Load several consecutive memory locations into consecutive registers.
4942 Operand 0 is the first of the consecutive registers, operand 1
4943 is the first memory location, and operand 2 is a constant: the
4944 number of consecutive registers.
4945
4946 Define this only if the target machine really has such an instruction;
4947 do not define this if the most efficient way of loading consecutive
4948 registers from memory is to do them one at a time.
4949
4950 On some machines, there are restrictions as to which consecutive
4951 registers can be stored into memory, such as particular starting or
4952 ending register numbers or only a range of valid counts. For those
4953 machines, use a @code{define_expand} (@pxref{Expander Definitions})
4954 and make the pattern fail if the restrictions are not met.
4955
4956 Write the generated insn as a @code{parallel} with elements being a
4957 @code{set} of one register from the appropriate memory location (you may
4958 also need @code{use} or @code{clobber} elements). Use a
4959 @code{match_parallel} (@pxref{RTL Template}) to recognize the insn. See
4960 @file{rs6000.md} for examples of the use of this insn pattern.
4961
4962 @cindex @samp{store_multiple} instruction pattern
4963 @item @samp{store_multiple}
4964 Similar to @samp{load_multiple}, but store several consecutive registers
4965 into consecutive memory locations. Operand 0 is the first of the
4966 consecutive memory locations, operand 1 is the first register, and
4967 operand 2 is a constant: the number of consecutive registers.
4968
4969 @cindex @code{vec_load_lanes@var{m}@var{n}} instruction pattern
4970 @item @samp{vec_load_lanes@var{m}@var{n}}
4971 Perform an interleaved load of several vectors from memory operand 1
4972 into register operand 0. Both operands have mode @var{m}. The register
4973 operand is viewed as holding consecutive vectors of mode @var{n},
4974 while the memory operand is a flat array that contains the same number
4975 of elements. The operation is equivalent to:
4976
4977 @smallexample
4978 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
4979 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
4980 for (i = 0; i < c; i++)
4981 operand0[i][j] = operand1[j * c + i];
4982 @end smallexample
4983
4984 For example, @samp{vec_load_lanestiv4hi} loads 8 16-bit values
4985 from memory into a register of mode @samp{TI}@. The register
4986 contains two consecutive vectors of mode @samp{V4HI}@.
4987
4988 This pattern can only be used if:
4989 @smallexample
4990 TARGET_ARRAY_MODE_SUPPORTED_P (@var{n}, @var{c})
4991 @end smallexample
4992 is true. GCC assumes that, if a target supports this kind of
4993 instruction for some mode @var{n}, it also supports unaligned
4994 loads for vectors of mode @var{n}.
4995
4996 This pattern is not allowed to @code{FAIL}.
4997
4998 @cindex @code{vec_mask_load_lanes@var{m}@var{n}} instruction pattern
4999 @item @samp{vec_mask_load_lanes@var{m}@var{n}}
5000 Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional
5001 mask operand (operand 2) that specifies which elements of the destination
5002 vectors should be loaded. Other elements of the destination vectors are
5003 taken from operand 3, which is an else operand similar to the one in
5004 @code{maskload}.
5005 The operation is equivalent to:
5006
5007 @smallexample
5008 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
5009 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
5010 if (operand2[j])
5011 for (i = 0; i < c; i++)
5012 operand0[i][j] = operand1[j * c + i];
5013 else
5014 for (i = 0; i < c; i++)
5015 operand0[i][j] = operand3[j];
5016 @end smallexample
5017
5018 This pattern is not allowed to @code{FAIL}.
5019
5020 @cindex @code{vec_mask_len_load_lanes@var{m}@var{n}} instruction pattern
5021 @item @samp{vec_mask_len_load_lanes@var{m}@var{n}}
5022 Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional
5023 mask operand (operand 2), length operand (operand 4) as well as bias operand
5024 (operand 5) that specifies which elements of the destination vectors should be
5025 loaded. Other elements of the destination vectors are taken from operand 3,
5026 which is an else operand similar to the one in @code{maskload}.
5027 The operation is equivalent to:
5028
5029 @smallexample
5030 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
5031 for (j = 0; j < operand4 + operand5; j++)
5032 for (i = 0; i < c; i++)
5033 if (operand2[j])
5034 operand0[i][j] = operand1[j * c + i];
5035 else
5036 operand0[i][j] = operand3[j];
5037 @end smallexample
5038
5039 This pattern is not allowed to @code{FAIL}.
5040
5041 @cindex @code{vec_store_lanes@var{m}@var{n}} instruction pattern
5042 @item @samp{vec_store_lanes@var{m}@var{n}}
5043 Equivalent to @samp{vec_load_lanes@var{m}@var{n}}, with the memory
5044 and register operands reversed. That is, the instruction is
5045 equivalent to:
5046
5047 @smallexample
5048 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
5049 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
5050 for (i = 0; i < c; i++)
5051 operand0[j * c + i] = operand1[i][j];
5052 @end smallexample
5053
5054 for a memory operand 0 and register operand 1.
5055
5056 This pattern is not allowed to @code{FAIL}.
5057
5058 @cindex @code{vec_mask_store_lanes@var{m}@var{n}} instruction pattern
5059 @item @samp{vec_mask_store_lanes@var{m}@var{n}}
5060 Like @samp{vec_store_lanes@var{m}@var{n}}, but takes an additional
5061 mask operand (operand 2) that specifies which elements of the source
5062 vectors should be stored. The operation is equivalent to:
5063
5064 @smallexample
5065 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
5066 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
5067 if (operand2[j])
5068 for (i = 0; i < c; i++)
5069 operand0[j * c + i] = operand1[i][j];
5070 @end smallexample
5071
5072 This pattern is not allowed to @code{FAIL}.
5073
5074 @cindex @code{vec_mask_len_store_lanes@var{m}@var{n}} instruction pattern
5075 @item @samp{vec_mask_len_store_lanes@var{m}@var{n}}
5076 Like @samp{vec_store_lanes@var{m}@var{n}}, but takes an additional
5077 mask operand (operand 2), length operand (operand 3) as well as bias operand (operand 4)
5078 that specifies which elements of the source vectors should be stored.
5079 The operation is equivalent to:
5080
5081 @smallexample
5082 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
5083 for (j = 0; j < operand3 + operand4; j++)
5084 if (operand2[j])
5085 for (i = 0; i < c; i++)
5086 operand0[j * c + i] = operand1[i][j];
5087 @end smallexample
5088
5089 This pattern is not allowed to @code{FAIL}.
5090
5091 @cindex @code{gather_load@var{m}@var{n}} instruction pattern
5092 @item @samp{gather_load@var{m}@var{n}}
5093 Load several separate memory locations into a vector of mode @var{m}.
5094 Operand 1 is a scalar base address and operand 2 is a vector of mode @var{n}
5095 containing offsets from that base. Operand 0 is a destination vector with
5096 the same number of elements as @var{n}. For each element index @var{i}:
5097
5098 @itemize @bullet
5099 @item
5100 extend the offset element @var{i} to address width, using zero
5101 extension if operand 3 is 1 and sign extension if operand 3 is zero;
5102 @item
5103 multiply the extended offset by operand 4;
5104 @item
5105 add the result to the base; and
5106 @item
5107 load the value at that address into element @var{i} of operand 0.
5108 @end itemize
5109
5110 The value of operand 3 does not matter if the offsets are already
5111 address width.
5112
5113 @cindex @code{mask_gather_load@var{m}@var{n}} instruction pattern
5114 @item @samp{mask_gather_load@var{m}@var{n}}
5115 Like @samp{gather_load@var{m}@var{n}}, but takes an extra mask operand as
5116 operand 5.
5117 Other elements of the destination vectors are taken from operand 6,
5118 which is an else operand similar to the one in @code{maskload}.
5119 Bit @var{i} of the mask is set if element @var{i}
5120 of the result should be loaded from memory and clear if element @var{i}
5121 of the result should be set to operand 6.
5122
5123 @cindex @code{mask_len_gather_load@var{m}@var{n}} instruction pattern
5124 @item @samp{mask_len_gather_load@var{m}@var{n}}
5125 Like @samp{gather_load@var{m}@var{n}}, but takes an extra mask operand
5126 (operand 5) and an else operand (operand 6) as well as a len operand
5127 (operand 7) and a bias operand (operand 8).
5128
5129 Similar to mask_len_load the instruction loads at
5130 most (operand 7 + operand 8) elements from memory.
5131 Bit @var{i} of the mask is set if element @var{i} of the result should
5132 be loaded from memory and clear if element @var{i} of the result should
5133 be set to element @var{i} of operand 6.
5134 Mask elements @var{i} with @var{i} > (operand 7 + operand 8) are ignored.
5135
5136 @cindex @code{mask_len_strided_load@var{m}} instruction pattern
5137 @item @samp{mask_len_strided_load@var{m}}
5138 Load several separate memory locations into a destination vector of mode @var{m}.
5139 Operand 0 is a destination vector of mode @var{m}.
5140 Operand 1 is a scalar base address and operand 2 is a scalar stride of Pmode.
5141 operand 3 is mask operand, operand 4 is length operand and operand 5 is bias operand.
5142 The instruction can be seen as a special case of @code{mask_len_gather_load@var{m}@var{n}}
5143 with an offset vector that is a @code{vec_series} with zero as base and operand 2 as step.
5144 For each element the load address is operand 1 + @var{i} * operand 2.
5145 Similar to mask_len_load, the instruction loads at most (operand 4 + operand 5) elements from memory.
5146 Element @var{i} of the mask (operand 3) is set if element @var{i} of the result should
5147 be loaded from memory and clear if element @var{i} of the result should be zero.
5148 Mask elements @var{i} with @var{i} > (operand 4 + operand 5) are ignored.
5149
5150 @cindex @code{scatter_store@var{m}@var{n}} instruction pattern
5151 @item @samp{scatter_store@var{m}@var{n}}
5152 Store a vector of mode @var{m} into several distinct memory locations.
5153 Operand 0 is a scalar base address and operand 1 is a vector of mode
5154 @var{n} containing offsets from that base. Operand 4 is the vector of
5155 values that should be stored, which has the same number of elements as
5156 @var{n}. For each element index @var{i}:
5157
5158 @itemize @bullet
5159 @item
5160 extend the offset element @var{i} to address width, using zero
5161 extension if operand 2 is 1 and sign extension if operand 2 is zero;
5162 @item
5163 multiply the extended offset by operand 3;
5164 @item
5165 add the result to the base; and
5166 @item
5167 store element @var{i} of operand 4 to that address.
5168 @end itemize
5169
5170 The value of operand 2 does not matter if the offsets are already
5171 address width.
5172
5173 @cindex @code{mask_scatter_store@var{m}@var{n}} instruction pattern
5174 @item @samp{mask_scatter_store@var{m}@var{n}}
5175 Like @samp{scatter_store@var{m}@var{n}}, but takes an extra mask operand as
5176 operand 5. Bit @var{i} of the mask is set if element @var{i}
5177 of the result should be stored to memory.
5178
5179 @cindex @code{mask_len_scatter_store@var{m}@var{n}} instruction pattern
5180 @item @samp{mask_len_scatter_store@var{m}@var{n}}
5181 Like @samp{scatter_store@var{m}@var{n}}, but takes an extra mask operand (operand 5),
5182 a len operand (operand 6) as well as a bias operand (operand 7). The instruction stores
5183 at most (operand 6 + operand 7) elements of (operand 4) to memory.
5184 Bit @var{i} of the mask is set if element @var{i} of (operand 4) should be stored.
5185 Mask elements @var{i} with @var{i} > (operand 6 + operand 7) are ignored.
5186
5187 @cindex @code{mask_len_strided_store@var{m}} instruction pattern
5188 @item @samp{mask_len_strided_store@var{m}}
5189 Store a vector of mode m into several distinct memory locations.
5190 Operand 0 is a scalar base address and operand 1 is scalar stride of Pmode.
5191 Operand 2 is the vector of values that should be stored, which is of mode @var{m}.
5192 operand 3 is mask operand, operand 4 is length operand and operand 5 is bias operand.
5193 The instruction can be seen as a special case of @code{mask_len_scatter_store@var{m}@var{n}}
5194 with an offset vector that is a @code{vec_series} with zero as base and operand 1 as step.
5195 For each element the store address is operand 0 + @var{i} * operand 1.
5196 Similar to mask_len_store, the instruction stores at most (operand 4 + operand 5) elements of
5197 mask (operand 3) to memory. Element @var{i} of the mask is set if element @var{i} of (operand 3)
5198 should be stored. Mask elements @var{i} with @var{i} > (operand 4 + operand 5) are ignored.
5199
5200 @cindex @code{vec_set@var{m}} instruction pattern
5201 @item @samp{vec_set@var{m}}
5202 Set given field in the vector value. Operand 0 is the vector to modify,
5203 operand 1 is new value of field and operand 2 specify the field index.
5204
5205 This pattern is not allowed to @code{FAIL}.
5206
5207 @cindex @code{vec_extract@var{m}@var{n}} instruction pattern
5208 @item @samp{vec_extract@var{m}@var{n}}
5209 Extract given field from the vector value. Operand 1 is the vector, operand 2
5210 specify field index and operand 0 place to store value into. The
5211 @var{n} mode is the mode of the field or vector of fields that should be
5212 extracted, should be either element mode of the vector mode @var{m}, or
5213 a vector mode with the same element mode and smaller number of elements.
5214 If @var{n} is a vector mode the index is counted in multiples of
5215 mode @var{n}.
5216
5217 This pattern is not allowed to @code{FAIL}.
5218
5219 @cindex @code{vec_init@var{m}@var{n}} instruction pattern
5220 @item @samp{vec_init@var{m}@var{n}}
5221 Initialize the vector to given values. Operand 0 is the vector to initialize
5222 and operand 1 is parallel containing values for individual fields. The
5223 @var{n} mode is the mode of the elements, should be either element mode of
5224 the vector mode @var{m}, or a vector mode with the same element mode and
5225 smaller number of elements.
5226
5227 @cindex @code{vec_duplicate@var{m}} instruction pattern
5228 @item @samp{vec_duplicate@var{m}}
5229 Initialize vector output operand 0 so that each element has the value given
5230 by scalar input operand 1. The vector has mode @var{m} and the scalar has
5231 the mode appropriate for one element of @var{m}.
5232
5233 This pattern only handles duplicates of non-constant inputs. Constant
5234 vectors go through the @code{mov@var{m}} pattern instead.
5235
5236 This pattern is not allowed to @code{FAIL}.
5237
5238 @cindex @code{vec_series@var{m}} instruction pattern
5239 @item @samp{vec_series@var{m}}
5240 Initialize vector output operand 0 so that element @var{i} is equal to
5241 operand 1 plus @var{i} times operand 2. In other words, create a linear
5242 series whose base value is operand 1 and whose step is operand 2.
5243
5244 The vector output has mode @var{m} and the scalar inputs have the mode
5245 appropriate for one element of @var{m}. This pattern is not used for
5246 floating-point vectors, in order to avoid having to specify the
5247 rounding behavior for @var{i} > 1.
5248
5249 This pattern is not allowed to @code{FAIL}.
5250
5251 @cindex @code{while_ult@var{m}@var{n}} instruction pattern
5252 @item @code{while_ult@var{m}@var{n}}
5253 Set operand 0 to a mask that is true while incrementing operand 1
5254 gives a value that is less than operand 2, for a vector length up to operand 3.
5255 Operand 0 has mode @var{n} and operands 1 and 2 are scalar integers of mode
5256 @var{m}. Operand 3 should be omitted when @var{n} is a vector mode, and
5257 a @code{CONST_INT} otherwise. The operation for vector modes is equivalent to:
5258
5259 @smallexample
5260 operand0[0] = operand1 < operand2;
5261 for (i = 1; i < GET_MODE_NUNITS (@var{n}); i++)
5262 operand0[i] = operand0[i - 1] && (operand1 + i < operand2);
5263 @end smallexample
5264
5265 And for non-vector modes the operation is equivalent to:
5266
5267 @smallexample
5268 operand0[0] = operand1 < operand2;
5269 for (i = 1; i < operand3; i++)
5270 operand0[i] = operand0[i - 1] && (operand1 + i < operand2);
5271 @end smallexample
5272
5273 @cindex @code{select_vl@var{m}} instruction pattern
5274 @item @code{select_vl@var{m}}
5275 Set operand 0 to the number of scalar iterations that should be handled
5276 by one iteration of a vector loop. Operand 1 is the total number of
5277 scalar iterations that the loop needs to process and operand 2 is a
5278 maximum bound on the result (also known as the maximum ``vectorization
5279 factor'').
5280
5281 The maximum value of operand 0 is given by:
5282 @smallexample
5283 operand0 = MIN (operand1, operand2)
5284 @end smallexample
5285 However, targets might choose a lower value than this, based on
5286 target-specific criteria. Each iteration of the vector loop might
5287 therefore process a different number of scalar iterations, which in turn
5288 means that induction variables will have a variable step. Because of
5289 this, it is generally not useful to define this instruction if it will
5290 always calculate the maximum value.
5291
5292 This optab is only useful on targets that implement @samp{len_load_@var{m}}
5293 and/or @samp{len_store_@var{m}}.
5294
5295 @cindex @code{check_raw_ptrs@var{m}} instruction pattern
5296 @item @samp{check_raw_ptrs@var{m}}
5297 Check whether, given two pointers @var{a} and @var{b} and a length @var{len},
5298 a write of @var{len} bytes at @var{a} followed by a read of @var{len} bytes
5299 at @var{b} can be split into interleaved byte accesses
5300 @samp{@var{a}[0], @var{b}[0], @var{a}[1], @var{b}[1], @dots{}}
5301 without affecting the dependencies between the bytes. Set operand 0
5302 to true if the split is possible and false otherwise.
5303
5304 Operands 1, 2 and 3 provide the values of @var{a}, @var{b} and @var{len}
5305 respectively. Operand 4 is a constant integer that provides the known
5306 common alignment of @var{a} and @var{b}. All inputs have mode @var{m}.
5307
5308 This split is possible if:
5309
5310 @smallexample
5311 @var{a} == @var{b} || @var{a} + @var{len} <= @var{b} || @var{b} + @var{len} <= @var{a}
5312 @end smallexample
5313
5314 You should only define this pattern if the target has a way of accelerating
5315 the test without having to do the individual comparisons.
5316
5317 @cindex @code{check_war_ptrs@var{m}} instruction pattern
5318 @item @samp{check_war_ptrs@var{m}}
5319 Like @samp{check_raw_ptrs@var{m}}, but with the read and write swapped round.
5320 The split is possible in this case if:
5321
5322 @smallexample
5323 @var{b} <= @var{a} || @var{a} + @var{len} <= @var{b}
5324 @end smallexample
5325
5326 @cindex @code{vec_cmp@var{m}@var{n}} instruction pattern
5327 @item @samp{vec_cmp@var{m}@var{n}}
5328 Output a vector comparison. Operand 0 of mode @var{n} is the destination for
5329 predicate in operand 1 which is a signed vector comparison with operands of
5330 mode @var{m} in operands 2 and 3. Predicate is computed by element-wise
5331 evaluation of the vector comparison with a truth value of all-ones and a false
5332 value of all-zeros.
5333
5334 @cindex @code{vec_cmpu@var{m}@var{n}} instruction pattern
5335 @item @samp{vec_cmpu@var{m}@var{n}}
5336 Similar to @code{vec_cmp@var{m}@var{n}} but perform unsigned vector comparison.
5337
5338 @cindex @code{vec_cmpeq@var{m}@var{n}} instruction pattern
5339 @item @samp{vec_cmpeq@var{m}@var{n}}
5340 Similar to @code{vec_cmp@var{m}@var{n}} but perform equality or non-equality
5341 vector comparison only. If @code{vec_cmp@var{m}@var{n}}
5342 or @code{vec_cmpu@var{m}@var{n}} instruction pattern is supported,
5343 it will be preferred over @code{vec_cmpeq@var{m}@var{n}}, so there is
5344 no need to define this instruction pattern if the others are supported.
5345
5346 @cindex @code{vcond_mask_@var{m}@var{n}} instruction pattern
5347 @item @samp{vcond_mask_@var{m}@var{n}}
5348 Output a conditional vector move. Operand 0 is the destination to
5349 receive a combination of operand 1 and operand 2, depending on the
5350 mask in operand 3. Operands 0, 1, and 2 have mode @var{m} while
5351 operand 3 has mode @var{n}.
5352
5353 Suppose that @var{m} has @var{e} elements. There are then two
5354 supported forms of @var{n}. The first form is an integer or
5355 boolean vector that also has @var{e} elements. In this case, each
5356 element is -1 or 0, with -1 selecting elements from operand 1 and
5357 0 selecting elements from operand 2. The second supported form
5358 of @var{n} is a scalar integer that has at least @var{e} bits.
5359 A set bit then selects from operand 1 and a clear bit selects
5360 from operand 2. Bits @var{e} and above have no effect.
5361
5362 Subject to those restrictions, the behavior is equivalent to:
5363
5364 @smallexample
5365 for (i = 0; i < @var{e}; i++)
5366 op0[i] = op3[i] ? op1[i] : op2[i];
5367 @end smallexample
5368
5369 @cindex @code{vcond_mask_len_@var{m}@var{n}} instruction pattern
5370 @item @samp{vcond_mask_len_@var{m}@var{n}}
5371 Set each element of operand 0 to the corresponding element of operand 2
5372 or operand 3. Choose operand 2 if both the element index is less than
5373 operand 4 plus operand 5 and the corresponding element of operand 1
5374 is nonzero:
5375
5376 @smallexample
5377 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
5378 op0[i] = i < op4 + op5 && op1[i] ? op2[i] : op3[i];
5379 @end smallexample
5380
5381 Operands 0, 2 and 3 have mode @var{m}. Operand 1 has mode @var{n}.
5382 Operands 4 and 5 have a target-dependent scalar integer mode.
5383
5384 @cindex @code{maskload@var{m}@var{n}} instruction pattern
5385 @item @samp{maskload@var{m}@var{n}}
5386 Perform a masked load of vector from memory operand 1 of mode @var{m}
5387 into register operand 0. The mask is provided in register operand 2 of
5388 mode @var{n}. Operand 3 (the ``else value'') is of mode @var{m} and
5389 specifies which value is loaded when the mask is unset.
5390 The predicate of operand 3 must only accept the else values that the target
5391 actually supports. Currently three values are attempted, zero, -1, and
5392 undefined. GCC handles an else value of zero more efficiently than -1 or
5393 undefined.
5394
5395 This pattern is not allowed to @code{FAIL}.
5396
5397 @cindex @code{maskstore@var{m}@var{n}} instruction pattern
5398 @item @samp{maskstore@var{m}@var{n}}
5399 Perform a masked store of vector from register operand 1 of mode @var{m}
5400 into memory operand 0. Mask is provided in register operand 2 of
5401 mode @var{n}.
5402
5403 This pattern is not allowed to @code{FAIL}.
5404
5405 @cindex @code{len_load_@var{m}} instruction pattern
5406 @item @samp{len_load_@var{m}}
5407 Load (operand 2 + operand 3) elements from memory operand 1
5408 into vector register operand 0, setting the other elements of
5409 operand 0 to undefined values. Operands 0 and 1 have mode @var{m},
5410 which must be a vector mode. Operand 2 has whichever integer mode the
5411 target prefers. Operand 3 conceptually has mode @code{QI}.
5412
5413 Operand 2 can be a variable or a constant amount. Operand 3 specifies a
5414 constant bias: it is either a constant 0 or a constant -1. The predicate on
5415 operand 3 must only accept the bias values that the target actually supports.
5416 GCC handles a bias of 0 more efficiently than a bias of -1.
5417
5418 If (operand 2 + operand 3) exceeds the number of elements in mode
5419 @var{m}, the behavior is undefined.
5420
5421 If the target prefers the length to be measured in bytes rather than
5422 elements, it should only implement this pattern for vectors of @code{QI}
5423 elements.
5424
5425 This pattern is not allowed to @code{FAIL}.
5426
5427 @cindex @code{len_store_@var{m}} instruction pattern
5428 @item @samp{len_store_@var{m}}
5429 Store (operand 2 + operand 3) vector elements from vector register operand 1
5430 into memory operand 0, leaving the other elements of
5431 operand 0 unchanged. Operands 0 and 1 have mode @var{m}, which must be
5432 a vector mode. Operand 2 has whichever integer mode the target prefers.
5433 Operand 3 conceptually has mode @code{QI}.
5434
5435 Operand 2 can be a variable or a constant amount. Operand 3 specifies a
5436 constant bias: it is either a constant 0 or a constant -1. The predicate on
5437 operand 3 must only accept the bias values that the target actually supports.
5438 GCC handles a bias of 0 more efficiently than a bias of -1.
5439
5440 If (operand 2 + operand 3) exceeds the number of elements in mode
5441 @var{m}, the behavior is undefined.
5442
5443 If the target prefers the length to be measured in bytes
5444 rather than elements, it should only implement this pattern for vectors
5445 of @code{QI} elements.
5446
5447 This pattern is not allowed to @code{FAIL}.
5448
5449 @cindex @code{mask_len_load@var{m}@var{n}} instruction pattern
5450 @item @samp{mask_len_load@var{m}@var{n}}
5451 Perform a masked load from the memory location pointed to by operand 1
5452 into register operand 0. (operand 3 + operand 4) elements are loaded from
5453 memory and other elements in operand 0 are set to undefined values.
5454 This is a combination of len_load and maskload.
5455 Operands 0 and 1 have mode @var{m}, which must be a vector mode. Operand 3
5456 has whichever integer mode the target prefers. A mask is specified in
5457 operand 2 which must be of type @var{n}. The mask has lower precedence than
5458 the length and is itself subject to length masking,
5459 i.e. only mask indices < (operand 4 + operand 5) are used.
5460 Operand 3 is an else operand similar to the one in @code{maskload}.
5461 Operand 4 conceptually has mode @code{QI}.
5462
5463 Operand 4 can be a variable or a constant amount. Operand 5 specifies a
5464 constant bias: it is either a constant 0 or a constant -1. The predicate on
5465 operand 5 must only accept the bias values that the target actually supports.
5466 GCC handles a bias of 0 more efficiently than a bias of -1.
5467
5468 If (operand 4 + operand 5) exceeds the number of elements in mode
5469 @var{m}, the behavior is undefined.
5470
5471 If the target prefers the length to be measured in bytes
5472 rather than elements, it should only implement this pattern for vectors
5473 of @code{QI} elements.
5474
5475 This pattern is not allowed to @code{FAIL}.
5476
5477 @cindex @code{mask_len_store@var{m}@var{n}} instruction pattern
5478 @item @samp{mask_len_store@var{m}@var{n}}
5479 Perform a masked store from vector register operand 1 into memory operand 0.
5480 (operand 3 + operand 4) elements are stored to memory
5481 and leave the other elements of operand 0 unchanged.
5482 This is a combination of len_store and maskstore.
5483 Operands 0 and 1 have mode @var{m}, which must be a vector mode. Operand 3 has whichever
5484 integer mode the target prefers. A mask is specified in operand 2 which must be
5485 of type @var{n}. The mask has lower precedence than the length and is itself subject to
5486 length masking, i.e. only mask indices < (operand 3 + operand 4) are used.
5487 Operand 4 conceptually has mode @code{QI}.
5488
5489 Operand 2 can be a variable or a constant amount. Operand 3 specifies a
5490 constant bias: it is either a constant 0 or a constant -1. The predicate on
5491 operand 4 must only accept the bias values that the target actually supports.
5492 GCC handles a bias of 0 more efficiently than a bias of -1.
5493
5494 If (operand 2 + operand 4) exceeds the number of elements in mode
5495 @var{m}, the behavior is undefined.
5496
5497 If the target prefers the length to be measured in bytes
5498 rather than elements, it should only implement this pattern for vectors
5499 of @code{QI} elements.
5500
5501 This pattern is not allowed to @code{FAIL}.
5502
5503 @cindex @code{vec_perm@var{m}} instruction pattern
5504 @item @samp{vec_perm@var{m}}
5505 Output a (variable) vector permutation. Operand 0 is the destination
5506 to receive elements from operand 1 and operand 2, which are of mode
5507 @var{m}. Operand 3 is the @dfn{selector}. It is an integral mode
5508 vector of the same width and number of elements as mode @var{m}.
5509
5510 The input elements are numbered from 0 in operand 1 through
5511 @math{2*@var{N}-1} in operand 2. The elements of the selector must
5512 be computed modulo @math{2*@var{N}}. Note that if
5513 @code{rtx_equal_p(operand1, operand2)}, this can be implemented
5514 with just operand 1 and selector elements modulo @var{N}.
5515
5516 In order to make things easy for a number of targets, if there is no
5517 @samp{vec_perm} pattern for mode @var{m}, but there is for mode @var{q}
5518 where @var{q} is a vector of @code{QImode} of the same width as @var{m},
5519 the middle-end will lower the mode @var{m} @code{VEC_PERM_EXPR} to
5520 mode @var{q}.
5521
5522 See also @code{TARGET_VECTORIZER_VEC_PERM_CONST}, which performs
5523 the analogous operation for constant selectors.
5524
5525 @cindex @code{push@var{m}1} instruction pattern
5526 @item @samp{push@var{m}1}
5527 Output a push instruction. Operand 0 is value to push. Used only when
5528 @code{PUSH_ROUNDING} is defined. For historical reason, this pattern may be
5529 missing and in such case an @code{mov} expander is used instead, with a
5530 @code{MEM} expression forming the push operation. The @code{mov} expander
5531 method is deprecated.
5532
5533 @cindex @code{add@var{m}3} instruction pattern
5534 @item @samp{add@var{m}3}
5535 Add operand 2 and operand 1, storing the result in operand 0. All operands
5536 must have mode @var{m}. This can be used even on two-address machines, by
5537 means of constraints requiring operands 1 and 0 to be the same location.
5538
5539 @cindex @code{ssadd@var{m}3} instruction pattern
5540 @cindex @code{usadd@var{m}3} instruction pattern
5541 @cindex @code{sub@var{m}3} instruction pattern
5542 @cindex @code{sssub@var{m}3} instruction pattern
5543 @cindex @code{ussub@var{m}3} instruction pattern
5544 @cindex @code{mul@var{m}3} instruction pattern
5545 @cindex @code{ssmul@var{m}3} instruction pattern
5546 @cindex @code{usmul@var{m}3} instruction pattern
5547 @cindex @code{div@var{m}3} instruction pattern
5548 @cindex @code{ssdiv@var{m}3} instruction pattern
5549 @cindex @code{udiv@var{m}3} instruction pattern
5550 @cindex @code{usdiv@var{m}3} instruction pattern
5551 @cindex @code{mod@var{m}3} instruction pattern
5552 @cindex @code{umod@var{m}3} instruction pattern
5553 @cindex @code{umin@var{m}3} instruction pattern
5554 @cindex @code{umax@var{m}3} instruction pattern
5555 @cindex @code{and@var{m}3} instruction pattern
5556 @cindex @code{ior@var{m}3} instruction pattern
5557 @cindex @code{xor@var{m}3} instruction pattern
5558 @item @samp{ssadd@var{m}3}, @samp{usadd@var{m}3}
5559 @itemx @samp{sub@var{m}3}, @samp{sssub@var{m}3}, @samp{ussub@var{m}3}
5560 @itemx @samp{mul@var{m}3}, @samp{ssmul@var{m}3}, @samp{usmul@var{m}3}
5561 @itemx @samp{div@var{m}3}, @samp{ssdiv@var{m}3}
5562 @itemx @samp{udiv@var{m}3}, @samp{usdiv@var{m}3}
5563 @itemx @samp{mod@var{m}3}, @samp{umod@var{m}3}
5564 @itemx @samp{umin@var{m}3}, @samp{umax@var{m}3}
5565 @itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3}
5566 Similar, for other arithmetic operations.
5567
5568 @cindex @code{ustrunc@var{m}@var{n}2} instruction pattern
5569 @item @samp{ustrunc@var{m}@var{n}2}
5570 Truncate the operand 1, and storing the result in operand 0. There will
5571 be saturation during the trunction. The result will be saturated to the
5572 maximal value of operand 0 type if there is overflow when truncation. The
5573 operand 1 must have mode @var{n}, and the operand 0 must have mode @var{m}.
5574 Both scalar and vector integer modes are allowed.
5575
5576 @cindex @code{sstrunc@var{m}@var{n}2} instruction pattern
5577 @item @samp{sstrunc@var{m}@var{n}2}
5578 Similar but for signed.
5579
5580 @cindex @code{andn@var{m}3} instruction pattern
5581 @item @samp{andn@var{m}3}
5582 Like @code{and@var{m}3}, but it uses bitwise-complement of operand 2
5583 rather than operand 2 itself.
5584
5585 @cindex @code{iorn@var{m}3} instruction pattern
5586 @item @samp{iorn@var{m}3}
5587 Like @code{ior@var{m}3}, but it uses bitwise-complement of operand 2
5588 rather than operand 2 itself.
5589
5590 @cindex @code{addv@var{m}4} instruction pattern
5591 @item @samp{addv@var{m}4}
5592 Like @code{add@var{m}3} but takes a @code{code_label} as operand 3 and
5593 emits code to jump to it if signed overflow occurs during the addition.
5594 This pattern is used to implement the built-in functions performing
5595 signed integer addition with overflow checking.
5596
5597 @cindex @code{subv@var{m}4} instruction pattern
5598 @cindex @code{mulv@var{m}4} instruction pattern
5599 @item @samp{subv@var{m}4}, @samp{mulv@var{m}4}
5600 Similar, for other signed arithmetic operations.
5601
5602 @cindex @code{uaddv@var{m}4} instruction pattern
5603 @item @samp{uaddv@var{m}4}
5604 Like @code{addv@var{m}4} but for unsigned addition. That is to
5605 say, the operation is the same as signed addition but the jump
5606 is taken only on unsigned overflow.
5607
5608 @cindex @code{usubv@var{m}4} instruction pattern
5609 @cindex @code{umulv@var{m}4} instruction pattern
5610 @item @samp{usubv@var{m}4}, @samp{umulv@var{m}4}
5611 Similar, for other unsigned arithmetic operations.
5612
5613 @cindex @code{uaddc@var{m}5} instruction pattern
5614 @item @samp{uaddc@var{m}5}
5615 Adds unsigned operands 2, 3 and 4 (where the last operand is guaranteed to
5616 have only values 0 or 1) together, sets operand 0 to the result of the
5617 addition of the 3 operands and sets operand 1 to 1 iff there was
5618 overflow on the unsigned additions, and to 0 otherwise. So, it is
5619 an addition with carry in (operand 4) and carry out (operand 1).
5620 All operands have the same mode.
5621
5622 @cindex @code{usubc@var{m}5} instruction pattern
5623 @item @samp{usubc@var{m}5}
5624 Similarly to @samp{uaddc@var{m}5}, except subtracts unsigned operands 3
5625 and 4 from operand 2 instead of adding them. So, it is
5626 a subtraction with carry/borrow in (operand 4) and carry/borrow out
5627 (operand 1). All operands have the same mode.
5628
5629 @cindex @code{addptr@var{m}3} instruction pattern
5630 @item @samp{addptr@var{m}3}
5631 Like @code{add@var{m}3} but is guaranteed to only be used for address
5632 calculations. The expanded code is not allowed to clobber the
5633 condition code. It only needs to be defined if @code{add@var{m}3}
5634 sets the condition code. If adds used for address calculations and
5635 normal adds are not compatible it is required to expand a distinct
5636 pattern (e.g.@: using an unspec). The pattern is used by LRA to emit
5637 address calculations. @code{add@var{m}3} is used if
5638 @code{addptr@var{m}3} is not defined.
5639
5640 @cindex @code{fma@var{m}4} instruction pattern
5641 @item @samp{fma@var{m}4}
5642 Multiply operand 2 and operand 1, then add operand 3, storing the
5643 result in operand 0 without doing an intermediate rounding step. All
5644 operands must have mode @var{m}. This pattern is used to implement
5645 the @code{fma}, @code{fmaf}, and @code{fmal} builtin functions from
5646 the ISO C99 standard.
5647
5648 @cindex @code{fms@var{m}4} instruction pattern
5649 @item @samp{fms@var{m}4}
5650 Like @code{fma@var{m}4}, except operand 3 subtracted from the
5651 product instead of added to the product. This is represented
5652 in the rtl as
5653
5654 @smallexample
5655 (fma:@var{m} @var{op1} @var{op2} (neg:@var{m} @var{op3}))
5656 @end smallexample
5657
5658 @cindex @code{fnma@var{m}4} instruction pattern
5659 @item @samp{fnma@var{m}4}
5660 Like @code{fma@var{m}4} except that the intermediate product
5661 is negated before being added to operand 3. This is represented
5662 in the rtl as
5663
5664 @smallexample
5665 (fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} @var{op3})
5666 @end smallexample
5667
5668 @cindex @code{fnms@var{m}4} instruction pattern
5669 @item @samp{fnms@var{m}4}
5670 Like @code{fms@var{m}4} except that the intermediate product
5671 is negated before subtracting operand 3. This is represented
5672 in the rtl as
5673
5674 @smallexample
5675 (fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} (neg:@var{m} @var{op3}))
5676 @end smallexample
5677
5678 @cindex @code{min@var{m}3} instruction pattern
5679 @cindex @code{max@var{m}3} instruction pattern
5680 @item @samp{smin@var{m}3}, @samp{smax@var{m}3}
5681 Signed minimum and maximum operations. When used with floating point,
5682 if both operands are zeros, or if either operand is @code{NaN}, then
5683 it is unspecified which of the two operands is returned as the result.
5684
5685 @cindex @code{fmin@var{m}3} instruction pattern
5686 @cindex @code{fmax@var{m}3} instruction pattern
5687 @item @samp{fmin@var{m}3}, @samp{fmax@var{m}3}
5688 IEEE-conformant minimum and maximum operations. If one operand is a quiet
5689 @code{NaN}, then the other operand is returned. If both operands are quiet
5690 @code{NaN}, then a quiet @code{NaN} is returned. In the case when gcc supports
5691 signaling @code{NaN} (-fsignaling-nans) an invalid floating point exception is
5692 raised and a quiet @code{NaN} is returned.
5693
5694 All operands have mode @var{m}, which is a scalar or vector
5695 floating-point mode. These patterns are not allowed to @code{FAIL}.
5696
5697 @cindex @code{reduc_smin_scal_@var{m}} instruction pattern
5698 @cindex @code{reduc_smax_scal_@var{m}} instruction pattern
5699 @item @samp{reduc_smin_scal_@var{m}}, @samp{reduc_smax_scal_@var{m}}
5700 Find the signed minimum/maximum of the elements of a vector. The vector is
5701 operand 1, and operand 0 is the scalar result, with mode equal to the mode of
5702 the elements of the input vector.
5703
5704 @cindex @code{reduc_umin_scal_@var{m}} instruction pattern
5705 @cindex @code{reduc_umax_scal_@var{m}} instruction pattern
5706 @item @samp{reduc_umin_scal_@var{m}}, @samp{reduc_umax_scal_@var{m}}
5707 Find the unsigned minimum/maximum of the elements of a vector. The vector is
5708 operand 1, and operand 0 is the scalar result, with mode equal to the mode of
5709 the elements of the input vector.
5710
5711 @cindex @code{reduc_fmin_scal_@var{m}} instruction pattern
5712 @cindex @code{reduc_fmax_scal_@var{m}} instruction pattern
5713 @item @samp{reduc_fmin_scal_@var{m}}, @samp{reduc_fmax_scal_@var{m}}
5714 Find the floating-point minimum/maximum of the elements of a vector,
5715 using the same rules as @code{fmin@var{m}3} and @code{fmax@var{m}3}.
5716 Operand 1 is a vector of mode @var{m} and operand 0 is the scalar
5717 result, which has mode @code{GET_MODE_INNER (@var{m})}.
5718
5719 @cindex @code{reduc_plus_scal_@var{m}} instruction pattern
5720 @item @samp{reduc_plus_scal_@var{m}}
5721 Compute the sum of the elements of a vector. The vector is operand 1, and
5722 operand 0 is the scalar result, with mode equal to the mode of the elements of
5723 the input vector.
5724
5725 @cindex @code{reduc_and_scal_@var{m}} instruction pattern
5726 @cindex @code{reduc_ior_scal_@var{m}} instruction pattern
5727 @cindex @code{reduc_xor_scal_@var{m}} instruction pattern
5728 @item @samp{reduc_and_scal_@var{m}}
5729 @itemx @samp{reduc_ior_scal_@var{m}}
5730 @itemx @samp{reduc_xor_scal_@var{m}}
5731 Compute the bitwise @code{AND}/@code{IOR}/@code{XOR} reduction of the elements
5732 of a vector of mode @var{m}. Operand 1 is the vector input and operand 0
5733 is the scalar result. The mode of the scalar result is the same as one
5734 element of @var{m}.
5735
5736 @cindex @code{extract_last_@var{m}} instruction pattern
5737 @item @code{extract_last_@var{m}}
5738 Find the last set bit in mask operand 1 and extract the associated element
5739 of vector operand 2. Store the result in scalar operand 0. Operand 2
5740 has vector mode @var{m} while operand 0 has the mode appropriate for one
5741 element of @var{m}. Operand 1 has the usual mask mode for vectors of mode
5742 @var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}.
5743
5744 @cindex @code{fold_extract_last_@var{m}} instruction pattern
5745 @item @code{fold_extract_last_@var{m}}
5746 If any bits of mask operand 2 are set, find the last set bit, extract
5747 the associated element from vector operand 3, and store the result
5748 in operand 0. Store operand 1 in operand 0 otherwise. Operand 3
5749 has mode @var{m} and operands 0 and 1 have the mode appropriate for
5750 one element of @var{m}. Operand 2 has the usual mask mode for vectors
5751 of mode @var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}.
5752
5753 @cindex @code{len_fold_extract_last_@var{m}} instruction pattern
5754 @item @code{len_fold_extract_last_@var{m}}
5755 Like @samp{fold_extract_last_@var{m}}, but takes an extra length operand as
5756 operand 4 and an extra bias operand as operand 5. The last associated element
5757 is extracted should have the index i < len (operand 4) + bias (operand 5).
5758
5759 @cindex @code{fold_left_plus_@var{m}} instruction pattern
5760 @item @code{fold_left_plus_@var{m}}
5761 Take scalar operand 1 and successively add each element from vector
5762 operand 2. Store the result in scalar operand 0. The vector has
5763 mode @var{m} and the scalars have the mode appropriate for one
5764 element of @var{m}. The operation is strictly in-order: there is
5765 no reassociation.
5766
5767 @cindex @code{mask_fold_left_plus_@var{m}} instruction pattern
5768 @item @code{mask_fold_left_plus_@var{m}}
5769 Like @samp{fold_left_plus_@var{m}}, but takes an additional mask operand
5770 (operand 3) that specifies which elements of the source vector should be added.
5771
5772 @cindex @code{mask_len_fold_left_plus_@var{m}} instruction pattern
5773 @item @code{mask_len_fold_left_plus_@var{m}}
5774 Like @samp{fold_left_plus_@var{m}}, but takes an additional mask operand
5775 (operand 3), len operand (operand 4) and bias operand (operand 5) that
5776 performs following operations strictly in-order (no reassociation):
5777
5778 @smallexample
5779 operand0 = operand1;
5780 for (i = 0; i < LEN + BIAS; i++)
5781 if (operand3[i])
5782 operand0 += operand2[i];
5783 @end smallexample
5784
5785 @cindex @code{sdot_prod@var{m}@var{n}} instruction pattern
5786 @item @samp{sdot_prod@var{m}@var{n}}
5787
5788 Multiply operand 1 by operand 2 without loss of precision, given that
5789 both operands contain signed elements. Add each product to the overlapping
5790 element of operand 3 and store the result in operand 0. Operands 0 and 3
5791 have mode @var{m} and operands 1 and 2 have mode @var{n}, with @var{n}
5792 having narrower elements than @var{m}.
5793
5794 Semantically the expressions perform the multiplication in the following signs
5795
5796 @smallexample
5797 sdot<signed op0, signed op1, signed op2, signed op3> ==
5798 op0 = sign-ext (op1) * sign-ext (op2) + op3
5799 @dots{}
5800 @end smallexample
5801
5802 @cindex @code{udot_prod@var{m}@var{n}} instruction pattern
5803 @item @samp{udot_prod@var{m}@var{n}}
5804
5805 Multiply operand 1 by operand 2 without loss of precision, given that
5806 both operands contain unsigned elements. Add each product to the overlapping
5807 element of operand 3 and store the result in operand 0. Operands 0 and 3
5808 have mode @var{m} and operands 1 and 2 have mode @var{n}, with @var{n}
5809 having narrower elements than @var{m}.
5810
5811 Semantically the expressions perform the multiplication in the following signs
5812
5813 @smallexample
5814 udot<unsigned op0, unsigned op1, unsigned op2, unsigned op3> ==
5815 op0 = zero-ext (op1) * zero-ext (op2) + op3
5816 @dots{}
5817 @end smallexample
5818
5819 @cindex @code{usdot_prod@var{m}@var{n}} instruction pattern
5820 @item @samp{usdot_prod@var{m}@var{n}}
5821 Compute the sum of the products of elements of different signs.
5822 Multiply operand 1 by operand 2 without loss of precision, given that operand 1
5823 is unsigned and operand 2 is signed. Add each product to the overlapping
5824 element of operand 3 and store the result in operand 0. Operands 0 and 3 have
5825 mode @var{m} and operands 1 and 2 have mode @var{n}, with @var{n} having
5826 narrower elements than @var{m}.
5827
5828 Semantically the expressions perform the multiplication in the following signs
5829
5830 @smallexample
5831 usdot<signed op0, unsigned op1, signed op2, signed op3> ==
5832 op0 = ((signed-conv) zero-ext (op1)) * sign-ext (op2) + op3
5833 @dots{}
5834 @end smallexample
5835
5836 @cindex @code{ssad@var{m}} instruction pattern
5837 @cindex @code{usad@var{m}} instruction pattern
5838 @item @samp{ssad@var{m}}
5839 @item @samp{usad@var{m}}
5840 Compute the sum of absolute differences of two signed/unsigned elements.
5841 Operand 1 and operand 2 are of the same mode. Their absolute difference, which
5842 is of a wider mode, is computed and added to operand 3. Operand 3 is of a mode
5843 equal or wider than the mode of the absolute difference. The result is placed
5844 in operand 0, which is of the same mode as operand 3.
5845 @var{m} is the mode of operand 1 and operand 2.
5846
5847 @cindex @code{widen_ssum@var{m}3} instruction pattern
5848 @cindex @code{widen_usum@var{m}3} instruction pattern
5849 @item @samp{widen_ssum@var{m}3}
5850 @itemx @samp{widen_usum@var{m}3}
5851 Operands 0 and 2 are of the same mode, which is wider than the mode of
5852 operand 1. Add operand 1 to operand 2 and place the widened result in
5853 operand 0. (This is used express accumulation of elements into an accumulator
5854 of a wider mode.)
5855 @var{m} is the mode of operand 1.
5856
5857 @cindex @code{smulhs@var{m}3} instruction pattern
5858 @cindex @code{umulhs@var{m}3} instruction pattern
5859 @item @samp{smulhs@var{m}3}
5860 @itemx @samp{umulhs@var{m}3}
5861 Signed/unsigned multiply high with scale. This is equivalent to the C code:
5862 @smallexample
5863 narrow op0, op1, op2;
5864 @dots{}
5865 op0 = (narrow) (((wide) op1 * (wide) op2) >> (N / 2 - 1));
5866 @end smallexample
5867 where the sign of @samp{narrow} determines whether this is a signed
5868 or unsigned operation, and @var{N} is the size of @samp{wide} in bits.
5869 @var{m} is the mode for all 3 operands (narrow). The wide mode is not specified
5870 and is defined to fit the whole multiply.
5871
5872 @cindex @code{smulhrs@var{m}3} instruction pattern
5873 @cindex @code{umulhrs@var{m}3} instruction pattern
5874 @item @samp{smulhrs@var{m}3}
5875 @itemx @samp{umulhrs@var{m}3}
5876 Signed/unsigned multiply high with round and scale. This is
5877 equivalent to the C code:
5878 @smallexample
5879 narrow op0, op1, op2;
5880 @dots{}
5881 op0 = (narrow) (((((wide) op1 * (wide) op2) >> (N / 2 - 2)) + 1) >> 1);
5882 @end smallexample
5883 where the sign of @samp{narrow} determines whether this is a signed
5884 or unsigned operation, and @var{N} is the size of @samp{wide} in bits.
5885 @var{m} is the mode for all 3 operands (narrow). The wide mode is not specified
5886 and is defined to fit the whole multiply.
5887
5888 @cindex @code{sdiv_pow2@var{m}3} instruction pattern
5889 @cindex @code{sdiv_pow2@var{m}3} instruction pattern
5890 @item @samp{sdiv_pow2@var{m}3}
5891 @itemx @samp{sdiv_pow2@var{m}3}
5892 Signed division by power-of-2 immediate. Equivalent to:
5893 @smallexample
5894 signed op0, op1;
5895 @dots{}
5896 op0 = op1 / (1 << imm);
5897 @end smallexample
5898
5899 @cindex @code{vec_shl_insert_@var{m}} instruction pattern
5900 @item @samp{vec_shl_insert_@var{m}}
5901 Shift the elements in vector input operand 1 left one element (i.e.@:
5902 away from element 0) and fill the vacated element 0 with the scalar
5903 in operand 2. Store the result in vector output operand 0. Operands
5904 0 and 1 have mode @var{m} and operand 2 has the mode appropriate for
5905 one element of @var{m}.
5906
5907 @cindex @code{vec_shl_@var{m}} instruction pattern
5908 @item @samp{vec_shl_@var{m}}
5909 Whole vector left shift in bits, i.e.@: away from element 0.
5910 Operand 1 is a vector to be shifted.
5911 Operand 2 is an integer shift amount in bits.
5912 Operand 0 is where the resulting shifted vector is stored.
5913 The output and input vectors should have the same modes.
5914
5915 @cindex @code{vec_shr_@var{m}} instruction pattern
5916 @item @samp{vec_shr_@var{m}}
5917 Whole vector right shift in bits, i.e.@: towards element 0.
5918 Operand 1 is a vector to be shifted.
5919 Operand 2 is an integer shift amount in bits.
5920 Operand 0 is where the resulting shifted vector is stored.
5921 The output and input vectors should have the same modes.
5922
5923 @cindex @code{vec_pack_trunc_@var{m}} instruction pattern
5924 @item @samp{vec_pack_trunc_@var{m}}
5925 Narrow (demote) and merge the elements of two vectors. Operands 1 and 2
5926 are vectors of the same mode having N integral or floating point elements
5927 of size S@. Operand 0 is the resulting vector in which 2*N elements of
5928 size S/2 are concatenated after narrowing them down using truncation.
5929
5930 @cindex @code{vec_pack_sbool_trunc_@var{m}} instruction pattern
5931 @item @samp{vec_pack_sbool_trunc_@var{m}}
5932 Narrow and merge the elements of two vectors. Operands 1 and 2 are vectors
5933 of the same type having N boolean elements. Operand 0 is the resulting
5934 vector in which 2*N elements are concatenated. The last operand (operand 3)
5935 is the number of elements in the output vector 2*N as a @code{CONST_INT}.
5936 This instruction pattern is used when all the vector input and output
5937 operands have the same scalar mode @var{m} and thus using
5938 @code{vec_pack_trunc_@var{m}} would be ambiguous.
5939
5940 @cindex @code{vec_pack_ssat_@var{m}} instruction pattern
5941 @cindex @code{vec_pack_usat_@var{m}} instruction pattern
5942 @item @samp{vec_pack_ssat_@var{m}}, @samp{vec_pack_usat_@var{m}}
5943 Narrow (demote) and merge the elements of two vectors. Operands 1 and 2
5944 are vectors of the same mode having N integral elements of size S.
5945 Operand 0 is the resulting vector in which the elements of the two input
5946 vectors are concatenated after narrowing them down using signed/unsigned
5947 saturating arithmetic.
5948
5949 @cindex @code{vec_pack_sfix_trunc_@var{m}} instruction pattern
5950 @cindex @code{vec_pack_ufix_trunc_@var{m}} instruction pattern
5951 @item @samp{vec_pack_sfix_trunc_@var{m}}, @samp{vec_pack_ufix_trunc_@var{m}}
5952 Narrow, convert to signed/unsigned integral type and merge the elements
5953 of two vectors. Operands 1 and 2 are vectors of the same mode having N
5954 floating point elements of size S@. Operand 0 is the resulting vector
5955 in which 2*N elements of size S/2 are concatenated.
5956
5957 @cindex @code{vec_packs_float_@var{m}} instruction pattern
5958 @cindex @code{vec_packu_float_@var{m}} instruction pattern
5959 @item @samp{vec_packs_float_@var{m}}, @samp{vec_packu_float_@var{m}}
5960 Narrow, convert to floating point type and merge the elements
5961 of two vectors. Operands 1 and 2 are vectors of the same mode having N
5962 signed/unsigned integral elements of size S@. Operand 0 is the resulting vector
5963 in which 2*N elements of size S/2 are concatenated.
5964
5965 @cindex @code{vec_unpacks_hi_@var{m}} instruction pattern
5966 @cindex @code{vec_unpacks_lo_@var{m}} instruction pattern
5967 @item @samp{vec_unpacks_hi_@var{m}}, @samp{vec_unpacks_lo_@var{m}}
5968 Extract and widen (promote) the high/low part of a vector of signed
5969 integral or floating point elements. The input vector (operand 1) has N
5970 elements of size S@. Widen (promote) the high/low elements of the vector
5971 using signed or floating point extension and place the resulting N/2
5972 values of size 2*S in the output vector (operand 0).
5973
5974 @cindex @code{vec_unpacku_hi_@var{m}} instruction pattern
5975 @cindex @code{vec_unpacku_lo_@var{m}} instruction pattern
5976 @item @samp{vec_unpacku_hi_@var{m}}, @samp{vec_unpacku_lo_@var{m}}
5977 Extract and widen (promote) the high/low part of a vector of unsigned
5978 integral elements. The input vector (operand 1) has N elements of size S.
5979 Widen (promote) the high/low elements of the vector using zero extension and
5980 place the resulting N/2 values of size 2*S in the output vector (operand 0).
5981
5982 @cindex @code{vec_unpacks_sbool_hi_@var{m}} instruction pattern
5983 @cindex @code{vec_unpacks_sbool_lo_@var{m}} instruction pattern
5984 @item @samp{vec_unpacks_sbool_hi_@var{m}}, @samp{vec_unpacks_sbool_lo_@var{m}}
5985 Extract the high/low part of a vector of boolean elements that have scalar
5986 mode @var{m}. The input vector (operand 1) has N elements, the output
5987 vector (operand 0) has N/2 elements. The last operand (operand 2) is the
5988 number of elements of the input vector N as a @code{CONST_INT}. These
5989 patterns are used if both the input and output vectors have the same scalar
5990 mode @var{m} and thus using @code{vec_unpacks_hi_@var{m}} or
5991 @code{vec_unpacks_lo_@var{m}} would be ambiguous.
5992
5993 @cindex @code{vec_unpacks_float_hi_@var{m}} instruction pattern
5994 @cindex @code{vec_unpacks_float_lo_@var{m}} instruction pattern
5995 @cindex @code{vec_unpacku_float_hi_@var{m}} instruction pattern
5996 @cindex @code{vec_unpacku_float_lo_@var{m}} instruction pattern
5997 @item @samp{vec_unpacks_float_hi_@var{m}}, @samp{vec_unpacks_float_lo_@var{m}}
5998 @itemx @samp{vec_unpacku_float_hi_@var{m}}, @samp{vec_unpacku_float_lo_@var{m}}
5999 Extract, convert to floating point type and widen the high/low part of a
6000 vector of signed/unsigned integral elements. The input vector (operand 1)
6001 has N elements of size S@. Convert the high/low elements of the vector using
6002 floating point conversion and place the resulting N/2 values of size 2*S in
6003 the output vector (operand 0).
6004
6005 @cindex @code{vec_unpack_sfix_trunc_hi_@var{m}} instruction pattern
6006 @cindex @code{vec_unpack_sfix_trunc_lo_@var{m}} instruction pattern
6007 @cindex @code{vec_unpack_ufix_trunc_hi_@var{m}} instruction pattern
6008 @cindex @code{vec_unpack_ufix_trunc_lo_@var{m}} instruction pattern
6009 @item @samp{vec_unpack_sfix_trunc_hi_@var{m}},
6010 @itemx @samp{vec_unpack_sfix_trunc_lo_@var{m}}
6011 @itemx @samp{vec_unpack_ufix_trunc_hi_@var{m}}
6012 @itemx @samp{vec_unpack_ufix_trunc_lo_@var{m}}
6013 Extract, convert to signed/unsigned integer type and widen the high/low part of a
6014 vector of floating point elements. The input vector (operand 1)
6015 has N elements of size S@. Convert the high/low elements of the vector
6016 to integers and place the resulting N/2 values of size 2*S in
6017 the output vector (operand 0).
6018
6019 @cindex @code{vec_widen_umult_hi_@var{m}} instruction pattern
6020 @cindex @code{vec_widen_umult_lo_@var{m}} instruction pattern
6021 @cindex @code{vec_widen_smult_hi_@var{m}} instruction pattern
6022 @cindex @code{vec_widen_smult_lo_@var{m}} instruction pattern
6023 @cindex @code{vec_widen_umult_even_@var{m}} instruction pattern
6024 @cindex @code{vec_widen_umult_odd_@var{m}} instruction pattern
6025 @cindex @code{vec_widen_smult_even_@var{m}} instruction pattern
6026 @cindex @code{vec_widen_smult_odd_@var{m}} instruction pattern
6027 @item @samp{vec_widen_umult_hi_@var{m}}, @samp{vec_widen_umult_lo_@var{m}}
6028 @itemx @samp{vec_widen_smult_hi_@var{m}}, @samp{vec_widen_smult_lo_@var{m}}
6029 @itemx @samp{vec_widen_umult_even_@var{m}}, @samp{vec_widen_umult_odd_@var{m}}
6030 @itemx @samp{vec_widen_smult_even_@var{m}}, @samp{vec_widen_smult_odd_@var{m}}
6031 Signed/Unsigned widening multiplication. The two inputs (operands 1 and 2)
6032 are vectors with N signed/unsigned elements of size S@. Multiply the high/low
6033 or even/odd elements of the two vectors, and put the N/2 products of size 2*S
6034 in the output vector (operand 0). A target shouldn't implement even/odd pattern
6035 pair if it is less efficient than lo/hi one.
6036
6037 @cindex @code{vec_widen_ushiftl_hi_@var{m}} instruction pattern
6038 @cindex @code{vec_widen_ushiftl_lo_@var{m}} instruction pattern
6039 @cindex @code{vec_widen_sshiftl_hi_@var{m}} instruction pattern
6040 @cindex @code{vec_widen_sshiftl_lo_@var{m}} instruction pattern
6041 @item @samp{vec_widen_ushiftl_hi_@var{m}}, @samp{vec_widen_ushiftl_lo_@var{m}}
6042 @itemx @samp{vec_widen_sshiftl_hi_@var{m}}, @samp{vec_widen_sshiftl_lo_@var{m}}
6043 Signed/Unsigned widening shift left. The first input (operand 1) is a vector
6044 with N signed/unsigned elements of size S@. Operand 2 is a constant. Shift
6045 the high/low elements of operand 1, and put the N/2 results of size 2*S in the
6046 output vector (operand 0).
6047
6048 @cindex @code{vec_widen_saddl_hi_@var{m}} instruction pattern
6049 @cindex @code{vec_widen_saddl_lo_@var{m}} instruction pattern
6050 @cindex @code{vec_widen_uaddl_hi_@var{m}} instruction pattern
6051 @cindex @code{vec_widen_uaddl_lo_@var{m}} instruction pattern
6052 @item @samp{vec_widen_uaddl_hi_@var{m}}, @samp{vec_widen_uaddl_lo_@var{m}}
6053 @itemx @samp{vec_widen_saddl_hi_@var{m}}, @samp{vec_widen_saddl_lo_@var{m}}
6054 Signed/Unsigned widening add long. Operands 1 and 2 are vectors with N
6055 signed/unsigned elements of size S@. Add the high/low elements of 1 and 2
6056 together, widen the resulting elements and put the N/2 results of size 2*S in
6057 the output vector (operand 0).
6058
6059 @cindex @code{vec_widen_ssubl_hi_@var{m}} instruction pattern
6060 @cindex @code{vec_widen_ssubl_lo_@var{m}} instruction pattern
6061 @cindex @code{vec_widen_usubl_hi_@var{m}} instruction pattern
6062 @cindex @code{vec_widen_usubl_lo_@var{m}} instruction pattern
6063 @item @samp{vec_widen_usubl_hi_@var{m}}, @samp{vec_widen_usubl_lo_@var{m}}
6064 @itemx @samp{vec_widen_ssubl_hi_@var{m}}, @samp{vec_widen_ssubl_lo_@var{m}}
6065 Signed/Unsigned widening subtract long. Operands 1 and 2 are vectors with N
6066 signed/unsigned elements of size S@. Subtract the high/low elements of 2 from
6067 1 and widen the resulting elements. Put the N/2 results of size 2*S in the
6068 output vector (operand 0).
6069
6070 @cindex @code{vec_widen_sabd_hi_@var{m}} instruction pattern
6071 @cindex @code{vec_widen_sabd_lo_@var{m}} instruction pattern
6072 @cindex @code{vec_widen_sabd_odd_@var{m}} instruction pattern
6073 @cindex @code{vec_widen_sabd_even_@var{m}} instruction pattern
6074 @cindex @code{vec_widen_uabd_hi_@var{m}} instruction pattern
6075 @cindex @code{vec_widen_uabd_lo_@var{m}} instruction pattern
6076 @cindex @code{vec_widen_uabd_odd_@var{m}} instruction pattern
6077 @cindex @code{vec_widen_uabd_even_@var{m}} instruction pattern
6078 @item @samp{vec_widen_uabd_hi_@var{m}}, @samp{vec_widen_uabd_lo_@var{m}}
6079 @itemx @samp{vec_widen_uabd_odd_@var{m}}, @samp{vec_widen_uabd_even_@var{m}}
6080 @itemx @samp{vec_widen_sabd_hi_@var{m}}, @samp{vec_widen_sabd_lo_@var{m}}
6081 @itemx @samp{vec_widen_sabd_odd_@var{m}}, @samp{vec_widen_sabd_even_@var{m}}
6082 Signed/Unsigned widening absolute difference. Operands 1 and 2 are
6083 vectors with N signed/unsigned elements of size S@. Find the absolute
6084 difference between operands 1 and 2 and widen the resulting elements.
6085 Put the N/2 results of size 2*S in the output vector (operand 0).
6086
6087 @cindex @code{vec_addsub@var{m}3} instruction pattern
6088 @item @samp{vec_addsub@var{m}3}
6089 Alternating subtract, add with even lanes doing subtract and odd
6090 lanes doing addition. Operands 1 and 2 and the outout operand are vectors
6091 with mode @var{m}.
6092
6093 @cindex @code{vec_fmaddsub@var{m}4} instruction pattern
6094 @item @samp{vec_fmaddsub@var{m}4}
6095 Alternating multiply subtract, add with even lanes doing subtract and odd
6096 lanes doing addition of the third operand to the multiplication result
6097 of the first two operands. Operands 1, 2 and 3 and the outout operand are vectors
6098 with mode @var{m}.
6099
6100 @cindex @code{vec_fmsubadd@var{m}4} instruction pattern
6101 @item @samp{vec_fmsubadd@var{m}4}
6102 Alternating multiply add, subtract with even lanes doing addition and odd
6103 lanes doing subtraction of the third operand to the multiplication result
6104 of the first two operands. Operands 1, 2 and 3 and the outout operand are vectors
6105 with mode @var{m}.
6106
6107 These instructions are not allowed to @code{FAIL}.
6108
6109 @cindex @code{mulhisi3} instruction pattern
6110 @item @samp{mulhisi3}
6111 Multiply operands 1 and 2, which have mode @code{HImode}, and store
6112 a @code{SImode} product in operand 0.
6113
6114 @cindex @code{mulqihi3} instruction pattern
6115 @cindex @code{mulsidi3} instruction pattern
6116 @item @samp{mulqihi3}, @samp{mulsidi3}
6117 Similar widening-multiplication instructions of other widths.
6118
6119 @cindex @code{umulqihi3} instruction pattern
6120 @cindex @code{umulhisi3} instruction pattern
6121 @cindex @code{umulsidi3} instruction pattern
6122 @item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
6123 Similar widening-multiplication instructions that do unsigned
6124 multiplication.
6125
6126 @cindex @code{usmulqihi3} instruction pattern
6127 @cindex @code{usmulhisi3} instruction pattern
6128 @cindex @code{usmulsidi3} instruction pattern
6129 @item @samp{usmulqihi3}, @samp{usmulhisi3}, @samp{usmulsidi3}
6130 Similar widening-multiplication instructions that interpret the first
6131 operand as unsigned and the second operand as signed, then do a signed
6132 multiplication.
6133
6134 @cindex @code{smul@var{m}3_highpart} instruction pattern
6135 @item @samp{smul@var{m}3_highpart}
6136 Perform a signed multiplication of operands 1 and 2, which have mode
6137 @var{m}, and store the most significant half of the product in operand 0.
6138 The least significant half of the product is discarded. This may be
6139 represented in RTL using a @code{smul_highpart} RTX expression.
6140
6141 @cindex @code{umul@var{m}3_highpart} instruction pattern
6142 @item @samp{umul@var{m}3_highpart}
6143 Similar, but the multiplication is unsigned. This may be represented
6144 in RTL using an @code{umul_highpart} RTX expression.
6145
6146 @cindex @code{madd@var{m}@var{n}4} instruction pattern
6147 @item @samp{madd@var{m}@var{n}4}
6148 Multiply operands 1 and 2, sign-extend them to mode @var{n}, add
6149 operand 3, and store the result in operand 0. Operands 1 and 2
6150 have mode @var{m} and operands 0 and 3 have mode @var{n}.
6151 Both modes must be integer or fixed-point modes and @var{n} must be twice
6152 the size of @var{m}.
6153
6154 In other words, @code{madd@var{m}@var{n}4} is like
6155 @code{mul@var{m}@var{n}3} except that it also adds operand 3.
6156
6157 These instructions are not allowed to @code{FAIL}.
6158
6159 @cindex @code{umadd@var{m}@var{n}4} instruction pattern
6160 @item @samp{umadd@var{m}@var{n}4}
6161 Like @code{madd@var{m}@var{n}4}, but zero-extend the multiplication
6162 operands instead of sign-extending them.
6163
6164 @cindex @code{ssmadd@var{m}@var{n}4} instruction pattern
6165 @item @samp{ssmadd@var{m}@var{n}4}
6166 Like @code{madd@var{m}@var{n}4}, but all involved operations must be
6167 signed-saturating.
6168
6169 @cindex @code{usmadd@var{m}@var{n}4} instruction pattern
6170 @item @samp{usmadd@var{m}@var{n}4}
6171 Like @code{umadd@var{m}@var{n}4}, but all involved operations must be
6172 unsigned-saturating.
6173
6174 @cindex @code{msub@var{m}@var{n}4} instruction pattern
6175 @item @samp{msub@var{m}@var{n}4}
6176 Multiply operands 1 and 2, sign-extend them to mode @var{n}, subtract the
6177 result from operand 3, and store the result in operand 0. Operands 1 and 2
6178 have mode @var{m} and operands 0 and 3 have mode @var{n}.
6179 Both modes must be integer or fixed-point modes and @var{n} must be twice
6180 the size of @var{m}.
6181
6182 In other words, @code{msub@var{m}@var{n}4} is like
6183 @code{mul@var{m}@var{n}3} except that it also subtracts the result
6184 from operand 3.
6185
6186 These instructions are not allowed to @code{FAIL}.
6187
6188 @cindex @code{umsub@var{m}@var{n}4} instruction pattern
6189 @item @samp{umsub@var{m}@var{n}4}
6190 Like @code{msub@var{m}@var{n}4}, but zero-extend the multiplication
6191 operands instead of sign-extending them.
6192
6193 @cindex @code{ssmsub@var{m}@var{n}4} instruction pattern
6194 @item @samp{ssmsub@var{m}@var{n}4}
6195 Like @code{msub@var{m}@var{n}4}, but all involved operations must be
6196 signed-saturating.
6197
6198 @cindex @code{usmsub@var{m}@var{n}4} instruction pattern
6199 @item @samp{usmsub@var{m}@var{n}4}
6200 Like @code{umsub@var{m}@var{n}4}, but all involved operations must be
6201 unsigned-saturating.
6202
6203 @cindex @code{divmod@var{m}4} instruction pattern
6204 @item @samp{divmod@var{m}4}
6205 Signed division that produces both a quotient and a remainder.
6206 Operand 1 is divided by operand 2 to produce a quotient stored
6207 in operand 0 and a remainder stored in operand 3.
6208
6209 For machines with an instruction that produces both a quotient and a
6210 remainder, provide a pattern for @samp{divmod@var{m}4} but do not
6211 provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}. This
6212 allows optimization in the relatively common case when both the quotient
6213 and remainder are computed.
6214
6215 If an instruction that just produces a quotient or just a remainder
6216 exists and is more efficient than the instruction that produces both,
6217 write the output routine of @samp{divmod@var{m}4} to call
6218 @code{find_reg_note} and look for a @code{REG_UNUSED} note on the
6219 quotient or remainder and generate the appropriate instruction.
6220
6221 @cindex @code{udivmod@var{m}4} instruction pattern
6222 @item @samp{udivmod@var{m}4}
6223 Similar, but does unsigned division.
6224
6225 @anchor{shift patterns}
6226 @cindex @code{ashl@var{m}3} instruction pattern
6227 @cindex @code{ssashl@var{m}3} instruction pattern
6228 @cindex @code{usashl@var{m}3} instruction pattern
6229 @item @samp{ashl@var{m}3}, @samp{ssashl@var{m}3}, @samp{usashl@var{m}3}
6230 Arithmetic-shift operand 1 left by a number of bits specified by operand
6231 2, and store the result in operand 0. Here @var{m} is the mode of
6232 operand 0 and operand 1; operand 2's mode is specified by the
6233 instruction pattern, and the compiler will convert the operand to that
6234 mode before generating the instruction. The shift or rotate expander
6235 or instruction pattern should explicitly specify the mode of the operand 2,
6236 it should never be @code{VOIDmode}. The meaning of out-of-range shift
6237 counts can optionally be specified by @code{TARGET_SHIFT_TRUNCATION_MASK}.
6238 @xref{TARGET_SHIFT_TRUNCATION_MASK}. Operand 2 is always a scalar type.
6239
6240 @cindex @code{ashr@var{m}3} instruction pattern
6241 @cindex @code{lshr@var{m}3} instruction pattern
6242 @cindex @code{rotl@var{m}3} instruction pattern
6243 @cindex @code{rotr@var{m}3} instruction pattern
6244 @item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3}
6245 Other shift and rotate instructions, analogous to the
6246 @code{ashl@var{m}3} instructions. Operand 2 is always a scalar type.
6247
6248 @cindex @code{vashl@var{m}3} instruction pattern
6249 @cindex @code{vashr@var{m}3} instruction pattern
6250 @cindex @code{vlshr@var{m}3} instruction pattern
6251 @cindex @code{vrotl@var{m}3} instruction pattern
6252 @cindex @code{vrotr@var{m}3} instruction pattern
6253 @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}
6254 Vector shift and rotate instructions that take vectors as operand 2
6255 instead of a scalar type.
6256
6257 @cindex @code{uabd@var{m}3} instruction pattern
6258 @cindex @code{sabd@var{m}3} instruction pattern
6259 @item @samp{uabd@var{m}}, @samp{sabd@var{m}}
6260 Signed and unsigned absolute difference instructions. These
6261 instructions find the difference between operands 1 and 2
6262 then return the absolute value. A C code equivalent would be:
6263 @smallexample
6264 op0 = op1 > op2 ? op1 - op2 : op2 - op1;
6265 @end smallexample
6266
6267 @cindex @code{avg@var{m}3_floor} instruction pattern
6268 @cindex @code{uavg@var{m}3_floor} instruction pattern
6269 @item @samp{avg@var{m}3_floor}
6270 @itemx @samp{uavg@var{m}3_floor}
6271 Signed and unsigned average instructions. These instructions add
6272 operands 1 and 2 without truncation, divide the result by 2,
6273 round towards -Inf, and store the result in operand 0. This is
6274 equivalent to the C code:
6275 @smallexample
6276 narrow op0, op1, op2;
6277 @dots{}
6278 op0 = (narrow) (((wide) op1 + (wide) op2) >> 1);
6279 @end smallexample
6280 where the sign of @samp{narrow} determines whether this is a signed
6281 or unsigned operation.
6282
6283 @cindex @code{avg@var{m}3_ceil} instruction pattern
6284 @cindex @code{uavg@var{m}3_ceil} instruction pattern
6285 @item @samp{avg@var{m}3_ceil}
6286 @itemx @samp{uavg@var{m}3_ceil}
6287 Like @samp{avg@var{m}3_floor} and @samp{uavg@var{m}3_floor}, but round
6288 towards +Inf. This is equivalent to the C code:
6289 @smallexample
6290 narrow op0, op1, op2;
6291 @dots{}
6292 op0 = (narrow) (((wide) op1 + (wide) op2 + 1) >> 1);
6293 @end smallexample
6294
6295 @cindex @code{bswap@var{m}2} instruction pattern
6296 @item @samp{bswap@var{m}2}
6297 Reverse the order of bytes of operand 1 and store the result in operand 0.
6298
6299 @cindex @code{neg@var{m}2} instruction pattern
6300 @cindex @code{ssneg@var{m}2} instruction pattern
6301 @cindex @code{usneg@var{m}2} instruction pattern
6302 @item @samp{neg@var{m}2}, @samp{ssneg@var{m}2}, @samp{usneg@var{m}2}
6303 Negate operand 1 and store the result in operand 0.
6304
6305 @cindex @code{negv@var{m}3} instruction pattern
6306 @item @samp{negv@var{m}3}
6307 Like @code{neg@var{m}2} but takes a @code{code_label} as operand 2 and
6308 emits code to jump to it if signed overflow occurs during the negation.
6309
6310 @cindex @code{abs@var{m}2} instruction pattern
6311 @item @samp{abs@var{m}2}
6312 Store the absolute value of operand 1 into operand 0.
6313
6314 @cindex @code{sqrt@var{m}2} instruction pattern
6315 @item @samp{sqrt@var{m}2}
6316 Store the square root of operand 1 into operand 0. Both operands have
6317 mode @var{m}, which is a scalar or vector floating-point mode.
6318
6319 This pattern is not allowed to @code{FAIL}.
6320
6321 @cindex @code{rsqrt@var{m}2} instruction pattern
6322 @item @samp{rsqrt@var{m}2}
6323 Store the reciprocal of the square root of operand 1 into operand 0.
6324 Both operands have mode @var{m}, which is a scalar or vector
6325 floating-point mode.
6326
6327 On most architectures this pattern is only approximate, so either
6328 its C condition or the @code{TARGET_OPTAB_SUPPORTED_P} hook should
6329 check for the appropriate math flags. (Using the C condition is
6330 more direct, but using @code{TARGET_OPTAB_SUPPORTED_P} can be useful
6331 if a target-specific built-in also uses the @samp{rsqrt@var{m}2}
6332 pattern.)
6333
6334 This pattern is not allowed to @code{FAIL}.
6335
6336 @cindex @code{fmod@var{m}3} instruction pattern
6337 @item @samp{fmod@var{m}3}
6338 Store the remainder of dividing operand 1 by operand 2 into
6339 operand 0, rounded towards zero to an integer. All operands have
6340 mode @var{m}, which is a scalar or vector floating-point mode.
6341
6342 This pattern is not allowed to @code{FAIL}.
6343
6344 @cindex @code{remainder@var{m}3} instruction pattern
6345 @item @samp{remainder@var{m}3}
6346 Store the remainder of dividing operand 1 by operand 2 into
6347 operand 0, rounded to the nearest integer. All operands have
6348 mode @var{m}, which is a scalar or vector floating-point mode.
6349
6350 This pattern is not allowed to @code{FAIL}.
6351
6352 @cindex @code{scalb@var{m}3} instruction pattern
6353 @item @samp{scalb@var{m}3}
6354 Raise @code{FLT_RADIX} to the power of operand 2, multiply it by
6355 operand 1, and store the result in operand 0. All operands have
6356 mode @var{m}, which is a scalar or vector floating-point mode.
6357
6358 This pattern is not allowed to @code{FAIL}.
6359
6360 @cindex @code{ldexp@var{m}3} instruction pattern
6361 @item @samp{ldexp@var{m}3}
6362 Raise 2 to the power of operand 2, multiply it by operand 1, and store
6363 the result in operand 0. Operands 0 and 1 have mode @var{m}, which is
6364 a scalar or vector floating-point mode. Operand 2's mode has
6365 the same number of elements as @var{m} and each element is wide
6366 enough to store an @code{int}. The integers are signed.
6367
6368 This pattern is not allowed to @code{FAIL}.
6369
6370 @cindex @code{cos@var{m}2} instruction pattern
6371 @item @samp{cos@var{m}2}
6372 Store the cosine of operand 1 into operand 0. Both operands have
6373 mode @var{m}, which is a scalar or vector floating-point mode.
6374
6375 This pattern is not allowed to @code{FAIL}.
6376
6377 @cindex @code{sin@var{m}2} instruction pattern
6378 @item @samp{sin@var{m}2}
6379 Store the sine of operand 1 into operand 0. Both operands have
6380 mode @var{m}, which is a scalar or vector floating-point mode.
6381
6382 This pattern is not allowed to @code{FAIL}.
6383
6384 @cindex @code{sincos@var{m}3} instruction pattern
6385 @item @samp{sincos@var{m}3}
6386 Store the cosine of operand 2 into operand 0 and the sine of
6387 operand 2 into operand 1. All operands have mode @var{m},
6388 which is a scalar or vector floating-point mode.
6389
6390 Targets that can calculate the sine and cosine simultaneously can
6391 implement this pattern as opposed to implementing individual
6392 @code{sin@var{m}2} and @code{cos@var{m}2} patterns. The @code{sin}
6393 and @code{cos} built-in functions will then be expanded to the
6394 @code{sincos@var{m}3} pattern, with one of the output values
6395 left unused.
6396
6397 @cindex @code{tan@var{m}2} instruction pattern
6398 @item @samp{tan@var{m}2}
6399 Store the tangent of operand 1 into operand 0. Both operands have
6400 mode @var{m}, which is a scalar or vector floating-point mode.
6401
6402 This pattern is not allowed to @code{FAIL}.
6403
6404 @cindex @code{asin@var{m}2} instruction pattern
6405 @item @samp{asin@var{m}2}
6406 Store the arc sine of operand 1 into operand 0. Both operands have
6407 mode @var{m}, which is a scalar or vector floating-point mode.
6408
6409 This pattern is not allowed to @code{FAIL}.
6410
6411 @cindex @code{acos@var{m}2} instruction pattern
6412 @item @samp{acos@var{m}2}
6413 Store the arc cosine of operand 1 into operand 0. Both operands have
6414 mode @var{m}, which is a scalar or vector floating-point mode.
6415
6416 This pattern is not allowed to @code{FAIL}.
6417
6418 @cindex @code{atan@var{m}2} instruction pattern
6419 @item @samp{atan@var{m}2}
6420 Store the arc tangent of operand 1 into operand 0. Both operands have
6421 mode @var{m}, which is a scalar or vector floating-point mode.
6422
6423 This pattern is not allowed to @code{FAIL}.
6424
6425 @cindex @code{fegetround@var{m}} instruction pattern
6426 @item @samp{fegetround@var{m}}
6427 Store the current machine floating-point rounding mode into operand 0.
6428 Operand 0 has mode @var{m}, which is scalar. This pattern is used to
6429 implement the @code{fegetround} function from the ISO C99 standard.
6430
6431 @cindex @code{feclearexcept@var{m}} instruction pattern
6432 @cindex @code{feraiseexcept@var{m}} instruction pattern
6433 @item @samp{feclearexcept@var{m}}
6434 @item @samp{feraiseexcept@var{m}}
6435 Clears or raises the supported machine floating-point exceptions
6436 represented by the bits in operand 1. Error status is stored as
6437 nonzero value in operand 0. Both operands have mode @var{m}, which is
6438 a scalar. These patterns are used to implement the
6439 @code{feclearexcept} and @code{feraiseexcept} functions from the ISO
6440 C99 standard.
6441
6442 @cindex @code{exp@var{m}2} instruction pattern
6443 @item @samp{exp@var{m}2}
6444 Raise e (the base of natural logarithms) to the power of operand 1
6445 and store the result in operand 0. Both operands have mode @var{m},
6446 which is a scalar or vector floating-point mode.
6447
6448 This pattern is not allowed to @code{FAIL}.
6449
6450 @cindex @code{expm1@var{m}2} instruction pattern
6451 @item @samp{expm1@var{m}2}
6452 Raise e (the base of natural logarithms) to the power of operand 1,
6453 subtract 1, and store the result in operand 0. Both operands have
6454 mode @var{m}, which is a scalar or vector floating-point mode.
6455
6456 For inputs close to zero, the pattern is expected to be more
6457 accurate than a separate @code{exp@var{m}2} and @code{sub@var{m}3}
6458 would be.
6459
6460 This pattern is not allowed to @code{FAIL}.
6461
6462 @cindex @code{exp10@var{m}2} instruction pattern
6463 @item @samp{exp10@var{m}2}
6464 Raise 10 to the power of operand 1 and store the result in operand 0.
6465 Both operands have mode @var{m}, which is a scalar or vector
6466 floating-point mode.
6467
6468 This pattern is not allowed to @code{FAIL}.
6469
6470 @cindex @code{exp2@var{m}2} instruction pattern
6471 @item @samp{exp2@var{m}2}
6472 Raise 2 to the power of operand 1 and store the result in operand 0.
6473 Both operands have mode @var{m}, which is a scalar or vector
6474 floating-point mode.
6475
6476 This pattern is not allowed to @code{FAIL}.
6477
6478 @cindex @code{log@var{m}2} instruction pattern
6479 @item @samp{log@var{m}2}
6480 Store the natural logarithm of operand 1 into operand 0. Both operands
6481 have mode @var{m}, which is a scalar or vector floating-point mode.
6482
6483 This pattern is not allowed to @code{FAIL}.
6484
6485 @cindex @code{log1p@var{m}2} instruction pattern
6486 @item @samp{log1p@var{m}2}
6487 Add 1 to operand 1, compute the natural logarithm, and store
6488 the result in operand 0. Both operands have mode @var{m}, which is
6489 a scalar or vector floating-point mode.
6490
6491 For inputs close to zero, the pattern is expected to be more
6492 accurate than a separate @code{add@var{m}3} and @code{log@var{m}2}
6493 would be.
6494
6495 This pattern is not allowed to @code{FAIL}.
6496
6497 @cindex @code{log10@var{m}2} instruction pattern
6498 @item @samp{log10@var{m}2}
6499 Store the base-10 logarithm of operand 1 into operand 0. Both operands
6500 have mode @var{m}, which is a scalar or vector floating-point mode.
6501
6502 This pattern is not allowed to @code{FAIL}.
6503
6504 @cindex @code{log2@var{m}2} instruction pattern
6505 @item @samp{log2@var{m}2}
6506 Store the base-2 logarithm of operand 1 into operand 0. Both operands
6507 have mode @var{m}, which is a scalar or vector floating-point mode.
6508
6509 This pattern is not allowed to @code{FAIL}.
6510
6511 @cindex @code{logb@var{m}2} instruction pattern
6512 @item @samp{logb@var{m}2}
6513 Store the base-@code{FLT_RADIX} logarithm of operand 1 into operand 0.
6514 Both operands have mode @var{m}, which is a scalar or vector
6515 floating-point mode.
6516
6517 This pattern is not allowed to @code{FAIL}.
6518
6519 @cindex @code{signbit@var{m}2} instruction pattern
6520 @item @samp{signbit@var{m}2}
6521 Store the sign bit of floating-point operand 1 in operand 0.
6522 @var{m} is either a scalar or vector mode. When it is a scalar,
6523 operand 1 has mode @var{m} but operand 0 must have mode @code{SImode}.
6524 When @var{m} is a vector, operand 1 has the mode @var{m}.
6525 operand 0's mode should be an vector integer mode which has
6526 the same number of elements and the same size as mode @var{m}.
6527
6528 This pattern is not allowed to @code{FAIL}.
6529
6530 @cindex @code{significand@var{m}2} instruction pattern
6531 @item @samp{significand@var{m}2}
6532 Store the significand of floating-point operand 1 in operand 0.
6533 Both operands have mode @var{m}, which is a scalar or vector
6534 floating-point mode.
6535
6536 This pattern is not allowed to @code{FAIL}.
6537
6538 @cindex @code{pow@var{m}3} instruction pattern
6539 @item @samp{pow@var{m}3}
6540 Store the value of operand 1 raised to the exponent operand 2
6541 into operand 0. All operands have mode @var{m}, which is a scalar
6542 or vector floating-point mode.
6543
6544 This pattern is not allowed to @code{FAIL}.
6545
6546 @cindex @code{atan2@var{m}3} instruction pattern
6547 @item @samp{atan2@var{m}3}
6548 Store the arc tangent (inverse tangent) of operand 1 divided by
6549 operand 2 into operand 0, using the signs of both arguments to
6550 determine the quadrant of the result. All operands have mode
6551 @var{m}, which is a scalar or vector floating-point mode.
6552
6553 This pattern is not allowed to @code{FAIL}.
6554
6555 @cindex @code{floor@var{m}2} instruction pattern
6556 @item @samp{floor@var{m}2}
6557 Store the largest integral value not greater than operand 1 in operand 0.
6558 Both operands have mode @var{m}, which is a scalar or vector
6559 floating-point mode. If @option{-ffp-int-builtin-inexact} is in
6560 effect, the ``inexact'' exception may be raised for noninteger
6561 operands; otherwise, it may not.
6562
6563 This pattern is not allowed to @code{FAIL}.
6564
6565 @cindex @code{btrunc@var{m}2} instruction pattern
6566 @item @samp{btrunc@var{m}2}
6567 Round operand 1 to an integer, towards zero, and store the result in
6568 operand 0. Both operands have mode @var{m}, which is a scalar or
6569 vector floating-point mode. If @option{-ffp-int-builtin-inexact} is
6570 in effect, the ``inexact'' exception may be raised for noninteger
6571 operands; otherwise, it may not.
6572
6573 This pattern is not allowed to @code{FAIL}.
6574
6575 @cindex @code{round@var{m}2} instruction pattern
6576 @item @samp{round@var{m}2}
6577 Round operand 1 to the nearest integer, rounding away from zero in the
6578 event of a tie, and store the result in operand 0. Both operands have
6579 mode @var{m}, which is a scalar or vector floating-point mode. If
6580 @option{-ffp-int-builtin-inexact} is in effect, the ``inexact''
6581 exception may be raised for noninteger operands; otherwise, it may
6582 not.
6583
6584 This pattern is not allowed to @code{FAIL}.
6585
6586 @cindex @code{ceil@var{m}2} instruction pattern
6587 @item @samp{ceil@var{m}2}
6588 Store the smallest integral value not less than operand 1 in operand 0.
6589 Both operands have mode @var{m}, which is a scalar or vector
6590 floating-point mode. If @option{-ffp-int-builtin-inexact} is in
6591 effect, the ``inexact'' exception may be raised for noninteger
6592 operands; otherwise, it may not.
6593
6594 This pattern is not allowed to @code{FAIL}.
6595
6596 @cindex @code{nearbyint@var{m}2} instruction pattern
6597 @item @samp{nearbyint@var{m}2}
6598 Round operand 1 to an integer, using the current rounding mode, and
6599 store the result in operand 0. Do not raise an inexact condition when
6600 the result is different from the argument. Both operands have mode
6601 @var{m}, which is a scalar or vector floating-point mode.
6602
6603 This pattern is not allowed to @code{FAIL}.
6604
6605 @cindex @code{rint@var{m}2} instruction pattern
6606 @item @samp{rint@var{m}2}
6607 Round operand 1 to an integer, using the current rounding mode, and
6608 store the result in operand 0. Raise an inexact condition when
6609 the result is different from the argument. Both operands have mode
6610 @var{m}, which is a scalar or vector floating-point mode.
6611
6612 This pattern is not allowed to @code{FAIL}.
6613
6614 @cindex @code{lrint@var{m}@var{n}2}
6615 @item @samp{lrint@var{m}@var{n}2}
6616 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6617 point mode @var{n} as a signed number according to the current
6618 rounding mode and store in operand 0 (which has mode @var{n}).
6619
6620 @cindex @code{lround@var{m}@var{n}2}
6621 @item @samp{lround@var{m}@var{n}2}
6622 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6623 point mode @var{n} as a signed number rounding to nearest and away
6624 from zero and store in operand 0 (which has mode @var{n}).
6625
6626 @cindex @code{lfloor@var{m}@var{n}2}
6627 @item @samp{lfloor@var{m}@var{n}2}
6628 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6629 point mode @var{n} as a signed number rounding down and store in
6630 operand 0 (which has mode @var{n}).
6631
6632 @cindex @code{lceil@var{m}@var{n}2}
6633 @item @samp{lceil@var{m}@var{n}2}
6634 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6635 point mode @var{n} as a signed number rounding up and store in
6636 operand 0 (which has mode @var{n}).
6637
6638 @cindex @code{copysign@var{m}3} instruction pattern
6639 @item @samp{copysign@var{m}3}
6640 Store a value with the magnitude of operand 1 and the sign of operand
6641 2 into operand 0. All operands have mode @var{m}, which is a scalar or
6642 vector floating-point mode.
6643
6644 This pattern is not allowed to @code{FAIL}.
6645
6646 @cindex @code{xorsign@var{m}3} instruction pattern
6647 @item @samp{xorsign@var{m}3}
6648 Equivalent to @samp{op0 = op1 * copysign (1.0, op2)}: store a value with
6649 the magnitude of operand 1 and the sign of operand 2 into operand 0.
6650 All operands have mode @var{m}, which is a scalar or vector
6651 floating-point mode.
6652
6653 This pattern is not allowed to @code{FAIL}.
6654
6655 @cindex @code{issignaling@var{m}2} instruction pattern
6656 @item @samp{issignaling@var{m}2}
6657 Set operand 0 to 1 if operand 1 is a signaling NaN and to 0 otherwise.
6658
6659 @cindex @code{cadd90@var{m}3} instruction pattern
6660 @item @samp{cadd90@var{m}3}
6661 Perform vector add and subtract on even/odd number pairs. The operation being
6662 matched is semantically described as
6663
6664 @smallexample
6665 for (int i = 0; i < N; i += 2)
6666 @{
6667 c[i] = a[i] - b[i+1];
6668 c[i+1] = a[i+1] + b[i];
6669 @}
6670 @end smallexample
6671
6672 This operation is semantically equivalent to performing a vector addition of
6673 complex numbers in operand 1 with operand 2 rotated by 90 degrees around
6674 the argand plane and storing the result in operand 0.
6675
6676 In GCC lane ordering the real part of the number must be in the even lanes with
6677 the imaginary part in the odd lanes.
6678
6679 The operation is only supported for vector modes @var{m}.
6680
6681 This pattern is not allowed to @code{FAIL}.
6682
6683 @cindex @code{cadd270@var{m}3} instruction pattern
6684 @item @samp{cadd270@var{m}3}
6685 Perform vector add and subtract on even/odd number pairs. The operation being
6686 matched is semantically described as
6687
6688 @smallexample
6689 for (int i = 0; i < N; i += 2)
6690 @{
6691 c[i] = a[i] + b[i+1];
6692 c[i+1] = a[i+1] - b[i];
6693 @}
6694 @end smallexample
6695
6696 This operation is semantically equivalent to performing a vector addition of
6697 complex numbers in operand 1 with operand 2 rotated by 270 degrees around
6698 the argand plane and storing the result in operand 0.
6699
6700 In GCC lane ordering the real part of the number must be in the even lanes with
6701 the imaginary part in the odd lanes.
6702
6703 The operation is only supported for vector modes @var{m}.
6704
6705 This pattern is not allowed to @code{FAIL}.
6706
6707 @cindex @code{cmla@var{m}4} instruction pattern
6708 @item @samp{cmla@var{m}4}
6709 Perform a vector multiply and accumulate that is semantically the same as
6710 a multiply and accumulate of complex numbers.
6711
6712 @smallexample
6713 complex TYPE op0[N];
6714 complex TYPE op1[N];
6715 complex TYPE op2[N];
6716 complex TYPE op3[N];
6717 for (int i = 0; i < N; i += 1)
6718 @{
6719 op0[i] = op1[i] * op2[i] + op3[i];
6720 @}
6721 @end smallexample
6722
6723 In GCC lane ordering the real part of the number must be in the even lanes with
6724 the imaginary part in the odd lanes.
6725
6726 The operation is only supported for vector modes @var{m}.
6727
6728 This pattern is not allowed to @code{FAIL}.
6729
6730 @cindex @code{cmla_conj@var{m}4} instruction pattern
6731 @item @samp{cmla_conj@var{m}4}
6732 Perform a vector multiply by conjugate and accumulate that is semantically
6733 the same as a multiply and accumulate of complex numbers where the second
6734 multiply arguments is conjugated.
6735
6736 @smallexample
6737 complex TYPE op0[N];
6738 complex TYPE op1[N];
6739 complex TYPE op2[N];
6740 complex TYPE op3[N];
6741 for (int i = 0; i < N; i += 1)
6742 @{
6743 op0[i] = op1[i] * conj (op2[i]) + op3[i];
6744 @}
6745 @end smallexample
6746
6747 In GCC lane ordering the real part of the number must be in the even lanes with
6748 the imaginary part in the odd lanes.
6749
6750 The operation is only supported for vector modes @var{m}.
6751
6752 This pattern is not allowed to @code{FAIL}.
6753
6754 @cindex @code{cmls@var{m}4} instruction pattern
6755 @item @samp{cmls@var{m}4}
6756 Perform a vector multiply and subtract that is semantically the same as
6757 a multiply and subtract of complex numbers.
6758
6759 @smallexample
6760 complex TYPE op0[N];
6761 complex TYPE op1[N];
6762 complex TYPE op2[N];
6763 complex TYPE op3[N];
6764 for (int i = 0; i < N; i += 1)
6765 @{
6766 op0[i] = op1[i] * op2[i] - op3[i];
6767 @}
6768 @end smallexample
6769
6770 In GCC lane ordering the real part of the number must be in the even lanes with
6771 the imaginary part in the odd lanes.
6772
6773 The operation is only supported for vector modes @var{m}.
6774
6775 This pattern is not allowed to @code{FAIL}.
6776
6777 @cindex @code{cmls_conj@var{m}4} instruction pattern
6778 @item @samp{cmls_conj@var{m}4}
6779 Perform a vector multiply by conjugate and subtract that is semantically
6780 the same as a multiply and subtract of complex numbers where the second
6781 multiply arguments is conjugated.
6782
6783 @smallexample
6784 complex TYPE op0[N];
6785 complex TYPE op1[N];
6786 complex TYPE op2[N];
6787 complex TYPE op3[N];
6788 for (int i = 0; i < N; i += 1)
6789 @{
6790 op0[i] = op1[i] * conj (op2[i]) - op3[i];
6791 @}
6792 @end smallexample
6793
6794 In GCC lane ordering the real part of the number must be in the even lanes with
6795 the imaginary part in the odd lanes.
6796
6797 The operation is only supported for vector modes @var{m}.
6798
6799 This pattern is not allowed to @code{FAIL}.
6800
6801 @cindex @code{cmul@var{m}4} instruction pattern
6802 @item @samp{cmul@var{m}4}
6803 Perform a vector multiply that is semantically the same as multiply of
6804 complex numbers.
6805
6806 @smallexample
6807 complex TYPE op0[N];
6808 complex TYPE op1[N];
6809 complex TYPE op2[N];
6810 for (int i = 0; i < N; i += 1)
6811 @{
6812 op0[i] = op1[i] * op2[i];
6813 @}
6814 @end smallexample
6815
6816 In GCC lane ordering the real part of the number must be in the even lanes with
6817 the imaginary part in the odd lanes.
6818
6819 The operation is only supported for vector modes @var{m}.
6820
6821 This pattern is not allowed to @code{FAIL}.
6822
6823 @cindex @code{cmul_conj@var{m}4} instruction pattern
6824 @item @samp{cmul_conj@var{m}4}
6825 Perform a vector multiply by conjugate that is semantically the same as a
6826 multiply of complex numbers where the second multiply arguments is conjugated.
6827
6828 @smallexample
6829 complex TYPE op0[N];
6830 complex TYPE op1[N];
6831 complex TYPE op2[N];
6832 for (int i = 0; i < N; i += 1)
6833 @{
6834 op0[i] = op1[i] * conj (op2[i]);
6835 @}
6836 @end smallexample
6837
6838 In GCC lane ordering the real part of the number must be in the even lanes with
6839 the imaginary part in the odd lanes.
6840
6841 The operation is only supported for vector modes @var{m}.
6842
6843 This pattern is not allowed to @code{FAIL}.
6844
6845 @cindex @code{ffs@var{m}2} instruction pattern
6846 @item @samp{ffs@var{m}2}
6847 Store into operand 0 one plus the index of the least significant 1-bit
6848 of operand 1. If operand 1 is zero, store zero.
6849
6850 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6851 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6852 integer mode is suitable for the target. The compiler will insert
6853 conversion instructions as necessary (typically to convert the result
6854 to the same width as @code{int}). When @var{m} is a vector, both
6855 operands must have mode @var{m}.
6856
6857 This pattern is not allowed to @code{FAIL}.
6858
6859 @cindex @code{clrsb@var{m}2} instruction pattern
6860 @item @samp{clrsb@var{m}2}
6861 Count leading redundant sign bits.
6862 Store into operand 0 the number of redundant sign bits in operand 1, starting
6863 at the most significant bit position.
6864 A redundant sign bit is defined as any sign bit after the first. As such,
6865 this count will be one less than the count of leading sign bits.
6866
6867 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6868 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6869 integer mode is suitable for the target. The compiler will insert
6870 conversion instructions as necessary (typically to convert the result
6871 to the same width as @code{int}). When @var{m} is a vector, both
6872 operands must have mode @var{m}.
6873
6874 This pattern is not allowed to @code{FAIL}.
6875
6876 @cindex @code{clz@var{m}2} instruction pattern
6877 @item @samp{clz@var{m}2}
6878 Store into operand 0 the number of leading 0-bits in operand 1, starting
6879 at the most significant bit position. If operand 1 is 0, the
6880 @code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
6881 the result is undefined or has a useful value.
6882
6883 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6884 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6885 integer mode is suitable for the target. The compiler will insert
6886 conversion instructions as necessary (typically to convert the result
6887 to the same width as @code{int}). When @var{m} is a vector, both
6888 operands must have mode @var{m}.
6889
6890 This pattern is not allowed to @code{FAIL}.
6891
6892 @cindex @code{ctz@var{m}2} instruction pattern
6893 @item @samp{ctz@var{m}2}
6894 Store into operand 0 the number of trailing 0-bits in operand 1, starting
6895 at the least significant bit position. If operand 1 is 0, the
6896 @code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
6897 the result is undefined or has a useful value.
6898
6899 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6900 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6901 integer mode is suitable for the target. The compiler will insert
6902 conversion instructions as necessary (typically to convert the result
6903 to the same width as @code{int}). When @var{m} is a vector, both
6904 operands must have mode @var{m}.
6905
6906 This pattern is not allowed to @code{FAIL}.
6907
6908 @cindex @code{popcount@var{m}2} instruction pattern
6909 @item @samp{popcount@var{m}2}
6910 Store into operand 0 the number of 1-bits in operand 1.
6911
6912 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6913 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6914 integer mode is suitable for the target. The compiler will insert
6915 conversion instructions as necessary (typically to convert the result
6916 to the same width as @code{int}). When @var{m} is a vector, both
6917 operands must have mode @var{m}.
6918
6919 This pattern is not allowed to @code{FAIL}.
6920
6921 @cindex @code{parity@var{m}2} instruction pattern
6922 @item @samp{parity@var{m}2}
6923 Store into operand 0 the parity of operand 1, i.e.@: the number of 1-bits
6924 in operand 1 modulo 2.
6925
6926 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6927 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6928 integer mode is suitable for the target. The compiler will insert
6929 conversion instructions as necessary (typically to convert the result
6930 to the same width as @code{int}). When @var{m} is a vector, both
6931 operands must have mode @var{m}.
6932
6933 This pattern is not allowed to @code{FAIL}.
6934
6935 @cindex @code{one_cmpl@var{m}2} instruction pattern
6936 @item @samp{one_cmpl@var{m}2}
6937 Store the bitwise-complement of operand 1 into operand 0.
6938
6939 @cindex @code{cpymem@var{m}} instruction pattern
6940 @item @samp{cpymem@var{m}}
6941 Block copy instruction. The destination and source blocks of memory
6942 are the first two operands, and both are @code{mem:BLK}s with an
6943 address in mode @code{Pmode}.
6944
6945 The number of bytes to copy is the third operand, in mode @var{m}.
6946 Usually, you specify @code{Pmode} for @var{m}. However, if you can
6947 generate better code knowing the range of valid lengths is smaller than
6948 those representable in a full Pmode pointer, you should provide
6949 a pattern with a
6950 mode corresponding to the range of values you can handle efficiently
6951 (e.g., @code{QImode} for values in the range 0--127; note we avoid numbers
6952 that appear negative) and also a pattern with @code{Pmode}.
6953
6954 The fourth operand is the known shared alignment of the source and
6955 destination, in the form of a @code{const_int} rtx. Thus, if the
6956 compiler knows that both source and destination are word-aligned,
6957 it may provide the value 4 for this operand.
6958
6959 Optional operands 5 and 6 specify expected alignment and size of block
6960 respectively. The expected alignment differs from alignment in operand 4
6961 in a way that the blocks are not required to be aligned according to it in
6962 all cases. This expected alignment is also in bytes, just like operand 4.
6963 Expected size, when unknown, is set to @code{(const_int -1)}.
6964
6965 Descriptions of multiple @code{cpymem@var{m}} patterns can only be
6966 beneficial if the patterns for smaller modes have fewer restrictions
6967 on their first, second and fourth operands. Note that the mode @var{m}
6968 in @code{cpymem@var{m}} does not impose any restriction on the mode of
6969 individually copied data units in the block.
6970
6971 The @code{cpymem@var{m}} patterns need not give special consideration
6972 to the possibility that the source and destination strings might
6973 overlap. An exception is the case where source and destination are
6974 equal, this case needs to be handled correctly.
6975 These patterns are used to do inline expansion of @code{__builtin_memcpy}.
6976
6977 @cindex @code{movmem@var{m}} instruction pattern
6978 @item @samp{movmem@var{m}}
6979 Block move instruction. The destination and source blocks of memory
6980 are the first two operands, and both are @code{mem:BLK}s with an
6981 address in mode @code{Pmode}.
6982
6983 The number of bytes to copy is the third operand, in mode @var{m}.
6984 Usually, you specify @code{Pmode} for @var{m}. However, if you can
6985 generate better code knowing the range of valid lengths is smaller than
6986 those representable in a full Pmode pointer, you should provide
6987 a pattern with a
6988 mode corresponding to the range of values you can handle efficiently
6989 (e.g., @code{QImode} for values in the range 0--127; note we avoid numbers
6990 that appear negative) and also a pattern with @code{Pmode}.
6991
6992 The fourth operand is the known shared alignment of the source and
6993 destination, in the form of a @code{const_int} rtx. Thus, if the
6994 compiler knows that both source and destination are word-aligned,
6995 it may provide the value 4 for this operand.
6996
6997 Optional operands 5 and 6 specify expected alignment and size of block
6998 respectively. The expected alignment differs from alignment in operand 4
6999 in a way that the blocks are not required to be aligned according to it in
7000 all cases. This expected alignment is also in bytes, just like operand 4.
7001 Expected size, when unknown, is set to @code{(const_int -1)}.
7002
7003 Descriptions of multiple @code{movmem@var{m}} patterns can only be
7004 beneficial if the patterns for smaller modes have fewer restrictions
7005 on their first, second and fourth operands. Note that the mode @var{m}
7006 in @code{movmem@var{m}} does not impose any restriction on the mode of
7007 individually copied data units in the block.
7008
7009 The @code{movmem@var{m}} patterns must correctly handle the case where
7010 the source and destination strings overlap. These patterns are used to
7011 do inline expansion of @code{__builtin_memmove}.
7012
7013 @cindex @code{movstr} instruction pattern
7014 @item @samp{movstr}
7015 String copy instruction, with @code{stpcpy} semantics. Operand 0 is
7016 an output operand in mode @code{Pmode}. The addresses of the
7017 destination and source strings are operands 1 and 2, and both are
7018 @code{mem:BLK}s with addresses in mode @code{Pmode}. The execution of
7019 the expansion of this pattern should store in operand 0 the address in
7020 which the @code{NUL} terminator was stored in the destination string.
7021
7022 This pattern has also several optional operands that are same as in
7023 @code{setmem}.
7024
7025 @cindex @code{setmem@var{m}} instruction pattern
7026 @item @samp{setmem@var{m}}
7027 Block set instruction. The destination string is the first operand,
7028 given as a @code{mem:BLK} whose address is in mode @code{Pmode}. The
7029 number of bytes to set is the second operand, in mode @var{m}. The value to
7030 initialize the memory with is the third operand. Targets that only support the
7031 clearing of memory should reject any value that is not the constant 0. See
7032 @samp{cpymem@var{m}} for a discussion of the choice of mode.
7033
7034 The fourth operand is the known alignment of the destination, in the form
7035 of a @code{const_int} rtx. Thus, if the compiler knows that the
7036 destination is word-aligned, it may provide the value 4 for this
7037 operand.
7038
7039 Optional operands 5 and 6 specify expected alignment and size of block
7040 respectively. The expected alignment differs from alignment in operand 4
7041 in a way that the blocks are not required to be aligned according to it in
7042 all cases. This expected alignment is also in bytes, just like operand 4.
7043 Expected size, when unknown, is set to @code{(const_int -1)}.
7044 Operand 7 is the minimal size of the block and operand 8 is the
7045 maximal size of the block (NULL if it cannot be represented as CONST_INT).
7046 Operand 9 is the probable maximal size (i.e.@: we cannot rely on it for
7047 correctness, but it can be used for choosing proper code sequence for a
7048 given size).
7049
7050 The use for multiple @code{setmem@var{m}} is as for @code{cpymem@var{m}}.
7051
7052 @cindex @code{cmpstrn@var{m}} instruction pattern
7053 @item @samp{cmpstrn@var{m}}
7054 String compare instruction, with five operands. Operand 0 is the output;
7055 it has mode @var{m}. The remaining four operands are like the operands
7056 of @samp{cpymem@var{m}}. The two memory blocks specified are compared
7057 byte by byte in lexicographic order starting at the beginning of each
7058 string. The instruction is not allowed to prefetch more than one byte
7059 at a time since either string may end in the first byte and reading past
7060 that may access an invalid page or segment and cause a fault. The
7061 comparison terminates early if the fetched bytes are different or if
7062 they are equal to zero. The effect of the instruction is to store a
7063 value in operand 0 whose sign indicates the result of the comparison.
7064
7065 @cindex @code{cmpstr@var{m}} instruction pattern
7066 @item @samp{cmpstr@var{m}}
7067 String compare instruction, without known maximum length. Operand 0 is the
7068 output; it has mode @var{m}. The second and third operand are the blocks of
7069 memory to be compared; both are @code{mem:BLK} with an address in mode
7070 @code{Pmode}.
7071
7072 The fourth operand is the known shared alignment of the source and
7073 destination, in the form of a @code{const_int} rtx. Thus, if the
7074 compiler knows that both source and destination are word-aligned,
7075 it may provide the value 4 for this operand.
7076
7077 The two memory blocks specified are compared byte by byte in lexicographic
7078 order starting at the beginning of each string. The instruction is not allowed
7079 to prefetch more than one byte at a time since either string may end in the
7080 first byte and reading past that may access an invalid page or segment and
7081 cause a fault. The comparison will terminate when the fetched bytes
7082 are different or if they are equal to zero. The effect of the
7083 instruction is to store a value in operand 0 whose sign indicates the
7084 result of the comparison.
7085
7086 @cindex @code{cmpmem@var{m}} instruction pattern
7087 @item @samp{cmpmem@var{m}}
7088 Block compare instruction, with five operands like the operands
7089 of @samp{cmpstr@var{m}}. The two memory blocks specified are compared
7090 byte by byte in lexicographic order starting at the beginning of each
7091 block. Unlike @samp{cmpstr@var{m}} the instruction can prefetch
7092 any bytes in the two memory blocks. Also unlike @samp{cmpstr@var{m}}
7093 the comparison will not stop if both bytes are zero. The effect of
7094 the instruction is to store a value in operand 0 whose sign indicates
7095 the result of the comparison.
7096
7097 @cindex @code{strlen@var{m}} instruction pattern
7098 @item @samp{strlen@var{m}}
7099 Compute the length of a string, with three operands.
7100 Operand 0 is the result (of mode @var{m}), operand 1 is
7101 a @code{mem} referring to the first character of the string,
7102 operand 2 is the character to search for (normally zero),
7103 and operand 3 is a constant describing the known alignment
7104 of the beginning of the string.
7105
7106 @cindex @code{rawmemchr@var{m}} instruction pattern
7107 @item @samp{rawmemchr@var{m}}
7108 Scan memory referred to by operand 1 for the first occurrence of operand 2.
7109 Operand 1 is a @code{mem} and operand 2 a @code{const_int} of mode @var{m}.
7110 Operand 0 is the result, i.e., a pointer to the first occurrence of operand 2
7111 in the memory block given by operand 1.
7112
7113 @cindex @code{float@var{m}@var{n}2} instruction pattern
7114 @item @samp{float@var{m}@var{n}2}
7115 Convert signed integer operand 1 (valid for fixed point mode @var{m}) to
7116 floating point mode @var{n} and store in operand 0 (which has mode
7117 @var{n}).
7118
7119 @cindex @code{floatuns@var{m}@var{n}2} instruction pattern
7120 @item @samp{floatuns@var{m}@var{n}2}
7121 Convert unsigned integer operand 1 (valid for fixed point mode @var{m})
7122 to floating point mode @var{n} and store in operand 0 (which has mode
7123 @var{n}).
7124
7125 @cindex @code{fix@var{m}@var{n}2} instruction pattern
7126 @item @samp{fix@var{m}@var{n}2}
7127 Convert operand 1 (valid for floating point mode @var{m}) to fixed
7128 point mode @var{n} as a signed number and store in operand 0 (which
7129 has mode @var{n}). This instruction's result is defined only when
7130 the value of operand 1 is an integer.
7131
7132 If the machine description defines this pattern, it also needs to
7133 define the @code{ftrunc} pattern.
7134
7135 @cindex @code{fixuns@var{m}@var{n}2} instruction pattern
7136 @item @samp{fixuns@var{m}@var{n}2}
7137 Convert operand 1 (valid for floating point mode @var{m}) to fixed
7138 point mode @var{n} as an unsigned number and store in operand 0 (which
7139 has mode @var{n}). This instruction's result is defined only when the
7140 value of operand 1 is an integer.
7141
7142 @cindex @code{ftrunc@var{m}2} instruction pattern
7143 @item @samp{ftrunc@var{m}2}
7144 Convert operand 1 (valid for floating point mode @var{m}) to an
7145 integer value, still represented in floating point mode @var{m}, and
7146 store it in operand 0 (valid for floating point mode @var{m}).
7147
7148 @cindex @code{fix_trunc@var{m}@var{n}2} instruction pattern
7149 @item @samp{fix_trunc@var{m}@var{n}2}
7150 Like @samp{fix@var{m}@var{n}2} but works for any floating point value
7151 of mode @var{m} by converting the value to an integer.
7152
7153 @cindex @code{fixuns_trunc@var{m}@var{n}2} instruction pattern
7154 @item @samp{fixuns_trunc@var{m}@var{n}2}
7155 Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
7156 value of mode @var{m} by converting the value to an integer.
7157
7158 @cindex @code{trunc@var{m}@var{n}2} instruction pattern
7159 @item @samp{trunc@var{m}@var{n}2}
7160 Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
7161 store in operand 0 (which has mode @var{n}). Both modes must be fixed
7162 point or both floating point.
7163
7164 @cindex @code{extend@var{m}@var{n}2} instruction pattern
7165 @item @samp{extend@var{m}@var{n}2}
7166 Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
7167 store in operand 0 (which has mode @var{n}). Both modes must be fixed
7168 point or both floating point.
7169
7170 @cindex @code{zero_extend@var{m}@var{n}2} instruction pattern
7171 @item @samp{zero_extend@var{m}@var{n}2}
7172 Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
7173 store in operand 0 (which has mode @var{n}). Both modes must be fixed
7174 point.
7175
7176 @cindex @code{fract@var{m}@var{n}2} instruction pattern
7177 @item @samp{fract@var{m}@var{n}2}
7178 Convert operand 1 of mode @var{m} to mode @var{n} and store in
7179 operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n}
7180 could be fixed-point to fixed-point, signed integer to fixed-point,
7181 fixed-point to signed integer, floating-point to fixed-point,
7182 or fixed-point to floating-point.
7183 When overflows or underflows happen, the results are undefined.
7184
7185 @cindex @code{satfract@var{m}@var{n}2} instruction pattern
7186 @item @samp{satfract@var{m}@var{n}2}
7187 Convert operand 1 of mode @var{m} to mode @var{n} and store in
7188 operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n}
7189 could be fixed-point to fixed-point, signed integer to fixed-point,
7190 or floating-point to fixed-point.
7191 When overflows or underflows happen, the instruction saturates the
7192 results to the maximum or the minimum.
7193
7194 @cindex @code{fractuns@var{m}@var{n}2} instruction pattern
7195 @item @samp{fractuns@var{m}@var{n}2}
7196 Convert operand 1 of mode @var{m} to mode @var{n} and store in
7197 operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n}
7198 could be unsigned integer to fixed-point, or
7199 fixed-point to unsigned integer.
7200 When overflows or underflows happen, the results are undefined.
7201
7202 @cindex @code{satfractuns@var{m}@var{n}2} instruction pattern
7203 @item @samp{satfractuns@var{m}@var{n}2}
7204 Convert unsigned integer operand 1 of mode @var{m} to fixed-point mode
7205 @var{n} and store in operand 0 (which has mode @var{n}).
7206 When overflows or underflows happen, the instruction saturates the
7207 results to the maximum or the minimum.
7208
7209 @cindex @code{extv@var{m}} instruction pattern
7210 @item @samp{extv@var{m}}
7211 Extract a bit-field from register operand 1, sign-extend it, and store
7212 it in operand 0. Operand 2 specifies the width of the field in bits
7213 and operand 3 the starting bit, which counts from the most significant
7214 bit if @samp{BITS_BIG_ENDIAN} is true and from the least significant bit
7215 otherwise.
7216
7217 Operands 0 and 1 both have mode @var{m}. Operands 2 and 3 have a
7218 target-specific mode.
7219
7220 @cindex @code{extvmisalign@var{m}} instruction pattern
7221 @item @samp{extvmisalign@var{m}}
7222 Extract a bit-field from memory operand 1, sign extend it, and store
7223 it in operand 0. Operand 2 specifies the width in bits and operand 3
7224 the starting bit. The starting bit is always somewhere in the first byte of
7225 operand 1; it counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
7226 is true and from the least significant bit otherwise.
7227
7228 Operand 0 has mode @var{m} while operand 1 has @code{BLK} mode.
7229 Operands 2 and 3 have a target-specific mode.
7230
7231 The instruction must not read beyond the last byte of the bit-field.
7232
7233 @cindex @code{extzv@var{m}} instruction pattern
7234 @item @samp{extzv@var{m}}
7235 Like @samp{extv@var{m}} except that the bit-field value is zero-extended.
7236
7237 @cindex @code{extzvmisalign@var{m}} instruction pattern
7238 @item @samp{extzvmisalign@var{m}}
7239 Like @samp{extvmisalign@var{m}} except that the bit-field value is
7240 zero-extended.
7241
7242 @cindex @code{insv@var{m}} instruction pattern
7243 @item @samp{insv@var{m}}
7244 Insert operand 3 into a bit-field of register operand 0. Operand 1
7245 specifies the width of the field in bits and operand 2 the starting bit,
7246 which counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
7247 is true and from the least significant bit otherwise.
7248
7249 Operands 0 and 3 both have mode @var{m}. Operands 1 and 2 have a
7250 target-specific mode.
7251
7252 @cindex @code{insvmisalign@var{m}} instruction pattern
7253 @item @samp{insvmisalign@var{m}}
7254 Insert operand 3 into a bit-field of memory operand 0. Operand 1
7255 specifies the width of the field in bits and operand 2 the starting bit.
7256 The starting bit is always somewhere in the first byte of operand 0;
7257 it counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
7258 is true and from the least significant bit otherwise.
7259
7260 Operand 3 has mode @var{m} while operand 0 has @code{BLK} mode.
7261 Operands 1 and 2 have a target-specific mode.
7262
7263 The instruction must not read or write beyond the last byte of the bit-field.
7264
7265 @cindex @code{extv} instruction pattern
7266 @item @samp{extv}
7267 Extract a bit-field from operand 1 (a register or memory operand), where
7268 operand 2 specifies the width in bits and operand 3 the starting bit,
7269 and store it in operand 0. Operand 0 must have mode @code{word_mode}.
7270 Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often
7271 @code{word_mode} is allowed only for registers. Operands 2 and 3 must
7272 be valid for @code{word_mode}.
7273
7274 The RTL generation pass generates this instruction only with constants
7275 for operands 2 and 3 and the constant is never zero for operand 2.
7276
7277 The bit-field value is sign-extended to a full word integer
7278 before it is stored in operand 0.
7279
7280 This pattern is deprecated; please use @samp{extv@var{m}} and
7281 @code{extvmisalign@var{m}} instead.
7282
7283 @cindex @code{extzv} instruction pattern
7284 @item @samp{extzv}
7285 Like @samp{extv} except that the bit-field value is zero-extended.
7286
7287 This pattern is deprecated; please use @samp{extzv@var{m}} and
7288 @code{extzvmisalign@var{m}} instead.
7289
7290 @cindex @code{insv} instruction pattern
7291 @item @samp{insv}
7292 Store operand 3 (which must be valid for @code{word_mode}) into a
7293 bit-field in operand 0, where operand 1 specifies the width in bits and
7294 operand 2 the starting bit. Operand 0 may have mode @code{byte_mode} or
7295 @code{word_mode}; often @code{word_mode} is allowed only for registers.
7296 Operands 1 and 2 must be valid for @code{word_mode}.
7297
7298 The RTL generation pass generates this instruction only with constants
7299 for operands 1 and 2 and the constant is never zero for operand 1.
7300
7301 This pattern is deprecated; please use @samp{insv@var{m}} and
7302 @code{insvmisalign@var{m}} instead.
7303
7304 @cindex @code{mov@var{mode}cc} instruction pattern
7305 @item @samp{mov@var{mode}cc}
7306 Conditionally move operand 2 or operand 3 into operand 0 according to the
7307 comparison in operand 1. If the comparison is true, operand 2 is moved
7308 into operand 0, otherwise operand 3 is moved.
7309
7310 The mode of the operands being compared need not be the same as the operands
7311 being moved. Some machines, sparc64 for example, have instructions that
7312 conditionally move an integer value based on the floating point condition
7313 codes and vice versa.
7314
7315 If the machine does not have conditional move instructions, do not
7316 define these patterns.
7317
7318 @cindex @code{add@var{mode}cc} instruction pattern
7319 @item @samp{add@var{mode}cc}
7320 Similar to @samp{mov@var{mode}cc} but for conditional addition. Conditionally
7321 move operand 2 or (operands 2 + operand 3) into operand 0 according to the
7322 comparison in operand 1. If the comparison is false, operand 2 is moved into
7323 operand 0, otherwise (operand 2 + operand 3) is moved.
7324
7325 @cindex @code{cond_neg@var{mode}} instruction pattern
7326 @cindex @code{cond_one_cmpl@var{mode}} instruction pattern
7327 @item @samp{cond_neg@var{mode}}
7328 @itemx @samp{cond_one_cmpl@var{mode}}
7329 When operand 1 is true, perform an operation on operands 2 and
7330 store the result in operand 0, otherwise store operand 3 in operand 0.
7331 The operation works elementwise if the operands are vectors.
7332
7333 The scalar case is equivalent to:
7334
7335 @smallexample
7336 op0 = op1 ? @var{op} op2 : op3;
7337 @end smallexample
7338
7339 while the vector case is equivalent to:
7340
7341 @smallexample
7342 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
7343 op0[i] = op1[i] ? @var{op} op2[i] : op3[i];
7344 @end smallexample
7345
7346 where, for example, @var{op} is @code{~} for @samp{cond_one_cmpl@var{mode}}.
7347
7348 When defined for floating-point modes, the contents of @samp{op2[i]}
7349 are not interpreted if @samp{op1[i]} is false, just like they would not
7350 be in a normal C @samp{?:} condition.
7351
7352 Operands 0, 2, and 3 all have mode @var{m}. Operand 1 is a scalar
7353 integer if @var{m} is scalar, otherwise it has the mode returned by
7354 @code{TARGET_VECTORIZE_GET_MASK_MODE}.
7355
7356 @samp{cond_@var{op}@var{mode}} generally corresponds to a conditional
7357 form of @samp{@var{op}@var{mode}2}.
7358
7359 @cindex @code{cond_add@var{mode}} instruction pattern
7360 @cindex @code{cond_sub@var{mode}} instruction pattern
7361 @cindex @code{cond_mul@var{mode}} instruction pattern
7362 @cindex @code{cond_div@var{mode}} instruction pattern
7363 @cindex @code{cond_udiv@var{mode}} instruction pattern
7364 @cindex @code{cond_mod@var{mode}} instruction pattern
7365 @cindex @code{cond_umod@var{mode}} instruction pattern
7366 @cindex @code{cond_and@var{mode}} instruction pattern
7367 @cindex @code{cond_ior@var{mode}} instruction pattern
7368 @cindex @code{cond_xor@var{mode}} instruction pattern
7369 @cindex @code{cond_smin@var{mode}} instruction pattern
7370 @cindex @code{cond_smax@var{mode}} instruction pattern
7371 @cindex @code{cond_umin@var{mode}} instruction pattern
7372 @cindex @code{cond_umax@var{mode}} instruction pattern
7373 @cindex @code{cond_copysign@var{mode}} instruction pattern
7374 @cindex @code{cond_fmin@var{mode}} instruction pattern
7375 @cindex @code{cond_fmax@var{mode}} instruction pattern
7376 @cindex @code{cond_ashl@var{mode}} instruction pattern
7377 @cindex @code{cond_ashr@var{mode}} instruction pattern
7378 @cindex @code{cond_lshr@var{mode}} instruction pattern
7379 @item @samp{cond_add@var{mode}}
7380 @itemx @samp{cond_sub@var{mode}}
7381 @itemx @samp{cond_mul@var{mode}}
7382 @itemx @samp{cond_div@var{mode}}
7383 @itemx @samp{cond_udiv@var{mode}}
7384 @itemx @samp{cond_mod@var{mode}}
7385 @itemx @samp{cond_umod@var{mode}}
7386 @itemx @samp{cond_and@var{mode}}
7387 @itemx @samp{cond_ior@var{mode}}
7388 @itemx @samp{cond_xor@var{mode}}
7389 @itemx @samp{cond_smin@var{mode}}
7390 @itemx @samp{cond_smax@var{mode}}
7391 @itemx @samp{cond_umin@var{mode}}
7392 @itemx @samp{cond_umax@var{mode}}
7393 @itemx @samp{cond_copysign@var{mode}}
7394 @itemx @samp{cond_fmin@var{mode}}
7395 @itemx @samp{cond_fmax@var{mode}}
7396 @itemx @samp{cond_ashl@var{mode}}
7397 @itemx @samp{cond_ashr@var{mode}}
7398 @itemx @samp{cond_lshr@var{mode}}
7399 When operand 1 is true, perform an operation on operands 2 and 3 and
7400 store the result in operand 0, otherwise store operand 4 in operand 0.
7401 The operation works elementwise if the operands are vectors.
7402
7403 The scalar case is equivalent to:
7404
7405 @smallexample
7406 op0 = op1 ? op2 @var{op} op3 : op4;
7407 @end smallexample
7408
7409 while the vector case is equivalent to:
7410
7411 @smallexample
7412 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
7413 op0[i] = op1[i] ? op2[i] @var{op} op3[i] : op4[i];
7414 @end smallexample
7415
7416 where, for example, @var{op} is @code{+} for @samp{cond_add@var{mode}}.
7417
7418 When defined for floating-point modes, the contents of @samp{op3[i]}
7419 are not interpreted if @samp{op1[i]} is false, just like they would not
7420 be in a normal C @samp{?:} condition.
7421
7422 Operands 0, 2, 3 and 4 all have mode @var{m}. Operand 1 is a scalar
7423 integer if @var{m} is scalar, otherwise it has the mode returned by
7424 @code{TARGET_VECTORIZE_GET_MASK_MODE}.
7425
7426 @samp{cond_@var{op}@var{mode}} generally corresponds to a conditional
7427 form of @samp{@var{op}@var{mode}3}. As an exception, the vector forms
7428 of shifts correspond to patterns like @code{vashl@var{mode}3} rather
7429 than patterns like @code{ashl@var{mode}3}.
7430
7431 @samp{cond_copysign@var{mode}} is only defined for floating point modes.
7432
7433 @cindex @code{cond_fma@var{mode}} instruction pattern
7434 @cindex @code{cond_fms@var{mode}} instruction pattern
7435 @cindex @code{cond_fnma@var{mode}} instruction pattern
7436 @cindex @code{cond_fnms@var{mode}} instruction pattern
7437 @item @samp{cond_fma@var{mode}}
7438 @itemx @samp{cond_fms@var{mode}}
7439 @itemx @samp{cond_fnma@var{mode}}
7440 @itemx @samp{cond_fnms@var{mode}}
7441 Like @samp{cond_add@var{m}}, except that the conditional operation
7442 takes 3 operands rather than two. For example, the vector form of
7443 @samp{cond_fma@var{mode}} is equivalent to:
7444
7445 @smallexample
7446 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
7447 op0[i] = op1[i] ? fma (op2[i], op3[i], op4[i]) : op5[i];
7448 @end smallexample
7449
7450 @cindex @code{cond_len_neg@var{mode}} instruction pattern
7451 @cindex @code{cond_len_one_cmpl@var{mode}} instruction pattern
7452 @item @samp{cond_len_neg@var{mode}}
7453 @itemx @samp{cond_len_one_cmpl@var{mode}}
7454 When operand 1 is true and element index < operand 4 + operand 5, perform an operation on operands 1 and
7455 store the result in operand 0, otherwise store operand 2 in operand 0.
7456 The operation only works for the operands are vectors.
7457
7458 @smallexample
7459 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
7460 op0[i] = (i < ops[4] + ops[5] && op1[i]
7461 ? @var{op} op2[i]
7462 : op3[i]);
7463 @end smallexample
7464
7465 where, for example, @var{op} is @code{~} for @samp{cond_len_one_cmpl@var{mode}}.
7466
7467 When defined for floating-point modes, the contents of @samp{op2[i]}
7468 are not interpreted if @samp{op1[i]} is false, just like they would not
7469 be in a normal C @samp{?:} condition.
7470
7471 Operands 0, 2, and 3 all have mode @var{m}. Operand 1 is a scalar
7472 integer if @var{m} is scalar, otherwise it has the mode returned by
7473 @code{TARGET_VECTORIZE_GET_MASK_MODE}. Operand 4 has whichever
7474 integer mode the target prefers.
7475
7476 @samp{cond_len_@var{op}@var{mode}} generally corresponds to a conditional
7477 form of @samp{@var{op}@var{mode}2}.
7478
7479
7480 @cindex @code{cond_len_add@var{mode}} instruction pattern
7481 @cindex @code{cond_len_sub@var{mode}} instruction pattern
7482 @cindex @code{cond_len_mul@var{mode}} instruction pattern
7483 @cindex @code{cond_len_div@var{mode}} instruction pattern
7484 @cindex @code{cond_len_udiv@var{mode}} instruction pattern
7485 @cindex @code{cond_len_mod@var{mode}} instruction pattern
7486 @cindex @code{cond_len_umod@var{mode}} instruction pattern
7487 @cindex @code{cond_len_and@var{mode}} instruction pattern
7488 @cindex @code{cond_len_ior@var{mode}} instruction pattern
7489 @cindex @code{cond_len_xor@var{mode}} instruction pattern
7490 @cindex @code{cond_len_smin@var{mode}} instruction pattern
7491 @cindex @code{cond_len_smax@var{mode}} instruction pattern
7492 @cindex @code{cond_len_umin@var{mode}} instruction pattern
7493 @cindex @code{cond_len_umax@var{mode}} instruction pattern
7494 @cindex @code{cond_len_copysign@var{mode}} instruction pattern
7495 @cindex @code{cond_len_fmin@var{mode}} instruction pattern
7496 @cindex @code{cond_len_fmax@var{mode}} instruction pattern
7497 @cindex @code{cond_len_ashl@var{mode}} instruction pattern
7498 @cindex @code{cond_len_ashr@var{mode}} instruction pattern
7499 @cindex @code{cond_len_lshr@var{mode}} instruction pattern
7500 @item @samp{cond_len_add@var{mode}}
7501 @itemx @samp{cond_len_sub@var{mode}}
7502 @itemx @samp{cond_len_mul@var{mode}}
7503 @itemx @samp{cond_len_div@var{mode}}
7504 @itemx @samp{cond_len_udiv@var{mode}}
7505 @itemx @samp{cond_len_mod@var{mode}}
7506 @itemx @samp{cond_len_umod@var{mode}}
7507 @itemx @samp{cond_len_and@var{mode}}
7508 @itemx @samp{cond_len_ior@var{mode}}
7509 @itemx @samp{cond_len_xor@var{mode}}
7510 @itemx @samp{cond_len_smin@var{mode}}
7511 @itemx @samp{cond_len_smax@var{mode}}
7512 @itemx @samp{cond_len_umin@var{mode}}
7513 @itemx @samp{cond_len_umax@var{mode}}
7514 @itemx @samp{cond_len_copysign@var{mode}}
7515 @itemx @samp{cond_len_fmin@var{mode}}
7516 @itemx @samp{cond_len_fmax@var{mode}}
7517 @itemx @samp{cond_len_ashl@var{mode}}
7518 @itemx @samp{cond_len_ashr@var{mode}}
7519 @itemx @samp{cond_len_lshr@var{mode}}
7520 When operand 1 is true and element index < operand 5 + operand 6, perform an operation on operands 2 and 3 and
7521 store the result in operand 0, otherwise store operand 4 in operand 0.
7522 The operation only works for the operands are vectors.
7523
7524 @smallexample
7525 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
7526 op0[i] = (i < ops[5] + ops[6] && op1[i]
7527 ? op2[i] @var{op} op3[i]
7528 : op4[i]);
7529 @end smallexample
7530
7531 where, for example, @var{op} is @code{+} for @samp{cond_len_add@var{mode}}.
7532
7533 When defined for floating-point modes, the contents of @samp{op3[i]}
7534 are not interpreted if @samp{op1[i]} is false, just like they would not
7535 be in a normal C @samp{?:} condition.
7536
7537 Operands 0, 2, 3 and 4 all have mode @var{m}. Operand 1 is a scalar
7538 integer if @var{m} is scalar, otherwise it has the mode returned by
7539 @code{TARGET_VECTORIZE_GET_MASK_MODE}. Operand 5 has whichever
7540 integer mode the target prefers.
7541
7542 @samp{cond_len_@var{op}@var{mode}} generally corresponds to a conditional
7543 form of @samp{@var{op}@var{mode}3}. As an exception, the vector forms
7544 of shifts correspond to patterns like @code{vashl@var{mode}3} rather
7545 than patterns like @code{ashl@var{mode}3}.
7546
7547 @samp{cond_len_copysign@var{mode}} is only defined for floating point modes.
7548
7549 @cindex @code{cond_len_fma@var{mode}} instruction pattern
7550 @cindex @code{cond_len_fms@var{mode}} instruction pattern
7551 @cindex @code{cond_len_fnma@var{mode}} instruction pattern
7552 @cindex @code{cond_len_fnms@var{mode}} instruction pattern
7553 @item @samp{cond_len_fma@var{mode}}
7554 @itemx @samp{cond_len_fms@var{mode}}
7555 @itemx @samp{cond_len_fnma@var{mode}}
7556 @itemx @samp{cond_len_fnms@var{mode}}
7557 Like @samp{cond_len_add@var{m}}, except that the conditional operation
7558 takes 3 operands rather than two. For example, the vector form of
7559 @samp{cond_len_fma@var{mode}} is equivalent to:
7560
7561 @smallexample
7562 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
7563 op0[i] = (i < ops[6] + ops[7] && op1[i]
7564 ? fma (op2[i], op3[i], op4[i])
7565 : op5[i]);
7566 @end smallexample
7567
7568 @cindex @code{neg@var{mode}cc} instruction pattern
7569 @item @samp{neg@var{mode}cc}
7570 Similar to @samp{mov@var{mode}cc} but for conditional negation. Conditionally
7571 move the negation of operand 2 or the unchanged operand 3 into operand 0
7572 according to the comparison in operand 1. If the comparison is true, the negation
7573 of operand 2 is moved into operand 0, otherwise operand 3 is moved.
7574
7575 @cindex @code{not@var{mode}cc} instruction pattern
7576 @item @samp{not@var{mode}cc}
7577 Similar to @samp{neg@var{mode}cc} but for conditional complement.
7578 Conditionally move the bitwise complement of operand 2 or the unchanged
7579 operand 3 into operand 0 according to the comparison in operand 1.
7580 If the comparison is true, the complement of operand 2 is moved into
7581 operand 0, otherwise operand 3 is moved.
7582
7583 @cindex @code{cstore@var{mode}4} instruction pattern
7584 @item @samp{cstore@var{mode}4}
7585 Store zero or nonzero in operand 0 according to whether a comparison
7586 is true. Operand 1 is a comparison operator. Operand 2 and operand 3
7587 are the first and second operand of the comparison, respectively.
7588 You specify the mode that operand 0 must have when you write the
7589 @code{match_operand} expression. The compiler automatically sees which
7590 mode you have used and supplies an operand of that mode.
7591
7592 The value stored for a true condition must have 1 as its low bit, or
7593 else must be negative. Otherwise the instruction is not suitable and
7594 you should omit it from the machine description. You describe to the
7595 compiler exactly which value is stored by defining the macro
7596 @code{STORE_FLAG_VALUE} (@pxref{Misc}). If a description cannot be
7597 found that can be used for all the possible comparison operators, you
7598 should pick one and use a @code{define_expand} to map all results
7599 onto the one you chose.
7600
7601 These operations may @code{FAIL}, but should do so only in relatively
7602 uncommon cases; if they would @code{FAIL} for common cases involving
7603 integer comparisons, it is best to restrict the predicates to not
7604 allow these operands. Likewise if a given comparison operator will
7605 always fail, independent of the operands (for floating-point modes, the
7606 @code{ordered_comparison_operator} predicate is often useful in this case).
7607
7608 If this pattern is omitted, the compiler will generate a conditional
7609 branch---for example, it may copy a constant one to the target and branching
7610 around an assignment of zero to the target---or a libcall. If the predicate
7611 for operand 1 only rejects some operators, it will also try reordering the
7612 operands and/or inverting the result value (e.g.@: by an exclusive OR).
7613 These possibilities could be cheaper or equivalent to the instructions
7614 used for the @samp{cstore@var{mode}4} pattern followed by those required
7615 to convert a positive result from @code{STORE_FLAG_VALUE} to 1; in this
7616 case, you can and should make operand 1's predicate reject some operators
7617 in the @samp{cstore@var{mode}4} pattern, or remove the pattern altogether
7618 from the machine description.
7619
7620 @cindex @code{tbranch_@var{op}@var{mode}3} instruction pattern
7621 @item @samp{tbranch_@var{op}@var{mode}3}
7622 Conditional branch instruction combined with a bit test-and-compare
7623 instruction. Operand 0 is the operand of the comparison. Operand 1 is the bit
7624 position of Operand 1 to test. Operand 3 is the @code{code_label} to jump to.
7625 @var{op} is one of @var{eq} or @var{ne}.
7626
7627 @cindex @code{cbranch@var{mode}4} instruction pattern
7628 @item @samp{cbranch@var{mode}4}
7629 Conditional branch instruction combined with a compare instruction.
7630 Operand 0 is a comparison operator. Operand 1 and operand 2 are the
7631 first and second operands of the comparison, respectively. Operand 3
7632 is the @code{code_label} to jump to.
7633
7634 @cindex @code{jump} instruction pattern
7635 @item @samp{jump}
7636 A jump inside a function; an unconditional branch. Operand 0 is the
7637 @code{code_label} to jump to. This pattern name is mandatory on all
7638 machines.
7639
7640 @cindex @code{call} instruction pattern
7641 @item @samp{call}
7642 Subroutine call instruction returning no value. Operand 0 is the
7643 function to call; operand 1 is the number of bytes of arguments pushed
7644 as a @code{const_int}. Operand 2 is the result of calling the target
7645 hook @code{TARGET_FUNCTION_ARG} with the second argument @code{arg}
7646 yielding true for @code{arg.end_marker_p ()}, in a call after all
7647 parameters have been passed to that hook. By default this is the first
7648 register beyond those used for arguments in the call, or @code{NULL} if
7649 all the argument-registers are used in the call.
7650
7651 On most machines, operand 2 is not actually stored into the RTL
7652 pattern. It is supplied for the sake of some RISC machines which need
7653 to put this information into the assembler code; they can put it in
7654 the RTL instead of operand 1.
7655
7656 Operand 0 should be a @code{mem} RTX whose address is the address of the
7657 function. Note, however, that this address can be a @code{symbol_ref}
7658 expression even if it would not be a legitimate memory address on the
7659 target machine. If it is also not a valid argument for a call
7660 instruction, the pattern for this operation should be a
7661 @code{define_expand} (@pxref{Expander Definitions}) that places the
7662 address into a register and uses that register in the call instruction.
7663
7664 @cindex @code{call_value} instruction pattern
7665 @item @samp{call_value}
7666 Subroutine call instruction returning a value. Operand 0 is the hard
7667 register in which the value is returned. There are three more
7668 operands, the same as the three operands of the @samp{call}
7669 instruction (but with numbers increased by one).
7670
7671 Subroutines that return @code{BLKmode} objects use the @samp{call}
7672 insn.
7673
7674 @cindex @code{call_pop} instruction pattern
7675 @cindex @code{call_value_pop} instruction pattern
7676 @item @samp{call_pop}, @samp{call_value_pop}
7677 Similar to @samp{call} and @samp{call_value}, except used if defined and
7678 if @code{RETURN_POPS_ARGS} is nonzero. They should emit a @code{parallel}
7679 that contains both the function call and a @code{set} to indicate the
7680 adjustment made to the frame pointer.
7681
7682 For machines where @code{RETURN_POPS_ARGS} can be nonzero, the use of these
7683 patterns increases the number of functions for which the frame pointer
7684 can be eliminated, if desired.
7685
7686 @cindex @code{untyped_call} instruction pattern
7687 @item @samp{untyped_call}
7688 Subroutine call instruction returning a value of any type. Operand 0 is
7689 the function to call; operand 1 is a memory location where the result of
7690 calling the function is to be stored; operand 2 is a @code{parallel}
7691 expression where each element is a @code{set} expression that indicates
7692 the saving of a function return value into the result block.
7693
7694 This instruction pattern should be defined to support
7695 @code{__builtin_apply} on machines where special instructions are needed
7696 to call a subroutine with arbitrary arguments or to save the value
7697 returned. This instruction pattern is required on machines that have
7698 multiple registers that can hold a return value
7699 (i.e.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register).
7700
7701 @cindex @code{return} instruction pattern
7702 @item @samp{return}
7703 Subroutine return instruction. This instruction pattern name should be
7704 defined only if a single instruction can do all the work of returning
7705 from a function.
7706
7707 Like the @samp{mov@var{m}} patterns, this pattern is also used after the
7708 RTL generation phase. In this case it is to support machines where
7709 multiple instructions are usually needed to return from a function, but
7710 some class of functions only requires one instruction to implement a
7711 return. Normally, the applicable functions are those which do not need
7712 to save any registers or allocate stack space.
7713
7714 It is valid for this pattern to expand to an instruction using
7715 @code{simple_return} if no epilogue is required.
7716
7717 @cindex @code{simple_return} instruction pattern
7718 @item @samp{simple_return}
7719 Subroutine return instruction. This instruction pattern name should be
7720 defined only if a single instruction can do all the work of returning
7721 from a function on a path where no epilogue is required. This pattern
7722 is very similar to the @code{return} instruction pattern, but it is emitted
7723 only by the shrink-wrapping optimization on paths where the function
7724 prologue has not been executed, and a function return should occur without
7725 any of the effects of the epilogue. Additional uses may be introduced on
7726 paths where both the prologue and the epilogue have executed.
7727
7728 @findex reload_completed
7729 @findex leaf_function_p
7730 For such machines, the condition specified in this pattern should only
7731 be true when @code{reload_completed} is nonzero and the function's
7732 epilogue would only be a single instruction. For machines with register
7733 windows, the routine @code{leaf_function_p} may be used to determine if
7734 a register window push is required.
7735
7736 Machines that have conditional return instructions should define patterns
7737 such as
7738
7739 @smallexample
7740 (define_insn ""
7741 [(set (pc)
7742 (if_then_else (match_operator
7743 0 "comparison_operator"
7744 [(reg:CC CC_REG) (const_int 0)])
7745 (return)
7746 (pc)))]
7747 "@var{condition}"
7748 "@dots{}")
7749 @end smallexample
7750
7751 where @var{condition} would normally be the same condition specified on the
7752 named @samp{return} pattern.
7753
7754 @cindex @code{untyped_return} instruction pattern
7755 @item @samp{untyped_return}
7756 Untyped subroutine return instruction. This instruction pattern should
7757 be defined to support @code{__builtin_return} on machines where special
7758 instructions are needed to return a value of any type.
7759
7760 Operand 0 is a memory location where the result of calling a function
7761 with @code{__builtin_apply} is stored; operand 1 is a @code{parallel}
7762 expression where each element is a @code{set} expression that indicates
7763 the restoring of a function return value from the result block.
7764
7765 @cindex @code{nop} instruction pattern
7766 @item @samp{nop}
7767 No-op instruction. This instruction pattern name should always be defined
7768 to output a no-op in assembler code. @code{(const_int 0)} will do as an
7769 RTL pattern.
7770
7771 @cindex @code{indirect_jump} instruction pattern
7772 @item @samp{indirect_jump}
7773 An instruction to jump to an address which is operand zero.
7774 This pattern name is mandatory on all machines.
7775
7776 @cindex @code{casesi} instruction pattern
7777 @item @samp{casesi}
7778 Instruction to jump through a dispatch table, including bounds checking.
7779 This instruction takes five operands:
7780
7781 @enumerate
7782 @item
7783 The index to dispatch on, which has mode @code{SImode}.
7784
7785 @item
7786 The lower bound for indices in the table, an integer constant.
7787
7788 @item
7789 The total range of indices in the table---the largest index
7790 minus the smallest one (both inclusive).
7791
7792 @item
7793 A label that precedes the table itself.
7794
7795 @item
7796 A label to jump to if the index has a value outside the bounds.
7797 @end enumerate
7798
7799 The table is an @code{addr_vec} or @code{addr_diff_vec} inside of a
7800 @code{jump_table_data}. The number of elements in the table is one plus the
7801 difference between the upper bound and the lower bound.
7802
7803 @cindex @code{tablejump} instruction pattern
7804 @item @samp{tablejump}
7805 Instruction to jump to a variable address. This is a low-level
7806 capability which can be used to implement a dispatch table when there
7807 is no @samp{casesi} pattern.
7808
7809 This pattern requires two operands: the address or offset, and a label
7810 which should immediately precede the jump table. If the macro
7811 @code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first
7812 operand is an offset which counts from the address of the table; otherwise,
7813 it is an absolute address to jump to. In either case, the first operand has
7814 mode @code{Pmode}.
7815
7816 The @samp{tablejump} insn is always the last insn before the jump
7817 table it uses. Its assembler code normally has no need to use the
7818 second operand, but you should incorporate it in the RTL pattern so
7819 that the jump optimizer will not delete the table as unreachable code.
7820
7821
7822 @cindex @code{doloop_end} instruction pattern
7823 @item @samp{doloop_end}
7824 Conditional branch instruction that decrements a register and
7825 jumps if the register is nonzero. Operand 0 is the register to
7826 decrement and test; operand 1 is the label to jump to if the
7827 register is nonzero.
7828 @xref{Looping Patterns}.
7829
7830 This optional instruction pattern should be defined for machines with
7831 low-overhead looping instructions as the loop optimizer will try to
7832 modify suitable loops to utilize it. The target hook
7833 @code{TARGET_CAN_USE_DOLOOP_P} controls the conditions under which
7834 low-overhead loops can be used.
7835
7836 @cindex @code{doloop_begin} instruction pattern
7837 @item @samp{doloop_begin}
7838 Companion instruction to @code{doloop_end} required for machines that
7839 need to perform some initialization, such as loading a special counter
7840 register. Operand 1 is the associated @code{doloop_end} pattern and
7841 operand 0 is the register that it decrements.
7842
7843 If initialization insns do not always need to be emitted, use a
7844 @code{define_expand} (@pxref{Expander Definitions}) and make it fail.
7845
7846 @cindex @code{canonicalize_funcptr_for_compare} instruction pattern
7847 @item @samp{canonicalize_funcptr_for_compare}
7848 Canonicalize the function pointer in operand 1 and store the result
7849 into operand 0.
7850
7851 Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1
7852 may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc
7853 and also has mode @code{Pmode}.
7854
7855 Canonicalization of a function pointer usually involves computing
7856 the address of the function which would be called if the function
7857 pointer were used in an indirect call.
7858
7859 Only define this pattern if function pointers on the target machine
7860 can have different values but still call the same function when
7861 used in an indirect call.
7862
7863 @cindex @code{save_stack_block} instruction pattern
7864 @cindex @code{save_stack_function} instruction pattern
7865 @cindex @code{save_stack_nonlocal} instruction pattern
7866 @cindex @code{restore_stack_block} instruction pattern
7867 @cindex @code{restore_stack_function} instruction pattern
7868 @cindex @code{restore_stack_nonlocal} instruction pattern
7869 @item @samp{save_stack_block}
7870 @itemx @samp{save_stack_function}
7871 @itemx @samp{save_stack_nonlocal}
7872 @itemx @samp{restore_stack_block}
7873 @itemx @samp{restore_stack_function}
7874 @itemx @samp{restore_stack_nonlocal}
7875 Most machines save and restore the stack pointer by copying it to or
7876 from an object of mode @code{Pmode}. Do not define these patterns on
7877 such machines.
7878
7879 Some machines require special handling for stack pointer saves and
7880 restores. On those machines, define the patterns corresponding to the
7881 non-standard cases by using a @code{define_expand} (@pxref{Expander
7882 Definitions}) that produces the required insns. The three types of
7883 saves and restores are:
7884
7885 @enumerate
7886 @item
7887 @samp{save_stack_block} saves the stack pointer at the start of a block
7888 that allocates a variable-sized object, and @samp{restore_stack_block}
7889 restores the stack pointer when the block is exited.
7890
7891 @item
7892 @samp{save_stack_function} and @samp{restore_stack_function} do a
7893 similar job for the outermost block of a function and are used when the
7894 function allocates variable-sized objects or calls @code{alloca}. Only
7895 the epilogue uses the restored stack pointer, allowing a simpler save or
7896 restore sequence on some machines.
7897
7898 @item
7899 @samp{save_stack_nonlocal} is used in functions that contain labels
7900 branched to by nested functions. It saves the stack pointer in such a
7901 way that the inner function can use @samp{restore_stack_nonlocal} to
7902 restore the stack pointer. The compiler generates code to restore the
7903 frame and argument pointer registers, but some machines require saving
7904 and restoring additional data such as register window information or
7905 stack backchains. Place insns in these patterns to save and restore any
7906 such required data.
7907 @end enumerate
7908
7909 When saving the stack pointer, operand 0 is the save area and operand 1
7910 is the stack pointer. The mode used to allocate the save area defaults
7911 to @code{Pmode} but you can override that choice by defining the
7912 @code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}). You must
7913 specify an integral mode, or @code{VOIDmode} if no save area is needed
7914 for a particular type of save (either because no save is needed or
7915 because a machine-specific save area can be used). Operand 0 is the
7916 stack pointer and operand 1 is the save area for restore operations. If
7917 @samp{save_stack_block} is defined, operand 0 must not be
7918 @code{VOIDmode} since these saves can be arbitrarily nested.
7919
7920 A save area is a @code{mem} that is at a constant offset from
7921 @code{virtual_stack_vars_rtx} when the stack pointer is saved for use by
7922 nonlocal gotos and a @code{reg} in the other two cases.
7923
7924 @cindex @code{allocate_stack} instruction pattern
7925 @item @samp{allocate_stack}
7926 Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from
7927 the stack pointer to create space for dynamically allocated data.
7928
7929 Store the resultant pointer to this space into operand 0. If you
7930 are allocating space from the main stack, do this by emitting a
7931 move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0.
7932 If you are allocating the space elsewhere, generate code to copy the
7933 location of the space to operand 0. In the latter case, you must
7934 ensure this space gets freed when the corresponding space on the main
7935 stack is free.
7936
7937 Do not define this pattern if all that must be done is the subtraction.
7938 Some machines require other operations such as stack probes or
7939 maintaining the back chain. Define this pattern to emit those
7940 operations in addition to updating the stack pointer.
7941
7942 @cindex @code{check_stack} instruction pattern
7943 @item @samp{check_stack}
7944 If stack checking (@pxref{Stack Checking}) cannot be done on your system by
7945 probing the stack, define this pattern to perform the needed check and signal
7946 an error if the stack has overflowed. The single operand is the address in
7947 the stack farthest from the current stack pointer that you need to validate.
7948 Normally, on platforms where this pattern is needed, you would obtain the
7949 stack limit from a global or thread-specific variable or register.
7950
7951 @cindex @code{probe_stack_address} instruction pattern
7952 @item @samp{probe_stack_address}
7953 If stack checking (@pxref{Stack Checking}) can be done on your system by
7954 probing the stack but without the need to actually access it, define this
7955 pattern and signal an error if the stack has overflowed. The single operand
7956 is the memory address in the stack that needs to be probed.
7957
7958 @cindex @code{probe_stack} instruction pattern
7959 @item @samp{probe_stack}
7960 If stack checking (@pxref{Stack Checking}) can be done on your system by
7961 probing the stack but doing it with a ``store zero'' instruction is not valid
7962 or optimal, define this pattern to do the probing differently and signal an
7963 error if the stack has overflowed. The single operand is the memory reference
7964 in the stack that needs to be probed.
7965
7966 @cindex @code{nonlocal_goto} instruction pattern
7967 @item @samp{nonlocal_goto}
7968 Emit code to generate a non-local goto, e.g., a jump from one function
7969 to a label in an outer function. This pattern has four arguments,
7970 each representing a value to be used in the jump. The first
7971 argument is to be loaded into the frame pointer, the second is
7972 the address to branch to (code to dispatch to the actual label),
7973 the third is the address of a location where the stack is saved,
7974 and the last is the address of the label, to be placed in the
7975 location for the incoming static chain.
7976
7977 On most machines you need not define this pattern, since GCC will
7978 already generate the correct code, which is to load the frame pointer
7979 and static chain, restore the stack (using the
7980 @samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly
7981 to the dispatcher. You need only define this pattern if this code will
7982 not work on your machine.
7983
7984 @cindex @code{nonlocal_goto_receiver} instruction pattern
7985 @item @samp{nonlocal_goto_receiver}
7986 This pattern, if defined, contains code needed at the target of a
7987 nonlocal goto after the code already generated by GCC@. You will not
7988 normally need to define this pattern. A typical reason why you might
7989 need this pattern is if some value, such as a pointer to a global table,
7990 must be restored when the frame pointer is restored. Note that a nonlocal
7991 goto only occurs within a unit-of-translation, so a global table pointer
7992 that is shared by all functions of a given module need not be restored.
7993 There are no arguments.
7994
7995 @cindex @code{exception_receiver} instruction pattern
7996 @item @samp{exception_receiver}
7997 This pattern, if defined, contains code needed at the site of an
7998 exception handler that isn't needed at the site of a nonlocal goto. You
7999 will not normally need to define this pattern. A typical reason why you
8000 might need this pattern is if some value, such as a pointer to a global
8001 table, must be restored after control flow is branched to the handler of
8002 an exception. There are no arguments.
8003
8004 @cindex @code{builtin_setjmp_setup} instruction pattern
8005 @item @samp{builtin_setjmp_setup}
8006 This pattern, if defined, contains additional code needed to initialize
8007 the @code{jmp_buf}. You will not normally need to define this pattern.
8008 A typical reason why you might need this pattern is if some value, such
8009 as a pointer to a global table, must be restored. Though it is
8010 preferred that the pointer value be recalculated if possible (given the
8011 address of a label for instance). The single argument is a pointer to
8012 the @code{jmp_buf}. Note that the buffer is five words long and that
8013 the first three are normally used by the generic mechanism.
8014
8015 @cindex @code{builtin_setjmp_receiver} instruction pattern
8016 @item @samp{builtin_setjmp_receiver}
8017 This pattern, if defined, contains code needed at the site of a
8018 built-in setjmp that isn't needed at the site of a nonlocal goto. You
8019 will not normally need to define this pattern. A typical reason why you
8020 might need this pattern is if some value, such as a pointer to a global
8021 table, must be restored. It takes one argument, which is the label
8022 to which builtin_longjmp transferred control; this pattern may be emitted
8023 at a small offset from that label.
8024
8025 @cindex @code{builtin_longjmp} instruction pattern
8026 @item @samp{builtin_longjmp}
8027 This pattern, if defined, performs the entire action of the longjmp.
8028 You will not normally need to define this pattern unless you also define
8029 @code{builtin_setjmp_setup}. The single argument is a pointer to the
8030 @code{jmp_buf}.
8031
8032 @cindex @code{eh_return} instruction pattern
8033 @item @samp{eh_return}
8034 This pattern, if defined, affects the way @code{__builtin_eh_return},
8035 and thence the call frame exception handling library routines, are
8036 built. It is intended to handle non-trivial actions needed along
8037 the abnormal return path.
8038
8039 The address of the exception handler to which the function should return
8040 is passed as operand to this pattern. It will normally need to copied by
8041 the pattern to some special register or memory location.
8042 If the pattern needs to determine the location of the target call
8043 frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX},
8044 if defined; it will have already been assigned.
8045
8046 If this pattern is not defined, the default action will be to simply
8047 copy the return address to @code{EH_RETURN_HANDLER_RTX}. Either
8048 that macro or this pattern needs to be defined if call frame exception
8049 handling is to be used.
8050
8051 @cindex @code{prologue} instruction pattern
8052 @anchor{prologue instruction pattern}
8053 @item @samp{prologue}
8054 This pattern, if defined, emits RTL for entry to a function. The function
8055 entry is responsible for setting up the stack frame, initializing the frame
8056 pointer register, saving callee saved registers, etc.
8057
8058 Using a prologue pattern is generally preferred over defining
8059 @code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue.
8060
8061 The @code{prologue} pattern is particularly useful for targets which perform
8062 instruction scheduling.
8063
8064 @cindex @code{window_save} instruction pattern
8065 @anchor{window_save instruction pattern}
8066 @item @samp{window_save}
8067 This pattern, if defined, emits RTL for a register window save. It should
8068 be defined if the target machine has register windows but the window events
8069 are decoupled from calls to subroutines. The canonical example is the SPARC
8070 architecture.
8071
8072 @cindex @code{epilogue} instruction pattern
8073 @anchor{epilogue instruction pattern}
8074 @item @samp{epilogue}
8075 This pattern emits RTL for exit from a function. The function
8076 exit is responsible for deallocating the stack frame, restoring callee saved
8077 registers and emitting the return instruction.
8078
8079 Using an epilogue pattern is generally preferred over defining
8080 @code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue.
8081
8082 The @code{epilogue} pattern is particularly useful for targets which perform
8083 instruction scheduling or which have delay slots for their return instruction.
8084
8085 @cindex @code{sibcall_epilogue} instruction pattern
8086 @item @samp{sibcall_epilogue}
8087 This pattern, if defined, emits RTL for exit from a function without the final
8088 branch back to the calling function. This pattern will be emitted before any
8089 sibling call (aka tail call) sites.
8090
8091 The @code{sibcall_epilogue} pattern must not clobber any arguments used for
8092 parameter passing or any stack slots for arguments passed to the current
8093 function.
8094
8095 @cindex @code{trap} instruction pattern
8096 @item @samp{trap}
8097 This pattern, if defined, signals an error, typically by causing some
8098 kind of signal to be raised.
8099
8100 @cindex @code{ctrap@var{MM}4} instruction pattern
8101 @item @samp{ctrap@var{MM}4}
8102 Conditional trap instruction. Operand 0 is a piece of RTL which
8103 performs a comparison, and operands 1 and 2 are the arms of the
8104 comparison. Operand 3 is the trap code, an integer.
8105
8106 A typical @code{ctrap} pattern looks like
8107
8108 @smallexample
8109 (define_insn "ctrapsi4"
8110 [(trap_if (match_operator 0 "trap_operator"
8111 [(match_operand 1 "register_operand")
8112 (match_operand 2 "immediate_operand")])
8113 (match_operand 3 "const_int_operand" "i"))]
8114 ""
8115 "@dots{}")
8116 @end smallexample
8117
8118 @cindex @code{prefetch} instruction pattern
8119 @item @samp{prefetch}
8120 This pattern, if defined, emits code for a non-faulting data prefetch
8121 instruction. Operand 0 is the address of the memory to prefetch. Operand 1
8122 is a constant 1 if the prefetch is preparing for a write to the memory
8123 address, or a constant 0 otherwise. Operand 2 is the expected degree of
8124 temporal locality of the data and is a value between 0 and 3, inclusive; 0
8125 means that the data has no temporal locality, so it need not be left in the
8126 cache after the access; 3 means that the data has a high degree of temporal
8127 locality and should be left in all levels of cache possible; 1 and 2 mean,
8128 respectively, a low or moderate degree of temporal locality.
8129
8130 Targets that do not support write prefetches or locality hints can ignore
8131 the values of operands 1 and 2.
8132
8133 @cindex @code{blockage} instruction pattern
8134 @item @samp{blockage}
8135 This pattern defines a pseudo insn that prevents the instruction
8136 scheduler and other passes from moving instructions and using register
8137 equivalences across the boundary defined by the blockage insn.
8138 This needs to be an UNSPEC_VOLATILE pattern or a volatile ASM.
8139
8140 @cindex @code{memory_blockage} instruction pattern
8141 @item @samp{memory_blockage}
8142 This pattern, if defined, represents a compiler memory barrier, and will be
8143 placed at points across which RTL passes may not propagate memory accesses.
8144 This instruction needs to read and write volatile BLKmode memory. It does
8145 not need to generate any machine instruction. If this pattern is not defined,
8146 the compiler falls back to emitting an instruction corresponding
8147 to @code{asm volatile ("" ::: "memory")}.
8148
8149 @cindex @code{memory_barrier} instruction pattern
8150 @item @samp{memory_barrier}
8151 If the target memory model is not fully synchronous, then this pattern
8152 should be defined to an instruction that orders both loads and stores
8153 before the instruction with respect to loads and stores after the instruction.
8154 This pattern has no operands.
8155
8156 @cindex @code{speculation_barrier} instruction pattern
8157 @item @samp{speculation_barrier}
8158 If the target can support speculative execution, then this pattern should
8159 be defined to an instruction that will block subsequent execution until
8160 any prior speculation conditions has been resolved. The pattern must also
8161 ensure that the compiler cannot move memory operations past the barrier,
8162 so it needs to be an UNSPEC_VOLATILE pattern. The pattern has no
8163 operands.
8164
8165 If this pattern is not defined then the default expansion of
8166 @code{__builtin_speculation_safe_value} will emit a warning. You can
8167 suppress this warning by defining this pattern with a final condition
8168 of @code{0} (zero), which tells the compiler that a speculation
8169 barrier is not needed for this target.
8170
8171 @cindex @code{sync_compare_and_swap@var{mode}} instruction pattern
8172 @item @samp{sync_compare_and_swap@var{mode}}
8173 This pattern, if defined, emits code for an atomic compare-and-swap
8174 operation. Operand 1 is the memory on which the atomic operation is
8175 performed. Operand 2 is the ``old'' value to be compared against the
8176 current contents of the memory location. Operand 3 is the ``new'' value
8177 to store in the memory if the compare succeeds. Operand 0 is the result
8178 of the operation; it should contain the contents of the memory
8179 before the operation. If the compare succeeds, this should obviously be
8180 a copy of operand 2.
8181
8182 This pattern must show that both operand 0 and operand 1 are modified.
8183
8184 This pattern must issue any memory barrier instructions such that all
8185 memory operations before the atomic operation occur before the atomic
8186 operation and all memory operations after the atomic operation occur
8187 after the atomic operation.
8188
8189 For targets where the success or failure of the compare-and-swap
8190 operation is available via the status flags, it is possible to
8191 avoid a separate compare operation and issue the subsequent
8192 branch or store-flag operation immediately after the compare-and-swap.
8193 To this end, GCC will look for a @code{MODE_CC} set in the
8194 output of @code{sync_compare_and_swap@var{mode}}; if the machine
8195 description includes such a set, the target should also define special
8196 @code{cbranchcc4} and/or @code{cstorecc4} instructions. GCC will then
8197 be able to take the destination of the @code{MODE_CC} set and pass it
8198 to the @code{cbranchcc4} or @code{cstorecc4} pattern as the first
8199 operand of the comparison (the second will be @code{(const_int 0)}).
8200
8201 For targets where the operating system may provide support for this
8202 operation via library calls, the @code{sync_compare_and_swap_optab}
8203 may be initialized to a function with the same interface as the
8204 @code{__sync_val_compare_and_swap_@var{n}} built-in. If the entire
8205 set of @var{__sync} builtins are supported via library calls, the
8206 target can initialize all of the optabs at once with
8207 @code{init_sync_libfuncs}.
8208 For the purposes of C++11 @code{std::atomic::is_lock_free}, it is
8209 assumed that these library calls do @emph{not} use any kind of
8210 interruptable locking.
8211
8212 @cindex @code{sync_add@var{mode}} instruction pattern
8213 @cindex @code{sync_sub@var{mode}} instruction pattern
8214 @cindex @code{sync_ior@var{mode}} instruction pattern
8215 @cindex @code{sync_and@var{mode}} instruction pattern
8216 @cindex @code{sync_xor@var{mode}} instruction pattern
8217 @cindex @code{sync_nand@var{mode}} instruction pattern
8218 @item @samp{sync_add@var{mode}}, @samp{sync_sub@var{mode}}
8219 @itemx @samp{sync_ior@var{mode}}, @samp{sync_and@var{mode}}
8220 @itemx @samp{sync_xor@var{mode}}, @samp{sync_nand@var{mode}}
8221 These patterns emit code for an atomic operation on memory.
8222 Operand 0 is the memory on which the atomic operation is performed.
8223 Operand 1 is the second operand to the binary operator.
8224
8225 This pattern must issue any memory barrier instructions such that all
8226 memory operations before the atomic operation occur before the atomic
8227 operation and all memory operations after the atomic operation occur
8228 after the atomic operation.
8229
8230 If these patterns are not defined, the operation will be constructed
8231 from a compare-and-swap operation, if defined.
8232
8233 @cindex @code{sync_old_add@var{mode}} instruction pattern
8234 @cindex @code{sync_old_sub@var{mode}} instruction pattern
8235 @cindex @code{sync_old_ior@var{mode}} instruction pattern
8236 @cindex @code{sync_old_and@var{mode}} instruction pattern
8237 @cindex @code{sync_old_xor@var{mode}} instruction pattern
8238 @cindex @code{sync_old_nand@var{mode}} instruction pattern
8239 @item @samp{sync_old_add@var{mode}}, @samp{sync_old_sub@var{mode}}
8240 @itemx @samp{sync_old_ior@var{mode}}, @samp{sync_old_and@var{mode}}
8241 @itemx @samp{sync_old_xor@var{mode}}, @samp{sync_old_nand@var{mode}}
8242 These patterns emit code for an atomic operation on memory,
8243 and return the value that the memory contained before the operation.
8244 Operand 0 is the result value, operand 1 is the memory on which the
8245 atomic operation is performed, and operand 2 is the second operand
8246 to the binary operator.
8247
8248 This pattern must issue any memory barrier instructions such that all
8249 memory operations before the atomic operation occur before the atomic
8250 operation and all memory operations after the atomic operation occur
8251 after the atomic operation.
8252
8253 If these patterns are not defined, the operation will be constructed
8254 from a compare-and-swap operation, if defined.
8255
8256 @cindex @code{sync_new_add@var{mode}} instruction pattern
8257 @cindex @code{sync_new_sub@var{mode}} instruction pattern
8258 @cindex @code{sync_new_ior@var{mode}} instruction pattern
8259 @cindex @code{sync_new_and@var{mode}} instruction pattern
8260 @cindex @code{sync_new_xor@var{mode}} instruction pattern
8261 @cindex @code{sync_new_nand@var{mode}} instruction pattern
8262 @item @samp{sync_new_add@var{mode}}, @samp{sync_new_sub@var{mode}}
8263 @itemx @samp{sync_new_ior@var{mode}}, @samp{sync_new_and@var{mode}}
8264 @itemx @samp{sync_new_xor@var{mode}}, @samp{sync_new_nand@var{mode}}
8265 These patterns are like their @code{sync_old_@var{op}} counterparts,
8266 except that they return the value that exists in the memory location
8267 after the operation, rather than before the operation.
8268
8269 @cindex @code{sync_lock_test_and_set@var{mode}} instruction pattern
8270 @item @samp{sync_lock_test_and_set@var{mode}}
8271 This pattern takes two forms, based on the capabilities of the target.
8272 In either case, operand 0 is the result of the operand, operand 1 is
8273 the memory on which the atomic operation is performed, and operand 2
8274 is the value to set in the lock.
8275
8276 In the ideal case, this operation is an atomic exchange operation, in
8277 which the previous value in memory operand is copied into the result
8278 operand, and the value operand is stored in the memory operand.
8279
8280 For less capable targets, any value operand that is not the constant 1
8281 should be rejected with @code{FAIL}. In this case the target may use
8282 an atomic test-and-set bit operation. The result operand should contain
8283 1 if the bit was previously set and 0 if the bit was previously clear.
8284 The true contents of the memory operand are implementation defined.
8285
8286 This pattern must issue any memory barrier instructions such that the
8287 pattern as a whole acts as an acquire barrier, that is all memory
8288 operations after the pattern do not occur until the lock is acquired.
8289
8290 If this pattern is not defined, the operation will be constructed from
8291 a compare-and-swap operation, if defined.
8292
8293 @cindex @code{sync_lock_release@var{mode}} instruction pattern
8294 @item @samp{sync_lock_release@var{mode}}
8295 This pattern, if defined, releases a lock set by
8296 @code{sync_lock_test_and_set@var{mode}}. Operand 0 is the memory
8297 that contains the lock; operand 1 is the value to store in the lock.
8298
8299 If the target doesn't implement full semantics for
8300 @code{sync_lock_test_and_set@var{mode}}, any value operand which is not
8301 the constant 0 should be rejected with @code{FAIL}, and the true contents
8302 of the memory operand are implementation defined.
8303
8304 This pattern must issue any memory barrier instructions such that the
8305 pattern as a whole acts as a release barrier, that is the lock is
8306 released only after all previous memory operations have completed.
8307
8308 If this pattern is not defined, then a @code{memory_barrier} pattern
8309 will be emitted, followed by a store of the value to the memory operand.
8310
8311 @cindex @code{atomic_compare_and_swap@var{mode}} instruction pattern
8312 @item @samp{atomic_compare_and_swap@var{mode}}
8313 This pattern, if defined, emits code for an atomic compare-and-swap
8314 operation with memory model semantics. Operand 2 is the memory on which
8315 the atomic operation is performed. Operand 0 is an output operand which
8316 is set to true or false based on whether the operation succeeded. Operand
8317 1 is an output operand which is set to the contents of the memory before
8318 the operation was attempted. Operand 3 is the value that is expected to
8319 be in memory. Operand 4 is the value to put in memory if the expected
8320 value is found there. Operand 5 is set to 1 if this compare and swap is to
8321 be treated as a weak operation. Operand 6 is the memory model to be used
8322 if the operation is a success. Operand 7 is the memory model to be used
8323 if the operation fails.
8324
8325 If memory referred to in operand 2 contains the value in operand 3, then
8326 operand 4 is stored in memory pointed to by operand 2 and fencing based on
8327 the memory model in operand 6 is issued.
8328
8329 If memory referred to in operand 2 does not contain the value in operand 3,
8330 then fencing based on the memory model in operand 7 is issued.
8331
8332 If a target does not support weak compare-and-swap operations, or the port
8333 elects not to implement weak operations, the argument in operand 5 can be
8334 ignored. Note a strong implementation must be provided.
8335
8336 If this pattern is not provided, the @code{__atomic_compare_exchange}
8337 built-in functions will utilize the legacy @code{sync_compare_and_swap}
8338 pattern with an @code{__ATOMIC_SEQ_CST} memory model.
8339
8340 @cindex @code{atomic_load@var{mode}} instruction pattern
8341 @item @samp{atomic_load@var{mode}}
8342 This pattern implements an atomic load operation with memory model
8343 semantics. Operand 1 is the memory address being loaded from. Operand 0
8344 is the result of the load. Operand 2 is the memory model to be used for
8345 the load operation.
8346
8347 If not present, the @code{__atomic_load} built-in function will either
8348 resort to a normal load with memory barriers, or a compare-and-swap
8349 operation if a normal load would not be atomic.
8350
8351 @cindex @code{atomic_store@var{mode}} instruction pattern
8352 @item @samp{atomic_store@var{mode}}
8353 This pattern implements an atomic store operation with memory model
8354 semantics. Operand 0 is the memory address being stored to. Operand 1
8355 is the value to be written. Operand 2 is the memory model to be used for
8356 the operation.
8357
8358 If not present, the @code{__atomic_store} built-in function will attempt to
8359 perform a normal store and surround it with any required memory fences. If
8360 the store would not be atomic, then an @code{__atomic_exchange} is
8361 attempted with the result being ignored.
8362
8363 @cindex @code{atomic_exchange@var{mode}} instruction pattern
8364 @item @samp{atomic_exchange@var{mode}}
8365 This pattern implements an atomic exchange operation with memory model
8366 semantics. Operand 1 is the memory location the operation is performed on.
8367 Operand 0 is an output operand which is set to the original value contained
8368 in the memory pointed to by operand 1. Operand 2 is the value to be
8369 stored. Operand 3 is the memory model to be used.
8370
8371 If this pattern is not present, the built-in function
8372 @code{__atomic_exchange} will attempt to preform the operation with a
8373 compare and swap loop.
8374
8375 @cindex @code{atomic_add@var{mode}} instruction pattern
8376 @cindex @code{atomic_sub@var{mode}} instruction pattern
8377 @cindex @code{atomic_or@var{mode}} instruction pattern
8378 @cindex @code{atomic_and@var{mode}} instruction pattern
8379 @cindex @code{atomic_xor@var{mode}} instruction pattern
8380 @cindex @code{atomic_nand@var{mode}} instruction pattern
8381 @item @samp{atomic_add@var{mode}}, @samp{atomic_sub@var{mode}}
8382 @itemx @samp{atomic_or@var{mode}}, @samp{atomic_and@var{mode}}
8383 @itemx @samp{atomic_xor@var{mode}}, @samp{atomic_nand@var{mode}}
8384 These patterns emit code for an atomic operation on memory with memory
8385 model semantics. Operand 0 is the memory on which the atomic operation is
8386 performed. Operand 1 is the second operand to the binary operator.
8387 Operand 2 is the memory model to be used by the operation.
8388
8389 If these patterns are not defined, attempts will be made to use legacy
8390 @code{sync} patterns, or equivalent patterns which return a result. If
8391 none of these are available a compare-and-swap loop will be used.
8392
8393 @cindex @code{atomic_fetch_add@var{mode}} instruction pattern
8394 @cindex @code{atomic_fetch_sub@var{mode}} instruction pattern
8395 @cindex @code{atomic_fetch_or@var{mode}} instruction pattern
8396 @cindex @code{atomic_fetch_and@var{mode}} instruction pattern
8397 @cindex @code{atomic_fetch_xor@var{mode}} instruction pattern
8398 @cindex @code{atomic_fetch_nand@var{mode}} instruction pattern
8399 @item @samp{atomic_fetch_add@var{mode}}, @samp{atomic_fetch_sub@var{mode}}
8400 @itemx @samp{atomic_fetch_or@var{mode}}, @samp{atomic_fetch_and@var{mode}}
8401 @itemx @samp{atomic_fetch_xor@var{mode}}, @samp{atomic_fetch_nand@var{mode}}
8402 These patterns emit code for an atomic operation on memory with memory
8403 model semantics, and return the original value. Operand 0 is an output
8404 operand which contains the value of the memory location before the
8405 operation was performed. Operand 1 is the memory on which the atomic
8406 operation is performed. Operand 2 is the second operand to the binary
8407 operator. Operand 3 is the memory model to be used by the operation.
8408
8409 If these patterns are not defined, attempts will be made to use legacy
8410 @code{sync} patterns. If none of these are available a compare-and-swap
8411 loop will be used.
8412
8413 @cindex @code{atomic_add_fetch@var{mode}} instruction pattern
8414 @cindex @code{atomic_sub_fetch@var{mode}} instruction pattern
8415 @cindex @code{atomic_or_fetch@var{mode}} instruction pattern
8416 @cindex @code{atomic_and_fetch@var{mode}} instruction pattern
8417 @cindex @code{atomic_xor_fetch@var{mode}} instruction pattern
8418 @cindex @code{atomic_nand_fetch@var{mode}} instruction pattern
8419 @item @samp{atomic_add_fetch@var{mode}}, @samp{atomic_sub_fetch@var{mode}}
8420 @itemx @samp{atomic_or_fetch@var{mode}}, @samp{atomic_and_fetch@var{mode}}
8421 @itemx @samp{atomic_xor_fetch@var{mode}}, @samp{atomic_nand_fetch@var{mode}}
8422 These patterns emit code for an atomic operation on memory with memory
8423 model semantics and return the result after the operation is performed.
8424 Operand 0 is an output operand which contains the value after the
8425 operation. Operand 1 is the memory on which the atomic operation is
8426 performed. Operand 2 is the second operand to the binary operator.
8427 Operand 3 is the memory model to be used by the operation.
8428
8429 If these patterns are not defined, attempts will be made to use legacy
8430 @code{sync} patterns, or equivalent patterns which return the result before
8431 the operation followed by the arithmetic operation required to produce the
8432 result. If none of these are available a compare-and-swap loop will be
8433 used.
8434
8435 @cindex @code{atomic_test_and_set} instruction pattern
8436 @item @samp{atomic_test_and_set}
8437 This pattern emits code for @code{__builtin_atomic_test_and_set}.
8438 Operand 0 is an output operand which is set to true if the previous
8439 previous contents of the byte was "set", and false otherwise. Operand 1
8440 is the @code{QImode} memory to be modified. Operand 2 is the memory
8441 model to be used.
8442
8443 The specific value that defines "set" is implementation defined, and
8444 is normally based on what is performed by the native atomic test and set
8445 instruction.
8446
8447 @cindex @code{atomic_bit_test_and_set@var{mode}} instruction pattern
8448 @cindex @code{atomic_bit_test_and_complement@var{mode}} instruction pattern
8449 @cindex @code{atomic_bit_test_and_reset@var{mode}} instruction pattern
8450 @item @samp{atomic_bit_test_and_set@var{mode}}
8451 @itemx @samp{atomic_bit_test_and_complement@var{mode}}
8452 @itemx @samp{atomic_bit_test_and_reset@var{mode}}
8453 These patterns emit code for an atomic bitwise operation on memory with memory
8454 model semantics, and return the original value of the specified bit.
8455 Operand 0 is an output operand which contains the value of the specified bit
8456 from the memory location before the operation was performed. Operand 1 is the
8457 memory on which the atomic operation is performed. Operand 2 is the bit within
8458 the operand, starting with least significant bit. Operand 3 is the memory model
8459 to be used by the operation. Operand 4 is a flag - it is @code{const1_rtx}
8460 if operand 0 should contain the original value of the specified bit in the
8461 least significant bit of the operand, and @code{const0_rtx} if the bit should
8462 be in its original position in the operand.
8463 @code{atomic_bit_test_and_set@var{mode}} atomically sets the specified bit after
8464 remembering its original value, @code{atomic_bit_test_and_complement@var{mode}}
8465 inverts the specified bit and @code{atomic_bit_test_and_reset@var{mode}} clears
8466 the specified bit.
8467
8468 If these patterns are not defined, attempts will be made to use
8469 @code{atomic_fetch_or@var{mode}}, @code{atomic_fetch_xor@var{mode}} or
8470 @code{atomic_fetch_and@var{mode}} instruction patterns, or their @code{sync}
8471 counterparts. If none of these are available a compare-and-swap
8472 loop will be used.
8473
8474 @cindex @code{atomic_add_fetch_cmp_0@var{mode}} instruction pattern
8475 @cindex @code{atomic_sub_fetch_cmp_0@var{mode}} instruction pattern
8476 @cindex @code{atomic_and_fetch_cmp_0@var{mode}} instruction pattern
8477 @cindex @code{atomic_or_fetch_cmp_0@var{mode}} instruction pattern
8478 @cindex @code{atomic_xor_fetch_cmp_0@var{mode}} instruction pattern
8479 @item @samp{atomic_add_fetch_cmp_0@var{mode}}
8480 @itemx @samp{atomic_sub_fetch_cmp_0@var{mode}}
8481 @itemx @samp{atomic_and_fetch_cmp_0@var{mode}}
8482 @itemx @samp{atomic_or_fetch_cmp_0@var{mode}}
8483 @itemx @samp{atomic_xor_fetch_cmp_0@var{mode}}
8484 These patterns emit code for an atomic operation on memory with memory
8485 model semantics if the fetch result is used only in a comparison against
8486 zero.
8487 Operand 0 is an output operand which contains a boolean result of comparison
8488 of the value after the operation against zero. Operand 1 is the memory on
8489 which the atomic operation is performed. Operand 2 is the second operand
8490 to the binary operator. Operand 3 is the memory model to be used by the
8491 operation. Operand 4 is an integer holding the comparison code, one of
8492 @code{EQ}, @code{NE}, @code{LT}, @code{GT}, @code{LE} or @code{GE}.
8493
8494 If these patterns are not defined, attempts will be made to use separate
8495 atomic operation and fetch pattern followed by comparison of the result
8496 against zero.
8497
8498 @cindex @code{mem_thread_fence} instruction pattern
8499 @item @samp{mem_thread_fence}
8500 This pattern emits code required to implement a thread fence with
8501 memory model semantics. Operand 0 is the memory model to be used.
8502
8503 For the @code{__ATOMIC_RELAXED} model no instructions need to be issued
8504 and this expansion is not invoked.
8505
8506 The compiler always emits a compiler memory barrier regardless of what
8507 expanding this pattern produced.
8508
8509 If this pattern is not defined, the compiler falls back to expanding the
8510 @code{memory_barrier} pattern, then to emitting @code{__sync_synchronize}
8511 library call, and finally to just placing a compiler memory barrier.
8512
8513 @cindex @code{get_thread_pointer@var{mode}} instruction pattern
8514 @cindex @code{set_thread_pointer@var{mode}} instruction pattern
8515 @item @samp{get_thread_pointer@var{mode}}
8516 @itemx @samp{set_thread_pointer@var{mode}}
8517 These patterns emit code that reads/sets the TLS thread pointer. Currently,
8518 these are only needed if the target needs to support the
8519 @code{__builtin_thread_pointer} and @code{__builtin_set_thread_pointer}
8520 builtins.
8521
8522 The get/set patterns have a single output/input operand respectively,
8523 with @var{mode} intended to be @code{Pmode}.
8524
8525 @cindex @code{stack_protect_combined_set} instruction pattern
8526 @item @samp{stack_protect_combined_set}
8527 This pattern, if defined, moves a @code{ptr_mode} value from an address
8528 whose declaration RTX is given in operand 1 to the memory in operand 0
8529 without leaving the value in a register afterward. If several
8530 instructions are needed by the target to perform the operation (eg. to
8531 load the address from a GOT entry then load the @code{ptr_mode} value
8532 and finally store it), it is the backend's responsibility to ensure no
8533 intermediate result gets spilled. This is to avoid leaking the value
8534 some place that an attacker might use to rewrite the stack guard slot
8535 after having clobbered it.
8536
8537 If this pattern is not defined, then the address declaration is
8538 expanded first in the standard way and a @code{stack_protect_set}
8539 pattern is then generated to move the value from that address to the
8540 address in operand 0.
8541
8542 @cindex @code{stack_protect_set} instruction pattern
8543 @item @samp{stack_protect_set}
8544 This pattern, if defined, moves a @code{ptr_mode} value from the valid
8545 memory location in operand 1 to the memory in operand 0 without leaving
8546 the value in a register afterward. This is to avoid leaking the value
8547 some place that an attacker might use to rewrite the stack guard slot
8548 after having clobbered it.
8549
8550 Note: on targets where the addressing modes do not allow to load
8551 directly from stack guard address, the address is expanded in a standard
8552 way first which could cause some spills.
8553
8554 If this pattern is not defined, then a plain move pattern is generated.
8555
8556 @cindex @code{stack_protect_combined_test} instruction pattern
8557 @item @samp{stack_protect_combined_test}
8558 This pattern, if defined, compares a @code{ptr_mode} value from an
8559 address whose declaration RTX is given in operand 1 with the memory in
8560 operand 0 without leaving the value in a register afterward and
8561 branches to operand 2 if the values were equal. If several
8562 instructions are needed by the target to perform the operation (eg. to
8563 load the address from a GOT entry then load the @code{ptr_mode} value
8564 and finally store it), it is the backend's responsibility to ensure no
8565 intermediate result gets spilled. This is to avoid leaking the value
8566 some place that an attacker might use to rewrite the stack guard slot
8567 after having clobbered it.
8568
8569 If this pattern is not defined, then the address declaration is
8570 expanded first in the standard way and a @code{stack_protect_test}
8571 pattern is then generated to compare the value from that address to the
8572 value at the memory in operand 0.
8573
8574 @cindex @code{stack_protect_test} instruction pattern
8575 @item @samp{stack_protect_test}
8576 This pattern, if defined, compares a @code{ptr_mode} value from the
8577 valid memory location in operand 1 with the memory in operand 0 without
8578 leaving the value in a register afterward and branches to operand 2 if
8579 the values were equal.
8580
8581 If this pattern is not defined, then a plain compare pattern and
8582 conditional branch pattern is used.
8583
8584 @cindex @code{clear_cache} instruction pattern
8585 @item @samp{clear_cache}
8586 This pattern, if defined, flushes the instruction cache for a region of
8587 memory. The region is bounded to by the Pmode pointers in operand 0
8588 inclusive and operand 1 exclusive.
8589
8590 If this pattern is not defined, a call to the library function
8591 @code{__clear_cache} is used.
8592
8593 @cindex @code{spaceship@var{m}4} instruction pattern
8594 @item @samp{spaceship@var{m}4}
8595 Initialize output operand 0 with mode of integer type to -1, 0, 1 or 2
8596 if operand 1 with mode @var{m} compares less than operand 2, equal to
8597 operand 2, greater than operand 2 or is unordered with operand 2.
8598 Operand 3 should be @code{const0_rtx} if the result is used in comparisons,
8599 @code{const1_rtx} if the result is used as integer value and the comparison
8600 is integral unsigned, @code{constm1_rtx} if the result is used as integer
8601 value and the comparison is integral signed and some other @code{CONST_INT}
8602 if the result is used as integer value and the comparison is floating point.
8603 In the last case, instead of setting output operand 0 to 2 for unordered,
8604 set it to operand 3.
8605 @var{m} should be a scalar floating point mode.
8606
8607 This pattern is not allowed to @code{FAIL}.
8608
8609 @cindex @code{isfinite@var{m}2} instruction pattern
8610 @item @samp{isfinite@var{m}2}
8611 Return 1 if operand 1 is a finite floating point number and 0
8612 otherwise. @var{m} is a scalar floating point mode. Operand 0
8613 has mode @code{SImode}, and operand 1 has mode @var{m}.
8614
8615 @cindex @code{isnormal@var{m}2} instruction pattern
8616 @item @samp{isnormal@var{m}2}
8617 Return 1 if operand 1 is a normal floating point number and 0
8618 otherwise. @var{m} is a scalar floating point mode. Operand 0
8619 has mode @code{SImode}, and operand 1 has mode @var{m}.
8620
8621 @cindex @code{crc@var{m}@var{n}4} instruction pattern
8622 @item @samp{crc@var{m}@var{n}4}
8623 Calculate a bit-forward CRC using operands 1, 2 and 3,
8624 then store the result in operand 0.
8625 Operands 1 is the initial CRC, operands 2 is the data and operands 3 is the
8626 polynomial without leading 1.
8627 Operands 0, 1 and 3 have mode @var{n} and operand 2 has mode @var{m}, where
8628 both modes are integers. The size of CRC to be calculated is determined by the
8629 mode; for example, if @var{n} is @code{HImode}, a CRC16 is calculated.
8630
8631 @cindex @code{crc_rev@var{m}@var{n}4} instruction pattern
8632 @item @samp{crc_rev@var{m}@var{n}4}
8633 Similar to @samp{crc@var{m}@var{n}4}, but calculates a bit-reversed CRC.
8634
8635 @end table
8636
8637 @end ifset
8638 @c Each of the following nodes are wrapped in separate
8639 @c "@ifset INTERNALS" to work around memory limits for the default
8640 @c configuration in older tetex distributions. Known to not work:
8641 @c tetex-1.0.7, known to work: tetex-2.0.2.
8642 @ifset INTERNALS
8643 @node Pattern Ordering
8644 @section When the Order of Patterns Matters
8645 @cindex Pattern Ordering
8646 @cindex Ordering of Patterns
8647
8648 Sometimes an insn can match more than one instruction pattern. Then the
8649 pattern that appears first in the machine description is the one used.
8650 Therefore, more specific patterns (patterns that will match fewer things)
8651 and faster instructions (those that will produce better code when they
8652 do match) should usually go first in the description.
8653
8654 In some cases the effect of ordering the patterns can be used to hide
8655 a pattern when it is not valid. For example, the 68000 has an
8656 instruction for converting a fullword to floating point and another
8657 for converting a byte to floating point. An instruction converting
8658 an integer to floating point could match either one. We put the
8659 pattern to convert the fullword first to make sure that one will
8660 be used rather than the other. (Otherwise a large integer might
8661 be generated as a single-byte immediate quantity, which would not work.)
8662 Instead of using this pattern ordering it would be possible to make the
8663 pattern for convert-a-byte smart enough to deal properly with any
8664 constant value.
8665
8666 @end ifset
8667 @ifset INTERNALS
8668 @node Dependent Patterns
8669 @section Interdependence of Patterns
8670 @cindex Dependent Patterns
8671 @cindex Interdependence of Patterns
8672
8673 In some cases machines support instructions identical except for the
8674 machine mode of one or more operands. For example, there may be
8675 ``sign-extend halfword'' and ``sign-extend byte'' instructions whose
8676 patterns are
8677
8678 @smallexample
8679 (set (match_operand:SI 0 @dots{})
8680 (extend:SI (match_operand:HI 1 @dots{})))
8681
8682 (set (match_operand:SI 0 @dots{})
8683 (extend:SI (match_operand:QI 1 @dots{})))
8684 @end smallexample
8685
8686 @noindent
8687 Constant integers do not specify a machine mode, so an instruction to
8688 extend a constant value could match either pattern. The pattern it
8689 actually will match is the one that appears first in the file. For correct
8690 results, this must be the one for the widest possible mode (@code{HImode},
8691 here). If the pattern matches the @code{QImode} instruction, the results
8692 will be incorrect if the constant value does not actually fit that mode.
8693
8694 Such instructions to extend constants are rarely generated because they are
8695 optimized away, but they do occasionally happen in nonoptimized
8696 compilations.
8697
8698 If a constraint in a pattern allows a constant, the reload pass may
8699 replace a register with a constant permitted by the constraint in some
8700 cases. Similarly for memory references. Because of this substitution,
8701 you should not provide separate patterns for increment and decrement
8702 instructions. Instead, they should be generated from the same pattern
8703 that supports register-register add insns by examining the operands and
8704 generating the appropriate machine instruction.
8705
8706 @end ifset
8707 @ifset INTERNALS
8708 @node Jump Patterns
8709 @section Defining Jump Instruction Patterns
8710 @cindex jump instruction patterns
8711 @cindex defining jump instruction patterns
8712
8713 GCC does not assume anything about how the machine realizes jumps.
8714 The machine description should define a single pattern, usually
8715 a @code{define_expand}, which expands to all the required insns.
8716
8717 Usually, this would be a comparison insn to set the condition code
8718 and a separate branch insn testing the condition code and branching
8719 or not according to its value. For many machines, however,
8720 separating compares and branches is limiting, which is why the
8721 more flexible approach with one @code{define_expand} is used in GCC.
8722 The machine description becomes clearer for architectures that
8723 have compare-and-branch instructions but no condition code. It also
8724 works better when different sets of comparison operators are supported
8725 by different kinds of conditional branches (e.g.@: integer vs.@:
8726 floating-point), or by conditional branches with respect to conditional stores.
8727
8728 Two separate insns are always used on most machines that use a separate
8729 condition code register (@pxref{Condition Code}).
8730
8731 Even in this case having a single entry point for conditional branches
8732 is advantageous, because it handles equally well the case where a single
8733 comparison instruction records the results of both signed and unsigned
8734 comparison of the given operands (with the branch insns coming in distinct
8735 signed and unsigned flavors) as in the x86 or SPARC, and the case where
8736 there are distinct signed and unsigned compare instructions and only
8737 one set of conditional branch instructions as in the PowerPC.
8738
8739 @end ifset
8740 @ifset INTERNALS
8741 @node Looping Patterns
8742 @section Defining Looping Instruction Patterns
8743 @cindex looping instruction patterns
8744 @cindex defining looping instruction patterns
8745
8746 Some machines have special jump instructions that can be utilized to
8747 make loops more efficient. A common example is the 68000 @samp{dbra}
8748 instruction which performs a decrement of a register and a branch if the
8749 result was greater than zero. Other machines, in particular digital
8750 signal processors (DSPs), have special block repeat instructions to
8751 provide low-overhead loop support. For example, the TI TMS320C3x/C4x
8752 DSPs have a block repeat instruction that loads special registers to
8753 mark the top and end of a loop and to count the number of loop
8754 iterations. This avoids the need for fetching and executing a
8755 @samp{dbra}-like instruction and avoids pipeline stalls associated with
8756 the jump.
8757
8758 GCC has two special named patterns to support low overhead looping.
8759 They are @samp{doloop_begin} and @samp{doloop_end}. These are emitted
8760 by the loop optimizer for certain well-behaved loops with a finite
8761 number of loop iterations using information collected during strength
8762 reduction.
8763
8764 The @samp{doloop_end} pattern describes the actual looping instruction
8765 (or the implicit looping operation) and the @samp{doloop_begin} pattern
8766 is an optional companion pattern that can be used for initialization
8767 needed for some low-overhead looping instructions.
8768
8769 Note that some machines require the actual looping instruction to be
8770 emitted at the top of the loop (e.g., the TMS320C3x/C4x DSPs). Emitting
8771 the true RTL for a looping instruction at the top of the loop can cause
8772 problems with flow analysis. So instead, a dummy @code{doloop} insn is
8773 emitted at the end of the loop. The machine dependent reorg pass checks
8774 for the presence of this @code{doloop} insn and then searches back to
8775 the top of the loop, where it inserts the true looping insn (provided
8776 there are no instructions in the loop which would cause problems). Any
8777 additional labels can be emitted at this point. In addition, if the
8778 desired special iteration counter register was not allocated, this
8779 machine dependent reorg pass could emit a traditional compare and jump
8780 instruction pair.
8781
8782 For the @samp{doloop_end} pattern, the loop optimizer allocates an
8783 additional pseudo register as an iteration counter. This pseudo
8784 register cannot be used within the loop (i.e., general induction
8785 variables cannot be derived from it), however, in many cases the loop
8786 induction variable may become redundant and removed by the flow pass.
8787
8788 The @samp{doloop_end} pattern must have a specific structure to be
8789 handled correctly by GCC. The example below is taken (slightly
8790 simplified) from the PDP-11 target:
8791
8792 @smallexample
8793 @group
8794 (define_expand "doloop_end"
8795 [(parallel [(set (pc)
8796 (if_then_else
8797 (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m")
8798 (const_int 1))
8799 (label_ref (match_operand 1 "" ""))
8800 (pc)))
8801 (set (match_dup 0)
8802 (plus:HI (match_dup 0)
8803 (const_int -1)))])]
8804 ""
8805 "@{
8806 if (GET_MODE (operands[0]) != HImode)
8807 FAIL;
8808 @}")
8809
8810 (define_insn "doloop_end_insn"
8811 [(set (pc)
8812 (if_then_else
8813 (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m")
8814 (const_int 1))
8815 (label_ref (match_operand 1 "" ""))
8816 (pc)))
8817 (set (match_dup 0)
8818 (plus:HI (match_dup 0)
8819 (const_int -1)))]
8820 ""
8821
8822 @{
8823 if (which_alternative == 0)
8824 return "sob %0,%l1";
8825
8826 /* emulate sob */
8827 output_asm_insn ("dec %0", operands);
8828 return "bne %l1";
8829 @})
8830 @end group
8831 @end smallexample
8832
8833 The first part of the pattern describes the branch condition. GCC
8834 supports three cases for the way the target machine handles the loop
8835 counter:
8836 @itemize @bullet
8837 @item Loop terminates when the loop register decrements to zero. This
8838 is represented by a @code{ne} comparison of the register (its old value)
8839 with constant 1 (as in the example above).
8840 @item Loop terminates when the loop register decrements to @minus{}1.
8841 This is represented by a @code{ne} comparison of the register with
8842 constant zero.
8843 @item Loop terminates when the loop register decrements to a negative
8844 value. This is represented by a @code{ge} comparison of the register
8845 with constant zero. For this case, GCC will attach a @code{REG_NONNEG}
8846 note to the @code{doloop_end} insn if it can determine that the register
8847 will be non-negative.
8848 @end itemize
8849
8850 Since the @code{doloop_end} insn is a jump insn that also has an output,
8851 the reload pass does not handle the output operand. Therefore, the
8852 constraint must allow for that operand to be in memory rather than a
8853 register. In the example shown above, that is handled (in the
8854 @code{doloop_end_insn} pattern) by using a loop instruction sequence
8855 that can handle memory operands when the memory alternative appears.
8856
8857 GCC does not check the mode of the loop register operand when generating
8858 the @code{doloop_end} pattern. If the pattern is only valid for some
8859 modes but not others, the pattern should be a @code{define_expand}
8860 pattern that checks the operand mode in the preparation code, and issues
8861 @code{FAIL} if an unsupported mode is found. The example above does
8862 this, since the machine instruction to be used only exists for
8863 @code{HImode}.
8864
8865 If the @code{doloop_end} pattern is a @code{define_expand}, there must
8866 also be a @code{define_insn} or @code{define_insn_and_split} matching
8867 the generated pattern. Otherwise, the compiler will fail during loop
8868 optimization.
8869
8870 @end ifset
8871 @ifset INTERNALS
8872 @node Insn Canonicalizations
8873 @section Canonicalization of Instructions
8874 @cindex canonicalization of instructions
8875 @cindex insn canonicalization
8876
8877 There are often cases where multiple RTL expressions could represent an
8878 operation performed by a single machine instruction. This situation is
8879 most commonly encountered with logical, branch, and multiply-accumulate
8880 instructions. In such cases, the compiler attempts to convert these
8881 multiple RTL expressions into a single canonical form to reduce the
8882 number of insn patterns required.
8883
8884 In addition to algebraic simplifications, following canonicalizations
8885 are performed:
8886
8887 @itemize @bullet
8888 @item
8889 For commutative and comparison operators, a constant is always made the
8890 second operand. If a machine only supports a constant as the second
8891 operand, only patterns that match a constant in the second operand need
8892 be supplied.
8893
8894 @cindex @code{vec_merge}, canonicalization of
8895 @item
8896 For the @code{vec_merge} with constant mask(the third operand), the first
8897 and the second operand can be exchanged by inverting the mask. In such cases,
8898 a constant is always made the second operand, otherwise the least significant
8899 bit of the mask is always set(select the first operand first).
8900
8901 @item
8902 For associative operators, a sequence of operators will always chain
8903 to the left; for instance, only the left operand of an integer @code{plus}
8904 can itself be a @code{plus}. @code{and}, @code{ior}, @code{xor},
8905 @code{plus}, @code{mult}, @code{smin}, @code{smax}, @code{umin}, and
8906 @code{umax} are associative when applied to integers, and sometimes to
8907 floating-point.
8908
8909 @cindex @code{neg}, canonicalization of
8910 @cindex @code{not}, canonicalization of
8911 @cindex @code{mult}, canonicalization of
8912 @cindex @code{plus}, canonicalization of
8913 @cindex @code{minus}, canonicalization of
8914 @item
8915 For these operators, if only one operand is a @code{neg}, @code{not},
8916 @code{mult}, @code{plus}, or @code{minus} expression, it will be the
8917 first operand.
8918
8919 @item
8920 In combinations of @code{neg}, @code{mult}, @code{plus}, and
8921 @code{minus}, the @code{neg} operations (if any) will be moved inside
8922 the operations as far as possible. For instance,
8923 @code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but
8924 @code{(plus (mult (neg B) C) A)} is canonicalized as
8925 @code{(minus A (mult B C))}.
8926
8927 @cindex @code{compare}, canonicalization of
8928 @item
8929 For the @code{compare} operator, a constant is always the second operand
8930 if the first argument is a condition code register.
8931
8932 @item
8933 For instructions that inherently set a condition code register, the
8934 @code{compare} operator is always written as the first RTL expression of
8935 the @code{parallel} instruction pattern. For example,
8936
8937 @smallexample
8938 (define_insn ""
8939 [(set (reg:CCZ FLAGS_REG)
8940 (compare:CCZ
8941 (plus:SI
8942 (match_operand:SI 1 "register_operand" "%r")
8943 (match_operand:SI 2 "register_operand" "r"))
8944 (const_int 0)))
8945 (set (match_operand:SI 0 "register_operand" "=r")
8946 (plus:SI (match_dup 1) (match_dup 2)))]
8947 ""
8948 "addl %0, %1, %2")
8949 @end smallexample
8950
8951 @item
8952 An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or
8953 @code{minus} is made the first operand under the same conditions as
8954 above.
8955
8956 @item
8957 @code{(ltu (plus @var{a} @var{b}) @var{b})} is converted to
8958 @code{(ltu (plus @var{a} @var{b}) @var{a})}. Likewise with @code{geu} instead
8959 of @code{ltu}.
8960
8961 @item
8962 @code{(minus @var{x} (const_int @var{n}))} is converted to
8963 @code{(plus @var{x} (const_int @var{-n}))}.
8964
8965 @item
8966 Within address computations (i.e., inside @code{mem}), a left shift is
8967 converted into the appropriate multiplication by a power of two.
8968
8969 @cindex @code{ior}, canonicalization of
8970 @cindex @code{and}, canonicalization of
8971 @cindex De Morgan's law
8972 @item
8973 De Morgan's Law is used to move bitwise negation inside a bitwise
8974 logical-and or logical-or operation. If this results in only one
8975 operand being a @code{not} expression, it will be the first one.
8976
8977 A machine that has an instruction that performs a bitwise logical-and of one
8978 operand with the bitwise negation of the other should specify the pattern
8979 for that instruction as
8980
8981 @smallexample
8982 (define_insn ""
8983 [(set (match_operand:@var{m} 0 @dots{})
8984 (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
8985 (match_operand:@var{m} 2 @dots{})))]
8986 "@dots{}"
8987 "@dots{}")
8988 @end smallexample
8989
8990 @noindent
8991 Similarly, a pattern for a ``NAND'' instruction should be written
8992
8993 @smallexample
8994 (define_insn ""
8995 [(set (match_operand:@var{m} 0 @dots{})
8996 (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
8997 (not:@var{m} (match_operand:@var{m} 2 @dots{}))))]
8998 "@dots{}"
8999 "@dots{}")
9000 @end smallexample
9001
9002 In both cases, it is not necessary to include patterns for the many
9003 logically equivalent RTL expressions.
9004
9005 @cindex @code{xor}, canonicalization of
9006 @item
9007 The only possible RTL expressions involving both bitwise exclusive-or
9008 and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})}
9009 and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}.
9010
9011 @item
9012 The sum of three items, one of which is a constant, will only appear in
9013 the form
9014
9015 @smallexample
9016 (plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant})
9017 @end smallexample
9018
9019 @cindex @code{zero_extract}, canonicalization of
9020 @cindex @code{sign_extract}, canonicalization of
9021 @item
9022 Equality comparisons of a group of bits (usually a single bit) with zero
9023 will be written using @code{zero_extract} rather than the equivalent
9024 @code{and} or @code{sign_extract} operations.
9025
9026 @cindex @code{mult}, canonicalization of
9027 @item
9028 @code{(sign_extend:@var{m1} (mult:@var{m2} (sign_extend:@var{m2} @var{x})
9029 (sign_extend:@var{m2} @var{y})))} is converted to @code{(mult:@var{m1}
9030 (sign_extend:@var{m1} @var{x}) (sign_extend:@var{m1} @var{y}))}, and likewise
9031 for @code{zero_extend}.
9032
9033 @item
9034 @code{(sign_extend:@var{m1} (mult:@var{m2} (ashiftrt:@var{m2}
9035 @var{x} @var{s}) (sign_extend:@var{m2} @var{y})))} is converted
9036 to @code{(mult:@var{m1} (sign_extend:@var{m1} (ashiftrt:@var{m2}
9037 @var{x} @var{s})) (sign_extend:@var{m1} @var{y}))}, and likewise for
9038 patterns using @code{zero_extend} and @code{lshiftrt}. If the second
9039 operand of @code{mult} is also a shift, then that is extended also.
9040 This transformation is only applied when it can be proven that the
9041 original operation had sufficient precision to prevent overflow.
9042
9043 @end itemize
9044
9045 Further canonicalization rules are defined in the function
9046 @code{commutative_operand_precedence} in @file{gcc/rtlanal.cc}.
9047
9048 @end ifset
9049 @ifset INTERNALS
9050 @node Expander Definitions
9051 @section Defining RTL Sequences for Code Generation
9052 @cindex expander definitions
9053 @cindex code generation RTL sequences
9054 @cindex defining RTL sequences for code generation
9055
9056 On some target machines, some standard pattern names for RTL generation
9057 cannot be handled with single insn, but a sequence of RTL insns can
9058 represent them. For these target machines, you can write a
9059 @code{define_expand} to specify how to generate the sequence of RTL@.
9060
9061 @findex define_expand
9062 A @code{define_expand} is an RTL expression that looks almost like a
9063 @code{define_insn}; but, unlike the latter, a @code{define_expand} is used
9064 only for RTL generation and it can produce more than one RTL insn.
9065
9066 A @code{define_expand} RTX has four operands:
9067
9068 @itemize @bullet
9069 @item
9070 The name. Each @code{define_expand} must have a name, since the only
9071 use for it is to refer to it by name.
9072
9073 @item
9074 The RTL template. This is a vector of RTL expressions representing
9075 a sequence of separate instructions. Unlike @code{define_insn}, there
9076 is no implicit surrounding @code{PARALLEL}.
9077
9078 @item
9079 The condition, a string containing a C expression. This expression is
9080 used to express how the availability of this pattern depends on
9081 subclasses of target machine, selected by command-line options when GCC
9082 is run. This is just like the condition of a @code{define_insn} that
9083 has a standard name. Therefore, the condition (if present) may not
9084 depend on the data in the insn being matched, but only the
9085 target-machine-type flags. The compiler needs to test these conditions
9086 during initialization in order to learn exactly which named instructions
9087 are available in a particular run.
9088
9089 @item
9090 The preparation statements, a string containing zero or more C
9091 statements which are to be executed before RTL code is generated from
9092 the RTL template.
9093
9094 Usually these statements prepare temporary registers for use as
9095 internal operands in the RTL template, but they can also generate RTL
9096 insns directly by calling routines such as @code{emit_insn}, etc.
9097 Any such insns precede the ones that come from the RTL template.
9098
9099 @item
9100 Optionally, a vector containing the values of attributes. @xref{Insn
9101 Attributes}.
9102 @end itemize
9103
9104 Every RTL insn emitted by a @code{define_expand} must match some
9105 @code{define_insn} in the machine description. Otherwise, the compiler
9106 will crash when trying to generate code for the insn or trying to optimize
9107 it.
9108
9109 The RTL template, in addition to controlling generation of RTL insns,
9110 also describes the operands that need to be specified when this pattern
9111 is used. In particular, it gives a predicate for each operand.
9112
9113 A true operand, which needs to be specified in order to generate RTL from
9114 the pattern, should be described with a @code{match_operand} in its first
9115 occurrence in the RTL template. This enters information on the operand's
9116 predicate into the tables that record such things. GCC uses the
9117 information to preload the operand into a register if that is required for
9118 valid RTL code. If the operand is referred to more than once, subsequent
9119 references should use @code{match_dup}.
9120
9121 The RTL template may also refer to internal ``operands'' which are
9122 temporary registers or labels used only within the sequence made by the
9123 @code{define_expand}. Internal operands are substituted into the RTL
9124 template with @code{match_dup}, never with @code{match_operand}. The
9125 values of the internal operands are not passed in as arguments by the
9126 compiler when it requests use of this pattern. Instead, they are computed
9127 within the pattern, in the preparation statements. These statements
9128 compute the values and store them into the appropriate elements of
9129 @code{operands} so that @code{match_dup} can find them.
9130
9131 There are two special macros defined for use in the preparation statements:
9132 @code{DONE} and @code{FAIL}. Use them with a following semicolon,
9133 as a statement.
9134
9135 @table @code
9136
9137 @findex DONE
9138 @item DONE
9139 Use the @code{DONE} macro to end RTL generation for the pattern. The
9140 only RTL insns resulting from the pattern on this occasion will be
9141 those already emitted by explicit calls to @code{emit_insn} within the
9142 preparation statements; the RTL template will not be generated.
9143
9144 @findex FAIL
9145 @item FAIL
9146 Make the pattern fail on this occasion. When a pattern fails, it means
9147 that the pattern was not truly available. The calling routines in the
9148 compiler will try other strategies for code generation using other patterns.
9149
9150 Failure is currently supported only for binary (addition, multiplication,
9151 shifting, etc.) and bit-field (@code{extv}, @code{extzv}, and @code{insv})
9152 operations.
9153 @end table
9154
9155 If the preparation falls through (invokes neither @code{DONE} nor
9156 @code{FAIL}), then the @code{define_expand} acts like a
9157 @code{define_insn} in that the RTL template is used to generate the
9158 insn.
9159
9160 The RTL template is not used for matching, only for generating the
9161 initial insn list. If the preparation statement always invokes
9162 @code{DONE} or @code{FAIL}, the RTL template may be reduced to a simple
9163 list of operands, such as this example:
9164
9165 @smallexample
9166 @group
9167 (define_expand "addsi3"
9168 [(match_operand:SI 0 "register_operand" "")
9169 (match_operand:SI 1 "register_operand" "")
9170 (match_operand:SI 2 "register_operand" "")]
9171 ""
9172 "
9173 @{
9174 handle_add (operands[0], operands[1], operands[2]);
9175 DONE;
9176 @}")
9177 @end group
9178 @end smallexample
9179
9180 Here is an example, the definition of left-shift for the SPUR chip:
9181
9182 @smallexample
9183 @group
9184 (define_expand "ashlsi3"
9185 [(set (match_operand:SI 0 "register_operand" "")
9186 (ashift:SI
9187 (match_operand:SI 1 "register_operand" "")
9188 (match_operand:SI 2 "nonmemory_operand" "")))]
9189 ""
9190 "
9191 @{
9192 if (GET_CODE (operands[2]) != CONST_INT
9193 || (unsigned) INTVAL (operands[2]) > 3)
9194 FAIL;
9195 @}")
9196 @end group
9197 @end smallexample
9198
9199 @noindent
9200 This example uses @code{define_expand} so that it can generate an RTL insn
9201 for shifting when the shift-count is in the supported range of 0 to 3 but
9202 fail in other cases where machine insns aren't available. When it fails,
9203 the compiler tries another strategy using different patterns (such as, a
9204 library call).
9205
9206 If the compiler were able to handle nontrivial condition-strings in
9207 patterns with names, then it would be possible to use a
9208 @code{define_insn} in that case. Here is another case (zero-extension
9209 on the 68000) which makes more use of the power of @code{define_expand}:
9210
9211 @smallexample
9212 (define_expand "zero_extendhisi2"
9213 [(set (match_operand:SI 0 "general_operand" "")
9214 (const_int 0))
9215 (set (strict_low_part
9216 (subreg:HI
9217 (match_dup 0)
9218 0))
9219 (match_operand:HI 1 "general_operand" ""))]
9220 ""
9221 "operands[1] = make_safe_from (operands[1], operands[0]);")
9222 @end smallexample
9223
9224 @noindent
9225 @findex make_safe_from
9226 Here two RTL insns are generated, one to clear the entire output operand
9227 and the other to copy the input operand into its low half. This sequence
9228 is incorrect if the input operand refers to [the old value of] the output
9229 operand, so the preparation statement makes sure this isn't so. The
9230 function @code{make_safe_from} copies the @code{operands[1]} into a
9231 temporary register if it refers to @code{operands[0]}. It does this
9232 by emitting another RTL insn.
9233
9234 Finally, a third example shows the use of an internal operand.
9235 Zero-extension on the SPUR chip is done by @code{and}-ing the result
9236 against a halfword mask. But this mask cannot be represented by a
9237 @code{const_int} because the constant value is too large to be legitimate
9238 on this machine. So it must be copied into a register with
9239 @code{force_reg} and then the register used in the @code{and}.
9240
9241 @smallexample
9242 (define_expand "zero_extendhisi2"
9243 [(set (match_operand:SI 0 "register_operand" "")
9244 (and:SI (subreg:SI
9245 (match_operand:HI 1 "register_operand" "")
9246 0)
9247 (match_dup 2)))]
9248 ""
9249 "operands[2]
9250 = force_reg (SImode, GEN_INT (65535)); ")
9251 @end smallexample
9252
9253 @emph{Note:} If the @code{define_expand} is used to serve a
9254 standard binary or unary arithmetic operation or a bit-field operation,
9255 then the last insn it generates must not be a @code{code_label},
9256 @code{barrier} or @code{note}. It must be an @code{insn},
9257 @code{jump_insn} or @code{call_insn}. If you don't need a real insn
9258 at the end, emit an insn to copy the result of the operation into
9259 itself. Such an insn will generate no code, but it can avoid problems
9260 in the compiler.
9261
9262 @end ifset
9263 @ifset INTERNALS
9264 @node Insn Splitting
9265 @section Defining How to Split Instructions
9266 @cindex insn splitting
9267 @cindex instruction splitting
9268 @cindex splitting instructions
9269
9270 There are two cases where you should specify how to split a pattern
9271 into multiple insns. On machines that have instructions requiring
9272 delay slots (@pxref{Delay Slots}) or that have instructions whose
9273 output is not available for multiple cycles (@pxref{Processor pipeline
9274 description}), the compiler phases that optimize these cases need to
9275 be able to move insns into one-instruction delay slots. However, some
9276 insns may generate more than one machine instruction. These insns
9277 cannot be placed into a delay slot.
9278
9279 Often you can rewrite the single insn as a list of individual insns,
9280 each corresponding to one machine instruction. The disadvantage of
9281 doing so is that it will cause the compilation to be slower and require
9282 more space. If the resulting insns are too complex, it may also
9283 suppress some optimizations. The compiler splits the insn if there is a
9284 reason to believe that it might improve instruction or delay slot
9285 scheduling.
9286
9287 The insn combiner phase also splits putative insns. If three insns are
9288 merged into one insn with a complex expression that cannot be matched by
9289 some @code{define_insn} pattern, the combiner phase attempts to split
9290 the complex pattern into two insns that are recognized. Usually it can
9291 break the complex pattern into two patterns by splitting out some
9292 subexpression. However, in some other cases, such as performing an
9293 addition of a large constant in two insns on a RISC machine, the way to
9294 split the addition into two insns is machine-dependent.
9295
9296 @findex define_split
9297 The @code{define_split} definition tells the compiler how to split a
9298 complex insn into several simpler insns. It looks like this:
9299
9300 @smallexample
9301 (define_split
9302 [@var{insn-pattern}]
9303 "@var{condition}"
9304 [@var{new-insn-pattern-1}
9305 @var{new-insn-pattern-2}
9306 @dots{}]
9307 "@var{preparation-statements}")
9308 @end smallexample
9309
9310 @var{insn-pattern} is a pattern that needs to be split and
9311 @var{condition} is the final condition to be tested, as in a
9312 @code{define_insn}. When an insn matching @var{insn-pattern} and
9313 satisfying @var{condition} is found, it is replaced in the insn list
9314 with the insns given by @var{new-insn-pattern-1},
9315 @var{new-insn-pattern-2}, etc.
9316
9317 The @var{preparation-statements} are similar to those statements that
9318 are specified for @code{define_expand} (@pxref{Expander Definitions})
9319 and are executed before the new RTL is generated to prepare for the
9320 generated code or emit some insns whose pattern is not fixed. Unlike
9321 those in @code{define_expand}, however, these statements must not
9322 generate any new pseudo-registers. Once reload has completed, they also
9323 must not allocate any space in the stack frame.
9324
9325 There are two special macros defined for use in the preparation statements:
9326 @code{DONE} and @code{FAIL}. Use them with a following semicolon,
9327 as a statement.
9328
9329 @table @code
9330
9331 @findex DONE
9332 @item DONE
9333 Use the @code{DONE} macro to end RTL generation for the splitter. The
9334 only RTL insns generated as replacement for the matched input insn will
9335 be those already emitted by explicit calls to @code{emit_insn} within
9336 the preparation statements; the replacement pattern is not used.
9337
9338 @findex FAIL
9339 @item FAIL
9340 Make the @code{define_split} fail on this occasion. When a @code{define_split}
9341 fails, it means that the splitter was not truly available for the inputs
9342 it was given, and the input insn will not be split.
9343 @end table
9344
9345 If the preparation falls through (invokes neither @code{DONE} nor
9346 @code{FAIL}), then the @code{define_split} uses the replacement
9347 template.
9348
9349 Patterns are matched against @var{insn-pattern} in two different
9350 circumstances. If an insn needs to be split for delay slot scheduling
9351 or insn scheduling, the insn is already known to be valid, which means
9352 that it must have been matched by some @code{define_insn} and, if
9353 @code{reload_completed} is nonzero, is known to satisfy the constraints
9354 of that @code{define_insn}. In that case, the new insn patterns must
9355 also be insns that are matched by some @code{define_insn} and, if
9356 @code{reload_completed} is nonzero, must also satisfy the constraints
9357 of those definitions.
9358
9359 As an example of this usage of @code{define_split}, consider the following
9360 example from @file{a29k.md}, which splits a @code{sign_extend} from
9361 @code{HImode} to @code{SImode} into a pair of shift insns:
9362
9363 @smallexample
9364 (define_split
9365 [(set (match_operand:SI 0 "gen_reg_operand" "")
9366 (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))]
9367 ""
9368 [(set (match_dup 0)
9369 (ashift:SI (match_dup 1)
9370 (const_int 16)))
9371 (set (match_dup 0)
9372 (ashiftrt:SI (match_dup 0)
9373 (const_int 16)))]
9374 "
9375 @{ operands[1] = gen_lowpart (SImode, operands[1]); @}")
9376 @end smallexample
9377
9378 When the combiner phase tries to split an insn pattern, it is always the
9379 case that the pattern is @emph{not} matched by any @code{define_insn}.
9380 The combiner pass first tries to split a single @code{set} expression
9381 and then the same @code{set} expression inside a @code{parallel}, but
9382 followed by a @code{clobber} of a pseudo-reg to use as a scratch
9383 register. In these cases, the combiner expects exactly one or two new insn
9384 patterns to be generated. It will verify that these patterns match some
9385 @code{define_insn} definitions, so you need not do this test in the
9386 @code{define_split} (of course, there is no point in writing a
9387 @code{define_split} that will never produce insns that match).
9388
9389 Here is an example of this use of @code{define_split}, taken from
9390 @file{rs6000.md}:
9391
9392 @smallexample
9393 (define_split
9394 [(set (match_operand:SI 0 "gen_reg_operand" "")
9395 (plus:SI (match_operand:SI 1 "gen_reg_operand" "")
9396 (match_operand:SI 2 "non_add_cint_operand" "")))]
9397 ""
9398 [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3)))
9399 (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))]
9400 "
9401 @{
9402 int low = INTVAL (operands[2]) & 0xffff;
9403 int high = (unsigned) INTVAL (operands[2]) >> 16;
9404
9405 if (low & 0x8000)
9406 high++, low |= 0xffff0000;
9407
9408 operands[3] = GEN_INT (high << 16);
9409 operands[4] = GEN_INT (low);
9410 @}")
9411 @end smallexample
9412
9413 Here the predicate @code{non_add_cint_operand} matches any
9414 @code{const_int} that is @emph{not} a valid operand of a single add
9415 insn. The add with the smaller displacement is written so that it
9416 can be substituted into the address of a subsequent operation.
9417
9418 An example that uses a scratch register, from the same file, generates
9419 an equality comparison of a register and a large constant:
9420
9421 @smallexample
9422 (define_split
9423 [(set (match_operand:CC 0 "cc_reg_operand" "")
9424 (compare:CC (match_operand:SI 1 "gen_reg_operand" "")
9425 (match_operand:SI 2 "non_short_cint_operand" "")))
9426 (clobber (match_operand:SI 3 "gen_reg_operand" ""))]
9427 "find_single_use (operands[0], insn, 0)
9428 && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ
9429 || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)"
9430 [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4)))
9431 (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))]
9432 "
9433 @{
9434 /* @r{Get the constant we are comparing against, C, and see what it
9435 looks like sign-extended to 16 bits. Then see what constant
9436 could be XOR'ed with C to get the sign-extended value.} */
9437
9438 int c = INTVAL (operands[2]);
9439 int sextc = (c << 16) >> 16;
9440 int xorv = c ^ sextc;
9441
9442 operands[4] = GEN_INT (xorv);
9443 operands[5] = GEN_INT (sextc);
9444 @}")
9445 @end smallexample
9446
9447 To avoid confusion, don't write a single @code{define_split} that
9448 accepts some insns that match some @code{define_insn} as well as some
9449 insns that don't. Instead, write two separate @code{define_split}
9450 definitions, one for the insns that are valid and one for the insns that
9451 are not valid.
9452
9453 The splitter is allowed to split jump instructions into a sequence of jumps or
9454 create new jumps while splitting non-jump instructions. As the control flow
9455 graph and branch prediction information needs to be updated after the splitter
9456 runs, several restrictions apply.
9457
9458 Splitting of a jump instruction into a sequence that has another jump
9459 instruction to the same label is always valid, as the compiler expects
9460 identical behavior of the new jump. When the new sequence contains multiple
9461 jump instructions or new labels, more assistance is needed. The splitter is
9462 permitted to create only unconditional jumps, or simple conditional jump
9463 instructions. Additionally it must attach a @code{REG_BR_PROB} note to each
9464 conditional jump. A global variable @code{split_branch_probability} holds the
9465 probability of the original branch in case it was a simple conditional jump,
9466 @minus{}1 otherwise. To simplify recomputing of edge frequencies, the new
9467 sequence is permitted to have only forward jumps to the newly-created labels.
9468
9469 @findex define_insn_and_split
9470 For the common case where the pattern of a define_split exactly matches the
9471 pattern of a define_insn, use @code{define_insn_and_split}. It looks like
9472 this:
9473
9474 @smallexample
9475 (define_insn_and_split
9476 [@var{insn-pattern}]
9477 "@var{condition}"
9478 "@var{output-template}"
9479 "@var{split-condition}"
9480 [@var{new-insn-pattern-1}
9481 @var{new-insn-pattern-2}
9482 @dots{}]
9483 "@var{preparation-statements}"
9484 [@var{insn-attributes}])
9485
9486 @end smallexample
9487
9488 @var{insn-pattern}, @var{condition}, @var{output-template}, and
9489 @var{insn-attributes} are used as in @code{define_insn}. The
9490 @var{new-insn-pattern} vector and the @var{preparation-statements} are used as
9491 in a @code{define_split}. The @var{split-condition} is also used as in
9492 @code{define_split}, with the additional behavior that if the condition starts
9493 with @samp{&&}, the condition used for the split will be the constructed as a
9494 logical ``and'' of the split condition with the insn condition. For example,
9495 from i386.md:
9496
9497 @smallexample
9498 (define_insn_and_split "zero_extendhisi2_and"
9499 [(set (match_operand:SI 0 "register_operand" "=r")
9500 (zero_extend:SI (match_operand:HI 1 "register_operand" "0")))
9501 (clobber (reg:CC 17))]
9502 "TARGET_ZERO_EXTEND_WITH_AND && !optimize_size"
9503 "#"
9504 "&& reload_completed"
9505 [(parallel [(set (match_dup 0)
9506 (and:SI (match_dup 0) (const_int 65535)))
9507 (clobber (reg:CC 17))])]
9508 ""
9509 [(set_attr "type" "alu1")])
9510
9511 @end smallexample
9512
9513 In this case, the actual split condition will be
9514 @samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}.
9515
9516 The @code{define_insn_and_split} construction provides exactly the same
9517 functionality as two separate @code{define_insn} and @code{define_split}
9518 patterns. It exists for compactness, and as a maintenance tool to prevent
9519 having to ensure the two patterns' templates match.
9520
9521 @findex define_insn_and_rewrite
9522 It is sometimes useful to have a @code{define_insn_and_split}
9523 that replaces specific operands of an instruction but leaves the
9524 rest of the instruction pattern unchanged. You can do this directly
9525 with a @code{define_insn_and_split}, but it requires a
9526 @var{new-insn-pattern-1} that repeats most of the original @var{insn-pattern}.
9527 There is also the complication that an implicit @code{parallel} in
9528 @var{insn-pattern} must become an explicit @code{parallel} in
9529 @var{new-insn-pattern-1}, which is easy to overlook.
9530 A simpler alternative is to use @code{define_insn_and_rewrite}, which
9531 is a form of @code{define_insn_and_split} that automatically generates
9532 @var{new-insn-pattern-1} by replacing each @code{match_operand}
9533 in @var{insn-pattern} with a corresponding @code{match_dup}, and each
9534 @code{match_operator} in the pattern with a corresponding @code{match_op_dup}.
9535 The arguments are otherwise identical to @code{define_insn_and_split}:
9536
9537 @smallexample
9538 (define_insn_and_rewrite
9539 [@var{insn-pattern}]
9540 "@var{condition}"
9541 "@var{output-template}"
9542 "@var{split-condition}"
9543 "@var{preparation-statements}"
9544 [@var{insn-attributes}])
9545 @end smallexample
9546
9547 The @code{match_dup}s and @code{match_op_dup}s in the new
9548 instruction pattern use any new operand values that the
9549 @var{preparation-statements} store in the @code{operands} array,
9550 as for a normal @code{define_insn_and_split}. @var{preparation-statements}
9551 can also emit additional instructions before the new instruction.
9552 They can even emit an entirely different sequence of instructions and
9553 use @code{DONE} to avoid emitting a new form of the original
9554 instruction.
9555
9556 The split in a @code{define_insn_and_rewrite} is only intended
9557 to apply to existing instructions that match @var{insn-pattern}.
9558 @var{split-condition} must therefore start with @code{&&},
9559 so that the split condition applies on top of @var{condition}.
9560
9561 Here is an example from the AArch64 SVE port, in which operand 1 is
9562 known to be equivalent to an all-true constant and isn't used by the
9563 output template:
9564
9565 @smallexample
9566 (define_insn_and_rewrite "*while_ult<GPI:mode><PRED_ALL:mode>_cc"
9567 [(set (reg:CC CC_REGNUM)
9568 (compare:CC
9569 (unspec:SI [(match_operand:PRED_ALL 1)
9570 (unspec:PRED_ALL
9571 [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ")
9572 (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")]
9573 UNSPEC_WHILE_LO)]
9574 UNSPEC_PTEST_PTRUE)
9575 (const_int 0)))
9576 (set (match_operand:PRED_ALL 0 "register_operand" "=Upa")
9577 (unspec:PRED_ALL [(match_dup 2)
9578 (match_dup 3)]
9579 UNSPEC_WHILE_LO))]
9580 "TARGET_SVE"
9581 "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3"
9582 ;; Force the compiler to drop the unused predicate operand, so that we
9583 ;; don't have an unnecessary PTRUE.
9584 "&& !CONSTANT_P (operands[1])"
9585 @{
9586 operands[1] = CONSTM1_RTX (<MODE>mode);
9587 @}
9588 )
9589 @end smallexample
9590
9591 The splitter in this case simply replaces operand 1 with the constant
9592 value that it is known to have. The equivalent @code{define_insn_and_split}
9593 would be:
9594
9595 @smallexample
9596 (define_insn_and_split "*while_ult<GPI:mode><PRED_ALL:mode>_cc"
9597 [(set (reg:CC CC_REGNUM)
9598 (compare:CC
9599 (unspec:SI [(match_operand:PRED_ALL 1)
9600 (unspec:PRED_ALL
9601 [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ")
9602 (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")]
9603 UNSPEC_WHILE_LO)]
9604 UNSPEC_PTEST_PTRUE)
9605 (const_int 0)))
9606 (set (match_operand:PRED_ALL 0 "register_operand" "=Upa")
9607 (unspec:PRED_ALL [(match_dup 2)
9608 (match_dup 3)]
9609 UNSPEC_WHILE_LO))]
9610 "TARGET_SVE"
9611 "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3"
9612 ;; Force the compiler to drop the unused predicate operand, so that we
9613 ;; don't have an unnecessary PTRUE.
9614 "&& !CONSTANT_P (operands[1])"
9615 [(parallel
9616 [(set (reg:CC CC_REGNUM)
9617 (compare:CC
9618 (unspec:SI [(match_dup 1)
9619 (unspec:PRED_ALL [(match_dup 2)
9620 (match_dup 3)]
9621 UNSPEC_WHILE_LO)]
9622 UNSPEC_PTEST_PTRUE)
9623 (const_int 0)))
9624 (set (match_dup 0)
9625 (unspec:PRED_ALL [(match_dup 2)
9626 (match_dup 3)]
9627 UNSPEC_WHILE_LO))])]
9628 @{
9629 operands[1] = CONSTM1_RTX (<MODE>mode);
9630 @}
9631 )
9632 @end smallexample
9633
9634 @end ifset
9635 @ifset INTERNALS
9636 @node Including Patterns
9637 @section Including Patterns in Machine Descriptions.
9638 @cindex insn includes
9639
9640 @findex include
9641 The @code{include} pattern tells the compiler tools where to
9642 look for patterns that are in files other than in the file
9643 @file{.md}. This is used only at build time and there is no preprocessing allowed.
9644
9645 It looks like:
9646
9647 @smallexample
9648
9649 (include @var{pathname})
9650 @end smallexample
9651
9652 For example:
9653
9654 @smallexample
9655
9656 (include "filestuff")
9657
9658 @end smallexample
9659
9660 Where @var{pathname} is a string that specifies the location of the file,
9661 specifies the include file to be in @file{gcc/config/target/filestuff}. The
9662 directory @file{gcc/config/target} is regarded as the default directory.
9663
9664
9665 Machine descriptions may be split up into smaller more manageable subsections
9666 and placed into subdirectories.
9667
9668 By specifying:
9669
9670 @smallexample
9671
9672 (include "BOGUS/filestuff")
9673
9674 @end smallexample
9675
9676 the include file is specified to be in @file{gcc/config/@var{target}/BOGUS/filestuff}.
9677
9678 Specifying an absolute path for the include file such as;
9679 @smallexample
9680
9681 (include "/u2/BOGUS/filestuff")
9682
9683 @end smallexample
9684 is permitted but is not encouraged.
9685
9686 @subsection RTL Generation Tool Options for Directory Search
9687 @cindex directory options .md
9688 @cindex options, directory search
9689 @cindex search options
9690
9691 The @option{-I@var{dir}} option specifies directories to search for machine descriptions.
9692 For example:
9693
9694 @smallexample
9695
9696 genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md
9697
9698 @end smallexample
9699
9700
9701 Add the directory @var{dir} to the head of the list of directories to be
9702 searched for header files. This can be used to override a system machine definition
9703 file, substituting your own version, since these directories are
9704 searched before the default machine description file directories. If you use more than
9705 one @option{-I} option, the directories are scanned in left-to-right
9706 order; the standard default directory come after.
9707
9708
9709 @end ifset
9710 @ifset INTERNALS
9711 @node Peephole Definitions
9712 @section Machine-Specific Peephole Optimizers
9713 @cindex peephole optimizer definitions
9714 @cindex defining peephole optimizers
9715
9716 In addition to instruction patterns the @file{md} file may contain
9717 definitions of machine-specific peephole optimizations.
9718
9719 The combiner does not notice certain peephole optimizations when the data
9720 flow in the program does not suggest that it should try them. For example,
9721 sometimes two consecutive insns related in purpose can be combined even
9722 though the second one does not appear to use a register computed in the
9723 first one. A machine-specific peephole optimizer can detect such
9724 opportunities.
9725
9726 There are two forms of peephole definitions that may be used. The
9727 original @code{define_peephole} is run at assembly output time to
9728 match insns and substitute assembly text. Use of @code{define_peephole}
9729 is deprecated.
9730
9731 A newer @code{define_peephole2} matches insns and substitutes new
9732 insns. The @code{peephole2} pass is run after register allocation
9733 but before scheduling, which may result in much better code for
9734 targets that do scheduling.
9735
9736 @menu
9737 * define_peephole:: RTL to Text Peephole Optimizers
9738 * define_peephole2:: RTL to RTL Peephole Optimizers
9739 @end menu
9740
9741 @end ifset
9742 @ifset INTERNALS
9743 @node define_peephole
9744 @subsection RTL to Text Peephole Optimizers
9745 @findex define_peephole
9746
9747 @need 1000
9748 A definition looks like this:
9749
9750 @smallexample
9751 (define_peephole
9752 [@var{insn-pattern-1}
9753 @var{insn-pattern-2}
9754 @dots{}]
9755 "@var{condition}"
9756 "@var{template}"
9757 "@var{optional-insn-attributes}")
9758 @end smallexample
9759
9760 @noindent
9761 The last string operand may be omitted if you are not using any
9762 machine-specific information in this machine description. If present,
9763 it must obey the same rules as in a @code{define_insn}.
9764
9765 In this skeleton, @var{insn-pattern-1} and so on are patterns to match
9766 consecutive insns. The optimization applies to a sequence of insns when
9767 @var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches
9768 the next, and so on.
9769
9770 Each of the insns matched by a peephole must also match a
9771 @code{define_insn}. Peepholes are checked only at the last stage just
9772 before code generation, and only optionally. Therefore, any insn which
9773 would match a peephole but no @code{define_insn} will cause a crash in code
9774 generation in an unoptimized compilation, or at various optimization
9775 stages.
9776
9777 The operands of the insns are matched with @code{match_operands},
9778 @code{match_operator}, and @code{match_dup}, as usual. What is not
9779 usual is that the operand numbers apply to all the insn patterns in the
9780 definition. So, you can check for identical operands in two insns by
9781 using @code{match_operand} in one insn and @code{match_dup} in the
9782 other.
9783
9784 The operand constraints used in @code{match_operand} patterns do not have
9785 any direct effect on the applicability of the peephole, but they will
9786 be validated afterward, so make sure your constraints are general enough
9787 to apply whenever the peephole matches. If the peephole matches
9788 but the constraints are not satisfied, the compiler will crash.
9789
9790 It is safe to omit constraints in all the operands of the peephole; or
9791 you can write constraints which serve as a double-check on the criteria
9792 previously tested.
9793
9794 Once a sequence of insns matches the patterns, the @var{condition} is
9795 checked. This is a C expression which makes the final decision whether to
9796 perform the optimization (we do so if the expression is nonzero). If
9797 @var{condition} is omitted (in other words, the string is empty) then the
9798 optimization is applied to every sequence of insns that matches the
9799 patterns.
9800
9801 The defined peephole optimizations are applied after register allocation
9802 is complete. Therefore, the peephole definition can check which
9803 operands have ended up in which kinds of registers, just by looking at
9804 the operands.
9805
9806 @findex prev_active_insn
9807 The way to refer to the operands in @var{condition} is to write
9808 @code{operands[@var{i}]} for operand number @var{i} (as matched by
9809 @code{(match_operand @var{i} @dots{})}). Use the variable @code{insn}
9810 to refer to the last of the insns being matched; use
9811 @code{prev_active_insn} to find the preceding insns.
9812
9813 @findex dead_or_set_p
9814 When optimizing computations with intermediate results, you can use
9815 @var{condition} to match only when the intermediate results are not used
9816 elsewhere. Use the C expression @code{dead_or_set_p (@var{insn},
9817 @var{op})}, where @var{insn} is the insn in which you expect the value
9818 to be used for the last time (from the value of @code{insn}, together
9819 with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate
9820 value (from @code{operands[@var{i}]}).
9821
9822 Applying the optimization means replacing the sequence of insns with one
9823 new insn. The @var{template} controls ultimate output of assembler code
9824 for this combined insn. It works exactly like the template of a
9825 @code{define_insn}. Operand numbers in this template are the same ones
9826 used in matching the original sequence of insns.
9827
9828 The result of a defined peephole optimizer does not need to match any of
9829 the insn patterns in the machine description; it does not even have an
9830 opportunity to match them. The peephole optimizer definition itself serves
9831 as the insn pattern to control how the insn is output.
9832
9833 Defined peephole optimizers are run as assembler code is being output,
9834 so the insns they produce are never combined or rearranged in any way.
9835
9836 Here is an example, taken from the 68000 machine description:
9837
9838 @smallexample
9839 (define_peephole
9840 [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
9841 (set (match_operand:DF 0 "register_operand" "=f")
9842 (match_operand:DF 1 "register_operand" "ad"))]
9843 "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
9844 @{
9845 rtx xoperands[2];
9846 xoperands[1] = gen_rtx_REG (SImode, REGNO (operands[1]) + 1);
9847 #ifdef MOTOROLA
9848 output_asm_insn ("move.l %1,(sp)", xoperands);
9849 output_asm_insn ("move.l %1,-(sp)", operands);
9850 return "fmove.d (sp)+,%0";
9851 #else
9852 output_asm_insn ("movel %1,sp@@", xoperands);
9853 output_asm_insn ("movel %1,sp@@-", operands);
9854 return "fmoved sp@@+,%0";
9855 #endif
9856 @})
9857 @end smallexample
9858
9859 @need 1000
9860 The effect of this optimization is to change
9861
9862 @smallexample
9863 @group
9864 jbsr _foobar
9865 addql #4,sp
9866 movel d1,sp@@-
9867 movel d0,sp@@-
9868 fmoved sp@@+,fp0
9869 @end group
9870 @end smallexample
9871
9872 @noindent
9873 into
9874
9875 @smallexample
9876 @group
9877 jbsr _foobar
9878 movel d1,sp@@
9879 movel d0,sp@@-
9880 fmoved sp@@+,fp0
9881 @end group
9882 @end smallexample
9883
9884 @ignore
9885 @findex CC_REVERSED
9886 If a peephole matches a sequence including one or more jump insns, you must
9887 take account of the flags such as @code{CC_REVERSED} which specify that the
9888 condition codes are represented in an unusual manner. The compiler
9889 automatically alters any ordinary conditional jumps which occur in such
9890 situations, but the compiler cannot alter jumps which have been replaced by
9891 peephole optimizations. So it is up to you to alter the assembler code
9892 that the peephole produces. Supply C code to write the assembler output,
9893 and in this C code check the condition code status flags and change the
9894 assembler code as appropriate.
9895 @end ignore
9896
9897 @var{insn-pattern-1} and so on look @emph{almost} like the second
9898 operand of @code{define_insn}. There is one important difference: the
9899 second operand of @code{define_insn} consists of one or more RTX's
9900 enclosed in square brackets. Usually, there is only one: then the same
9901 action can be written as an element of a @code{define_peephole}. But
9902 when there are multiple actions in a @code{define_insn}, they are
9903 implicitly enclosed in a @code{parallel}. Then you must explicitly
9904 write the @code{parallel}, and the square brackets within it, in the
9905 @code{define_peephole}. Thus, if an insn pattern looks like this,
9906
9907 @smallexample
9908 (define_insn "divmodsi4"
9909 [(set (match_operand:SI 0 "general_operand" "=d")
9910 (div:SI (match_operand:SI 1 "general_operand" "0")
9911 (match_operand:SI 2 "general_operand" "dmsK")))
9912 (set (match_operand:SI 3 "general_operand" "=d")
9913 (mod:SI (match_dup 1) (match_dup 2)))]
9914 "TARGET_68020"
9915 "divsl%.l %2,%3:%0")
9916 @end smallexample
9917
9918 @noindent
9919 then the way to mention this insn in a peephole is as follows:
9920
9921 @smallexample
9922 (define_peephole
9923 [@dots{}
9924 (parallel
9925 [(set (match_operand:SI 0 "general_operand" "=d")
9926 (div:SI (match_operand:SI 1 "general_operand" "0")
9927 (match_operand:SI 2 "general_operand" "dmsK")))
9928 (set (match_operand:SI 3 "general_operand" "=d")
9929 (mod:SI (match_dup 1) (match_dup 2)))])
9930 @dots{}]
9931 @dots{})
9932 @end smallexample
9933
9934 @end ifset
9935 @ifset INTERNALS
9936 @node define_peephole2
9937 @subsection RTL to RTL Peephole Optimizers
9938 @findex define_peephole2
9939
9940 The @code{define_peephole2} definition tells the compiler how to
9941 substitute one sequence of instructions for another sequence,
9942 what additional scratch registers may be needed and what their
9943 lifetimes must be.
9944
9945 @smallexample
9946 (define_peephole2
9947 [@var{insn-pattern-1}
9948 @var{insn-pattern-2}
9949 @dots{}]
9950 "@var{condition}"
9951 [@var{new-insn-pattern-1}
9952 @var{new-insn-pattern-2}
9953 @dots{}]
9954 "@var{preparation-statements}")
9955 @end smallexample
9956
9957 The definition is almost identical to @code{define_split}
9958 (@pxref{Insn Splitting}) except that the pattern to match is not a
9959 single instruction, but a sequence of instructions.
9960
9961 It is possible to request additional scratch registers for use in the
9962 output template. If appropriate registers are not free, the pattern
9963 will simply not match.
9964
9965 @findex match_scratch
9966 @findex match_dup
9967 Scratch registers are requested with a @code{match_scratch} pattern at
9968 the top level of the input pattern. The allocated register (initially) will
9969 be dead at the point requested within the original sequence. If the scratch
9970 is used at more than a single point, a @code{match_dup} pattern at the
9971 top level of the input pattern marks the last position in the input sequence
9972 at which the register must be available.
9973
9974 Here is an example from the IA-32 machine description:
9975
9976 @smallexample
9977 (define_peephole2
9978 [(match_scratch:SI 2 "r")
9979 (parallel [(set (match_operand:SI 0 "register_operand" "")
9980 (match_operator:SI 3 "arith_or_logical_operator"
9981 [(match_dup 0)
9982 (match_operand:SI 1 "memory_operand" "")]))
9983 (clobber (reg:CC 17))])]
9984 "! optimize_size && ! TARGET_READ_MODIFY"
9985 [(set (match_dup 2) (match_dup 1))
9986 (parallel [(set (match_dup 0)
9987 (match_op_dup 3 [(match_dup 0) (match_dup 2)]))
9988 (clobber (reg:CC 17))])]
9989 "")
9990 @end smallexample
9991
9992 @noindent
9993 This pattern tries to split a load from its use in the hopes that we'll be
9994 able to schedule around the memory load latency. It allocates a single
9995 @code{SImode} register of class @code{GENERAL_REGS} (@code{"r"}) that needs
9996 to be live only at the point just before the arithmetic.
9997
9998 A real example requiring extended scratch lifetimes is harder to come by,
9999 so here's a silly made-up example:
10000
10001 @smallexample
10002 (define_peephole2
10003 [(match_scratch:SI 4 "r")
10004 (set (match_operand:SI 0 "" "") (match_operand:SI 1 "" ""))
10005 (set (match_operand:SI 2 "" "") (match_dup 1))
10006 (match_dup 4)
10007 (set (match_operand:SI 3 "" "") (match_dup 1))]
10008 "/* @r{determine 1 does not overlap 0 and 2} */"
10009 [(set (match_dup 4) (match_dup 1))
10010 (set (match_dup 0) (match_dup 4))
10011 (set (match_dup 2) (match_dup 4))
10012 (set (match_dup 3) (match_dup 4))]
10013 "")
10014 @end smallexample
10015
10016 @noindent
10017 If we had not added the @code{(match_dup 4)} in the middle of the input
10018 sequence, it might have been the case that the register we chose at the
10019 beginning of the sequence is killed by the first or second @code{set}.
10020
10021 There are two special macros defined for use in the preparation statements:
10022 @code{DONE} and @code{FAIL}. Use them with a following semicolon,
10023 as a statement.
10024
10025 @table @code
10026
10027 @findex DONE
10028 @item DONE
10029 Use the @code{DONE} macro to end RTL generation for the peephole. The
10030 only RTL insns generated as replacement for the matched input insn will
10031 be those already emitted by explicit calls to @code{emit_insn} within
10032 the preparation statements; the replacement pattern is not used.
10033
10034 @findex FAIL
10035 @item FAIL
10036 Make the @code{define_peephole2} fail on this occasion. When a @code{define_peephole2}
10037 fails, it means that the replacement was not truly available for the
10038 particular inputs it was given. In that case, GCC may still apply a
10039 later @code{define_peephole2} that also matches the given insn pattern.
10040 (Note that this is different from @code{define_split}, where @code{FAIL}
10041 prevents the input insn from being split at all.)
10042 @end table
10043
10044 If the preparation falls through (invokes neither @code{DONE} nor
10045 @code{FAIL}), then the @code{define_peephole2} uses the replacement
10046 template.
10047
10048 Insns are scanned in forward order from beginning to end for each basic
10049 block. Matches are attempted in order of @code{define_peephole2}
10050 appearance in the @file{md} file. After a successful replacement,
10051 scanning for further opportunities for @code{define_peephole2}, resumes
10052 with the first generated replacement insn as the first insn to be
10053 matched against all @code{define_peephole2}. For the example above,
10054 after its successful replacement, the first insn that can be matched by
10055 a @code{define_peephole2} is @code{(set (match_dup 4) (match_dup 1))}.
10056
10057 @end ifset
10058 @ifset INTERNALS
10059 @node Insn Attributes
10060 @section Instruction Attributes
10061 @cindex insn attributes
10062 @cindex instruction attributes
10063
10064 In addition to describing the instruction supported by the target machine,
10065 the @file{md} file also defines a group of @dfn{attributes} and a set of
10066 values for each. Every generated insn is assigned a value for each attribute.
10067 One possible attribute would be the effect that the insn has on the machine's
10068 condition code.
10069
10070 @menu
10071 * Defining Attributes:: Specifying attributes and their values.
10072 * Expressions:: Valid expressions for attribute values.
10073 * Tagging Insns:: Assigning attribute values to insns.
10074 * Attr Example:: An example of assigning attributes.
10075 * Insn Lengths:: Computing the length of insns.
10076 * Constant Attributes:: Defining attributes that are constant.
10077 * Mnemonic Attribute:: Obtain the instruction mnemonic as attribute value.
10078 * Delay Slots:: Defining delay slots required for a machine.
10079 * Processor pipeline description:: Specifying information for insn scheduling.
10080 @end menu
10081
10082 @end ifset
10083 @ifset INTERNALS
10084 @node Defining Attributes
10085 @subsection Defining Attributes and their Values
10086 @cindex defining attributes and their values
10087 @cindex attributes, defining
10088
10089 @findex define_attr
10090 The @code{define_attr} expression is used to define each attribute required
10091 by the target machine. It looks like:
10092
10093 @smallexample
10094 (define_attr @var{name} @var{list-of-values} @var{default})
10095 @end smallexample
10096
10097 @var{name} is a string specifying the name of the attribute being
10098 defined. Some attributes are used in a special way by the rest of the
10099 compiler. The @code{enabled} attribute can be used to conditionally
10100 enable or disable insn alternatives (@pxref{Disable Insn
10101 Alternatives}). The @code{predicable} attribute, together with a
10102 suitable @code{define_cond_exec} (@pxref{Conditional Execution}), can
10103 be used to automatically generate conditional variants of instruction
10104 patterns. The @code{mnemonic} attribute can be used to check for the
10105 instruction mnemonic (@pxref{Mnemonic Attribute}). The compiler
10106 internally uses the names @code{ce_enabled} and @code{nonce_enabled},
10107 so they should not be used elsewhere as alternative names.
10108
10109 @var{list-of-values} is either a string that specifies a comma-separated
10110 list of values that can be assigned to the attribute, or a null string to
10111 indicate that the attribute takes numeric values.
10112
10113 @var{default} is an attribute expression that gives the value of this
10114 attribute for insns that match patterns whose definition does not include
10115 an explicit value for this attribute. @xref{Attr Example}, for more
10116 information on the handling of defaults. @xref{Constant Attributes},
10117 for information on attributes that do not depend on any particular insn.
10118
10119 @findex insn-attr.h
10120 For each defined attribute, a number of definitions are written to the
10121 @file{insn-attr.h} file. For cases where an explicit set of values is
10122 specified for an attribute, the following are defined:
10123
10124 @itemize @bullet
10125 @item
10126 A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}.
10127
10128 @item
10129 An enumerated class is defined for @samp{attr_@var{name}} with
10130 elements of the form @samp{@var{upper-name}_@var{upper-value}} where
10131 the attribute name and value are first converted to uppercase.
10132
10133 @item
10134 A function @samp{get_attr_@var{name}} is defined that is passed an insn and
10135 returns the attribute value for that insn.
10136 @end itemize
10137
10138 For example, if the following is present in the @file{md} file:
10139
10140 @smallexample
10141 (define_attr "type" "branch,fp,load,store,arith" @dots{})
10142 @end smallexample
10143
10144 @noindent
10145 the following lines will be written to the file @file{insn-attr.h}.
10146
10147 @smallexample
10148 #define HAVE_ATTR_type 1
10149 enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD,
10150 TYPE_STORE, TYPE_ARITH@};
10151 extern enum attr_type get_attr_type ();
10152 @end smallexample
10153
10154 If the attribute takes numeric values, no @code{enum} type will be
10155 defined and the function to obtain the attribute's value will return
10156 @code{int}.
10157
10158 There are attributes which are tied to a specific meaning. These
10159 attributes are not free to use for other purposes:
10160
10161 @table @code
10162 @item length
10163 The @code{length} attribute is used to calculate the length of emitted
10164 code chunks. This is especially important when verifying branch
10165 distances. @xref{Insn Lengths}.
10166
10167 @item enabled
10168 The @code{enabled} attribute can be defined to prevent certain
10169 alternatives of an insn definition from being used during code
10170 generation. @xref{Disable Insn Alternatives}.
10171
10172 @item mnemonic
10173 The @code{mnemonic} attribute can be defined to implement instruction
10174 specific checks in e.g.@: the pipeline description.
10175 @xref{Mnemonic Attribute}.
10176 @end table
10177
10178 For each of these special attributes, the corresponding
10179 @samp{HAVE_ATTR_@var{name}} @samp{#define} is also written when the
10180 attribute is not defined; in that case, it is defined as @samp{0}.
10181
10182 @findex define_enum_attr
10183 @anchor{define_enum_attr}
10184 Another way of defining an attribute is to use:
10185
10186 @smallexample
10187 (define_enum_attr "@var{attr}" "@var{enum}" @var{default})
10188 @end smallexample
10189
10190 This works in just the same way as @code{define_attr}, except that
10191 the list of values is taken from a separate enumeration called
10192 @var{enum} (@pxref{define_enum}). This form allows you to use
10193 the same list of values for several attributes without having to
10194 repeat the list each time. For example:
10195
10196 @smallexample
10197 (define_enum "processor" [
10198 model_a
10199 model_b
10200 @dots{}
10201 ])
10202 (define_enum_attr "arch" "processor"
10203 (const (symbol_ref "target_arch")))
10204 (define_enum_attr "tune" "processor"
10205 (const (symbol_ref "target_tune")))
10206 @end smallexample
10207
10208 defines the same attributes as:
10209
10210 @smallexample
10211 (define_attr "arch" "model_a,model_b,@dots{}"
10212 (const (symbol_ref "target_arch")))
10213 (define_attr "tune" "model_a,model_b,@dots{}"
10214 (const (symbol_ref "target_tune")))
10215 @end smallexample
10216
10217 but without duplicating the processor list. The second example defines two
10218 separate C enums (@code{attr_arch} and @code{attr_tune}) whereas the first
10219 defines a single C enum (@code{processor}).
10220 @end ifset
10221 @ifset INTERNALS
10222 @node Expressions
10223 @subsection Attribute Expressions
10224 @cindex attribute expressions
10225
10226 RTL expressions used to define attributes use the codes described above
10227 plus a few specific to attribute definitions, to be discussed below.
10228 Attribute value expressions must have one of the following forms:
10229
10230 @table @code
10231 @cindex @code{const_int} and attributes
10232 @item (const_int @var{i})
10233 The integer @var{i} specifies the value of a numeric attribute. @var{i}
10234 must be non-negative.
10235
10236 The value of a numeric attribute can be specified either with a
10237 @code{const_int}, or as an integer represented as a string in
10238 @code{const_string}, @code{eq_attr} (see below), @code{attr},
10239 @code{symbol_ref}, simple arithmetic expressions, and @code{set_attr}
10240 overrides on specific instructions (@pxref{Tagging Insns}).
10241
10242 @cindex @code{const_string} and attributes
10243 @item (const_string @var{value})
10244 The string @var{value} specifies a constant attribute value.
10245 If @var{value} is specified as @samp{"*"}, it means that the default value of
10246 the attribute is to be used for the insn containing this expression.
10247 @samp{"*"} obviously cannot be used in the @var{default} expression
10248 of a @code{define_attr}.
10249
10250 If the attribute whose value is being specified is numeric, @var{value}
10251 must be a string containing a non-negative integer (normally
10252 @code{const_int} would be used in this case). Otherwise, it must
10253 contain one of the valid values for the attribute.
10254
10255 @cindex @code{if_then_else} and attributes
10256 @item (if_then_else @var{test} @var{true-value} @var{false-value})
10257 @var{test} specifies an attribute test, whose format is defined below.
10258 The value of this expression is @var{true-value} if @var{test} is true,
10259 otherwise it is @var{false-value}.
10260
10261 @cindex @code{cond} and attributes
10262 @item (cond [@var{test1} @var{value1} @dots{}] @var{default})
10263 The first operand of this expression is a vector containing an even
10264 number of expressions and consisting of pairs of @var{test} and @var{value}
10265 expressions. The value of the @code{cond} expression is that of the
10266 @var{value} corresponding to the first true @var{test} expression. If
10267 none of the @var{test} expressions are true, the value of the @code{cond}
10268 expression is that of the @var{default} expression.
10269 @end table
10270
10271 @var{test} expressions can have one of the following forms:
10272
10273 @table @code
10274 @cindex @code{const_int} and attribute tests
10275 @item (const_int @var{i})
10276 This test is true if @var{i} is nonzero and false otherwise.
10277
10278 @cindex @code{not} and attributes
10279 @cindex @code{ior} and attributes
10280 @cindex @code{and} and attributes
10281 @item (not @var{test})
10282 @itemx (ior @var{test1} @var{test2})
10283 @itemx (and @var{test1} @var{test2})
10284 These tests are true if the indicated logical function is true.
10285
10286 @cindex @code{match_operand} and attributes
10287 @item (match_operand:@var{m} @var{n} @var{pred} @var{constraints})
10288 This test is true if operand @var{n} of the insn whose attribute value
10289 is being determined has mode @var{m} (this part of the test is ignored
10290 if @var{m} is @code{VOIDmode}) and the function specified by the string
10291 @var{pred} returns a nonzero value when passed operand @var{n} and mode
10292 @var{m} (this part of the test is ignored if @var{pred} is the null
10293 string).
10294
10295 The @var{constraints} operand is ignored and should be the null string.
10296
10297 @cindex @code{match_test} and attributes
10298 @item (match_test @var{c-expr})
10299 The test is true if C expression @var{c-expr} is true. In non-constant
10300 attributes, @var{c-expr} has access to the following variables:
10301
10302 @table @var
10303 @item insn
10304 The rtl instruction under test.
10305 @item which_alternative
10306 The @code{define_insn} alternative that @var{insn} matches.
10307 @xref{Output Statement}.
10308 @item operands
10309 An array of @var{insn}'s rtl operands.
10310 @end table
10311
10312 @var{c-expr} behaves like the condition in a C @code{if} statement,
10313 so there is no need to explicitly convert the expression into a boolean
10314 0 or 1 value. For example, the following two tests are equivalent:
10315
10316 @smallexample
10317 (match_test "x & 2")
10318 (match_test "(x & 2) != 0")
10319 @end smallexample
10320
10321 @cindex @code{le} and attributes
10322 @cindex @code{leu} and attributes
10323 @cindex @code{lt} and attributes
10324 @cindex @code{gt} and attributes
10325 @cindex @code{gtu} and attributes
10326 @cindex @code{ge} and attributes
10327 @cindex @code{geu} and attributes
10328 @cindex @code{ne} and attributes
10329 @cindex @code{eq} and attributes
10330 @cindex @code{plus} and attributes
10331 @cindex @code{minus} and attributes
10332 @cindex @code{mult} and attributes
10333 @cindex @code{div} and attributes
10334 @cindex @code{mod} and attributes
10335 @cindex @code{abs} and attributes
10336 @cindex @code{neg} and attributes
10337 @cindex @code{ashift} and attributes
10338 @cindex @code{lshiftrt} and attributes
10339 @cindex @code{ashiftrt} and attributes
10340 @item (le @var{arith1} @var{arith2})
10341 @itemx (leu @var{arith1} @var{arith2})
10342 @itemx (lt @var{arith1} @var{arith2})
10343 @itemx (ltu @var{arith1} @var{arith2})
10344 @itemx (gt @var{arith1} @var{arith2})
10345 @itemx (gtu @var{arith1} @var{arith2})
10346 @itemx (ge @var{arith1} @var{arith2})
10347 @itemx (geu @var{arith1} @var{arith2})
10348 @itemx (ne @var{arith1} @var{arith2})
10349 @itemx (eq @var{arith1} @var{arith2})
10350 These tests are true if the indicated comparison of the two arithmetic
10351 expressions is true. Arithmetic expressions are formed with
10352 @code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod},
10353 @code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not},
10354 @code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions.
10355
10356 @findex get_attr
10357 @code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn
10358 Lengths},for additional forms). @code{symbol_ref} is a string
10359 denoting a C expression that yields an @code{int} when evaluated by the
10360 @samp{get_attr_@dots{}} routine. It should normally be a global
10361 variable.
10362
10363 @findex eq_attr
10364 @item (eq_attr @var{name} @var{value})
10365 @var{name} is a string specifying the name of an attribute.
10366
10367 @var{value} is a string that is either a valid value for attribute
10368 @var{name}, a comma-separated list of values, or @samp{!} followed by a
10369 value or list. If @var{value} does not begin with a @samp{!}, this
10370 test is true if the value of the @var{name} attribute of the current
10371 insn is in the list specified by @var{value}. If @var{value} begins
10372 with a @samp{!}, this test is true if the attribute's value is
10373 @emph{not} in the specified list.
10374
10375 For example,
10376
10377 @smallexample
10378 (eq_attr "type" "load,store")
10379 @end smallexample
10380
10381 @noindent
10382 is equivalent to
10383
10384 @smallexample
10385 (ior (eq_attr "type" "load") (eq_attr "type" "store"))
10386 @end smallexample
10387
10388 If @var{name} specifies an attribute of @samp{alternative}, it refers to the
10389 value of the compiler variable @code{which_alternative}
10390 (@pxref{Output Statement}) and the values must be small integers. For
10391 example,
10392
10393 @smallexample
10394 (eq_attr "alternative" "2,3")
10395 @end smallexample
10396
10397 @noindent
10398 is equivalent to
10399
10400 @smallexample
10401 (ior (eq (symbol_ref "which_alternative") (const_int 2))
10402 (eq (symbol_ref "which_alternative") (const_int 3)))
10403 @end smallexample
10404
10405 Note that, for most attributes, an @code{eq_attr} test is simplified in cases
10406 where the value of the attribute being tested is known for all insns matching
10407 a particular pattern. This is by far the most common case.
10408
10409 @findex attr_flag
10410 @item (attr_flag @var{name})
10411 The value of an @code{attr_flag} expression is true if the flag
10412 specified by @var{name} is true for the @code{insn} currently being
10413 scheduled.
10414
10415 @var{name} is a string specifying one of a fixed set of flags to test.
10416 Test the flags @code{forward} and @code{backward} to determine the
10417 direction of a conditional branch.
10418
10419 This example describes a conditional branch delay slot which
10420 can be nullified for forward branches that are taken (annul-true) or
10421 for backward branches which are not taken (annul-false).
10422
10423 @smallexample
10424 (define_delay (eq_attr "type" "cbranch")
10425 [(eq_attr "in_branch_delay" "true")
10426 (and (eq_attr "in_branch_delay" "true")
10427 (attr_flag "forward"))
10428 (and (eq_attr "in_branch_delay" "true")
10429 (attr_flag "backward"))])
10430 @end smallexample
10431
10432 The @code{forward} and @code{backward} flags are false if the current
10433 @code{insn} being scheduled is not a conditional branch.
10434
10435 @code{attr_flag} is only used during delay slot scheduling and has no
10436 meaning to other passes of the compiler.
10437
10438 @findex attr
10439 @item (attr @var{name})
10440 The value of another attribute is returned. This is most useful
10441 for numeric attributes, as @code{eq_attr} and @code{attr_flag}
10442 produce more efficient code for non-numeric attributes.
10443 @end table
10444
10445 @end ifset
10446 @ifset INTERNALS
10447 @node Tagging Insns
10448 @subsection Assigning Attribute Values to Insns
10449 @cindex tagging insns
10450 @cindex assigning attribute values to insns
10451
10452 The value assigned to an attribute of an insn is primarily determined by
10453 which pattern is matched by that insn (or which @code{define_peephole}
10454 generated it). Every @code{define_insn} and @code{define_peephole} can
10455 have an optional last argument to specify the values of attributes for
10456 matching insns. The value of any attribute not specified in a particular
10457 insn is set to the default value for that attribute, as specified in its
10458 @code{define_attr}. Extensive use of default values for attributes
10459 permits the specification of the values for only one or two attributes
10460 in the definition of most insn patterns, as seen in the example in the
10461 next section.
10462
10463 The optional last argument of @code{define_insn} and
10464 @code{define_peephole} is a vector of expressions, each of which defines
10465 the value for a single attribute. The most general way of assigning an
10466 attribute's value is to use a @code{set} expression whose first operand is an
10467 @code{attr} expression giving the name of the attribute being set. The
10468 second operand of the @code{set} is an attribute expression
10469 (@pxref{Expressions}) giving the value of the attribute.
10470
10471 When the attribute value depends on the @samp{alternative} attribute
10472 (i.e., which is the applicable alternative in the constraint of the
10473 insn), the @code{set_attr_alternative} expression can be used. It
10474 allows the specification of a vector of attribute expressions, one for
10475 each alternative.
10476
10477 @findex set_attr
10478 When the generality of arbitrary attribute expressions is not required,
10479 the simpler @code{set_attr} expression can be used, which allows
10480 specifying a string giving either a single attribute value or a list
10481 of attribute values, one for each alternative.
10482
10483 The form of each of the above specifications is shown below. In each case,
10484 @var{name} is a string specifying the attribute to be set.
10485
10486 @table @code
10487 @item (set_attr @var{name} @var{value-string})
10488 @var{value-string} is either a string giving the desired attribute value,
10489 or a string containing a comma-separated list giving the values for
10490 succeeding alternatives. The number of elements must match the number
10491 of alternatives in the constraint of the insn pattern.
10492
10493 Note that it may be useful to specify @samp{*} for some alternative, in
10494 which case the attribute will assume its default value for insns matching
10495 that alternative.
10496
10497 @findex set_attr_alternative
10498 @item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}])
10499 Depending on the alternative of the insn, the value will be one of the
10500 specified values. This is a shorthand for using a @code{cond} with
10501 tests on the @samp{alternative} attribute.
10502
10503 @findex attr
10504 @item (set (attr @var{name}) @var{value})
10505 The first operand of this @code{set} must be the special RTL expression
10506 @code{attr}, whose sole operand is a string giving the name of the
10507 attribute being set. @var{value} is the value of the attribute.
10508 @end table
10509
10510 The following shows three different ways of representing the same
10511 attribute value specification:
10512
10513 @smallexample
10514 (set_attr "type" "load,store,arith")
10515
10516 (set_attr_alternative "type"
10517 [(const_string "load") (const_string "store")
10518 (const_string "arith")])
10519
10520 (set (attr "type")
10521 (cond [(eq_attr "alternative" "1") (const_string "load")
10522 (eq_attr "alternative" "2") (const_string "store")]
10523 (const_string "arith")))
10524 @end smallexample
10525
10526 @need 1000
10527 @findex define_asm_attributes
10528 The @code{define_asm_attributes} expression provides a mechanism to
10529 specify the attributes assigned to insns produced from an @code{asm}
10530 statement. It has the form:
10531
10532 @smallexample
10533 (define_asm_attributes [@var{attr-sets}])
10534 @end smallexample
10535
10536 @noindent
10537 where @var{attr-sets} is specified the same as for both the
10538 @code{define_insn} and the @code{define_peephole} expressions.
10539
10540 These values will typically be the ``worst case'' attribute values. For
10541 example, they might indicate that the condition code will be clobbered.
10542
10543 A specification for a @code{length} attribute is handled specially. The
10544 way to compute the length of an @code{asm} insn is to multiply the
10545 length specified in the expression @code{define_asm_attributes} by the
10546 number of machine instructions specified in the @code{asm} statement,
10547 determined by counting the number of semicolons and newlines in the
10548 string. Therefore, the value of the @code{length} attribute specified
10549 in a @code{define_asm_attributes} should be the maximum possible length
10550 of a single machine instruction.
10551
10552 @end ifset
10553 @ifset INTERNALS
10554 @node Attr Example
10555 @subsection Example of Attribute Specifications
10556 @cindex attribute specifications example
10557 @cindex attribute specifications
10558
10559 The judicious use of defaulting is important in the efficient use of
10560 insn attributes. Typically, insns are divided into @dfn{types} and an
10561 attribute, customarily called @code{type}, is used to represent this
10562 value. This attribute is normally used only to define the default value
10563 for other attributes. An example will clarify this usage.
10564
10565 Assume we have a RISC machine with a condition code and in which only
10566 full-word operations are performed in registers. Let us assume that we
10567 can divide all insns into loads, stores, (integer) arithmetic
10568 operations, floating point operations, and branches.
10569
10570 Here we will concern ourselves with determining the effect of an insn on
10571 the condition code and will limit ourselves to the following possible
10572 effects: The condition code can be set unpredictably (clobbered), not
10573 be changed, be set to agree with the results of the operation, or only
10574 changed if the item previously set into the condition code has been
10575 modified.
10576
10577 Here is part of a sample @file{md} file for such a machine:
10578
10579 @smallexample
10580 (define_attr "type" "load,store,arith,fp,branch" (const_string "arith"))
10581
10582 (define_attr "cc" "clobber,unchanged,set,change0"
10583 (cond [(eq_attr "type" "load")
10584 (const_string "change0")
10585 (eq_attr "type" "store,branch")
10586 (const_string "unchanged")
10587 (eq_attr "type" "arith")
10588 (if_then_else (match_operand:SI 0 "" "")
10589 (const_string "set")
10590 (const_string "clobber"))]
10591 (const_string "clobber")))
10592
10593 (define_insn ""
10594 [(set (match_operand:SI 0 "general_operand" "=r,r,m")
10595 (match_operand:SI 1 "general_operand" "r,m,r"))]
10596 ""
10597 "@@
10598 move %0,%1
10599 load %0,%1
10600 store %0,%1"
10601 [(set_attr "type" "arith,load,store")])
10602 @end smallexample
10603
10604 Note that we assume in the above example that arithmetic operations
10605 performed on quantities smaller than a machine word clobber the condition
10606 code since they will set the condition code to a value corresponding to the
10607 full-word result.
10608
10609 @end ifset
10610 @ifset INTERNALS
10611 @node Insn Lengths
10612 @subsection Computing the Length of an Insn
10613 @cindex insn lengths, computing
10614 @cindex computing the length of an insn
10615
10616 For many machines, multiple types of branch instructions are provided, each
10617 for different length branch displacements. In most cases, the assembler
10618 will choose the correct instruction to use. However, when the assembler
10619 cannot do so, GCC can when a special attribute, the @code{length}
10620 attribute, is defined. This attribute must be defined to have numeric
10621 values by specifying a null string in its @code{define_attr}.
10622
10623 In the case of the @code{length} attribute, two additional forms of
10624 arithmetic terms are allowed in test expressions:
10625
10626 @table @code
10627 @cindex @code{match_dup} and attributes
10628 @item (match_dup @var{n})
10629 This refers to the address of operand @var{n} of the current insn, which
10630 must be a @code{label_ref}.
10631
10632 @cindex @code{pc} and attributes
10633 @item (pc)
10634 For non-branch instructions and backward branch instructions, this refers
10635 to the address of the current insn. But for forward branch instructions,
10636 this refers to the address of the next insn, because the length of the
10637 current insn is to be computed.
10638 @end table
10639
10640 @cindex @code{addr_vec}, length of
10641 @cindex @code{addr_diff_vec}, length of
10642 For normal insns, the length will be determined by value of the
10643 @code{length} attribute. In the case of @code{addr_vec} and
10644 @code{addr_diff_vec} insn patterns, the length is computed as
10645 the number of vectors multiplied by the size of each vector.
10646
10647 Lengths are measured in addressable storage units (bytes).
10648
10649 Note that it is possible to call functions via the @code{symbol_ref}
10650 mechanism to compute the length of an insn. However, if you use this
10651 mechanism you must provide dummy clauses to express the maximum length
10652 without using the function call. You can see an example of this in the
10653 @code{pa} machine description for the @code{call_symref} pattern.
10654
10655 The following macros can be used to refine the length computation:
10656
10657 @table @code
10658 @findex ADJUST_INSN_LENGTH
10659 @item ADJUST_INSN_LENGTH (@var{insn}, @var{length})
10660 If defined, modifies the length assigned to instruction @var{insn} as a
10661 function of the context in which it is used. @var{length} is an lvalue
10662 that contains the initially computed length of the insn and should be
10663 updated with the correct length of the insn.
10664
10665 This macro will normally not be required. A case in which it is
10666 required is the ROMP@. On this machine, the size of an @code{addr_vec}
10667 insn must be increased by two to compensate for the fact that alignment
10668 may be required.
10669 @end table
10670
10671 @findex get_attr_length
10672 The routine that returns @code{get_attr_length} (the value of the
10673 @code{length} attribute) can be used by the output routine to
10674 determine the form of the branch instruction to be written, as the
10675 example below illustrates.
10676
10677 As an example of the specification of variable-length branches, consider
10678 the IBM 360. If we adopt the convention that a register will be set to
10679 the starting address of a function, we can jump to labels within 4k of
10680 the start using a four-byte instruction. Otherwise, we need a six-byte
10681 sequence to load the address from memory and then branch to it.
10682
10683 On such a machine, a pattern for a branch instruction might be specified
10684 as follows:
10685
10686 @smallexample
10687 (define_insn "jump"
10688 [(set (pc)
10689 (label_ref (match_operand 0 "" "")))]
10690 ""
10691 @{
10692 return (get_attr_length (insn) == 4
10693 ? "b %l0" : "l r15,=a(%l0); br r15");
10694 @}
10695 [(set (attr "length")
10696 (if_then_else (lt (match_dup 0) (const_int 4096))
10697 (const_int 4)
10698 (const_int 6)))])
10699 @end smallexample
10700
10701 @end ifset
10702 @ifset INTERNALS
10703 @node Constant Attributes
10704 @subsection Constant Attributes
10705 @cindex constant attributes
10706
10707 A special form of @code{define_attr}, where the expression for the
10708 default value is a @code{const} expression, indicates an attribute that
10709 is constant for a given run of the compiler. Constant attributes may be
10710 used to specify which variety of processor is used. For example,
10711
10712 @smallexample
10713 (define_attr "cpu" "m88100,m88110,m88000"
10714 (const
10715 (cond [(symbol_ref "TARGET_88100") (const_string "m88100")
10716 (symbol_ref "TARGET_88110") (const_string "m88110")]
10717 (const_string "m88000"))))
10718
10719 (define_attr "memory" "fast,slow"
10720 (const
10721 (if_then_else (symbol_ref "TARGET_FAST_MEM")
10722 (const_string "fast")
10723 (const_string "slow"))))
10724 @end smallexample
10725
10726 The routine generated for constant attributes has no parameters as it
10727 does not depend on any particular insn. RTL expressions used to define
10728 the value of a constant attribute may use the @code{symbol_ref} form,
10729 but may not use either the @code{match_operand} form or @code{eq_attr}
10730 forms involving insn attributes.
10731
10732 @end ifset
10733 @ifset INTERNALS
10734 @node Mnemonic Attribute
10735 @subsection Mnemonic Attribute
10736 @cindex mnemonic attribute
10737
10738 The @code{mnemonic} attribute is a string type attribute holding the
10739 instruction mnemonic for an insn alternative. The attribute values
10740 will automatically be generated by the machine description parser if
10741 there is an attribute definition in the md file:
10742
10743 @smallexample
10744 (define_attr "mnemonic" "unknown" (const_string "unknown"))
10745 @end smallexample
10746
10747 The default value can be freely chosen as long as it does not collide
10748 with any of the instruction mnemonics. This value will be used
10749 whenever the machine description parser is not able to determine the
10750 mnemonic string. This might be the case for output templates
10751 containing more than a single instruction as in
10752 @code{"mvcle\t%0,%1,0\;jo\t.-4"}.
10753
10754 The @code{mnemonic} attribute set is not generated automatically if the
10755 instruction string is generated via C code.
10756
10757 An existing @code{mnemonic} attribute set in an insn definition will not
10758 be overriden by the md file parser. That way it is possible to
10759 manually set the instruction mnemonics for the cases where the md file
10760 parser fails to determine it automatically.
10761
10762 The @code{mnemonic} attribute is useful for dealing with instruction
10763 specific properties in the pipeline description without defining
10764 additional insn attributes.
10765
10766 @smallexample
10767 (define_attr "ooo_expanded" ""
10768 (cond [(eq_attr "mnemonic" "dlr,dsgr,d,dsgf,stam,dsgfr,dlgr")
10769 (const_int 1)]
10770 (const_int 0)))
10771 @end smallexample
10772
10773 @end ifset
10774 @ifset INTERNALS
10775 @node Delay Slots
10776 @subsection Delay Slot Scheduling
10777 @cindex delay slots, defining
10778
10779 The insn attribute mechanism can be used to specify the requirements for
10780 delay slots, if any, on a target machine. An instruction is said to
10781 require a @dfn{delay slot} if some instructions that are physically
10782 after the instruction are executed as if they were located before it.
10783 Classic examples are branch and call instructions, which often execute
10784 the following instruction before the branch or call is performed.
10785
10786 On some machines, conditional branch instructions can optionally
10787 @dfn{annul} instructions in the delay slot. This means that the
10788 instruction will not be executed for certain branch outcomes. Both
10789 instructions that annul if the branch is true and instructions that
10790 annul if the branch is false are supported.
10791
10792 Delay slot scheduling differs from instruction scheduling in that
10793 determining whether an instruction needs a delay slot is dependent only
10794 on the type of instruction being generated, not on data flow between the
10795 instructions. See the next section for a discussion of data-dependent
10796 instruction scheduling.
10797
10798 @findex define_delay
10799 The requirement of an insn needing one or more delay slots is indicated
10800 via the @code{define_delay} expression. It has the following form:
10801
10802 @smallexample
10803 (define_delay @var{test}
10804 [@var{delay-1} @var{annul-true-1} @var{annul-false-1}
10805 @var{delay-2} @var{annul-true-2} @var{annul-false-2}
10806 @dots{}])
10807 @end smallexample
10808
10809 @var{test} is an attribute test that indicates whether this
10810 @code{define_delay} applies to a particular insn. If so, the number of
10811 required delay slots is determined by the length of the vector specified
10812 as the second argument. An insn placed in delay slot @var{n} must
10813 satisfy attribute test @var{delay-n}. @var{annul-true-n} is an
10814 attribute test that specifies which insns may be annulled if the branch
10815 is true. Similarly, @var{annul-false-n} specifies which insns in the
10816 delay slot may be annulled if the branch is false. If annulling is not
10817 supported for that delay slot, @code{(nil)} should be coded.
10818
10819 For example, in the common case where branch and call insns require
10820 a single delay slot, which may contain any insn other than a branch or
10821 call, the following would be placed in the @file{md} file:
10822
10823 @smallexample
10824 (define_delay (eq_attr "type" "branch,call")
10825 [(eq_attr "type" "!branch,call") (nil) (nil)])
10826 @end smallexample
10827
10828 Multiple @code{define_delay} expressions may be specified. In this
10829 case, each such expression specifies different delay slot requirements
10830 and there must be no insn for which tests in two @code{define_delay}
10831 expressions are both true.
10832
10833 For example, if we have a machine that requires one delay slot for branches
10834 but two for calls, no delay slot can contain a branch or call insn,
10835 and any valid insn in the delay slot for the branch can be annulled if the
10836 branch is true, we might represent this as follows:
10837
10838 @smallexample
10839 (define_delay (eq_attr "type" "branch")
10840 [(eq_attr "type" "!branch,call")
10841 (eq_attr "type" "!branch,call")
10842 (nil)])
10843
10844 (define_delay (eq_attr "type" "call")
10845 [(eq_attr "type" "!branch,call") (nil) (nil)
10846 (eq_attr "type" "!branch,call") (nil) (nil)])
10847 @end smallexample
10848 @c the above is *still* too long. --mew 4feb93
10849
10850 @end ifset
10851 @ifset INTERNALS
10852 @node Processor pipeline description
10853 @subsection Specifying processor pipeline description
10854 @cindex processor pipeline description
10855 @cindex processor functional units
10856 @cindex instruction latency time
10857 @cindex interlock delays
10858 @cindex data dependence delays
10859 @cindex reservation delays
10860 @cindex pipeline hazard recognizer
10861 @cindex automaton based pipeline description
10862 @cindex regular expressions
10863 @cindex deterministic finite state automaton
10864 @cindex automaton based scheduler
10865 @cindex RISC
10866 @cindex VLIW
10867
10868 To achieve better performance, most modern processors
10869 (super-pipelined, superscalar @acronym{RISC}, and @acronym{VLIW}
10870 processors) have many @dfn{functional units} on which several
10871 instructions can be executed simultaneously. An instruction starts
10872 execution if its issue conditions are satisfied. If not, the
10873 instruction is stalled until its conditions are satisfied. Such
10874 @dfn{interlock (pipeline) delay} causes interruption of the fetching
10875 of successor instructions (or demands nop instructions, e.g.@: for some
10876 MIPS processors).
10877
10878 There are two major kinds of interlock delays in modern processors.
10879 The first one is a data dependence delay determining @dfn{instruction
10880 latency time}. The instruction execution is not started until all
10881 source data have been evaluated by prior instructions (there are more
10882 complex cases when the instruction execution starts even when the data
10883 are not available but will be ready in given time after the
10884 instruction execution start). Taking the data dependence delays into
10885 account is simple. The data dependence (true, output, and
10886 anti-dependence) delay between two instructions is given by a
10887 constant. In most cases this approach is adequate. The second kind
10888 of interlock delays is a reservation delay. The reservation delay
10889 means that two instructions under execution will be in need of shared
10890 processors resources, i.e.@: buses, internal registers, and/or
10891 functional units, which are reserved for some time. Taking this kind
10892 of delay into account is complex especially for modern @acronym{RISC}
10893 processors.
10894
10895 The task of exploiting more processor parallelism is solved by an
10896 instruction scheduler. For a better solution to this problem, the
10897 instruction scheduler has to have an adequate description of the
10898 processor parallelism (or @dfn{pipeline description}). GCC
10899 machine descriptions describe processor parallelism and functional
10900 unit reservations for groups of instructions with the aid of
10901 @dfn{regular expressions}.
10902
10903 The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to
10904 figure out the possibility of the instruction issue by the processor
10905 on a given simulated processor cycle. The pipeline hazard recognizer is
10906 automatically generated from the processor pipeline description. The
10907 pipeline hazard recognizer generated from the machine description
10908 is based on a deterministic finite state automaton (@acronym{DFA}):
10909 the instruction issue is possible if there is a transition from one
10910 automaton state to another one. This algorithm is very fast, and
10911 furthermore, its speed is not dependent on processor
10912 complexity@footnote{However, the size of the automaton depends on
10913 processor complexity. To limit this effect, machine descriptions
10914 can split orthogonal parts of the machine description among several
10915 automata: but then, since each of these must be stepped independently,
10916 this does cause a small decrease in the algorithm's performance.}.
10917
10918 @cindex automaton based pipeline description
10919 The rest of this section describes the directives that constitute
10920 an automaton-based processor pipeline description. The order of
10921 these constructions within the machine description file is not
10922 important.
10923
10924 @findex define_automaton
10925 @cindex pipeline hazard recognizer
10926 The following optional construction describes names of automata
10927 generated and used for the pipeline hazards recognition. Sometimes
10928 the generated finite state automaton used by the pipeline hazard
10929 recognizer is large. If we use more than one automaton and bind functional
10930 units to the automata, the total size of the automata is usually
10931 less than the size of the single automaton. If there is no one such
10932 construction, only one finite state automaton is generated.
10933
10934 @smallexample
10935 (define_automaton @var{automata-names})
10936 @end smallexample
10937
10938 @var{automata-names} is a string giving names of the automata. The
10939 names are separated by commas. All the automata should have unique names.
10940 The automaton name is used in the constructions @code{define_cpu_unit} and
10941 @code{define_query_cpu_unit}.
10942
10943 @findex define_cpu_unit
10944 @cindex processor functional units
10945 Each processor functional unit used in the description of instruction
10946 reservations should be described by the following construction.
10947
10948 @smallexample
10949 (define_cpu_unit @var{unit-names} [@var{automaton-name}])
10950 @end smallexample
10951
10952 @var{unit-names} is a string giving the names of the functional units
10953 separated by commas. Don't use name @samp{nothing}, it is reserved
10954 for other goals.
10955
10956 @var{automaton-name} is a string giving the name of the automaton with
10957 which the unit is bound. The automaton should be described in
10958 construction @code{define_automaton}. You should give
10959 @dfn{automaton-name}, if there is a defined automaton.
10960
10961 The assignment of units to automata are constrained by the uses of the
10962 units in insn reservations. The most important constraint is: if a
10963 unit reservation is present on a particular cycle of an alternative
10964 for an insn reservation, then some unit from the same automaton must
10965 be present on the same cycle for the other alternatives of the insn
10966 reservation. The rest of the constraints are mentioned in the
10967 description of the subsequent constructions.
10968
10969 @findex define_query_cpu_unit
10970 @cindex querying function unit reservations
10971 The following construction describes CPU functional units analogously
10972 to @code{define_cpu_unit}. The reservation of such units can be
10973 queried for an automaton state. The instruction scheduler never
10974 queries reservation of functional units for given automaton state. So
10975 as a rule, you don't need this construction. This construction could
10976 be used for future code generation goals (e.g.@: to generate
10977 @acronym{VLIW} insn templates).
10978
10979 @smallexample
10980 (define_query_cpu_unit @var{unit-names} [@var{automaton-name}])
10981 @end smallexample
10982
10983 @var{unit-names} is a string giving names of the functional units
10984 separated by commas.
10985
10986 @var{automaton-name} is a string giving the name of the automaton with
10987 which the unit is bound.
10988
10989 @findex define_insn_reservation
10990 @cindex instruction latency time
10991 @cindex regular expressions
10992 @cindex data bypass
10993 The following construction is the major one to describe pipeline
10994 characteristics of an instruction.
10995
10996 @smallexample
10997 (define_insn_reservation @var{insn-name} @var{default_latency}
10998 @var{condition} @var{regexp})
10999 @end smallexample
11000
11001 @var{default_latency} is a number giving latency time of the
11002 instruction. There is an important difference between the old
11003 description and the automaton based pipeline description. The latency
11004 time is used for all dependencies when we use the old description. In
11005 the automaton based pipeline description, the given latency time is only
11006 used for true dependencies. The cost of anti-dependencies is always
11007 zero and the cost of output dependencies is the difference between
11008 latency times of the producing and consuming insns (if the difference
11009 is negative, the cost is considered to be zero). You can always
11010 change the default costs for any description by using the target hook
11011 @code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}).
11012
11013 @var{insn-name} is a string giving the internal name of the insn. The
11014 internal names are used in constructions @code{define_bypass} and in
11015 the automaton description file generated for debugging. The internal
11016 name has nothing in common with the names in @code{define_insn}. It is a
11017 good practice to use insn classes described in the processor manual.
11018
11019 @var{condition} defines what RTL insns are described by this
11020 construction. You should remember that you will be in trouble if
11021 @var{condition} for two or more different
11022 @code{define_insn_reservation} constructions is TRUE for an insn. In
11023 this case what reservation will be used for the insn is not defined.
11024 Such cases are not checked during generation of the pipeline hazards
11025 recognizer because in general recognizing that two conditions may have
11026 the same value is quite difficult (especially if the conditions
11027 contain @code{symbol_ref}). It is also not checked during the
11028 pipeline hazard recognizer work because it would slow down the
11029 recognizer considerably.
11030
11031 @var{regexp} is a string describing the reservation of the cpu's functional
11032 units by the instruction. The reservations are described by a regular
11033 expression according to the following syntax:
11034
11035 @smallexample
11036 regexp = regexp "," oneof
11037 | oneof
11038
11039 oneof = oneof "|" allof
11040 | allof
11041
11042 allof = allof "+" repeat
11043 | repeat
11044
11045 repeat = element "*" number
11046 | element
11047
11048 element = cpu_function_unit_name
11049 | reservation_name
11050 | result_name
11051 | "nothing"
11052 | "(" regexp ")"
11053 @end smallexample
11054
11055 @itemize @bullet
11056 @item
11057 @samp{,} is used for describing the start of the next cycle in
11058 the reservation.
11059
11060 @item
11061 @samp{|} is used for describing a reservation described by the first
11062 regular expression @strong{or} a reservation described by the second
11063 regular expression @strong{or} etc.
11064
11065 @item
11066 @samp{+} is used for describing a reservation described by the first
11067 regular expression @strong{and} a reservation described by the
11068 second regular expression @strong{and} etc.
11069
11070 @item
11071 @samp{*} is used for convenience and simply means a sequence in which
11072 the regular expression are repeated @var{number} times with cycle
11073 advancing (see @samp{,}).
11074
11075 @item
11076 @samp{cpu_function_unit_name} denotes reservation of the named
11077 functional unit.
11078
11079 @item
11080 @samp{reservation_name} --- see description of construction
11081 @samp{define_reservation}.
11082
11083 @item
11084 @samp{nothing} denotes no unit reservations.
11085 @end itemize
11086
11087 @findex define_reservation
11088 Sometimes unit reservations for different insns contain common parts.
11089 In such case, you can simplify the pipeline description by describing
11090 the common part by the following construction
11091
11092 @smallexample
11093 (define_reservation @var{reservation-name} @var{regexp})
11094 @end smallexample
11095
11096 @var{reservation-name} is a string giving name of @var{regexp}.
11097 Functional unit names and reservation names are in the same name
11098 space. So the reservation names should be different from the
11099 functional unit names and cannot be the reserved name @samp{nothing}.
11100
11101 @findex define_bypass
11102 @cindex instruction latency time
11103 @cindex data bypass
11104 The following construction is used to describe exceptions in the
11105 latency time for given instruction pair. This is so called bypasses.
11106
11107 @smallexample
11108 (define_bypass @var{number} @var{out_insn_names} @var{in_insn_names}
11109 [@var{guard}])
11110 @end smallexample
11111
11112 @var{number} defines when the result generated by the instructions
11113 given in string @var{out_insn_names} will be ready for the
11114 instructions given in string @var{in_insn_names}. Each of these
11115 strings is a comma-separated list of filename-style globs and
11116 they refer to the names of @code{define_insn_reservation}s.
11117 For example:
11118 @smallexample
11119 (define_bypass 1 "cpu1_load_*, cpu1_store_*" "cpu1_load_*")
11120 @end smallexample
11121 defines a bypass between instructions that start with
11122 @samp{cpu1_load_} or @samp{cpu1_store_} and those that start with
11123 @samp{cpu1_load_}.
11124
11125 @var{guard} is an optional string giving the name of a C function which
11126 defines an additional guard for the bypass. The function will get the
11127 two insns as parameters. If the function returns zero the bypass will
11128 be ignored for this case. The additional guard is necessary to
11129 recognize complicated bypasses, e.g.@: when the consumer is only an address
11130 of insn @samp{store} (not a stored value).
11131
11132 If there are more one bypass with the same output and input insns, the
11133 chosen bypass is the first bypass with a guard in description whose
11134 guard function returns nonzero. If there is no such bypass, then
11135 bypass without the guard function is chosen.
11136
11137 @findex exclusion_set
11138 @findex presence_set
11139 @findex final_presence_set
11140 @findex absence_set
11141 @findex final_absence_set
11142 @cindex VLIW
11143 @cindex RISC
11144 The following five constructions are usually used to describe
11145 @acronym{VLIW} processors, or more precisely, to describe a placement
11146 of small instructions into @acronym{VLIW} instruction slots. They
11147 can be used for @acronym{RISC} processors, too.
11148
11149 @smallexample
11150 (exclusion_set @var{unit-names} @var{unit-names})
11151 (presence_set @var{unit-names} @var{patterns})
11152 (final_presence_set @var{unit-names} @var{patterns})
11153 (absence_set @var{unit-names} @var{patterns})
11154 (final_absence_set @var{unit-names} @var{patterns})
11155 @end smallexample
11156
11157 @var{unit-names} is a string giving names of functional units
11158 separated by commas.
11159
11160 @var{patterns} is a string giving patterns of functional units
11161 separated by comma. Currently pattern is one unit or units
11162 separated by white-spaces.
11163
11164 The first construction (@samp{exclusion_set}) means that each
11165 functional unit in the first string cannot be reserved simultaneously
11166 with a unit whose name is in the second string and vice versa. For
11167 example, the construction is useful for describing processors
11168 (e.g.@: some SPARC processors) with a fully pipelined floating point
11169 functional unit which can execute simultaneously only single floating
11170 point insns or only double floating point insns.
11171
11172 The second construction (@samp{presence_set}) means that each
11173 functional unit in the first string cannot be reserved unless at
11174 least one of pattern of units whose names are in the second string is
11175 reserved. This is an asymmetric relation. For example, it is useful
11176 for description that @acronym{VLIW} @samp{slot1} is reserved after
11177 @samp{slot0} reservation. We could describe it by the following
11178 construction
11179
11180 @smallexample
11181 (presence_set "slot1" "slot0")
11182 @end smallexample
11183
11184 Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0}
11185 reservation. In this case we could write
11186
11187 @smallexample
11188 (presence_set "slot1" "slot0 b0")
11189 @end smallexample
11190
11191 The third construction (@samp{final_presence_set}) is analogous to
11192 @samp{presence_set}. The difference between them is when checking is
11193 done. When an instruction is issued in given automaton state
11194 reflecting all current and planned unit reservations, the automaton
11195 state is changed. The first state is a source state, the second one
11196 is a result state. Checking for @samp{presence_set} is done on the
11197 source state reservation, checking for @samp{final_presence_set} is
11198 done on the result reservation. This construction is useful to
11199 describe a reservation which is actually two subsequent reservations.
11200 For example, if we use
11201
11202 @smallexample
11203 (presence_set "slot1" "slot0")
11204 @end smallexample
11205
11206 the following insn will be never issued (because @samp{slot1} requires
11207 @samp{slot0} which is absent in the source state).
11208
11209 @smallexample
11210 (define_reservation "insn_and_nop" "slot0 + slot1")
11211 @end smallexample
11212
11213 but it can be issued if we use analogous @samp{final_presence_set}.
11214
11215 The forth construction (@samp{absence_set}) means that each functional
11216 unit in the first string can be reserved only if each pattern of units
11217 whose names are in the second string is not reserved. This is an
11218 asymmetric relation (actually @samp{exclusion_set} is analogous to
11219 this one but it is symmetric). For example it might be useful in a
11220 @acronym{VLIW} description to say that @samp{slot0} cannot be reserved
11221 after either @samp{slot1} or @samp{slot2} have been reserved. This
11222 can be described as:
11223
11224 @smallexample
11225 (absence_set "slot0" "slot1, slot2")
11226 @end smallexample
11227
11228 Or @samp{slot2} cannot be reserved if @samp{slot0} and unit @samp{b0}
11229 are reserved or @samp{slot1} and unit @samp{b1} are reserved. In
11230 this case we could write
11231
11232 @smallexample
11233 (absence_set "slot2" "slot0 b0, slot1 b1")
11234 @end smallexample
11235
11236 All functional units mentioned in a set should belong to the same
11237 automaton.
11238
11239 The last construction (@samp{final_absence_set}) is analogous to
11240 @samp{absence_set} but checking is done on the result (state)
11241 reservation. See comments for @samp{final_presence_set}.
11242
11243 @findex automata_option
11244 @cindex deterministic finite state automaton
11245 @cindex nondeterministic finite state automaton
11246 @cindex finite state automaton minimization
11247 You can control the generator of the pipeline hazard recognizer with
11248 the following construction.
11249
11250 @smallexample
11251 (automata_option @var{options})
11252 @end smallexample
11253
11254 @var{options} is a string giving options which affect the generated
11255 code. Currently there are the following options:
11256
11257 @itemize @bullet
11258 @item
11259 @dfn{no-minimization} makes no minimization of the automaton. This is
11260 only worth to do when we are debugging the description and need to
11261 look more accurately at reservations of states.
11262
11263 @item
11264 @dfn{time} means printing time statistics about the generation of
11265 automata.
11266
11267 @item
11268 @dfn{stats} means printing statistics about the generated automata
11269 such as the number of DFA states, NDFA states and arcs.
11270
11271 @item
11272 @dfn{v} means a generation of the file describing the result automata.
11273 The file has suffix @samp{.dfa} and can be used for the description
11274 verification and debugging.
11275
11276 @item
11277 @dfn{w} means a generation of warning instead of error for
11278 non-critical errors.
11279
11280 @item
11281 @dfn{no-comb-vect} prevents the automaton generator from generating
11282 two data structures and comparing them for space efficiency. Using
11283 a comb vector to represent transitions may be better, but it can be
11284 very expensive to construct. This option is useful if the build
11285 process spends an unacceptably long time in genautomata.
11286
11287 @item
11288 @dfn{ndfa} makes nondeterministic finite state automata. This affects
11289 the treatment of operator @samp{|} in the regular expressions. The
11290 usual treatment of the operator is to try the first alternative and,
11291 if the reservation is not possible, the second alternative. The
11292 nondeterministic treatment means trying all alternatives, some of them
11293 may be rejected by reservations in the subsequent insns.
11294
11295 @item
11296 @dfn{collapse-ndfa} modifies the behavior of the generator when
11297 producing an automaton. An additional state transition to collapse a
11298 nondeterministic @acronym{NDFA} state to a deterministic @acronym{DFA}
11299 state is generated. It can be triggered by passing @code{const0_rtx} to
11300 state_transition. In such an automaton, cycle advance transitions are
11301 available only for these collapsed states. This option is useful for
11302 ports that want to use the @code{ndfa} option, but also want to use
11303 @code{define_query_cpu_unit} to assign units to insns issued in a cycle.
11304
11305 @item
11306 @dfn{progress} means output of a progress bar showing how many states
11307 were generated so far for automaton being processed. This is useful
11308 during debugging a @acronym{DFA} description. If you see too many
11309 generated states, you could interrupt the generator of the pipeline
11310 hazard recognizer and try to figure out a reason for generation of the
11311 huge automaton.
11312 @end itemize
11313
11314 As an example, consider a superscalar @acronym{RISC} machine which can
11315 issue three insns (two integer insns and one floating point insn) on
11316 the cycle but can finish only two insns. To describe this, we define
11317 the following functional units.
11318
11319 @smallexample
11320 (define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline")
11321 (define_cpu_unit "port0, port1")
11322 @end smallexample
11323
11324 All simple integer insns can be executed in any integer pipeline and
11325 their result is ready in two cycles. The simple integer insns are
11326 issued into the first pipeline unless it is reserved, otherwise they
11327 are issued into the second pipeline. Integer division and
11328 multiplication insns can be executed only in the second integer
11329 pipeline and their results are ready correspondingly in 9 and 4
11330 cycles. The integer division is not pipelined, i.e.@: the subsequent
11331 integer division insn cannot be issued until the current division
11332 insn finished. Floating point insns are fully pipelined and their
11333 results are ready in 3 cycles. Where the result of a floating point
11334 insn is used by an integer insn, an additional delay of one cycle is
11335 incurred. To describe all of this we could specify
11336
11337 @smallexample
11338 (define_cpu_unit "div")
11339
11340 (define_insn_reservation "simple" 2 (eq_attr "type" "int")
11341 "(i0_pipeline | i1_pipeline), (port0 | port1)")
11342
11343 (define_insn_reservation "mult" 4 (eq_attr "type" "mult")
11344 "i1_pipeline, nothing*2, (port0 | port1)")
11345
11346 (define_insn_reservation "div" 9 (eq_attr "type" "div")
11347 "i1_pipeline, div*7, div + (port0 | port1)")
11348
11349 (define_insn_reservation "float" 3 (eq_attr "type" "float")
11350 "f_pipeline, nothing, (port0 | port1))
11351
11352 (define_bypass 4 "float" "simple,mult,div")
11353 @end smallexample
11354
11355 To simplify the description we could describe the following reservation
11356
11357 @smallexample
11358 (define_reservation "finish" "port0|port1")
11359 @end smallexample
11360
11361 and use it in all @code{define_insn_reservation} as in the following
11362 construction
11363
11364 @smallexample
11365 (define_insn_reservation "simple" 2 (eq_attr "type" "int")
11366 "(i0_pipeline | i1_pipeline), finish")
11367 @end smallexample
11368
11369
11370 @end ifset
11371 @ifset INTERNALS
11372 @node Conditional Execution
11373 @section Conditional Execution
11374 @cindex conditional execution
11375 @cindex predication
11376
11377 A number of architectures provide for some form of conditional
11378 execution, or predication. The hallmark of this feature is the
11379 ability to nullify most of the instructions in the instruction set.
11380 When the instruction set is large and not entirely symmetric, it
11381 can be quite tedious to describe these forms directly in the
11382 @file{.md} file. An alternative is the @code{define_cond_exec} template.
11383
11384 @findex define_cond_exec
11385 @smallexample
11386 (define_cond_exec
11387 [@var{predicate-pattern}]
11388 "@var{condition}"
11389 "@var{output-template}"
11390 "@var{optional-insn-attribues}")
11391 @end smallexample
11392
11393 @var{predicate-pattern} is the condition that must be true for the
11394 insn to be executed at runtime and should match a relational operator.
11395 One can use @code{match_operator} to match several relational operators
11396 at once. Any @code{match_operand} operands must have no more than one
11397 alternative.
11398
11399 @var{condition} is a C expression that must be true for the generated
11400 pattern to match.
11401
11402 @findex current_insn_predicate
11403 @var{output-template} is a string similar to the @code{define_insn}
11404 output template (@pxref{Output Template}), except that the @samp{*}
11405 and @samp{@@} special cases do not apply. This is only useful if the
11406 assembly text for the predicate is a simple prefix to the main insn.
11407 In order to handle the general case, there is a global variable
11408 @code{current_insn_predicate} that will contain the entire predicate
11409 if the current insn is predicated, and will otherwise be @code{NULL}.
11410
11411 @var{optional-insn-attributes} is an optional vector of attributes that gets
11412 appended to the insn attributes of the produced cond_exec rtx. It can
11413 be used to add some distinguishing attribute to cond_exec rtxs produced
11414 that way. An example usage would be to use this attribute in conjunction
11415 with attributes on the main pattern to disable particular alternatives under
11416 certain conditions.
11417
11418 When @code{define_cond_exec} is used, an implicit reference to
11419 the @code{predicable} instruction attribute is made.
11420 @xref{Insn Attributes}. This attribute must be a boolean (i.e.@: have
11421 exactly two elements in its @var{list-of-values}), with the possible
11422 values being @code{no} and @code{yes}. The default and all uses in
11423 the insns must be a simple constant, not a complex expressions. It
11424 may, however, depend on the alternative, by using a comma-separated
11425 list of values. If that is the case, the port should also define an
11426 @code{enabled} attribute (@pxref{Disable Insn Alternatives}), which
11427 should also allow only @code{no} and @code{yes} as its values.
11428
11429 For each @code{define_insn} for which the @code{predicable}
11430 attribute is true, a new @code{define_insn} pattern will be
11431 generated that matches a predicated version of the instruction.
11432 For example,
11433
11434 @smallexample
11435 (define_insn "addsi"
11436 [(set (match_operand:SI 0 "register_operand" "r")
11437 (plus:SI (match_operand:SI 1 "register_operand" "r")
11438 (match_operand:SI 2 "register_operand" "r")))]
11439 "@var{test1}"
11440 "add %2,%1,%0")
11441
11442 (define_cond_exec
11443 [(ne (match_operand:CC 0 "register_operand" "c")
11444 (const_int 0))]
11445 "@var{test2}"
11446 "(%0)")
11447 @end smallexample
11448
11449 @noindent
11450 generates a new pattern
11451
11452 @smallexample
11453 (define_insn ""
11454 [(cond_exec
11455 (ne (match_operand:CC 3 "register_operand" "c") (const_int 0))
11456 (set (match_operand:SI 0 "register_operand" "r")
11457 (plus:SI (match_operand:SI 1 "register_operand" "r")
11458 (match_operand:SI 2 "register_operand" "r"))))]
11459 "(@var{test2}) && (@var{test1})"
11460 "(%3) add %2,%1,%0")
11461 @end smallexample
11462
11463 @end ifset
11464 @ifset INTERNALS
11465 @node Define Subst
11466 @section RTL Templates Transformations
11467 @cindex define_subst
11468
11469 For some hardware architectures there are common cases when the RTL
11470 templates for the instructions can be derived from the other RTL
11471 templates using simple transformations. E.g., @file{i386.md} contains
11472 an RTL template for the ordinary @code{sub} instruction---
11473 @code{*subsi_1}, and for the @code{sub} instruction with subsequent
11474 zero-extension---@code{*subsi_1_zext}. Such cases can be easily
11475 implemented by a single meta-template capable of generating a modified
11476 case based on the initial one:
11477
11478 @findex define_subst
11479 @smallexample
11480 (define_subst "@var{name}"
11481 [@var{input-template}]
11482 "@var{condition}"
11483 [@var{output-template}])
11484 @end smallexample
11485 @var{input-template} is a pattern describing the source RTL template,
11486 which will be transformed.
11487
11488 @var{condition} is a C expression that is conjunct with the condition
11489 from the input-template to generate a condition to be used in the
11490 output-template.
11491
11492 @var{output-template} is a pattern that will be used in the resulting
11493 template.
11494
11495 @code{define_subst} mechanism is tightly coupled with the notion of the
11496 subst attribute (@pxref{Subst Iterators}). The use of
11497 @code{define_subst} is triggered by a reference to a subst attribute in
11498 the transforming RTL template. This reference initiates duplication of
11499 the source RTL template and substitution of the attributes with their
11500 values. The source RTL template is left unchanged, while the copy is
11501 transformed by @code{define_subst}. This transformation can fail in the
11502 case when the source RTL template is not matched against the
11503 input-template of the @code{define_subst}. In such case the copy is
11504 deleted.
11505
11506 @code{define_subst} can be used only in @code{define_insn} and
11507 @code{define_expand}, it cannot be used in other expressions (e.g.@: in
11508 @code{define_insn_and_split}).
11509
11510 @menu
11511 * Define Subst Example:: Example of @code{define_subst} work.
11512 * Define Subst Pattern Matching:: Process of template comparison.
11513 * Define Subst Output Template:: Generation of output template.
11514 @end menu
11515
11516 @node Define Subst Example
11517 @subsection @code{define_subst} Example
11518 @cindex define_subst
11519
11520 To illustrate how @code{define_subst} works, let us examine a simple
11521 template transformation.
11522
11523 Suppose there are two kinds of instructions: one that touches flags and
11524 the other that does not. The instructions of the second type could be
11525 generated with the following @code{define_subst}:
11526
11527 @smallexample
11528 (define_subst "add_clobber_subst"
11529 [(set (match_operand:SI 0 "" "")
11530 (match_operand:SI 1 "" ""))]
11531 ""
11532 [(set (match_dup 0)
11533 (match_dup 1))
11534 (clobber (reg:CC FLAGS_REG))])
11535 @end smallexample
11536
11537 This @code{define_subst} can be applied to any RTL pattern containing
11538 @code{set} of mode SI and generates a copy with clobber when it is
11539 applied.
11540
11541 Assume there is an RTL template for a @code{max} instruction to be used
11542 in @code{define_subst} mentioned above:
11543
11544 @smallexample
11545 (define_insn "maxsi"
11546 [(set (match_operand:SI 0 "register_operand" "=r")
11547 (max:SI
11548 (match_operand:SI 1 "register_operand" "r")
11549 (match_operand:SI 2 "register_operand" "r")))]
11550 ""
11551 "max\t@{%2, %1, %0|%0, %1, %2@}"
11552 [@dots{}])
11553 @end smallexample
11554
11555 To mark the RTL template for @code{define_subst} application,
11556 subst-attributes are used. They should be declared in advance:
11557
11558 @smallexample
11559 (define_subst_attr "add_clobber_name" "add_clobber_subst" "_noclobber" "_clobber")
11560 @end smallexample
11561
11562 Here @samp{add_clobber_name} is the attribute name,
11563 @samp{add_clobber_subst} is the name of the corresponding
11564 @code{define_subst}, the third argument (@samp{_noclobber}) is the
11565 attribute value that would be substituted into the unchanged version of
11566 the source RTL template, and the last argument (@samp{_clobber}) is the
11567 value that would be substituted into the second, transformed,
11568 version of the RTL template.
11569
11570 Once the subst-attribute has been defined, it should be used in RTL
11571 templates which need to be processed by the @code{define_subst}. So,
11572 the original RTL template should be changed:
11573
11574 @smallexample
11575 (define_insn "maxsi<add_clobber_name>"
11576 [(set (match_operand:SI 0 "register_operand" "=r")
11577 (max:SI
11578 (match_operand:SI 1 "register_operand" "r")
11579 (match_operand:SI 2 "register_operand" "r")))]
11580 ""
11581 "max\t@{%2, %1, %0|%0, %1, %2@}"
11582 [@dots{}])
11583 @end smallexample
11584
11585 The result of the @code{define_subst} usage would look like the following:
11586
11587 @smallexample
11588 (define_insn "maxsi_noclobber"
11589 [(set (match_operand:SI 0 "register_operand" "=r")
11590 (max:SI
11591 (match_operand:SI 1 "register_operand" "r")
11592 (match_operand:SI 2 "register_operand" "r")))]
11593 ""
11594 "max\t@{%2, %1, %0|%0, %1, %2@}"
11595 [@dots{}])
11596 (define_insn "maxsi_clobber"
11597 [(set (match_operand:SI 0 "register_operand" "=r")
11598 (max:SI
11599 (match_operand:SI 1 "register_operand" "r")
11600 (match_operand:SI 2 "register_operand" "r")))
11601 (clobber (reg:CC FLAGS_REG))]
11602 ""
11603 "max\t@{%2, %1, %0|%0, %1, %2@}"
11604 [@dots{}])
11605 @end smallexample
11606
11607 @node Define Subst Pattern Matching
11608 @subsection Pattern Matching in @code{define_subst}
11609 @cindex define_subst
11610
11611 All expressions, allowed in @code{define_insn} or @code{define_expand},
11612 are allowed in the input-template of @code{define_subst}, except
11613 @code{match_par_dup}, @code{match_scratch}, @code{match_parallel}. The
11614 meanings of expressions in the input-template were changed:
11615
11616 @code{match_operand} matches any expression (possibly, a subtree in
11617 RTL-template), if modes of the @code{match_operand} and this expression
11618 are the same, or mode of the @code{match_operand} is @code{VOIDmode}, or
11619 this expression is @code{match_dup}, @code{match_op_dup}. If the
11620 expression is @code{match_operand} too, and predicate of
11621 @code{match_operand} from the input pattern is not empty, then the
11622 predicates are compared. That can be used for more accurate filtering
11623 of accepted RTL-templates.
11624
11625 @code{match_operator} matches common operators (like @code{plus},
11626 @code{minus}), @code{unspec}, @code{unspec_volatile} operators and
11627 @code{match_operator}s from the original pattern if the modes match and
11628 @code{match_operator} from the input pattern has the same number of
11629 operands as the operator from the original pattern.
11630
11631 @node Define Subst Output Template
11632 @subsection Generation of output template in @code{define_subst}
11633 @cindex define_subst
11634
11635 If all necessary checks for @code{define_subst} application pass, a new
11636 RTL-pattern, based on the output-template, is created to replace the old
11637 template. Like in input-patterns, meanings of some RTL expressions are
11638 changed when they are used in output-patterns of a @code{define_subst}.
11639 Thus, @code{match_dup} is used for copying the whole expression from the
11640 original pattern, which matched corresponding @code{match_operand} from
11641 the input pattern.
11642
11643 @code{match_dup N} is used in the output template to be replaced with
11644 the expression from the original pattern, which matched
11645 @code{match_operand N} from the input pattern. As a consequence,
11646 @code{match_dup} cannot be used to point to @code{match_operand}s from
11647 the output pattern, it should always refer to a @code{match_operand}
11648 from the input pattern. If a @code{match_dup N} occurs more than once
11649 in the output template, its first occurrence is replaced with the
11650 expression from the original pattern, and the subsequent expressions
11651 are replaced with @code{match_dup N}, i.e., a reference to the first
11652 expression.
11653
11654 In the output template one can refer to the expressions from the
11655 original pattern and create new ones. For instance, some operands could
11656 be added by means of standard @code{match_operand}.
11657
11658 After replacing @code{match_dup} with some RTL-subtree from the original
11659 pattern, it could happen that several @code{match_operand}s in the
11660 output pattern have the same indexes. It is unknown, how many and what
11661 indexes would be used in the expression which would replace
11662 @code{match_dup}, so such conflicts in indexes are inevitable. To
11663 overcome this issue, @code{match_operands} and @code{match_operators},
11664 which were introduced into the output pattern, are renumerated when all
11665 @code{match_dup}s are replaced.
11666
11667 Number of alternatives in @code{match_operand}s introduced into the
11668 output template @code{M} could differ from the number of alternatives in
11669 the original pattern @code{N}, so in the resultant pattern there would
11670 be @code{N*M} alternatives. Thus, constraints from the original pattern
11671 would be duplicated @code{N} times, constraints from the output pattern
11672 would be duplicated @code{M} times, producing all possible combinations.
11673 @end ifset
11674
11675 @ifset INTERNALS
11676 @node Constant Definitions
11677 @section Constant Definitions
11678 @cindex constant definitions
11679 @findex define_constants
11680
11681 Using literal constants inside instruction patterns reduces legibility and
11682 can be a maintenance problem.
11683
11684 To overcome this problem, you may use the @code{define_constants}
11685 expression. It contains a vector of name-value pairs. From that
11686 point on, wherever any of the names appears in the MD file, it is as
11687 if the corresponding value had been written instead. You may use
11688 @code{define_constants} multiple times; each appearance adds more
11689 constants to the table. It is an error to redefine a constant with
11690 a different value.
11691
11692 To come back to the a29k load multiple example, instead of
11693
11694 @smallexample
11695 (define_insn ""
11696 [(match_parallel 0 "load_multiple_operation"
11697 [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
11698 (match_operand:SI 2 "memory_operand" "m"))
11699 (use (reg:SI 179))
11700 (clobber (reg:SI 179))])]
11701 ""
11702 "loadm 0,0,%1,%2")
11703 @end smallexample
11704
11705 You could write:
11706
11707 @smallexample
11708 (define_constants [
11709 (R_BP 177)
11710 (R_FC 178)
11711 (R_CR 179)
11712 (R_Q 180)
11713 ])
11714
11715 (define_insn ""
11716 [(match_parallel 0 "load_multiple_operation"
11717 [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
11718 (match_operand:SI 2 "memory_operand" "m"))
11719 (use (reg:SI R_CR))
11720 (clobber (reg:SI R_CR))])]
11721 ""
11722 "loadm 0,0,%1,%2")
11723 @end smallexample
11724
11725 The constants that are defined with a define_constant are also output
11726 in the insn-codes.h header file as #defines.
11727
11728 @cindex enumerations
11729 @findex define_c_enum
11730 You can also use the machine description file to define enumerations.
11731 Like the constants defined by @code{define_constant}, these enumerations
11732 are visible to both the machine description file and the main C code.
11733
11734 The syntax is as follows:
11735
11736 @smallexample
11737 (define_c_enum "@var{name}" [
11738 @var{value0}
11739 @var{value1}
11740 (@var{value32} 32)
11741 @var{value33}
11742 @dots{}
11743 @var{valuen}
11744 ])
11745 @end smallexample
11746
11747 This definition causes the equivalent of the following C code to appear
11748 in @file{insn-constants.h}:
11749
11750 @smallexample
11751 enum @var{name} @{
11752 @var{value0} = 0,
11753 @var{value1} = 1,
11754 @var{value32} = 32,
11755 @var{value33} = 33,
11756 @dots{}
11757 @var{valuen} = @var{n}
11758 @};
11759 #define NUM_@var{cname}_VALUES (@var{n} + 1)
11760 @end smallexample
11761
11762 where @var{cname} is the capitalized form of @var{name}.
11763 It also makes each @var{valuei} available in the machine description
11764 file, just as if it had been declared with:
11765
11766 @smallexample
11767 (define_constants [(@var{valuei} @var{i})])
11768 @end smallexample
11769
11770 Each @var{valuei} is usually an upper-case identifier and usually
11771 begins with @var{cname}.
11772
11773 You can split the enumeration definition into as many statements as
11774 you like. The above example is directly equivalent to:
11775
11776 @smallexample
11777 (define_c_enum "@var{name}" [@var{value0}])
11778 (define_c_enum "@var{name}" [@var{value1}])
11779 @dots{}
11780 (define_c_enum "@var{name}" [@var{valuen}])
11781 @end smallexample
11782
11783 Splitting the enumeration helps to improve the modularity of each
11784 individual @code{.md} file. For example, if a port defines its
11785 synchronization instructions in a separate @file{sync.md} file,
11786 it is convenient to define all synchronization-specific enumeration
11787 values in @file{sync.md} rather than in the main @file{.md} file.
11788
11789 Some enumeration names have special significance to GCC:
11790
11791 @table @code
11792 @findex unspec_volatile
11793 @item unspecv
11794 If an enumeration called @code{unspecv} is defined, GCC will use it
11795 when printing out @code{unspec_volatile} expressions. For example:
11796
11797 @smallexample
11798 (define_c_enum "unspecv" [
11799 UNSPECV_BLOCKAGE
11800 ])
11801 @end smallexample
11802
11803 causes GCC to print @samp{(unspec_volatile @dots{} 0)} as:
11804
11805 @smallexample
11806 (unspec_volatile ... UNSPECV_BLOCKAGE)
11807 @end smallexample
11808
11809 @findex unspec
11810 @item unspec
11811 If an enumeration called @code{unspec} is defined, GCC will use
11812 it when printing out @code{unspec} expressions. GCC will also use
11813 it when printing out @code{unspec_volatile} expressions unless an
11814 @code{unspecv} enumeration is also defined. You can therefore
11815 decide whether to keep separate enumerations for volatile and
11816 non-volatile expressions or whether to use the same enumeration
11817 for both.
11818 @end table
11819
11820 @findex define_enum
11821 @anchor{define_enum}
11822 Another way of defining an enumeration is to use @code{define_enum}:
11823
11824 @smallexample
11825 (define_enum "@var{name}" [
11826 @var{value0}
11827 @var{value1}
11828 @dots{}
11829 @var{valuen}
11830 ])
11831 @end smallexample
11832
11833 This directive implies:
11834
11835 @smallexample
11836 (define_c_enum "@var{name}" [
11837 @var{cname}_@var{cvalue0}
11838 @var{cname}_@var{cvalue1}
11839 @dots{}
11840 @var{cname}_@var{cvaluen}
11841 ])
11842 @end smallexample
11843
11844 @findex define_enum_attr
11845 where @var{cvaluei} is the capitalized form of @var{valuei}.
11846 However, unlike @code{define_c_enum}, the enumerations defined
11847 by @code{define_enum} can be used in attribute specifications
11848 (@pxref{define_enum_attr}).
11849 @end ifset
11850 @ifset INTERNALS
11851 @node Iterators
11852 @section Iterators
11853 @cindex iterators in @file{.md} files
11854
11855 Ports often need to define similar patterns for more than one machine
11856 mode or for more than one rtx code. GCC provides some simple iterator
11857 facilities to make this process easier.
11858
11859 @menu
11860 * Mode Iterators:: Generating variations of patterns for different modes.
11861 * Code Iterators:: Doing the same for codes.
11862 * Int Iterators:: Doing the same for integers.
11863 * Subst Iterators:: Generating variations of patterns for define_subst.
11864 * Parameterized Names:: Specifying iterator values in C++ code.
11865 @end menu
11866
11867 @node Mode Iterators
11868 @subsection Mode Iterators
11869 @cindex mode iterators in @file{.md} files
11870
11871 Ports often need to define similar patterns for two or more different modes.
11872 For example:
11873
11874 @itemize @bullet
11875 @item
11876 If a processor has hardware support for both single and double
11877 floating-point arithmetic, the @code{SFmode} patterns tend to be
11878 very similar to the @code{DFmode} ones.
11879
11880 @item
11881 If a port uses @code{SImode} pointers in one configuration and
11882 @code{DImode} pointers in another, it will usually have very similar
11883 @code{SImode} and @code{DImode} patterns for manipulating pointers.
11884 @end itemize
11885
11886 Mode iterators allow several patterns to be instantiated from one
11887 @file{.md} file template. They can be used with any type of
11888 rtx-based construct, such as a @code{define_insn},
11889 @code{define_split}, or @code{define_peephole2}.
11890
11891 @menu
11892 * Defining Mode Iterators:: Defining a new mode iterator.
11893 * Substitutions:: Combining mode iterators with substitutions
11894 * Examples:: Examples
11895 @end menu
11896
11897 @node Defining Mode Iterators
11898 @subsubsection Defining Mode Iterators
11899 @findex define_mode_iterator
11900
11901 The syntax for defining a mode iterator is:
11902
11903 @smallexample
11904 (define_mode_iterator @var{name} [(@var{mode1} "@var{cond1}") @dots{} (@var{moden} "@var{condn}")])
11905 @end smallexample
11906
11907 This allows subsequent @file{.md} file constructs to use the mode suffix
11908 @code{:@var{name}}. Every construct that does so will be expanded
11909 @var{n} times, once with every use of @code{:@var{name}} replaced by
11910 @code{:@var{mode1}}, once with every use replaced by @code{:@var{mode2}},
11911 and so on. In the expansion for a particular @var{modei}, every
11912 C condition will also require that @var{condi} be true.
11913
11914 For example:
11915
11916 @smallexample
11917 (define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")])
11918 @end smallexample
11919
11920 defines a new mode suffix @code{:P}. Every construct that uses
11921 @code{:P} will be expanded twice, once with every @code{:P} replaced
11922 by @code{:SI} and once with every @code{:P} replaced by @code{:DI}.
11923 The @code{:SI} version will only apply if @code{Pmode == SImode} and
11924 the @code{:DI} version will only apply if @code{Pmode == DImode}.
11925
11926 As with other @file{.md} conditions, an empty string is treated
11927 as ``always true''. @code{(@var{mode} "")} can also be abbreviated
11928 to @code{@var{mode}}. For example:
11929
11930 @smallexample
11931 (define_mode_iterator GPR [SI (DI "TARGET_64BIT")])
11932 @end smallexample
11933
11934 means that the @code{:DI} expansion only applies if @code{TARGET_64BIT}
11935 but that the @code{:SI} expansion has no such constraint.
11936
11937 It is also possible to include iterators in other iterators. For example:
11938
11939 @smallexample
11940 (define_mode_iterator VI [V16QI V8HI V4SI V2DI])
11941 (define_mode_iterator VF [V8HF V4SF (V2DF "TARGET_DOUBLE")])
11942 (define_mode_iterator V [VI (VF "TARGET_FLOAT")])
11943 @end smallexample
11944
11945 makes @samp{:V} iterate over the modes in @code{VI} and the modes
11946 in @code{VF}. When a construct uses @samp{:V}, the @code{V8HF} and
11947 @code{V4SF} expansions require @samp{TARGET_FLOAT} while the @code{V2DF}
11948 expansion requires @samp{TARGET_DOUBLE && TARGET_FLOAT}.
11949
11950 Iterators are applied in the order they are defined. This can be
11951 significant if two iterators are used in a construct that requires
11952 substitutions. @xref{Substitutions}.
11953
11954 @node Substitutions
11955 @subsubsection Substitution in Mode Iterators
11956 @findex define_mode_attr
11957
11958 If an @file{.md} file construct uses mode iterators, each version of the
11959 construct will often need slightly different strings or modes. For
11960 example:
11961
11962 @itemize @bullet
11963 @item
11964 When a @code{define_expand} defines several @code{add@var{m}3} patterns
11965 (@pxref{Standard Names}), each expander will need to use the
11966 appropriate mode name for @var{m}.
11967
11968 @item
11969 When a @code{define_insn} defines several instruction patterns,
11970 each instruction will often use a different assembler mnemonic.
11971
11972 @item
11973 When a @code{define_insn} requires operands with different modes,
11974 using an iterator for one of the operand modes usually requires a specific
11975 mode for the other operand(s).
11976 @end itemize
11977
11978 GCC supports such variations through a system of ``mode attributes''.
11979 There are two standard attributes: @code{mode}, which is the name of
11980 the mode in lower case, and @code{MODE}, which is the same thing in
11981 upper case. You can define other attributes using:
11982
11983 @smallexample
11984 (define_mode_attr @var{name} [(@var{mode1} "@var{value1}") @dots{} (@var{moden} "@var{valuen}")])
11985 @end smallexample
11986
11987 where @var{name} is the name of the attribute and @var{valuei}
11988 is the value associated with @var{modei}.
11989
11990 When GCC replaces some @var{:iterator} with @var{:mode}, it will scan
11991 each string and mode in the pattern for sequences of the form
11992 @code{<@var{iterator}:@var{attr}>}, where @var{attr} is the name of a
11993 mode attribute. If the attribute is defined for @var{mode}, the whole
11994 @code{<@dots{}>} sequence will be replaced by the appropriate attribute
11995 value.
11996
11997 For example, suppose an @file{.md} file has:
11998
11999 @smallexample
12000 (define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")])
12001 (define_mode_attr load [(SI "lw") (DI "ld")])
12002 @end smallexample
12003
12004 If one of the patterns that uses @code{:P} contains the string
12005 @code{"<P:load>\t%0,%1"}, the @code{SI} version of that pattern
12006 will use @code{"lw\t%0,%1"} and the @code{DI} version will use
12007 @code{"ld\t%0,%1"}.
12008
12009 Here is an example of using an attribute for a mode:
12010
12011 @smallexample
12012 (define_mode_iterator LONG [SI DI])
12013 (define_mode_attr SHORT [(SI "HI") (DI "SI")])
12014 (define_insn @dots{}
12015 (sign_extend:LONG (match_operand:<LONG:SHORT> @dots{})) @dots{})
12016 @end smallexample
12017
12018 The @code{@var{iterator}:} prefix may be omitted, in which case the
12019 substitution will be attempted for every iterator expansion.
12020
12021 @node Examples
12022 @subsubsection Mode Iterator Examples
12023
12024 Here is an example from the MIPS port. It defines the following
12025 modes and attributes (among others):
12026
12027 @smallexample
12028 (define_mode_iterator GPR [SI (DI "TARGET_64BIT")])
12029 (define_mode_attr d [(SI "") (DI "d")])
12030 @end smallexample
12031
12032 and uses the following template to define both @code{subsi3}
12033 and @code{subdi3}:
12034
12035 @smallexample
12036 (define_insn "sub<mode>3"
12037 [(set (match_operand:GPR 0 "register_operand" "=d")
12038 (minus:GPR (match_operand:GPR 1 "register_operand" "d")
12039 (match_operand:GPR 2 "register_operand" "d")))]
12040 ""
12041 "<d>subu\t%0,%1,%2"
12042 [(set_attr "type" "arith")
12043 (set_attr "mode" "<MODE>")])
12044 @end smallexample
12045
12046 This is exactly equivalent to:
12047
12048 @smallexample
12049 (define_insn "subsi3"
12050 [(set (match_operand:SI 0 "register_operand" "=d")
12051 (minus:SI (match_operand:SI 1 "register_operand" "d")
12052 (match_operand:SI 2 "register_operand" "d")))]
12053 ""
12054 "subu\t%0,%1,%2"
12055 [(set_attr "type" "arith")
12056 (set_attr "mode" "SI")])
12057
12058 (define_insn "subdi3"
12059 [(set (match_operand:DI 0 "register_operand" "=d")
12060 (minus:DI (match_operand:DI 1 "register_operand" "d")
12061 (match_operand:DI 2 "register_operand" "d")))]
12062 "TARGET_64BIT"
12063 "dsubu\t%0,%1,%2"
12064 [(set_attr "type" "arith")
12065 (set_attr "mode" "DI")])
12066 @end smallexample
12067
12068 @node Code Iterators
12069 @subsection Code Iterators
12070 @cindex code iterators in @file{.md} files
12071 @findex define_code_iterator
12072 @findex define_code_attr
12073
12074 Code iterators operate in a similar way to mode iterators. @xref{Mode Iterators}.
12075
12076 The construct:
12077
12078 @smallexample
12079 (define_code_iterator @var{name} [(@var{code1} "@var{cond1}") @dots{} (@var{coden} "@var{condn}")])
12080 @end smallexample
12081
12082 defines a pseudo rtx code @var{name} that can be instantiated as
12083 @var{codei} if condition @var{condi} is true. Each @var{codei}
12084 must have the same rtx format. @xref{RTL Classes}.
12085
12086 As with mode iterators, each pattern that uses @var{name} will be
12087 expanded @var{n} times, once with all uses of @var{name} replaced by
12088 @var{code1}, once with all uses replaced by @var{code2}, and so on.
12089 @xref{Defining Mode Iterators}.
12090
12091 It is possible to define attributes for codes as well as for modes.
12092 There are two standard code attributes: @code{code}, the name of the
12093 code in lower case, and @code{CODE}, the name of the code in upper case.
12094 Other attributes are defined using:
12095
12096 @smallexample
12097 (define_code_attr @var{name} [(@var{code1} "@var{value1}") @dots{} (@var{coden} "@var{valuen}")])
12098 @end smallexample
12099
12100 Instruction patterns can use code attributes as rtx codes, which can be
12101 useful if two sets of codes act in tandem. For example, the following
12102 @code{define_insn} defines two patterns, one calculating a signed absolute
12103 difference and another calculating an unsigned absolute difference:
12104
12105 @smallexample
12106 (define_code_iterator any_max [smax umax])
12107 (define_code_attr paired_min [(smax "smin") (umax "umin")])
12108 (define_insn @dots{}
12109 [(set (match_operand:SI 0 @dots{})
12110 (minus:SI (any_max:SI (match_operand:SI 1 @dots{})
12111 (match_operand:SI 2 @dots{}))
12112 (<paired_min>:SI (match_dup 1) (match_dup 2))))]
12113 @dots{})
12114 @end smallexample
12115
12116 The signed version of the instruction uses @code{smax} and @code{smin}
12117 while the unsigned version uses @code{umax} and @code{umin}. There
12118 are no versions that pair @code{smax} with @code{umin} or @code{umax}
12119 with @code{smin}.
12120
12121 It is also possible to use other types of attributes as codes,
12122 in a similar way. For example, an int iterator could be used to
12123 iterate over @code{unspec} numbers, with an int attribute specifying
12124 an associated rtx code. @xref{Int Iterators}.
12125
12126 Here's an example of code iterators in action, taken from the MIPS port:
12127
12128 @smallexample
12129 (define_code_iterator any_cond [unordered ordered unlt unge uneq ltgt unle ungt
12130 eq ne gt ge lt le gtu geu ltu leu])
12131
12132 (define_expand "b<code>"
12133 [(set (pc)
12134 (if_then_else (any_cond:CC (cc0)
12135 (const_int 0))
12136 (label_ref (match_operand 0 ""))
12137 (pc)))]
12138 ""
12139 @{
12140 gen_conditional_branch (operands, <CODE>);
12141 DONE;
12142 @})
12143 @end smallexample
12144
12145 This is equivalent to:
12146
12147 @smallexample
12148 (define_expand "bunordered"
12149 [(set (pc)
12150 (if_then_else (unordered:CC (cc0)
12151 (const_int 0))
12152 (label_ref (match_operand 0 ""))
12153 (pc)))]
12154 ""
12155 @{
12156 gen_conditional_branch (operands, UNORDERED);
12157 DONE;
12158 @})
12159
12160 (define_expand "bordered"
12161 [(set (pc)
12162 (if_then_else (ordered:CC (cc0)
12163 (const_int 0))
12164 (label_ref (match_operand 0 ""))
12165 (pc)))]
12166 ""
12167 @{
12168 gen_conditional_branch (operands, ORDERED);
12169 DONE;
12170 @})
12171
12172 @dots{}
12173 @end smallexample
12174
12175 @node Int Iterators
12176 @subsection Int Iterators
12177 @cindex int iterators in @file{.md} files
12178 @findex define_int_iterator
12179 @findex define_int_attr
12180
12181 Int iterators operate in a similar way to code iterators. @xref{Code Iterators}.
12182
12183 The construct:
12184
12185 @smallexample
12186 (define_int_iterator @var{name} [(@var{int1} "@var{cond1}") @dots{} (@var{intn} "@var{condn}")])
12187 @end smallexample
12188
12189 defines a pseudo integer constant @var{name} that can be instantiated as
12190 @var{inti} if condition @var{condi} is true. Int iterators can appear in
12191 only those rtx fields that have `i', `n', `w', or `p' as the specifier.
12192 This means that each @var{int} has to be a constant defined using
12193 @samp{define_constant} or @samp{define_c_enum}.
12194
12195 As with mode and code iterators, each pattern that uses @var{name} will be
12196 expanded @var{n} times, once with all uses of @var{name} replaced by
12197 @var{int1}, once with all uses replaced by @var{int2}, and so on.
12198 @xref{Defining Mode Iterators}.
12199
12200 It is possible to define attributes for ints as well as for codes and modes.
12201 Attributes are defined using:
12202
12203 @smallexample
12204 (define_int_attr @var{attr_name} [(@var{int1} "@var{value1}") @dots{} (@var{intn} "@var{valuen}")])
12205 @end smallexample
12206
12207 In additon to these user-defined attributes, it is possible to use
12208 @samp{<@var{name}>} to refer to the current expansion of iterator
12209 @var{name} (such as @var{int1}, @var{int2}, and so on).
12210
12211 Here's an example of int iterators in action, taken from the ARM port:
12212
12213 @smallexample
12214 (define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG])
12215
12216 (define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")])
12217
12218 (define_insn "neon_vq<absneg><mode>"
12219 [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
12220 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
12221 (match_operand:SI 2 "immediate_operand" "i")]
12222 QABSNEG))]
12223 "TARGET_NEON"
12224 "vq<absneg>.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
12225 [(set_attr "type" "neon_vqneg_vqabs")]
12226 )
12227
12228 @end smallexample
12229
12230 This is equivalent to:
12231
12232 @smallexample
12233 (define_insn "neon_vqabs<mode>"
12234 [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
12235 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
12236 (match_operand:SI 2 "immediate_operand" "i")]
12237 UNSPEC_VQABS))]
12238 "TARGET_NEON"
12239 "vqabs.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
12240 [(set_attr "type" "neon_vqneg_vqabs")]
12241 )
12242
12243 (define_insn "neon_vqneg<mode>"
12244 [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
12245 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
12246 (match_operand:SI 2 "immediate_operand" "i")]
12247 UNSPEC_VQNEG))]
12248 "TARGET_NEON"
12249 "vqneg.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
12250 [(set_attr "type" "neon_vqneg_vqabs")]
12251 )
12252
12253 @end smallexample
12254
12255 @node Subst Iterators
12256 @subsection Subst Iterators
12257 @cindex subst iterators in @file{.md} files
12258 @findex define_subst
12259 @findex define_subst_attr
12260
12261 Subst iterators are special type of iterators with the following
12262 restrictions: they could not be declared explicitly, they always have
12263 only two values, and they do not have explicit dedicated name.
12264 Subst-iterators are triggered only when corresponding subst-attribute is
12265 used in RTL-pattern.
12266
12267 Subst iterators transform templates in the following way: the templates
12268 are duplicated, the subst-attributes in these templates are replaced
12269 with the corresponding values, and a new attribute is implicitly added
12270 to the given @code{define_insn}/@code{define_expand}. The name of the
12271 added attribute matches the name of @code{define_subst}. Such
12272 attributes are declared implicitly, and it is not allowed to have a
12273 @code{define_attr} named as a @code{define_subst}.
12274
12275 Each subst iterator is linked to a @code{define_subst}. It is declared
12276 implicitly by the first appearance of the corresponding
12277 @code{define_subst_attr}, and it is not allowed to define it explicitly.
12278
12279 Declarations of subst-attributes have the following syntax:
12280
12281 @findex define_subst_attr
12282 @smallexample
12283 (define_subst_attr "@var{name}"
12284 "@var{subst-name}"
12285 "@var{no-subst-value}"
12286 "@var{subst-applied-value}")
12287 @end smallexample
12288
12289 @var{name} is a string with which the given subst-attribute could be
12290 referred to.
12291
12292 @var{subst-name} shows which @code{define_subst} should be applied to an
12293 RTL-template if the given subst-attribute is present in the
12294 RTL-template.
12295
12296 @var{no-subst-value} is a value with which subst-attribute would be
12297 replaced in the first copy of the original RTL-template.
12298
12299 @var{subst-applied-value} is a value with which subst-attribute would be
12300 replaced in the second copy of the original RTL-template.
12301
12302 @node Parameterized Names
12303 @subsection Parameterized Names
12304 @cindex @samp{@@} in instruction pattern names
12305 Ports sometimes need to apply iterators using C++ code, in order to
12306 get the code or RTL pattern for a specific instruction. For example,
12307 suppose we have the @samp{neon_vq<absneg><mode>} pattern given above:
12308
12309 @smallexample
12310 (define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG])
12311
12312 (define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")])
12313
12314 (define_insn "neon_vq<absneg><mode>"
12315 [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
12316 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
12317 (match_operand:SI 2 "immediate_operand" "i")]
12318 QABSNEG))]
12319 @dots{}
12320 )
12321 @end smallexample
12322
12323 A port might need to generate this pattern for a variable
12324 @samp{QABSNEG} value and a variable @samp{VDQIW} mode. There are two
12325 ways of doing this. The first is to build the rtx for the pattern
12326 directly from C++ code; this is a valid technique and avoids any risk
12327 of combinatorial explosion. The second is to prefix the instruction
12328 name with the special character @samp{@@}, which tells GCC to generate
12329 the four additional functions below. In each case, @var{name} is the
12330 name of the instruction without the leading @samp{@@} character,
12331 without the @samp{<@dots{}>} placeholders, and with any underscore
12332 before a @samp{<@dots{}>} placeholder removed if keeping it would
12333 lead to a double or trailing underscore.
12334
12335 @table @samp
12336 @item insn_code maybe_code_for_@var{name} (@var{i1}, @var{i2}, @dots{})
12337 See whether replacing the first @samp{<@dots{}>} placeholder with
12338 iterator value @var{i1}, the second with iterator value @var{i2}, and
12339 so on, gives a valid instruction. Return its code if so, otherwise
12340 return @code{CODE_FOR_nothing}.
12341
12342 @item insn_code code_for_@var{name} (@var{i1}, @var{i2}, @dots{})
12343 Same, but abort the compiler if the requested instruction does not exist.
12344
12345 @item rtx maybe_gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{})
12346 Check for a valid instruction in the same way as
12347 @code{maybe_code_for_@var{name}}. If the instruction exists,
12348 generate an instance of it using the operand values given by @var{op0},
12349 @var{op1}, and so on, otherwise return null.
12350
12351 @item rtx gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{})
12352 Same, but abort the compiler if the requested instruction does not exist,
12353 or if the instruction generator invoked the @code{FAIL} macro.
12354 @end table
12355
12356 For example, changing the pattern above to:
12357
12358 @smallexample
12359 (define_insn "@@neon_vq<absneg><mode>"
12360 [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
12361 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
12362 (match_operand:SI 2 "immediate_operand" "i")]
12363 QABSNEG))]
12364 @dots{}
12365 )
12366 @end smallexample
12367
12368 would define the same patterns as before, but in addition would generate
12369 the four functions below:
12370
12371 @smallexample
12372 insn_code maybe_code_for_neon_vq (int, machine_mode);
12373 insn_code code_for_neon_vq (int, machine_mode);
12374 rtx maybe_gen_neon_vq (int, machine_mode, rtx, rtx, rtx);
12375 rtx gen_neon_vq (int, machine_mode, rtx, rtx, rtx);
12376 @end smallexample
12377
12378 Calling @samp{code_for_neon_vq (UNSPEC_VQABS, V8QImode)}
12379 would then give @code{CODE_FOR_neon_vqabsv8qi}.
12380
12381 It is possible to have multiple @samp{@@} patterns with the same
12382 name and same types of iterator. For example:
12383
12384 @smallexample
12385 (define_insn "@@some_arithmetic_op<mode>"
12386 [(set (match_operand:INTEGER_MODES 0 "register_operand") @dots{})]
12387 @dots{}
12388 )
12389
12390 (define_insn "@@some_arithmetic_op<mode>"
12391 [(set (match_operand:FLOAT_MODES 0 "register_operand") @dots{})]
12392 @dots{}
12393 )
12394 @end smallexample
12395
12396 would produce a single set of functions that handles both
12397 @code{INTEGER_MODES} and @code{FLOAT_MODES}.
12398
12399 It is also possible for these @samp{@@} patterns to have different
12400 numbers of operands from each other. For example, patterns with
12401 a binary rtl code might take three operands (one output and two inputs)
12402 while patterns with a ternary rtl code might take four operands (one
12403 output and three inputs). This combination would produce separate
12404 @samp{maybe_gen_@var{name}} and @samp{gen_@var{name}} functions for
12405 each operand count, but it would still produce a single
12406 @samp{maybe_code_for_@var{name}} and a single @samp{code_for_@var{name}}.
12407
12408 Currently, these @code{@@} patterns only take into account patterns for
12409 which no @code{define_subst} has been applied (@pxref{Define Subst}).
12410 Any @samp{<@dots{}>} placeholders that refer to subst attributes
12411 (@pxref{Subst Iterators}) are ignored.
12412
12413 @end ifset