source: trunk/third/gcc/gcc.info-18 @ 11288

This is Info file gcc.info, produced by Makeinfo version 1.67 from the
input file gcc.texi.

   This file documents the use and the internals of the GNU compiler.

   Published by the Free Software Foundation 59 Temple Place - Suite 330
Boston, MA 02111-1307 USA

   Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998
Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "GNU General Public License," "Funding for
Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "GNU General Public
License," "Funding for Free Software," and "Protect Your Freedom--Fight
`Look And Feel'", and this permission notice, may be included in
translations approved by the Free Software Foundation instead of in the
original English.


File: gcc.info,  Node: Standard Names,  Next: Pattern Ordering,  Prev: Constraints,  Up: Machine Desc

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 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.  *Note
     Register Classes::.

     The constraints on a `movM' 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 `movM' 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 `movM'
     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 `movM' 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 *note 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' (*note 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'
     (*note 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.

`mulM3_highpart'
     Perform a signed multiplication of operands 1 and 2, which have
     mode M, and store the most significant half of the product in
     operand 0.  The least significant half of the product is discarded.

`umulM3_highpart'
     Similar, but the multiplication is unsigned.

`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.
     Usually, you specify `word_mode' for M.  However, if you can
     generate better code knowing the range of valid lengths is smaller
     than those representable in a full word, you should provide a
     pattern with a mode corresponding to the range of values you can
     handle efficiently (e.g., `QImode' for values in the range 0-127;
     note we avoid numbers that appear negative) and also a pattern
     with `word_mode'.

     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.

`clrstrM'
     Block clear instruction.  The addresses of the destination string
     is the first operand, in mode `Pmode'.  The number of bytes to
     clear is the second operand, in mode M.  See `movstrM' for a
     discussion of the choice of mode.

     The third operand is the known alignment of the destination, in
     the form of a `const_int' rtx.  Thus, if the compiler knows that
     the destination is word-aligned, it may provide the value 4 for
     this operand.

`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.

`strlenM'
     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.

`truncMN2'
     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.

`extendMN2'
     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_extendMN2'
     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.

`movMODEcc'
     Conditionally move operand 2 or operand 3 into operand 0 according
     to the comparison in operand 1.  If the comparison is true,
     operand 2 is moved into operand 0, otherwise operand 3 is moved.

     The mode of the operands being compared need not be the same as
     the operands being moved.  Some machines, sparc64 for example,
     have instructions that conditionally move an integer value based
     on the floating point condition codes and vice versa.

     If the machine does not have conditional move instructions, do not
     define these patterns.

`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' (*note 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' (*note 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.  *Note Jump
     Patterns::

     The above discussion also applies to the `movMODEcc' and `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' (*note 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.

`canonicalize_funcptr_for_compare'
     Canonicalize the function pointer in operand 1 and store the result
     into operand 0.

     Operand 0 is always a `reg' and has mode `Pmode'; operand 1 may be
     a `reg', `mem', `symbol_ref', `const_int', etc and also has mode
     `Pmode'.

     Canonicalization of a function pointer usually involves computing
     the address of the function which would be called if the function
     pointer were used in an indirect call.

     Only define this pattern if function pointers on the target machine
     can have different values but still call the same function when
     used in an indirect call.

`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' (*note 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 1
     from the stack pointer to create space for dynamically allocated
     data.

     Store the resultant pointer to this space into operand 0.  If you
     are allocating space from the main stack, do this by emitting a
     move insn to copy `virtual_stack_dynamic_rtx' to operand 0.  If
     you are allocating the space elsewhere, generate code to copy the
     location of the space to operand 0.  In the latter case, you must
     ensure this space gets freed when the corresponding space on the
     main stack is free.

     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.

`probe'
     Some machines require instructions to be executed after space is
     allocated from the stack, for example to generate a reference at
     the bottom of the stack.

     If you need to emit instructions before the stack has been
     adjusted, put them into the `allocate_stack' pattern.  Otherwise,
     define this pattern to emit the required instructions.

     No operands are provided.

`check_stack'
     If stack checking cannot be done on your system by probing the
     stack with a load or store instruction (*note Stack Checking::.),
     define this pattern to perform the needed check and signaling an
     error if the stack has overflowed.  The single operand is the
     location in the stack furthest from the current stack pointer that
     you need to validate.  Normally, on machines where this pattern is
     needed, you would obtain the stack limit from a global or
     thread-specific variable or register.

`nonlocal_goto'
     Emit code to generate a non-local goto, e.g., a jump from one
     function to a label in an outer function.  This pattern has four
     arguments, each representing a value to be used in the jump.  The
     first argument is to be loadedd into the frame pointer, the second
     is the address to branch to (code to dispatch to the actual label),
     the third is the address of a location where the stack is saved,
     and the last is the address of the label, to be placed in the
     location for the incoming static chain.

     On most machines you need not define this pattern, since GNU CC
     will already generate the correct code, which is to load the frame
     pointer and static chain, restore the stack (using the
     `restore_stack_nonlocal' pattern, if defined), and jump indirectly
     to the dispatcher.  You need only define this pattern if this code
     will not work on your machine.

`nonlocal_goto_receiver'
     This pattern, if defined, contains code needed at the target of a
     nonlocal goto after the code already generated by GNU CC.  You
     will not normally need to define this pattern.  A typical reason
     why you might need this pattern is if some value, such as a
     pointer to a global table, must be restored when the frame pointer
     is restored.  There are no arguments.

`exception_receiver'
     This pattern, if defined, contains code needed at the site of an
     exception handler that isn't needed at the site of a nonlocal
     goto.  You will not normally need to define this pattern.  A
     typical reason why you might need this pattern is if some value,
     such as a pointer to a global table, must be restored after
     control flow is branched to the handler of an exception.  There
     are no arguments.

`builtin_setjmp_receiver'
     This pattern, if defined, contains code needed at the site of an
     builtin setjmp that isn't needed at the site of a nonlocal goto.
     You will not normally need to define this pattern.  A typical
     reason why you might need this pattern is if some value, such as a
     pointer to a global table, must be restored.  This pattern is
     called immediate after the call to `__dummy' has been emitted.
     There are no arguments.


File: gcc.info,  Node: Pattern Ordering,  Next: Dependent Patterns,  Prev: Standard Names,  Up: Machine Desc

When the Order of Patterns Matters
==================================

   Sometimes an insn can match more than one instruction pattern.  Then
the pattern that appears first in the machine description is the one
used.  Therefore, more specific patterns (patterns that will match
fewer things) and faster instructions (those that will produce better
code when they do match) should usually go first in the description.

   In some cases the effect of ordering the patterns can be used to hide
a pattern when it is not valid.  For example, the 68000 has an
instruction for converting a fullword to floating point and another for
converting a byte to floating point.  An instruction converting an
integer to floating point could match either one.  We put the pattern
to convert the fullword first to make sure that one will be used rather
than the other.  (Otherwise a large integer might be generated as a
single-byte immediate quantity, which would not work.) Instead of using
this pattern ordering it would be possible to make the pattern for
convert-a-byte smart enough to deal properly with any constant value.


File: gcc.info,  Node: Dependent Patterns,  Next: Jump Patterns,  Prev: Pattern Ordering,  Up: Machine Desc

Interdependence of Patterns
===========================

   Every machine description must have a named pattern for each of the
conditional branch names `bCOND'.  The recognition template must always
have the form

     (set (pc)
          (if_then_else (COND (cc0) (const_int 0))
                        (label_ref (match_operand 0 "" ""))
                        (pc)))

In addition, every machine description must have an anonymous pattern
for each of the possible reverse-conditional branches.  Their templates
look like

     (set (pc)
          (if_then_else (COND (cc0) (const_int 0))
                        (pc)
                        (label_ref (match_operand 0 "" ""))))

They are necessary because jump optimization can turn direct-conditional
branches into reverse-conditional branches.

   It is often convenient to use the `match_operator' construct to
reduce the number of patterns that must be specified for branches.  For
example,

     (define_insn ""
       [(set (pc)
             (if_then_else (match_operator 0 "comparison_operator"
                                           [(cc0) (const_int 0)])
                           (pc)
                           (label_ref (match_operand 1 "" ""))))]
       "CONDITION"
       "...")

   In some cases machines support instructions identical except for the
machine mode of one or more operands.  For example, there may be
"sign-extend halfword" and "sign-extend byte" instructions whose
patterns are

     (set (match_operand:SI 0 ...)
          (extend:SI (match_operand:HI 1 ...)))
     
     (set (match_operand:SI 0 ...)
          (extend:SI (match_operand:QI 1 ...)))

Constant integers do not specify a machine mode, so an instruction to
extend a constant value could match either pattern.  The pattern it
actually will match is the one that appears first in the file.  For
correct results, this must be the one for the widest possible mode
(`HImode', here).  If the pattern matches the `QImode' instruction, the
results will be incorrect if the constant value does not actually fit
that mode.

   Such instructions to extend constants are rarely generated because
they are optimized away, but they do occasionally happen in nonoptimized
compilations.

   If a constraint in a pattern allows a constant, the reload pass may
replace a register with a constant permitted by the constraint in some
cases.  Similarly for memory references.  Because of this substitution,
you should not provide separate patterns for increment and decrement
instructions.  Instead, they should be generated from the same pattern
that supports register-register add insns by examining the operands and
generating the appropriate machine instruction.


File: gcc.info,  Node: Jump Patterns,  Next: Insn Canonicalizations,  Prev: Dependent Patterns,  Up: Machine Desc

Defining Jump Instruction Patterns
==================================

   For most machines, GNU CC assumes that the machine has a condition
code.  A comparison insn sets the condition code, recording the results
of both signed and unsigned comparison of the given operands.  A
separate branch insn tests the condition code and branches or not
according its value.  The branch insns come in distinct signed and
unsigned flavors.  Many common machines, such as the Vax, the 68000 and
the 32000, work this way.

   Some machines have distinct signed and unsigned compare
instructions, and only one set of conditional branch instructions.  The
easiest way to handle these machines is to treat them just like the
others until the final stage where assembly code is written.  At this
time, when outputting code for the compare instruction, peek ahead at
the following branch using `next_cc0_user (insn)'.  (The variable
`insn' refers to the insn being output, in the output-writing code in
an instruction pattern.)  If the RTL says that is an unsigned branch,
output an unsigned compare; otherwise output a signed compare.  When
the branch itself is output, you can treat signed and unsigned branches
identically.

   The reason you can do this is that GNU CC always generates a pair of
consecutive RTL insns, possibly separated by `note' insns, one to set
the condition code and one to test it, and keeps the pair inviolate
until the end.

   To go with this technique, you must define the machine-description
macro `NOTICE_UPDATE_CC' to do `CC_STATUS_INIT'; in other words, no
compare instruction is superfluous.

   Some machines have compare-and-branch instructions and no condition
code.  A similar technique works for them.  When it is time to "output"
a compare instruction, record its operands in two static variables.
When outputting the branch-on-condition-code instruction that follows,
actually output a compare-and-branch instruction that uses the
remembered operands.

   It also works to define patterns for compare-and-branch instructions.
In optimizing compilation, the pair of compare and branch instructions
will be combined according to these patterns.  But this does not happen
if optimization is not requested.  So you must use one of the solutions
above in addition to any special patterns you define.

   In many RISC machines, most instructions do not affect the condition
code and there may not even be a separate condition code register.  On
these machines, the restriction that the definition and use of the
condition code be adjacent insns is not necessary and can prevent
important optimizations.  For example, on the IBM RS/6000, there is a
delay for taken branches unless the condition code register is set three
instructions earlier than the conditional branch.  The instruction
scheduler cannot perform this optimization if it is not permitted to
separate the definition and use of the condition code register.

   On these machines, do not use `(cc0)', but instead use a register to
represent the condition code.  If there is a specific condition code
register in the machine, use a hard register.  If the condition code or
comparison result can be placed in any general register, or if there are
multiple condition registers, use a pseudo register.

   On some machines, the type of branch instruction generated may
depend on the way the condition code was produced; for example, on the
68k and Sparc, setting the condition code directly from an add or
subtract instruction does not clear the overflow bit the way that a test
instruction does, so a different branch instruction must be used for
some conditional branches.  For machines that use `(cc0)', the set and
use of the condition code must be adjacent (separated only by `note'
insns) allowing flags in `cc_status' to be used.  (*Note Condition
Code::.)  Also, the comparison and branch insns can be located from
each other by using the functions `prev_cc0_setter' and `next_cc0_user'.

   However, this is not true on machines that do not use `(cc0)'.  On
those machines, no assumptions can be made about the adjacency of the
compare and branch insns and the above methods cannot be used.  Instead,
we use the machine mode of the condition code register to record
different formats of the condition code register.

   Registers used to store the condition code value should have a mode
that is in class `MODE_CC'.  Normally, it will be `CCmode'.  If
additional modes are required (as for the add example mentioned above in
the Sparc), define the macro `EXTRA_CC_MODES' to list the additional
modes required (*note Condition Code::.).  Also define `EXTRA_CC_NAMES'
to list the names of those modes and `SELECT_CC_MODE' to choose a mode
given an operand of a compare.

   If it is known during RTL generation that a different mode will be
required (for example, if the machine has separate compare instructions
for signed and unsigned quantities, like most IBM processors), they can
be specified at that time.

   If the cases that require different modes would be made by
instruction combination, the macro `SELECT_CC_MODE' determines which
machine mode should be used for the comparison result.  The patterns
should be written using that mode.  To support the case of the add on
the Sparc discussed above, we have the pattern

     (define_insn ""
       [(set (reg:CC_NOOV 0)
             (compare:CC_NOOV
               (plus:SI (match_operand:SI 0 "register_operand" "%r")
                        (match_operand:SI 1 "arith_operand" "rI"))
               (const_int 0)))]
       ""
       "...")

   The `SELECT_CC_MODE' macro on the Sparc returns `CC_NOOVmode' for
comparisons whose argument is a `plus'.


File: gcc.info,  Node: Insn Canonicalizations,  Next: Peephole Definitions,  Prev: Jump Patterns,  Up: Machine Desc

Canonicalization of Instructions
================================

   There are often cases where multiple RTL expressions could represent
an operation performed by a single machine instruction.  This situation
is most commonly encountered with logical, branch, and
multiply-accumulate instructions.  In such cases, the compiler attempts
to convert these multiple RTL expressions into a single canonical form
to reduce the number of insn patterns required.

   In addition to algebraic simplifications, following canonicalizations
are performed:

   * For commutative and comparison operators, a constant is always
     made the second operand.  If a machine only supports a constant as
     the second operand, only patterns that match a constant in the
     second operand need be supplied.

     For these operators, if only one operand is a `neg', `not',
     `mult', `plus', or `minus' expression, it will be the first
     operand.

   * For the `compare' operator, a constant is always the second operand
     on machines where `cc0' is used (*note Jump Patterns::.).  On other
     machines, there are rare cases where the compiler might want to
     construct a `compare' with a constant as the first operand.
     However, these cases are not common enough for it to be worthwhile
     to provide a pattern matching a constant as the first operand
     unless the machine actually has such an instruction.

     An operand of `neg', `not', `mult', `plus', or `minus' is made the
     first operand under the same conditions as above.

   * `(minus X (const_int N))' is converted to `(plus X (const_int
     -N))'.

   * Within address computations (i.e., inside `mem'), a left shift is
     converted into the appropriate multiplication by a power of two.

   * De`Morgan's Law is used to move bitwise negation inside a bitwise
     logical-and or logical-or operation.  If this results in only one
     operand being a `not' expression, it will be the first one.

     A machine that has an instruction that performs a bitwise
     logical-and of one operand with the bitwise negation of the other
     should specify the pattern for that instruction as

          (define_insn ""
            [(set (match_operand:M 0 ...)
                  (and:M (not:M (match_operand:M 1 ...))
                               (match_operand:M 2 ...)))]
            "..."
            "...")

     Similarly, a pattern for a "NAND" instruction should be written

          (define_insn ""
            [(set (match_operand:M 0 ...)
                  (ior:M (not:M (match_operand:M 1 ...))
                               (not:M (match_operand:M 2 ...))))]
            "..."
            "...")

     In both cases, it is not necessary to include patterns for the many
     logically equivalent RTL expressions.

   * The only possible RTL expressions involving both bitwise
     exclusive-or and bitwise negation are `(xor:M X Y)' and `(not:M
     (xor:M X Y))'.

   * The sum of three items, one of which is a constant, will only
     appear in the form

          (plus:M (plus:M X Y) CONSTANT)

   * On machines that do not use `cc0', `(compare X (const_int 0))'
     will be converted to X.

   * Equality comparisons of a group of bits (usually a single bit)
     with zero will be written using `zero_extract' rather than the
     equivalent `and' or `sign_extract' operations.