![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to md.texi CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to md.texi CVS log | Up to [GCC 2.x] / gcc |
1.1 root 1: @c Copyright (C) 1988, 1989, 1992 Free Software Foundation, Inc.
2: @c This is part of the GCC manual.
3: @c For copying conditions, see the file gcc.texi.
4:
5: @ifset INTERNALS
1.1.1.3 ! root 6: @node Machine Desc
1.1 root 7: @chapter Machine Descriptions
8: @cindex machine descriptions
9:
10: A machine description has two parts: a file of instruction patterns
11: (@file{.md} file) and a C header file of macro definitions.
12:
13: The @file{.md} file for a target machine contains a pattern for each
14: instruction that the target machine supports (or at least each instruction
15: that is worth telling the compiler about). It may also contain comments.
16: A semicolon causes the rest of the line to be a comment, unless the semicolon
17: is inside a quoted string.
18:
19: See the next chapter for information on the C header file.
20:
21: @menu
22: * Patterns:: How to write instruction patterns.
23: * Example:: An explained example of a @code{define_insn} pattern.
24: * RTL Template:: The RTL template defines what insns match a pattern.
25: * Output Template:: The output template says how to make assembler code
26: from such an insn.
27: * Output Statement:: For more generality, write C code to output
28: the assembler code.
29: * Constraints:: When not all operands are general operands.
30: * Standard Names:: Names mark patterns to use for code generation.
31: * Pattern Ordering:: When the order of patterns makes a difference.
32: * Dependent Patterns:: Having one pattern may make you need another.
33: * Jump Patterns:: Special considerations for patterns for jump insns.
34: * Insn Canonicalizations::Canonicalization of Instructions
35: * Peephole Definitions::Defining machine-specific peephole optimizations.
36: * Expander Definitions::Generating a sequence of several RTL insns
37: for a standard operation.
38: * Insn Splitting:: Splitting Instructions into Multiple Instructions
39: * Insn Attributes:: Specifying the value of attributes for generated insns.
40: @end menu
41:
42: @node Patterns, Example, Machine Desc, Machine Desc
43: @section Everything about Instruction Patterns
44: @cindex patterns
45: @cindex instruction patterns
46:
47: @findex define_insn
48: Each instruction pattern contains an incomplete RTL expression, with pieces
49: to be filled in later, operand constraints that restrict how the pieces can
50: be filled in, and an output pattern or C code to generate the assembler
51: output, all wrapped up in a @code{define_insn} expression.
52:
53: A @code{define_insn} is an RTL expression containing four or five operands:
54:
55: @enumerate
56: @item
57: An optional name. The presence of a name indicate that this instruction
58: pattern can perform a certain standard job for the RTL-generation
59: pass of the compiler. This pass knows certain names and will use
60: the instruction patterns with those names, if the names are defined
61: in the machine description.
62:
63: The absence of a name is indicated by writing an empty string
64: where the name should go. Nameless instruction patterns are never
65: used for generating RTL code, but they may permit several simpler insns
66: to be combined later on.
67:
68: Names that are not thus known and used in RTL-generation have no
69: effect; they are equivalent to no name at all.
70:
71: @item
72: The @dfn{RTL template} (@pxref{RTL Template}) is a vector of incomplete
73: RTL expressions which show what the instruction should look like. It is
74: incomplete because it may contain @code{match_operand},
75: @code{match_operator}, and @code{match_dup} expressions that stand for
76: operands of the instruction.
77:
78: If the vector has only one element, that element is the template for the
79: instruction pattern. If the vector has multiple elements, then the
80: instruction pattern is a @code{parallel} expression containing the
81: elements described.
82:
83: @item
84: @cindex pattern conditions
85: @cindex conditions, in patterns
86: A condition. This is a string which contains a C expression that is
87: the final test to decide whether an insn body matches this pattern.
88:
89: @cindex named patterns and conditions
90: For a named pattern, the condition (if present) may not depend on
91: the data in the insn being matched, but only the target-machine-type
92: flags. The compiler needs to test these conditions during
93: initialization in order to learn exactly which named instructions are
94: available in a particular run.
95:
96: @findex operands
97: For nameless patterns, the condition is applied only when matching an
98: individual insn, and only after the insn has matched the pattern's
99: recognition template. The insn's operands may be found in the vector
100: @code{operands}.
101:
102: @item
103: The @dfn{output template}: a string that says how to output matching
104: insns as assembler code. @samp{%} in this string specifies where
105: to substitute the value of an operand. @xref{Output Template}.
106:
107: When simple substitution isn't general enough, you can specify a piece
108: of C code to compute the output. @xref{Output Statement}.
109:
110: @item
111: Optionally, a vector containing the values of attributes for insns matching
112: this pattern. @xref{Insn Attributes}.
113: @end enumerate
114:
115: @node Example, RTL Template, Patterns, Machine Desc
116: @section Example of @code{define_insn}
117: @cindex @code{define_insn} example
118:
119: Here is an actual example of an instruction pattern, for the 68000/68020.
120:
121: @example
122: (define_insn "tstsi"
123: [(set (cc0)
124: (match_operand:SI 0 "general_operand" "rm"))]
125: ""
126: "*
127: @{ if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
128: return \"tstl %0\";
129: return \"cmpl #0,%0\"; @}")
130: @end example
131:
132: This is an instruction that sets the condition codes based on the value of
133: a general operand. It has no condition, so any insn whose RTL description
134: has the form shown may be handled according to this pattern. The name
135: @samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation
136: pass that, when it is necessary to test such a value, an insn to do so
137: can be constructed using this pattern.
138:
139: The output control string is a piece of C code which chooses which
140: output template to return based on the kind of operand and the specific
141: type of CPU for which code is being generated.
142:
143: @samp{"rm"} is an operand constraint. Its meaning is explained below.
144:
145: @node RTL Template, Output Template, Example, Machine Desc
146: @section RTL Template for Generating and Recognizing Insns
147: @cindex RTL insn template
148: @cindex generating insns
149: @cindex insns, generating
150: @cindex recognizing insns
151: @cindex insns, recognizing
152:
153: The RTL template is used to define which insns match the particular pattern
154: and how to find their operands. For named patterns, the RTL template also
155: says how to construct an insn from specified operands.
156:
157: Construction involves substituting specified operands into a copy of the
158: template. Matching involves determining the values that serve as the
159: operands in the insn being matched. Both of these activities are
160: controlled by special expression types that direct matching and
161: substitution of the operands.
162:
163: @table @code
164: @findex match_operand
165: @item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint})
166: This expression is a placeholder for operand number @var{n} of
167: the insn. When constructing an insn, operand number @var{n}
168: will be substituted at this point. When matching an insn, whatever
169: appears at this position in the insn will be taken as operand
170: number @var{n}; but it must satisfy @var{predicate} or this instruction
171: pattern will not match at all.
172:
173: Operand numbers must be chosen consecutively counting from zero in
174: each instruction pattern. There may be only one @code{match_operand}
175: expression in the pattern for each operand number. Usually operands
176: are numbered in the order of appearance in @code{match_operand}
177: expressions.
178:
179: @var{predicate} is a string that is the name of a C function that accepts two
180: arguments, an expression and a machine mode. During matching, the
181: function will be called with the putative operand as the expression and
182: @var{m} as the mode argument (if @var{m} is not specified,
183: @code{VOIDmode} will be used, which normally causes @var{predicate} to accept
184: any mode). If it returns zero, this instruction pattern fails to match.
185: @var{predicate} may be an empty string; then it means no test is to be done
186: on the operand, so anything which occurs in this position is valid.
187:
188: Most of the time, @var{predicate} will reject modes other than @var{m}---but
189: not always. For example, the predicate @code{address_operand} uses
190: @var{m} as the mode of memory ref that the address should be valid for.
191: Many predicates accept @code{const_int} nodes even though their mode is
192: @code{VOIDmode}.
193:
194: @var{constraint} controls reloading and the choice of the best register
195: class to use for a value, as explained later (@pxref{Constraints}).
196:
197: People are often unclear on the difference between the constraint and the
198: predicate. The predicate helps decide whether a given insn matches the
199: pattern. The constraint plays no role in this decision; instead, it
200: controls various decisions in the case of an insn which does match.
201:
202: @findex general_operand
203: On CISC machines, @var{predicate} is most often @code{"general_operand"}.
204: This function checks that the putative operand is either a constant, a
205: register or a memory reference, and that it is valid for mode @var{m}.
206:
207: @findex register_operand
208: For an operand that must be a register, @var{predicate} should be
209: @code{"register_operand"}. It would be valid to use
210: @code{"general_operand"}, since the reload pass would copy any
211: non-register operands through registers, but this would make GNU CC do
212: extra work, it would prevent invariant operands (such as constant) from
213: being removed from loops, and it would prevent the register allocator
214: from doing the best possible job. On RISC machines, it is usually most
215: efficient to allow @var{predicate} to accept only objects that the
216: constraints allow.
217:
218: @findex immediate_operand
219: For an operand that must be a constant, either use
220: @code{"immediate_operand"} for @var{predicate}, or make the instruction
221: pattern's extra condition require a constant, or both. You cannot
222: expect the constraints to do this work! If the constraints allow only
223: constants, but the predicate allows something else, the compiler will
224: crash when that case arises.
225:
226: @findex match_scratch
227: @item (match_scratch:@var{m} @var{n} @var{constraint})
228: This expression is also a placeholder for operand number @var{n}
229: and indicates that operand must be a @code{scratch} or @code{reg}
230: expression.
231:
232: When matching patterns, this is completely equivalent to
233:
234: @example
235: (match_operand:@var{m} @var{n} "scratch_operand" @var{pred})
236: @end example
237:
238: but, when generating RTL, it produces a (@code{scratch}:@var{m})
239: expression.
240:
241: If the last few expressions in a @code{parallel} are @code{clobber}
242: expressions whose operands are either a hard register or
243: @code{match_scratch}, the combiner can add them when necessary.
244: @xref{Side Effects}.
245:
246: @findex match_dup
247: @item (match_dup @var{n})
248: This expression is also a placeholder for operand number @var{n}.
249: It is used when the operand needs to appear more than once in the
250: insn.
251:
252: In construction, @code{match_dup} behaves exactly like
253: @code{match_operand}: the operand is substituted into the insn being
254: constructed. But in matching, @code{match_dup} behaves differently.
255: It assumes that operand number @var{n} has already been determined by
256: a @code{match_operand} appearing earlier in the recognition template,
257: and it matches only an identical-looking expression.
258:
259: @findex match_operator
260: @item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}])
261: This pattern is a kind of placeholder for a variable RTL expression
262: code.
263:
264: When constructing an insn, it stands for an RTL expression whose
265: expression code is taken from that of operand @var{n}, and whose
266: operands are constructed from the patterns @var{operands}.
267:
268: When matching an expression, it matches an expression if the function
269: @var{predicate} returns nonzero on that expression @emph{and} the
270: patterns @var{operands} match the operands of the expression.
271:
272: Suppose that the function @code{commutative_operator} is defined as
273: follows, to match any expression whose operator is one of the
274: commutative arithmetic operators of RTL and whose mode is @var{mode}:
275:
276: @example
277: int
278: commutative_operator (x, mode)
279: rtx x;
280: enum machine_mode mode;
281: @{
282: enum rtx_code code = GET_CODE (x);
283: if (GET_MODE (x) != mode)
284: return 0;
285: return GET_RTX_CLASS (code) == 'c' || code == EQ || code == NE;
286: @}
287: @end example
288:
289: Then the following pattern will match any RTL expression consisting
290: of a commutative operator applied to two general operands:
291:
292: @example
293: (match_operator:SI 3 "commutative_operator"
294: [(match_operand:SI 1 "general_operand" "g")
295: (match_operand:SI 2 "general_operand" "g")])
296: @end example
297:
298: Here the vector @code{[@var{operands}@dots{}]} contains two patterns
299: because the expressions to be matched all contain two operands.
300:
301: When this pattern does match, the two operands of the commutative
302: operator are recorded as operands 1 and 2 of the insn. (This is done
303: by the two instances of @code{match_operand}.) Operand 3 of the insn
304: will be the entire commutative expression: use @code{GET_CODE
305: (operands[3])} to see which commutative operator was used.
306:
307: The machine mode @var{m} of @code{match_operator} works like that of
308: @code{match_operand}: it is passed as the second argument to the
309: predicate function, and that function is solely responsible for
310: deciding whether the expression to be matched ``has'' that mode.
311:
312: When constructing an insn, argument 3 of the gen-function will specify
313: the operation (i.e. the expression code) for the expression to be
314: made. It should be an RTL expression, whose expression code is copied
315: into a new expression whose operands are arguments 1 and 2 of the
316: gen-function. The subexpressions of argument 3 are not used;
317: only its expression code matters.
318:
319: When @code{match_operator} is used in a pattern for matching an insn,
320: it usually best if the operand number of the @code{match_operator}
321: is higher than that of the actual operands of the insn. This improves
322: register allocation because the register allocator often looks at
323: operands 1 and 2 of insns to see if it can do register tying.
324:
325: There is no way to specify constraints in @code{match_operator}. The
326: operand of the insn which corresponds to the @code{match_operator}
327: never has any constraints because it is never reloaded as a whole.
328: However, if parts of its @var{operands} are matched by
329: @code{match_operand} patterns, those parts may have constraints of
330: their own.
331:
1.1.1.3 ! root 332: @findex match_parallel
! 333: @item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}])
! 334: This pattern is a placeholder for an insn that consists of a
! 335: @code{parallel} expression with a variable number of elements. This
! 336: expression should only appear at the top level of an insn pattern.
! 337:
! 338: When constructing an insn, operand number @var{n} will be substituted at
! 339: this point. When matching an insn, it matches if the body of the insn
! 340: is a @code{parallel} expression with at least as many elements as the
! 341: vector of @var{subpat} expressions in the @code{match_parallel}, if each
! 342: @var{subpat} matches the corresponding element of the @code{parallel},
! 343: @emph{and} the function @var{predicate} returns nonzero on the
! 344: @code{parallel} that is the body of the insn. It is the responsibility
! 345: of the predicate to validate elements of the @code{parallel} beyond
! 346: those listed in the @code{match_parallel}.@refill
! 347:
! 348: A typical use of @code{match_parallel} is to match load and store
! 349: multiple expressions, which can contains a variable number of elements
! 350: in a @code{parallel}. For example,
! 351:
! 352: @example
! 353: (define_insn ""
! 354: [(match_parallel 0 "load_multiple_operation"
! 355: [(set (match_operand:SI 1 "gen_reg_operand" "=r")
! 356: (match_operand:SI 2 "memory_operand" "m"))
! 357: (use (reg:SI 179))
! 358: (clobber (reg:SI 179))])]
! 359: ""
! 360: "loadm 0,0,%1,%2")
! 361: @end example
! 362:
! 363: This example comes from @file{a29k.md}. The function
! 364: @code{load_multiple_operations} is defined in @file{a29k.c} and checks
! 365: that subsequent elements in the @code{parallel} are the same as the
! 366: @code{set} in the pattern, except that they are referencing subsequent
! 367: registers and memory locations.
! 368:
! 369: An insn that matches this pattern might look like:
! 370:
! 371: @example
! 372: (parallel [(set (reg:SI 20) (mem:SI (reg:SI 100)))
! 373: (use (reg:SI 179))
! 374: (clobber (reg:SI 179))
! 375: (set (reg:SI 21) (mem:SI (plus:SI (reg:SI 100) (const_int 4))))
! 376: (set (reg:SI 22) (mem:SI (plus:SI (reg:SI 100) (const_int 8))))])
! 377: @end example
! 378:
1.1 root 379: @findex address
380: @item (address (match_operand:@var{m} @var{n} "address_operand" ""))
381: This complex of expressions is a placeholder for an operand number
382: @var{n} in a ``load address'' instruction: an operand which specifies
383: a memory location in the usual way, but for which the actual operand
384: value used is the address of the location, not the contents of the
385: location.
386:
387: @code{address} expressions never appear in RTL code, only in machine
388: descriptions. And they are used only in machine descriptions that do
389: not use the operand constraint feature. When operand constraints are
390: in use, the letter @samp{p} in the constraint serves this purpose.
391:
392: @var{m} is the machine mode of the @emph{memory location being
393: addressed}, not the machine mode of the address itself. That mode is
394: always the same on a given target machine (it is @code{Pmode}, which
395: normally is @code{SImode}), so there is no point in mentioning it;
396: thus, no machine mode is written in the @code{address} expression. If
397: some day support is added for machines in which addresses of different
398: kinds of objects appear differently or are used differently (such as
399: the PDP-10), different formats would perhaps need different machine
400: modes and these modes might be written in the @code{address}
401: expression.
402: @end table
403:
404: @node Output Template, Output Statement, RTL Template, Machine Desc
405: @section Output Templates and Operand Substitution
406: @cindex output templates
407: @cindex operand substitution
408:
409: @cindex @samp{%} in template
410: @cindex percent sign
411: The @dfn{output template} is a string which specifies how to output the
412: assembler code for an instruction pattern. Most of the template is a
413: fixed string which is output literally. The character @samp{%} is used
414: to specify where to substitute an operand; it can also be used to
415: identify places where different variants of the assembler require
416: different syntax.
417:
418: In the simplest case, a @samp{%} followed by a digit @var{n} says to output
419: operand @var{n} at that point in the string.
420:
421: @samp{%} followed by a letter and a digit says to output an operand in an
422: alternate fashion. Four letters have standard, built-in meanings described
423: below. The machine description macro @code{PRINT_OPERAND} can define
424: additional letters with nonstandard meanings.
425:
426: @samp{%c@var{digit}} can be used to substitute an operand that is a
427: constant value without the syntax that normally indicates an immediate
428: operand.
429:
430: @samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of
431: the constant is negated before printing.
432:
433: @samp{%a@var{digit}} can be used to substitute an operand as if it were a
434: memory reference, with the actual operand treated as the address. This may
435: be useful when outputting a ``load address'' instruction, because often the
436: assembler syntax for such an instruction requires you to write the operand
437: as if it were a memory reference.
438:
439: @samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump
440: instruction.
441:
442: @samp{%} followed by a punctuation character specifies a substitution that
443: does not use an operand. Only one case is standard: @samp{%%} outputs a
444: @samp{%} into the assembler code. Other nonstandard cases can be
445: defined in the @code{PRINT_OPERAND} macro. You must also define
446: which punctuation characters are valid with the
447: @code{PRINT_OPERAND_PUNCT_VALID_P} macro.
448:
449: @cindex \
450: @cindex backslash
451: The template may generate multiple assembler instructions. Write the text
452: for the instructions, with @samp{\;} between them.
453:
454: @cindex matching operands
455: When the RTL contains two operands which are required by constraint to match
456: each other, the output template must refer only to the lower-numbered operand.
457: Matching operands are not always identical, and the rest of the compiler
458: arranges to put the proper RTL expression for printing into the lower-numbered
459: operand.
460:
461: One use of nonstandard letters or punctuation following @samp{%} is to
462: distinguish between different assembler languages for the same machine; for
463: example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax
464: requires periods in most opcode names, while MIT syntax does not. For
465: example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
466: syntax. The same file of patterns is used for both kinds of output syntax,
467: but the character sequence @samp{%.} is used in each place where Motorola
468: syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax
469: defines the sequence to output a period; the macro for MIT syntax defines
470: it to do nothing.
471:
472: @node Output Statement, Constraints, Output Template, Machine Desc
473: @section C Statements for Generating Assembler Output
474: @cindex output statements
475: @cindex C statements for assembler output
476: @cindex generating assembler output
477:
478: Often a single fixed template string cannot produce correct and efficient
479: assembler code for all the cases that are recognized by a single
480: instruction pattern. For example, the opcodes may depend on the kinds of
481: operands; or some unfortunate combinations of operands may require extra
482: machine instructions.
483:
484: If the output control string starts with a @samp{@@}, then it is actually
485: a series of templates, each on a separate line. (Blank lines and
486: leading spaces and tabs are ignored.) The templates correspond to the
487: pattern's constraint alternatives (@pxref{Multi-Alternative}). For example,
488: if a target machine has a two-address add instruction @samp{addr} to add
489: into a register and another @samp{addm} to add a register to memory, you
490: might write this pattern:
491:
492: @example
493: (define_insn "addsi3"
1.1.1.3 ! root 494: [(set (match_operand:SI 0 "general_operand" "=r,m")
1.1 root 495: (plus:SI (match_operand:SI 1 "general_operand" "0,0")
496: (match_operand:SI 2 "general_operand" "g,r")))]
497: ""
498: "@@
499: addr %1,%0
500: addm %1,%0")
501: @end example
502:
503: @cindex @code{*} in template
504: @cindex asterisk in template
505: If the output control string starts with a @samp{*}, then it is not an
506: output template but rather a piece of C program that should compute a
507: template. It should execute a @code{return} statement to return the
508: template-string you want. Most such templates use C string literals, which
509: require doublequote characters to delimit them. To include these
510: doublequote characters in the string, prefix each one with @samp{\}.
511:
512: The operands may be found in the array @code{operands}, whose C data type
513: is @code{rtx []}.
514:
515: It is very common to select different ways of generating assembler code
516: based on whether an immediate operand is within a certain range. Be
517: careful when doing this, because the result of @code{INTVAL} is an
518: integer on the host machine. If the host machine has more bits in an
519: @code{int} than the target machine has in the mode in which the constant
520: will be used, then some of the bits you get from @code{INTVAL} will be
521: superfluous. For proper results, you must carefully disregard the
522: values of those bits.
523:
524: @findex output_asm_insn
525: It is possible to output an assembler instruction and then go on to output
526: or compute more of them, using the subroutine @code{output_asm_insn}. This
527: receives two arguments: a template-string and a vector of operands. The
528: vector may be @code{operands}, or it may be another array of @code{rtx}
529: that you declare locally and initialize yourself.
530:
531: @findex which_alternative
532: When an insn pattern has multiple alternatives in its constraints, often
533: the appearance of the assembler code is determined mostly by which alternative
534: was matched. When this is so, the C code can test the variable
535: @code{which_alternative}, which is the ordinal number of the alternative
536: that was actually satisfied (0 for the first, 1 for the second alternative,
537: etc.).
538:
539: For example, suppose there are two opcodes for storing zero, @samp{clrreg}
540: for registers and @samp{clrmem} for memory locations. Here is how
541: a pattern could use @code{which_alternative} to choose between them:
542:
543: @example
544: (define_insn ""
1.1.1.3 ! root 545: [(set (match_operand:SI 0 "general_operand" "=r,m")
1.1 root 546: (const_int 0))]
547: ""
548: "*
549: return (which_alternative == 0
550: ? \"clrreg %0\" : \"clrmem %0\");
551: ")
552: @end example
553:
554: The example above, where the assembler code to generate was
555: @emph{solely} determined by the alternative, could also have been specified
556: as follows, having the output control string start with a @samp{@@}:
557:
558: @example
559: (define_insn ""
1.1.1.3 ! root 560: [(set (match_operand:SI 0 "general_operand" "=r,m")
1.1 root 561: (const_int 0))]
562: ""
563: "@@
564: clrreg %0
565: clrmem %0")
566: @end example
567:
568: @node Constraints, Standard Names, Output Statement, Machine Desc
569: @section Operand Constraints
570: @cindex operand constraints
571: @cindex constraints
572:
573: Each @code{match_operand} in an instruction pattern can specify a
574: constraint for the type of operands allowed. Constraints can say whether
575: an operand may be in a register, and which kinds of register; whether the
576: operand can be a memory reference, and which kinds of address; whether the
577: operand may be an immediate constant, and which possible values it may
578: have. Constraints can also require two operands to match.
579:
580: @menu
581: * Simple Constraints:: Basic use of constraints.
582: * Multi-Alternative:: When an insn has two alternative constraint-patterns.
583: * Class Preferences:: Constraints guide which hard register to put things in.
584: * Modifiers:: More precise control over effects of constraints.
585: * No Constraints:: Describing a clean machine without constraints.
586: @end menu
587:
588: @node Simple Constraints, Multi-Alternative, Constraints, Constraints
589: @subsection Simple Constraints
590: @cindex simple constraints
591:
592: The simplest kind of constraint is a string full of letters, each of
593: which describes one kind of operand that is permitted. Here are
594: the letters that are allowed:
595:
596: @table @asis
597: @cindex @samp{m} in constraint
598: @cindex memory references in constraints
599: @item @samp{m}
600: A memory operand is allowed, with any kind of address that the machine
601: supports in general.
602:
603: @cindex offsettable address
604: @cindex @samp{o} in constraint
605: @item @samp{o}
606: A memory operand is allowed, but only if the address is
607: @dfn{offsettable}. This means that adding a small integer (actually,
608: the width in bytes of the operand, as determined by its machine mode)
609: may be added to the address and the result is also a valid memory
610: address.
611:
612: @cindex autoincrement/decrement addressing
613: For example, an address which is constant is offsettable; so is an
614: address that is the sum of a register and a constant (as long as a
615: slightly larger constant is also within the range of address-offsets
616: supported by the machine); but an autoincrement or autodecrement
617: address is not offsettable. More complicated indirect/indexed
618: addresses may or may not be offsettable depending on the other
619: addressing modes that the machine supports.
620:
621: Note that in an output operand which can be matched by another
622: operand, the constraint letter @samp{o} is valid only when accompanied
623: by both @samp{<} (if the target machine has predecrement addressing)
624: and @samp{>} (if the target machine has preincrement addressing).
625:
626: @cindex @samp{V} in constraint
627: @item @samp{V}
628: A memory operand that is not offsettable. In other words, anything that
629: would fit the @samp{m} constraint but not the @samp{o} constraint.
630:
631: @cindex @samp{<} in constraint
632: @item @samp{<}
633: A memory operand with autodecrement addressing (either predecrement or
634: postdecrement) is allowed.
635:
636: @cindex @samp{>} in constraint
637: @item @samp{>}
638: A memory operand with autoincrement addressing (either preincrement or
639: postincrement) is allowed.
640:
641: @cindex @samp{r} in constraint
642: @cindex registers in constraints
643: @item @samp{r}
644: A register operand is allowed provided that it is in a general
645: register.
646:
647: @cindex @samp{d} in constraint
648: @item @samp{d}, @samp{a}, @samp{f}, @dots{}
649: Other letters can be defined in machine-dependent fashion to stand for
650: particular classes of registers. @samp{d}, @samp{a} and @samp{f} are
651: defined on the 68000/68020 to stand for data, address and floating
652: point registers.
653:
654: @cindex constants in constraints
655: @cindex @samp{i} in constraint
656: @item @samp{i}
657: An immediate integer operand (one with constant value) is allowed.
658: This includes symbolic constants whose values will be known only at
659: assembly time.
660:
661: @cindex @samp{n} in constraint
662: @item @samp{n}
663: An immediate integer operand with a known numeric value is allowed.
664: Many systems cannot support assembly-time constants for operands less
665: than a word wide. Constraints for these operands should use @samp{n}
666: rather than @samp{i}.
667:
668: @cindex @samp{I} in constraint
669: @item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}
670: Other letters in the range @samp{I} through @samp{P} may be defined in
671: a machine-dependent fashion to permit immediate integer operands with
672: explicit integer values in specified ranges. For example, on the
673: 68000, @samp{I} is defined to stand for the range of values 1 to 8.
674: This is the range permitted as a shift count in the shift
675: instructions.
676:
677: @cindex @samp{E} in constraint
678: @item @samp{E}
679: An immediate floating operand (expression code @code{const_double}) is
680: allowed, but only if the target floating point format is the same as
681: that of the host machine (on which the compiler is running).
682:
683: @cindex @samp{F} in constraint
684: @item @samp{F}
685: An immediate floating operand (expression code @code{const_double}) is
686: allowed.
687:
688: @cindex @samp{G} in constraint
689: @cindex @samp{H} in constraint
690: @item @samp{G}, @samp{H}
691: @samp{G} and @samp{H} may be defined in a machine-dependent fashion to
692: permit immediate floating operands in particular ranges of values.
693:
694: @cindex @samp{s} in constraint
695: @item @samp{s}
696: An immediate integer operand whose value is not an explicit integer is
697: allowed.
698:
699: This might appear strange; if an insn allows a constant operand with a
700: value not known at compile time, it certainly must allow any known
701: value. So why use @samp{s} instead of @samp{i}? Sometimes it allows
702: better code to be generated.
703:
704: For example, on the 68000 in a fullword instruction it is possible to
705: use an immediate operand; but if the immediate value is between -128
706: and 127, better code results from loading the value into a register and
707: using the register. This is because the load into the register can be
708: done with a @samp{moveq} instruction. We arrange for this to happen
709: by defining the letter @samp{K} to mean ``any integer outside the
710: range -128 to 127'', and then specifying @samp{Ks} in the operand
711: constraints.
712:
713: @cindex @samp{g} in constraint
714: @item @samp{g}
715: Any register, memory or immediate integer operand is allowed, except for
716: registers that are not general registers.
717:
718: @cindex @samp{X} in constraint
719: @item @samp{X}
720: Any operand whatsoever is allowed, even if it does not satisfy
721: @code{general_operand}. This is normally used in the constraint of
722: a @code{match_scratch} when certain alternatives will not actually
723: require a scratch register.
724:
725: @cindex @samp{0} in constraint
726: @cindex digits in constraint
727: @item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{9}
728: An operand that matches the specified operand number is allowed. If a
729: digit is used together with letters within the same alternative, the
730: digit should come last.
731:
732: @cindex matching constraint
733: @cindex constraint, matching
734: This is called a @dfn{matching constraint} and what it really means is
735: that the assembler has only a single operand that fills two roles
736: considered separate in the RTL insn. For example, an add insn has two
1.1.1.3 ! root 737: input operands and one output operand in the RTL, but on most CISC
! 738: machines an add instruction really has only two operands, one of them an
! 739: input-output operand:
! 740:
! 741: @example
! 742: addl #35,r12
! 743: @end example
1.1 root 744:
1.1.1.3 ! root 745: Matching constraints are used in these circumstances.
1.1 root 746: More precisely, the two operands that match must include one input-only
747: operand and one output-only operand. Moreover, the digit must be a
748: smaller number than the number of the operand that uses it in the
749: constraint.
750:
751: For operands to match in a particular case usually means that they
752: are identical-looking RTL expressions. But in a few special cases
753: specific kinds of dissimilarity are allowed. For example, @code{*x}
754: as an input operand will match @code{*x++} as an output operand.
755: For proper results in such cases, the output template should always
756: use the output-operand's number when printing the operand.
757:
758: @cindex load address instruction
759: @cindex push address instruction
760: @cindex address constraints
761: @cindex @samp{p} in constraint
762: @item @samp{p}
763: An operand that is a valid memory address is allowed. This is
764: for ``load address'' and ``push address'' instructions.
765:
766: @findex address_operand
767: @samp{p} in the constraint must be accompanied by @code{address_operand}
768: as the predicate in the @code{match_operand}. This predicate interprets
769: the mode specified in the @code{match_operand} as the mode of the memory
770: reference for which the address would be valid.
771:
772: @cindex extensible constraints
773: @cindex @samp{Q}, in constraint
774: @item @samp{Q}, @samp{R}, @samp{S}, @dots{} @samp{U}
775: Letters in the range @samp{Q} through @samp{U} may be defined in a
776: machine-dependent fashion to stand for arbitrary operand types.
777: The machine description macro @code{EXTRA_CONSTRAINT} is passed the
778: operand as its first argument and the constraint letter as its
779: second operand.
780:
781: A typical use for this would be to distinguish certain types of
782: memory references that affect other insn operands.
783:
784: Do not define these constraint letters to accept register references
785: (@code{reg}); the reload pass does not expect this and would not handle
786: it properly.
787: @end table
788:
789: In order to have valid assembler code, each operand must satisfy
790: its constraint. But a failure to do so does not prevent the pattern
791: from applying to an insn. Instead, it directs the compiler to modify
792: the code so that the constraint will be satisfied. Usually this is
793: done by copying an operand into a register.
794:
795: Contrast, therefore, the two instruction patterns that follow:
796:
797: @example
798: (define_insn ""
1.1.1.3 ! root 799: [(set (match_operand:SI 0 "general_operand" "=r")
1.1 root 800: (plus:SI (match_dup 0)
801: (match_operand:SI 1 "general_operand" "r")))]
802: ""
803: "@dots{}")
804: @end example
805:
806: @noindent
807: which has two operands, one of which must appear in two places, and
808:
809: @example
810: (define_insn ""
1.1.1.3 ! root 811: [(set (match_operand:SI 0 "general_operand" "=r")
1.1 root 812: (plus:SI (match_operand:SI 1 "general_operand" "0")
813: (match_operand:SI 2 "general_operand" "r")))]
814: ""
815: "@dots{}")
816: @end example
817:
818: @noindent
819: which has three operands, two of which are required by a constraint to be
820: identical. If we are considering an insn of the form
821:
822: @example
823: (insn @var{n} @var{prev} @var{next}
824: (set (reg:SI 3)
825: (plus:SI (reg:SI 6) (reg:SI 109)))
826: @dots{})
827: @end example
828:
829: @noindent
830: the first pattern would not apply at all, because this insn does not
831: contain two identical subexpressions in the right place. The pattern would
832: say, ``That does not look like an add instruction; try other patterns.''
833: The second pattern would say, ``Yes, that's an add instruction, but there
834: is something wrong with it.'' It would direct the reload pass of the
835: compiler to generate additional insns to make the constraint true. The
836: results might look like this:
837:
838: @example
839: (insn @var{n2} @var{prev} @var{n}
840: (set (reg:SI 3) (reg:SI 6))
841: @dots{})
842:
843: (insn @var{n} @var{n2} @var{next}
844: (set (reg:SI 3)
845: (plus:SI (reg:SI 3) (reg:SI 109)))
846: @dots{})
847: @end example
848:
849: It is up to you to make sure that each operand, in each pattern, has
850: constraints that can handle any RTL expression that could be present for
851: that operand. (When multiple alternatives are in use, each pattern must,
852: for each possible combination of operand expressions, have at least one
853: alternative which can handle that combination of operands.) The
854: constraints don't need to @emph{allow} any possible operand---when this is
855: the case, they do not constrain---but they must at least point the way to
856: reloading any possible operand so that it will fit.
857:
858: @itemize @bullet
859: @item
860: If the constraint accepts whatever operands the predicate permits,
861: there is no problem: reloading is never necessary for this operand.
862:
863: For example, an operand whose constraints permit everything except
864: registers is safe provided its predicate rejects registers.
865:
866: An operand whose predicate accepts only constant values is safe
867: provided its constraints include the letter @samp{i}. If any possible
868: constant value is accepted, then nothing less than @samp{i} will do;
869: if the predicate is more selective, then the constraints may also be
870: more selective.
871:
872: @item
873: Any operand expression can be reloaded by copying it into a register.
874: So if an operand's constraints allow some kind of register, it is
875: certain to be safe. It need not permit all classes of registers; the
876: compiler knows how to copy a register into another register of the
877: proper class in order to make an instruction valid.
878:
879: @cindex nonoffsettable memory reference
880: @cindex memory reference, nonoffsettable
881: @item
882: A nonoffsettable memory reference can be reloaded by copying the
883: address into a register. So if the constraint uses the letter
884: @samp{o}, all memory references are taken care of.
885:
886: @item
887: A constant operand can be reloaded by allocating space in memory to
888: hold it as preinitialized data. Then the memory reference can be used
889: in place of the constant. So if the constraint uses the letters
890: @samp{o} or @samp{m}, constant operands are not a problem.
891:
892: @item
893: If the constraint permits a constant and a pseudo register used in an insn
894: was not allocated to a hard register and is equivalent to a constant,
895: the register will be replaced with the constant. If the predicate does
896: not permit a constant and the insn is re-recognized for some reason, the
897: compiler will crash. Thus the predicate must always recognize any
898: objects allowed by the constraint.
899: @end itemize
900:
901: If the operand's predicate can recognize registers, but the constraint does
902: not permit them, it can make the compiler crash. When this operand happens
903: to be a register, the reload pass will be stymied, because it does not know
904: how to copy a register temporarily into memory.
905:
906: @node Multi-Alternative, Class Preferences, Simple Constraints, Constraints
907: @subsection Multiple Alternative Constraints
908: @cindex multiple alternative constraints
909:
910: Sometimes a single instruction has multiple alternative sets of possible
911: operands. For example, on the 68000, a logical-or instruction can combine
912: register or an immediate value into memory, or it can combine any kind of
913: operand into a register; but it cannot combine one memory location into
914: another.
915:
916: These constraints are represented as multiple alternatives. An alternative
917: can be described by a series of letters for each operand. The overall
918: constraint for an operand is made from the letters for this operand
919: from the first alternative, a comma, the letters for this operand from
920: the second alternative, a comma, and so on until the last alternative.
921: Here is how it is done for fullword logical-or on the 68000:
922:
923: @example
924: (define_insn "iorsi3"
925: [(set (match_operand:SI 0 "general_operand" "=m,d")
926: (ior:SI (match_operand:SI 1 "general_operand" "%0,0")
927: (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
928: @dots{})
929: @end example
930:
931: The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
932: operand 1 (meaning it must match operand 0), and @samp{dKs} for operand
933: 2. The second alternative has @samp{d} (data register) for operand 0,
934: @samp{0} for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and
935: @samp{%} in the constraints apply to all the alternatives; their
936: meaning is explained in the next section (@pxref{Class Preferences}).
937:
938: If all the operands fit any one alternative, the instruction is valid.
939: Otherwise, for each alternative, the compiler counts how many instructions
940: must be added to copy the operands so that that alternative applies.
941: The alternative requiring the least copying is chosen. If two alternatives
942: need the same amount of copying, the one that comes first is chosen.
943: These choices can be altered with the @samp{?} and @samp{!} characters:
944:
945: @table @code
946: @cindex @samp{?} in constraint
947: @cindex question mark
948: @item ?
949: Disparage slightly the alternative that the @samp{?} appears in,
950: as a choice when no alternative applies exactly. The compiler regards
951: this alternative as one unit more costly for each @samp{?} that appears
952: in it.
953:
954: @cindex @samp{!} in constraint
955: @cindex exclamation point
956: @item !
957: Disparage severely the alternative that the @samp{!} appears in.
958: This alternative can still be used if it fits without reloading,
959: but if reloading is needed, some other alternative will be used.
960: @end table
961:
962: When an insn pattern has multiple alternatives in its constraints, often
963: the appearance of the assembler code is determined mostly by which
964: alternative was matched. When this is so, the C code for writing the
965: assembler code can use the variable @code{which_alternative}, which is
966: the ordinal number of the alternative that was actually satisfied (0 for
967: the first, 1 for the second alternative, etc.). @xref{Output Statement}.
968:
969: @node Class Preferences, Modifiers, Multi-Alternative, Constraints
970: @subsection Register Class Preferences
971: @cindex class preference constraints
972: @cindex register class preference constraints
973:
974: @cindex voting between constraint alternatives
975: The operand constraints have another function: they enable the compiler
976: to decide which kind of hardware register a pseudo register is best
977: allocated to. The compiler examines the constraints that apply to the
978: insns that use the pseudo register, looking for the machine-dependent
979: letters such as @samp{d} and @samp{a} that specify classes of registers.
980: The pseudo register is put in whichever class gets the most ``votes''.
981: The constraint letters @samp{g} and @samp{r} also vote: they vote in
982: favor of a general register. The machine description says which registers
983: are considered general.
984:
985: Of course, on some machines all registers are equivalent, and no register
986: classes are defined. Then none of this complexity is relevant.
987:
988: @node Modifiers, No Constraints, Class Preferences, Constraints
989: @subsection Constraint Modifier Characters
990: @cindex modifiers in constraints
991: @cindex constraint modifier characters
992:
993: @table @samp
994: @cindex @samp{=} in constraint
995: @item =
996: Means that this operand is write-only for this instruction: the previous
997: value is discarded and replaced by output data.
998:
999: @cindex @samp{+} in constraint
1000: @item +
1001: Means that this operand is both read and written by the instruction.
1002:
1003: When the compiler fixes up the operands to satisfy the constraints,
1004: it needs to know which operands are inputs to the instruction and
1005: which are outputs from it. @samp{=} identifies an output; @samp{+}
1006: identifies an operand that is both input and output; all other operands
1007: are assumed to be input only.
1008:
1009: @cindex @samp{&} in constraint
1010: @item &
1011: Means (in a particular alternative) that this operand is written
1012: before the instruction is finished using the input operands.
1013: Therefore, this operand may not lie in a register that is used as an
1014: input operand or as part of any memory address.
1015:
1016: @samp{&} applies only to the alternative in which it is written. In
1017: constraints with multiple alternatives, sometimes one alternative
1018: requires @samp{&} while others do not. See, for example, the
1019: @samp{movdf} insn of the 68000.
1020:
1021: @samp{&} does not obviate the need to write @samp{=}.
1022:
1023: @cindex @samp{%} in constraint
1024: @item %
1025: Declares the instruction to be commutative for this operand and the
1026: following operand. This means that the compiler may interchange the
1027: two operands if that is the cheapest way to make all operands fit the
1028: constraints. This is often used in patterns for addition instructions
1029: that really have only two operands: the result must go in one of the
1030: arguments. Here for example, is how the 68000 halfword-add
1031: instruction is defined:
1032:
1033: @example
1034: (define_insn "addhi3"
1035: [(set (match_operand:HI 0 "general_operand" "=m,r")
1036: (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
1037: (match_operand:HI 2 "general_operand" "di,g")))]
1038: @dots{})
1039: @end example
1040:
1041: @cindex @samp{#} in constraint
1042: @item #
1043: Says that all following characters, up to the next comma, are to be
1044: ignored as a constraint. They are significant only for choosing
1045: register preferences.
1046:
1047: @cindex @samp{*} in constraint
1048: @item *
1049: Says that the following character should be ignored when choosing
1050: register preferences. @samp{*} has no effect on the meaning of the
1051: constraint as a constraint, and no effect on reloading.
1052:
1053: Here is an example: the 68000 has an instruction to sign-extend a
1054: halfword in a data register, and can also sign-extend a value by
1055: copying it into an address register. While either kind of register is
1056: acceptable, the constraints on an address-register destination are
1057: less strict, so it is best if register allocation makes an address
1058: register its goal. Therefore, @samp{*} is used so that the @samp{d}
1059: constraint letter (for data register) is ignored when computing
1060: register preferences.
1061:
1062: @example
1063: (define_insn "extendhisi2"
1064: [(set (match_operand:SI 0 "general_operand" "=*d,a")
1065: (sign_extend:SI
1066: (match_operand:HI 1 "general_operand" "0,g")))]
1067: @dots{})
1068: @end example
1069: @end table
1070:
1071: @node No Constraints,, Modifiers, Constraints
1072: @subsection Not Using Constraints
1073: @cindex no constraints
1074: @cindex not using constraints
1075:
1076: Some machines are so clean that operand constraints are not required. For
1077: example, on the Vax, an operand valid in one context is valid in any other
1078: context. On such a machine, every operand constraint would be @samp{g},
1079: excepting only operands of ``load address'' instructions which are
1080: written as if they referred to a memory location's contents but actual
1081: refer to its address. They would have constraint @samp{p}.
1082:
1083: @cindex empty constraints
1084: For such machines, instead of writing @samp{g} and @samp{p} for all
1085: the constraints, you can choose to write a description with empty constraints.
1086: Then you write @samp{""} for the constraint in every @code{match_operand}.
1087: Address operands are identified by writing an @code{address} expression
1088: around the @code{match_operand}, not by their constraints.
1089:
1090: When the machine description has just empty constraints, certain parts
1091: of compilation are skipped, making the compiler faster. However,
1092: few machines actually do not need constraints; all machine descriptions
1093: now in existence use constraints.
1094:
1095: @node Standard Names, Pattern Ordering, Constraints, Machine Desc
1096: @section Standard Names for Patterns Used in Generation
1097: @cindex standard pattern names
1098: @cindex pattern names
1099: @cindex names, pattern
1100:
1101: Here is a table of the instruction names that are meaningful in the RTL
1102: generation pass of the compiler. Giving one of these names to an
1103: instruction pattern tells the RTL generation pass that it can use the
1104: pattern in to accomplish a certain task.
1105:
1106: @table @asis
1107: @cindex @code{mov@var{m}} instruction pattern
1108: @item @samp{mov@var{m}}
1109: Here @var{m} stands for a two-letter machine mode name, in lower case.
1110: This instruction pattern moves data with that machine mode from operand
1111: 1 to operand 0. For example, @samp{movsi} moves full-word data.
1112:
1113: If operand 0 is a @code{subreg} with mode @var{m} of a register whose
1114: own mode is wider than @var{m}, the effect of this instruction is
1115: to store the specified value in the part of the register that corresponds
1116: to mode @var{m}. The effect on the rest of the register is undefined.
1117:
1118: This class of patterns is special in several ways. First of all, each
1119: of these names @emph{must} be defined, because there is no other way
1120: to copy a datum from one place to another.
1121:
1122: Second, these patterns are not used solely in the RTL generation pass.
1123: Even the reload pass can generate move insns to copy values from stack
1124: slots into temporary registers. When it does so, one of the operands is
1125: a hard register and the other is an operand that can need to be reloaded
1126: into a register.
1127:
1128: @findex force_reg
1129: Therefore, when given such a pair of operands, the pattern must generate
1130: RTL which needs no reloading and needs no temporary registers---no
1131: registers other than the operands. For example, if you support the
1132: pattern with a @code{define_expand}, then in such a case the
1133: @code{define_expand} mustn't call @code{force_reg} or any other such
1134: function which might generate new pseudo registers.
1135:
1136: This requirement exists even for subword modes on a RISC machine where
1137: fetching those modes from memory normally requires several insns and
1138: some temporary registers. Look in @file{spur.md} to see how the
1139: requirement can be satisfied.
1140:
1141: @findex change_address
1142: During reload a memory reference with an invalid address may be passed
1143: as an operand. Such an address will be replaced with a valid address
1144: later in the reload pass. In this case, nothing may be done with the
1145: address except to use it as it stands. If it is copied, it will not be
1146: replaced with a valid address. No attempt should be made to make such
1147: an address into a valid address and no routine (such as
1148: @code{change_address}) that will do so may be called. Note that
1149: @code{general_operand} will fail when applied to such an address.
1150:
1151: @findex reload_in_progress
1152: The global variable @code{reload_in_progress} (which must be explicitly
1153: declared if required) can be used to determine whether such special
1154: handling is required.
1155:
1156: The variety of operands that have reloads depends on the rest of the
1157: machine description, but typically on a RISC machine these can only be
1158: pseudo registers that did not get hard registers, while on other
1159: machines explicit memory references will get optional reloads.
1160:
1161: If a scratch register is required to move an object to or from memory,
1162: it can be allocated using @code{gen_reg_rtx} prior to reload. But this
1163: is impossible during and after reload. If there are cases needing
1164: scratch registers after reload, you must define
1165: @code{SECONDARY_INPUT_RELOAD_CLASS} and/or
1166: @code{SECONDARY_OUTPUT_RELOAD_CLASS} to detect them, and provide
1167: patterns @samp{reload_in@var{m}} or @samp{reload_out@var{m}} to handle
1168: them. @xref{Register Classes}.
1169:
1170: The constraints on a @samp{move@var{m}} must permit moving any hard
1171: register to any other hard register provided that
1172: @code{HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and
1173: @code{REGISTER_MOVE_COST} applied to their classes returns a value of 2.
1174:
1175: It is obligatory to support floating point @samp{move@var{m}}
1176: instructions into and out of any registers that can hold fixed point
1177: values, because unions and structures (which have modes @code{SImode} or
1178: @code{DImode}) can be in those registers and they may have floating
1179: point members.
1180:
1181: There may also be a need to support fixed point @samp{move@var{m}}
1182: instructions in and out of floating point registers. Unfortunately, I
1183: have forgotten why this was so, and I don't know whether it is still
1184: true. If @code{HARD_REGNO_MODE_OK} rejects fixed point values in
1185: floating point registers, then the constraints of the fixed point
1186: @samp{move@var{m}} instructions must be designed to avoid ever trying to
1187: reload into a floating point register.
1188:
1.1.1.3 ! root 1189: @cindex @code{reload_in} instruction pattern
! 1190: @cindex @code{reload_out} instruction pattern
1.1 root 1191: @item @samp{reload_in@var{m}}
1192: @itemx @samp{reload_out@var{m}}
1193: Like @samp{mov@var{m}}, but used when a scratch register is required to
1194: move between operand 0 and operand 1. Operand 2 describes the scratch
1195: register. See the discussion of the @code{SECONDARY_RELOAD_CLASS}
1196: macro in @pxref{Register Classes}.
1197:
1198: @cindex @code{movstrict@var{m}} instruction pattern
1199: @item @samp{movstrict@var{m}}
1200: Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg}
1201: with mode @var{m} of a register whose natural mode is wider,
1202: the @samp{movstrict@var{m}} instruction is guaranteed not to alter
1203: any of the register except the part which belongs to mode @var{m}.
1204:
1.1.1.3 ! root 1205: @cindex @code{load_multiple} instruction pattern
! 1206: @item @code{load_multiple}
! 1207: Load several consecutive memory locations into consecutive registers.
! 1208: Operand 0 is the first of the consecutive registers, operand 1
! 1209: is the first memory location, and operand 2 is a constant: the
! 1210: number of consecutive registers.
! 1211:
! 1212: Define this only if the target machine really has such an instruction;
! 1213: do not define this if the most efficient way of loading consecutive
! 1214: registers from memory is to do them one at a time.
! 1215:
! 1216: On some machines, there are restrictions as to which consecutive
! 1217: registers can be stored into memory, such as particular starting or
! 1218: ending register numbers or only a range of valid counts. For those
! 1219: machines, use a @code{define_expand} (@pxref{Expander Definitions})
! 1220: and make the pattern fail if the restrictions are not met.
! 1221:
! 1222: Write the generated insn as a @code{parallel} with elements being a
! 1223: @code{set} of one register from the appropriate memory location (you may
! 1224: also need @code{use} or @code{clobber} elements). Use a
! 1225: @code{match_parallel} (@pxref{RTL Template}) to recognize the insn. See
! 1226: @file{a29k.md} and @file{rs6000.md} for examples of the use of this insn
! 1227: pattern.
! 1228:
! 1229: @cindex @samp{store_multiple} instruction pattern
! 1230: @item @code{store_multiple}
! 1231: Similar to @samp{load_multiple}, but store several consecutive registers
! 1232: into consecutive memory locations. Operand 0 is the first of the
! 1233: consecutive memory locations, operand 1 is the first register, and
! 1234: operand 2 is a constant: the number of consecutive registers.
! 1235:
1.1 root 1236: @cindex @code{add@var{m}3} instruction pattern
1237: @item @samp{add@var{m}3}
1238: Add operand 2 and operand 1, storing the result in operand 0. All operands
1239: must have mode @var{m}. This can be used even on two-address machines, by
1240: means of constraints requiring operands 1 and 0 to be the same location.
1241:
1242: @cindex @code{sub@var{m}3} instruction pattern
1243: @cindex @code{mul@var{m}3} instruction pattern
1244: @cindex @code{div@var{m}3} instruction pattern
1245: @cindex @code{udiv@var{m}3} instruction pattern
1246: @cindex @code{mod@var{m}3} instruction pattern
1247: @cindex @code{umod@var{m}3} instruction pattern
1248: @cindex @code{min@var{m}3} instruction pattern
1249: @cindex @code{max@var{m}3} instruction pattern
1250: @cindex @code{umin@var{m}3} instruction pattern
1251: @cindex @code{umax@var{m}3} instruction pattern
1252: @cindex @code{and@var{m}3} instruction pattern
1253: @cindex @code{ior@var{m}3} instruction pattern
1254: @cindex @code{xor@var{m}3} instruction pattern
1255: @item @samp{sub@var{m}3}, @samp{mul@var{m}3}
1256: @itemx @samp{div@var{m}3}, @samp{udiv@var{m}3}, @samp{mod@var{m}3}, @samp{umod@var{m}3}
1257: @itemx @samp{smin@var{m}3}, @samp{smax@var{m}3}, @samp{umin@var{m}3}, @samp{umax@var{m}3}
1258: @itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3}
1259: Similar, for other arithmetic operations.
1260:
1261: @cindex @code{mulhisi3} instruction pattern
1262: @item @samp{mulhisi3}
1263: Multiply operands 1 and 2, which have mode @code{HImode}, and store
1264: a @code{SImode} product in operand 0.
1265:
1266: @cindex @code{mulqihi3} instruction pattern
1267: @cindex @code{mulsidi3} instruction pattern
1268: @item @samp{mulqihi3}, @samp{mulsidi3}
1269: Similar widening-multiplication instructions of other widths.
1270:
1271: @cindex @code{umulqihi3} instruction pattern
1272: @cindex @code{umulhisi3} instruction pattern
1273: @cindex @code{umulsidi3} instruction pattern
1274: @item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
1275: Similar widening-multiplication instructions that do unsigned
1276: multiplication.
1277:
1278: @cindex @code{divmod@var{m}4} instruction pattern
1279: @item @samp{divmod@var{m}4}
1280: Signed division that produces both a quotient and a remainder.
1281: Operand 1 is divided by operand 2 to produce a quotient stored
1282: in operand 0 and a remainder stored in operand 3.
1283:
1284: For machines with an instruction that produces both a quotient and a
1285: remainder, provide a pattern for @samp{divmod@var{m}4} but do not
1286: provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}. This
1287: allows optimization in the relatively common case when both the quotient
1288: and remainder are computed.
1289:
1290: If an instruction that just produces a quotient or just a remainder
1291: exists and is more efficient than the instruction that produces both,
1292: write the output routine of @samp{divmod@var{m}4} to call
1293: @code{find_reg_note} and look for a @code{REG_UNUSED} note on the
1294: quotient or remainder and generate the appropriate instruction.
1295:
1296: @cindex @code{udivmod@var{m}4} instruction pattern
1297: @item @samp{udivmod@var{m}4}
1298: Similar, but does unsigned division.
1299:
1300: @cindex @code{ashl@var{m}3} instruction pattern
1301: @item @samp{ashl@var{m}3}
1.1.1.3 ! root 1302: Arithmetic-shift operand 1 left by a number of bits specified by operand
! 1303: 2, and store the result in operand 0. Here @var{m} is the mode of
! 1304: operand 0 and operand 1; operand 2's mode is specified by the
! 1305: instruction pattern, and the compiler will convert the operand to that
! 1306: mode before generating the instruction.
1.1 root 1307:
1308: @cindex @code{ashr@var{m}3} instruction pattern
1309: @cindex @code{lshl@var{m}3} instruction pattern
1310: @cindex @code{lshr@var{m}3} instruction pattern
1311: @cindex @code{rotl@var{m}3} instruction pattern
1312: @cindex @code{rotr@var{m}3} instruction pattern
1313: @item @samp{ashr@var{m}3}, @samp{lshl@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3}
1.1.1.3 ! root 1314: Other shift and rotate instructions, analogous to the
! 1315: @code{ashl@var{m}3} instructions.
1.1 root 1316:
1317: Logical and arithmetic left shift are the same. Machines that do not
1318: allow negative shift counts often have only one instruction for
1319: shifting left. On such machines, you should define a pattern named
1320: @samp{ashl@var{m}3} and leave @samp{lshl@var{m}3} undefined.
1321:
1322: @cindex @code{neg@var{m}2} instruction pattern
1323: @item @samp{neg@var{m}2}
1324: Negate operand 1 and store the result in operand 0.
1325:
1326: @cindex @code{abs@var{m}2} instruction pattern
1327: @item @samp{abs@var{m}2}
1328: Store the absolute value of operand 1 into operand 0.
1329:
1330: @cindex @code{sqrt@var{m}2} instruction pattern
1331: @item @samp{sqrt@var{m}2}
1332: Store the square root of operand 1 into operand 0.
1333:
1.1.1.3 ! root 1334: The @code{sqrt} built-in function of C always uses the mode which
! 1335: corresponds to the C data type @code{double}.
! 1336:
1.1 root 1337: @cindex @code{ffs@var{m}2} instruction pattern
1338: @item @samp{ffs@var{m}2}
1339: Store into operand 0 one plus the index of the least significant 1-bit
1340: of operand 1. If operand 1 is zero, store zero. @var{m} is the mode
1341: of operand 0; operand 1's mode is specified by the instruction
1342: pattern, and the compiler will convert the operand to that mode before
1343: generating the instruction.
1344:
1.1.1.3 ! root 1345: The @code{ffs} built-in function of C always uses the mode which
! 1346: corresponds to the C data type @code{int}.
! 1347:
1.1 root 1348: @cindex @code{one_cmpl@var{m}2} instruction pattern
1349: @item @samp{one_cmpl@var{m}2}
1350: Store the bitwise-complement of operand 1 into operand 0.
1351:
1352: @cindex @code{cmp@var{m}} instruction pattern
1353: @item @samp{cmp@var{m}}
1354: Compare operand 0 and operand 1, and set the condition codes.
1355: The RTL pattern should look like this:
1356:
1357: @example
1358: (set (cc0) (compare (match_operand:@var{m} 0 @dots{})
1359: (match_operand:@var{m} 1 @dots{})))
1360: @end example
1361:
1362: @cindex @code{tst@var{m}} instruction pattern
1363: @item @samp{tst@var{m}}
1364: Compare operand 0 against zero, and set the condition codes.
1365: The RTL pattern should look like this:
1366:
1367: @example
1368: (set (cc0) (match_operand:@var{m} 0 @dots{}))
1369: @end example
1370:
1371: @samp{tst@var{m}} patterns should not be defined for machines that do
1372: not use @code{(cc0)}. Doing so would confuse the optimizer since it
1373: would no longer be clear which @code{set} operations were comparisons.
1374: The @samp{cmp@var{m}} patterns should be used instead.
1375:
1376: @cindex @code{movstr@var{m}} instruction pattern
1377: @item @samp{movstr@var{m}}
1378: Block move instruction. The addresses of the destination and source
1379: strings are the first two operands, and both are in mode @code{Pmode}.
1380: The number of bytes to move is the third operand, in mode @var{m}.
1381:
1382: The fourth operand is the known shared alignment of the source and
1383: destination, in the form of a @code{const_int} rtx. Thus, if the
1384: compiler knows that both source and destination are word-aligned,
1385: it may provide the value 4 for this operand.
1386:
1387: These patterns need not give special consideration to the possibility
1388: that the source and destination strings might overlap.
1389:
1390: @cindex @code{cmpstr@var{m}} instruction pattern
1391: @item @samp{cmpstr@var{m}}
1392: Block compare instruction, with five operands. Operand 0 is the output;
1393: it has mode @var{m}. The remaining four operands are like the operands
1394: of @samp{movstr@var{m}}. The two memory blocks specified are compared
1395: byte by byte in lexicographic order. The effect of the instruction is
1396: to store a value in operand 0 whose sign indicates the result of the
1397: comparison.
1398:
1399: @cindex @code{float@var{mn}2} instruction pattern
1400: @item @samp{float@var{m}@var{n}2}
1401: Convert signed integer operand 1 (valid for fixed point mode @var{m}) to
1402: floating point mode @var{n} and store in operand 0 (which has mode
1403: @var{n}).
1404:
1405: @cindex @code{floatuns@var{mn}2} instruction pattern
1406: @item @samp{floatuns@var{m}@var{n}2}
1407: Convert unsigned integer operand 1 (valid for fixed point mode @var{m})
1408: to floating point mode @var{n} and store in operand 0 (which has mode
1409: @var{n}).
1410:
1411: @cindex @code{fix@var{mn}2} instruction pattern
1412: @item @samp{fix@var{m}@var{n}2}
1413: Convert operand 1 (valid for floating point mode @var{m}) to fixed
1414: point mode @var{n} as a signed number and store in operand 0 (which
1415: has mode @var{n}). This instruction's result is defined only when
1416: the value of operand 1 is an integer.
1417:
1418: @cindex @code{fixuns@var{mn}2} instruction pattern
1419: @item @samp{fixuns@var{m}@var{n}2}
1420: Convert operand 1 (valid for floating point mode @var{m}) to fixed
1421: point mode @var{n} as an unsigned number and store in operand 0 (which
1422: has mode @var{n}). This instruction's result is defined only when the
1423: value of operand 1 is an integer.
1424:
1425: @cindex @code{ftrunc@var{m}2} instruction pattern
1426: @item @samp{ftrunc@var{m}2}
1427: Convert operand 1 (valid for floating point mode @var{m}) to an
1428: integer value, still represented in floating point mode @var{m}, and
1429: store it in operand 0 (valid for floating point mode @var{m}).
1430:
1431: @cindex @code{fix_trunc@var{mn}2} instruction pattern
1432: @item @samp{fix_trunc@var{m}@var{n}2}
1433: Like @samp{fix@var{m}@var{n}2} but works for any floating point value
1434: of mode @var{m} by converting the value to an integer.
1435:
1436: @cindex @code{fixuns_trunc@var{mn}2} instruction pattern
1437: @item @samp{fixuns_trunc@var{m}@var{n}2}
1438: Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
1439: value of mode @var{m} by converting the value to an integer.
1440:
1441: @cindex @code{trunc@var{mn}} instruction pattern
1442: @item @samp{trunc@var{m}@var{n}}
1443: Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
1444: store in operand 0 (which has mode @var{n}). Both modes must be fixed
1445: point or both floating point.
1446:
1447: @cindex @code{extend@var{mn}} instruction pattern
1448: @item @samp{extend@var{m}@var{n}}
1449: Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
1450: store in operand 0 (which has mode @var{n}). Both modes must be fixed
1451: point or both floating point.
1452:
1453: @cindex @code{zero_extend@var{mn}} instruction pattern
1454: @item @samp{zero_extend@var{m}@var{n}}
1455: Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
1456: store in operand 0 (which has mode @var{n}). Both modes must be fixed
1457: point.
1458:
1459: @cindex @code{extv} instruction pattern
1460: @item @samp{extv}
1461: Extract a bit field from operand 1 (a register or memory operand), where
1462: operand 2 specifies the width in bits and operand 3 the starting bit,
1463: and store it in operand 0. Operand 0 must have mode @code{word_mode}.
1464: Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often
1465: @code{word_mode} is allowed only for registers. Operands 2 and 3 must
1466: be valid for @code{word_mode}.
1467:
1468: The RTL generation pass generates this instruction only with constants
1469: for operands 2 and 3.
1470:
1471: The bit-field value is sign-extended to a full word integer
1472: before it is stored in operand 0.
1473:
1474: @cindex @code{extzv} instruction pattern
1475: @item @samp{extzv}
1476: Like @samp{extv} except that the bit-field value is zero-extended.
1477:
1478: @cindex @code{insv} instruction pattern
1479: @item @samp{insv}
1480: Store operand 3 (which must be valid for @code{word_mode}) into a bit
1481: field in operand 0, where operand 1 specifies the width in bits and
1482: operand 2 the starting bit. Operand 0 may have mode @code{byte_mode} or
1483: @code{word_mode}; often @code{word_mode} is allowed only for registers.
1484: Operands 1 and 2 must be valid for @code{word_mode}.
1485:
1486: The RTL generation pass generates this instruction only with constants
1487: for operands 1 and 2.
1488:
1489: @cindex @code{s@var{cond}} instruction pattern
1490: @item @samp{s@var{cond}}
1491: Store zero or nonzero in the operand according to the condition codes.
1492: Value stored is nonzero iff the condition @var{cond} is true.
1493: @var{cond} is the name of a comparison operation expression code, such
1494: as @code{eq}, @code{lt} or @code{leu}.
1495:
1496: You specify the mode that the operand must have when you write the
1497: @code{match_operand} expression. The compiler automatically sees
1498: which mode you have used and supplies an operand of that mode.
1499:
1500: The value stored for a true condition must have 1 as its low bit, or
1501: else must be negative. Otherwise the instruction is not suitable and
1502: you should omit it from the machine description. You describe to the
1503: compiler exactly which value is stored by defining the macro
1504: @code{STORE_FLAG_VALUE} (@pxref{Misc}). If a description cannot be
1505: found that can be used for all the @samp{s@var{cond}} patterns, you
1506: should omit those operations from the machine description.
1507:
1508: These operations may fail, but should do so only in relatively
1509: uncommon cases; if they would fail for common cases involving
1510: integer comparisons, it is best to omit these patterns.
1511:
1512: If these operations are omitted, the compiler will usually generate code
1513: that copies the constant one to the target and branches around an
1514: assignment of zero to the target. If this code is more efficient than
1515: the potential instructions used for the @samp{s@var{cond}} pattern
1516: followed by those required to convert the result into a 1 or a zero in
1517: @code{SImode}, you should omit the @samp{s@var{cond}} operations from
1518: the machine description.
1519:
1520: @cindex @code{b@var{cond}} instruction pattern
1521: @item @samp{b@var{cond}}
1522: Conditional branch instruction. Operand 0 is a @code{label_ref} that
1523: refers to the label to jump to. Jump if the condition codes meet
1524: condition @var{cond}.
1525:
1526: Some machines do not follow the model assumed here where a comparison
1527: instruction is followed by a conditional branch instruction. In that
1528: case, the @samp{cmp@var{m}} (and @samp{tst@var{m}}) patterns should
1529: simply store the operands away and generate all the required insns in a
1530: @code{define_expand} (@pxref{Expander Definitions}) for the conditional
1531: branch operations. All calls to expand @samp{v@var{cond}} patterns are
1532: immediately preceded by calls to expand either a @samp{cmp@var{m}}
1533: pattern or a @samp{tst@var{m}} pattern.
1534:
1535: Machines that use a pseudo register for the condition code value, or
1536: where the mode used for the comparison depends on the condition being
1537: tested, should also use the above mechanism. @xref{Jump Patterns}
1538:
1539: The above discussion also applies to @samp{s@var{cond}} patterns.
1540:
1541: @cindex @code{call} instruction pattern
1542: @item @samp{call}
1543: Subroutine call instruction returning no value. Operand 0 is the
1544: function to call; operand 1 is the number of bytes of arguments pushed
1545: (in mode @code{SImode}, except it is normally a @code{const_int});
1546: operand 2 is the number of registers used as operands.
1547:
1548: On most machines, operand 2 is not actually stored into the RTL
1549: pattern. It is supplied for the sake of some RISC machines which need
1550: to put this information into the assembler code; they can put it in
1551: the RTL instead of operand 1.
1552:
1553: Operand 0 should be a @code{mem} RTX whose address is the address of the
1554: function. Note, however, that this address can be a @code{symbol_ref}
1555: expression even if it would not be a legitimate memory address on the
1556: target machine. If it is also not a valid argument for a call
1557: instruction, the pattern for this operation should be a
1558: @code{define_expand} (@pxref{Expander Definitions}) that places the
1559: address into a register and uses that register in the call instruction.
1560:
1561: @cindex @code{call_value} instruction pattern
1562: @item @samp{call_value}
1563: Subroutine call instruction returning a value. Operand 0 is the hard
1564: register in which the value is returned. There are three more
1565: operands, the same as the three operands of the @samp{call}
1566: instruction (but with numbers increased by one).
1567:
1568: Subroutines that return @code{BLKmode} objects use the @samp{call}
1569: insn.
1570:
1571: @cindex @code{call_pop} instruction pattern
1572: @cindex @code{call_value_pop} instruction pattern
1573: @item @samp{call_pop}, @samp{call_value_pop}
1574: Similar to @samp{call} and @samp{call_value}, except used if defined and
1575: if @code{RETURN_POPS_ARGS} is non-zero. They should emit a @code{parallel}
1576: that contains both the function call and a @code{set} to indicate the
1577: adjustment made to the frame pointer.
1578:
1579: For machines where @code{RETURN_POPS_ARGS} can be non-zero, the use of these
1580: patterns increases the number of functions for which the frame pointer
1581: can be eliminated, if desired.
1582:
1583: @cindex @code{return} instruction pattern
1584: @item @samp{return}
1585: Subroutine return instruction. This instruction pattern name should be
1586: defined only if a single instruction can do all the work of returning
1587: from a function.
1588:
1589: Like the @samp{mov@var{m}} patterns, this pattern is also used after the
1590: RTL generation phase. In this case it is to support machines where
1591: multiple instructions are usually needed to return from a function, but
1592: some class of functions only requires one instruction to implement a
1593: return. Normally, the applicable functions are those which do not need
1594: to save any registers or allocate stack space.
1595:
1596: @findex reload_completed
1597: @findex leaf_function_p
1598: For such machines, the condition specified in this pattern should only
1599: be true when @code{reload_completed} is non-zero and the function's
1600: epilogue would only be a single instruction. For machines with register
1601: windows, the routine @code{leaf_function_p} may be used to determine if
1602: a register window push is required.
1603:
1604: Machines that have conditional return instructions should define patterns
1605: such as
1606:
1607: @example
1608: (define_insn ""
1609: [(set (pc)
1610: (if_then_else (match_operator 0 "comparison_operator"
1611: [(cc0) (const_int 0)])
1612: (return)
1613: (pc)))]
1614: "@var{condition}"
1615: "@dots{}")
1616: @end example
1617:
1618: where @var{condition} would normally be the same condition specified on the
1619: named @samp{return} pattern.
1620:
1621: @cindex @code{nop} instruction pattern
1622: @item @samp{nop}
1623: No-op instruction. This instruction pattern name should always be defined
1624: to output a no-op in assembler code. @code{(const_int 0)} will do as an
1625: RTL pattern.
1626:
1627: @cindex @code{indirect_jump} instruction pattern
1628: @item @samp{indirect_jump}
1629: An instruction to jump to an address which is operand zero.
1630: This pattern name is mandatory on all machines.
1631:
1632: @cindex @code{casesi} instruction pattern
1633: @item @samp{casesi}
1634: Instruction to jump through a dispatch table, including bounds checking.
1635: This instruction takes five operands:
1636:
1637: @enumerate
1638: @item
1639: The index to dispatch on, which has mode @code{SImode}.
1640:
1641: @item
1642: The lower bound for indices in the table, an integer constant.
1643:
1644: @item
1645: The total range of indices in the table---the largest index
1646: minus the smallest one (both inclusive).
1647:
1648: @item
1649: A label that precedes the table itself.
1650:
1651: @item
1652: A label to jump to if the index has a value outside the bounds.
1653: (If the machine-description macro @code{CASE_DROPS_THROUGH} is defined,
1654: then an out-of-bounds index drops through to the code following
1655: the jump table instead of jumping to this label. In that case,
1656: this label is not actually used by the @samp{casesi} instruction,
1657: but it is always provided as an operand.)
1658: @end enumerate
1659:
1660: The table is a @code{addr_vec} or @code{addr_diff_vec} inside of a
1661: @code{jump_insn}. The number of elements in the table is one plus the
1662: difference between the upper bound and the lower bound.
1663:
1664: @cindex @code{tablejump} instruction pattern
1665: @item @samp{tablejump}
1666: Instruction to jump to a variable address. This is a low-level
1667: capability which can be used to implement a dispatch table when there
1668: is no @samp{casesi} pattern.
1669:
1670: This pattern requires two operands: the address or offset, and a label
1671: which should immediately precede the jump table. If the macro
1672: @code{CASE_VECTOR_PC_RELATIVE} is defined then the first operand is an
1673: offset which counts from the address of the table; otherwise, it is an
1.1.1.3 ! root 1674: absolute address to jump to. In either case, the first operand has
! 1675: mode @code{Pmode}.
1.1 root 1676:
1677: The @samp{tablejump} insn is always the last insn before the jump
1678: table it uses. Its assembler code normally has no need to use the
1679: second operand, but you should incorporate it in the RTL pattern so
1680: that the jump optimizer will not delete the table as unreachable code.
1.1.1.3 ! root 1681:
! 1682: @cindex @code{save_stack_block} instruction pattern
! 1683: @cindex @code{save_stack_function} instruction pattern
! 1684: @cindex @code{save_stack_nonlocal} instruction pattern
! 1685: @cindex @code{restore_stack_block} instruction pattern
! 1686: @cindex @code{restore_stack_function} instruction pattern
! 1687: @cindex @code{restore_stack_nonlocal} instruction pattern
! 1688: @item @samp{save_stack_block}
! 1689: @itemx @samp{save_stack_function}
! 1690: @itemx @samp{save_stack_nonlocal}
! 1691: @itemx @samp{restore_stack_block}
! 1692: @itemx @samp{restore_stack_function}
! 1693: @itemx @samp{restore_stack_nonlocal}
! 1694: Most machines save and restore the stack pointer by copying it to or
! 1695: from an object of mode @code{Pmode}. Do not define these patterns on
! 1696: such machines.
! 1697:
! 1698: Some machines require special handling for stack pointer saves and
! 1699: restores. On those machines, define the patterns corresponding to the
! 1700: non-standard cases by using a @code{define_expand} (@pxref{Expander
! 1701: Definitions}) that produces the required insns. The three types of
! 1702: saves and restores are:
! 1703:
! 1704: @enumerate
! 1705: @item
! 1706: @samp{save_stack_block} saves the stack pointer at the start of a block
! 1707: that allocates a variable-sized object and @samp{restore_stack_block}
! 1708: restores the stack pointer when the block is exited.
! 1709:
! 1710: @item
! 1711: @samp{save_stack_function} and @samp{restore_stack_function} operate
! 1712: similarly for the outermost block of a function and are used when the
! 1713: function allocates variable-sized objects or calls @code{alloca}. Only
! 1714: the epilogue uses the restored stack pointer, allowing a simpler save or
! 1715: restore sequence on some machines.
! 1716:
! 1717: @item
! 1718: @samp{save_stack_nonlocal} is used in functions that contain labels
! 1719: branched to by nested functions. It saves the stack pointer in such a
! 1720: way that the inner function can use @samp{restore_stack_nonlocal} to
! 1721: restore the stack pointer. The compiler generates code to restore the
! 1722: frame and argument pointer registers, but some machines require saving
! 1723: and restoring additional data such as register window information or
! 1724: stack backchains. Place insns in these patterns to save and restore any
! 1725: such required data.
! 1726: @end enumerate
! 1727:
! 1728: When saving the stack pointer, operand 0 is the save area and operand 1
! 1729: is the stack pointer. The mode used to allocate the save area is the
! 1730: mode of operand 0. You must specify an integral mode, or
! 1731: @code{VOIDmode} if no save area is needed for a particular type of save
! 1732: (either because no save is needed or because a machine-specific save
! 1733: area can be used). Operand 0 is the stack pointer and operand 1 is the
! 1734: save area for restore operations. If @samp{save_stack_block} is
! 1735: defined, operand 0 must not be @code{VOIDmode} since these saves can be
! 1736: arbitrarily nested.
! 1737:
! 1738: A save area is a @code{mem} that is at a constant offset from
! 1739: @code{virtual_stack_vars_rtx} when the stack pointer is saved for use by
! 1740: nonlocal gotos and a @code{reg} in the other two cases.
! 1741:
! 1742: @cindex @code{allocate_stack} instruction pattern
! 1743: @item @samp{allocate_stack}
! 1744: Subtract operand 0 from the stack pointer to create space for
! 1745: for dynamically allocated data.
! 1746:
! 1747: Do not define this pattern if all that must be done is the subtraction.
! 1748: On some machines require other operations such as stack probes or
! 1749: maintaining the back chain. Define this pattern to emit those
! 1750: operations in addition to updating the stack pointer.
1.1 root 1751: @end table
1752:
1753: @node Pattern Ordering, Dependent Patterns, Standard Names, Machine Desc
1754: @section When the Order of Patterns Matters
1755: @cindex Pattern Ordering
1756: @cindex Ordering of Patterns
1757:
1758: Sometimes an insn can match more than one instruction pattern. Then the
1759: pattern that appears first in the machine description is the one used.
1760: Therefore, more specific patterns (patterns that will match fewer things)
1761: and faster instructions (those that will produce better code when they
1762: do match) should usually go first in the description.
1763:
1764: In some cases the effect of ordering the patterns can be used to hide
1765: a pattern when it is not valid. For example, the 68000 has an
1766: instruction for converting a fullword to floating point and another
1767: for converting a byte to floating point. An instruction converting
1768: an integer to floating point could match either one. We put the
1769: pattern to convert the fullword first to make sure that one will
1770: be used rather than the other. (Otherwise a large integer might
1771: be generated as a single-byte immediate quantity, which would not work.)
1772: Instead of using this pattern ordering it would be possible to make the
1773: pattern for convert-a-byte smart enough to deal properly with any
1774: constant value.
1775:
1776: @node Dependent Patterns, Jump Patterns, Pattern Ordering, Machine Desc
1777: @section Interdependence of Patterns
1778: @cindex Dependent Patterns
1779: @cindex Interdependence of Patterns
1780:
1781: Every machine description must have a named pattern for each of the
1782: conditional branch names @samp{b@var{cond}}. The recognition template
1783: must always have the form
1784:
1785: @example
1786: (set (pc)
1787: (if_then_else (@var{cond} (cc0) (const_int 0))
1788: (label_ref (match_operand 0 "" ""))
1789: (pc)))
1790: @end example
1791:
1792: @noindent
1793: In addition, every machine description must have an anonymous pattern
1794: for each of the possible reverse-conditional branches. Their templates
1795: look like
1796:
1797: @example
1798: (set (pc)
1799: (if_then_else (@var{cond} (cc0) (const_int 0))
1800: (pc)
1801: (label_ref (match_operand 0 "" ""))))
1802: @end example
1803:
1804: @noindent
1805: They are necessary because jump optimization can turn direct-conditional
1806: branches into reverse-conditional branches.
1807:
1808: It is often convenient to use the @code{match_operator} construct to
1809: reduce the number of patterns that must be specified for branches. For
1810: example,
1811:
1812: @example
1813: (define_insn ""
1814: [(set (pc)
1815: (if_then_else (match_operator 0 "comparison_operator"
1816: [(cc0) (const_int 0)])
1817: (pc)
1818: (label_ref (match_operand 1 "" ""))))]
1819: "@var{condition}"
1820: "@dots{}")
1821: @end example
1822:
1823: In some cases machines support instructions identical except for the
1824: machine mode of one or more operands. For example, there may be
1825: ``sign-extend halfword'' and ``sign-extend byte'' instructions whose
1826: patterns are
1827:
1828: @example
1829: (set (match_operand:SI 0 @dots{})
1830: (extend:SI (match_operand:HI 1 @dots{})))
1831:
1832: (set (match_operand:SI 0 @dots{})
1833: (extend:SI (match_operand:QI 1 @dots{})))
1834: @end example
1835:
1836: @noindent
1837: Constant integers do not specify a machine mode, so an instruction to
1838: extend a constant value could match either pattern. The pattern it
1839: actually will match is the one that appears first in the file. For correct
1840: results, this must be the one for the widest possible mode (@code{HImode},
1841: here). If the pattern matches the @code{QImode} instruction, the results
1842: will be incorrect if the constant value does not actually fit that mode.
1843:
1844: Such instructions to extend constants are rarely generated because they are
1845: optimized away, but they do occasionally happen in nonoptimized
1846: compilations.
1847:
1848: If a constraint in a pattern allows a constant, the reload pass may
1849: replace a register with a constant permitted by the constraint in some
1850: cases. Similarly for memory references. You must ensure that the
1851: predicate permits all objects allowed by the constraints to prevent the
1852: compiler from crashing.
1853:
1854: Because of this substitution, you should not provide separate patterns
1855: for increment and decrement instructions. Instead, they should be
1856: generated from the same pattern that supports register-register add
1857: insns by examining the operands and generating the appropriate machine
1858: instruction.
1859:
1860: @node Jump Patterns, Insn Canonicalizations, Dependent Patterns, Machine Desc
1861: @section Defining Jump Instruction Patterns
1862: @cindex jump instruction patterns
1863: @cindex defining jump instruction patterns
1864:
1865: For most machines, GNU CC assumes that the machine has a condition code.
1866: A comparison insn sets the condition code, recording the results of both
1867: signed and unsigned comparison of the given operands. A separate branch
1868: insn tests the condition code and branches or not according its value.
1869: The branch insns come in distinct signed and unsigned flavors. Many
1870: common machines, such as the Vax, the 68000 and the 32000, work this
1871: way.
1872:
1873: Some machines have distinct signed and unsigned compare instructions, and
1874: only one set of conditional branch instructions. The easiest way to handle
1875: these machines is to treat them just like the others until the final stage
1876: where assembly code is written. At this time, when outputting code for the
1877: compare instruction, peek ahead at the following branch using
1878: @code{next_cc0_user (insn)}. (The variable @code{insn} refers to the insn
1879: being output, in the output-writing code in an instruction pattern.) If
1880: the RTL says that is an unsigned branch, output an unsigned compare;
1881: otherwise output a signed compare. When the branch itself is output, you
1882: can treat signed and unsigned branches identically.
1883:
1884: The reason you can do this is that GNU CC always generates a pair of
1885: consecutive RTL insns, possibly separated by @code{note} insns, one to
1886: set the condition code and one to test it, and keeps the pair inviolate
1887: until the end.
1888:
1889: To go with this technique, you must define the machine-description macro
1890: @code{NOTICE_UPDATE_CC} to do @code{CC_STATUS_INIT}; in other words, no
1891: compare instruction is superfluous.
1892:
1893: Some machines have compare-and-branch instructions and no condition code.
1894: A similar technique works for them. When it is time to ``output'' a
1895: compare instruction, record its operands in two static variables. When
1896: outputting the branch-on-condition-code instruction that follows, actually
1897: output a compare-and-branch instruction that uses the remembered operands.
1898:
1899: It also works to define patterns for compare-and-branch instructions.
1900: In optimizing compilation, the pair of compare and branch instructions
1901: will be combined according to these patterns. But this does not happen
1902: if optimization is not requested. So you must use one of the solutions
1903: above in addition to any special patterns you define.
1904:
1905: In many RISC machines, most instructions do not affect the condition
1906: code and there may not even be a separate condition code register. On
1907: these machines, the restriction that the definition and use of the
1908: condition code be adjacent insns is not necessary and can prevent
1909: important optimizations. For example, on the IBM RS/6000, there is a
1910: delay for taken branches unless the condition code register is set three
1911: instructions earlier than the conditional branch. The instruction
1912: scheduler cannot perform this optimization if it is not permitted to
1913: separate the definition and use of the condition code register.
1914:
1915: On these machines, do not use @code{(cc0)}, but instead use a register
1916: to represent the condition code. If there is a specific condition code
1917: register in the machine, use a hard register. If the condition code or
1918: comparison result can be placed in any general register, or if there are
1919: multiple condition registers, use a pseudo register.
1920:
1921: @findex prev_cc0_setter
1922: @findex next_cc0_user
1923: On some machines, the type of branch instruction generated may depend on
1924: the way the condition code was produced; for example, on the 68k and
1925: Sparc, setting the condition code directly from an add or subtract
1926: instruction does not clear the overflow bit the way that a test
1927: instruction does, so a different branch instruction must be used for
1928: some conditional branches. For machines that use @code{(cc0)}, the set
1929: and use of the condition code must be adjacent (separated only by
1930: @code{note} insns) allowing flags in @code{cc_status} to be used.
1931: (@xref{Condition Code}.) Also, the comparison and branch insns can be
1932: located from each other by using the functions @code{prev_cc0_setter}
1933: and @code{next_cc0_user}.
1934:
1935: However, this is not true on machines that do not use @code{(cc0)}. On
1936: those machines, no assumptions can be made about the adjacency of the
1937: compare and branch insns and the above methods cannot be used. Instead,
1938: we use the machine mode of the condition code register to record
1939: different formats of the condition code register.
1940:
1941: Registers used to store the condition code value should have a mode that
1942: is in class @code{MODE_CC}. Normally, it will be @code{CCmode}. If
1943: additional modes are required (as for the add example mentioned above in
1944: the Sparc), define the macro @code{EXTRA_CC_MODES} to list the
1945: additional modes required (@pxref{Condition Code}). Also define
1946: @code{EXTRA_CC_NAMES} to list the names of those modes and
1947: @code{SELECT_CC_MODE} to choose a mode given an operand of a compare.
1948:
1949: If it is known during RTL generation that a different mode will be
1950: required (for example, if the machine has separate compare instructions
1951: for signed and unsigned quantities, like most IBM processors), they can
1952: be specified at that time.
1953:
1954: If the cases that require different modes would be made by instruction
1955: combination, the macro @code{SELECT_CC_MODE} determines which machine
1956: mode should be used for the comparison result. The patterns should be
1957: written using that mode. To support the case of the add on the Sparc
1958: discussed above, we have the pattern
1959:
1960: @example
1961: (define_insn ""
1962: [(set (reg:CC_NOOV 0)
1963: (compare:CC_NOOV (plus:SI (match_operand:SI 0 "register_operand" "%r")
1964: (match_operand:SI 1 "arith_operand" "rI"))
1965: (const_int 0)))]
1966: ""
1967: "@dots{}")
1968: @end example
1969:
1970: The @code{SELECT_CC_MODE} macro on the Sparc returns @code{CC_NOOVmode}
1971: for comparisons whose argument is a @code{plus}.
1972:
1973: @node Insn Canonicalizations, Peephole Definitions, Jump Patterns, Machine Desc
1974: @section Canonicalization of Instructions
1975: @cindex canonicalization of instructions
1976: @cindex insn canonicalization
1977:
1978: There are often cases where multiple RTL expressions could represent an
1.1.1.2 root 1979: operation performed by a single machine instruction. This situation is
1.1 root 1980: most commonly encountered with logical, branch, and multiply-accumulate
1981: instructions. In such cases, the compiler attempts to convert these
1982: multiple RTL expressions into a single canonical form to reduce the
1983: number of insn patterns required.
1984:
1985: In addition to algebraic simplifications, following canonicalizations
1986: are performed:
1987:
1988: @itemize @bullet
1989: @item
1990: For commutative and comparison operators, a constant is always made the
1991: second operand. If a machine only supports a constant as the second
1992: operand, only patterns that match a constant in the second operand need
1993: be supplied.
1994:
1995: @cindex @code{neg}, canonicalization of
1996: @cindex @code{not}, canonicalization of
1997: @cindex @code{mult}, canonicalization of
1998: @cindex @code{plus}, canonicalization of
1999: @cindex @code{minus}, canonicalization of
2000: For these operators, if only one operand is a @code{neg}, @code{not},
2001: @code{mult}, @code{plus}, or @code{minus} expression, it will be the
2002: first operand.
2003:
2004: @cindex @code{compare}, canonicalization of
2005: @item
2006: For the @code{compare} operator, a constant is always the second operand
2007: on machines where @code{cc0} is used (@pxref{Jump Patterns}). On other
2008: machines, there are rare cases where the compiler might want to construct
2009: a @code{compare} with a constant as the first operand. However, these
2010: cases are not common enough for it to be worthwhile to provide a pattern
2011: matching a constant as the first operand unless the machine actually has
2012: such an instruction.
2013:
2014: An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or
2015: @code{minus} is made the first operand under the same conditions as
2016: above.
2017:
2018: @item
2019: @code{(minus @var{x} (const_int @var{n}))} is converted to
2020: @code{(plus @var{x} (const_int @var{-n}))}.
2021:
2022: @item
2023: Within address computations (i.e., inside @code{mem}), a left shift is
2024: converted into the appropriate multiplication by a power of two.
2025:
2026: @cindex @code{ior}, canonicalization of
2027: @cindex @code{and}, canonicalization of
2028: @cindex De Morgan's law
2029: De`Morgan's Law is used to move bitwise negation inside a bitwise
2030: logical-and or logical-or operation. If this results in only one
2031: operand being a @code{not} expression, it will be the first one.
2032:
2033: A machine that has an instruction that performs a bitwise logical-and of one
2034: operand with the bitwise negation of the other should specify the pattern
2035: for that instruction as
2036:
2037: @example
2038: (define_insn ""
2039: [(set (match_operand:@var{m} 0 @dots{})
2040: (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
2041: (match_operand:@var{m} 2 @dots{})))]
2042: "@dots{}"
2043: "@dots{}")
2044: @end example
2045:
2046: @noindent
2047: Similarly, a pattern for a ``NAND'' instruction should be written
2048:
2049: @example
2050: (define_insn ""
2051: [(set (match_operand:@var{m} 0 @dots{})
2052: (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
2053: (not:@var{m} (match_operand:@var{m} 2 @dots{}))))]
2054: "@dots{}"
2055: "@dots{}")
2056: @end example
2057:
2058: In both cases, it is not necessary to include patterns for the many
2059: logically equivalent RTL expressions.
2060:
2061: @cindex @code{xor}, canonicalization of
2062: @item
2063: The only possible RTL expressions involving both bitwise exclusive-or
2064: and bitwise negation are @code{(xor:@var{m} @var{x}) @var{y})}
2065: and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}.@refill
2066:
2067: @item
2068: The sum of three items, one of which is a constant, will only appear in
2069: the form
2070:
2071: @example
2072: (plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant})
2073: @end example
2074:
2075: @item
2076: On machines that do not use @code{cc0},
2077: @code{(compare @var{x} (const_int 0))} will be converted to
2078: @var{x}.@refill
2079:
2080: @cindex @code{zero_extract}, canonicalization of
2081: @cindex @code{sign_extract}, canonicalization of
2082: @item
2083: Equality comparisons of a group of bits (usually a single bit) with zero
2084: will be written using @code{zero_extract} rather than the equivalent
2085: @code{and} or @code{sign_extract} operations.
2086:
2087: @end itemize
2088:
2089: @node Peephole Definitions, Expander Definitions, Insn Canonicalizations, Machine Desc
2090: @section Defining Machine-Specific Peephole Optimizers
2091: @cindex peephole optimizer definitions
2092: @cindex defining peephole optimizers
2093:
2094: In addition to instruction patterns the @file{md} file may contain
2095: definitions of machine-specific peephole optimizations.
2096:
2097: The combiner does not notice certain peephole optimizations when the data
2098: flow in the program does not suggest that it should try them. For example,
2099: sometimes two consecutive insns related in purpose can be combined even
2100: though the second one does not appear to use a register computed in the
2101: first one. A machine-specific peephole optimizer can detect such
2102: opportunities.
2103:
2104: A definition looks like this:
2105:
2106: @example
2107: (define_peephole
2108: [@var{insn-pattern-1}
2109: @var{insn-pattern-2}
2110: @dots{}]
2111: "@var{condition}"
2112: "@var{template}"
2113: "@var{optional insn-attributes}")
2114: @end example
2115:
2116: @noindent
2117: The last string operand may be omitted if you are not using any
2118: machine-specific information in this machine description. If present,
2119: it must obey the same rules as in a @code{define_insn}.
2120:
2121: In this skeleton, @var{insn-pattern-1} and so on are patterns to match
2122: consecutive insns. The optimization applies to a sequence of insns when
2123: @var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches
2124: the next, and so on.@refill
2125:
2126: Each of the insns matched by a peephole must also match a
2127: @code{define_insn}. Peepholes are checked only at the last stage just
2128: before code generation, and only optionally. Therefore, any insn which
2129: would match a peephole but no @code{define_insn} will cause a crash in code
2130: generation in an unoptimized compilation, or at various optimization
2131: stages.
2132:
2133: The operands of the insns are matched with @code{match_operands},
2134: @code{match_operator}, and @code{match_dup}, as usual. What is not
2135: usual is that the operand numbers apply to all the insn patterns in the
2136: definition. So, you can check for identical operands in two insns by
2137: using @code{match_operand} in one insn and @code{match_dup} in the
2138: other.
2139:
2140: The operand constraints used in @code{match_operand} patterns do not have
2141: any direct effect on the applicability of the peephole, but they will
2142: be validated afterward, so make sure your constraints are general enough
2143: to apply whenever the peephole matches. If the peephole matches
2144: but the constraints are not satisfied, the compiler will crash.
2145:
2146: It is safe to omit constraints in all the operands of the peephole; or
2147: you can write constraints which serve as a double-check on the criteria
2148: previously tested.
2149:
2150: Once a sequence of insns matches the patterns, the @var{condition} is
2151: checked. This is a C expression which makes the final decision whether to
2152: perform the optimization (we do so if the expression is nonzero). If
2153: @var{condition} is omitted (in other words, the string is empty) then the
2154: optimization is applied to every sequence of insns that matches the
2155: patterns.
2156:
2157: The defined peephole optimizations are applied after register allocation
2158: is complete. Therefore, the peephole definition can check which
2159: operands have ended up in which kinds of registers, just by looking at
2160: the operands.
2161:
2162: @findex prev_nonnote_insn
2163: The way to refer to the operands in @var{condition} is to write
2164: @code{operands[@var{i}]} for operand number @var{i} (as matched by
2165: @code{(match_operand @var{i} @dots{})}). Use the variable @code{insn}
2166: to refer to the last of the insns being matched; use
2167: @code{prev_nonnote_insn} to find the preceding insns.
2168:
2169: @findex dead_or_set_p
2170: When optimizing computations with intermediate results, you can use
2171: @var{condition} to match only when the intermediate results are not used
2172: elsewhere. Use the C expression @code{dead_or_set_p (@var{insn},
2173: @var{op})}, where @var{insn} is the insn in which you expect the value
2174: to be used for the last time (from the value of @code{insn}, together
2175: with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate
2176: value (from @code{operands[@var{i}]}).@refill
2177:
2178: Applying the optimization means replacing the sequence of insns with one
2179: new insn. The @var{template} controls ultimate output of assembler code
2180: for this combined insn. It works exactly like the template of a
2181: @code{define_insn}. Operand numbers in this template are the same ones
2182: used in matching the original sequence of insns.
2183:
2184: The result of a defined peephole optimizer does not need to match any of
2185: the insn patterns in the machine description; it does not even have an
2186: opportunity to match them. The peephole optimizer definition itself serves
2187: as the insn pattern to control how the insn is output.
2188:
2189: Defined peephole optimizers are run as assembler code is being output,
2190: so the insns they produce are never combined or rearranged in any way.
2191:
2192: Here is an example, taken from the 68000 machine description:
2193:
2194: @example
2195: (define_peephole
2196: [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
1.1.1.3 ! root 2197: (set (match_operand:DF 0 "register_operand" "=f")
1.1 root 2198: (match_operand:DF 1 "register_operand" "ad"))]
2199: "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
2200: "*
2201: @{
2202: rtx xoperands[2];
2203: xoperands[1] = gen_rtx (REG, SImode, REGNO (operands[1]) + 1);
2204: #ifdef MOTOROLA
2205: output_asm_insn (\"move.l %1,(sp)\", xoperands);
2206: output_asm_insn (\"move.l %1,-(sp)\", operands);
2207: return \"fmove.d (sp)+,%0\";
2208: #else
2209: output_asm_insn (\"movel %1,sp@@\", xoperands);
2210: output_asm_insn (\"movel %1,sp@@-\", operands);
2211: return \"fmoved sp@@+,%0\";
2212: #endif
2213: @}
2214: ")
2215: @end example
2216:
2217: The effect of this optimization is to change
2218:
2219: @example
2220: jbsr _foobar
2221: addql #4,sp
2222: movel d1,sp@@-
2223: movel d0,sp@@-
2224: fmoved sp@@+,fp0
2225: @end example
2226:
2227: @noindent
2228: into
2229:
2230: @example
2231: jbsr _foobar
2232: movel d1,sp@@
2233: movel d0,sp@@-
2234: fmoved sp@@+,fp0
2235: @end example
2236:
2237: @ignore
2238: @findex CC_REVERSED
2239: If a peephole matches a sequence including one or more jump insns, you must
2240: take account of the flags such as @code{CC_REVERSED} which specify that the
2241: condition codes are represented in an unusual manner. The compiler
2242: automatically alters any ordinary conditional jumps which occur in such
2243: situations, but the compiler cannot alter jumps which have been replaced by
2244: peephole optimizations. So it is up to you to alter the assembler code
2245: that the peephole produces. Supply C code to write the assembler output,
2246: and in this C code check the condition code status flags and change the
2247: assembler code as appropriate.
2248: @end ignore
2249:
2250: @var{insn-pattern-1} and so on look @emph{almost} like the second
2251: operand of @code{define_insn}. There is one important difference: the
2252: second operand of @code{define_insn} consists of one or more RTX's
2253: enclosed in square brackets. Usually, there is only one: then the same
2254: action can be written as an element of a @code{define_peephole}. But
2255: when there are multiple actions in a @code{define_insn}, they are
2256: implicitly enclosed in a @code{parallel}. Then you must explicitly
2257: write the @code{parallel}, and the square brackets within it, in the
2258: @code{define_peephole}. Thus, if an insn pattern looks like this,
2259:
2260: @example
2261: (define_insn "divmodsi4"
2262: [(set (match_operand:SI 0 "general_operand" "=d")
2263: (div:SI (match_operand:SI 1 "general_operand" "0")
2264: (match_operand:SI 2 "general_operand" "dmsK")))
2265: (set (match_operand:SI 3 "general_operand" "=d")
2266: (mod:SI (match_dup 1) (match_dup 2)))]
2267: "TARGET_68020"
2268: "divsl%.l %2,%3:%0")
2269: @end example
2270:
2271: @noindent
2272: then the way to mention this insn in a peephole is as follows:
2273:
2274: @example
2275: (define_peephole
2276: [@dots{}
2277: (parallel
2278: [(set (match_operand:SI 0 "general_operand" "=d")
2279: (div:SI (match_operand:SI 1 "general_operand" "0")
2280: (match_operand:SI 2 "general_operand" "dmsK")))
2281: (set (match_operand:SI 3 "general_operand" "=d")
2282: (mod:SI (match_dup 1) (match_dup 2)))])
2283: @dots{}]
2284: @dots{})
2285: @end example
2286:
2287: @node Expander Definitions, Insn Splitting, Peephole Definitions, Machine Desc
2288: @section Defining RTL Sequences for Code Generation
2289: @cindex expander definitions
2290: @cindex code generation RTL sequences
2291: @cindex defining RTL sequences for code generation
2292:
2293: On some target machines, some standard pattern names for RTL generation
2294: cannot be handled with single insn, but a sequence of RTL insns can
2295: represent them. For these target machines, you can write a
2296: @code{define_expand} to specify how to generate the sequence of RTL.
2297:
2298: @findex define_expand
2299: A @code{define_expand} is an RTL expression that looks almost like a
2300: @code{define_insn}; but, unlike the latter, a @code{define_expand} is used
2301: only for RTL generation and it can produce more than one RTL insn.
2302:
2303: A @code{define_expand} RTX has four operands:
2304:
2305: @itemize @bullet
2306: @item
2307: The name. Each @code{define_expand} must have a name, since the only
2308: use for it is to refer to it by name.
2309:
2310: @findex define_peephole
2311: @item
2312: The RTL template. This is just like the RTL template for a
2313: @code{define_peephole} in that it is a vector of RTL expressions
2314: each being one insn.
2315:
2316: @item
2317: The condition, a string containing a C expression. This expression is
2318: used to express how the availability of this pattern depends on
2319: subclasses of target machine, selected by command-line options when
2320: GNU CC is run. This is just like the condition of a
2321: @code{define_insn} that has a standard name.
2322:
2323: @item
2324: The preparation statements, a string containing zero or more C
2325: statements which are to be executed before RTL code is generated from
2326: the RTL template.
2327:
2328: Usually these statements prepare temporary registers for use as
2329: internal operands in the RTL template, but they can also generate RTL
2330: insns directly by calling routines such as @code{emit_insn}, etc.
2331: Any such insns precede the ones that come from the RTL template.
2332: @end itemize
2333:
2334: Every RTL insn emitted by a @code{define_expand} must match some
2335: @code{define_insn} in the machine description. Otherwise, the compiler
2336: will crash when trying to generate code for the insn or trying to optimize
2337: it.
2338:
2339: The RTL template, in addition to controlling generation of RTL insns,
2340: also describes the operands that need to be specified when this pattern
2341: is used. In particular, it gives a predicate for each operand.
2342:
2343: A true operand, which needs to be specified in order to generate RTL from
2344: the pattern, should be described with a @code{match_operand} in its first
2345: occurrence in the RTL template. This enters information on the operand's
2346: predicate into the tables that record such things. GNU CC uses the
2347: information to preload the operand into a register if that is required for
2348: valid RTL code. If the operand is referred to more than once, subsequent
2349: references should use @code{match_dup}.
2350:
2351: The RTL template may also refer to internal ``operands'' which are
2352: temporary registers or labels used only within the sequence made by the
2353: @code{define_expand}. Internal operands are substituted into the RTL
2354: template with @code{match_dup}, never with @code{match_operand}. The
2355: values of the internal operands are not passed in as arguments by the
2356: compiler when it requests use of this pattern. Instead, they are computed
2357: within the pattern, in the preparation statements. These statements
2358: compute the values and store them into the appropriate elements of
2359: @code{operands} so that @code{match_dup} can find them.
2360:
2361: There are two special macros defined for use in the preparation statements:
2362: @code{DONE} and @code{FAIL}. Use them with a following semicolon,
2363: as a statement.
2364:
2365: @table @code
2366:
2367: @findex DONE
2368: @item DONE
2369: Use the @code{DONE} macro to end RTL generation for the pattern. The
2370: only RTL insns resulting from the pattern on this occasion will be
2371: those already emitted by explicit calls to @code{emit_insn} within the
2372: preparation statements; the RTL template will not be generated.
2373:
2374: @findex FAIL
2375: @item FAIL
2376: Make the pattern fail on this occasion. When a pattern fails, it means
2377: that the pattern was not truly available. The calling routines in the
2378: compiler will try other strategies for code generation using other patterns.
2379:
2380: Failure is currently supported only for binary (addition, multiplication,
2381: shifting, etc.) and bitfield (@code{extv}, @code{extzv}, and @code{insv})
2382: operations.
2383: @end table
2384:
2385: Here is an example, the definition of left-shift for the SPUR chip:
2386:
2387: @example
2388: (define_expand "ashlsi3"
2389: [(set (match_operand:SI 0 "register_operand" "")
2390: (ashift:SI
2391: (match_operand:SI 1 "register_operand" "")
2392: (match_operand:SI 2 "nonmemory_operand" "")))]
2393: ""
2394: "
2395: @{
2396: if (GET_CODE (operands[2]) != CONST_INT
2397: || (unsigned) INTVAL (operands[2]) > 3)
2398: FAIL;
2399: @}")
2400: @end example
2401:
2402: @noindent
2403: This example uses @code{define_expand} so that it can generate an RTL insn
2404: for shifting when the shift-count is in the supported range of 0 to 3 but
2405: fail in other cases where machine insns aren't available. When it fails,
2406: the compiler tries another strategy using different patterns (such as, a
2407: library call).
2408:
2409: If the compiler were able to handle nontrivial condition-strings in
2410: patterns with names, then it would be possible to use a
2411: @code{define_insn} in that case. Here is another case (zero-extension
2412: on the 68000) which makes more use of the power of @code{define_expand}:
2413:
2414: @example
2415: (define_expand "zero_extendhisi2"
2416: [(set (match_operand:SI 0 "general_operand" "")
2417: (const_int 0))
2418: (set (strict_low_part
2419: (subreg:HI
2420: (match_dup 0)
2421: 0))
2422: (match_operand:HI 1 "general_operand" ""))]
2423: ""
2424: "operands[1] = make_safe_from (operands[1], operands[0]);")
2425: @end example
2426:
2427: @noindent
2428: @findex make_safe_from
2429: Here two RTL insns are generated, one to clear the entire output operand
2430: and the other to copy the input operand into its low half. This sequence
2431: is incorrect if the input operand refers to [the old value of] the output
2432: operand, so the preparation statement makes sure this isn't so. The
2433: function @code{make_safe_from} copies the @code{operands[1]} into a
2434: temporary register if it refers to @code{operands[0]}. It does this
2435: by emitting another RTL insn.
2436:
2437: Finally, a third example shows the use of an internal operand.
2438: Zero-extension on the SPUR chip is done by @code{and}-ing the result
2439: against a halfword mask. But this mask cannot be represented by a
2440: @code{const_int} because the constant value is too large to be legitimate
2441: on this machine. So it must be copied into a register with
2442: @code{force_reg} and then the register used in the @code{and}.
2443:
2444: @example
2445: (define_expand "zero_extendhisi2"
2446: [(set (match_operand:SI 0 "register_operand" "")
2447: (and:SI (subreg:SI
2448: (match_operand:HI 1 "register_operand" "")
2449: 0)
2450: (match_dup 2)))]
2451: ""
2452: "operands[2]
2453: = force_reg (SImode, gen_rtx (CONST_INT,
2454: VOIDmode, 65535)); ")
2455: @end example
2456:
2457: @strong{Note:} If the @code{define_expand} is used to serve a
2458: standard binary or unary arithmetic operation or a bitfield operation,
2459: then the last insn it generates must not be a @code{code_label},
2460: @code{barrier} or @code{note}. It must be an @code{insn},
2461: @code{jump_insn} or @code{call_insn}. If you don't need a real insn
2462: at the end, emit an insn to copy the result of the operation into
2463: itself. Such an insn will generate no code, but it can avoid problems
2464: in the compiler.@refill
2465:
2466: @node Insn Splitting, Insn Attributes, Expander Definitions, Machine Desc
2467: @section Splitting Instructions into Multiple Instructions
2468: @cindex insn splitting
2469: @cindex instruction splitting
2470: @cindex splitting instructions
2471:
1.1.1.3 ! root 2472: There are two cases where you should specify how to split a pattern into
! 2473: multiple insns. On machines that have instructions requiring delay
! 2474: slots (@pxref{Delay Slots}) or that have instructions whose output is
! 2475: not available for multiple cycles (@pxref{Function Units}), the compiler
! 2476: phases that optimize these cases need to be able to move insns into
! 2477: one-cycle delay slots. However, some insns may generate more than one
! 2478: machine instruction. These insns cannot be placed into a delay slot.
! 2479:
! 2480: Often you can rewrite the single insn as a list of individual insns,
! 2481: each corresponding to one machine instruction. The disadvantage of
! 2482: doing so is that it will cause the compilation to be slower and require
! 2483: more space. If the resulting insns are too complex, it may also
! 2484: suppress some optimizations. The compiler splits the insn if there is a
! 2485: reason to believe that it might improve instruction or delay slot
! 2486: scheduling.
! 2487:
! 2488: The insn combiner phase also splits putative insns. If three insns are
! 2489: merged into one insn with a complex expression that cannot be matched by
! 2490: some @code{define_insn} pattern, the combiner phase attempts to split
! 2491: the complex pattern into two insns that are recognized. Usually it can
! 2492: break the complex pattern into two patterns by splitting out some
! 2493: subexpression. However, in some other cases, such as performing an
! 2494: addition of a large constant in two insns on a RISC machine, the way to
! 2495: split the addition into two insns is machine-dependent.
1.1 root 2496:
1.1.1.3 ! root 2497: @cindex define_split
1.1 root 2498: The @code{define_split} definition tells the compiler how to split a
1.1.1.3 ! root 2499: complex insn into several simpler insns. It looks like this:
1.1 root 2500:
2501: @example
2502: (define_split
2503: [@var{insn-pattern}]
2504: "@var{condition}"
2505: [@var{new-insn-pattern-1}
2506: @var{new-insn-pattern-2}
2507: @dots{}]
2508: "@var{preparation statements}")
2509: @end example
2510:
2511: @var{insn-pattern} is a pattern that needs to be split and
2512: @var{condition} is the final condition to be tested, as in a
1.1.1.3 ! root 2513: @code{define_insn}. When an insn matching @var{insn-pattern} and
! 2514: satisfying @var{condition} is found, it is replaced in the insn list
! 2515: with the insns given by @var{new-insn-pattern-1},
! 2516: @var{new-insn-pattern-2}, etc.
1.1 root 2517:
2518: The @var{preparation statements} are similar to those specified for
2519: @code{define_expand} (@pxref{Expander Definitions}) and are executed
2520: before the new RTL is generated to prepare for the generated code
2521: or emit some insns whose pattern is not fixed.
2522:
1.1.1.3 ! root 2523: Patterns are matched against @var{insn-pattern} in two different
! 2524: circumstances. If an insn needs to be split for delay slot scheduling
! 2525: or insn scheduling, the insn is already known to be valid, which means
! 2526: that it must have been matched by some @code{define_insn} and, if
! 2527: @code{reload_completed} is non-zero, is known to satisfy the constraints
! 2528: of that @code{define_insn}. In that case, the new insn patterns must
! 2529: also be insns that are matched by some @code{define_insn} and, if
! 2530: @code{reload_completed} is non-zero, must also satisfy the constraints
! 2531: of those definitions.
! 2532:
! 2533: As an example of this usage of @code{define_split}, consider the following
! 2534: example from @file{a29k.md}, which splits a @code{sign_extend} from
1.1 root 2535: @code{HImode} to @code{SImode} into a pair of shift insns:
2536:
2537: @example
2538: (define_split
2539: [(set (match_operand:SI 0 "gen_reg_operand" "")
2540: (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))]
2541: ""
2542: [(set (match_dup 0)
2543: (ashift:SI (match_dup 1)
2544: (const_int 16)))
2545: (set (match_dup 0)
2546: (ashiftrt:SI (match_dup 0)
2547: (const_int 16)))]
2548: "
2549: @{ operands[1] = gen_lowpart (SImode, operands[1]); @}")
2550: @end example
2551:
1.1.1.3 ! root 2552: When the combiner phase tries to split an insn pattern, it is always the
! 2553: case that the pattern is @emph{not} matched by any @code{define_insn}.
! 2554: The combiner pass first tries to split a single @code{set} expression
! 2555: and then the same @code{set} expression inside a @code{parallel}, but
! 2556: followed by a @code{clobber} of a pseudo-reg to use as a scratch
! 2557: register. In these cases, the combiner expects exactly two new insn
! 2558: patterns to be generated. It will verify that these patterns match some
! 2559: @code{define_insn} definitions, so you need not do this test in the
! 2560: @code{define_split} (of course, there is no point in writing a
! 2561: @code{define_split} that will never produce insns that match).
! 2562:
! 2563: Here is an example of this use of @code{define_split}, taken from
! 2564: @file{rs6000.md}:
! 2565:
! 2566: @example
! 2567: (define_split
! 2568: [(set (match_operand:SI 0 "gen_reg_operand" "")
! 2569: (plus:SI (match_operand:SI 1 "gen_reg_operand" "")
! 2570: (match_operand:SI 2 "non_add_cint_operand" "")))]
! 2571: ""
! 2572: [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3)))
! 2573: (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))]
! 2574: "
! 2575: @{
! 2576: int low = INTVAL (operands[2]) & 0xffff;
! 2577: int high = (unsigned) INTVAL (operands[2]) >> 16;
! 2578:
! 2579: if (low & 0x8000)
! 2580: high++, low |= 0xffff0000;
! 2581:
! 2582: operands[3] = gen_rtx (CONST_INT, VOIDmode, high << 16);
! 2583: operands[4] = gen_rtx (CONST_INT, VOIDmode, low);
! 2584: @}")
! 2585: @end example
! 2586:
! 2587: Here the predicate @code{non_add_cint_operand} matches any
! 2588: @code{const_int} that is @emph{not} a valid operand of a single add
! 2589: insn. Write the add with the smaller displacement is written so that it
! 2590: can be substituted into the address of a subsequent operation.
! 2591:
! 2592: An example that uses a scratch register, from the same file, generates
! 2593: an equality comparison of a register and a large constant:
! 2594:
! 2595: @example
! 2596: (define_split
! 2597: [(set (match_operand:CC 0 "cc_reg_operand" "")
! 2598: (compare:CC (match_operand:SI 1 "gen_reg_operand" "")
! 2599: (match_operand:SI 2 "non_short_cint_operand" "")))
! 2600: (clobber (match_operand:SI 3 "gen_reg_operand" ""))]
! 2601: "find_single_use (operands[0], insn, 0)
! 2602: && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ
! 2603: || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)"
! 2604: [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4)))
! 2605: (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))]
! 2606: "
! 2607: @{
! 2608: /* Get the constant we are comparing against, C, and see what it looks like
! 2609: sign-extended to 16 bits. Then see what constant could be XOR'ed
! 2610: with C to get the sign-extended value. */
! 2611:
! 2612: int c = INTVAL (operands[2]);
! 2613: int sextc = (c << 16) >> 16;
! 2614: int xorv = c ^ sextc;
! 2615:
! 2616: operands[4] = gen_rtx (CONST_INT, VOIDmode, xorv);
! 2617: operands[5] = gen_rtx (CONST_INT, VOIDmode, sextc);
! 2618: @}")
! 2619: @end example
! 2620:
! 2621: To avoid confusion, don't write a single @code{define_split} that
! 2622: accepts some insns that match some @code{define_insn} as well as some
! 2623: insns that don't. Instead, write two separate @code{define_split}
! 2624: definitions, one for the insns that are valid and one for the insns that
! 2625: are not valid.
! 2626:
1.1 root 2627: @node Insn Attributes,, Insn Splitting, Machine Desc
2628: @section Instruction Attributes
2629: @cindex insn attributes
2630: @cindex instruction attributes
2631:
2632: In addition to describing the instruction supported by the target machine,
2633: the @file{md} file also defines a group of @dfn{attributes} and a set of
2634: values for each. Every generated insn is assigned a value for each attribute.
2635: One possible attribute would be the effect that the insn has on the machine's
2636: condition code. This attribute can then be used by @code{NOTICE_UPDATE_CC}
2637: to track the condition codes.
2638:
2639: @menu
2640: * Defining Attributes:: Specifying attributes and their values.
2641: * Expressions:: Valid expressions for attribute values.
2642: * Tagging Insns:: Assigning attribute values to insns.
2643: * Attr Example:: An example of assigning attributes.
2644: * Insn Lengths:: Computing the length of insns.
1.1.1.2 root 2645: * Constant Attributes:: Defining attributes that are constant.
1.1 root 2646: * Delay Slots:: Defining delay slots required for a machine.
2647: * Function Units:: Specifying information for insn scheduling.
2648: @end menu
2649:
2650: @node Defining Attributes, Expressions, Insn Attributes, Insn Attributes
2651: @subsection Defining Attributes and their Values
2652: @cindex defining attributes and their values
2653: @cindex attributes, defining
2654:
2655: @findex define_attr
2656: The @code{define_attr} expression is used to define each attribute required
2657: by the target machine. It looks like:
2658:
2659: @example
2660: (define_attr @var{name} @var{list-of-values} @var{default})
2661: @end example
2662:
2663: @var{name} is a string specifying the name of the attribute being defined.
2664:
2665: @var{list-of-values} is either a string that specifies a comma-separated
2666: list of values that can be assigned to the attribute, or a null string to
2667: indicate that the attribute takes numeric values.
2668:
2669: @var{default} is an attribute expression that gives the value of this
2670: attribute for insns that match patterns whose definition does not include
2671: an explicit value for this attribute. @xref{Attr Example}, for more
1.1.1.2 root 2672: information on the handling of defaults. @xref{Constant Attributes},
2673: for information on attributes that do not depend on any particular insn.
1.1 root 2674:
2675: @findex insn-attr.h
2676: For each defined attribute, a number of definitions are written to the
2677: @file{insn-attr.h} file. For cases where an explicit set of values is
2678: specified for an attribute, the following are defined:
2679:
2680: @itemize @bullet
2681: @item
2682: A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}.
2683:
2684: @item
2685: An enumeral class is defined for @samp{attr_@var{name}} with
2686: elements of the form @samp{@var{upper-name}_@var{upper-value}} where
2687: the attribute name and value are first converted to upper case.
2688:
2689: @item
2690: A function @samp{get_attr_@var{name}} is defined that is passed an insn and
2691: returns the attribute value for that insn.
2692: @end itemize
2693:
2694: For example, if the following is present in the @file{md} file:
2695:
2696: @example
2697: (define_attr "type" "branch,fp,load,store,arith" @dots{})
2698: @end example
2699:
2700: @noindent
2701: the following lines will be written to the file @file{insn-attr.h}.
2702:
2703: @example
2704: #define HAVE_ATTR_type
2705: enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD,
2706: TYPE_STORE, TYPE_ARITH@};
2707: extern enum attr_type get_attr_type ();
2708: @end example
2709:
2710: If the attribute takes numeric values, no @code{enum} type will be
2711: defined and the function to obtain the attribute's value will return
2712: @code{int}.
2713:
2714: @node Expressions, Tagging Insns, Defining Attributes, Insn Attributes
2715: @subsection Attribute Expressions
2716: @cindex attribute expressions
2717:
2718: RTL expressions used to define attributes use the codes described above
2719: plus a few specific to attribute definitions, to be discussed below.
2720: Attribute value expressions must have one of the following forms:
2721:
2722: @table @code
2723: @cindex @code{const_int} and attributes
2724: @item (const_int @var{i})
2725: The integer @var{i} specifies the value of a numeric attribute. @var{i}
2726: must be non-negative.
2727:
2728: The value of a numeric attribute can be specified either with a
2729: @code{const_int} or as an integer represented as a string in
2730: @code{const_string}, @code{eq_attr} (see below), and @code{set_attr}
2731: (@pxref{Tagging Insns}) expressions.
2732:
2733: @cindex @code{const_string} and attributes
2734: @item (const_string @var{value})
2735: The string @var{value} specifies a constant attribute value.
2736: If @var{value} is specified as @samp{"*"}, it means that the default value of
2737: the attribute is to be used for the insn containing this expression.
2738: @samp{"*"} obviously cannot be used in the @var{default} expression
2739: of a @code{define_attr}.@refill
2740:
2741: If the attribute whose value is being specified is numeric, @var{value}
2742: must be a string containing a non-negative integer (normally
2743: @code{const_int} would be used in this case). Otherwise, it must
2744: contain one of the valid values for the attribute.
2745:
2746: @cindex @code{if_then_else} and attributes
2747: @item (if_then_else @var{test} @var{true-value} @var{false-value})
2748: @var{test} specifies an attribute test, whose format is defined below.
2749: The value of this expression is @var{true-value} if @var{test} is true,
2750: otherwise it is @var{false-value}.
2751:
2752: @cindex @code{cond} and attributes
2753: @item (cond [@var{test1} @var{value1} @dots{}] @var{default})
2754: The first operand of this expression is a vector containing an even
2755: number of expressions and consisting of pairs of @var{test} and @var{value}
2756: expressions. The value of the @code{cond} expression is that of the
2757: @var{value} corresponding to the first true @var{test} expression. If
2758: none of the @var{test} expressions are true, the value of the @code{cond}
2759: expression is that of the @var{default} expression.
2760: @end table
2761:
2762: @var{test} expressions can have one of the following forms:
2763:
2764: @table @code
2765: @cindex @code{const_int} and attribute tests
2766: @item (const_int @var{i})
2767: This test is true if @var{i} is non-zero and false otherwise.
2768:
2769: @cindex @code{not} and attributes
2770: @cindex @code{ior} and attributes
2771: @cindex @code{and} and attributes
2772: @item (not @var{test})
2773: @itemx (ior @var{test1} @var{test2})
2774: @itemx (and @var{test1} @var{test2})
2775: These tests are true if the indicated logical function is true.
2776:
2777: @cindex @code{match_operand} and attributes
2778: @item (match_operand:@var{m} @var{n} @var{pred} @var{constraints})
2779: This test is true if operand @var{n} of the insn whose attribute value
2780: is being determined has mode @var{m} (this part of the test is ignored
2781: if @var{m} is @code{VOIDmode}) and the function specified by the string
2782: @var{pred} returns a non-zero value when passed operand @var{n} and mode
2783: @var{m} (this part of the test is ignored if @var{pred} is the null
2784: string).
2785:
2786: The @var{constraints} operand is ignored and should be the null string.
2787:
2788: @cindex @code{le} and attributes
2789: @cindex @code{leu} and attributes
2790: @cindex @code{lt} and attributes
2791: @cindex @code{gt} and attributes
2792: @cindex @code{gtu} and attributes
2793: @cindex @code{ge} and attributes
2794: @cindex @code{geu} and attributes
2795: @cindex @code{ne} and attributes
2796: @cindex @code{eq} and attributes
2797: @cindex @code{plus} and attributes
2798: @cindex @code{minus} and attributes
2799: @cindex @code{mult} and attributes
2800: @cindex @code{div} and attributes
2801: @cindex @code{mod} and attributes
2802: @cindex @code{abs} and attributes
2803: @cindex @code{neg} and attributes
2804: @cindex @code{lshift} and attributes
2805: @cindex @code{ashift} and attributes
2806: @cindex @code{lshiftrt} and attributes
2807: @cindex @code{ashiftrt} and attributes
2808: @item (le @var{arith1} @var{arith2})
2809: @itemx (leu @var{arith1} @var{arith2})
2810: @itemx (lt @var{arith1} @var{arith2})
2811: @itemx (ltu @var{arith1} @var{arith2})
2812: @itemx (gt @var{arith1} @var{arith2})
2813: @itemx (gtu @var{arith1} @var{arith2})
2814: @itemx (ge @var{arith1} @var{arith2})
2815: @itemx (geu @var{arith1} @var{arith2})
2816: @itemx (ne @var{arith1} @var{arith2})
2817: @itemx (eq @var{arith1} @var{arith2})
2818: These tests are true if the indicated comparison of the two arithmetic
2819: expressions is true. Arithmetic expressions are formed with
2820: @code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod},
2821: @code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not},
2822: @code{lshift}, @code{ashift}, @code{lshiftrt}, and @code{ashiftrt}
2823: expressions.@refill
2824:
2825: @findex get_attr
2826: @code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn
2827: Lengths},for additional forms). @code{symbol_ref} is a string
2828: denoting a C expression that yields an @code{int} when evaluated by the
2829: @samp{get_attr_@dots{}} routine. It should normally be a global
2830: variable.@refill
2831:
2832: @findex eq_attr
2833: @item (eq_attr @var{name} @var{value})
2834: @var{name} is a string specifying the name of an attribute.
2835:
2836: @var{value} is a string that is either a valid value for attribute
2837: @var{name}, a comma-separated list of values, or @samp{!} followed by a
2838: value or list. If @var{value} does not begin with a @samp{!}, this
2839: test is true if the value of the @var{name} attribute of the current
2840: insn is in the list specified by @var{value}. If @var{value} begins
2841: with a @samp{!}, this test is true if the attribute's value is
2842: @emph{not} in the specified list.
2843:
2844: For example,
2845:
2846: @example
2847: (eq_attr "type" "load,store")
2848: @end example
2849:
2850: @noindent
2851: is equivalent to
2852:
2853: @example
2854: (ior (eq_attr "type" "load") (eq_attr "type" "store"))
2855: @end example
2856:
2857: If @var{name} specifies an attribute of @samp{alternative}, it refers to the
2858: value of the compiler variable @code{which_alternative}
2859: (@pxref{Output Statement}) and the values must be small integers. For
2860: example,@refill
2861:
2862: @example
2863: (eq_attr "alternative" "2,3")
2864: @end example
2865:
2866: @noindent
2867: is equivalent to
2868:
2869: @example
2870: (ior (eq (symbol_ref "which_alternative") (const_int 2))
2871: (eq (symbol_ref "which_alternative") (const_int 3)))
2872: @end example
2873:
2874: Note that, for most attributes, an @code{eq_attr} test is simplified in cases
2875: where the value of the attribute being tested is known for all insns matching
2876: a particular pattern. This is by far the most common case.@refill
2877: @end table
2878:
2879: @node Tagging Insns, Attr Example, Expressions, Insn Attributes
2880: @subsection Assigning Attribute Values to Insns
2881: @cindex tagging insns
2882: @cindex assigning attribute values to insns
2883:
2884: The value assigned to an attribute of an insn is primarily determined by
2885: which pattern is matched by that insn (or which @code{define_peephole}
2886: generated it). Every @code{define_insn} and @code{define_peephole} can
2887: have an optional last argument to specify the values of attributes for
2888: matching insns. The value of any attribute not specified in a particular
2889: insn is set to the default value for that attribute, as specified in its
2890: @code{define_attr}. Extensive use of default values for attributes
2891: permits the specification of the values for only one or two attributes
2892: in the definition of most insn patterns, as seen in the example in the
2893: next section.@refill
2894:
2895: The optional last argument of @code{define_insn} and
2896: @code{define_peephole} is a vector of expressions, each of which defines
2897: the value for a single attribute. The most general way of assigning an
2898: attribute's value is to use a @code{set} expression whose first operand is an
2899: @code{attr} expression giving the name of the attribute being set. The
2900: second operand of the @code{set} is an attribute expression
2901: (@pxref{Expressions}) giving the value of the attribute.@refill
2902:
2903: When the attribute value depends on the @samp{alternative} attribute
2904: (i.e., which is the applicable alternative in the constraint of the
2905: insn), the @code{set_attr_alternative} expression can can be used. It
2906: allows the specification of a vector of attribute expressions, one for
2907: each alternative.
2908:
2909: @findex set_attr
2910: When the generality of arbitrary attribute expressions is not required,
2911: the simpler @code{set_attr} expression can be used, which allows
2912: specifying a string giving either a single attribute value or a list
2913: of attribute values, one for each alternative.
2914:
2915: The form of each of the above specifications is shown below. In each case,
2916: @var{name} is a string specifying the attribute to be set.
2917:
2918: @table @code
2919: @item (set_attr @var{name} @var{value-string})
2920: @var{value-string} is either a string giving the desired attribute value,
2921: or a string containing a comma-separated list giving the values for
2922: succeeding alternatives. The number of elements must match the number
2923: of alternatives in the constraint of the insn pattern.
2924:
2925: Note that it may be useful to specify @samp{*} for some alternative, in
2926: which case the attribute will assume its default value for insns matching
2927: that alternative.
2928:
2929: @findex set_attr_alternative
2930: @item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}])
2931: Depending on the alternative of the insn, the value will be one of the
2932: specified values. This is a shorthand for using a @code{cond} with
2933: tests on the @samp{alternative} attribute.
2934:
2935: @findex attr
2936: @item (set (attr @var{name}) @var{value})
2937: The first operand of this @code{set} must be the special RTL expression
2938: @code{attr}, whose sole operand is a string giving the name of the
2939: attribute being set. @var{value} is the value of the attribute.
2940: @end table
2941:
2942: The following shows three different ways of representing the same
2943: attribute value specification:
2944:
2945: @example
2946: (set_attr "type" "load,store,arith")
2947:
2948: (set_attr_alternative "type"
2949: [(const_string "load") (const_string "store")
2950: (const_string "arith")])
2951:
2952: (set (attr "type")
2953: (cond [(eq_attr "alternative" "1") (const_string "load")
2954: (eq_attr "alternative" "2") (const_string "store")]
2955: (const_string "arith")))
2956: @end example
2957:
2958: @findex define_asm_attributes
2959: The @code{define_asm_attributes} expression provides a mechanism to
2960: specify the attributes assigned to insns produced from an @code{asm}
2961: statement. It has the form:
2962:
2963: @example
2964: (define_asm_attributes [@var{attr-sets}])
2965: @end example
2966:
2967: @noindent
2968: where @var{attr-sets} is specified the same as for @code{define_insn}
2969: and @code{define_peephole} expressions.
2970:
2971: These values will typically be the ``worst case'' attribute values. For
2972: example, they might indicate that the condition code will be clobbered.
2973:
2974: A specification for a @code{length} attribute is handled specially. To
2975: compute the length of an @code{asm} insn, the length specified in the
2976: @code{define_asm_attributes} expression is multiplied by the number of
2977: machine instructions specified in the @code{asm} statement, determined
2978: by counting the number of semicolons and newlines in the string.
2979: Therefore, the value of the @code{length} attribute specified in a
2980: @code{define_asm_attributes} should be the maximum possible length of a
2981: single machine instruction.
2982:
2983: @node Attr Example, Insn Lengths, Tagging Insns, Insn Attributes
2984: @subsection Example of Attribute Specifications
2985: @cindex attribute specifications example
2986: @cindex attribute specifications
2987:
2988: The judicious use of defaulting is important in the efficient use of
2989: insn attributes. Typically, insns are divided into @dfn{types} and an
2990: attribute, customarily called @code{type}, is used to represent this
2991: value. This attribute is normally used only to define the default value
2992: for other attributes. An example will clarify this usage.
2993:
2994: Assume we have a RISC machine with a condition code and in which only
2995: full-word operations are performed in registers. Let us assume that we
2996: can divide all insns into loads, stores, (integer) arithmetic
2997: operations, floating point operations, and branches.
2998:
2999: Here we will concern ourselves with determining the effect of an insn on
3000: the condition code and will limit ourselves to the following possible
3001: effects: The condition code can be set unpredictably (clobbered), not
3002: be changed, be set to agree with the results of the operation, or only
3003: changed if the item previously set into the condition code has been
3004: modified.
3005:
3006: Here is part of a sample @file{md} file for such a machine:
3007:
3008: @example
3009: (define_attr "type" "load,store,arith,fp,branch" (const_string "arith"))
3010:
3011: (define_attr "cc" "clobber,unchanged,set,change0"
3012: (cond [(eq_attr "type" "load")
3013: (const_string "change0")
3014: (eq_attr "type" "store,branch")
3015: (const_string "unchanged")
3016: (eq_attr "type" "arith")
3017: (if_then_else (match_operand:SI 0 "" "")
3018: (const_string "set")
3019: (const_string "clobber"))]
3020: (const_string "clobber")))
3021:
3022: (define_insn ""
3023: [(set (match_operand:SI 0 "general_operand" "=r,r,m")
3024: (match_operand:SI 1 "general_operand" "r,m,r"))]
3025: ""
3026: "@@
3027: move %0,%1
3028: load %0,%1
3029: store %0,%1"
3030: [(set_attr "type" "arith,load,store")])
3031: @end example
3032:
3033: Note that we assume in the above example that arithmetic operations
3034: performed on quantities smaller than a machine word clobber the condition
3035: code since they will set the condition code to a value corresponding to the
3036: full-word result.
3037:
1.1.1.2 root 3038: @node Insn Lengths, Constant Attributes, Attr Example, Insn Attributes
1.1 root 3039: @subsection Computing the Length of an Insn
3040: @cindex insn lengths, computing
3041: @cindex computing the length of an insn
3042:
3043: For many machines, multiple types of branch instructions are provided, each
3044: for different length branch displacements. In most cases, the assembler
3045: will choose the correct instruction to use. However, when the assembler
3046: cannot do so, GCC can when a special attribute, the @samp{length}
3047: attribute, is defined. This attribute must be defined to have numeric
3048: values by specifying a null string in its @code{define_attr}.
3049:
3050: In the case of the @samp{length} attribute, two additional forms of
3051: arithmetic terms are allowed in test expressions:
3052:
3053: @table @code
3054: @cindex @code{match_dup} and attributes
3055: @item (match_dup @var{n})
3056: This refers to the address of operand @var{n} of the current insn, which
3057: must be a @code{label_ref}.
3058:
3059: @cindex @code{pc} and attributes
3060: @item (pc)
3061: This refers to the address of the @emph{current} insn. It might have
3062: been more consistent with other usage to make this the address of the
3063: @emph{next} insn but this would be confusing because the length of the
3064: current insn is to be computed.
3065: @end table
3066:
3067: @cindex @code{addr_vec}, length of
3068: @cindex @code{addr_diff_vec}, length of
3069: For normal insns, the length will be determined by value of the
3070: @samp{length} attribute. In the case of @code{addr_vec} and
3071: @code{addr_diff_vec} insn patterns, the length will be computed as
3072: the number of vectors multiplied by the size of each vector.@refill
3073:
3074: The following macros can be used to refine the length computation:
3075:
3076: @table @code
3077: @findex FIRST_INSN_ADDRESS
3078: @item FIRST_INSN_ADDRESS
3079: When the @code{length} insn attribute is used, this macro specifies the
3080: value to be assigned to the address of the first insn in a function. If
3081: not specified, 0 is used.
3082:
3083: @findex ADJUST_INSN_LENGTH
3084: @item ADJUST_INSN_LENGTH (@var{insn}, @var{length})
3085: If defined, modifies the length assigned to instruction @var{insn} as a
3086: function of the context in which it is used. @var{length} is an lvalue
3087: that contains the initially computed length of the insn and should be
3088: updated with the correct length of the insn. If updating is required,
3089: @var{insn} must not be a varying-length insn.
3090:
3091: This macro will normally not be required. A case in which it is
3092: required is the ROMP. On this machine, the size of an @code{addr_vec}
3093: insn must be increased by two to compensate for the fact that alignment
3094: may be required.
3095: @end table
3096:
1.1.1.2 root 3097: @findex get_attr_length
1.1 root 3098: The routine that returns the value of the @code{length} attribute,
1.1.1.2 root 3099: @code{get_attr_length}, can be used by the output routine to determine
1.1 root 3100: the form of the branch instruction to be written, as the example
3101: below illustrates.
3102:
3103: As an example of the specification of variable-length branches, consider
3104: the IBM 360. If we adopt the convention that a register will be set to
3105: the starting address of a function, we can jump to labels within 4K of
3106: the start using a four-byte instruction. Otherwise, we need a six-byte
3107: sequence to load the address from memory and then branch to it.
3108:
3109: On such a machine, a pattern for a branch instruction might be specified
3110: as follows:
3111:
3112: @example
3113: (define_insn "jump"
3114: [(set (pc)
3115: (label_ref (match_operand 0 "" "")))]
3116: ""
3117: "*
3118: @{
3119: return (get_attr_length (insn) == 4
3120: ? \"b %l0\" : \"l r15,=a(%l0); br r15\");
3121: @}"
3122: [(set (attr "length") (if_then_else (lt (match_dup 0) (const_int 4096))
3123: (const_int 4)
3124: (const_int 6)))])
3125: @end example
3126:
1.1.1.2 root 3127: @node Constant Attributes, Delay Slots, Insn Lengths, Insn Attributes
3128: @subsection Constant Attributes
3129: @cindex constant attributes
3130:
1.1.1.3 ! root 3131: A special form of @code{define_attr}, where the expression for the
! 3132: default value is a @code{const} expression, indicates an attribute that
! 3133: is constant for a given run of the compiler. Constant attributes may be
! 3134: used to specify which variety of processor is used. For example,
1.1.1.2 root 3135:
3136: @example
3137: (define_attr "cpu" "m88100,m88110,m88000"
3138: (const
3139: (cond [(symbol_ref "TARGET_88100") (const_string "m88100")
3140: (symbol_ref "TARGET_88110") (const_string "m88110")]
3141: (const_string "m88000"))))
3142:
3143: (define_attr "memory" "fast,slow"
3144: (const
3145: (if_then_else (symbol_ref "TARGET_FAST_MEM")
3146: (const_string "fast")
3147: (const_string "slow"))))
3148: @end example
3149:
3150: The routine generated for constant attributes has no parameters as it
1.1.1.3 ! root 3151: does not depend on any particular insn. RTL expressions used to define
! 3152: the value of a constant attribute may use the @code{symbol_ref} form,
! 3153: but may not use either the @code{match_operand} form or @code{eq_attr}
! 3154: forms involving insn attributes.
1.1.1.2 root 3155:
3156: @node Delay Slots, Function Units, Constant Attributes, Insn Attributes
1.1 root 3157: @subsection Delay Slot Scheduling
3158: @cindex delay slots, defining
3159:
3160: The insn attribute mechanism can be used to specify the requirements for
3161: delay slots, if any, on a target machine. An instruction is said to
3162: require a @dfn{delay slot} if some instructions that are physically
3163: after the instruction are executed as if they were located before it.
3164: Classic examples are branch and call instructions, which often execute
3165: the following instruction before the branch or call is performed.
3166:
3167: On some machines, conditional branch instructions can optionally
3168: @dfn{annul} instructions in the delay slot. This means that the
3169: instruction will not be executed for certain branch outcomes. Both
3170: instructions that annul if the branch is true and instructions that
3171: annul if the branch is false are supported.
3172:
3173: Delay slot scheduling differs from instruction scheduling in that
3174: determining whether an instruction needs a delay slot is dependent only
3175: on the type of instruction being generated, not on data flow between the
3176: instructions. See the next section for a discussion of data-dependent
3177: instruction scheduling.
3178:
3179: @findex define_delay
3180: The requirement of an insn needing one or more delay slots is indicated
3181: via the @code{define_delay} expression. It has the following form:
3182:
3183: @example
3184: (define_delay @var{test}
3185: [@var{delay-1} @var{annul-true-1} @var{annul-false-1}
3186: @var{delay-2} @var{annul-true-2} @var{annul-false-2}
3187: @dots{}])
3188: @end example
3189:
3190: @var{test} is an attribute test that indicates whether this
3191: @code{define_delay} applies to a particular insn. If so, the number of
3192: required delay slots is determined by the length of the vector specified
3193: as the second argument. An insn placed in delay slot @var{n} must
3194: satisfy attribute test @var{delay-n}. @var{annul-true-n} is an
3195: attribute test that specifies which insns may be annulled if the branch
3196: is true. Similarly, @var{annul-false-n} specifies which insns in the
3197: delay slot may be annulled if the branch is false. If annulling is not
3198: supported for that delay slot, @code{(nil)} should be coded.@refill
3199:
3200: For example, in the common case where branch and call insns require
3201: a single delay slot, which may contain any insn other than a branch or
3202: call, the following would be placed in the @file{md} file:
3203:
3204: @example
3205: (define_delay (eq_attr "type" "branch,call")
3206: [(eq_attr "type" "!branch,call") (nil) (nil)])
3207: @end example
3208:
3209: Multiple @code{define_delay} expressions may be specified. In this
3210: case, each such expression specifies different delay slot requirements
3211: and there must be no insn for which tests in two @code{define_delay}
3212: expressions are both true.
3213:
3214: For example, if we have a machine that requires one delay slot for branches
3215: but two for calls, no delay slot can contain a branch or call insn,
3216: and any valid insn in the delay slot for the branch can be annulled if the
3217: branch is true, we might represent this as follows:
3218:
3219: @example
3220: (define_delay (eq_attr "type" "branch")
3221: [(eq_attr "type" "!branch,call") (eq_attr "type" "!branch,call") (nil)])
3222:
3223: (define_delay (eq_attr "type" "call")
3224: [(eq_attr "type" "!branch,call") (nil) (nil)
3225: (eq_attr "type" "!branch,call") (nil) (nil)])
3226: @end example
3227:
3228: @node Function Units,, Delay Slots, Insn Attributes
3229: @subsection Specifying Function Units
3230: @cindex function units, for scheduling
3231:
3232: On most RISC machines, there are instructions whose results are not
3233: available for a specific number of cycles. Common cases are instructions
3234: that load data from memory. On many machines, a pipeline stall will result
3235: if the data is referenced too soon after the load instruction.
3236:
3237: In addition, many newer microprocessors have multiple function units, usually
3238: one for integer and one for floating point, and often will incur pipeline
3239: stalls when a result that is needed is not yet ready.
3240:
3241: The descriptions in this section allow the specification of how much
3242: time must elapse between the execution of an instruction and the time
3243: when its result is used. It also allows specification of when the
3244: execution of an instruction will delay execution of similar instructions
3245: due to function unit conflicts.
3246:
3247: For the purposes of the specifications in this section, a machine is
3248: divided into @dfn{function units}, each of which execute a specific
3249: class of instructions. Function units that accept one instruction each
3250: cycle and allow a result to be used in the succeeding instruction
3251: (usually via forwarding) need not be specified. Classic RISC
3252: microprocessors will normally have a single function unit, which we can
3253: call @samp{memory}. The newer ``superscalar'' processors will often
3254: have function units for floating point operations, usually at least
3255: a floating point adder and multiplier.
3256:
3257: @findex define_function_unit
3258: Each usage of a function units by a class of insns is specified with a
3259: @code{define_function_unit} expression, which looks like this:
3260:
3261: @example
3262: (define_function_unit @var{name} @var{multiplicity} @var{simultaneity}
3263: @var{test} @var{ready-delay} @var{busy-delay}
3264: [@var{conflict-list}])
3265: @end example
3266:
3267: @var{name} is a string giving the name of the function unit.
3268:
3269: @var{multiplicity} is an integer specifying the number of identical
3270: units in the processor. If more than one unit is specified, they will
3271: be scheduled independently. Only truly independent units should be
3272: counted; a pipelined unit should be specified as a single unit. (The
3273: only common example of a machine that has multiple function units for a
3274: single instruction class that are truly independent and not pipelined
3275: are the two multiply and two increment units of the CDC 6600.)
3276:
3277: @var{simultaneity} specifies the maximum number of insns that can be
3278: executing in each instance of the function unit simultaneously or zero
3279: if the unit is pipelined and has no limit.
3280:
3281: All @code{define_function_unit} definitions referring to function unit
3282: @var{name} must have the same name and values for @var{multiplicity} and
3283: @var{simultaneity}.
3284:
3285: @var{test} is an attribute test that selects the insns we are describing
3286: in this definition. Note that an insn may use more than one function
3287: unit and a function unit may be specified in more than one
3288: @code{define_function_unit}.
3289:
3290: @var{ready-delay} is an integer that specifies the number of cycles
3291: after which the result of the instruction can be used without
3292: introducing any stalls.
3293:
3294: @var{busy-delay} is an integer that represents the default cost if an
3295: insn is scheduled for this unit while the unit is active with another
3296: insn. If @var{simultaneity} is zero, this specification is ignored.
3297: Otherwise, a zero value indicates that these insns execute on @var{name}
3298: in a fully pipelined fashion, even if @var{simultaneity} is non-zero. A
3299: non-zero value indicates that scheduling a new insn on this unit while
3300: another is active will incur a cost. A cost of two indicates a single
3301: cycle delay. For a normal non-pipelined function unit, @var{busy-delay}
3302: will be twice @var{ready-delay}.
3303:
3304: @var{conflict-list} is an optional list giving detailed conflict costs
3305: for this unit. If specified, it is a list of condition test expressions
3306: which are applied to insns already executing in @var{name}. For each
3307: insn that is in the list, @var{busy-delay} will be used for the conflict
3308: cost, while a value of zero will be used for insns not in the list.
3309:
3310: Typical uses of this vector are where a floating point function unit can
3311: pipeline either single- or double-precision operations, but not both, or
3312: where a memory unit can pipeline loads, but not stores, etc.
3313:
3314: As an example, consider a classic RISC machine where the result of a
3315: load instruction is not available for two cycles (a single ``delay''
3316: instruction is required) and where only one load instruction can be executed
3317: simultaneously. This would be specified as:
3318:
3319: @example
3320: (define_function_unit "memory" 1 1 (eq_attr "type" "load") 2 4)
3321: @end example
3322:
3323: For the case of a floating point function unit that can pipeline either
3324: single or double precision, but not both, the following could be specified:
3325:
3326: @example
3327: (define_function_unit
3328: "fp" 1 1 (eq_attr "type" "sp_fp") 4 8 (eq_attr "type" "dp_fp")]
3329: (define_function_unit
3330: "fp" 1 1 (eq_attr "type" "dp_fp") 4 8 (eq_attr "type" "sp_fp")]
3331: @end example
3332:
3333: @strong{Note:} No code currently exists to avoid function unit
3334: conflicts, only data conflicts. Hence @var{multiplicity},
3335: @var{simultaneity}, @var{busy-cost}, and @var{conflict-list} are
3336: currently ignored. When such code is written, it is possible that the
3337: specifications for these values may be changed. It has recently come to
3338: our attention that these specifications may not allow modeling of some
3339: of the newer ``superscalar'' processors that have insns using multiple
3340: pipelined units. These insns will cause a potential conflict for the
3341: second unit used during their execution and there is no way of
3342: representing that conflict. We welcome any examples of how function
3343: unit conflicts work in such processors and suggestions for their
3344: representation.
3345: @end ifset
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.