PREV UP NEXT Using and Porting GNU CC

15.7: Standard Pattern Names For Generation

Here is a table of the instruction names that are meaningful in the RTL generation pass of the compiler. Giving one of these names to an instruction pattern tells the RTL generation pass that it can use the pattern in to accomplish a certain task.

`movm'
Here m stands for a two-letter machine mode name, in lower case. This instruction pattern moves data with that machine mode from operand 1 to operand 0. For example, `movsi' moves full-word data.

If operand 0 is a subreg with mode m of a register whose own mode is wider than m, the effect of this instruction is to store the specified value in the part of the register that corresponds to mode m. The effect on the rest of the register is undefined.

This class of patterns is special in several ways. First of all, each of these names must be defined, because there is no other way to copy a datum from one place to another.

Second, these patterns are not used solely in the RTL generation pass. Even the reload pass can generate move insns to copy values from stack slots into temporary registers. When it does so, one of the operands is a hard register and the other is an operand that can need to be reloaded into a register.

Therefore, when given such a pair of operands, the pattern must generate RTL which needs no reloading and needs no temporary registers---no registers other than the operands. For example, if you support the pattern with a define_expand, then in such a case the define_expand mustn't call force_reg or any other such function which might generate new pseudo registers.

This requirement exists even for subword modes on a RISC machine where fetching those modes from memory normally requires several insns and some temporary registers. Look in `spur.md' to see how the requirement can be satisfied.

During reload a memory reference with an invalid address may be passed as an operand. Such an address will be replaced with a valid address later in the reload pass. In this case, nothing may be done with the address except to use it as it stands. If it is copied, it will not be replaced with a valid address. No attempt should be made to make such an address into a valid address and no routine (such as change_address) that will do so may be called. Note that general_operand will fail when applied to such an address.

The global variable reload_in_progress (which must be explicitly declared if required) can be used to determine whether such special handling is required.

The variety of operands that have reloads depends on the rest of the machine description, but typically on a RISC machine these can only be pseudo registers that did not get hard registers, while on other machines explicit memory references will get optional reloads.

If a scratch register is required to move an object to or from memory, it can be allocated using gen_reg_rtx prior to reload. But this is impossible during and after reload. If there are cases needing scratch registers after reload, you must define SECONDARY_INPUT_RELOAD_CLASS and perhaps also SECONDARY_OUTPUT_RELOAD_CLASS to detect them, and provide patterns `reload_inm' or `reload_outm' to handle them. See Register Classes.

The constraints on a `movem' must permit moving any hard register to any other hard register provided that HARD_REGNO_MODE_OK permits mode m in both registers and REGISTER_MOVE_COST applied to their classes returns a value of 2.

It is obligatory to support floating point `movem' instructions into and out of any registers that can hold fixed point values, because unions and structures (which have modes SImode or DImode) can be in those registers and they may have floating point members.

There may also be a need to support fixed point `movem' instructions in and out of floating point registers. Unfortunately, I have forgotten why this was so, and I don't know whether it is still true. If HARD_REGNO_MODE_OK rejects fixed point values in floating point registers, then the constraints of the fixed point `movem' instructions must be designed to avoid ever trying to reload into a floating point register.

`reload_inm'
`reload_outm'
Like `movm', but used when a scratch register is required to move between operand 0 and operand 1. Operand 2 describes the scratch register. See the discussion of the SECONDARY_RELOAD_CLASS macro in see Register Classes.
`movstrictm'
Like `movm' except that if operand 0 is a subreg with mode m of a register whose natural mode is wider, the `movstrictm' instruction is guaranteed not to alter any of the register except the part which belongs to mode m.
load_multiple
Load several consecutive memory locations into consecutive registers. Operand 0 is the first of the consecutive registers, operand 1 is the first memory location, and operand 2 is a constant: the number of consecutive registers.

Define this only if the target machine really has such an instruction; do not define this if the most efficient way of loading consecutive registers from memory is to do them one at a time.

On some machines, there are restrictions as to which consecutive registers can be stored into memory, such as particular starting or ending register numbers or only a range of valid counts. For those machines, use a define_expand (see Expander Definitions) and make the pattern fail if the restrictions are not met.

Write the generated insn as a parallel with elements being a set of one register from the appropriate memory location (you may also need use or clobber elements). Use a match_parallel (see RTL Template) to recognize the insn. See `a29k.md' and `rs6000.md' for examples of the use of this insn pattern.

store_multiple
Similar to `load_multiple', but store several consecutive registers into consecutive memory locations. Operand 0 is the first of the consecutive memory locations, operand 1 is the first register, and operand 2 is a constant: the number of consecutive registers.
`addm3'
Add operand 2 and operand 1, storing the result in operand 0. All operands must have mode m. This can be used even on two-address machines, by means of constraints requiring operands 1 and 0 to be the same location.
`subm3', `mulm3'
`divm3', `udivm3', `modm3', `umodm3'
`sminm3', `smaxm3', `uminm3', `umaxm3'
`andm3', `iorm3', `xorm3'
Similar, for other arithmetic operations.
`mulhisi3'
Multiply operands 1 and 2, which have mode HImode, and store a SImode product in operand 0.
`mulqihi3', `mulsidi3'
Similar widening-multiplication instructions of other widths.
`umulqihi3', `umulhisi3', `umulsidi3'
Similar widening-multiplication instructions that do unsigned multiplication.
`divmodm4'
Signed division that produces both a quotient and a remainder. Operand 1 is divided by operand 2 to produce a quotient stored in operand 0 and a remainder stored in operand 3.

For machines with an instruction that produces both a quotient and a remainder, provide a pattern for `divmodm4' but do not provide patterns for `divm3' and `modm3'. This allows optimization in the relatively common case when both the quotient and remainder are computed.

If an instruction that just produces a quotient or just a remainder exists and is more efficient than the instruction that produces both, write the output routine of `divmodm4' to call find_reg_note and look for a REG_UNUSED note on the quotient or remainder and generate the appropriate instruction.

`udivmodm4'
Similar, but does unsigned division.
`ashlm3'
Arithmetic-shift operand 1 left by a number of bits specified by operand 2, and store the result in operand 0. Here m is the mode of operand 0 and operand 1; operand 2's mode is specified by the instruction pattern, and the compiler will convert the operand to that mode before generating the instruction.
`ashrm3', `lshrm3', `rotlm3', `rotrm3'
Other shift and rotate instructions, analogous to the ashlm3 instructions.
`negm2'
Negate operand 1 and store the result in operand 0.
`absm2'
Store the absolute value of operand 1 into operand 0.
`sqrtm2'
Store the square root of operand 1 into operand 0.

The sqrt built-in function of C always uses the mode which corresponds to the C data type double.

`ffsm2'
Store into operand 0 one plus the index of the least significant 1-bit of operand 1. If operand 1 is zero, store zero. m is the mode of operand 0; operand 1's mode is specified by the instruction pattern, and the compiler will convert the operand to that mode before generating the instruction.

The ffs built-in function of C always uses the mode which corresponds to the C data type int.

`one_cmplm2'
Store the bitwise-complement of operand 1 into operand 0.
`cmpm'
Compare operand 0 and operand 1, and set the condition codes. The RTL pattern should look like this:
(set (cc0) (compare (match_operand:m 0 ...)
                    (match_operand:m 1 ...)))
`tstm'
Compare operand 0 against zero, and set the condition codes. The RTL pattern should look like this:
(set (cc0) (match_operand:m 0 ...))

`tstm' patterns should not be defined for machines that do not use (cc0). Doing so would confuse the optimizer since it would no longer be clear which set operations were comparisons. The `cmpm' patterns should be used instead.

`movstrm'
Block move instruction. The addresses of the destination and source strings are the first two operands, and both are in mode Pmode. The number of bytes to move is the third operand, in mode m.

The fourth operand is the known shared alignment of the source and destination, in the form of a const_int rtx. Thus, if the compiler knows that both source and destination are word-aligned, it may provide the value 4 for this operand.

These patterns need not give special consideration to the possibility that the source and destination strings might overlap.

`cmpstrm'
Block compare instruction, with five operands. Operand 0 is the output; it has mode m. The remaining four operands are like the operands of `movstrm'. The two memory blocks specified are compared byte by byte in lexicographic order. The effect of the instruction is to store a value in operand 0 whose sign indicates the result of the comparison.

Compute the length of a string, with three operands. Operand 0 is the result (of mode m), operand 1 is a mem referring to the first character of the string, operand 2 is the character to search for (normally zero), and operand 3 is a constant describing the known alignment of the beginning of the string.

`floatmn2'
Convert signed integer operand 1 (valid for fixed point mode m) to floating point mode n and store in operand 0 (which has mode n).
`floatunsmn2'
Convert unsigned integer operand 1 (valid for fixed point mode m) to floating point mode n and store in operand 0 (which has mode n).
`fixmn2'
Convert operand 1 (valid for floating point mode m) to fixed point mode n as a signed number and store in operand 0 (which has mode n). This instruction's result is defined only when the value of operand 1 is an integer.
`fixunsmn2'
Convert operand 1 (valid for floating point mode m) to fixed point mode n as an unsigned number and store in operand 0 (which has mode n). This instruction's result is defined only when the value of operand 1 is an integer.
`ftruncm2'
Convert operand 1 (valid for floating point mode m) to an integer value, still represented in floating point mode m, and store it in operand 0 (valid for floating point mode m).
`fix_truncmn2'
Like `fixmn2' but works for any floating point value of mode m by converting the value to an integer.
`fixuns_truncmn2'
Like `fixunsmn2' but works for any floating point value of mode m by converting the value to an integer.
`truncmn'
Truncate operand 1 (valid for mode m) to mode n and store in operand 0 (which has mode n). Both modes must be fixed point or both floating point.
`extendmn'
Sign-extend operand 1 (valid for mode m) to mode n and store in operand 0 (which has mode n). Both modes must be fixed point or both floating point.
`zero_extendmn'
Zero-extend operand 1 (valid for mode m) to mode n and store in operand 0 (which has mode n). Both modes must be fixed point.
`extv'
Extract a bit field from operand 1 (a register or memory operand), where operand 2 specifies the width in bits and operand 3 the starting bit, and store it in operand 0. Operand 0 must have mode word_mode. Operand 1 may have mode byte_mode or word_mode; often word_mode is allowed only for registers. Operands 2 and 3 must be valid for word_mode.

The RTL generation pass generates this instruction only with constants for operands 2 and 3.

The bit-field value is sign-extended to a full word integer before it is stored in operand 0.

`extzv'
Like `extv' except that the bit-field value is zero-extended.
`insv'
Store operand 3 (which must be valid for word_mode) into a bit field in operand 0, where operand 1 specifies the width in bits and operand 2 the starting bit. Operand 0 may have mode byte_mode or word_mode; often word_mode is allowed only for registers. Operands 1 and 2 must be valid for word_mode.

The RTL generation pass generates this instruction only with constants for operands 1 and 2.

`scond'
Store zero or nonzero in the operand according to the condition codes. Value stored is nonzero iff the condition cond is true. cond is the name of a comparison operation expression code, such as eq, lt or leu.

You specify the mode that the operand must have when you write the match_operand expression. The compiler automatically sees which mode you have used and supplies an operand of that mode.

The value stored for a true condition must have 1 as its low bit, or else must be negative. Otherwise the instruction is not suitable and you should omit it from the machine description. You describe to the compiler exactly which value is stored by defining the macro STORE_FLAG_VALUE (see Misc). If a description cannot be found that can be used for all the `scond' patterns, you should omit those operations from the machine description.

These operations may fail, but should do so only in relatively uncommon cases; if they would fail for common cases involving integer comparisons, it is best to omit these patterns.

If these operations are omitted, the compiler will usually generate code that copies the constant one to the target and branches around an assignment of zero to the target. If this code is more efficient than the potential instructions used for the `scond' pattern followed by those required to convert the result into a 1 or a zero in SImode, you should omit the `scond' operations from the machine description.

`bcond'
Conditional branch instruction. Operand 0 is a label_ref that refers to the label to jump to. Jump if the condition codes meet condition cond.

Some machines do not follow the model assumed here where a comparison instruction is followed by a conditional branch instruction. In that case, the `cmpm' (and `tstm') patterns should simply store the operands away and generate all the required insns in a define_expand (see Expander Definitions) for the conditional branch operations. All calls to expand `bcond' patterns are immediately preceded by calls to expand either a `cmpm' pattern or a `tstm' pattern.

Machines that use a pseudo register for the condition code value, or where the mode used for the comparison depends on the condition being tested, should also use the above mechanism. See Jump Patterns

The above discussion also applies to `scond' patterns.

`call'
Subroutine call instruction returning no value. Operand 0 is the function to call; operand 1 is the number of bytes of arguments pushed (in mode SImode, except it is normally a const_int); operand 2 is the number of registers used as operands.

On most machines, operand 2 is not actually stored into the RTL pattern. It is supplied for the sake of some RISC machines which need to put this information into the assembler code; they can put it in the RTL instead of operand 1.

Operand 0 should be a mem RTX whose address is the address of the function. Note, however, that this address can be a symbol_ref expression even if it would not be a legitimate memory address on the target machine. If it is also not a valid argument for a call instruction, the pattern for this operation should be a define_expand (see Expander Definitions) that places the address into a register and uses that register in the call instruction.

`call_value'
Subroutine call instruction returning a value. Operand 0 is the hard register in which the value is returned. There are three more operands, the same as the three operands of the `call' instruction (but with numbers increased by one).

Subroutines that return BLKmode objects use the `call' insn.

`call_pop', `call_value_pop'
Similar to `call' and `call_value', except used if defined and if RETURN_POPS_ARGS is non-zero. They should emit a parallel that contains both the function call and a set to indicate the adjustment made to the frame pointer.

For machines where RETURN_POPS_ARGS can be non-zero, the use of these patterns increases the number of functions for which the frame pointer can be eliminated, if desired.

`untyped_call'
Subroutine call instruction returning a value of any type. Operand 0 is the function to call; operand 1 is a memory location where the result of calling the function is to be stored; operand 2 is a parallel expression where each element is a set expression that indicates the saving of a function return value into the result block.

This instruction pattern should be defined to support __builtin_apply on machines where special instructions are needed to call a subroutine with arbitrary arguments or to save the value returned. This instruction pattern is required on machines that have multiple registers that can hold a return value (i.e. FUNCTION_VALUE_REGNO_P is true for more than one register).

`return'
Subroutine return instruction. This instruction pattern name should be defined only if a single instruction can do all the work of returning from a function.

Like the `movm' patterns, this pattern is also used after the RTL generation phase. In this case it is to support machines where multiple instructions are usually needed to return from a function, but some class of functions only requires one instruction to implement a return. Normally, the applicable functions are those which do not need to save any registers or allocate stack space.

For such machines, the condition specified in this pattern should only be true when reload_completed is non-zero and the function's epilogue would only be a single instruction. For machines with register windows, the routine leaf_function_p may be used to determine if a register window push is required.

Machines that have conditional return instructions should define patterns such as

(define_insn ""
  [(set (pc)
        (if_then_else (match_operator
                         0 "comparison_operator"
                         [(cc0) (const_int 0)])
                      (return)
                      (pc)))]
  "condition"
  "...")

where condition would normally be the same condition specified on the named `return' pattern.

`untyped_return'
Untyped subroutine return instruction. This instruction pattern should be defined to support __builtin_return on machines where special instructions are needed to return a value of any type.

Operand 0 is a memory location where the result of calling a function with __builtin_apply is stored; operand 1 is a parallel expression where each element is a set expression that indicates the restoring of a function return value from the result block.

`nop'
No-op instruction. This instruction pattern name should always be defined to output a no-op in assembler code. (const_int 0) will do as an RTL pattern.
`indirect_jump'
An instruction to jump to an address which is operand zero. This pattern name is mandatory on all machines.
`casesi'
Instruction to jump through a dispatch table, including bounds checking. This instruction takes five operands:
  1. The index to dispatch on, which has mode SImode.
  2. The lower bound for indices in the table, an integer constant.
  3. The total range of indices in the table---the largest index minus the smallest one (both inclusive).
  4. A label that precedes the table itself.
  5. A label to jump to if the index has a value outside the bounds. (If the machine-description macro CASE_DROPS_THROUGH is defined, then an out-of-bounds index drops through to the code following the jump table instead of jumping to this label. In that case, this label is not actually used by the `casesi' instruction, but it is always provided as an operand.)

The table is a addr_vec or addr_diff_vec inside of a jump_insn. The number of elements in the table is one plus the difference between the upper bound and the lower bound.

`tablejump'
Instruction to jump to a variable address. This is a low-level capability which can be used to implement a dispatch table when there is no `casesi' pattern.

This pattern requires two operands: the address or offset, and a label which should immediately precede the jump table. If the macro CASE_VECTOR_PC_RELATIVE is defined then the first operand is an offset which counts from the address of the table; otherwise, it is an absolute address to jump to. In either case, the first operand has mode Pmode.

The `tablejump' insn is always the last insn before the jump table it uses. Its assembler code normally has no need to use the second operand, but you should incorporate it in the RTL pattern so that the jump optimizer will not delete the table as unreachable code.

`save_stack_block'
`save_stack_function'
`save_stack_nonlocal'
`restore_stack_block'
`restore_stack_function'
`restore_stack_nonlocal'
Most machines save and restore the stack pointer by copying it to or from an object of mode Pmode. Do not define these patterns on such machines.

Some machines require special handling for stack pointer saves and restores. On those machines, define the patterns corresponding to the non-standard cases by using a define_expand (see Expander Definitions) that produces the required insns. The three types of saves and restores are:

  1. `save_stack_block' saves the stack pointer at the start of a block that allocates a variable-sized object, and `restore_stack_block' restores the stack pointer when the block is exited.
  2. `save_stack_function' and `restore_stack_function' do a similar job for the outermost block of a function and are used when the function allocates variable-sized objects or calls alloca. Only the epilogue uses the restored stack pointer, allowing a simpler save or restore sequence on some machines.
  3. `save_stack_nonlocal' is used in functions that contain labels branched to by nested functions. It saves the stack pointer in such a way that the inner function can use `restore_stack_nonlocal' to restore the stack pointer. The compiler generates code to restore the frame and argument pointer registers, but some machines require saving and restoring additional data such as register window information or stack backchains. Place insns in these patterns to save and restore any such required data.

When saving the stack pointer, operand 0 is the save area and operand 1 is the stack pointer. The mode used to allocate the save area is the mode of operand 0. You must specify an integral mode, or VOIDmode if no save area is needed for a particular type of save (either because no save is needed or because a machine-specific save area can be used). Operand 0 is the stack pointer and operand 1 is the save area for restore operations. If `save_stack_block' is defined, operand 0 must not be VOIDmode since these saves can be arbitrarily nested.

A save area is a mem that is at a constant offset from virtual_stack_vars_rtx when the stack pointer is saved for use by nonlocal gotos and a reg in the other two cases.

`allocate_stack'
Subtract (or add if STACK_GROWS_DOWNWARD is undefined) operand 0 from the stack pointer to create space for dynamically allocated data.

Do not define this pattern if all that must be done is the subtraction. Some machines require other operations such as stack probes or maintaining the back chain. Define this pattern to emit those operations in addition to updating the stack pointer.