1 This is Info file gcc.info, produced by Makeinfo version 1.68 from the
4 This file documents the use and the internals of the GNU compiler.
6 Published by the Free Software Foundation 59 Temple Place - Suite 330
7 Boston, MA 02111-1307 USA
9 Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997 Free
10 Software Foundation, Inc.
12 Permission is granted to make and distribute verbatim copies of this
13 manual provided the copyright notice and this permission notice are
14 preserved on all copies.
16 Permission is granted to copy and distribute modified versions of
17 this manual under the conditions for verbatim copying, provided also
18 that the sections entitled "GNU General Public License," "Funding for
19 Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
20 included exactly as in the original, and provided that the entire
21 resulting derived work is distributed under the terms of a permission
22 notice identical to this one.
24 Permission is granted to copy and distribute translations of this
25 manual into another language, under the above conditions for modified
26 versions, except that the sections entitled "GNU General Public
27 License," "Funding for Free Software," and "Protect Your Freedom--Fight
28 `Look And Feel'", and this permission notice, may be included in
29 translations approved by the Free Software Foundation instead of in the
33 File: gcc.info, Node: Standard Names, Next: Pattern Ordering, Prev: Constraints, Up: Machine Desc
35 Standard Pattern Names For Generation
36 =====================================
38 Here is a table of the instruction names that are meaningful in the
39 RTL generation pass of the compiler. Giving one of these names to an
40 instruction pattern tells the RTL generation pass that it can use the
41 pattern in to accomplish a certain task.
44 Here M stands for a two-letter machine mode name, in lower case.
45 This instruction pattern moves data with that machine mode from
46 operand 1 to operand 0. For example, `movsi' moves full-word data.
48 If operand 0 is a `subreg' with mode M of a register whose own
49 mode is wider than M, the effect of this instruction is to store
50 the specified value in the part of the register that corresponds
51 to mode M. The effect on the rest of the register is undefined.
53 This class of patterns is special in several ways. First of all,
54 each of these names *must* be defined, because there is no other
55 way to copy a datum from one place to another.
57 Second, these patterns are not used solely in the RTL generation
58 pass. Even the reload pass can generate move insns to copy values
59 from stack slots into temporary registers. When it does so, one
60 of the operands is a hard register and the other is an operand
61 that can need to be reloaded into a register.
63 Therefore, when given such a pair of operands, the pattern must
64 generate RTL which needs no reloading and needs no temporary
65 registers--no registers other than the operands. For example, if
66 you support the pattern with a `define_expand', then in such a
67 case the `define_expand' mustn't call `force_reg' or any other such
68 function which might generate new pseudo registers.
70 This requirement exists even for subword modes on a RISC machine
71 where fetching those modes from memory normally requires several
72 insns and some temporary registers. Look in `spur.md' to see how
73 the requirement can be satisfied.
75 During reload a memory reference with an invalid address may be
76 passed as an operand. Such an address will be replaced with a
77 valid address later in the reload pass. In this case, nothing may
78 be done with the address except to use it as it stands. If it is
79 copied, it will not be replaced with a valid address. No attempt
80 should be made to make such an address into a valid address and no
81 routine (such as `change_address') that will do so may be called.
82 Note that `general_operand' will fail when applied to such an
85 The global variable `reload_in_progress' (which must be explicitly
86 declared if required) can be used to determine whether such special
89 The variety of operands that have reloads depends on the rest of
90 the machine description, but typically on a RISC machine these can
91 only be pseudo registers that did not get hard registers, while on
92 other machines explicit memory references will get optional
95 If a scratch register is required to move an object to or from
96 memory, it can be allocated using `gen_reg_rtx' prior to reload.
97 But this is impossible during and after reload. If there are
98 cases needing scratch registers after reload, you must define
99 `SECONDARY_INPUT_RELOAD_CLASS' and perhaps also
100 `SECONDARY_OUTPUT_RELOAD_CLASS' to detect them, and provide
101 patterns `reload_inM' or `reload_outM' to handle them. *Note
104 The constraints on a `movM' must permit moving any hard register
105 to any other hard register provided that `HARD_REGNO_MODE_OK'
106 permits mode M in both registers and `REGISTER_MOVE_COST' applied
107 to their classes returns a value of 2.
109 It is obligatory to support floating point `movM' instructions
110 into and out of any registers that can hold fixed point values,
111 because unions and structures (which have modes `SImode' or
112 `DImode') can be in those registers and they may have floating
115 There may also be a need to support fixed point `movM'
116 instructions in and out of floating point registers.
117 Unfortunately, I have forgotten why this was so, and I don't know
118 whether it is still true. If `HARD_REGNO_MODE_OK' rejects fixed
119 point values in floating point registers, then the constraints of
120 the fixed point `movM' instructions must be designed to avoid ever
121 trying to reload into a floating point register.
125 Like `movM', but used when a scratch register is required to move
126 between operand 0 and operand 1. Operand 2 describes the scratch
127 register. See the discussion of the `SECONDARY_RELOAD_CLASS'
128 macro in *note Register Classes::..
131 Like `movM' except that if operand 0 is a `subreg' with mode M of
132 a register whose natural mode is wider, the `movstrictM'
133 instruction is guaranteed not to alter any of the register except
134 the part which belongs to mode M.
137 Load several consecutive memory locations into consecutive
138 registers. Operand 0 is the first of the consecutive registers,
139 operand 1 is the first memory location, and operand 2 is a
140 constant: the number of consecutive registers.
142 Define this only if the target machine really has such an
143 instruction; do not define this if the most efficient way of
144 loading consecutive registers from memory is to do them one at a
147 On some machines, there are restrictions as to which consecutive
148 registers can be stored into memory, such as particular starting or
149 ending register numbers or only a range of valid counts. For those
150 machines, use a `define_expand' (*note Expander Definitions::.)
151 and make the pattern fail if the restrictions are not met.
153 Write the generated insn as a `parallel' with elements being a
154 `set' of one register from the appropriate memory location (you may
155 also need `use' or `clobber' elements). Use a `match_parallel'
156 (*note RTL Template::.) to recognize the insn. See `a29k.md' and
157 `rs6000.md' for examples of the use of this insn pattern.
160 Similar to `load_multiple', but store several consecutive registers
161 into consecutive memory locations. Operand 0 is the first of the
162 consecutive memory locations, operand 1 is the first register, and
163 operand 2 is a constant: the number of consecutive registers.
166 Add operand 2 and operand 1, storing the result in operand 0. All
167 operands must have mode M. This can be used even on two-address
168 machines, by means of constraints requiring operands 1 and 0 to be
172 `divM3', `udivM3', `modM3', `umodM3'
173 `sminM3', `smaxM3', `uminM3', `umaxM3'
174 `andM3', `iorM3', `xorM3'
175 Similar, for other arithmetic operations.
178 Multiply operands 1 and 2, which have mode `HImode', and store a
179 `SImode' product in operand 0.
181 `mulqihi3', `mulsidi3'
182 Similar widening-multiplication instructions of other widths.
184 `umulqihi3', `umulhisi3', `umulsidi3'
185 Similar widening-multiplication instructions that do unsigned
189 Perform a signed multiplication of operands 1 and 2, which have
190 mode M, and store the most significant half of the product in
191 operand 0. The least significant half of the product is discarded.
194 Similar, but the multiplication is unsigned.
197 Signed division that produces both a quotient and a remainder.
198 Operand 1 is divided by operand 2 to produce a quotient stored in
199 operand 0 and a remainder stored in operand 3.
201 For machines with an instruction that produces both a quotient and
202 a remainder, provide a pattern for `divmodM4' but do not provide
203 patterns for `divM3' and `modM3'. This allows optimization in the
204 relatively common case when both the quotient and remainder are
207 If an instruction that just produces a quotient or just a remainder
208 exists and is more efficient than the instruction that produces
209 both, write the output routine of `divmodM4' to call
210 `find_reg_note' and look for a `REG_UNUSED' note on the quotient
211 or remainder and generate the appropriate instruction.
214 Similar, but does unsigned division.
217 Arithmetic-shift operand 1 left by a number of bits specified by
218 operand 2, and store the result in operand 0. Here M is the mode
219 of operand 0 and operand 1; operand 2's mode is specified by the
220 instruction pattern, and the compiler will convert the operand to
221 that mode before generating the instruction.
223 `ashrM3', `lshrM3', `rotlM3', `rotrM3'
224 Other shift and rotate instructions, analogous to the `ashlM3'
228 Negate operand 1 and store the result in operand 0.
231 Store the absolute value of operand 1 into operand 0.
234 Store the square root of operand 1 into operand 0.
236 The `sqrt' built-in function of C always uses the mode which
237 corresponds to the C data type `double'.
240 Store into operand 0 one plus the index of the least significant
241 1-bit of operand 1. If operand 1 is zero, store zero. M is the
242 mode of operand 0; operand 1's mode is specified by the instruction
243 pattern, and the compiler will convert the operand to that mode
244 before generating the instruction.
246 The `ffs' built-in function of C always uses the mode which
247 corresponds to the C data type `int'.
250 Store the bitwise-complement of operand 1 into operand 0.
253 Compare operand 0 and operand 1, and set the condition codes. The
254 RTL pattern should look like this:
256 (set (cc0) (compare (match_operand:M 0 ...)
257 (match_operand:M 1 ...)))
260 Compare operand 0 against zero, and set the condition codes. The
261 RTL pattern should look like this:
263 (set (cc0) (match_operand:M 0 ...))
265 `tstM' patterns should not be defined for machines that do not use
266 `(cc0)'. Doing so would confuse the optimizer since it would no
267 longer be clear which `set' operations were comparisons. The
268 `cmpM' patterns should be used instead.
271 Block move instruction. The addresses of the destination and
272 source strings are the first two operands, and both are in mode
273 `Pmode'. The number of bytes to move is the third operand, in
276 The fourth operand is the known shared alignment of the source and
277 destination, in the form of a `const_int' rtx. Thus, if the
278 compiler knows that both source and destination are word-aligned,
279 it may provide the value 4 for this operand.
281 These patterns need not give special consideration to the
282 possibility that the source and destination strings might overlap.
285 Block clear instruction. The addresses of the destination string
286 is the first operand, in mode `Pmode'. The number of bytes to
287 clear is the second operand, in mode M.
289 The third operand is the known alignment of the destination, in
290 the form of a `const_int' rtx. Thus, if the compiler knows that
291 the destination is word-aligned, it may provide the value 4 for
295 Block compare instruction, with five operands. Operand 0 is the
296 output; it has mode M. The remaining four operands are like the
297 operands of `movstrM'. The two memory blocks specified are
298 compared byte by byte in lexicographic order. The effect of the
299 instruction is to store a value in operand 0 whose sign indicates
300 the result of the comparison.
303 Compute the length of a string, with three operands. Operand 0 is
304 the result (of mode M), operand 1 is a `mem' referring to the
305 first character of the string, operand 2 is the character to
306 search for (normally zero), and operand 3 is a constant describing
307 the known alignment of the beginning of the string.
310 Convert signed integer operand 1 (valid for fixed point mode M) to
311 floating point mode N and store in operand 0 (which has mode N).
314 Convert unsigned integer operand 1 (valid for fixed point mode M)
315 to floating point mode N and store in operand 0 (which has mode N).
318 Convert operand 1 (valid for floating point mode M) to fixed point
319 mode N as a signed number and store in operand 0 (which has mode
320 N). This instruction's result is defined only when the value of
321 operand 1 is an integer.
324 Convert operand 1 (valid for floating point mode M) to fixed point
325 mode N as an unsigned number and store in operand 0 (which has
326 mode N). This instruction's result is defined only when the value
327 of operand 1 is an integer.
330 Convert operand 1 (valid for floating point mode M) to an integer
331 value, still represented in floating point mode M, and store it in
332 operand 0 (valid for floating point mode M).
335 Like `fixMN2' but works for any floating point value of mode M by
336 converting the value to an integer.
339 Like `fixunsMN2' but works for any floating point value of mode M
340 by converting the value to an integer.
343 Truncate operand 1 (valid for mode M) to mode N and store in
344 operand 0 (which has mode N). Both modes must be fixed point or
348 Sign-extend operand 1 (valid for mode M) to mode N and store in
349 operand 0 (which has mode N). Both modes must be fixed point or
353 Zero-extend operand 1 (valid for mode M) to mode N and store in
354 operand 0 (which has mode N). Both modes must be fixed point.
357 Extract a bit field from operand 1 (a register or memory operand),
358 where operand 2 specifies the width in bits and operand 3 the
359 starting bit, and store it in operand 0. Operand 0 must have mode
360 `word_mode'. Operand 1 may have mode `byte_mode' or `word_mode';
361 often `word_mode' is allowed only for registers. Operands 2 and 3
362 must be valid for `word_mode'.
364 The RTL generation pass generates this instruction only with
365 constants for operands 2 and 3.
367 The bit-field value is sign-extended to a full word integer before
368 it is stored in operand 0.
371 Like `extv' except that the bit-field value is zero-extended.
374 Store operand 3 (which must be valid for `word_mode') into a bit
375 field in operand 0, where operand 1 specifies the width in bits and
376 operand 2 the starting bit. Operand 0 may have mode `byte_mode' or
377 `word_mode'; often `word_mode' is allowed only for registers.
378 Operands 1 and 2 must be valid for `word_mode'.
380 The RTL generation pass generates this instruction only with
381 constants for operands 1 and 2.
384 Conditionally move operand 2 or operand 3 into operand 0 according
385 to the comparison in operand 1. If the comparison is true,
386 operand 2 is moved into operand 0, otherwise operand 3 is moved.
388 The mode of the operands being compared need not be the same as
389 the operands being moved. Some machines, sparc64 for example,
390 have instructions that conditionally move an integer value based
391 on the floating point condition codes and vice versa.
393 If the machine does not have conditional move instructions, do not
394 define these patterns.
397 Store zero or nonzero in the operand according to the condition
398 codes. Value stored is nonzero iff the condition COND is true.
399 COND is the name of a comparison operation expression code, such
400 as `eq', `lt' or `leu'.
402 You specify the mode that the operand must have when you write the
403 `match_operand' expression. The compiler automatically sees which
404 mode you have used and supplies an operand of that mode.
406 The value stored for a true condition must have 1 as its low bit,
407 or else must be negative. Otherwise the instruction is not
408 suitable and you should omit it from the machine description. You
409 describe to the compiler exactly which value is stored by defining
410 the macro `STORE_FLAG_VALUE' (*note Misc::.). If a description
411 cannot be found that can be used for all the `sCOND' patterns, you
412 should omit those operations from the machine description.
414 These operations may fail, but should do so only in relatively
415 uncommon cases; if they would fail for common cases involving
416 integer comparisons, it is best to omit these patterns.
418 If these operations are omitted, the compiler will usually
419 generate code that copies the constant one to the target and
420 branches around an assignment of zero to the target. If this code
421 is more efficient than the potential instructions used for the
422 `sCOND' pattern followed by those required to convert the result
423 into a 1 or a zero in `SImode', you should omit the `sCOND'
424 operations from the machine description.
427 Conditional branch instruction. Operand 0 is a `label_ref' that
428 refers to the label to jump to. Jump if the condition codes meet
431 Some machines do not follow the model assumed here where a
432 comparison instruction is followed by a conditional branch
433 instruction. In that case, the `cmpM' (and `tstM') patterns should
434 simply store the operands away and generate all the required insns
435 in a `define_expand' (*note Expander Definitions::.) for the
436 conditional branch operations. All calls to expand `bCOND'
437 patterns are immediately preceded by calls to expand either a
438 `cmpM' pattern or a `tstM' pattern.
440 Machines that use a pseudo register for the condition code value,
441 or where the mode used for the comparison depends on the condition
442 being tested, should also use the above mechanism. *Note Jump
445 The above discussion also applies to the `movMODEcc' and `sCOND'
449 Subroutine call instruction returning no value. Operand 0 is the
450 function to call; operand 1 is the number of bytes of arguments
451 pushed (in mode `SImode', except it is normally a `const_int');
452 operand 2 is the number of registers used as operands.
454 On most machines, operand 2 is not actually stored into the RTL
455 pattern. It is supplied for the sake of some RISC machines which
456 need to put this information into the assembler code; they can put
457 it in the RTL instead of operand 1.
459 Operand 0 should be a `mem' RTX whose address is the address of the
460 function. Note, however, that this address can be a `symbol_ref'
461 expression even if it would not be a legitimate memory address on
462 the target machine. If it is also not a valid argument for a call
463 instruction, the pattern for this operation should be a
464 `define_expand' (*note Expander Definitions::.) that places the
465 address into a register and uses that register in the call
469 Subroutine call instruction returning a value. Operand 0 is the
470 hard register in which the value is returned. There are three more
471 operands, the same as the three operands of the `call' instruction
472 (but with numbers increased by one).
474 Subroutines that return `BLKmode' objects use the `call' insn.
476 `call_pop', `call_value_pop'
477 Similar to `call' and `call_value', except used if defined and if
478 `RETURN_POPS_ARGS' is non-zero. They should emit a `parallel'
479 that contains both the function call and a `set' to indicate the
480 adjustment made to the frame pointer.
482 For machines where `RETURN_POPS_ARGS' can be non-zero, the use of
483 these patterns increases the number of functions for which the
484 frame pointer can be eliminated, if desired.
487 Subroutine call instruction returning a value of any type.
488 Operand 0 is the function to call; operand 1 is a memory location
489 where the result of calling the function is to be stored; operand
490 2 is a `parallel' expression where each element is a `set'
491 expression that indicates the saving of a function return value
492 into the result block.
494 This instruction pattern should be defined to support
495 `__builtin_apply' on machines where special instructions are needed
496 to call a subroutine with arbitrary arguments or to save the value
497 returned. This instruction pattern is required on machines that
498 have multiple registers that can hold a return value (i.e.
499 `FUNCTION_VALUE_REGNO_P' is true for more than one register).
502 Subroutine return instruction. This instruction pattern name
503 should be defined only if a single instruction can do all the work
504 of returning from a function.
506 Like the `movM' patterns, this pattern is also used after the RTL
507 generation phase. In this case it is to support machines where
508 multiple instructions are usually needed to return from a
509 function, but some class of functions only requires one
510 instruction to implement a return. Normally, the applicable
511 functions are those which do not need to save any registers or
512 allocate stack space.
514 For such machines, the condition specified in this pattern should
515 only be true when `reload_completed' is non-zero and the function's
516 epilogue would only be a single instruction. For machines with
517 register windows, the routine `leaf_function_p' may be used to
518 determine if a register window push is required.
520 Machines that have conditional return instructions should define
525 (if_then_else (match_operator
526 0 "comparison_operator"
527 [(cc0) (const_int 0)])
533 where CONDITION would normally be the same condition specified on
534 the named `return' pattern.
537 Untyped subroutine return instruction. This instruction pattern
538 should be defined to support `__builtin_return' on machines where
539 special instructions are needed to return a value of any type.
541 Operand 0 is a memory location where the result of calling a
542 function with `__builtin_apply' is stored; operand 1 is a
543 `parallel' expression where each element is a `set' expression
544 that indicates the restoring of a function return value from the
548 No-op instruction. This instruction pattern name should always be
549 defined to output a no-op in assembler code. `(const_int 0)' will
550 do as an RTL pattern.
553 An instruction to jump to an address which is operand zero. This
554 pattern name is mandatory on all machines.
557 Instruction to jump through a dispatch table, including bounds
558 checking. This instruction takes five operands:
560 1. The index to dispatch on, which has mode `SImode'.
562 2. The lower bound for indices in the table, an integer constant.
564 3. The total range of indices in the table--the largest index
565 minus the smallest one (both inclusive).
567 4. A label that precedes the table itself.
569 5. A label to jump to if the index has a value outside the
570 bounds. (If the machine-description macro
571 `CASE_DROPS_THROUGH' is defined, then an out-of-bounds index
572 drops through to the code following the jump table instead of
573 jumping to this label. In that case, this label is not
574 actually used by the `casesi' instruction, but it is always
575 provided as an operand.)
577 The table is a `addr_vec' or `addr_diff_vec' inside of a
578 `jump_insn'. The number of elements in the table is one plus the
579 difference between the upper bound and the lower bound.
582 Instruction to jump to a variable address. This is a low-level
583 capability which can be used to implement a dispatch table when
584 there is no `casesi' pattern.
586 This pattern requires two operands: the address or offset, and a
587 label which should immediately precede the jump table. If the
588 macro `CASE_VECTOR_PC_RELATIVE' is defined then the first operand
589 is an offset which counts from the address of the table;
590 otherwise, it is an absolute address to jump to. In either case,
591 the first operand has mode `Pmode'.
593 The `tablejump' insn is always the last insn before the jump table
594 it uses. Its assembler code normally has no need to use the
595 second operand, but you should incorporate it in the RTL pattern so
596 that the jump optimizer will not delete the table as unreachable
599 `canonicalize_funcptr_for_compare'
600 Canonicalize the function pointer in operand 1 and store the result
603 Operand 0 is always a `reg' and has mode `Pmode'; operand 1 may be
604 a `reg', `mem', `symbol_ref', `const_int', etc and also has mode
607 Canonicalization of a function pointer usually involves computing
608 the address of the function which would be called if the function
609 pointer were used in an indirect call.
611 Only define this pattern if function pointers on the target machine
612 can have different values but still call the same function when
613 used in an indirect call.
616 `save_stack_function'
617 `save_stack_nonlocal'
618 `restore_stack_block'
619 `restore_stack_function'
620 `restore_stack_nonlocal'
621 Most machines save and restore the stack pointer by copying it to
622 or from an object of mode `Pmode'. Do not define these patterns on
625 Some machines require special handling for stack pointer saves and
626 restores. On those machines, define the patterns corresponding to
627 the non-standard cases by using a `define_expand' (*note Expander
628 Definitions::.) that produces the required insns. The three types
629 of saves and restores are:
631 1. `save_stack_block' saves the stack pointer at the start of a
632 block that allocates a variable-sized object, and
633 `restore_stack_block' restores the stack pointer when the
636 2. `save_stack_function' and `restore_stack_function' do a
637 similar job for the outermost block of a function and are
638 used when the function allocates variable-sized objects or
639 calls `alloca'. Only the epilogue uses the restored stack
640 pointer, allowing a simpler save or restore sequence on some
643 3. `save_stack_nonlocal' is used in functions that contain labels
644 branched to by nested functions. It saves the stack pointer
645 in such a way that the inner function can use
646 `restore_stack_nonlocal' to restore the stack pointer. The
647 compiler generates code to restore the frame and argument
648 pointer registers, but some machines require saving and
649 restoring additional data such as register window information
650 or stack backchains. Place insns in these patterns to save
651 and restore any such required data.
653 When saving the stack pointer, operand 0 is the save area and
654 operand 1 is the stack pointer. The mode used to allocate the
655 save area is the mode of operand 0. You must specify an integral
656 mode, or `VOIDmode' if no save area is needed for a particular
657 type of save (either because no save is needed or because a
658 machine-specific save area can be used). Operand 0 is the stack
659 pointer and operand 1 is the save area for restore operations. If
660 `save_stack_block' is defined, operand 0 must not be `VOIDmode'
661 since these saves can be arbitrarily nested.
663 A save area is a `mem' that is at a constant offset from
664 `virtual_stack_vars_rtx' when the stack pointer is saved for use by
665 nonlocal gotos and a `reg' in the other two cases.
668 Subtract (or add if `STACK_GROWS_DOWNWARD' is undefined) operand 1
669 from the stack pointer to create space for dynamically allocated
672 Store the resultant pointer to this space into operand 0. If you
673 are allocating space from the main stack, do this by emitting a
674 move insn to copy `virtual_stack_dynamic_rtx' to operand 0. If
675 you are allocating the space elsewhere, generate code to copy the
676 location of the space to operand 0. In the latter case, you must
677 ensure this space gets freed when the corresponding space on the
680 Do not define this pattern if all that must be done is the
681 subtraction. Some machines require other operations such as stack
682 probes or maintaining the back chain. Define this pattern to emit
683 those operations in addition to updating the stack pointer.
686 Some machines require instructions to be executed after space is
687 allocated from the stack, for example to generate a reference at
688 the bottom of the stack.
690 If you need to emit instructions before the stack has been
691 adjusted, put them into the `allocate_stack' pattern. Otherwise,
692 define this pattern to emit the required instructions.
694 No operands are provided.
697 If stack checking cannot be done on your system by probing the
698 stack with a load or store instruction (*note Stack Checking::.),
699 define this pattern to perform the needed check and signaling an
700 error if the stack has overflowed. The single operand is the
701 location in the stack furthest from the current stack pointer that
702 you need to validate. Normally, on machines where this pattern is
703 needed, you would obtain the stack limit from a global or
704 thread-specific variable or register.
707 Emit code to generate a non-local goto, e.g., a jump from one
708 function to a label in an outer function. This pattern has four
709 arguments, each representing a value to be used in the jump. The
710 first argument is to be loadedd into the frame pointer, the second
711 is the address to branch to (code to dispatch to the actual label),
712 the third is the address of a location where the stack is saved,
713 and the last is the address of the label, to be placed in the
714 location for the incoming static chain.
716 On most machines you need not define this pattern, since GNU CC
717 will already generate the correct code, which is to load the frame
718 pointer and static chain, restore the stack (using the
719 `restore_stack_nonlocal' pattern, if defined), and jump indirectly
720 to the dispatcher. You need only define this pattern if this code
721 will not work on your machine.
723 `nonlocal_goto_receiver'
724 This pattern, if defined, contains code needed at the target of a
725 nonlocal goto after the code already generated by GNU CC. You
726 will not normally need to define this pattern. A typical reason
727 why you might need this pattern is if some value, such as a
728 pointer to a global table, must be restored when the frame pointer
729 is restored. There are no arguments.
732 This pattern, if defined, contains code needed at the site of an
733 exception handler that isn't needed at the site of a nonlocal
734 goto. You will not normally need to define this pattern. A
735 typical reason why you might need this pattern is if some value,
736 such as a pointer to a global table, must be restored after
737 control flow is branched to the handler of an exception. There
741 File: gcc.info, Node: Pattern Ordering, Next: Dependent Patterns, Prev: Standard Names, Up: Machine Desc
743 When the Order of Patterns Matters
744 ==================================
746 Sometimes an insn can match more than one instruction pattern. Then
747 the pattern that appears first in the machine description is the one
748 used. Therefore, more specific patterns (patterns that will match
749 fewer things) and faster instructions (those that will produce better
750 code when they do match) should usually go first in the description.
752 In some cases the effect of ordering the patterns can be used to hide
753 a pattern when it is not valid. For example, the 68000 has an
754 instruction for converting a fullword to floating point and another for
755 converting a byte to floating point. An instruction converting an
756 integer to floating point could match either one. We put the pattern
757 to convert the fullword first to make sure that one will be used rather
758 than the other. (Otherwise a large integer might be generated as a
759 single-byte immediate quantity, which would not work.) Instead of
760 using this pattern ordering it would be possible to make the pattern
761 for convert-a-byte smart enough to deal properly with any constant
765 File: gcc.info, Node: Dependent Patterns, Next: Jump Patterns, Prev: Pattern Ordering, Up: Machine Desc
767 Interdependence of Patterns
768 ===========================
770 Every machine description must have a named pattern for each of the
771 conditional branch names `bCOND'. The recognition template must always
775 (if_then_else (COND (cc0) (const_int 0))
776 (label_ref (match_operand 0 "" ""))
779 In addition, every machine description must have an anonymous pattern
780 for each of the possible reverse-conditional branches. Their templates
784 (if_then_else (COND (cc0) (const_int 0))
786 (label_ref (match_operand 0 "" ""))))
788 They are necessary because jump optimization can turn direct-conditional
789 branches into reverse-conditional branches.
791 It is often convenient to use the `match_operator' construct to
792 reduce the number of patterns that must be specified for branches. For
797 (if_then_else (match_operator 0 "comparison_operator"
798 [(cc0) (const_int 0)])
800 (label_ref (match_operand 1 "" ""))))]
804 In some cases machines support instructions identical except for the
805 machine mode of one or more operands. For example, there may be
806 "sign-extend halfword" and "sign-extend byte" instructions whose
809 (set (match_operand:SI 0 ...)
810 (extend:SI (match_operand:HI 1 ...)))
812 (set (match_operand:SI 0 ...)
813 (extend:SI (match_operand:QI 1 ...)))
815 Constant integers do not specify a machine mode, so an instruction to
816 extend a constant value could match either pattern. The pattern it
817 actually will match is the one that appears first in the file. For
818 correct results, this must be the one for the widest possible mode
819 (`HImode', here). If the pattern matches the `QImode' instruction, the
820 results will be incorrect if the constant value does not actually fit
823 Such instructions to extend constants are rarely generated because
824 they are optimized away, but they do occasionally happen in nonoptimized
827 If a constraint in a pattern allows a constant, the reload pass may
828 replace a register with a constant permitted by the constraint in some
829 cases. Similarly for memory references. Because of this substitution,
830 you should not provide separate patterns for increment and decrement
831 instructions. Instead, they should be generated from the same pattern
832 that supports register-register add insns by examining the operands and
833 generating the appropriate machine instruction.
836 File: gcc.info, Node: Jump Patterns, Next: Insn Canonicalizations, Prev: Dependent Patterns, Up: Machine Desc
838 Defining Jump Instruction Patterns
839 ==================================
841 For most machines, GNU CC assumes that the machine has a condition
842 code. A comparison insn sets the condition code, recording the results
843 of both signed and unsigned comparison of the given operands. A
844 separate branch insn tests the condition code and branches or not
845 according its value. The branch insns come in distinct signed and
846 unsigned flavors. Many common machines, such as the Vax, the 68000 and
847 the 32000, work this way.
849 Some machines have distinct signed and unsigned compare
850 instructions, and only one set of conditional branch instructions. The
851 easiest way to handle these machines is to treat them just like the
852 others until the final stage where assembly code is written. At this
853 time, when outputting code for the compare instruction, peek ahead at
854 the following branch using `next_cc0_user (insn)'. (The variable
855 `insn' refers to the insn being output, in the output-writing code in
856 an instruction pattern.) If the RTL says that is an unsigned branch,
857 output an unsigned compare; otherwise output a signed compare. When
858 the branch itself is output, you can treat signed and unsigned branches
861 The reason you can do this is that GNU CC always generates a pair of
862 consecutive RTL insns, possibly separated by `note' insns, one to set
863 the condition code and one to test it, and keeps the pair inviolate
866 To go with this technique, you must define the machine-description
867 macro `NOTICE_UPDATE_CC' to do `CC_STATUS_INIT'; in other words, no
868 compare instruction is superfluous.
870 Some machines have compare-and-branch instructions and no condition
871 code. A similar technique works for them. When it is time to "output"
872 a compare instruction, record its operands in two static variables.
873 When outputting the branch-on-condition-code instruction that follows,
874 actually output a compare-and-branch instruction that uses the
877 It also works to define patterns for compare-and-branch instructions.
878 In optimizing compilation, the pair of compare and branch instructions
879 will be combined according to these patterns. But this does not happen
880 if optimization is not requested. So you must use one of the solutions
881 above in addition to any special patterns you define.
883 In many RISC machines, most instructions do not affect the condition
884 code and there may not even be a separate condition code register. On
885 these machines, the restriction that the definition and use of the
886 condition code be adjacent insns is not necessary and can prevent
887 important optimizations. For example, on the IBM RS/6000, there is a
888 delay for taken branches unless the condition code register is set three
889 instructions earlier than the conditional branch. The instruction
890 scheduler cannot perform this optimization if it is not permitted to
891 separate the definition and use of the condition code register.
893 On these machines, do not use `(cc0)', but instead use a register to
894 represent the condition code. If there is a specific condition code
895 register in the machine, use a hard register. If the condition code or
896 comparison result can be placed in any general register, or if there are
897 multiple condition registers, use a pseudo register.
899 On some machines, the type of branch instruction generated may
900 depend on the way the condition code was produced; for example, on the
901 68k and Sparc, setting the condition code directly from an add or
902 subtract instruction does not clear the overflow bit the way that a test
903 instruction does, so a different branch instruction must be used for
904 some conditional branches. For machines that use `(cc0)', the set and
905 use of the condition code must be adjacent (separated only by `note'
906 insns) allowing flags in `cc_status' to be used. (*Note Condition
907 Code::.) Also, the comparison and branch insns can be located from
908 each other by using the functions `prev_cc0_setter' and `next_cc0_user'.
910 However, this is not true on machines that do not use `(cc0)'. On
911 those machines, no assumptions can be made about the adjacency of the
912 compare and branch insns and the above methods cannot be used. Instead,
913 we use the machine mode of the condition code register to record
914 different formats of the condition code register.
916 Registers used to store the condition code value should have a mode
917 that is in class `MODE_CC'. Normally, it will be `CCmode'. If
918 additional modes are required (as for the add example mentioned above in
919 the Sparc), define the macro `EXTRA_CC_MODES' to list the additional
920 modes required (*note Condition Code::.). Also define `EXTRA_CC_NAMES'
921 to list the names of those modes and `SELECT_CC_MODE' to choose a mode
922 given an operand of a compare.
924 If it is known during RTL generation that a different mode will be
925 required (for example, if the machine has separate compare instructions
926 for signed and unsigned quantities, like most IBM processors), they can
927 be specified at that time.
929 If the cases that require different modes would be made by
930 instruction combination, the macro `SELECT_CC_MODE' determines which
931 machine mode should be used for the comparison result. The patterns
932 should be written using that mode. To support the case of the add on
933 the Sparc discussed above, we have the pattern
936 [(set (reg:CC_NOOV 0)
938 (plus:SI (match_operand:SI 0 "register_operand" "%r")
939 (match_operand:SI 1 "arith_operand" "rI"))
944 The `SELECT_CC_MODE' macro on the Sparc returns `CC_NOOVmode' for
945 comparisons whose argument is a `plus'.
948 File: gcc.info, Node: Insn Canonicalizations, Next: Peephole Definitions, Prev: Jump Patterns, Up: Machine Desc
950 Canonicalization of Instructions
951 ================================
953 There are often cases where multiple RTL expressions could represent
954 an operation performed by a single machine instruction. This situation
955 is most commonly encountered with logical, branch, and
956 multiply-accumulate instructions. In such cases, the compiler attempts
957 to convert these multiple RTL expressions into a single canonical form
958 to reduce the number of insn patterns required.
960 In addition to algebraic simplifications, following canonicalizations
963 * For commutative and comparison operators, a constant is always
964 made the second operand. If a machine only supports a constant as
965 the second operand, only patterns that match a constant in the
966 second operand need be supplied.
968 For these operators, if only one operand is a `neg', `not',
969 `mult', `plus', or `minus' expression, it will be the first
972 * For the `compare' operator, a constant is always the second operand
973 on machines where `cc0' is used (*note Jump Patterns::.). On other
974 machines, there are rare cases where the compiler might want to
975 construct a `compare' with a constant as the first operand.
976 However, these cases are not common enough for it to be worthwhile
977 to provide a pattern matching a constant as the first operand
978 unless the machine actually has such an instruction.
980 An operand of `neg', `not', `mult', `plus', or `minus' is made the
981 first operand under the same conditions as above.
983 * `(minus X (const_int N))' is converted to `(plus X (const_int
986 * Within address computations (i.e., inside `mem'), a left shift is
987 converted into the appropriate multiplication by a power of two.
989 * De`Morgan's Law is used to move bitwise negation inside a bitwise
990 logical-and or logical-or operation. If this results in only one
991 operand being a `not' expression, it will be the first one.
993 A machine that has an instruction that performs a bitwise
994 logical-and of one operand with the bitwise negation of the other
995 should specify the pattern for that instruction as
998 [(set (match_operand:M 0 ...)
999 (and:M (not:M (match_operand:M 1 ...))
1000 (match_operand:M 2 ...)))]
1004 Similarly, a pattern for a "NAND" instruction should be written
1007 [(set (match_operand:M 0 ...)
1008 (ior:M (not:M (match_operand:M 1 ...))
1009 (not:M (match_operand:M 2 ...))))]
1013 In both cases, it is not necessary to include patterns for the many
1014 logically equivalent RTL expressions.
1016 * The only possible RTL expressions involving both bitwise
1017 exclusive-or and bitwise negation are `(xor:M X Y)' and `(not:M
1020 * The sum of three items, one of which is a constant, will only
1023 (plus:M (plus:M X Y) CONSTANT)
1025 * On machines that do not use `cc0', `(compare X (const_int 0))'
1026 will be converted to X.
1028 * Equality comparisons of a group of bits (usually a single bit)
1029 with zero will be written using `zero_extract' rather than the
1030 equivalent `and' or `sign_extract' operations.