OSDN Git Service

cf690ec3fcdebfe72eae2f64d1ab0a7ef0df75a6
[pf3gnuchains/gcc-fork.git] / gcc / doc / md.texi
1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001,
2 @c 2002, 2003, 2004 Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
5
6 @ifset INTERNALS
7 @node Machine Desc
8 @chapter Machine Descriptions
9 @cindex machine descriptions
10
11 A machine description has two parts: a file of instruction patterns
12 (@file{.md} file) and a C header file of macro definitions.
13
14 The @file{.md} file for a target machine contains a pattern for each
15 instruction that the target machine supports (or at least each instruction
16 that is worth telling the compiler about).  It may also contain comments.
17 A semicolon causes the rest of the line to be a comment, unless the semicolon
18 is inside a quoted string.
19
20 See the next chapter for information on the C header file.
21
22 @menu
23 * Overview::            How the machine description is used.
24 * Patterns::            How to write instruction patterns.
25 * Example::             An explained example of a @code{define_insn} pattern.
26 * RTL Template::        The RTL template defines what insns match a pattern.
27 * Output Template::     The output template says how to make assembler code
28                           from such an insn.
29 * Output Statement::    For more generality, write C code to output
30                           the assembler code.
31 * Constraints::         When not all operands are general operands.
32 * Standard Names::      Names mark patterns to use for code generation.
33 * Pattern Ordering::    When the order of patterns makes a difference.
34 * Dependent Patterns::  Having one pattern may make you need another.
35 * Jump Patterns::       Special considerations for patterns for jump insns.
36 * Looping Patterns::    How to define patterns for special looping insns.
37 * Insn Canonicalizations::Canonicalization of Instructions
38 * Expander Definitions::Generating a sequence of several RTL insns
39                           for a standard operation.
40 * Insn Splitting::      Splitting Instructions into Multiple Instructions.
41 * Including Patterns::      Including Patterns in Machine Descriptions.
42 * Peephole Definitions::Defining machine-specific peephole optimizations.
43 * Insn Attributes::     Specifying the value of attributes for generated insns.
44 * Conditional Execution::Generating @code{define_insn} patterns for
45                            predication.
46 * Constant Definitions::Defining symbolic constants that can be used in the
47                         md file.
48 @end menu
49
50 @node Overview
51 @section Overview of How the Machine Description is Used
52
53 There are three main conversions that happen in the compiler:
54
55 @enumerate
56
57 @item
58 The front end reads the source code and builds a parse tree.
59
60 @item
61 The parse tree is used to generate an RTL insn list based on named
62 instruction patterns.
63
64 @item
65 The insn list is matched against the RTL templates to produce assembler
66 code.
67
68 @end enumerate
69
70 For the generate pass, only the names of the insns matter, from either a
71 named @code{define_insn} or a @code{define_expand}.  The compiler will
72 choose the pattern with the right name and apply the operands according
73 to the documentation later in this chapter, without regard for the RTL
74 template or operand constraints.  Note that the names the compiler looks
75 for are hard-coded in the compiler---it will ignore unnamed patterns and
76 patterns with names it doesn't know about, but if you don't provide a
77 named pattern it needs, it will abort.
78
79 If a @code{define_insn} is used, the template given is inserted into the
80 insn list.  If a @code{define_expand} is used, one of three things
81 happens, based on the condition logic.  The condition logic may manually
82 create new insns for the insn list, say via @code{emit_insn()}, and
83 invoke @code{DONE}.  For certain named patterns, it may invoke @code{FAIL} to tell the
84 compiler to use an alternate way of performing that task.  If it invokes
85 neither @code{DONE} nor @code{FAIL}, the template given in the pattern
86 is inserted, as if the @code{define_expand} were a @code{define_insn}.
87
88 Once the insn list is generated, various optimization passes convert,
89 replace, and rearrange the insns in the insn list.  This is where the
90 @code{define_split} and @code{define_peephole} patterns get used, for
91 example.
92
93 Finally, the insn list's RTL is matched up with the RTL templates in the
94 @code{define_insn} patterns, and those patterns are used to emit the
95 final assembly code.  For this purpose, each named @code{define_insn}
96 acts like it's unnamed, since the names are ignored.
97
98 @node Patterns
99 @section Everything about Instruction Patterns
100 @cindex patterns
101 @cindex instruction patterns
102
103 @findex define_insn
104 Each instruction pattern contains an incomplete RTL expression, with pieces
105 to be filled in later, operand constraints that restrict how the pieces can
106 be filled in, and an output pattern or C code to generate the assembler
107 output, all wrapped up in a @code{define_insn} expression.
108
109 A @code{define_insn} is an RTL expression containing four or five operands:
110
111 @enumerate
112 @item
113 An optional name.  The presence of a name indicate that this instruction
114 pattern can perform a certain standard job for the RTL-generation
115 pass of the compiler.  This pass knows certain names and will use
116 the instruction patterns with those names, if the names are defined
117 in the machine description.
118
119 The absence of a name is indicated by writing an empty string
120 where the name should go.  Nameless instruction patterns are never
121 used for generating RTL code, but they may permit several simpler insns
122 to be combined later on.
123
124 Names that are not thus known and used in RTL-generation have no
125 effect; they are equivalent to no name at all.
126
127 For the purpose of debugging the compiler, you may also specify a
128 name beginning with the @samp{*} character.  Such a name is used only
129 for identifying the instruction in RTL dumps; it is entirely equivalent
130 to having a nameless pattern for all other purposes.
131
132 @item
133 The @dfn{RTL template} (@pxref{RTL Template}) is a vector of incomplete
134 RTL expressions which show what the instruction should look like.  It is
135 incomplete because it may contain @code{match_operand},
136 @code{match_operator}, and @code{match_dup} expressions that stand for
137 operands of the instruction.
138
139 If the vector has only one element, that element is the template for the
140 instruction pattern.  If the vector has multiple elements, then the
141 instruction pattern is a @code{parallel} expression containing the
142 elements described.
143
144 @item
145 @cindex pattern conditions
146 @cindex conditions, in patterns
147 A condition.  This is a string which contains a C expression that is
148 the final test to decide whether an insn body matches this pattern.
149
150 @cindex named patterns and conditions
151 For a named pattern, the condition (if present) may not depend on
152 the data in the insn being matched, but only the target-machine-type
153 flags.  The compiler needs to test these conditions during
154 initialization in order to learn exactly which named instructions are
155 available in a particular run.
156
157 @findex operands
158 For nameless patterns, the condition is applied only when matching an
159 individual insn, and only after the insn has matched the pattern's
160 recognition template.  The insn's operands may be found in the vector
161 @code{operands}.  For an insn where the condition has once matched, it
162 can't be used to control register allocation, for example by excluding
163 certain hard registers or hard register combinations.
164
165 @item
166 The @dfn{output template}: a string that says how to output matching
167 insns as assembler code.  @samp{%} in this string specifies where
168 to substitute the value of an operand.  @xref{Output Template}.
169
170 When simple substitution isn't general enough, you can specify a piece
171 of C code to compute the output.  @xref{Output Statement}.
172
173 @item
174 Optionally, a vector containing the values of attributes for insns matching
175 this pattern.  @xref{Insn Attributes}.
176 @end enumerate
177
178 @node Example
179 @section Example of @code{define_insn}
180 @cindex @code{define_insn} example
181
182 Here is an actual example of an instruction pattern, for the 68000/68020.
183
184 @smallexample
185 (define_insn "tstsi"
186   [(set (cc0)
187         (match_operand:SI 0 "general_operand" "rm"))]
188   ""
189   "*
190 @{
191   if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
192     return \"tstl %0\";
193   return \"cmpl #0,%0\";
194 @}")
195 @end smallexample
196
197 @noindent
198 This can also be written using braced strings:
199
200 @smallexample
201 (define_insn "tstsi"
202   [(set (cc0)
203         (match_operand:SI 0 "general_operand" "rm"))]
204   ""
205 @{
206   if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
207     return "tstl %0";
208   return "cmpl #0,%0";
209 @})
210 @end smallexample
211
212 This is an instruction that sets the condition codes based on the value of
213 a general operand.  It has no condition, so any insn whose RTL description
214 has the form shown may be handled according to this pattern.  The name
215 @samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation
216 pass that, when it is necessary to test such a value, an insn to do so
217 can be constructed using this pattern.
218
219 The output control string is a piece of C code which chooses which
220 output template to return based on the kind of operand and the specific
221 type of CPU for which code is being generated.
222
223 @samp{"rm"} is an operand constraint.  Its meaning is explained below.
224
225 @node RTL Template
226 @section RTL Template
227 @cindex RTL insn template
228 @cindex generating insns
229 @cindex insns, generating
230 @cindex recognizing insns
231 @cindex insns, recognizing
232
233 The RTL template is used to define which insns match the particular pattern
234 and how to find their operands.  For named patterns, the RTL template also
235 says how to construct an insn from specified operands.
236
237 Construction involves substituting specified operands into a copy of the
238 template.  Matching involves determining the values that serve as the
239 operands in the insn being matched.  Both of these activities are
240 controlled by special expression types that direct matching and
241 substitution of the operands.
242
243 @table @code
244 @findex match_operand
245 @item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint})
246 This expression is a placeholder for operand number @var{n} of
247 the insn.  When constructing an insn, operand number @var{n}
248 will be substituted at this point.  When matching an insn, whatever
249 appears at this position in the insn will be taken as operand
250 number @var{n}; but it must satisfy @var{predicate} or this instruction
251 pattern will not match at all.
252
253 Operand numbers must be chosen consecutively counting from zero in
254 each instruction pattern.  There may be only one @code{match_operand}
255 expression in the pattern for each operand number.  Usually operands
256 are numbered in the order of appearance in @code{match_operand}
257 expressions.  In the case of a @code{define_expand}, any operand numbers
258 used only in @code{match_dup} expressions have higher values than all
259 other operand numbers.
260
261 @var{predicate} is a string that is the name of a C function that accepts two
262 arguments, an expression and a machine mode.  During matching, the
263 function will be called with the putative operand as the expression and
264 @var{m} as the mode argument (if @var{m} is not specified,
265 @code{VOIDmode} will be used, which normally causes @var{predicate} to accept
266 any mode).  If it returns zero, this instruction pattern fails to match.
267 @var{predicate} may be an empty string; then it means no test is to be done
268 on the operand, so anything which occurs in this position is valid.
269
270 Most of the time, @var{predicate} will reject modes other than @var{m}---but
271 not always.  For example, the predicate @code{address_operand} uses
272 @var{m} as the mode of memory ref that the address should be valid for.
273 Many predicates accept @code{const_int} nodes even though their mode is
274 @code{VOIDmode}.
275
276 @var{constraint} controls reloading and the choice of the best register
277 class to use for a value, as explained later (@pxref{Constraints}).
278
279 People are often unclear on the difference between the constraint and the
280 predicate.  The predicate helps decide whether a given insn matches the
281 pattern.  The constraint plays no role in this decision; instead, it
282 controls various decisions in the case of an insn which does match.
283
284 @findex general_operand
285 On CISC machines, the most common @var{predicate} is
286 @code{"general_operand"}.  This function checks that the putative
287 operand is either a constant, a register or a memory reference, and that
288 it is valid for mode @var{m}.
289
290 @findex register_operand
291 For an operand that must be a register, @var{predicate} should be
292 @code{"register_operand"}.  Using @code{"general_operand"} would be
293 valid, since the reload pass would copy any non-register operands
294 through registers, but this would make GCC do extra work, it would
295 prevent invariant operands (such as constant) from being removed from
296 loops, and it would prevent the register allocator from doing the best
297 possible job.  On RISC machines, it is usually most efficient to allow
298 @var{predicate} to accept only objects that the constraints allow.
299
300 @findex immediate_operand
301 For an operand that must be a constant, you must be sure to either use
302 @code{"immediate_operand"} for @var{predicate}, or make the instruction
303 pattern's extra condition require a constant, or both.  You cannot
304 expect the constraints to do this work!  If the constraints allow only
305 constants, but the predicate allows something else, the compiler will
306 crash when that case arises.
307
308 @findex match_scratch
309 @item (match_scratch:@var{m} @var{n} @var{constraint})
310 This expression is also a placeholder for operand number @var{n}
311 and indicates that operand must be a @code{scratch} or @code{reg}
312 expression.
313
314 When matching patterns, this is equivalent to
315
316 @smallexample
317 (match_operand:@var{m} @var{n} "scratch_operand" @var{pred})
318 @end smallexample
319
320 but, when generating RTL, it produces a (@code{scratch}:@var{m})
321 expression.
322
323 If the last few expressions in a @code{parallel} are @code{clobber}
324 expressions whose operands are either a hard register or
325 @code{match_scratch}, the combiner can add or delete them when
326 necessary.  @xref{Side Effects}.
327
328 @findex match_dup
329 @item (match_dup @var{n})
330 This expression is also a placeholder for operand number @var{n}.
331 It is used when the operand needs to appear more than once in the
332 insn.
333
334 In construction, @code{match_dup} acts just like @code{match_operand}:
335 the operand is substituted into the insn being constructed.  But in
336 matching, @code{match_dup} behaves differently.  It assumes that operand
337 number @var{n} has already been determined by a @code{match_operand}
338 appearing earlier in the recognition template, and it matches only an
339 identical-looking expression.
340
341 Note that @code{match_dup} should not be used to tell the compiler that
342 a particular register is being used for two operands (example:
343 @code{add} that adds one register to another; the second register is
344 both an input operand and the output operand).  Use a matching
345 constraint (@pxref{Simple Constraints}) for those.  @code{match_dup} is for the cases where one
346 operand is used in two places in the template, such as an instruction
347 that computes both a quotient and a remainder, where the opcode takes
348 two input operands but the RTL template has to refer to each of those
349 twice; once for the quotient pattern and once for the remainder pattern.
350
351 @findex match_operator
352 @item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}])
353 This pattern is a kind of placeholder for a variable RTL expression
354 code.
355
356 When constructing an insn, it stands for an RTL expression whose
357 expression code is taken from that of operand @var{n}, and whose
358 operands are constructed from the patterns @var{operands}.
359
360 When matching an expression, it matches an expression if the function
361 @var{predicate} returns nonzero on that expression @emph{and} the
362 patterns @var{operands} match the operands of the expression.
363
364 Suppose that the function @code{commutative_operator} is defined as
365 follows, to match any expression whose operator is one of the
366 commutative arithmetic operators of RTL and whose mode is @var{mode}:
367
368 @smallexample
369 int
370 commutative_operator (x, mode)
371      rtx x;
372      enum machine_mode mode;
373 @{
374   enum rtx_code code = GET_CODE (x);
375   if (GET_MODE (x) != mode)
376     return 0;
377   return (GET_RTX_CLASS (code) == 'c'
378           || code == EQ || code == NE);
379 @}
380 @end smallexample
381
382 Then the following pattern will match any RTL expression consisting
383 of a commutative operator applied to two general operands:
384
385 @smallexample
386 (match_operator:SI 3 "commutative_operator"
387   [(match_operand:SI 1 "general_operand" "g")
388    (match_operand:SI 2 "general_operand" "g")])
389 @end smallexample
390
391 Here the vector @code{[@var{operands}@dots{}]} contains two patterns
392 because the expressions to be matched all contain two operands.
393
394 When this pattern does match, the two operands of the commutative
395 operator are recorded as operands 1 and 2 of the insn.  (This is done
396 by the two instances of @code{match_operand}.)  Operand 3 of the insn
397 will be the entire commutative expression: use @code{GET_CODE
398 (operands[3])} to see which commutative operator was used.
399
400 The machine mode @var{m} of @code{match_operator} works like that of
401 @code{match_operand}: it is passed as the second argument to the
402 predicate function, and that function is solely responsible for
403 deciding whether the expression to be matched ``has'' that mode.
404
405 When constructing an insn, argument 3 of the gen-function will specify
406 the operation (i.e.@: the expression code) for the expression to be
407 made.  It should be an RTL expression, whose expression code is copied
408 into a new expression whose operands are arguments 1 and 2 of the
409 gen-function.  The subexpressions of argument 3 are not used;
410 only its expression code matters.
411
412 When @code{match_operator} is used in a pattern for matching an insn,
413 it usually best if the operand number of the @code{match_operator}
414 is higher than that of the actual operands of the insn.  This improves
415 register allocation because the register allocator often looks at
416 operands 1 and 2 of insns to see if it can do register tying.
417
418 There is no way to specify constraints in @code{match_operator}.  The
419 operand of the insn which corresponds to the @code{match_operator}
420 never has any constraints because it is never reloaded as a whole.
421 However, if parts of its @var{operands} are matched by
422 @code{match_operand} patterns, those parts may have constraints of
423 their own.
424
425 @findex match_op_dup
426 @item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}])
427 Like @code{match_dup}, except that it applies to operators instead of
428 operands.  When constructing an insn, operand number @var{n} will be
429 substituted at this point.  But in matching, @code{match_op_dup} behaves
430 differently.  It assumes that operand number @var{n} has already been
431 determined by a @code{match_operator} appearing earlier in the
432 recognition template, and it matches only an identical-looking
433 expression.
434
435 @findex match_parallel
436 @item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}])
437 This pattern is a placeholder for an insn that consists of a
438 @code{parallel} expression with a variable number of elements.  This
439 expression should only appear at the top level of an insn pattern.
440
441 When constructing an insn, operand number @var{n} will be substituted at
442 this point.  When matching an insn, it matches if the body of the insn
443 is a @code{parallel} expression with at least as many elements as the
444 vector of @var{subpat} expressions in the @code{match_parallel}, if each
445 @var{subpat} matches the corresponding element of the @code{parallel},
446 @emph{and} the function @var{predicate} returns nonzero on the
447 @code{parallel} that is the body of the insn.  It is the responsibility
448 of the predicate to validate elements of the @code{parallel} beyond
449 those listed in the @code{match_parallel}.
450
451 A typical use of @code{match_parallel} is to match load and store
452 multiple expressions, which can contain a variable number of elements
453 in a @code{parallel}.  For example,
454
455 @smallexample
456 (define_insn ""
457   [(match_parallel 0 "load_multiple_operation"
458      [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
459            (match_operand:SI 2 "memory_operand" "m"))
460       (use (reg:SI 179))
461       (clobber (reg:SI 179))])]
462   ""
463   "loadm 0,0,%1,%2")
464 @end smallexample
465
466 This example comes from @file{a29k.md}.  The function
467 @code{load_multiple_operation} is defined in @file{a29k.c} and checks
468 that subsequent elements in the @code{parallel} are the same as the
469 @code{set} in the pattern, except that they are referencing subsequent
470 registers and memory locations.
471
472 An insn that matches this pattern might look like:
473
474 @smallexample
475 (parallel
476  [(set (reg:SI 20) (mem:SI (reg:SI 100)))
477   (use (reg:SI 179))
478   (clobber (reg:SI 179))
479   (set (reg:SI 21)
480        (mem:SI (plus:SI (reg:SI 100)
481                         (const_int 4))))
482   (set (reg:SI 22)
483        (mem:SI (plus:SI (reg:SI 100)
484                         (const_int 8))))])
485 @end smallexample
486
487 @findex match_par_dup
488 @item (match_par_dup @var{n} [@var{subpat}@dots{}])
489 Like @code{match_op_dup}, but for @code{match_parallel} instead of
490 @code{match_operator}.
491
492 @findex match_insn
493 @item (match_insn @var{predicate})
494 Match a complete insn.  Unlike the other @code{match_*} recognizers,
495 @code{match_insn} does not take an operand number.
496
497 The machine mode @var{m} of @code{match_insn} works like that of
498 @code{match_operand}: it is passed as the second argument to the
499 predicate function, and that function is solely responsible for
500 deciding whether the expression to be matched ``has'' that mode.
501
502 @findex match_insn2
503 @item (match_insn2 @var{n} @var{predicate})
504 Match a complete insn.
505
506 The machine mode @var{m} of @code{match_insn2} works like that of
507 @code{match_operand}: it is passed as the second argument to the
508 predicate function, and that function is solely responsible for
509 deciding whether the expression to be matched ``has'' that mode.
510
511 @end table
512
513 @node Output Template
514 @section Output Templates and Operand Substitution
515 @cindex output templates
516 @cindex operand substitution
517
518 @cindex @samp{%} in template
519 @cindex percent sign
520 The @dfn{output template} is a string which specifies how to output the
521 assembler code for an instruction pattern.  Most of the template is a
522 fixed string which is output literally.  The character @samp{%} is used
523 to specify where to substitute an operand; it can also be used to
524 identify places where different variants of the assembler require
525 different syntax.
526
527 In the simplest case, a @samp{%} followed by a digit @var{n} says to output
528 operand @var{n} at that point in the string.
529
530 @samp{%} followed by a letter and a digit says to output an operand in an
531 alternate fashion.  Four letters have standard, built-in meanings described
532 below.  The machine description macro @code{PRINT_OPERAND} can define
533 additional letters with nonstandard meanings.
534
535 @samp{%c@var{digit}} can be used to substitute an operand that is a
536 constant value without the syntax that normally indicates an immediate
537 operand.
538
539 @samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of
540 the constant is negated before printing.
541
542 @samp{%a@var{digit}} can be used to substitute an operand as if it were a
543 memory reference, with the actual operand treated as the address.  This may
544 be useful when outputting a ``load address'' instruction, because often the
545 assembler syntax for such an instruction requires you to write the operand
546 as if it were a memory reference.
547
548 @samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump
549 instruction.
550
551 @samp{%=} outputs a number which is unique to each instruction in the
552 entire compilation.  This is useful for making local labels to be
553 referred to more than once in a single template that generates multiple
554 assembler instructions.
555
556 @samp{%} followed by a punctuation character specifies a substitution that
557 does not use an operand.  Only one case is standard: @samp{%%} outputs a
558 @samp{%} into the assembler code.  Other nonstandard cases can be
559 defined in the @code{PRINT_OPERAND} macro.  You must also define
560 which punctuation characters are valid with the
561 @code{PRINT_OPERAND_PUNCT_VALID_P} macro.
562
563 @cindex \
564 @cindex backslash
565 The template may generate multiple assembler instructions.  Write the text
566 for the instructions, with @samp{\;} between them.
567
568 @cindex matching operands
569 When the RTL contains two operands which are required by constraint to match
570 each other, the output template must refer only to the lower-numbered operand.
571 Matching operands are not always identical, and the rest of the compiler
572 arranges to put the proper RTL expression for printing into the lower-numbered
573 operand.
574
575 One use of nonstandard letters or punctuation following @samp{%} is to
576 distinguish between different assembler languages for the same machine; for
577 example, Motorola syntax versus MIT syntax for the 68000.  Motorola syntax
578 requires periods in most opcode names, while MIT syntax does not.  For
579 example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
580 syntax.  The same file of patterns is used for both kinds of output syntax,
581 but the character sequence @samp{%.} is used in each place where Motorola
582 syntax wants a period.  The @code{PRINT_OPERAND} macro for Motorola syntax
583 defines the sequence to output a period; the macro for MIT syntax defines
584 it to do nothing.
585
586 @cindex @code{#} in template
587 As a special case, a template consisting of the single character @code{#}
588 instructs the compiler to first split the insn, and then output the
589 resulting instructions separately.  This helps eliminate redundancy in the
590 output templates.   If you have a @code{define_insn} that needs to emit
591 multiple assembler instructions, and there is an matching @code{define_split}
592 already defined, then you can simply use @code{#} as the output template
593 instead of writing an output template that emits the multiple assembler
594 instructions.
595
596 If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct
597 of the form @samp{@{option0|option1|option2@}} in the templates.  These
598 describe multiple variants of assembler language syntax.
599 @xref{Instruction Output}.
600
601 @node Output Statement
602 @section C Statements for Assembler Output
603 @cindex output statements
604 @cindex C statements for assembler output
605 @cindex generating assembler output
606
607 Often a single fixed template string cannot produce correct and efficient
608 assembler code for all the cases that are recognized by a single
609 instruction pattern.  For example, the opcodes may depend on the kinds of
610 operands; or some unfortunate combinations of operands may require extra
611 machine instructions.
612
613 If the output control string starts with a @samp{@@}, then it is actually
614 a series of templates, each on a separate line.  (Blank lines and
615 leading spaces and tabs are ignored.)  The templates correspond to the
616 pattern's constraint alternatives (@pxref{Multi-Alternative}).  For example,
617 if a target machine has a two-address add instruction @samp{addr} to add
618 into a register and another @samp{addm} to add a register to memory, you
619 might write this pattern:
620
621 @smallexample
622 (define_insn "addsi3"
623   [(set (match_operand:SI 0 "general_operand" "=r,m")
624         (plus:SI (match_operand:SI 1 "general_operand" "0,0")
625                  (match_operand:SI 2 "general_operand" "g,r")))]
626   ""
627   "@@
628    addr %2,%0
629    addm %2,%0")
630 @end smallexample
631
632 @cindex @code{*} in template
633 @cindex asterisk in template
634 If the output control string starts with a @samp{*}, then it is not an
635 output template but rather a piece of C program that should compute a
636 template.  It should execute a @code{return} statement to return the
637 template-string you want.  Most such templates use C string literals, which
638 require doublequote characters to delimit them.  To include these
639 doublequote characters in the string, prefix each one with @samp{\}.
640
641 If the output control string is written as a brace block instead of a
642 double-quoted string, it is automatically assumed to be C code.  In that
643 case, it is not necessary to put in a leading asterisk, or to escape the
644 doublequotes surrounding C string literals.
645
646 The operands may be found in the array @code{operands}, whose C data type
647 is @code{rtx []}.
648
649 It is very common to select different ways of generating assembler code
650 based on whether an immediate operand is within a certain range.  Be
651 careful when doing this, because the result of @code{INTVAL} is an
652 integer on the host machine.  If the host machine has more bits in an
653 @code{int} than the target machine has in the mode in which the constant
654 will be used, then some of the bits you get from @code{INTVAL} will be
655 superfluous.  For proper results, you must carefully disregard the
656 values of those bits.
657
658 @findex output_asm_insn
659 It is possible to output an assembler instruction and then go on to output
660 or compute more of them, using the subroutine @code{output_asm_insn}.  This
661 receives two arguments: a template-string and a vector of operands.  The
662 vector may be @code{operands}, or it may be another array of @code{rtx}
663 that you declare locally and initialize yourself.
664
665 @findex which_alternative
666 When an insn pattern has multiple alternatives in its constraints, often
667 the appearance of the assembler code is determined mostly by which alternative
668 was matched.  When this is so, the C code can test the variable
669 @code{which_alternative}, which is the ordinal number of the alternative
670 that was actually satisfied (0 for the first, 1 for the second alternative,
671 etc.).
672
673 For example, suppose there are two opcodes for storing zero, @samp{clrreg}
674 for registers and @samp{clrmem} for memory locations.  Here is how
675 a pattern could use @code{which_alternative} to choose between them:
676
677 @smallexample
678 (define_insn ""
679   [(set (match_operand:SI 0 "general_operand" "=r,m")
680         (const_int 0))]
681   ""
682   @{
683   return (which_alternative == 0
684           ? "clrreg %0" : "clrmem %0");
685   @})
686 @end smallexample
687
688 The example above, where the assembler code to generate was
689 @emph{solely} determined by the alternative, could also have been specified
690 as follows, having the output control string start with a @samp{@@}:
691
692 @smallexample
693 @group
694 (define_insn ""
695   [(set (match_operand:SI 0 "general_operand" "=r,m")
696         (const_int 0))]
697   ""
698   "@@
699    clrreg %0
700    clrmem %0")
701 @end group
702 @end smallexample
703 @end ifset
704
705 @c Most of this node appears by itself (in a different place) even
706 @c when the INTERNALS flag is clear.  Passages that require the internals
707 @c manual's context are conditionalized to appear only in the internals manual.
708 @ifset INTERNALS
709 @node Constraints
710 @section Operand Constraints
711 @cindex operand constraints
712 @cindex constraints
713
714 Each @code{match_operand} in an instruction pattern can specify a
715 constraint for the type of operands allowed.
716 @end ifset
717 @ifclear INTERNALS
718 @node Constraints
719 @section Constraints for @code{asm} Operands
720 @cindex operand constraints, @code{asm}
721 @cindex constraints, @code{asm}
722 @cindex @code{asm} constraints
723
724 Here are specific details on what constraint letters you can use with
725 @code{asm} operands.
726 @end ifclear
727 Constraints can say whether
728 an operand may be in a register, and which kinds of register; whether the
729 operand can be a memory reference, and which kinds of address; whether the
730 operand may be an immediate constant, and which possible values it may
731 have.  Constraints can also require two operands to match.
732
733 @ifset INTERNALS
734 @menu
735 * Simple Constraints::  Basic use of constraints.
736 * Multi-Alternative::   When an insn has two alternative constraint-patterns.
737 * Class Preferences::   Constraints guide which hard register to put things in.
738 * Modifiers::           More precise control over effects of constraints.
739 * Machine Constraints:: Existing constraints for some particular machines.
740 @end menu
741 @end ifset
742
743 @ifclear INTERNALS
744 @menu
745 * Simple Constraints::  Basic use of constraints.
746 * Multi-Alternative::   When an insn has two alternative constraint-patterns.
747 * Modifiers::           More precise control over effects of constraints.
748 * Machine Constraints:: Special constraints for some particular machines.
749 @end menu
750 @end ifclear
751
752 @node Simple Constraints
753 @subsection Simple Constraints
754 @cindex simple constraints
755
756 The simplest kind of constraint is a string full of letters, each of
757 which describes one kind of operand that is permitted.  Here are
758 the letters that are allowed:
759
760 @table @asis
761 @item whitespace
762 Whitespace characters are ignored and can be inserted at any position
763 except the first.  This enables each alternative for different operands to
764 be visually aligned in the machine description even if they have different
765 number of constraints and modifiers.
766
767 @cindex @samp{m} in constraint
768 @cindex memory references in constraints
769 @item @samp{m}
770 A memory operand is allowed, with any kind of address that the machine
771 supports in general.
772
773 @cindex offsettable address
774 @cindex @samp{o} in constraint
775 @item @samp{o}
776 A memory operand is allowed, but only if the address is
777 @dfn{offsettable}.  This means that adding a small integer (actually,
778 the width in bytes of the operand, as determined by its machine mode)
779 may be added to the address and the result is also a valid memory
780 address.
781
782 @cindex autoincrement/decrement addressing
783 For example, an address which is constant is offsettable; so is an
784 address that is the sum of a register and a constant (as long as a
785 slightly larger constant is also within the range of address-offsets
786 supported by the machine); but an autoincrement or autodecrement
787 address is not offsettable.  More complicated indirect/indexed
788 addresses may or may not be offsettable depending on the other
789 addressing modes that the machine supports.
790
791 Note that in an output operand which can be matched by another
792 operand, the constraint letter @samp{o} is valid only when accompanied
793 by both @samp{<} (if the target machine has predecrement addressing)
794 and @samp{>} (if the target machine has preincrement addressing).
795
796 @cindex @samp{V} in constraint
797 @item @samp{V}
798 A memory operand that is not offsettable.  In other words, anything that
799 would fit the @samp{m} constraint but not the @samp{o} constraint.
800
801 @cindex @samp{<} in constraint
802 @item @samp{<}
803 A memory operand with autodecrement addressing (either predecrement or
804 postdecrement) is allowed.
805
806 @cindex @samp{>} in constraint
807 @item @samp{>}
808 A memory operand with autoincrement addressing (either preincrement or
809 postincrement) is allowed.
810
811 @cindex @samp{r} in constraint
812 @cindex registers in constraints
813 @item @samp{r}
814 A register operand is allowed provided that it is in a general
815 register.
816
817 @cindex constants in constraints
818 @cindex @samp{i} in constraint
819 @item @samp{i}
820 An immediate integer operand (one with constant value) is allowed.
821 This includes symbolic constants whose values will be known only at
822 assembly time.
823
824 @cindex @samp{n} in constraint
825 @item @samp{n}
826 An immediate integer operand with a known numeric value is allowed.
827 Many systems cannot support assembly-time constants for operands less
828 than a word wide.  Constraints for these operands should use @samp{n}
829 rather than @samp{i}.
830
831 @cindex @samp{I} in constraint
832 @item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}
833 Other letters in the range @samp{I} through @samp{P} may be defined in
834 a machine-dependent fashion to permit immediate integer operands with
835 explicit integer values in specified ranges.  For example, on the
836 68000, @samp{I} is defined to stand for the range of values 1 to 8.
837 This is the range permitted as a shift count in the shift
838 instructions.
839
840 @cindex @samp{E} in constraint
841 @item @samp{E}
842 An immediate floating operand (expression code @code{const_double}) is
843 allowed, but only if the target floating point format is the same as
844 that of the host machine (on which the compiler is running).
845
846 @cindex @samp{F} in constraint
847 @item @samp{F}
848 An immediate floating operand (expression code @code{const_double} or
849 @code{const_vector}) is allowed.
850
851 @cindex @samp{G} in constraint
852 @cindex @samp{H} in constraint
853 @item @samp{G}, @samp{H}
854 @samp{G} and @samp{H} may be defined in a machine-dependent fashion to
855 permit immediate floating operands in particular ranges of values.
856
857 @cindex @samp{s} in constraint
858 @item @samp{s}
859 An immediate integer operand whose value is not an explicit integer is
860 allowed.
861
862 This might appear strange; if an insn allows a constant operand with a
863 value not known at compile time, it certainly must allow any known
864 value.  So why use @samp{s} instead of @samp{i}?  Sometimes it allows
865 better code to be generated.
866
867 For example, on the 68000 in a fullword instruction it is possible to
868 use an immediate operand; but if the immediate value is between @minus{}128
869 and 127, better code results from loading the value into a register and
870 using the register.  This is because the load into the register can be
871 done with a @samp{moveq} instruction.  We arrange for this to happen
872 by defining the letter @samp{K} to mean ``any integer outside the
873 range @minus{}128 to 127'', and then specifying @samp{Ks} in the operand
874 constraints.
875
876 @cindex @samp{g} in constraint
877 @item @samp{g}
878 Any register, memory or immediate integer operand is allowed, except for
879 registers that are not general registers.
880
881 @cindex @samp{X} in constraint
882 @item @samp{X}
883 @ifset INTERNALS
884 Any operand whatsoever is allowed, even if it does not satisfy
885 @code{general_operand}.  This is normally used in the constraint of
886 a @code{match_scratch} when certain alternatives will not actually
887 require a scratch register.
888 @end ifset
889 @ifclear INTERNALS
890 Any operand whatsoever is allowed.
891 @end ifclear
892
893 @cindex @samp{0} in constraint
894 @cindex digits in constraint
895 @item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{9}
896 An operand that matches the specified operand number is allowed.  If a
897 digit is used together with letters within the same alternative, the
898 digit should come last.
899
900 This number is allowed to be more than a single digit.  If multiple
901 digits are encountered consecutively, they are interpreted as a single
902 decimal integer.  There is scant chance for ambiguity, since to-date
903 it has never been desirable that @samp{10} be interpreted as matching
904 either operand 1 @emph{or} operand 0.  Should this be desired, one
905 can use multiple alternatives instead.
906
907 @cindex matching constraint
908 @cindex constraint, matching
909 This is called a @dfn{matching constraint} and what it really means is
910 that the assembler has only a single operand that fills two roles
911 @ifset INTERNALS
912 considered separate in the RTL insn.  For example, an add insn has two
913 input operands and one output operand in the RTL, but on most CISC
914 @end ifset
915 @ifclear INTERNALS
916 which @code{asm} distinguishes.  For example, an add instruction uses
917 two input operands and an output operand, but on most CISC
918 @end ifclear
919 machines an add instruction really has only two operands, one of them an
920 input-output operand:
921
922 @smallexample
923 addl #35,r12
924 @end smallexample
925
926 Matching constraints are used in these circumstances.
927 More precisely, the two operands that match must include one input-only
928 operand and one output-only operand.  Moreover, the digit must be a
929 smaller number than the number of the operand that uses it in the
930 constraint.
931
932 @ifset INTERNALS
933 For operands to match in a particular case usually means that they
934 are identical-looking RTL expressions.  But in a few special cases
935 specific kinds of dissimilarity are allowed.  For example, @code{*x}
936 as an input operand will match @code{*x++} as an output operand.
937 For proper results in such cases, the output template should always
938 use the output-operand's number when printing the operand.
939 @end ifset
940
941 @cindex load address instruction
942 @cindex push address instruction
943 @cindex address constraints
944 @cindex @samp{p} in constraint
945 @item @samp{p}
946 An operand that is a valid memory address is allowed.  This is
947 for ``load address'' and ``push address'' instructions.
948
949 @findex address_operand
950 @samp{p} in the constraint must be accompanied by @code{address_operand}
951 as the predicate in the @code{match_operand}.  This predicate interprets
952 the mode specified in the @code{match_operand} as the mode of the memory
953 reference for which the address would be valid.
954
955 @cindex other register constraints
956 @cindex extensible constraints
957 @item @var{other-letters}
958 Other letters can be defined in machine-dependent fashion to stand for
959 particular classes of registers or other arbitrary operand types.
960 @samp{d}, @samp{a} and @samp{f} are defined on the 68000/68020 to stand
961 for data, address and floating point registers.
962
963 @ifset INTERNALS
964 The machine description macro @code{REG_CLASS_FROM_LETTER} has first
965 cut at the otherwise unused letters.  If it evaluates to @code{NO_REGS},
966 then @code{EXTRA_CONSTRAINT} is evaluated.
967
968 A typical use for @code{EXTRA_CONSTRAINT} would be to distinguish certain
969 types of memory references that affect other insn operands.
970 @end ifset
971 @end table
972
973 @ifset INTERNALS
974 In order to have valid assembler code, each operand must satisfy
975 its constraint.  But a failure to do so does not prevent the pattern
976 from applying to an insn.  Instead, it directs the compiler to modify
977 the code so that the constraint will be satisfied.  Usually this is
978 done by copying an operand into a register.
979
980 Contrast, therefore, the two instruction patterns that follow:
981
982 @smallexample
983 (define_insn ""
984   [(set (match_operand:SI 0 "general_operand" "=r")
985         (plus:SI (match_dup 0)
986                  (match_operand:SI 1 "general_operand" "r")))]
987   ""
988   "@dots{}")
989 @end smallexample
990
991 @noindent
992 which has two operands, one of which must appear in two places, and
993
994 @smallexample
995 (define_insn ""
996   [(set (match_operand:SI 0 "general_operand" "=r")
997         (plus:SI (match_operand:SI 1 "general_operand" "0")
998                  (match_operand:SI 2 "general_operand" "r")))]
999   ""
1000   "@dots{}")
1001 @end smallexample
1002
1003 @noindent
1004 which has three operands, two of which are required by a constraint to be
1005 identical.  If we are considering an insn of the form
1006
1007 @smallexample
1008 (insn @var{n} @var{prev} @var{next}
1009   (set (reg:SI 3)
1010        (plus:SI (reg:SI 6) (reg:SI 109)))
1011   @dots{})
1012 @end smallexample
1013
1014 @noindent
1015 the first pattern would not apply at all, because this insn does not
1016 contain two identical subexpressions in the right place.  The pattern would
1017 say, ``That does not look like an add instruction; try other patterns.''
1018 The second pattern would say, ``Yes, that's an add instruction, but there
1019 is something wrong with it.''  It would direct the reload pass of the
1020 compiler to generate additional insns to make the constraint true.  The
1021 results might look like this:
1022
1023 @smallexample
1024 (insn @var{n2} @var{prev} @var{n}
1025   (set (reg:SI 3) (reg:SI 6))
1026   @dots{})
1027
1028 (insn @var{n} @var{n2} @var{next}
1029   (set (reg:SI 3)
1030        (plus:SI (reg:SI 3) (reg:SI 109)))
1031   @dots{})
1032 @end smallexample
1033
1034 It is up to you to make sure that each operand, in each pattern, has
1035 constraints that can handle any RTL expression that could be present for
1036 that operand.  (When multiple alternatives are in use, each pattern must,
1037 for each possible combination of operand expressions, have at least one
1038 alternative which can handle that combination of operands.)  The
1039 constraints don't need to @emph{allow} any possible operand---when this is
1040 the case, they do not constrain---but they must at least point the way to
1041 reloading any possible operand so that it will fit.
1042
1043 @itemize @bullet
1044 @item
1045 If the constraint accepts whatever operands the predicate permits,
1046 there is no problem: reloading is never necessary for this operand.
1047
1048 For example, an operand whose constraints permit everything except
1049 registers is safe provided its predicate rejects registers.
1050
1051 An operand whose predicate accepts only constant values is safe
1052 provided its constraints include the letter @samp{i}.  If any possible
1053 constant value is accepted, then nothing less than @samp{i} will do;
1054 if the predicate is more selective, then the constraints may also be
1055 more selective.
1056
1057 @item
1058 Any operand expression can be reloaded by copying it into a register.
1059 So if an operand's constraints allow some kind of register, it is
1060 certain to be safe.  It need not permit all classes of registers; the
1061 compiler knows how to copy a register into another register of the
1062 proper class in order to make an instruction valid.
1063
1064 @cindex nonoffsettable memory reference
1065 @cindex memory reference, nonoffsettable
1066 @item
1067 A nonoffsettable memory reference can be reloaded by copying the
1068 address into a register.  So if the constraint uses the letter
1069 @samp{o}, all memory references are taken care of.
1070
1071 @item
1072 A constant operand can be reloaded by allocating space in memory to
1073 hold it as preinitialized data.  Then the memory reference can be used
1074 in place of the constant.  So if the constraint uses the letters
1075 @samp{o} or @samp{m}, constant operands are not a problem.
1076
1077 @item
1078 If the constraint permits a constant and a pseudo register used in an insn
1079 was not allocated to a hard register and is equivalent to a constant,
1080 the register will be replaced with the constant.  If the predicate does
1081 not permit a constant and the insn is re-recognized for some reason, the
1082 compiler will crash.  Thus the predicate must always recognize any
1083 objects allowed by the constraint.
1084 @end itemize
1085
1086 If the operand's predicate can recognize registers, but the constraint does
1087 not permit them, it can make the compiler crash.  When this operand happens
1088 to be a register, the reload pass will be stymied, because it does not know
1089 how to copy a register temporarily into memory.
1090
1091 If the predicate accepts a unary operator, the constraint applies to the
1092 operand.  For example, the MIPS processor at ISA level 3 supports an
1093 instruction which adds two registers in @code{SImode} to produce a
1094 @code{DImode} result, but only if the registers are correctly sign
1095 extended.  This predicate for the input operands accepts a
1096 @code{sign_extend} of an @code{SImode} register.  Write the constraint
1097 to indicate the type of register that is required for the operand of the
1098 @code{sign_extend}.
1099 @end ifset
1100
1101 @node Multi-Alternative
1102 @subsection Multiple Alternative Constraints
1103 @cindex multiple alternative constraints
1104
1105 Sometimes a single instruction has multiple alternative sets of possible
1106 operands.  For example, on the 68000, a logical-or instruction can combine
1107 register or an immediate value into memory, or it can combine any kind of
1108 operand into a register; but it cannot combine one memory location into
1109 another.
1110
1111 These constraints are represented as multiple alternatives.  An alternative
1112 can be described by a series of letters for each operand.  The overall
1113 constraint for an operand is made from the letters for this operand
1114 from the first alternative, a comma, the letters for this operand from
1115 the second alternative, a comma, and so on until the last alternative.
1116 @ifset INTERNALS
1117 Here is how it is done for fullword logical-or on the 68000:
1118
1119 @smallexample
1120 (define_insn "iorsi3"
1121   [(set (match_operand:SI 0 "general_operand" "=m,d")
1122         (ior:SI (match_operand:SI 1 "general_operand" "%0,0")
1123                 (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
1124   @dots{})
1125 @end smallexample
1126
1127 The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
1128 operand 1 (meaning it must match operand 0), and @samp{dKs} for operand
1129 2.  The second alternative has @samp{d} (data register) for operand 0,
1130 @samp{0} for operand 1, and @samp{dmKs} for operand 2.  The @samp{=} and
1131 @samp{%} in the constraints apply to all the alternatives; their
1132 meaning is explained in the next section (@pxref{Class Preferences}).
1133 @end ifset
1134
1135 @c FIXME Is this ? and ! stuff of use in asm()?  If not, hide unless INTERNAL
1136 If all the operands fit any one alternative, the instruction is valid.
1137 Otherwise, for each alternative, the compiler counts how many instructions
1138 must be added to copy the operands so that that alternative applies.
1139 The alternative requiring the least copying is chosen.  If two alternatives
1140 need the same amount of copying, the one that comes first is chosen.
1141 These choices can be altered with the @samp{?} and @samp{!} characters:
1142
1143 @table @code
1144 @cindex @samp{?} in constraint
1145 @cindex question mark
1146 @item ?
1147 Disparage slightly the alternative that the @samp{?} appears in,
1148 as a choice when no alternative applies exactly.  The compiler regards
1149 this alternative as one unit more costly for each @samp{?} that appears
1150 in it.
1151
1152 @cindex @samp{!} in constraint
1153 @cindex exclamation point
1154 @item !
1155 Disparage severely the alternative that the @samp{!} appears in.
1156 This alternative can still be used if it fits without reloading,
1157 but if reloading is needed, some other alternative will be used.
1158 @end table
1159
1160 @ifset INTERNALS
1161 When an insn pattern has multiple alternatives in its constraints, often
1162 the appearance of the assembler code is determined mostly by which
1163 alternative was matched.  When this is so, the C code for writing the
1164 assembler code can use the variable @code{which_alternative}, which is
1165 the ordinal number of the alternative that was actually satisfied (0 for
1166 the first, 1 for the second alternative, etc.).  @xref{Output Statement}.
1167 @end ifset
1168
1169 @ifset INTERNALS
1170 @node Class Preferences
1171 @subsection Register Class Preferences
1172 @cindex class preference constraints
1173 @cindex register class preference constraints
1174
1175 @cindex voting between constraint alternatives
1176 The operand constraints have another function: they enable the compiler
1177 to decide which kind of hardware register a pseudo register is best
1178 allocated to.  The compiler examines the constraints that apply to the
1179 insns that use the pseudo register, looking for the machine-dependent
1180 letters such as @samp{d} and @samp{a} that specify classes of registers.
1181 The pseudo register is put in whichever class gets the most ``votes''.
1182 The constraint letters @samp{g} and @samp{r} also vote: they vote in
1183 favor of a general register.  The machine description says which registers
1184 are considered general.
1185
1186 Of course, on some machines all registers are equivalent, and no register
1187 classes are defined.  Then none of this complexity is relevant.
1188 @end ifset
1189
1190 @node Modifiers
1191 @subsection Constraint Modifier Characters
1192 @cindex modifiers in constraints
1193 @cindex constraint modifier characters
1194
1195 @c prevent bad page break with this line
1196 Here are constraint modifier characters.
1197
1198 @table @samp
1199 @cindex @samp{=} in constraint
1200 @item =
1201 Means that this operand is write-only for this instruction: the previous
1202 value is discarded and replaced by output data.
1203
1204 @cindex @samp{+} in constraint
1205 @item +
1206 Means that this operand is both read and written by the instruction.
1207
1208 When the compiler fixes up the operands to satisfy the constraints,
1209 it needs to know which operands are inputs to the instruction and
1210 which are outputs from it.  @samp{=} identifies an output; @samp{+}
1211 identifies an operand that is both input and output; all other operands
1212 are assumed to be input only.
1213
1214 If you specify @samp{=} or @samp{+} in a constraint, you put it in the
1215 first character of the constraint string.
1216
1217 @cindex @samp{&} in constraint
1218 @cindex earlyclobber operand
1219 @item &
1220 Means (in a particular alternative) that this operand is an
1221 @dfn{earlyclobber} operand, which is modified before the instruction is
1222 finished using the input operands.  Therefore, this operand may not lie
1223 in a register that is used as an input operand or as part of any memory
1224 address.
1225
1226 @samp{&} applies only to the alternative in which it is written.  In
1227 constraints with multiple alternatives, sometimes one alternative
1228 requires @samp{&} while others do not.  See, for example, the
1229 @samp{movdf} insn of the 68000.
1230
1231 An input operand can be tied to an earlyclobber operand if its only
1232 use as an input occurs before the early result is written.  Adding
1233 alternatives of this form often allows GCC to produce better code
1234 when only some of the inputs can be affected by the earlyclobber.
1235 See, for example, the @samp{mulsi3} insn of the ARM@.
1236
1237 @samp{&} does not obviate the need to write @samp{=}.
1238
1239 @cindex @samp{%} in constraint
1240 @item %
1241 Declares the instruction to be commutative for this operand and the
1242 following operand.  This means that the compiler may interchange the
1243 two operands if that is the cheapest way to make all operands fit the
1244 constraints.
1245 @ifset INTERNALS
1246 This is often used in patterns for addition instructions
1247 that really have only two operands: the result must go in one of the
1248 arguments.  Here for example, is how the 68000 halfword-add
1249 instruction is defined:
1250
1251 @smallexample
1252 (define_insn "addhi3"
1253   [(set (match_operand:HI 0 "general_operand" "=m,r")
1254      (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
1255               (match_operand:HI 2 "general_operand" "di,g")))]
1256   @dots{})
1257 @end smallexample
1258 @end ifset
1259 GCC can only handle one commutative pair in an asm; if you use more, 
1260 the compiler may fail.
1261
1262 @cindex @samp{#} in constraint
1263 @item #
1264 Says that all following characters, up to the next comma, are to be
1265 ignored as a constraint.  They are significant only for choosing
1266 register preferences.
1267
1268 @cindex @samp{*} in constraint
1269 @item *
1270 Says that the following character should be ignored when choosing
1271 register preferences.  @samp{*} has no effect on the meaning of the
1272 constraint as a constraint, and no effect on reloading.
1273
1274 @ifset INTERNALS
1275 Here is an example: the 68000 has an instruction to sign-extend a
1276 halfword in a data register, and can also sign-extend a value by
1277 copying it into an address register.  While either kind of register is
1278 acceptable, the constraints on an address-register destination are
1279 less strict, so it is best if register allocation makes an address
1280 register its goal.  Therefore, @samp{*} is used so that the @samp{d}
1281 constraint letter (for data register) is ignored when computing
1282 register preferences.
1283
1284 @smallexample
1285 (define_insn "extendhisi2"
1286   [(set (match_operand:SI 0 "general_operand" "=*d,a")
1287         (sign_extend:SI
1288          (match_operand:HI 1 "general_operand" "0,g")))]
1289   @dots{})
1290 @end smallexample
1291 @end ifset
1292 @end table
1293
1294 @node Machine Constraints
1295 @subsection Constraints for Particular Machines
1296 @cindex machine specific constraints
1297 @cindex constraints, machine specific
1298
1299 Whenever possible, you should use the general-purpose constraint letters
1300 in @code{asm} arguments, since they will convey meaning more readily to
1301 people reading your code.  Failing that, use the constraint letters
1302 that usually have very similar meanings across architectures.  The most
1303 commonly used constraints are @samp{m} and @samp{r} (for memory and
1304 general-purpose registers respectively; @pxref{Simple Constraints}), and
1305 @samp{I}, usually the letter indicating the most common
1306 immediate-constant format.
1307
1308 For each machine architecture, the
1309 @file{config/@var{machine}/@var{machine}.h} file defines additional
1310 constraints.  These constraints are used by the compiler itself for
1311 instruction generation, as well as for @code{asm} statements; therefore,
1312 some of the constraints are not particularly interesting for @code{asm}.
1313 The constraints are defined through these macros:
1314
1315 @table @code
1316 @item REG_CLASS_FROM_LETTER
1317 Register class constraints (usually lowercase).
1318
1319 @item CONST_OK_FOR_LETTER_P
1320 Immediate constant constraints, for non-floating point constants of
1321 word size or smaller precision (usually uppercase).
1322
1323 @item CONST_DOUBLE_OK_FOR_LETTER_P
1324 Immediate constant constraints, for all floating point constants and for
1325 constants of greater than word size precision (usually uppercase).
1326
1327 @item EXTRA_CONSTRAINT
1328 Special cases of registers or memory.  This macro is not required, and
1329 is only defined for some machines.
1330 @end table
1331
1332 Inspecting these macro definitions in the compiler source for your
1333 machine is the best way to be certain you have the right constraints.
1334 However, here is a summary of the machine-dependent constraints
1335 available on some particular machines.
1336
1337 @table @emph
1338 @item ARM family---@file{arm.h}
1339 @table @code
1340 @item f
1341 Floating-point register
1342
1343 @item F
1344 One of the floating-point constants 0.0, 0.5, 1.0, 2.0, 3.0, 4.0, 5.0
1345 or 10.0
1346
1347 @item G
1348 Floating-point constant that would satisfy the constraint @samp{F} if it
1349 were negated
1350
1351 @item I
1352 Integer that is valid as an immediate operand in a data processing
1353 instruction.  That is, an integer in the range 0 to 255 rotated by a
1354 multiple of 2
1355
1356 @item J
1357 Integer in the range @minus{}4095 to 4095
1358
1359 @item K
1360 Integer that satisfies constraint @samp{I} when inverted (ones complement)
1361
1362 @item L
1363 Integer that satisfies constraint @samp{I} when negated (twos complement)
1364
1365 @item M
1366 Integer in the range 0 to 32
1367
1368 @item Q
1369 A memory reference where the exact address is in a single register
1370 (`@samp{m}' is preferable for @code{asm} statements)
1371
1372 @item R
1373 An item in the constant pool
1374
1375 @item S
1376 A symbol in the text segment of the current file
1377 @end table
1378
1379 @item AVR family---@file{avr.h}
1380 @table @code
1381 @item l
1382 Registers from r0 to r15
1383
1384 @item a
1385 Registers from r16 to r23
1386
1387 @item d
1388 Registers from r16 to r31
1389
1390 @item w
1391 Registers from r24 to r31.  These registers can be used in @samp{adiw} command
1392
1393 @item e
1394 Pointer register (r26--r31)
1395
1396 @item b
1397 Base pointer register (r28--r31)
1398
1399 @item q
1400 Stack pointer register (SPH:SPL)
1401
1402 @item t
1403 Temporary register r0
1404
1405 @item x
1406 Register pair X (r27:r26)
1407
1408 @item y
1409 Register pair Y (r29:r28)
1410
1411 @item z
1412 Register pair Z (r31:r30)
1413
1414 @item I
1415 Constant greater than @minus{}1, less than 64
1416
1417 @item J
1418 Constant greater than @minus{}64, less than 1
1419
1420 @item K
1421 Constant integer 2
1422
1423 @item L
1424 Constant integer 0
1425
1426 @item M
1427 Constant that fits in 8 bits
1428
1429 @item N
1430 Constant integer @minus{}1
1431
1432 @item O
1433 Constant integer 8, 16, or 24
1434
1435 @item P
1436 Constant integer 1
1437
1438 @item G
1439 A floating point constant 0.0
1440 @end table
1441
1442 @item PowerPC and IBM RS6000---@file{rs6000.h}
1443 @table @code
1444 @item b
1445 Address base register
1446
1447 @item f
1448 Floating point register
1449
1450 @item v
1451 Vector register
1452
1453 @item h
1454 @samp{MQ}, @samp{CTR}, or @samp{LINK} register
1455
1456 @item q
1457 @samp{MQ} register
1458
1459 @item c
1460 @samp{CTR} register
1461
1462 @item l
1463 @samp{LINK} register
1464
1465 @item x
1466 @samp{CR} register (condition register) number 0
1467
1468 @item y
1469 @samp{CR} register (condition register)
1470
1471 @item z
1472 @samp{FPMEM} stack memory for FPR-GPR transfers
1473
1474 @item I
1475 Signed 16-bit constant
1476
1477 @item J
1478 Unsigned 16-bit constant shifted left 16 bits (use @samp{L} instead for
1479 @code{SImode} constants)
1480
1481 @item K
1482 Unsigned 16-bit constant
1483
1484 @item L
1485 Signed 16-bit constant shifted left 16 bits
1486
1487 @item M
1488 Constant larger than 31
1489
1490 @item N
1491 Exact power of 2
1492
1493 @item O
1494 Zero
1495
1496 @item P
1497 Constant whose negation is a signed 16-bit constant
1498
1499 @item G
1500 Floating point constant that can be loaded into a register with one
1501 instruction per word
1502
1503 @item Q
1504 Memory operand that is an offset from a register (@samp{m} is preferable
1505 for @code{asm} statements)
1506
1507 @item R
1508 AIX TOC entry
1509
1510 @item S
1511 Constant suitable as a 64-bit mask operand
1512
1513 @item T
1514 Constant suitable as a 32-bit mask operand
1515
1516 @item U
1517 System V Release 4 small data area reference
1518 @end table
1519
1520 @item Intel 386---@file{i386.h}
1521 @table @code
1522 @item q
1523 @samp{a}, @code{b}, @code{c}, or @code{d} register for the i386.
1524 For x86-64 it is equivalent to @samp{r} class. (for 8-bit instructions that
1525 do not use upper halves)
1526
1527 @item Q
1528 @samp{a}, @code{b}, @code{c}, or @code{d} register. (for 8-bit instructions,
1529 that do use upper halves)
1530
1531 @item R
1532 Legacy register---equivalent to @code{r} class in i386 mode.
1533 (for non-8-bit registers used together with 8-bit upper halves in a single
1534 instruction)
1535
1536 @item A
1537 Specifies the @samp{a} or @samp{d} registers.  This is primarily useful
1538 for 64-bit integer values (when in 32-bit mode) intended to be returned
1539 with the @samp{d} register holding the most significant bits and the
1540 @samp{a} register holding the least significant bits.
1541
1542 @item f
1543 Floating point register
1544
1545 @item t
1546 First (top of stack) floating point register
1547
1548 @item u
1549 Second floating point register
1550
1551 @item a
1552 @samp{a} register
1553
1554 @item b
1555 @samp{b} register
1556
1557 @item c
1558 @samp{c} register
1559
1560 @item C
1561 Specifies constant that can be easily constructed in SSE register without
1562 loading it from memory.
1563
1564 @item d
1565 @samp{d} register
1566
1567 @item D
1568 @samp{di} register
1569
1570 @item S
1571 @samp{si} register
1572
1573 @item x
1574 @samp{xmm} SSE register
1575
1576 @item y
1577 MMX register
1578
1579 @item I
1580 Constant in range 0 to 31 (for 32-bit shifts)
1581
1582 @item J
1583 Constant in range 0 to 63 (for 64-bit shifts)
1584
1585 @item K
1586 @samp{0xff}
1587
1588 @item L
1589 @samp{0xffff}
1590
1591 @item M
1592 0, 1, 2, or 3 (shifts for @code{lea} instruction)
1593
1594 @item N
1595 Constant in range 0 to 255 (for @code{out} instruction)
1596
1597 @item Z
1598 Constant in range 0 to @code{0xffffffff} or symbolic reference known to fit specified range.
1599 (for using immediates in zero extending 32-bit to 64-bit x86-64 instructions)
1600
1601 @item e
1602 Constant in range @minus{}2147483648 to 2147483647 or symbolic reference known to fit specified range.
1603 (for using immediates in 64-bit x86-64 instructions)
1604
1605 @item G
1606 Standard 80387 floating point constant
1607 @end table
1608
1609 @item Intel 960---@file{i960.h}
1610 @table @code
1611 @item f
1612 Floating point register (@code{fp0} to @code{fp3})
1613
1614 @item l
1615 Local register (@code{r0} to @code{r15})
1616
1617 @item b
1618 Global register (@code{g0} to @code{g15})
1619
1620 @item d
1621 Any local or global register
1622
1623 @item I
1624 Integers from 0 to 31
1625
1626 @item J
1627 0
1628
1629 @item K
1630 Integers from @minus{}31 to 0
1631
1632 @item G
1633 Floating point 0
1634
1635 @item H
1636 Floating point 1
1637 @end table
1638
1639 @item Intel IA-64---@file{ia64.h}
1640 @table @code
1641 @item a
1642 General register @code{r0} to @code{r3} for @code{addl} instruction
1643
1644 @item b
1645 Branch register
1646
1647 @item c
1648 Predicate register (@samp{c} as in ``conditional'')
1649
1650 @item d
1651 Application register residing in M-unit
1652
1653 @item e
1654 Application register residing in I-unit
1655
1656 @item f
1657 Floating-point register
1658
1659 @item m
1660 Memory operand.
1661 Remember that @samp{m} allows postincrement and postdecrement which
1662 require printing with @samp{%Pn} on IA-64.
1663 Use @samp{S} to disallow postincrement and postdecrement.
1664
1665 @item G
1666 Floating-point constant 0.0 or 1.0
1667
1668 @item I
1669 14-bit signed integer constant
1670
1671 @item J
1672 22-bit signed integer constant
1673
1674 @item K
1675 8-bit signed integer constant for logical instructions
1676
1677 @item L
1678 8-bit adjusted signed integer constant for compare pseudo-ops
1679
1680 @item M
1681 6-bit unsigned integer constant for shift counts
1682
1683 @item N
1684 9-bit signed integer constant for load and store postincrements
1685
1686 @item O
1687 The constant zero
1688
1689 @item P
1690 0 or -1 for @code{dep} instruction
1691
1692 @item Q
1693 Non-volatile memory for floating-point loads and stores
1694
1695 @item R
1696 Integer constant in the range 1 to 4 for @code{shladd} instruction
1697
1698 @item S
1699 Memory operand except postincrement and postdecrement
1700 @end table
1701
1702 @item FRV---@file{frv.h}
1703 @table @code
1704 @item a
1705 Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}).
1706
1707 @item b
1708 Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}).
1709
1710 @item c
1711 Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and
1712 @code{icc0} to @code{icc3}).
1713
1714 @item d
1715 Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}).
1716
1717 @item e
1718 Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}).
1719 Odd registers are excluded not in the class but through the use of a machine
1720 mode larger than 4 bytes.
1721
1722 @item f
1723 Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}).
1724
1725 @item h
1726 Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}).
1727 Odd registers are excluded not in the class but through the use of a machine
1728 mode larger than 4 bytes.
1729
1730 @item l
1731 Register in the class @code{LR_REG} (the @code{lr} register).
1732
1733 @item q
1734 Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}).
1735 Register numbers not divisible by 4 are excluded not in the class but through
1736 the use of a machine mode larger than 8 bytes.
1737
1738 @item t
1739 Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}).
1740
1741 @item u
1742 Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}).
1743
1744 @item v
1745 Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}).
1746
1747 @item w
1748 Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}).
1749
1750 @item x
1751 Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}).
1752 Register numbers not divisible by 4 are excluded not in the class but through
1753 the use of a machine mode larger than 8 bytes.
1754
1755 @item z
1756 Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}).
1757
1758 @item A
1759 Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}).
1760
1761 @item B
1762 Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}).
1763
1764 @item C
1765 Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}).
1766
1767 @item G
1768 Floating point constant zero
1769
1770 @item I
1771 6-bit signed integer constant
1772
1773 @item J
1774 10-bit signed integer constant
1775
1776 @item L
1777 16-bit signed integer constant
1778
1779 @item M
1780 16-bit unsigned integer constant
1781
1782 @item N
1783 12-bit signed integer constant that is negative---i.e.@: in the
1784 range of @minus{}2048 to @minus{}1
1785
1786 @item O
1787 Constant zero
1788
1789 @item P
1790 12-bit signed integer constant that is greater than zero---i.e.@: in the
1791 range of 1 to 2047.
1792
1793 @end table
1794
1795 @item IP2K---@file{ip2k.h}
1796 @table @code
1797 @item a
1798 @samp{DP} or @samp{IP} registers (general address)
1799
1800 @item f
1801 @samp{IP} register
1802
1803 @item j
1804 @samp{IPL} register
1805
1806 @item k
1807 @samp{IPH} register
1808
1809 @item b
1810 @samp{DP} register
1811
1812 @item y
1813 @samp{DPH} register
1814
1815 @item z
1816 @samp{DPL} register
1817
1818 @item q
1819 @samp{SP} register
1820
1821 @item c
1822 @samp{DP} or @samp{SP} registers (offsettable address)
1823
1824 @item d
1825 Non-pointer registers (not @samp{SP}, @samp{DP}, @samp{IP})
1826
1827 @item u
1828 Non-SP registers (everything except @samp{SP})
1829
1830 @item R
1831 Indirect through @samp{IP} - Avoid this except for @code{QImode}, since we
1832 can't access extra bytes
1833
1834 @item S
1835 Indirect through @samp{SP} or @samp{DP} with short displacement (0..127)
1836
1837 @item T
1838 Data-section immediate value
1839
1840 @item I
1841 Integers from @minus{}255 to @minus{}1
1842
1843 @item J
1844 Integers from 0 to 7---valid bit number in a register
1845
1846 @item K
1847 Integers from 0 to 127---valid displacement for addressing mode
1848
1849 @item L
1850 Integers from 1 to 127
1851
1852 @item M
1853 Integer @minus{}1
1854
1855 @item N
1856 Integer 1
1857
1858 @item O
1859 Zero
1860
1861 @item P
1862 Integers from 0 to 255
1863 @end table
1864
1865 @item MIPS---@file{mips.h}
1866 @table @code
1867 @item d
1868 General-purpose integer register
1869
1870 @item f
1871 Floating-point register (if available)
1872
1873 @item h
1874 @samp{Hi} register
1875
1876 @item l
1877 @samp{Lo} register
1878
1879 @item x
1880 @samp{Hi} or @samp{Lo} register
1881
1882 @item y
1883 General-purpose integer register
1884
1885 @item z
1886 Floating-point status register
1887
1888 @item I
1889 Signed 16-bit constant (for arithmetic instructions)
1890
1891 @item J
1892 Zero
1893
1894 @item K
1895 Zero-extended 16-bit constant (for logic instructions)
1896
1897 @item L
1898 Constant with low 16 bits zero (can be loaded with @code{lui})
1899
1900 @item M
1901 32-bit constant which requires two instructions to load (a constant
1902 which is not @samp{I}, @samp{K}, or @samp{L})
1903
1904 @item N
1905 Negative 16-bit constant
1906
1907 @item O
1908 Exact power of two
1909
1910 @item P
1911 Positive 16-bit constant
1912
1913 @item G
1914 Floating point zero
1915
1916 @item Q
1917 Memory reference that can be loaded with more than one instruction
1918 (@samp{m} is preferable for @code{asm} statements)
1919
1920 @item R
1921 Memory reference that can be loaded with one instruction
1922 (@samp{m} is preferable for @code{asm} statements)
1923
1924 @item S
1925 Memory reference in external OSF/rose PIC format
1926 (@samp{m} is preferable for @code{asm} statements)
1927 @end table
1928
1929 @item Motorola 680x0---@file{m68k.h}
1930 @table @code
1931 @item a
1932 Address register
1933
1934 @item d
1935 Data register
1936
1937 @item f
1938 68881 floating-point register, if available
1939
1940 @item I
1941 Integer in the range 1 to 8
1942
1943 @item J
1944 16-bit signed number
1945
1946 @item K
1947 Signed number whose magnitude is greater than 0x80
1948
1949 @item L
1950 Integer in the range @minus{}8 to @minus{}1
1951
1952 @item M
1953 Signed number whose magnitude is greater than 0x100
1954
1955 @item G
1956 Floating point constant that is not a 68881 constant
1957 @end table
1958
1959 @item Motorola 68HC11 & 68HC12 families---@file{m68hc11.h}
1960 @table @code
1961 @item a
1962 Register 'a'
1963
1964 @item b
1965 Register 'b'
1966
1967 @item d
1968 Register 'd'
1969
1970 @item q
1971 An 8-bit register
1972
1973 @item t
1974 Temporary soft register _.tmp
1975
1976 @item u
1977 A soft register _.d1 to _.d31
1978
1979 @item w
1980 Stack pointer register
1981
1982 @item x
1983 Register 'x'
1984
1985 @item y
1986 Register 'y'
1987
1988 @item z
1989 Pseudo register 'z' (replaced by 'x' or 'y' at the end)
1990
1991 @item A
1992 An address register: x, y or z
1993
1994 @item B
1995 An address register: x or y
1996
1997 @item D
1998 Register pair (x:d) to form a 32-bit value
1999
2000 @item L
2001 Constants in the range @minus{}65536 to 65535
2002
2003 @item M
2004 Constants whose 16-bit low part is zero
2005
2006 @item N
2007 Constant integer 1 or @minus{}1
2008
2009 @item O
2010 Constant integer 16
2011
2012 @item P
2013 Constants in the range @minus{}8 to 2
2014
2015 @end table
2016
2017 @need 1000
2018 @item SPARC---@file{sparc.h}
2019 @table @code
2020 @item f
2021 Floating-point register on the SPARC-V8 architecture and
2022 lower floating-point register on the SPARC-V9 architecture.
2023
2024 @item e
2025 Floating-point register. It is equivalent to @samp{f} on the
2026 SPARC-V8 architecture and contains both lower and upper
2027 floating-point registers on the SPARC-V9 architecture.
2028
2029 @item c
2030 Floating-point condition code register.
2031
2032 @item d
2033 Lower floating-point register. It is only valid on the SPARC-V9
2034 architecture when the Visual Instruction Set is available.
2035
2036 @item b
2037 Floating-point register. It is only valid on the SPARC-V9 architecture
2038 when the Visual Instruction Set is available.
2039
2040 @item h
2041 64-bit global or out register for the SPARC-V8+ architecture.
2042
2043 @item I
2044 Signed 13-bit constant
2045
2046 @item J
2047 Zero
2048
2049 @item K
2050 32-bit constant with the low 12 bits clear (a constant that can be
2051 loaded with the @code{sethi} instruction)
2052
2053 @item L
2054 A constant in the range supported by @code{movcc} instructions
2055
2056 @item M
2057 A constant in the range supported by @code{movrcc} instructions
2058
2059 @item N
2060 Same as @samp{K}, except that it verifies that bits that are not in the
2061 lower 32-bit range are all zero.  Must be used instead of @samp{K} for
2062 modes wider than @code{SImode}
2063
2064 @item O
2065 The constant 4096
2066
2067 @item G
2068 Floating-point zero
2069
2070 @item H
2071 Signed 13-bit constant, sign-extended to 32 or 64 bits
2072
2073 @item Q
2074 Floating-point constant whose integral representation can
2075 be moved into an integer register using a single sethi
2076 instruction
2077
2078 @item R
2079 Floating-point constant whose integral representation can
2080 be moved into an integer register using a single mov
2081 instruction
2082
2083 @item S
2084 Floating-point constant whose integral representation can
2085 be moved into an integer register using a high/lo_sum
2086 instruction sequence
2087
2088 @item T
2089 Memory address aligned to an 8-byte boundary
2090
2091 @item U
2092 Even register
2093
2094 @item W
2095 Memory address for @samp{e} constraint registers.
2096
2097 @end table
2098
2099 @item TMS320C3x/C4x---@file{c4x.h}
2100 @table @code
2101 @item a
2102 Auxiliary (address) register (ar0-ar7)
2103
2104 @item b
2105 Stack pointer register (sp)
2106
2107 @item c
2108 Standard (32-bit) precision integer register
2109
2110 @item f
2111 Extended (40-bit) precision register (r0-r11)
2112
2113 @item k
2114 Block count register (bk)
2115
2116 @item q
2117 Extended (40-bit) precision low register (r0-r7)
2118
2119 @item t
2120 Extended (40-bit) precision register (r0-r1)
2121
2122 @item u
2123 Extended (40-bit) precision register (r2-r3)
2124
2125 @item v
2126 Repeat count register (rc)
2127
2128 @item x
2129 Index register (ir0-ir1)
2130
2131 @item y
2132 Status (condition code) register (st)
2133
2134 @item z
2135 Data page register (dp)
2136
2137 @item G
2138 Floating-point zero
2139
2140 @item H
2141 Immediate 16-bit floating-point constant
2142
2143 @item I
2144 Signed 16-bit constant
2145
2146 @item J
2147 Signed 8-bit constant
2148
2149 @item K
2150 Signed 5-bit constant
2151
2152 @item L
2153 Unsigned 16-bit constant
2154
2155 @item M
2156 Unsigned 8-bit constant
2157
2158 @item N
2159 Ones complement of unsigned 16-bit constant
2160
2161 @item O
2162 High 16-bit constant (32-bit constant with 16 LSBs zero)
2163
2164 @item Q
2165 Indirect memory reference with signed 8-bit or index register displacement
2166
2167 @item R
2168 Indirect memory reference with unsigned 5-bit displacement
2169
2170 @item S
2171 Indirect memory reference with 1 bit or index register displacement
2172
2173 @item T
2174 Direct memory reference
2175
2176 @item U
2177 Symbolic address
2178
2179 @end table
2180
2181 @item S/390 and zSeries---@file{s390.h}
2182 @table @code
2183 @item a
2184 Address register (general purpose register except r0)
2185
2186 @item d
2187 Data register (arbitrary general purpose register)
2188
2189 @item f
2190 Floating-point register
2191
2192 @item I
2193 Unsigned 8-bit constant (0--255)
2194
2195 @item J
2196 Unsigned 12-bit constant (0--4095)
2197
2198 @item K
2199 Signed 16-bit constant (@minus{}32768--32767)
2200
2201 @item L
2202 Value appropriate as displacement.
2203 @table @code
2204        @item (0..4095)
2205        for short displacement
2206        @item (-524288..524287)
2207        for long displacement
2208 @end table
2209
2210 @item M
2211 Constant integer with a value of 0x7fffffff.
2212
2213 @item N
2214 Multiple letter constraint followed by 4 parameter letters.
2215 @table @code
2216          @item 0..9:
2217          number of the part counting from most to least significant
2218          @item H,Q:
2219          mode of the part
2220          @item D,S,H:
2221          mode of the containing operand
2222          @item 0,F:
2223          value of the other parts (F - all bits set)
2224 @end table
2225 The constraint matches if the specified part of a constant
2226 has a value different from it's other parts.
2227
2228 @item Q
2229 Memory reference without index register and with short displacement.
2230
2231 @item R
2232 Memory reference with index register and short displacement.
2233
2234 @item S
2235 Memory reference without index register but with long displacement.
2236
2237 @item T
2238 Memory reference with index register and long displacement.
2239
2240 @item U
2241 Pointer with short displacement.
2242
2243 @item W
2244 Pointer with long displacement.
2245
2246 @item Y
2247 Shift count operand.
2248
2249 @end table
2250
2251 @item Xstormy16---@file{stormy16.h}
2252 @table @code
2253 @item a
2254 Register r0.
2255
2256 @item b
2257 Register r1.
2258
2259 @item c
2260 Register r2.
2261
2262 @item d
2263 Register r8.
2264
2265 @item e
2266 Registers r0 through r7.
2267
2268 @item t
2269 Registers r0 and r1.
2270
2271 @item y
2272 The carry register.
2273
2274 @item z
2275 Registers r8 and r9.
2276
2277 @item I
2278 A constant between 0 and 3 inclusive.
2279
2280 @item J
2281 A constant that has exactly one bit set.
2282
2283 @item K
2284 A constant that has exactly one bit clear.
2285
2286 @item L
2287 A constant between 0 and 255 inclusive.
2288
2289 @item M
2290 A constant between @minus{}255 and 0 inclusive.
2291
2292 @item N
2293 A constant between @minus{}3 and 0 inclusive.
2294
2295 @item O
2296 A constant between 1 and 4 inclusive.
2297
2298 @item P
2299 A constant between @minus{}4 and @minus{}1 inclusive.
2300
2301 @item Q
2302 A memory reference that is a stack push.
2303
2304 @item R
2305 A memory reference that is a stack pop.
2306
2307 @item S
2308 A memory reference that refers to a constant address of known value.
2309
2310 @item T
2311 The register indicated by Rx (not implemented yet).
2312
2313 @item U
2314 A constant that is not between 2 and 15 inclusive.
2315
2316 @item Z
2317 The constant 0.
2318
2319 @end table
2320
2321 @item Xtensa---@file{xtensa.h}
2322 @table @code
2323 @item a
2324 General-purpose 32-bit register
2325
2326 @item b
2327 One-bit boolean register
2328
2329 @item A
2330 MAC16 40-bit accumulator register
2331
2332 @item I
2333 Signed 12-bit integer constant, for use in MOVI instructions
2334
2335 @item J
2336 Signed 8-bit integer constant, for use in ADDI instructions
2337
2338 @item K
2339 Integer constant valid for BccI instructions
2340
2341 @item L
2342 Unsigned constant valid for BccUI instructions
2343
2344 @end table
2345
2346 @end table
2347
2348 @ifset INTERNALS
2349 @node Standard Names
2350 @section Standard Pattern Names For Generation
2351 @cindex standard pattern names
2352 @cindex pattern names
2353 @cindex names, pattern
2354
2355 Here is a table of the instruction names that are meaningful in the RTL
2356 generation pass of the compiler.  Giving one of these names to an
2357 instruction pattern tells the RTL generation pass that it can use the
2358 pattern to accomplish a certain task.
2359
2360 @table @asis
2361 @cindex @code{mov@var{m}} instruction pattern
2362 @item @samp{mov@var{m}}
2363 Here @var{m} stands for a two-letter machine mode name, in lowercase.
2364 This instruction pattern moves data with that machine mode from operand
2365 1 to operand 0.  For example, @samp{movsi} moves full-word data.
2366
2367 If operand 0 is a @code{subreg} with mode @var{m} of a register whose
2368 own mode is wider than @var{m}, the effect of this instruction is
2369 to store the specified value in the part of the register that corresponds
2370 to mode @var{m}.  Bits outside of @var{m}, but which are within the
2371 same target word as the @code{subreg} are undefined.  Bits which are
2372 outside the target word are left unchanged.
2373
2374 This class of patterns is special in several ways.  First of all, each
2375 of these names up to and including full word size @emph{must} be defined,
2376 because there is no other way to copy a datum from one place to another.
2377 If there are patterns accepting operands in larger modes,
2378 @samp{mov@var{m}} must be defined for integer modes of those sizes.
2379
2380 Second, these patterns are not used solely in the RTL generation pass.
2381 Even the reload pass can generate move insns to copy values from stack
2382 slots into temporary registers.  When it does so, one of the operands is
2383 a hard register and the other is an operand that can need to be reloaded
2384 into a register.
2385
2386 @findex force_reg
2387 Therefore, when given such a pair of operands, the pattern must generate
2388 RTL which needs no reloading and needs no temporary registers---no
2389 registers other than the operands.  For example, if you support the
2390 pattern with a @code{define_expand}, then in such a case the
2391 @code{define_expand} mustn't call @code{force_reg} or any other such
2392 function which might generate new pseudo registers.
2393
2394 This requirement exists even for subword modes on a RISC machine where
2395 fetching those modes from memory normally requires several insns and
2396 some temporary registers.
2397
2398 @findex change_address
2399 During reload a memory reference with an invalid address may be passed
2400 as an operand.  Such an address will be replaced with a valid address
2401 later in the reload pass.  In this case, nothing may be done with the
2402 address except to use it as it stands.  If it is copied, it will not be
2403 replaced with a valid address.  No attempt should be made to make such
2404 an address into a valid address and no routine (such as
2405 @code{change_address}) that will do so may be called.  Note that
2406 @code{general_operand} will fail when applied to such an address.
2407
2408 @findex reload_in_progress
2409 The global variable @code{reload_in_progress} (which must be explicitly
2410 declared if required) can be used to determine whether such special
2411 handling is required.
2412
2413 The variety of operands that have reloads depends on the rest of the
2414 machine description, but typically on a RISC machine these can only be
2415 pseudo registers that did not get hard registers, while on other
2416 machines explicit memory references will get optional reloads.
2417
2418 If a scratch register is required to move an object to or from memory,
2419 it can be allocated using @code{gen_reg_rtx} prior to life analysis.
2420
2421 If there are cases which need scratch registers during or after reload,
2422 you must define @code{SECONDARY_INPUT_RELOAD_CLASS} and/or
2423 @code{SECONDARY_OUTPUT_RELOAD_CLASS} to detect them, and provide
2424 patterns @samp{reload_in@var{m}} or @samp{reload_out@var{m}} to handle
2425 them.  @xref{Register Classes}.
2426
2427 @findex no_new_pseudos
2428 The global variable @code{no_new_pseudos} can be used to determine if it
2429 is unsafe to create new pseudo registers.  If this variable is nonzero, then
2430 it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo.
2431
2432 The constraints on a @samp{mov@var{m}} must permit moving any hard
2433 register to any other hard register provided that
2434 @code{HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and
2435 @code{REGISTER_MOVE_COST} applied to their classes returns a value of 2.
2436
2437 It is obligatory to support floating point @samp{mov@var{m}}
2438 instructions into and out of any registers that can hold fixed point
2439 values, because unions and structures (which have modes @code{SImode} or
2440 @code{DImode}) can be in those registers and they may have floating
2441 point members.
2442
2443 There may also be a need to support fixed point @samp{mov@var{m}}
2444 instructions in and out of floating point registers.  Unfortunately, I
2445 have forgotten why this was so, and I don't know whether it is still
2446 true.  If @code{HARD_REGNO_MODE_OK} rejects fixed point values in
2447 floating point registers, then the constraints of the fixed point
2448 @samp{mov@var{m}} instructions must be designed to avoid ever trying to
2449 reload into a floating point register.
2450
2451 @cindex @code{reload_in} instruction pattern
2452 @cindex @code{reload_out} instruction pattern
2453 @item @samp{reload_in@var{m}}
2454 @itemx @samp{reload_out@var{m}}
2455 Like @samp{mov@var{m}}, but used when a scratch register is required to
2456 move between operand 0 and operand 1.  Operand 2 describes the scratch
2457 register.  See the discussion of the @code{SECONDARY_RELOAD_CLASS}
2458 macro in @pxref{Register Classes}.
2459
2460 There are special restrictions on the form of the @code{match_operand}s
2461 used in these patterns.  First, only the predicate for the reload
2462 operand is examined, i.e., @code{reload_in} examines operand 1, but not
2463 the predicates for operand 0 or 2.  Second, there may be only one
2464 alternative in the constraints.  Third, only a single register class
2465 letter may be used for the constraint; subsequent constraint letters
2466 are ignored.  As a special exception, an empty constraint string
2467 matches the @code{ALL_REGS} register class.  This may relieve ports
2468 of the burden of defining an @code{ALL_REGS} constraint letter just
2469 for these patterns.
2470
2471 @cindex @code{movstrict@var{m}} instruction pattern
2472 @item @samp{movstrict@var{m}}
2473 Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg}
2474 with mode @var{m} of a register whose natural mode is wider,
2475 the @samp{movstrict@var{m}} instruction is guaranteed not to alter
2476 any of the register except the part which belongs to mode @var{m}.
2477
2478 @cindex @code{load_multiple} instruction pattern
2479 @item @samp{load_multiple}
2480 Load several consecutive memory locations into consecutive registers.
2481 Operand 0 is the first of the consecutive registers, operand 1
2482 is the first memory location, and operand 2 is a constant: the
2483 number of consecutive registers.
2484
2485 Define this only if the target machine really has such an instruction;
2486 do not define this if the most efficient way of loading consecutive
2487 registers from memory is to do them one at a time.
2488
2489 On some machines, there are restrictions as to which consecutive
2490 registers can be stored into memory, such as particular starting or
2491 ending register numbers or only a range of valid counts.  For those
2492 machines, use a @code{define_expand} (@pxref{Expander Definitions})
2493 and make the pattern fail if the restrictions are not met.
2494
2495 Write the generated insn as a @code{parallel} with elements being a
2496 @code{set} of one register from the appropriate memory location (you may
2497 also need @code{use} or @code{clobber} elements).  Use a
2498 @code{match_parallel} (@pxref{RTL Template}) to recognize the insn.  See
2499 @file{rs6000.md} for examples of the use of this insn pattern.
2500
2501 @cindex @samp{store_multiple} instruction pattern
2502 @item @samp{store_multiple}
2503 Similar to @samp{load_multiple}, but store several consecutive registers
2504 into consecutive memory locations.  Operand 0 is the first of the
2505 consecutive memory locations, operand 1 is the first register, and
2506 operand 2 is a constant: the number of consecutive registers.
2507
2508 @cindex @code{push@var{m}} instruction pattern
2509 @item @samp{push@var{m}}
2510 Output a push instruction.  Operand 0 is value to push.  Used only when
2511 @code{PUSH_ROUNDING} is defined.  For historical reason, this pattern may be
2512 missing and in such case an @code{mov} expander is used instead, with a
2513 @code{MEM} expression forming the push operation.  The @code{mov} expander
2514 method is deprecated.
2515
2516 @cindex @code{add@var{m}3} instruction pattern
2517 @item @samp{add@var{m}3}
2518 Add operand 2 and operand 1, storing the result in operand 0.  All operands
2519 must have mode @var{m}.  This can be used even on two-address machines, by
2520 means of constraints requiring operands 1 and 0 to be the same location.
2521
2522 @cindex @code{sub@var{m}3} instruction pattern
2523 @cindex @code{mul@var{m}3} instruction pattern
2524 @cindex @code{div@var{m}3} instruction pattern
2525 @cindex @code{udiv@var{m}3} instruction pattern
2526 @cindex @code{mod@var{m}3} instruction pattern
2527 @cindex @code{umod@var{m}3} instruction pattern
2528 @cindex @code{smin@var{m}3} instruction pattern
2529 @cindex @code{smax@var{m}3} instruction pattern
2530 @cindex @code{umin@var{m}3} instruction pattern
2531 @cindex @code{umax@var{m}3} instruction pattern
2532 @cindex @code{and@var{m}3} instruction pattern
2533 @cindex @code{ior@var{m}3} instruction pattern
2534 @cindex @code{xor@var{m}3} instruction pattern
2535 @item @samp{sub@var{m}3}, @samp{mul@var{m}3}
2536 @itemx @samp{div@var{m}3}, @samp{udiv@var{m}3}, @samp{mod@var{m}3}, @samp{umod@var{m}3}
2537 @itemx @samp{smin@var{m}3}, @samp{smax@var{m}3}, @samp{umin@var{m}3}, @samp{umax@var{m}3}
2538 @itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3}
2539 Similar, for other arithmetic operations.
2540 @cindex @code{min@var{m}3} instruction pattern
2541 @cindex @code{max@var{m}3} instruction pattern
2542 @itemx @samp{min@var{m}3}, @samp{max@var{m}3}
2543 Floating point min and max operations.  If both operands are zeros,
2544 or if either operand is NaN, then it is unspecified which of the two
2545 operands is returned as the result.
2546
2547
2548 @cindex @code{mulhisi3} instruction pattern
2549 @item @samp{mulhisi3}
2550 Multiply operands 1 and 2, which have mode @code{HImode}, and store
2551 a @code{SImode} product in operand 0.
2552
2553 @cindex @code{mulqihi3} instruction pattern
2554 @cindex @code{mulsidi3} instruction pattern
2555 @item @samp{mulqihi3}, @samp{mulsidi3}
2556 Similar widening-multiplication instructions of other widths.
2557
2558 @cindex @code{umulqihi3} instruction pattern
2559 @cindex @code{umulhisi3} instruction pattern
2560 @cindex @code{umulsidi3} instruction pattern
2561 @item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
2562 Similar widening-multiplication instructions that do unsigned
2563 multiplication.
2564
2565 @cindex @code{smul@var{m}3_highpart} instruction pattern
2566 @item @samp{smul@var{m}3_highpart}
2567 Perform a signed multiplication of operands 1 and 2, which have mode
2568 @var{m}, and store the most significant half of the product in operand 0.
2569 The least significant half of the product is discarded.
2570
2571 @cindex @code{umul@var{m}3_highpart} instruction pattern
2572 @item @samp{umul@var{m}3_highpart}
2573 Similar, but the multiplication is unsigned.
2574
2575 @cindex @code{divmod@var{m}4} instruction pattern
2576 @item @samp{divmod@var{m}4}
2577 Signed division that produces both a quotient and a remainder.
2578 Operand 1 is divided by operand 2 to produce a quotient stored
2579 in operand 0 and a remainder stored in operand 3.
2580
2581 For machines with an instruction that produces both a quotient and a
2582 remainder, provide a pattern for @samp{divmod@var{m}4} but do not
2583 provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}.  This
2584 allows optimization in the relatively common case when both the quotient
2585 and remainder are computed.
2586
2587 If an instruction that just produces a quotient or just a remainder
2588 exists and is more efficient than the instruction that produces both,
2589 write the output routine of @samp{divmod@var{m}4} to call
2590 @code{find_reg_note} and look for a @code{REG_UNUSED} note on the
2591 quotient or remainder and generate the appropriate instruction.
2592
2593 @cindex @code{udivmod@var{m}4} instruction pattern
2594 @item @samp{udivmod@var{m}4}
2595 Similar, but does unsigned division.
2596
2597 @cindex @code{ashl@var{m}3} instruction pattern
2598 @item @samp{ashl@var{m}3}
2599 Arithmetic-shift operand 1 left by a number of bits specified by operand
2600 2, and store the result in operand 0.  Here @var{m} is the mode of
2601 operand 0 and operand 1; operand 2's mode is specified by the
2602 instruction pattern, and the compiler will convert the operand to that
2603 mode before generating the instruction.
2604
2605 @cindex @code{ashr@var{m}3} instruction pattern
2606 @cindex @code{lshr@var{m}3} instruction pattern
2607 @cindex @code{rotl@var{m}3} instruction pattern
2608 @cindex @code{rotr@var{m}3} instruction pattern
2609 @item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3}
2610 Other shift and rotate instructions, analogous to the
2611 @code{ashl@var{m}3} instructions.
2612
2613 @cindex @code{neg@var{m}2} instruction pattern
2614 @item @samp{neg@var{m}2}
2615 Negate operand 1 and store the result in operand 0.
2616
2617 @cindex @code{abs@var{m}2} instruction pattern
2618 @item @samp{abs@var{m}2}
2619 Store the absolute value of operand 1 into operand 0.
2620
2621 @cindex @code{sqrt@var{m}2} instruction pattern
2622 @item @samp{sqrt@var{m}2}
2623 Store the square root of operand 1 into operand 0.
2624
2625 The @code{sqrt} built-in function of C always uses the mode which
2626 corresponds to the C data type @code{double} and the @code{sqrtf}
2627 built-in function uses the mode which corresponds to the C data
2628 type @code{float}.
2629
2630 @cindex @code{cos@var{m}2} instruction pattern
2631 @item @samp{cos@var{m}2}
2632 Store the cosine of operand 1 into operand 0.
2633
2634 The @code{cos} built-in function of C always uses the mode which
2635 corresponds to the C data type @code{double} and the @code{cosf}
2636 built-in function uses the mode which corresponds to the C data
2637 type @code{float}.
2638
2639 @cindex @code{sin@var{m}2} instruction pattern
2640 @item @samp{sin@var{m}2}
2641 Store the sine of operand 1 into operand 0.
2642
2643 The @code{sin} built-in function of C always uses the mode which
2644 corresponds to the C data type @code{double} and the @code{sinf}
2645 built-in function uses the mode which corresponds to the C data
2646 type @code{float}.
2647
2648 @cindex @code{exp@var{m}2} instruction pattern
2649 @item @samp{exp@var{m}2}
2650 Store the exponential of operand 1 into operand 0.
2651
2652 The @code{exp} built-in function of C always uses the mode which
2653 corresponds to the C data type @code{double} and the @code{expf}
2654 built-in function uses the mode which corresponds to the C data
2655 type @code{float}.
2656
2657 @cindex @code{log@var{m}2} instruction pattern
2658 @item @samp{log@var{m}2}
2659 Store the natural logarithm of operand 1 into operand 0.
2660
2661 The @code{log} built-in function of C always uses the mode which
2662 corresponds to the C data type @code{double} and the @code{logf}
2663 built-in function uses the mode which corresponds to the C data
2664 type @code{float}.
2665
2666 @cindex @code{pow@var{m}3} instruction pattern
2667 @item @samp{pow@var{m}3}
2668 Store the value of operand 1 raised to the exponent operand 2
2669 into operand 0.
2670
2671 The @code{pow} built-in function of C always uses the mode which
2672 corresponds to the C data type @code{double} and the @code{powf}
2673 built-in function uses the mode which corresponds to the C data
2674 type @code{float}.
2675
2676 @cindex @code{atan2@var{m}3} instruction pattern
2677 @item @samp{atan2@var{m}3}
2678 Store the arc tangent (inverse tangent) of operand 1 divided by
2679 operand 2 into operand 0, using the signs of both arguments to
2680 determine the quadrant of the result.
2681
2682 The @code{atan2} built-in function of C always uses the mode which
2683 corresponds to the C data type @code{double} and the @code{atan2f}
2684 built-in function uses the mode which corresponds to the C data
2685 type @code{float}.
2686
2687 @cindex @code{floor@var{m}2} instruction pattern
2688 @item @samp{floor@var{m}2}
2689 Store the largest integral value not greater than argument.
2690
2691 The @code{floor} built-in function of C always uses the mode which
2692 corresponds to the C data type @code{double} and the @code{floorf}
2693 built-in function uses the mode which corresponds to the C data
2694 type @code{float}.
2695
2696 @cindex @code{trunc@var{m}2} instruction pattern
2697 @item @samp{trunc@var{m}2}
2698 Store the argument rounded to integer towards zero.
2699
2700 The @code{trunc} built-in function of C always uses the mode which
2701 corresponds to the C data type @code{double} and the @code{truncf}
2702 built-in function uses the mode which corresponds to the C data
2703 type @code{float}.
2704
2705 @cindex @code{round@var{m}2} instruction pattern
2706 @item @samp{round@var{m}2}
2707 Store the argument rounded to integer away from zero.
2708
2709 The @code{round} built-in function of C always uses the mode which
2710 corresponds to the C data type @code{double} and the @code{roundf}
2711 built-in function uses the mode which corresponds to the C data
2712 type @code{float}.
2713
2714 @cindex @code{ceil@var{m}2} instruction pattern
2715 @item @samp{ceil@var{m}2}
2716 Store the argument rounded to integer away from zero.
2717
2718 The @code{ceil} built-in function of C always uses the mode which
2719 corresponds to the C data type @code{double} and the @code{ceilf}
2720 built-in function uses the mode which corresponds to the C data
2721 type @code{float}.
2722
2723 @cindex @code{nearbyint@var{m}2} instruction pattern
2724 @item @samp{nearbyint@var{m}2}
2725 Store the argument rounded according to the default rounding mode
2726
2727 The @code{nearbyint} built-in function of C always uses the mode which
2728 corresponds to the C data type @code{double} and the @code{nearbyintf}
2729 built-in function uses the mode which corresponds to the C data
2730 type @code{float}.
2731
2732 @cindex @code{ffs@var{m}2} instruction pattern
2733 @item @samp{ffs@var{m}2}
2734 Store into operand 0 one plus the index of the least significant 1-bit
2735 of operand 1.  If operand 1 is zero, store zero.  @var{m} is the mode
2736 of operand 0; operand 1's mode is specified by the instruction
2737 pattern, and the compiler will convert the operand to that mode before
2738 generating the instruction.
2739
2740 The @code{ffs} built-in function of C always uses the mode which
2741 corresponds to the C data type @code{int}.
2742
2743 @cindex @code{clz@var{m}2} instruction pattern
2744 @item @samp{clz@var{m}2}
2745 Store into operand 0 the number of leading 0-bits in @var{x}, starting
2746 at the most significant bit position.  If @var{x} is 0, the result is
2747 undefined.  @var{m} is the mode of operand 0; operand 1's mode is
2748 specified by the instruction pattern, and the compiler will convert the
2749 operand to that mode before generating the instruction.
2750
2751 @cindex @code{ctz@var{m}2} instruction pattern
2752 @item @samp{ctz@var{m}2}
2753 Store into operand 0 the number of trailing 0-bits in @var{x}, starting
2754 at the least significant bit position.  If @var{x} is 0, the result is
2755 undefined.  @var{m} is the mode of operand 0; operand 1's mode is
2756 specified by the instruction pattern, and the compiler will convert the
2757 operand to that mode before generating the instruction.
2758
2759 @cindex @code{popcount@var{m}2} instruction pattern
2760 @item @samp{popcount@var{m}2}
2761 Store into operand 0 the number of 1-bits in @var{x}.  @var{m} is the
2762 mode of operand 0; operand 1's mode is specified by the instruction
2763 pattern, and the compiler will convert the operand to that mode before
2764 generating the instruction.
2765
2766 @cindex @code{parity@var{m}2} instruction pattern
2767 @item @samp{parity@var{m}2}
2768 Store into operand 0 the parity of @var{x}, i.@:e. the number of 1-bits
2769 in @var{x} modulo 2.  @var{m} is the mode of operand 0; operand 1's mode
2770 is specified by the instruction pattern, and the compiler will convert
2771 the operand to that mode before generating the instruction.
2772
2773 @cindex @code{one_cmpl@var{m}2} instruction pattern
2774 @item @samp{one_cmpl@var{m}2}
2775 Store the bitwise-complement of operand 1 into operand 0.
2776
2777 @cindex @code{cmp@var{m}} instruction pattern
2778 @item @samp{cmp@var{m}}
2779 Compare operand 0 and operand 1, and set the condition codes.
2780 The RTL pattern should look like this:
2781
2782 @smallexample
2783 (set (cc0) (compare (match_operand:@var{m} 0 @dots{})
2784                     (match_operand:@var{m} 1 @dots{})))
2785 @end smallexample
2786
2787 @cindex @code{tst@var{m}} instruction pattern
2788 @item @samp{tst@var{m}}
2789 Compare operand 0 against zero, and set the condition codes.
2790 The RTL pattern should look like this:
2791
2792 @smallexample
2793 (set (cc0) (match_operand:@var{m} 0 @dots{}))
2794 @end smallexample
2795
2796 @samp{tst@var{m}} patterns should not be defined for machines that do
2797 not use @code{(cc0)}.  Doing so would confuse the optimizer since it
2798 would no longer be clear which @code{set} operations were comparisons.
2799 The @samp{cmp@var{m}} patterns should be used instead.
2800
2801 @cindex @code{movstr@var{m}} instruction pattern
2802 @item @samp{movstr@var{m}}
2803 Block move instruction.  The addresses of the destination and source
2804 strings are the first two operands, and both are in mode @code{Pmode}.
2805
2806 The number of bytes to move is the third operand, in mode @var{m}.
2807 Usually, you specify @code{word_mode} for @var{m}.  However, if you can
2808 generate better code knowing the range of valid lengths is smaller than
2809 those representable in a full word, you should provide a pattern with a
2810 mode corresponding to the range of values you can handle efficiently
2811 (e.g., @code{QImode} for values in the range 0--127; note we avoid numbers
2812 that appear negative) and also a pattern with @code{word_mode}.
2813
2814 The fourth operand is the known shared alignment of the source and
2815 destination, in the form of a @code{const_int} rtx.  Thus, if the
2816 compiler knows that both source and destination are word-aligned,
2817 it may provide the value 4 for this operand.
2818
2819 Descriptions of multiple @code{movstr@var{m}} patterns can only be
2820 beneficial if the patterns for smaller modes have fewer restrictions
2821 on their first, second and fourth operands.  Note that the mode @var{m}
2822 in @code{movstr@var{m}} does not impose any restriction on the mode of
2823 individually moved data units in the block.
2824
2825 These patterns need not give special consideration to the possibility
2826 that the source and destination strings might overlap.
2827
2828 @cindex @code{clrstr@var{m}} instruction pattern
2829 @item @samp{clrstr@var{m}}
2830 Block clear instruction.  The addresses of the destination string is the
2831 first operand, in mode @code{Pmode}.  The number of bytes to clear is
2832 the second operand, in mode @var{m}.  See @samp{movstr@var{m}} for
2833 a discussion of the choice of mode.
2834
2835 The third operand is the known alignment of the destination, in the form
2836 of a @code{const_int} rtx.  Thus, if the compiler knows that the
2837 destination is word-aligned, it may provide the value 4 for this
2838 operand.
2839
2840 The use for multiple @code{clrstr@var{m}} is as for @code{movstr@var{m}}.
2841
2842 @cindex @code{cmpstr@var{m}} instruction pattern
2843 @item @samp{cmpstr@var{m}}
2844 String compare instruction, with five operands.  Operand 0 is the output;
2845 it has mode @var{m}.  The remaining four operands are like the operands
2846 of @samp{movstr@var{m}}.  The two memory blocks specified are compared
2847 byte by byte in lexicographic order starting at the beginning of each
2848 string.  The instruction is not allowed to prefetch more than one byte
2849 at a time since either string may end in the first byte and reading past
2850 that may access an invalid page or segment and cause a fault.  The
2851 effect of the instruction is to store a value in operand 0 whose sign
2852 indicates the result of the comparison.
2853
2854 @cindex @code{cmpmem@var{m}} instruction pattern
2855 @item @samp{cmpmem@var{m}}
2856 Block compare instruction, with five operands like the operands
2857 of @samp{cmpstr@var{m}}.  The two memory blocks specified are compared
2858 byte by byte in lexicographic order starting at the beginning of each
2859 block.  Unlike @samp{cmpstr@var{m}} the instruction can prefetch
2860 any bytes in the two memory blocks.  The effect of the instruction is
2861 to store a value in operand 0 whose sign indicates the result of the
2862 comparison.
2863
2864 @cindex @code{strlen@var{m}} instruction pattern
2865 @item @samp{strlen@var{m}}
2866 Compute the length of a string, with three operands.
2867 Operand 0 is the result (of mode @var{m}), operand 1 is
2868 a @code{mem} referring to the first character of the string,
2869 operand 2 is the character to search for (normally zero),
2870 and operand 3 is a constant describing the known alignment
2871 of the beginning of the string.
2872
2873 @cindex @code{float@var{mn}2} instruction pattern
2874 @item @samp{float@var{m}@var{n}2}
2875 Convert signed integer operand 1 (valid for fixed point mode @var{m}) to
2876 floating point mode @var{n} and store in operand 0 (which has mode
2877 @var{n}).
2878
2879 @cindex @code{floatuns@var{mn}2} instruction pattern
2880 @item @samp{floatuns@var{m}@var{n}2}
2881 Convert unsigned integer operand 1 (valid for fixed point mode @var{m})
2882 to floating point mode @var{n} and store in operand 0 (which has mode
2883 @var{n}).
2884
2885 @cindex @code{fix@var{mn}2} instruction pattern
2886 @item @samp{fix@var{m}@var{n}2}
2887 Convert operand 1 (valid for floating point mode @var{m}) to fixed
2888 point mode @var{n} as a signed number and store in operand 0 (which
2889 has mode @var{n}).  This instruction's result is defined only when
2890 the value of operand 1 is an integer.
2891
2892 @cindex @code{fixuns@var{mn}2} instruction pattern
2893 @item @samp{fixuns@var{m}@var{n}2}
2894 Convert operand 1 (valid for floating point mode @var{m}) to fixed
2895 point mode @var{n} as an unsigned number and store in operand 0 (which
2896 has mode @var{n}).  This instruction's result is defined only when the
2897 value of operand 1 is an integer.
2898
2899 @cindex @code{ftrunc@var{m}2} instruction pattern
2900 @item @samp{ftrunc@var{m}2}
2901 Convert operand 1 (valid for floating point mode @var{m}) to an
2902 integer value, still represented in floating point mode @var{m}, and
2903 store it in operand 0 (valid for floating point mode @var{m}).
2904
2905 @cindex @code{fix_trunc@var{mn}2} instruction pattern
2906 @item @samp{fix_trunc@var{m}@var{n}2}
2907 Like @samp{fix@var{m}@var{n}2} but works for any floating point value
2908 of mode @var{m} by converting the value to an integer.
2909
2910 @cindex @code{fixuns_trunc@var{mn}2} instruction pattern
2911 @item @samp{fixuns_trunc@var{m}@var{n}2}
2912 Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
2913 value of mode @var{m} by converting the value to an integer.
2914
2915 @cindex @code{trunc@var{mn}2} instruction pattern
2916 @item @samp{trunc@var{m}@var{n}2}
2917 Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
2918 store in operand 0 (which has mode @var{n}).  Both modes must be fixed
2919 point or both floating point.
2920
2921 @cindex @code{extend@var{mn}2} instruction pattern
2922 @item @samp{extend@var{m}@var{n}2}
2923 Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
2924 store in operand 0 (which has mode @var{n}).  Both modes must be fixed
2925 point or both floating point.
2926
2927 @cindex @code{zero_extend@var{mn}2} instruction pattern
2928 @item @samp{zero_extend@var{m}@var{n}2}
2929 Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
2930 store in operand 0 (which has mode @var{n}).  Both modes must be fixed
2931 point.
2932
2933 @cindex @code{extv} instruction pattern
2934 @item @samp{extv}
2935 Extract a bit-field from operand 1 (a register or memory operand), where
2936 operand 2 specifies the width in bits and operand 3 the starting bit,
2937 and store it in operand 0.  Operand 0 must have mode @code{word_mode}.
2938 Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often
2939 @code{word_mode} is allowed only for registers.  Operands 2 and 3 must
2940 be valid for @code{word_mode}.
2941
2942 The RTL generation pass generates this instruction only with constants
2943 for operands 2 and 3.
2944
2945 The bit-field value is sign-extended to a full word integer
2946 before it is stored in operand 0.
2947
2948 @cindex @code{extzv} instruction pattern
2949 @item @samp{extzv}
2950 Like @samp{extv} except that the bit-field value is zero-extended.
2951
2952 @cindex @code{insv} instruction pattern
2953 @item @samp{insv}
2954 Store operand 3 (which must be valid for @code{word_mode}) into a
2955 bit-field in operand 0, where operand 1 specifies the width in bits and
2956 operand 2 the starting bit.  Operand 0 may have mode @code{byte_mode} or
2957 @code{word_mode}; often @code{word_mode} is allowed only for registers.
2958 Operands 1 and 2 must be valid for @code{word_mode}.
2959
2960 The RTL generation pass generates this instruction only with constants
2961 for operands 1 and 2.
2962
2963 @cindex @code{mov@var{mode}cc} instruction pattern
2964 @item @samp{mov@var{mode}cc}
2965 Conditionally move operand 2 or operand 3 into operand 0 according to the
2966 comparison in operand 1.  If the comparison is true, operand 2 is moved
2967 into operand 0, otherwise operand 3 is moved.
2968
2969 The mode of the operands being compared need not be the same as the operands
2970 being moved.  Some machines, sparc64 for example, have instructions that
2971 conditionally move an integer value based on the floating point condition
2972 codes and vice versa.
2973
2974 If the machine does not have conditional move instructions, do not
2975 define these patterns.
2976
2977 @cindex @code{add@var{mode}cc} instruction pattern
2978 @item @samp{add@var{mode}cc}
2979 Similar to @samp{mov@var{mode}cc} but for conditional addition.  Conditionally
2980 move operand 2 or (operands 2 + operand 3) into operand 0 according to the
2981 comparison in operand 1.  If the comparison is true, operand 2 is moved into
2982 operand 0, otherwise (operand 2 + operand 3) is moved.
2983
2984 @cindex @code{s@var{cond}} instruction pattern
2985 @item @samp{s@var{cond}}
2986 Store zero or nonzero in the operand according to the condition codes.
2987 Value stored is nonzero iff the condition @var{cond} is true.
2988 @var{cond} is the name of a comparison operation expression code, such
2989 as @code{eq}, @code{lt} or @code{leu}.
2990
2991 You specify the mode that the operand must have when you write the
2992 @code{match_operand} expression.  The compiler automatically sees
2993 which mode you have used and supplies an operand of that mode.
2994
2995 The value stored for a true condition must have 1 as its low bit, or
2996 else must be negative.  Otherwise the instruction is not suitable and
2997 you should omit it from the machine description.  You describe to the
2998 compiler exactly which value is stored by defining the macro
2999 @code{STORE_FLAG_VALUE} (@pxref{Misc}).  If a description cannot be
3000 found that can be used for all the @samp{s@var{cond}} patterns, you
3001 should omit those operations from the machine description.
3002
3003 These operations may fail, but should do so only in relatively
3004 uncommon cases; if they would fail for common cases involving
3005 integer comparisons, it is best to omit these patterns.
3006
3007 If these operations are omitted, the compiler will usually generate code
3008 that copies the constant one to the target and branches around an
3009 assignment of zero to the target.  If this code is more efficient than
3010 the potential instructions used for the @samp{s@var{cond}} pattern
3011 followed by those required to convert the result into a 1 or a zero in
3012 @code{SImode}, you should omit the @samp{s@var{cond}} operations from
3013 the machine description.
3014
3015 @cindex @code{b@var{cond}} instruction pattern
3016 @item @samp{b@var{cond}}
3017 Conditional branch instruction.  Operand 0 is a @code{label_ref} that
3018 refers to the label to jump to.  Jump if the condition codes meet
3019 condition @var{cond}.
3020
3021 Some machines do not follow the model assumed here where a comparison
3022 instruction is followed by a conditional branch instruction.  In that
3023 case, the @samp{cmp@var{m}} (and @samp{tst@var{m}}) patterns should
3024 simply store the operands away and generate all the required insns in a
3025 @code{define_expand} (@pxref{Expander Definitions}) for the conditional
3026 branch operations.  All calls to expand @samp{b@var{cond}} patterns are
3027 immediately preceded by calls to expand either a @samp{cmp@var{m}}
3028 pattern or a @samp{tst@var{m}} pattern.
3029
3030 Machines that use a pseudo register for the condition code value, or
3031 where the mode used for the comparison depends on the condition being
3032 tested, should also use the above mechanism.  @xref{Jump Patterns}.
3033
3034 The above discussion also applies to the @samp{mov@var{mode}cc} and
3035 @samp{s@var{cond}} patterns.
3036
3037 @cindex @code{jump} instruction pattern
3038 @item @samp{jump}
3039 A jump inside a function; an unconditional branch.  Operand 0 is the
3040 @code{label_ref} of the label to jump to.  This pattern name is mandatory
3041 on all machines.
3042
3043 @cindex @code{call} instruction pattern
3044 @item @samp{call}
3045 Subroutine call instruction returning no value.  Operand 0 is the
3046 function to call; operand 1 is the number of bytes of arguments pushed
3047 as a @code{const_int}; operand 2 is the number of registers used as
3048 operands.
3049
3050 On most machines, operand 2 is not actually stored into the RTL
3051 pattern.  It is supplied for the sake of some RISC machines which need
3052 to put this information into the assembler code; they can put it in
3053 the RTL instead of operand 1.
3054
3055 Operand 0 should be a @code{mem} RTX whose address is the address of the
3056 function.  Note, however, that this address can be a @code{symbol_ref}
3057 expression even if it would not be a legitimate memory address on the
3058 target machine.  If it is also not a valid argument for a call
3059 instruction, the pattern for this operation should be a
3060 @code{define_expand} (@pxref{Expander Definitions}) that places the
3061 address into a register and uses that register in the call instruction.
3062
3063 @cindex @code{call_value} instruction pattern
3064 @item @samp{call_value}
3065 Subroutine call instruction returning a value.  Operand 0 is the hard
3066 register in which the value is returned.  There are three more
3067 operands, the same as the three operands of the @samp{call}
3068 instruction (but with numbers increased by one).
3069
3070 Subroutines that return @code{BLKmode} objects use the @samp{call}
3071 insn.
3072
3073 @cindex @code{call_pop} instruction pattern
3074 @cindex @code{call_value_pop} instruction pattern
3075 @item @samp{call_pop}, @samp{call_value_pop}
3076 Similar to @samp{call} and @samp{call_value}, except used if defined and
3077 if @code{RETURN_POPS_ARGS} is nonzero.  They should emit a @code{parallel}
3078 that contains both the function call and a @code{set} to indicate the
3079 adjustment made to the frame pointer.
3080
3081 For machines where @code{RETURN_POPS_ARGS} can be nonzero, the use of these
3082 patterns increases the number of functions for which the frame pointer
3083 can be eliminated, if desired.
3084
3085 @cindex @code{untyped_call} instruction pattern
3086 @item @samp{untyped_call}
3087 Subroutine call instruction returning a value of any type.  Operand 0 is
3088 the function to call; operand 1 is a memory location where the result of
3089 calling the function is to be stored; operand 2 is a @code{parallel}
3090 expression where each element is a @code{set} expression that indicates
3091 the saving of a function return value into the result block.
3092
3093 This instruction pattern should be defined to support
3094 @code{__builtin_apply} on machines where special instructions are needed
3095 to call a subroutine with arbitrary arguments or to save the value
3096 returned.  This instruction pattern is required on machines that have
3097 multiple registers that can hold a return value
3098 (i.e.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register).
3099
3100 @cindex @code{return} instruction pattern
3101 @item @samp{return}
3102 Subroutine return instruction.  This instruction pattern name should be
3103 defined only if a single instruction can do all the work of returning
3104 from a function.
3105
3106 Like the @samp{mov@var{m}} patterns, this pattern is also used after the
3107 RTL generation phase.  In this case it is to support machines where
3108 multiple instructions are usually needed to return from a function, but
3109 some class of functions only requires one instruction to implement a
3110 return.  Normally, the applicable functions are those which do not need
3111 to save any registers or allocate stack space.
3112
3113 @findex reload_completed
3114 @findex leaf_function_p
3115 For such machines, the condition specified in this pattern should only
3116 be true when @code{reload_completed} is nonzero and the function's
3117 epilogue would only be a single instruction.  For machines with register
3118 windows, the routine @code{leaf_function_p} may be used to determine if
3119 a register window push is required.
3120
3121 Machines that have conditional return instructions should define patterns
3122 such as
3123
3124 @smallexample
3125 (define_insn ""
3126   [(set (pc)
3127         (if_then_else (match_operator
3128                          0 "comparison_operator"
3129                          [(cc0) (const_int 0)])
3130                       (return)
3131                       (pc)))]
3132   "@var{condition}"
3133   "@dots{}")
3134 @end smallexample
3135
3136 where @var{condition} would normally be the same condition specified on the
3137 named @samp{return} pattern.
3138
3139 @cindex @code{untyped_return} instruction pattern
3140 @item @samp{untyped_return}
3141 Untyped subroutine return instruction.  This instruction pattern should
3142 be defined to support @code{__builtin_return} on machines where special
3143 instructions are needed to return a value of any type.
3144
3145 Operand 0 is a memory location where the result of calling a function
3146 with @code{__builtin_apply} is stored; operand 1 is a @code{parallel}
3147 expression where each element is a @code{set} expression that indicates
3148 the restoring of a function return value from the result block.
3149
3150 @cindex @code{nop} instruction pattern
3151 @item @samp{nop}
3152 No-op instruction.  This instruction pattern name should always be defined
3153 to output a no-op in assembler code.  @code{(const_int 0)} will do as an
3154 RTL pattern.
3155
3156 @cindex @code{indirect_jump} instruction pattern
3157 @item @samp{indirect_jump}
3158 An instruction to jump to an address which is operand zero.
3159 This pattern name is mandatory on all machines.
3160
3161 @cindex @code{casesi} instruction pattern
3162 @item @samp{casesi}
3163 Instruction to jump through a dispatch table, including bounds checking.
3164 This instruction takes five operands:
3165
3166 @enumerate
3167 @item
3168 The index to dispatch on, which has mode @code{SImode}.
3169
3170 @item
3171 The lower bound for indices in the table, an integer constant.
3172
3173 @item
3174 The total range of indices in the table---the largest index
3175 minus the smallest one (both inclusive).
3176
3177 @item
3178 A label that precedes the table itself.
3179
3180 @item
3181 A label to jump to if the index has a value outside the bounds.
3182 (If the machine-description macro @code{CASE_DROPS_THROUGH} is defined,
3183 then an out-of-bounds index drops through to the code following
3184 the jump table instead of jumping to this label.  In that case,
3185 this label is not actually used by the @samp{casesi} instruction,
3186 but it is always provided as an operand.)
3187 @end enumerate
3188
3189 The table is a @code{addr_vec} or @code{addr_diff_vec} inside of a
3190 @code{jump_insn}.  The number of elements in the table is one plus the
3191 difference between the upper bound and the lower bound.
3192
3193 @cindex @code{tablejump} instruction pattern
3194 @item @samp{tablejump}
3195 Instruction to jump to a variable address.  This is a low-level
3196 capability which can be used to implement a dispatch table when there
3197 is no @samp{casesi} pattern.
3198
3199 This pattern requires two operands: the address or offset, and a label
3200 which should immediately precede the jump table.  If the macro
3201 @code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first
3202 operand is an offset which counts from the address of the table; otherwise,
3203 it is an absolute address to jump to.  In either case, the first operand has
3204 mode @code{Pmode}.
3205
3206 The @samp{tablejump} insn is always the last insn before the jump
3207 table it uses.  Its assembler code normally has no need to use the
3208 second operand, but you should incorporate it in the RTL pattern so
3209 that the jump optimizer will not delete the table as unreachable code.
3210
3211
3212 @cindex @code{decrement_and_branch_until_zero} instruction pattern
3213 @item @samp{decrement_and_branch_until_zero}
3214 Conditional branch instruction that decrements a register and
3215 jumps if the register is nonzero.  Operand 0 is the register to
3216 decrement and test; operand 1 is the label to jump to if the
3217 register is nonzero.  @xref{Looping Patterns}.
3218
3219 This optional instruction pattern is only used by the combiner,
3220 typically for loops reversed by the loop optimizer when strength
3221 reduction is enabled.
3222
3223 @cindex @code{doloop_end} instruction pattern
3224 @item @samp{doloop_end}
3225 Conditional branch instruction that decrements a register and jumps if
3226 the register is nonzero.  This instruction takes five operands: Operand
3227 0 is the register to decrement and test; operand 1 is the number of loop
3228 iterations as a @code{const_int} or @code{const0_rtx} if this cannot be
3229 determined until run-time; operand 2 is the actual or estimated maximum
3230 number of iterations as a @code{const_int}; operand 3 is the number of
3231 enclosed loops as a @code{const_int} (an innermost loop has a value of
3232 1); operand 4 is the label to jump to if the register is nonzero.
3233 @xref{Looping Patterns}.
3234
3235 This optional instruction pattern should be defined for machines with
3236 low-overhead looping instructions as the loop optimizer will try to
3237 modify suitable loops to utilize it.  If nested low-overhead looping is
3238 not supported, use a @code{define_expand} (@pxref{Expander Definitions})
3239 and make the pattern fail if operand 3 is not @code{const1_rtx}.
3240 Similarly, if the actual or estimated maximum number of iterations is
3241 too large for this instruction, make it fail.
3242
3243 @cindex @code{doloop_begin} instruction pattern
3244 @item @samp{doloop_begin}
3245 Companion instruction to @code{doloop_end} required for machines that
3246 need to perform some initialization, such as loading special registers
3247 used by a low-overhead looping instruction.  If initialization insns do
3248 not always need to be emitted, use a @code{define_expand}
3249 (@pxref{Expander Definitions}) and make it fail.
3250
3251
3252 @cindex @code{canonicalize_funcptr_for_compare} instruction pattern
3253 @item @samp{canonicalize_funcptr_for_compare}
3254 Canonicalize the function pointer in operand 1 and store the result
3255 into operand 0.
3256
3257 Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1
3258 may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc
3259 and also has mode @code{Pmode}.
3260
3261 Canonicalization of a function pointer usually involves computing
3262 the address of the function which would be called if the function
3263 pointer were used in an indirect call.
3264
3265 Only define this pattern if function pointers on the target machine
3266 can have different values but still call the same function when
3267 used in an indirect call.
3268
3269 @cindex @code{save_stack_block} instruction pattern
3270 @cindex @code{save_stack_function} instruction pattern
3271 @cindex @code{save_stack_nonlocal} instruction pattern
3272 @cindex @code{restore_stack_block} instruction pattern
3273 @cindex @code{restore_stack_function} instruction pattern
3274 @cindex @code{restore_stack_nonlocal} instruction pattern
3275 @item @samp{save_stack_block}
3276 @itemx @samp{save_stack_function}
3277 @itemx @samp{save_stack_nonlocal}
3278 @itemx @samp{restore_stack_block}
3279 @itemx @samp{restore_stack_function}
3280 @itemx @samp{restore_stack_nonlocal}
3281 Most machines save and restore the stack pointer by copying it to or
3282 from an object of mode @code{Pmode}.  Do not define these patterns on
3283 such machines.
3284
3285 Some machines require special handling for stack pointer saves and
3286 restores.  On those machines, define the patterns corresponding to the
3287 non-standard cases by using a @code{define_expand} (@pxref{Expander
3288 Definitions}) that produces the required insns.  The three types of
3289 saves and restores are:
3290
3291 @enumerate
3292 @item
3293 @samp{save_stack_block} saves the stack pointer at the start of a block
3294 that allocates a variable-sized object, and @samp{restore_stack_block}
3295 restores the stack pointer when the block is exited.
3296
3297 @item
3298 @samp{save_stack_function} and @samp{restore_stack_function} do a
3299 similar job for the outermost block of a function and are used when the
3300 function allocates variable-sized objects or calls @code{alloca}.  Only
3301 the epilogue uses the restored stack pointer, allowing a simpler save or
3302 restore sequence on some machines.
3303
3304 @item
3305 @samp{save_stack_nonlocal} is used in functions that contain labels
3306 branched to by nested functions.  It saves the stack pointer in such a
3307 way that the inner function can use @samp{restore_stack_nonlocal} to
3308 restore the stack pointer.  The compiler generates code to restore the
3309 frame and argument pointer registers, but some machines require saving
3310 and restoring additional data such as register window information or
3311 stack backchains.  Place insns in these patterns to save and restore any
3312 such required data.
3313 @end enumerate
3314
3315 When saving the stack pointer, operand 0 is the save area and operand 1
3316 is the stack pointer.  The mode used to allocate the save area defaults
3317 to @code{Pmode} but you can override that choice by defining the
3318 @code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}).  You must
3319 specify an integral mode, or @code{VOIDmode} if no save area is needed
3320 for a particular type of save (either because no save is needed or
3321 because a machine-specific save area can be used).  Operand 0 is the
3322 stack pointer and operand 1 is the save area for restore operations.  If
3323 @samp{save_stack_block} is defined, operand 0 must not be
3324 @code{VOIDmode} since these saves can be arbitrarily nested.
3325
3326 A save area is a @code{mem} that is at a constant offset from
3327 @code{virtual_stack_vars_rtx} when the stack pointer is saved for use by
3328 nonlocal gotos and a @code{reg} in the other two cases.
3329
3330 @cindex @code{allocate_stack} instruction pattern
3331 @item @samp{allocate_stack}
3332 Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from
3333 the stack pointer to create space for dynamically allocated data.
3334
3335 Store the resultant pointer to this space into operand 0.  If you
3336 are allocating space from the main stack, do this by emitting a
3337 move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0.
3338 If you are allocating the space elsewhere, generate code to copy the
3339 location of the space to operand 0.  In the latter case, you must
3340 ensure this space gets freed when the corresponding space on the main
3341 stack is free.
3342
3343 Do not define this pattern if all that must be done is the subtraction.
3344 Some machines require other operations such as stack probes or
3345 maintaining the back chain.  Define this pattern to emit those
3346 operations in addition to updating the stack pointer.
3347
3348 @cindex @code{check_stack} instruction pattern
3349 @item @samp{check_stack}
3350 If stack checking cannot be done on your system by probing the stack with
3351 a load or store instruction (@pxref{Stack Checking}), define this pattern
3352 to perform the needed check and signaling an error if the stack
3353 has overflowed.  The single operand is the location in the stack furthest
3354 from the current stack pointer that you need to validate.  Normally,
3355 on machines where this pattern is needed, you would obtain the stack
3356 limit from a global or thread-specific variable or register.
3357
3358 @cindex @code{nonlocal_goto} instruction pattern
3359 @item @samp{nonlocal_goto}
3360 Emit code to generate a non-local goto, e.g., a jump from one function
3361 to a label in an outer function.  This pattern has four arguments,
3362 each representing a value to be used in the jump.  The first
3363 argument is to be loaded into the frame pointer, the second is
3364 the address to branch to (code to dispatch to the actual label),
3365 the third is the address of a location where the stack is saved,
3366 and the last is the address of the label, to be placed in the
3367 location for the incoming static chain.
3368
3369 On most machines you need not define this pattern, since GCC will
3370 already generate the correct code, which is to load the frame pointer
3371 and static chain, restore the stack (using the
3372 @samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly
3373 to the dispatcher.  You need only define this pattern if this code will
3374 not work on your machine.
3375
3376 @cindex @code{nonlocal_goto_receiver} instruction pattern
3377 @item @samp{nonlocal_goto_receiver}
3378 This pattern, if defined, contains code needed at the target of a
3379 nonlocal goto after the code already generated by GCC@.  You will not
3380 normally need to define this pattern.  A typical reason why you might
3381 need this pattern is if some value, such as a pointer to a global table,
3382 must be restored when the frame pointer is restored.  Note that a nonlocal
3383 goto only occurs within a unit-of-translation, so a global table pointer
3384 that is shared by all functions of a given module need not be restored.
3385 There are no arguments.
3386
3387 @cindex @code{exception_receiver} instruction pattern
3388 @item @samp{exception_receiver}
3389 This pattern, if defined, contains code needed at the site of an
3390 exception handler that isn't needed at the site of a nonlocal goto.  You
3391 will not normally need to define this pattern.  A typical reason why you
3392 might need this pattern is if some value, such as a pointer to a global
3393 table, must be restored after control flow is branched to the handler of
3394 an exception.  There are no arguments.
3395
3396 @cindex @code{builtin_setjmp_setup} instruction pattern
3397 @item @samp{builtin_setjmp_setup}
3398 This pattern, if defined, contains additional code needed to initialize
3399 the @code{jmp_buf}.  You will not normally need to define this pattern.
3400 A typical reason why you might need this pattern is if some value, such
3401 as a pointer to a global table, must be restored.  Though it is
3402 preferred that the pointer value be recalculated if possible (given the
3403 address of a label for instance).  The single argument is a pointer to
3404 the @code{jmp_buf}.  Note that the buffer is five words long and that
3405 the first three are normally used by the generic mechanism.
3406
3407 @cindex @code{builtin_setjmp_receiver} instruction pattern
3408 @item @samp{builtin_setjmp_receiver}
3409 This pattern, if defined, contains code needed at the site of an
3410 built-in setjmp that isn't needed at the site of a nonlocal goto.  You
3411 will not normally need to define this pattern.  A typical reason why you
3412 might need this pattern is if some value, such as a pointer to a global
3413 table, must be restored.  It takes one argument, which is the label
3414 to which builtin_longjmp transfered control; this pattern may be emitted
3415 at a small offset from that label.
3416
3417 @cindex @code{builtin_longjmp} instruction pattern
3418 @item @samp{builtin_longjmp}
3419 This pattern, if defined, performs the entire action of the longjmp.
3420 You will not normally need to define this pattern unless you also define
3421 @code{builtin_setjmp_setup}.  The single argument is a pointer to the
3422 @code{jmp_buf}.
3423
3424 @cindex @code{eh_return} instruction pattern
3425 @item @samp{eh_return}
3426 This pattern, if defined, affects the way @code{__builtin_eh_return},
3427 and thence the call frame exception handling library routines, are
3428 built.  It is intended to handle non-trivial actions needed along
3429 the abnormal return path.
3430
3431 The address of the exception handler to which the function should return
3432 is passed as operand to this pattern.  It will normally need to copied by 
3433 the pattern to some special register or memory location.
3434 If the pattern needs to determine the location of the target call
3435 frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX},
3436 if defined; it will have already been assigned.
3437
3438 If this pattern is not defined, the default action will be to simply
3439 copy the return address to @code{EH_RETURN_HANDLER_RTX}.  Either
3440 that macro or this pattern needs to be defined if call frame exception
3441 handling is to be used.
3442
3443 @cindex @code{prologue} instruction pattern
3444 @anchor{prologue instruction pattern}
3445 @item @samp{prologue}
3446 This pattern, if defined, emits RTL for entry to a function.  The function
3447 entry is responsible for setting up the stack frame, initializing the frame
3448 pointer register, saving callee saved registers, etc.
3449
3450 Using a prologue pattern is generally preferred over defining
3451 @code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue.
3452
3453 The @code{prologue} pattern is particularly useful for targets which perform
3454 instruction scheduling.
3455
3456 @cindex @code{epilogue} instruction pattern
3457 @anchor{epilogue instruction pattern}
3458 @item @samp{epilogue}
3459 This pattern emits RTL for exit from a function.  The function
3460 exit is responsible for deallocating the stack frame, restoring callee saved
3461 registers and emitting the return instruction.
3462
3463 Using an epilogue pattern is generally preferred over defining
3464 @code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue.
3465
3466 The @code{epilogue} pattern is particularly useful for targets which perform
3467 instruction scheduling or which have delay slots for their return instruction.
3468
3469 @cindex @code{sibcall_epilogue} instruction pattern
3470 @item @samp{sibcall_epilogue}
3471 This pattern, if defined, emits RTL for exit from a function without the final
3472 branch back to the calling function.  This pattern will be emitted before any
3473 sibling call (aka tail call) sites.
3474
3475 The @code{sibcall_epilogue} pattern must not clobber any arguments used for
3476 parameter passing or any stack slots for arguments passed to the current
3477 function.
3478
3479 @cindex @code{trap} instruction pattern
3480 @item @samp{trap}
3481 This pattern, if defined, signals an error, typically by causing some
3482 kind of signal to be raised.  Among other places, it is used by the Java
3483 front end to signal `invalid array index' exceptions.
3484
3485 @cindex @code{conditional_trap} instruction pattern
3486 @item @samp{conditional_trap}
3487 Conditional trap instruction.  Operand 0 is a piece of RTL which
3488 performs a comparison.  Operand 1 is the trap code, an integer.
3489
3490 A typical @code{conditional_trap} pattern looks like
3491
3492 @smallexample
3493 (define_insn "conditional_trap"
3494   [(trap_if (match_operator 0 "trap_operator"
3495              [(cc0) (const_int 0)])
3496             (match_operand 1 "const_int_operand" "i"))]
3497   ""
3498   "@dots{}")
3499 @end smallexample
3500
3501 @cindex @code{prefetch} instruction pattern
3502 @item @samp{prefetch}
3503
3504 This pattern, if defined, emits code for a non-faulting data prefetch
3505 instruction.  Operand 0 is the address of the memory to prefetch.  Operand 1
3506 is a constant 1 if the prefetch is preparing for a write to the memory
3507 address, or a constant 0 otherwise.  Operand 2 is the expected degree of
3508 temporal locality of the data and is a value between 0 and 3, inclusive; 0
3509 means that the data has no temporal locality, so it need not be left in the
3510 cache after the access; 3 means that the data has a high degree of temporal
3511 locality and should be left in all levels of cache possible;  1 and 2 mean,
3512 respectively, a low or moderate degree of temporal locality.
3513
3514 Targets that do not support write prefetches or locality hints can ignore
3515 the values of operands 1 and 2.
3516
3517 @end table
3518
3519 @node Pattern Ordering
3520 @section When the Order of Patterns Matters
3521 @cindex Pattern Ordering
3522 @cindex Ordering of Patterns
3523
3524 Sometimes an insn can match more than one instruction pattern.  Then the
3525 pattern that appears first in the machine description is the one used.
3526 Therefore, more specific patterns (patterns that will match fewer things)
3527 and faster instructions (those that will produce better code when they
3528 do match) should usually go first in the description.
3529
3530 In some cases the effect of ordering the patterns can be used to hide
3531 a pattern when it is not valid.  For example, the 68000 has an
3532 instruction for converting a fullword to floating point and another
3533 for converting a byte to floating point.  An instruction converting
3534 an integer to floating point could match either one.  We put the
3535 pattern to convert the fullword first to make sure that one will
3536 be used rather than the other.  (Otherwise a large integer might
3537 be generated as a single-byte immediate quantity, which would not work.)
3538 Instead of using this pattern ordering it would be possible to make the
3539 pattern for convert-a-byte smart enough to deal properly with any
3540 constant value.
3541
3542 @node Dependent Patterns
3543 @section Interdependence of Patterns
3544 @cindex Dependent Patterns
3545 @cindex Interdependence of Patterns
3546
3547 Every machine description must have a named pattern for each of the
3548 conditional branch names @samp{b@var{cond}}.  The recognition template
3549 must always have the form
3550
3551 @smallexample
3552 (set (pc)
3553      (if_then_else (@var{cond} (cc0) (const_int 0))
3554                    (label_ref (match_operand 0 "" ""))
3555                    (pc)))
3556 @end smallexample
3557
3558 @noindent
3559 In addition, every machine description must have an anonymous pattern
3560 for each of the possible reverse-conditional branches.  Their templates
3561 look like
3562
3563 @smallexample
3564 (set (pc)
3565      (if_then_else (@var{cond} (cc0) (const_int 0))
3566                    (pc)
3567                    (label_ref (match_operand 0 "" ""))))
3568 @end smallexample
3569
3570 @noindent
3571 They are necessary because jump optimization can turn direct-conditional
3572 branches into reverse-conditional branches.
3573
3574 It is often convenient to use the @code{match_operator} construct to
3575 reduce the number of patterns that must be specified for branches.  For
3576 example,
3577
3578 @smallexample
3579 (define_insn ""
3580   [(set (pc)
3581         (if_then_else (match_operator 0 "comparison_operator"
3582                                       [(cc0) (const_int 0)])
3583                       (pc)
3584                       (label_ref (match_operand 1 "" ""))))]
3585   "@var{condition}"
3586   "@dots{}")
3587 @end smallexample
3588
3589 In some cases machines support instructions identical except for the
3590 machine mode of one or more operands.  For example, there may be
3591 ``sign-extend halfword'' and ``sign-extend byte'' instructions whose
3592 patterns are
3593
3594 @smallexample
3595 (set (match_operand:SI 0 @dots{})
3596      (extend:SI (match_operand:HI 1 @dots{})))
3597
3598 (set (match_operand:SI 0 @dots{})
3599      (extend:SI (match_operand:QI 1 @dots{})))
3600 @end smallexample
3601
3602 @noindent
3603 Constant integers do not specify a machine mode, so an instruction to
3604 extend a constant value could match either pattern.  The pattern it
3605 actually will match is the one that appears first in the file.  For correct
3606 results, this must be the one for the widest possible mode (@code{HImode},
3607 here).  If the pattern matches the @code{QImode} instruction, the results
3608 will be incorrect if the constant value does not actually fit that mode.
3609
3610 Such instructions to extend constants are rarely generated because they are
3611 optimized away, but they do occasionally happen in nonoptimized
3612 compilations.
3613
3614 If a constraint in a pattern allows a constant, the reload pass may
3615 replace a register with a constant permitted by the constraint in some
3616 cases.  Similarly for memory references.  Because of this substitution,
3617 you should not provide separate patterns for increment and decrement
3618 instructions.  Instead, they should be generated from the same pattern
3619 that supports register-register add insns by examining the operands and
3620 generating the appropriate machine instruction.
3621
3622 @node Jump Patterns
3623 @section Defining Jump Instruction Patterns
3624 @cindex jump instruction patterns
3625 @cindex defining jump instruction patterns
3626
3627 For most machines, GCC assumes that the machine has a condition code.
3628 A comparison insn sets the condition code, recording the results of both
3629 signed and unsigned comparison of the given operands.  A separate branch
3630 insn tests the condition code and branches or not according its value.
3631 The branch insns come in distinct signed and unsigned flavors.  Many
3632 common machines, such as the VAX, the 68000 and the 32000, work this
3633 way.
3634
3635 Some machines have distinct signed and unsigned compare instructions, and
3636 only one set of conditional branch instructions.  The easiest way to handle
3637 these machines is to treat them just like the others until the final stage
3638 where assembly code is written.  At this time, when outputting code for the
3639 compare instruction, peek ahead at the following branch using
3640 @code{next_cc0_user (insn)}.  (The variable @code{insn} refers to the insn
3641 being output, in the output-writing code in an instruction pattern.)  If
3642 the RTL says that is an unsigned branch, output an unsigned compare;
3643 otherwise output a signed compare.  When the branch itself is output, you
3644 can treat signed and unsigned branches identically.
3645
3646 The reason you can do this is that GCC always generates a pair of
3647 consecutive RTL insns, possibly separated by @code{note} insns, one to
3648 set the condition code and one to test it, and keeps the pair inviolate
3649 until the end.
3650
3651 To go with this technique, you must define the machine-description macro
3652 @code{NOTICE_UPDATE_CC} to do @code{CC_STATUS_INIT}; in other words, no
3653 compare instruction is superfluous.
3654
3655 Some machines have compare-and-branch instructions and no condition code.
3656 A similar technique works for them.  When it is time to ``output'' a
3657 compare instruction, record its operands in two static variables.  When
3658 outputting the branch-on-condition-code instruction that follows, actually
3659 output a compare-and-branch instruction that uses the remembered operands.
3660
3661 It also works to define patterns for compare-and-branch instructions.
3662 In optimizing compilation, the pair of compare and branch instructions
3663 will be combined according to these patterns.  But this does not happen
3664 if optimization is not requested.  So you must use one of the solutions
3665 above in addition to any special patterns you define.
3666
3667 In many RISC machines, most instructions do not affect the condition
3668 code and there may not even be a separate condition code register.  On
3669 these machines, the restriction that the definition and use of the
3670 condition code be adjacent insns is not necessary and can prevent
3671 important optimizations.  For example, on the IBM RS/6000, there is a
3672 delay for taken branches unless the condition code register is set three
3673 instructions earlier than the conditional branch.  The instruction
3674 scheduler cannot perform this optimization if it is not permitted to
3675 separate the definition and use of the condition code register.
3676
3677 On these machines, do not use @code{(cc0)}, but instead use a register
3678 to represent the condition code.  If there is a specific condition code
3679 register in the machine, use a hard register.  If the condition code or
3680 comparison result can be placed in any general register, or if there are
3681 multiple condition registers, use a pseudo register.
3682
3683 @findex prev_cc0_setter
3684 @findex next_cc0_user
3685 On some machines, the type of branch instruction generated may depend on
3686 the way the condition code was produced; for example, on the 68k and
3687 SPARC, setting the condition code directly from an add or subtract
3688 instruction does not clear the overflow bit the way that a test
3689 instruction does, so a different branch instruction must be used for
3690 some conditional branches.  For machines that use @code{(cc0)}, the set
3691 and use of the condition code must be adjacent (separated only by
3692 @code{note} insns) allowing flags in @code{cc_status} to be used.
3693 (@xref{Condition Code}.)  Also, the comparison and branch insns can be
3694 located from each other by using the functions @code{prev_cc0_setter}
3695 and @code{next_cc0_user}.
3696
3697 However, this is not true on machines that do not use @code{(cc0)}.  On
3698 those machines, no assumptions can be made about the adjacency of the
3699 compare and branch insns and the above methods cannot be used.  Instead,
3700 we use the machine mode of the condition code register to record
3701 different formats of the condition code register.
3702
3703 Registers used to store the condition code value should have a mode that
3704 is in class @code{MODE_CC}.  Normally, it will be @code{CCmode}.  If
3705 additional modes are required (as for the add example mentioned above in
3706 the SPARC), define the macro @code{EXTRA_CC_MODES} to list the
3707 additional modes required (@pxref{Condition Code}).  Also define
3708 @code{SELECT_CC_MODE} to choose a mode given an operand of a compare.
3709
3710 If it is known during RTL generation that a different mode will be
3711 required (for example, if the machine has separate compare instructions
3712 for signed and unsigned quantities, like most IBM processors), they can
3713 be specified at that time.
3714
3715 If the cases that require different modes would be made by instruction
3716 combination, the macro @code{SELECT_CC_MODE} determines which machine
3717 mode should be used for the comparison result.  The patterns should be
3718 written using that mode.  To support the case of the add on the SPARC
3719 discussed above, we have the pattern
3720
3721 @smallexample
3722 (define_insn ""
3723   [(set (reg:CC_NOOV 0)
3724         (compare:CC_NOOV
3725           (plus:SI (match_operand:SI 0 "register_operand" "%r")
3726                    (match_operand:SI 1 "arith_operand" "rI"))
3727           (const_int 0)))]
3728   ""
3729   "@dots{}")
3730 @end smallexample
3731
3732 The @code{SELECT_CC_MODE} macro on the SPARC returns @code{CC_NOOVmode}
3733 for comparisons whose argument is a @code{plus}.
3734
3735 @node Looping Patterns
3736 @section Defining Looping Instruction Patterns
3737 @cindex looping instruction patterns
3738 @cindex defining looping instruction patterns
3739
3740 Some machines have special jump instructions that can be utilized to
3741 make loops more efficient.  A common example is the 68000 @samp{dbra}
3742 instruction which performs a decrement of a register and a branch if the
3743 result was greater than zero.  Other machines, in particular digital
3744 signal processors (DSPs), have special block repeat instructions to
3745 provide low-overhead loop support.  For example, the TI TMS320C3x/C4x
3746 DSPs have a block repeat instruction that loads special registers to
3747 mark the top and end of a loop and to count the number of loop
3748 iterations.  This avoids the need for fetching and executing a
3749 @samp{dbra}-like instruction and avoids pipeline stalls associated with
3750 the jump.
3751
3752 GCC has three special named patterns to support low overhead looping.
3753 They are @samp{decrement_and_branch_until_zero}, @samp{doloop_begin},
3754 and @samp{doloop_end}.  The first pattern,
3755 @samp{decrement_and_branch_until_zero}, is not emitted during RTL
3756 generation but may be emitted during the instruction combination phase.
3757 This requires the assistance of the loop optimizer, using information
3758 collected during strength reduction, to reverse a loop to count down to
3759 zero.  Some targets also require the loop optimizer to add a
3760 @code{REG_NONNEG} note to indicate that the iteration count is always
3761 positive.  This is needed if the target performs a signed loop
3762 termination test.  For example, the 68000 uses a pattern similar to the
3763 following for its @code{dbra} instruction:
3764
3765 @smallexample
3766 @group
3767 (define_insn "decrement_and_branch_until_zero"
3768   [(set (pc)
3769         (if_then_else
3770           (ge (plus:SI (match_operand:SI 0 "general_operand" "+d*am")
3771                        (const_int -1))
3772               (const_int 0))
3773           (label_ref (match_operand 1 "" ""))
3774           (pc)))
3775    (set (match_dup 0)
3776         (plus:SI (match_dup 0)
3777                  (const_int -1)))]
3778   "find_reg_note (insn, REG_NONNEG, 0)"
3779   "@dots{}")
3780 @end group
3781 @end smallexample
3782
3783 Note that since the insn is both a jump insn and has an output, it must
3784 deal with its own reloads, hence the `m' constraints.  Also note that
3785 since this insn is generated by the instruction combination phase
3786 combining two sequential insns together into an implicit parallel insn,
3787 the iteration counter needs to be biased by the same amount as the
3788 decrement operation, in this case @minus{}1.  Note that the following similar
3789 pattern will not be matched by the combiner.
3790
3791 @smallexample
3792 @group
3793 (define_insn "decrement_and_branch_until_zero"
3794   [(set (pc)
3795         (if_then_else
3796           (ge (match_operand:SI 0 "general_operand" "+d*am")
3797               (const_int 1))
3798           (label_ref (match_operand 1 "" ""))
3799           (pc)))
3800    (set (match_dup 0)
3801         (plus:SI (match_dup 0)
3802                  (const_int -1)))]
3803   "find_reg_note (insn, REG_NONNEG, 0)"
3804   "@dots{}")
3805 @end group
3806 @end smallexample
3807
3808 The other two special looping patterns, @samp{doloop_begin} and
3809 @samp{doloop_end}, are emitted by the loop optimizer for certain
3810 well-behaved loops with a finite number of loop iterations using
3811 information collected during strength reduction.
3812
3813 The @samp{doloop_end} pattern describes the actual looping instruction
3814 (or the implicit looping operation) and the @samp{doloop_begin} pattern
3815 is an optional companion pattern that can be used for initialization
3816 needed for some low-overhead looping instructions.
3817
3818 Note that some machines require the actual looping instruction to be
3819 emitted at the top of the loop (e.g., the TMS320C3x/C4x DSPs).  Emitting
3820 the true RTL for a looping instruction at the top of the loop can cause
3821 problems with flow analysis.  So instead, a dummy @code{doloop} insn is
3822 emitted at the end of the loop.  The machine dependent reorg pass checks
3823 for the presence of this @code{doloop} insn and then searches back to
3824 the top of the loop, where it inserts the true looping insn (provided
3825 there are no instructions in the loop which would cause problems).  Any
3826 additional labels can be emitted at this point.  In addition, if the
3827 desired special iteration counter register was not allocated, this
3828 machine dependent reorg pass could emit a traditional compare and jump
3829 instruction pair.
3830
3831 The essential difference between the
3832 @samp{decrement_and_branch_until_zero} and the @samp{doloop_end}
3833 patterns is that the loop optimizer allocates an additional pseudo
3834 register for the latter as an iteration counter.  This pseudo register
3835 cannot be used within the loop (i.e., general induction variables cannot
3836 be derived from it), however, in many cases the loop induction variable
3837 may become redundant and removed by the flow pass.
3838
3839
3840 @node Insn Canonicalizations
3841 @section Canonicalization of Instructions
3842 @cindex canonicalization of instructions
3843 @cindex insn canonicalization
3844
3845 There are often cases where multiple RTL expressions could represent an
3846 operation performed by a single machine instruction.  This situation is
3847 most commonly encountered with logical, branch, and multiply-accumulate
3848 instructions.  In such cases, the compiler attempts to convert these
3849 multiple RTL expressions into a single canonical form to reduce the
3850 number of insn patterns required.
3851
3852 In addition to algebraic simplifications, following canonicalizations
3853 are performed:
3854
3855 @itemize @bullet
3856 @item
3857 For commutative and comparison operators, a constant is always made the
3858 second operand.  If a machine only supports a constant as the second
3859 operand, only patterns that match a constant in the second operand need
3860 be supplied.
3861
3862 @cindex @code{neg}, canonicalization of
3863 @cindex @code{not}, canonicalization of
3864 @cindex @code{mult}, canonicalization of
3865 @cindex @code{plus}, canonicalization of
3866 @cindex @code{minus}, canonicalization of
3867 For these operators, if only one operand is a @code{neg}, @code{not},
3868 @code{mult}, @code{plus}, or @code{minus} expression, it will be the
3869 first operand.
3870
3871 @item
3872 In combinations of @code{neg}, @code{mult}, @code{plus}, and
3873 @code{minus}, the @code{neg} operations (if any) will be moved inside
3874 the operations as far as possible.  For instance, 
3875 @code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but
3876 @code{(plus (mult (neg A) B) C)} is canonicalized as
3877 @code{(minus A (mult B C))}.
3878
3879 @cindex @code{compare}, canonicalization of
3880 @item
3881 For the @code{compare} operator, a constant is always the second operand
3882 on machines where @code{cc0} is used (@pxref{Jump Patterns}).  On other
3883 machines, there are rare cases where the compiler might want to construct
3884 a @code{compare} with a constant as the first operand.  However, these
3885 cases are not common enough for it to be worthwhile to provide a pattern
3886 matching a constant as the first operand unless the machine actually has
3887 such an instruction.
3888
3889 An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or
3890 @code{minus} is made the first operand under the same conditions as
3891 above.
3892
3893 @item
3894 @code{(minus @var{x} (const_int @var{n}))} is converted to
3895 @code{(plus @var{x} (const_int @var{-n}))}.
3896
3897 @item
3898 Within address computations (i.e., inside @code{mem}), a left shift is
3899 converted into the appropriate multiplication by a power of two.
3900
3901 @cindex @code{ior}, canonicalization of
3902 @cindex @code{and}, canonicalization of
3903 @cindex De Morgan's law
3904 @item
3905 De`Morgan's Law is used to move bitwise negation inside a bitwise
3906 logical-and or logical-or operation.  If this results in only one
3907 operand being a @code{not} expression, it will be the first one.
3908
3909 A machine that has an instruction that performs a bitwise logical-and of one
3910 operand with the bitwise negation of the other should specify the pattern
3911 for that instruction as
3912
3913 @smallexample
3914 (define_insn ""
3915   [(set (match_operand:@var{m} 0 @dots{})
3916         (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
3917                      (match_operand:@var{m} 2 @dots{})))]
3918   "@dots{}"
3919   "@dots{}")
3920 @end smallexample
3921
3922 @noindent
3923 Similarly, a pattern for a ``NAND'' instruction should be written
3924
3925 @smallexample
3926 (define_insn ""
3927   [(set (match_operand:@var{m} 0 @dots{})
3928         (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
3929                      (not:@var{m} (match_operand:@var{m} 2 @dots{}))))]
3930   "@dots{}"
3931   "@dots{}")
3932 @end smallexample
3933
3934 In both cases, it is not necessary to include patterns for the many
3935 logically equivalent RTL expressions.
3936
3937 @cindex @code{xor}, canonicalization of
3938 @item
3939 The only possible RTL expressions involving both bitwise exclusive-or
3940 and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})}
3941 and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}.
3942
3943 @item
3944 The sum of three items, one of which is a constant, will only appear in
3945 the form
3946
3947 @smallexample
3948 (plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant})
3949 @end smallexample
3950
3951 @item
3952 On machines that do not use @code{cc0},
3953 @code{(compare @var{x} (const_int 0))} will be converted to
3954 @var{x}.
3955
3956 @cindex @code{zero_extract}, canonicalization of
3957 @cindex @code{sign_extract}, canonicalization of
3958 @item
3959 Equality comparisons of a group of bits (usually a single bit) with zero
3960 will be written using @code{zero_extract} rather than the equivalent
3961 @code{and} or @code{sign_extract} operations.
3962
3963 @end itemize
3964
3965 @node Expander Definitions
3966 @section Defining RTL Sequences for Code Generation
3967 @cindex expander definitions
3968 @cindex code generation RTL sequences
3969 @cindex defining RTL sequences for code generation
3970
3971 On some target machines, some standard pattern names for RTL generation
3972 cannot be handled with single insn, but a sequence of RTL insns can
3973 represent them.  For these target machines, you can write a
3974 @code{define_expand} to specify how to generate the sequence of RTL@.
3975
3976 @findex define_expand
3977 A @code{define_expand} is an RTL expression that looks almost like a
3978 @code{define_insn}; but, unlike the latter, a @code{define_expand} is used
3979 only for RTL generation and it can produce more than one RTL insn.
3980
3981 A @code{define_expand} RTX has four operands:
3982
3983 @itemize @bullet
3984 @item
3985 The name.  Each @code{define_expand} must have a name, since the only
3986 use for it is to refer to it by name.
3987
3988 @item
3989 The RTL template.  This is a vector of RTL expressions representing
3990 a sequence of separate instructions.  Unlike @code{define_insn}, there
3991 is no implicit surrounding @code{PARALLEL}.
3992
3993 @item
3994 The condition, a string containing a C expression.  This expression is
3995 used to express how the availability of this pattern depends on
3996 subclasses of target machine, selected by command-line options when GCC
3997 is run.  This is just like the condition of a @code{define_insn} that
3998 has a standard name.  Therefore, the condition (if present) may not
3999 depend on the data in the insn being matched, but only the
4000 target-machine-type flags.  The compiler needs to test these conditions
4001 during initialization in order to learn exactly which named instructions
4002 are available in a particular run.
4003
4004 @item
4005 The preparation statements, a string containing zero or more C
4006 statements which are to be executed before RTL code is generated from
4007 the RTL template.
4008
4009 Usually these statements prepare temporary registers for use as
4010 internal operands in the RTL template, but they can also generate RTL
4011 insns directly by calling routines such as @code{emit_insn}, etc.
4012 Any such insns precede the ones that come from the RTL template.
4013 @end itemize
4014
4015 Every RTL insn emitted by a @code{define_expand} must match some
4016 @code{define_insn} in the machine description.  Otherwise, the compiler
4017 will crash when trying to generate code for the insn or trying to optimize
4018 it.
4019
4020 The RTL template, in addition to controlling generation of RTL insns,
4021 also describes the operands that need to be specified when this pattern
4022 is used.  In particular, it gives a predicate for each operand.
4023
4024 A true operand, which needs to be specified in order to generate RTL from
4025 the pattern, should be described with a @code{match_operand} in its first
4026 occurrence in the RTL template.  This enters information on the operand's
4027 predicate into the tables that record such things.  GCC uses the
4028 information to preload the operand into a register if that is required for
4029 valid RTL code.  If the operand is referred to more than once, subsequent
4030 references should use @code{match_dup}.
4031
4032 The RTL template may also refer to internal ``operands'' which are
4033 temporary registers or labels used only within the sequence made by the
4034 @code{define_expand}.  Internal operands are substituted into the RTL
4035 template with @code{match_dup}, never with @code{match_operand}.  The
4036 values of the internal operands are not passed in as arguments by the
4037 compiler when it requests use of this pattern.  Instead, they are computed
4038 within the pattern, in the preparation statements.  These statements
4039 compute the values and store them into the appropriate elements of
4040 @code{operands} so that @code{match_dup} can find them.
4041
4042 There are two special macros defined for use in the preparation statements:
4043 @code{DONE} and @code{FAIL}.  Use them with a following semicolon,
4044 as a statement.
4045
4046 @table @code
4047
4048 @findex DONE
4049 @item DONE
4050 Use the @code{DONE} macro to end RTL generation for the pattern.  The
4051 only RTL insns resulting from the pattern on this occasion will be
4052 those already emitted by explicit calls to @code{emit_insn} within the
4053 preparation statements; the RTL template will not be generated.
4054
4055 @findex FAIL
4056 @item FAIL
4057 Make the pattern fail on this occasion.  When a pattern fails, it means
4058 that the pattern was not truly available.  The calling routines in the
4059 compiler will try other strategies for code generation using other patterns.
4060
4061 Failure is currently supported only for binary (addition, multiplication,
4062 shifting, etc.) and bit-field (@code{extv}, @code{extzv}, and @code{insv})
4063 operations.
4064 @end table
4065
4066 If the preparation falls through (invokes neither @code{DONE} nor
4067 @code{FAIL}), then the @code{define_expand} acts like a
4068 @code{define_insn} in that the RTL template is used to generate the
4069 insn.
4070
4071 The RTL template is not used for matching, only for generating the
4072 initial insn list.  If the preparation statement always invokes
4073 @code{DONE} or @code{FAIL}, the RTL template may be reduced to a simple
4074 list of operands, such as this example:
4075
4076 @smallexample
4077 @group
4078 (define_expand "addsi3"
4079   [(match_operand:SI 0 "register_operand" "")
4080    (match_operand:SI 1 "register_operand" "")
4081    (match_operand:SI 2 "register_operand" "")]
4082 @end group
4083 @group
4084   ""
4085   "
4086 @{
4087   handle_add (operands[0], operands[1], operands[2]);
4088   DONE;
4089 @}")
4090 @end group
4091 @end smallexample
4092
4093 Here is an example, the definition of left-shift for the SPUR chip:
4094
4095 @smallexample
4096 @group
4097 (define_expand "ashlsi3"
4098   [(set (match_operand:SI 0 "register_operand" "")
4099         (ashift:SI
4100 @end group
4101 @group
4102           (match_operand:SI 1 "register_operand" "")
4103           (match_operand:SI 2 "nonmemory_operand" "")))]
4104   ""
4105   "
4106 @end group
4107 @end smallexample
4108
4109 @smallexample
4110 @group
4111 @{
4112   if (GET_CODE (operands[2]) != CONST_INT
4113       || (unsigned) INTVAL (operands[2]) > 3)
4114     FAIL;
4115 @}")
4116 @end group
4117 @end smallexample
4118
4119 @noindent
4120 This example uses @code{define_expand} so that it can generate an RTL insn
4121 for shifting when the shift-count is in the supported range of 0 to 3 but
4122 fail in other cases where machine insns aren't available.  When it fails,
4123 the compiler tries another strategy using different patterns (such as, a
4124 library call).
4125
4126 If the compiler were able to handle nontrivial condition-strings in
4127 patterns with names, then it would be possible to use a
4128 @code{define_insn} in that case.  Here is another case (zero-extension
4129 on the 68000) which makes more use of the power of @code{define_expand}:
4130
4131 @smallexample
4132 (define_expand "zero_extendhisi2"
4133   [(set (match_operand:SI 0 "general_operand" "")
4134         (const_int 0))
4135    (set (strict_low_part
4136           (subreg:HI
4137             (match_dup 0)
4138             0))
4139         (match_operand:HI 1 "general_operand" ""))]
4140   ""
4141   "operands[1] = make_safe_from (operands[1], operands[0]);")
4142 @end smallexample
4143
4144 @noindent
4145 @findex make_safe_from
4146 Here two RTL insns are generated, one to clear the entire output operand
4147 and the other to copy the input operand into its low half.  This sequence
4148 is incorrect if the input operand refers to [the old value of] the output
4149 operand, so the preparation statement makes sure this isn't so.  The
4150 function @code{make_safe_from} copies the @code{operands[1]} into a
4151 temporary register if it refers to @code{operands[0]}.  It does this
4152 by emitting another RTL insn.
4153
4154 Finally, a third example shows the use of an internal operand.
4155 Zero-extension on the SPUR chip is done by @code{and}-ing the result
4156 against a halfword mask.  But this mask cannot be represented by a
4157 @code{const_int} because the constant value is too large to be legitimate
4158 on this machine.  So it must be copied into a register with
4159 @code{force_reg} and then the register used in the @code{and}.
4160
4161 @smallexample
4162 (define_expand "zero_extendhisi2"
4163   [(set (match_operand:SI 0 "register_operand" "")
4164         (and:SI (subreg:SI
4165                   (match_operand:HI 1 "register_operand" "")
4166                   0)
4167                 (match_dup 2)))]
4168   ""
4169   "operands[2]
4170      = force_reg (SImode, GEN_INT (65535)); ")
4171 @end smallexample
4172
4173 @strong{Note:} If the @code{define_expand} is used to serve a
4174 standard binary or unary arithmetic operation or a bit-field operation,
4175 then the last insn it generates must not be a @code{code_label},
4176 @code{barrier} or @code{note}.  It must be an @code{insn},
4177 @code{jump_insn} or @code{call_insn}.  If you don't need a real insn
4178 at the end, emit an insn to copy the result of the operation into
4179 itself.  Such an insn will generate no code, but it can avoid problems
4180 in the compiler.
4181
4182 @node Insn Splitting
4183 @section Defining How to Split Instructions
4184 @cindex insn splitting
4185 @cindex instruction splitting
4186 @cindex splitting instructions
4187
4188 There are two cases where you should specify how to split a pattern
4189 into multiple insns.  On machines that have instructions requiring
4190 delay slots (@pxref{Delay Slots}) or that have instructions whose
4191 output is not available for multiple cycles (@pxref{Processor pipeline
4192 description}), the compiler phases that optimize these cases need to
4193 be able to move insns into one-instruction delay slots.  However, some
4194 insns may generate more than one machine instruction.  These insns
4195 cannot be placed into a delay slot.
4196
4197 Often you can rewrite the single insn as a list of individual insns,
4198 each corresponding to one machine instruction.  The disadvantage of
4199 doing so is that it will cause the compilation to be slower and require
4200 more space.  If the resulting insns are too complex, it may also
4201 suppress some optimizations.  The compiler splits the insn if there is a
4202 reason to believe that it might improve instruction or delay slot
4203 scheduling.
4204
4205 The insn combiner phase also splits putative insns.  If three insns are
4206 merged into one insn with a complex expression that cannot be matched by
4207 some @code{define_insn} pattern, the combiner phase attempts to split
4208 the complex pattern into two insns that are recognized.  Usually it can
4209 break the complex pattern into two patterns by splitting out some
4210 subexpression.  However, in some other cases, such as performing an
4211 addition of a large constant in two insns on a RISC machine, the way to
4212 split the addition into two insns is machine-dependent.
4213
4214 @findex define_split
4215 The @code{define_split} definition tells the compiler how to split a
4216 complex insn into several simpler insns.  It looks like this:
4217
4218 @smallexample
4219 (define_split
4220   [@var{insn-pattern}]
4221   "@var{condition}"
4222   [@var{new-insn-pattern-1}
4223    @var{new-insn-pattern-2}
4224    @dots{}]
4225   "@var{preparation-statements}")
4226 @end smallexample
4227
4228 @var{insn-pattern} is a pattern that needs to be split and
4229 @var{condition} is the final condition to be tested, as in a
4230 @code{define_insn}.  When an insn matching @var{insn-pattern} and
4231 satisfying @var{condition} is found, it is replaced in the insn list
4232 with the insns given by @var{new-insn-pattern-1},
4233 @var{new-insn-pattern-2}, etc.
4234
4235 The @var{preparation-statements} are similar to those statements that
4236 are specified for @code{define_expand} (@pxref{Expander Definitions})
4237 and are executed before the new RTL is generated to prepare for the
4238 generated code or emit some insns whose pattern is not fixed.  Unlike
4239 those in @code{define_expand}, however, these statements must not
4240 generate any new pseudo-registers.  Once reload has completed, they also
4241 must not allocate any space in the stack frame.
4242
4243 Patterns are matched against @var{insn-pattern} in two different
4244 circumstances.  If an insn needs to be split for delay slot scheduling
4245 or insn scheduling, the insn is already known to be valid, which means
4246 that it must have been matched by some @code{define_insn} and, if
4247 @code{reload_completed} is nonzero, is known to satisfy the constraints
4248 of that @code{define_insn}.  In that case, the new insn patterns must
4249 also be insns that are matched by some @code{define_insn} and, if
4250 @code{reload_completed} is nonzero, must also satisfy the constraints
4251 of those definitions.
4252
4253 As an example of this usage of @code{define_split}, consider the following
4254 example from @file{a29k.md}, which splits a @code{sign_extend} from
4255 @code{HImode} to @code{SImode} into a pair of shift insns:
4256
4257 @smallexample
4258 (define_split
4259   [(set (match_operand:SI 0 "gen_reg_operand" "")
4260         (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))]
4261   ""
4262   [(set (match_dup 0)
4263         (ashift:SI (match_dup 1)
4264                    (const_int 16)))
4265    (set (match_dup 0)
4266         (ashiftrt:SI (match_dup 0)
4267                      (const_int 16)))]
4268   "
4269 @{ operands[1] = gen_lowpart (SImode, operands[1]); @}")
4270 @end smallexample
4271
4272 When the combiner phase tries to split an insn pattern, it is always the
4273 case that the pattern is @emph{not} matched by any @code{define_insn}.
4274 The combiner pass first tries to split a single @code{set} expression
4275 and then the same @code{set} expression inside a @code{parallel}, but
4276 followed by a @code{clobber} of a pseudo-reg to use as a scratch
4277 register.  In these cases, the combiner expects exactly two new insn
4278 patterns to be generated.  It will verify that these patterns match some
4279 @code{define_insn} definitions, so you need not do this test in the
4280 @code{define_split} (of course, there is no point in writing a
4281 @code{define_split} that will never produce insns that match).
4282
4283 Here is an example of this use of @code{define_split}, taken from
4284 @file{rs6000.md}:
4285
4286 @smallexample
4287 (define_split
4288   [(set (match_operand:SI 0 "gen_reg_operand" "")
4289         (plus:SI (match_operand:SI 1 "gen_reg_operand" "")
4290                  (match_operand:SI 2 "non_add_cint_operand" "")))]
4291   ""
4292   [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3)))
4293    (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))]
4294 "
4295 @{
4296   int low = INTVAL (operands[2]) & 0xffff;
4297   int high = (unsigned) INTVAL (operands[2]) >> 16;
4298
4299   if (low & 0x8000)
4300     high++, low |= 0xffff0000;
4301
4302   operands[3] = GEN_INT (high << 16);
4303   operands[4] = GEN_INT (low);
4304 @}")
4305 @end smallexample
4306
4307 Here the predicate @code{non_add_cint_operand} matches any
4308 @code{const_int} that is @emph{not} a valid operand of a single add
4309 insn.  The add with the smaller displacement is written so that it
4310 can be substituted into the address of a subsequent operation.
4311
4312 An example that uses a scratch register, from the same file, generates
4313 an equality comparison of a register and a large constant:
4314
4315 @smallexample
4316 (define_split
4317   [(set (match_operand:CC 0 "cc_reg_operand" "")
4318         (compare:CC (match_operand:SI 1 "gen_reg_operand" "")
4319                     (match_operand:SI 2 "non_short_cint_operand" "")))
4320    (clobber (match_operand:SI 3 "gen_reg_operand" ""))]
4321   "find_single_use (operands[0], insn, 0)
4322    && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ
4323        || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)"
4324   [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4)))
4325    (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))]
4326   "
4327 @{
4328   /* Get the constant we are comparing against, C, and see what it
4329      looks like sign-extended to 16 bits.  Then see what constant
4330      could be XOR'ed with C to get the sign-extended value.  */
4331
4332   int c = INTVAL (operands[2]);
4333   int sextc = (c << 16) >> 16;
4334   int xorv = c ^ sextc;
4335
4336   operands[4] = GEN_INT (xorv);
4337   operands[5] = GEN_INT (sextc);
4338 @}")
4339 @end smallexample
4340
4341 To avoid confusion, don't write a single @code{define_split} that
4342 accepts some insns that match some @code{define_insn} as well as some
4343 insns that don't.  Instead, write two separate @code{define_split}
4344 definitions, one for the insns that are valid and one for the insns that
4345 are not valid.
4346
4347 The splitter is allowed to split jump instructions into sequence of
4348 jumps or create new jumps in while splitting non-jump instructions.  As
4349 the central flowgraph and branch prediction information needs to be updated,
4350 several restriction apply.
4351
4352 Splitting of jump instruction into sequence that over by another jump
4353 instruction is always valid, as compiler expect identical behavior of new
4354 jump.  When new sequence contains multiple jump instructions or new labels,
4355 more assistance is needed.  Splitter is required to create only unconditional
4356 jumps, or simple conditional jump instructions.  Additionally it must attach a
4357 @code{REG_BR_PROB} note to each conditional jump.  A global variable
4358 @code{split_branch_probability} hold the probability of original branch in case
4359 it was an simple conditional jump, @minus{}1 otherwise.  To simplify
4360 recomputing of edge frequencies, new sequence is required to have only
4361 forward jumps to the newly created labels.
4362
4363 @findex define_insn_and_split
4364 For the common case where the pattern of a define_split exactly matches the
4365 pattern of a define_insn, use @code{define_insn_and_split}.  It looks like
4366 this:
4367
4368 @smallexample
4369 (define_insn_and_split
4370   [@var{insn-pattern}]
4371   "@var{condition}"
4372   "@var{output-template}"
4373   "@var{split-condition}"