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