--- gcc/gcc.info-15 2018/04/24 17:51:27 1.1.1.1 +++ gcc/gcc.info-15 2018/04/24 18:12:34 1.1.1.6 @@ -1,1120 +1,1092 @@ -This is Info file gcc.info, produced by Makeinfo-1.43 from the input +This is Info file gcc.info, produced by Makeinfo-1.54 from the input file gcc.texi. This file documents the use and the internals of the GNU compiler. - Copyright (C) 1988, 1989, 1992 Free Software Foundation, Inc. + Published by the Free Software Foundation 675 Massachusetts Avenue +Cambridge, MA 02139 USA - 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. + Copyright (C) 1988, 1989, 1992, 1993 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 section entitled "GNU General Public License" is 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. +that the sections entitled "GNU General Public License" 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 section entitled "GNU General Public -License" 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: Uninitialized Data, Next: Label Output, Prev: Data Output, Up: Assembler Format - -Output of Uninitialized Variables ---------------------------------- - - Each of the macros in this section is used to do the whole job of -outputting a single uninitialized variable. - -`ASM_OUTPUT_COMMON (STREAM, NAME, SIZE, ROUNDED)' - A C statement (sans semicolon) to output to the stdio stream - STREAM the assembler definition of a common-label named NAME - whose size is SIZE bytes. The variable ROUNDED is the size - rounded up to whatever alignment the caller wants. - - Use the expression `assemble_name (STREAM, NAME)' to output the - name itself; before and after that, output the additional - assembler syntax for defining the name, and a newline. - - This macro controls how the assembler definitions of uninitialized - global variables are output. - -`ASM_OUTPUT_ALIGNED_COMMON (STREAM, NAME, SIZE, ALIGNMENT)' - Like `ASM_OUTPUT_COMMON' except takes the required alignment as a - separate, explicit argument. If you define this macro, it is - used in place of `ASM_OUTPUT_COMMON', and gives you more - flexibility in handling the required alignment of the variable. - -`ASM_OUTPUT_SHARED_COMMON (STREAM, NAME, SIZE, ROUNDED)' - If defined, it is similar to `ASM_OUTPUT_COMMON', except that it - is used when NAME is shared. If not defined, `ASM_OUTPUT_COMMON' - will be used. - -`ASM_OUTPUT_LOCAL (STREAM, NAME, SIZE, ROUNDED)' - A C statement (sans semicolon) to output to the stdio stream - STREAM the assembler definition of a local-common-label named - NAME whose size is SIZE bytes. The variable ROUNDED is the size - rounded up to whatever alignment the caller wants. - - Use the expression `assemble_name (STREAM, NAME)' to output the - name itself; before and after that, output the additional - assembler syntax for defining the name, and a newline. - - This macro controls how the assembler definitions of uninitialized - static variables are output. - -`ASM_OUTPUT_ALIGNED_LOCAL (STREAM, NAME, SIZE, ALIGNMENT)' - Like `ASM_OUTPUT_LOCAL' except takes the required alignment as a - separate, explicit argument. If you define this macro, it is - used in place of `ASM_OUTPUT_LOCAL', and gives you more - flexibility in handling the required alignment of the variable. - -`ASM_OUTPUT_SHARED_LOCAL (STREAM, NAME, SIZE, ROUNDED)' - If defined, it is similar to `ASM_OUTPUT_LOCAL', except that it - is used when NAME is shared. If not defined, `ASM_OUTPUT_LOCAL' - will be used. +versions, except that the sections entitled "GNU General Public +License" 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: Label Output, Next: Constructor Output, Prev: Uninitialized Data, Up: Assembler Format +File: gcc.info, Node: Standard Names, Next: Pattern Ordering, Prev: Constraints, Up: Machine Desc -Output and Generation of Labels -------------------------------- +Standard Pattern Names For Generation +===================================== -`ASM_OUTPUT_LABEL (STREAM, NAME)' - A C statement (sans semicolon) to output to the stdio stream - STREAM the assembler definition of a label named NAME. Use the - expression `assemble_name (STREAM, NAME)' to output the name - itself; before and after that, output the additional assembler - syntax for defining the name, and a newline. - -`ASM_DECLARE_FUNCTION_NAME (STREAM, NAME, DECL)' - A C statement (sans semicolon) to output to the stdio stream - STREAM any text necessary for declaring the name NAME of a - function which is being defined. This macro is responsible for - outputting the label definition (perhaps using - `ASM_OUTPUT_LABEL'). The argument DECL is the `FUNCTION_DECL' - tree node representing the function. - - If this macro is not defined, then the function name is defined - in the usual manner as a label (by means of `ASM_OUTPUT_LABEL'). - -`ASM_DECLARE_FUNCTION_SIZE (STREAM, NAME, DECL)' - A C statement (sans semicolon) to output to the stdio stream - STREAM any text necessary for declaring the size of a function - which is being defined. The argument NAME is the name of the - function. The argument DECL is the `FUNCTION_DECL' tree node - representing the function. - - If this macro is not defined, then the function size is not - defined. - -`ASM_DECLARE_OBJECT_NAME (STREAM, NAME, DECL)' - A C statement (sans semicolon) to output to the stdio stream - STREAM any text necessary for declaring the name NAME of an - initialized variable which is being defined. This macro must - output the label definition (perhaps using `ASM_OUTPUT_LABEL'). - The argument DECL is the `VAR_DECL' tree node representing the - variable. - - If this macro is not defined, then the variable name is defined - in the usual manner as a label (by means of `ASM_OUTPUT_LABEL'). - -`ASM_GLOBALIZE_LABEL (STREAM, NAME)' - A C statement (sans semicolon) to output to the stdio stream - STREAM some commands that will make the label NAME global; that - is, available for reference from other files. Use the expression - `assemble_name (STREAM, NAME)' to output the name itself; before - and after that, output the additional assembler syntax for making - that name global, and a newline. - -`ASM_OUTPUT_EXTERNAL (STREAM, DECL, NAME)' - A C statement (sans semicolon) to output to the stdio stream - STREAM any text necessary for declaring the name of an external - symbol named NAME which is referenced in this compilation but not - defined. The value of DECL is the tree node for the declaration. - - This macro need not be defined if it does not need to output - anything. The GNU assembler and most Unix assemblers don't - require anything. - -`ASM_OUTPUT_EXTERNAL_LIBCALL (STREAM, SYMREF)' - A C statement (sans semicolon) to output on STREAM an assembler - pseudo-op to declare a library function name external. The name - of the library function is given by SYMREF, which has type `rtx' - and is a `symbol_ref'. - - This macro need not be defined if it does not need to output - anything. The GNU assembler and most Unix assemblers don't - require anything. - -`ASM_OUTPUT_LABELREF (STREAM, NAME)' - A C statement (sans semicolon) to output to the stdio stream - STREAM a reference in assembler syntax to a label named NAME. - This should add `_' to the front of the name, if that is - customary on your operating system, as it is in most Berkeley Unix - systems. This macro is used in `assemble_name'. - -`ASM_OUTPUT_LABELREF_AS_INT (FILE, LABEL)' - Define this macro for systems that use the program `collect2'. - The definition should be a C statement to output a word containing - a reference to the label LABEL. - -`ASM_GENERATE_INTERNAL_LABEL (STRING, PREFIX, NUM)' - A C statement to store into the string STRING a label whose name - is made from the string PREFIX and the number NUM. - - This string, when output subsequently by `ASM_OUTPUT_LABELREF', - should produce the same output that `ASM_OUTPUT_INTERNAL_LABEL' - would produce with the same PREFIX and NUM. - -`ASM_OUTPUT_INTERNAL_LABEL (STREAM, PREFIX, NUM)' - A C statement to output to the stdio stream STREAM a label whose - name is made from the string PREFIX and the number NUM. These - labels are used for internal purposes, and there is no reason for - them to appear in the symbol table of the object file. On many - systems, the letter `L' at the beginning of a label has this - effect. The usual definition of this macro is as follows: - - fprintf (STREAM, "L%s%d:\n", PREFIX, NUM) - -`ASM_FORMAT_PRIVATE_NAME (OUTVAR, NAME, NUMBER)' - A C expression to assign to OUTVAR (which is a variable of type - `char *') a newly allocated string made from the string NAME and - the number NUMBER, with some suitable punctuation added. Use - `alloca' to get space for the string. - - This string will be used as the argument to `ASM_OUTPUT_LABELREF' - to produce an assembler label for an internal static variable - whose name is NAME. Therefore, the string must be such as to - result in valid assembler code. The argument NUMBER is different - each time this macro is executed; it prevents conflicts between - similarly-named internal static variables in different scopes. - - Ideally this string should not be a valid C identifier, to - prevent any conflict with the user's own symbols. Most - assemblers allow periods or percent signs in assembler symbols; - putting at least one of these between the name and the number - will suffice. - -`OBJC_GEN_METHOD_LABEL (BUF, IS_INST, CLASS_NAME, CAT_NAME, SEL_NAME)' - Define this macro to override the default assembler names used for - Objective C methods. - - The default name is a unique method number followed by the name - of the class (e.g. `_1_Foo'). For methods in categories, the - name of the category is also included in the assembler name (e.g. - `_1_Foo_Bar'). - - These names are safe on most systems, but make debugging - difficult since the method's selector is not present in the name. - Therefore, particular systems define other ways of computing - names. - - BUF is a buffer in which to store the name (256 chars max); - IS_INST specifies whether the method is an instance method or a - class method; CLASS_NAME is the name of the class; CAT_NAME is - the name of the category (or NULL if the method is not in a - category); and SEL_NAME is the name of the selector. - - On systems where the assembler can handle quoted names, you can - use this macro to provide more human-readable names. + 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. *Note + 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 *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. + +`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', `lshlM3', `lshrM3', `rotlM3', `rotrM3' + Other shift and rotate instructions, analogous to the `ashlM3' + instructions. + + Logical and arithmetic left shift are the same. Machines that do + not allow negative shift counts often have only one instruction for + shifting left. On such machines, you should define a pattern named + `ashlM3' and leave `lshlM3' undefined. + +`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' (*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 `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. + +`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 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.  -File: gcc.info, Node: Constructor Output, Next: Instruction Output, Prev: Label Output, Up: Assembler Format +File: gcc.info, Node: Pattern Ordering, Next: Dependent Patterns, Prev: Standard Names, Up: Machine Desc -Output of Initialization Routines ---------------------------------- +When the Order of Patterns Matters +================================== - The compiled code for certain languages includes "constructors" -(also called "initialization routines")--functions to initialize data -in the program when the program is started. These functions need to -be called before the program is "started"--that is to say, before -`main' is called. - - Compiling some languages generates "destructors" (also called -"termination routines") that should be called when the program -terminates. - - To make the initialization and termination functions work, the -compiler must output something in the assembler code to cause those -functions to be called at the appropriate time. When you port the -compiler to a new system, you need to specify what assembler code is -needed to do this. - - Here are the two macros you should define if necessary: - -`ASM_OUTPUT_CONSTRUCTOR (STREAM, NAME)' - Define this macro as a C statement to output on the stream STREAM - the assembler code to arrange to call the function named NAME at - initialization time. - - Assume that NAME is the name of a C function generated - automatically by the compiler. This function takes no arguments. - Use the function `assemble_name' to output the name NAME; this - performs any system-specific syntactic transformations such as - adding an underscore. - - If you don't define this macro, nothing special is output to - arrange to call the function. This is correct when the function - will be called in some other manner--for example, by means of the - `collect' program, which looks through the symbol table to find - these functions by their names. If you want to use `collect', - then you need to arrange for it to be built and installed and - used on your system. - -`ASM_OUTPUT_DESTRUCTOR (STREAM, NAME)' - This is like `ASM_OUTPUT_CONSTRUCTOR' but used for termination - functions rather than initialization functions. + 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: Instruction Output, Next: Dispatch Tables, Prev: Constructor Output, Up: Assembler Format +File: gcc.info, Node: Dependent Patterns, Next: Jump Patterns, Prev: Pattern Ordering, Up: Machine Desc -Output of Assembler Instructions --------------------------------- +Interdependence of Patterns +=========================== -`REGISTER_NAMES' - A C initializer containing the assembler's names for the machine - registers, each one as a C string constant. This is what - translates register numbers in the compiler into assembler - language. - -`ADDITIONAL_REGISTER_NAMES' - If defined, a C initializer for an array of structures containing - a name and a register number. This macro defines additional - names for hard registers, thus allowing the `asm' option in - declarations to refer to registers using alternate names. - -`ASM_OUTPUT_OPCODE (STREAM, PTR)' - Define this macro if you are using an unusual assembler that - requires different names for the machine instructions. - - The definition is a C statement or statements which output an - assembler instruction opcode to the stdio stream STREAM. The - macro-operand PTR is a variable of type `char *' which points to - the opcode name in its "internal" form--the form that is written - in the machine description. The definition should output the - opcode name to STREAM, performing any translation you desire, and - increment the variable PTR to point at the end of the opcode so - that it will not be output twice. - - In fact, your macro definition may process less than the entire - opcode name, or more than the opcode name; but if you want to - process text that includes `%'-sequences to substitute operands, - you must take care of the substitution yourself. Just be sure to - increment PTR over whatever text should not be output normally. - - If you need to look at the operand values, they can be found as - the elements of `recog_operand'. - - If the macro definition does nothing, the instruction is output - in the usual way. - -`FINAL_PRESCAN_INSN (INSN, OPVEC, NOPERANDS)' - If defined, a C statement to be executed just prior to the output - of assembler code for INSN, to modify the extracted operands so - they will be output differently. - - Here the argument OPVEC is the vector containing the operands - extracted from INSN, and NOPERANDS is the number of elements of - the vector which contain meaningful data for this insn. The - contents of this vector are what will be used to convert the insn - template into assembler code, so you can change the assembler - output by changing the contents of the vector. - - This macro is useful when various assembler syntaxes share a - single file of instruction patterns; by defining this macro - differently, you can cause a large class of instructions to be - output differently (such as with rearranged operands). - Naturally, variations in assembler syntax affecting individual - insn patterns ought to be handled by writing conditional output - routines in those patterns. - - If this macro is not defined, it is equivalent to a null - statement. - -`PRINT_OPERAND (STREAM, X, CODE)' - A C compound statement to output to stdio stream STREAM the - assembler syntax for an instruction operand X. X is an RTL - expression. - - CODE is a value that can be used to specify one of several ways - of printing the operand. It is used when identical operands must - be printed differently depending on the context. CODE comes from - the `%' specification that was used to request printing of the - operand. If the specification was just `%DIGIT' then CODE is 0; - if the specification was `%LTR DIGIT' then CODE is the ASCII code - for LTR. - - If X is a register, this macro should print the register's name. - The names can be found in an array `reg_names' whose type is - `char *[]'. `reg_names' is initialized from `REGISTER_NAMES'. - - When the machine description has a specification `%PUNCT' (a `%' - followed by a punctuation character), this macro is called with a - null pointer for X and the punctuation character for CODE. - -`PRINT_OPERAND_PUNCT_VALID_P (CODE)' - A C expression which evaluates to true if CODE is a valid - punctuation character for use in the `PRINT_OPERAND' macro. If - `PRINT_OPERAND_PUNCT_VALID_P' is not defined, it means that no - punctuation characters (except for the standard one, `%') are used - in this way. - -`PRINT_OPERAND_ADDRESS (STREAM, X)' - A C compound statement to output to stdio stream STREAM the - assembler syntax for an instruction operand that is a memory - reference whose address is X. X is an RTL expression. - - On some machines, the syntax for a symbolic address depends on the - section that the address refers to. On these machines, define - the macro `ENCODE_SECTION_INFO' to store the information into the - `symbol_ref', and then check for it here. *Note Assembler - Format::. - -`DBR_OUTPUT_SEQEND(FILE)' - A C statement, to be executed after all slot-filler instructions - have been output. If necessary, call `dbr_sequence_length' to - determine the number of slots filled in a sequence (zero if not - currently outputting a sequence), to decide how many no-ops to - output, or whatever. - - Don't define this macro if it has nothing to do, but it is - helpful in reading assembly output if the extent of the delay - sequence is made explicit (e.g. with white space). - - Note that output routines for instructions with delay slots must - be prepared to deal with not being output as part of a sequence - (i.e. when the scheduling pass is not run, or when no slot - fillers could be found.) The variable `final_sequence' is null - when not processing a sequence, otherwise it contains the - `sequence' rtx being output. - -`REGISTER_PREFIX' -`LOCAL_LABEL_PREFIX' -`USER_LABEL_PREFIX' -`IMMEDIATE_PREFIX' - If defined, C string expressions to be used for the `%R', `%L', - `%U', and `%I' options of `asm_fprintf' (see `final.c'). These - are useful when a single `md' file must support multiple - assembler formats. In that case, the various `tm.h' files can - define these macros differently. - -`ASM_OUTPUT_REG_PUSH (STREAM, REGNO)' - A C expression to output to STREAM some assembler code which will - push hard register number REGNO onto the stack. The code need - not be optimal, since this macro is used only when profiling. - -`ASM_OUTPUT_REG_POP (STREAM, REGNO)' - A C expression to output to STREAM some assembler code which will - pop hard register number REGNO off of the stack. The code need - not be optimal, since this macro is used only when profiling. + 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. You must ensure that the +predicate permits all objects allowed by the constraints to prevent the +compiler from crashing. + + 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: Dispatch Tables, Next: Alignment Output, Prev: Instruction Output, Up: Assembler Format +File: gcc.info, Node: Jump Patterns, Next: Insn Canonicalizations, Prev: Dependent Patterns, Up: Machine Desc -Output of Dispatch Tables -------------------------- +Defining Jump Instruction Patterns +================================== -`ASM_OUTPUT_ADDR_DIFF_ELT (STREAM, VALUE, REL)' - This macro should be provided on machines where the addresses in - a dispatch table are relative to the table's own address. - - The definition should be a C statement to output to the stdio - stream STREAM an assembler pseudo-instruction to generate a - difference between two labels. VALUE and REL are the numbers of - two internal labels. The definitions of these labels are output - using `ASM_OUTPUT_INTERNAL_LABEL', and they must be printed in - the same way here. For example, - - fprintf (STREAM, "\t.word L%d-L%d\n", - VALUE, REL) - -`ASM_OUTPUT_ADDR_VEC_ELT (STREAM, VALUE)' - This macro should be provided on machines where the addresses in - a dispatch table are absolute. - - The definition should be a C statement to output to the stdio - stream STREAM an assembler pseudo-instruction to generate a - reference to a label. VALUE is the number of an internal label - whose definition is output using `ASM_OUTPUT_INTERNAL_LABEL'. - For example, - - fprintf (STREAM, "\t.word L%d\n", VALUE) - -`ASM_OUTPUT_CASE_LABEL (STREAM, PREFIX, NUM, TABLE)' - Define this if the label before a jump-table needs to be output - specially. The first three arguments are the same as for - `ASM_OUTPUT_INTERNAL_LABEL'; the fourth argument is the - jump-table which follows (a `jump_insn' containing an `addr_vec' - or `addr_diff_vec'). - - This feature is used on system V to output a `swbeg' statement - for the table. - - If this macro is not defined, these labels are output with - `ASM_OUTPUT_INTERNAL_LABEL'. - -`ASM_OUTPUT_CASE_END (STREAM, NUM, TABLE)' - Define this if something special must be output at the end of a - jump-table. The definition should be a C statement to be executed - after the assembler code for the table is written. It should - write the appropriate code to stdio stream STREAM. The argument - TABLE is the jump-table insn, and NUM is the label-number of the - preceding label. + 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)))] + "" + "...") - If this macro is not defined, nothing special is output at the - end of the jump-table. + The `SELECT_CC_MODE' macro on the Sparc returns `CC_NOOVmode' for +comparisons whose argument is a `plus'.  -File: gcc.info, Node: Alignment Output, Prev: Dispatch Tables, Up: Assembler Format +File: gcc.info, Node: Insn Canonicalizations, Next: Peephole Definitions, Prev: Jump Patterns, Up: Machine Desc -Assembler Commands for Alignment --------------------------------- +Canonicalization of Instructions +================================ -`ASM_OUTPUT_ALIGN_CODE (FILE)' - A C expression to output text to align the location counter in - the way that is desirable at a point in the code that is reached - only by jumping. - - This macro need not be defined if you don't want any special - alignment to be done at such a time. Most machine descriptions - do not currently define the macro. - -`ASM_OUTPUT_LOOP_ALIGN (FILE)' - A C expression to output text to align the location counter in - the way that is desirable at the beginning of a loop. - - This macro need not be defined if you don't want any special - alignment to be done at such a time. Most machine descriptions - do not currently define the macro. - -`ASM_OUTPUT_SKIP (STREAM, NBYTES)' - A C statement to output to the stdio stream STREAM an assembler - instruction to advance the location counter by NBYTES bytes. - Those bytes should be zero when loaded. NBYTES will be a C - expression of type `int'. - -`ASM_NO_SKIP_IN_TEXT' - Define this macro if `ASM_OUTPUT_SKIP' should not be used in the - text section because it fails put zeros in the bytes that are - skipped. This is true on many Unix systems, where the pseudo--op - to skip bytes produces no-op instructions rather than zeros when - used in the text section. - -`ASM_OUTPUT_ALIGN (STREAM, POWER)' - A C statement to output to the stdio stream STREAM an assembler - command to advance the location counter to a multiple of 2 to the - POWER bytes. POWER will be a C expression of type `int'. + 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.  -File: gcc.info, Node: Debugging Info, Next: Cross-compilation, Prev: Assembler Format, Up: Machine Macros - -Controlling Debugging Information Format -======================================== +File: gcc.info, Node: Peephole Definitions, Next: Expander Definitions, Prev: Insn Canonicalizations, Up: Machine Desc -`DBX_REGISTER_NUMBER (REGNO)' - A C expression that returns the DBX register number for the - compiler register number REGNO. In simple cases, the value of - this expression may be REGNO itself. But sometimes there are some - registers that the compiler knows about and DBX does not, or vice - versa. In such cases, some register may need to have one number - in the compiler and another for DBX. - - If two registers have consecutive numbers inside GNU CC, and they - can be used as a pair to hold a multiword value, then they *must* - have consecutive numbers after renumbering with - `DBX_REGISTER_NUMBER'. Otherwise, debuggers will be unable to - access such a pair, because they expect register pairs to be - consecutive in their own numbering scheme. - - If you find yourself defining `DBX_REGISTER_NUMBER' in way that - does not preserve register pairs, then what you must do instead is - redefine the actual register numbering scheme. - -`DBX_DEBUGGING_INFO' - Define this macro if GNU CC should produce debugging output for - DBX in response to the `-g' option. - -`SDB_DEBUGGING_INFO' - Define this macro if GNU CC should produce COFF-style debugging - output for SDB in response to the `-g' option. - -`DWARF_DEBUGGING_INFO' - Define this macro if GNU CC should produce dwarf format debugging - output in response to the `-g' option. - -`DEFAULT_GDB_EXTENSIONS' - Define this macro to control whether GNU CC should by default - generate GDB's extended version of DBX debugging information - (assuming DBX-format debugging information is enabled at all). - If you don't define the macro, the default is 1: always generate - the extended information. - -`DEBUG_SYMS_TEXT' - Define this macro if all `.stabs' commands should be output while - in the text section. - -`DEBUGGER_AUTO_OFFSET (X)' - A C expression that returns the integer offset value for an - automatic variable having address X (an RTL expression). The - default computation assumes that X is based on the frame-pointer - and gives the offset from the frame-pointer. This is required - for targets that produce debugging output for DBX or COFF-style - debugging output for SDB and allow the frame-pointer to be - eliminated when the `-g' options is used. - -`DEBUGGER_ARG_OFFSET (OFFSET, X)' - A C expression that returns the integer offset value for an - argument having address X (an RTL expression). The nominal - offset is OFFSET. - -`ASM_STABS_OP' - A C string constant naming the assembler pseudo op to use instead - of `.stabs' to define an ordinary debugging symbol. If you don't - define this macro, `.stabs' is used. This macro applies only to - DBX debugging information format. - -`ASM_STABD_OP' - A C string constant naming the assembler pseudo op to use instead - of `.stabd' to define a debugging symbol whose value is the - current location. If you don't define this macro, `.stabd' is - used. This macro applies only to DBX debugging information - format. - -`ASM_STABN_OP' - A C string constant naming the assembler pseudo op to use instead - of `.stabn' to define a debugging symbol with no name. If you - don't define this macro, `.stabn' is used. This macro applies - only to DBX debugging information format. - -`PUT_SDB_...' - Define these macros to override the assembler syntax for the - special SDB assembler directives. See `sdbout.c' for a list of - these macros and their arguments. If the standard syntax is - used, you need not define them yourself. - -`SDB_DELIM' - Some assemblers do not support a semicolon as a delimiter, even - between SDB assembler directives. In that case, define this - macro to be the delimiter to use (usually `\n'). It is not - necessary to define a new set of `PUT_SDB_OP' macros if this is - the only change required. - -`SDB_GENERATE_FAKE' - Define this macro to override the usual method of constructing a - dummy name for anonymous structure and union types. See - `sdbout.c' for more information. - -`SDB_ALLOW_UNKNOWN_REFERENCES' - Define this macro to allow references to unknown structure, - union, or enumeration tags to be emitted. Standard COFF does not - allow handling of unknown references, MIPS ECOFF has support for - it. - -`SDB_ALLOW_FORWARD_REFERENCES' - Define this macro to allow references to structure, union, or - enumeration tags that have not yet been seen to be handled. Some - assemblers choke if forward tags are used, while some require it. - -`DBX_NO_XREFS' - Define this macro if DBX on your system does not support the - construct `xsTAGNAME'. On some systems, this construct is used to - describe a forward reference to a structure named TAGNAME. On - other systems, this construct is not supported at all. - -`DBX_CONTIN_LENGTH' - A symbol name in DBX-format debugging information is normally - continued (split into two separate `.stabs' directives) when it - exceeds a certain length (by default, 80 characters). On some - operating systems, DBX requires this splitting; on others, - splitting must not be done. You can inhibit splitting by - defining this macro with the value zero. You can override the - default splitting-length by defining this macro as an expression - for the length you desire. - -`DBX_CONTIN_CHAR' - Normally continuation is indicated by adding a `\' character to - the end of a `.stabs' string when a continuation follows. To use - a different character instead, define this macro as a character - constant for the character you want to use. Do not define this - macro if backslash is correct for your system. - -`DBX_STATIC_STAB_DATA_SECTION' - Define this macro if it is necessary to go to the data section - before outputting the `.stabs' pseudo-op for a non-global static - variable. - -`DBX_LBRAC_FIRST' - Define this macro if the `N_LBRAC' symbol for a block should - precede the debugging information for variables and functions - defined in that block. Normally, in DBX format, the `N_LBRAC' - symbol comes first. - -`DBX_FUNCTION_FIRST' - Define this macro if the DBX information for a function and its - arguments should precede the assembler code for the function. - Normally, in DBX format, the debugging information entirely - follows the assembler code. - -`DBX_OUTPUT_FUNCTION_END (STREAM, FUNCTION)' - Define this macro if the target machine requires special output - at the end of the debugging information for a function. The - definition should be a C statement (sans semicolon) to output the - appropriate information to STREAM. FUNCTION is the - `FUNCTION_DECL' node for the function. - -`DBX_OUTPUT_STANDARD_TYPES (SYMS)' - Define this macro if you need to control the order of output of - the standard data types at the beginning of compilation. The - argument SYMS is a `tree' which is a chain of all the predefined - global symbols, including names of data types. - - Normally, DBX output starts with definitions of the types for - integers and characters, followed by all the other predefined - types of the particular language in no particular order. - - On some machines, it is necessary to output different particular - types first. To do this, define `DBX_OUTPUT_STANDARD_TYPES' to - output those symbols in the necessary order. Any predefined - types that you don't explicitly output will be output afterward - in no particular order. - - Be careful not to define this macro so that it works only for C. - There are no global variables to access most of the built-in - types, because another language may have another set of types. - The way to output a particular type is to look through SYMS to - see if you can find it. Here is an example: - - { - tree decl; - for (decl = syms; decl; decl = TREE_CHAIN (decl)) - if (!strcmp (IDENTIFIER_POINTER (DECL_NAME (decl)), "long int")) - dbxout_symbol (decl); - ... - } - - This does nothing if the expected type does not exist. - - See the function `init_decl_processing' in source file `c-decl.c' - to find the names to use for all the built-in C types. - -`DBX_OUTPUT_MAIN_SOURCE_FILENAME (STREAM, NAME)' - A C statement to output DBX debugging information to the stdio - stream STREAM which indicates that file NAME is the main source - file--the file specified as the input file for compilation. This - macro is called only once, at the beginning of compilation. - - This macro need not be defined if the standard form of output for - DBX debugging information is appropriate. - -`DBX_OUTPUT_MAIN_SOURCE_DIRECTORY (STREAM, NAME)' - A C statement to output DBX debugging information to the stdio - stream STREAM which indicates that the current directory during - compilation is named NAME. - - This macro need not be defined if the standard form of output for - DBX debugging information is appropriate. - -`DBX_OUTPUT_MAIN_SOURCE_FILE_END (STREAM, NAME)' - A C statement to output DBX debugging information at the end of - compilation of the main source file NAME. - - If you don't define this macro, nothing special is output at the - end of compilation, which is correct for most machines. - -`DBX_OUTPUT_SOURCE_FILENAME (STREAM, NAME)' - A C statement to output DBX debugging information to the stdio - stream STREAM which indicates that file NAME is the current source - file. This output is generated each time input shifts to a - different source file as a result of `#include', the end of an - included file, or a `#line' command. - - This macro need not be defined if the standard form of output for - DBX debugging information is appropriate. - - -File: gcc.info, Node: Cross-compilation, Next: Misc, Prev: Debugging INfo, Up: Machine Macros - -Cross Compilation and Floating Point Format -=========================================== - - While all modern machines use 2's complement representation for -integers, there are a variety of representations for floating point -numbers. This means that in a cross-compiler the representation of -floating point numbers in the compiled program may be different from -that used in the machine doing the compilation. - - Because different representation systems may offer different -amounts of range and precision, the cross compiler cannot safely use -the host machine's floating point arithmetic. Therefore, floating -point constants must be represented in the target machine's format. -This means that the cross compiler cannot use `atof' to parse a -floating point constant; it must have its own special routine to use -instead. Also, constant folding must emulate the target machine's -arithmetic (or must not be done at all). - - The macros in the following table should be defined only if you are -cross compiling between different floating point formats. - - Otherwise, don't define them. Then default definitions will be set -up which use `double' as the data type, `==' to test for equality, etc. - - You don't need to worry about how many times you use an operand of -any of these macros. The compiler never uses operands which have side -effects. - -`REAL_VALUE_TYPE' - A macro for the C data type to be used to hold a floating point - value in the target machine's format. Typically this would be a - `struct' containing an array of `int'. - -`REAL_VALUES_EQUAL (X, Y)' - A macro for a C expression which compares for equality the two - values, X and Y, both of type `REAL_VALUE_TYPE'. - -`REAL_VALUES_LESS (X, Y)' - A macro for a C expression which tests whether X is less than Y, - both values being of type `REAL_VALUE_TYPE' and interpreted as - floating point numbers in the target machine's representation. - -`REAL_VALUE_LDEXP (X, SCALE)' - A macro for a C expression which performs the standard library - function `ldexp', but using the target machine's floating point - representation. Both X and the value of the expression have type - `REAL_VALUE_TYPE'. The second argument, SCALE, is an integer. - -`REAL_VALUE_FIX (X)' - A macro whose definition is a C expression to convert the - target-machine floating point value X to a signed integer. X has - type `REAL_VALUE_TYPE'. - -`REAL_VALUE_UNSIGNED_FIX (X)' - A macro whose definition is a C expression to convert the - target-machine floating point value X to an unsigned integer. X - has type `REAL_VALUE_TYPE'. - -`REAL_VALUE_FIX_TRUNCATE (X)' - A macro whose definition is a C expression to convert the - target-machine floating point value X to a signed integer, - rounding toward 0. X has type `REAL_VALUE_TYPE'. - -`REAL_VALUE_UNSIGNED_FIX_TRUNCATE (X)' - A macro whose definition is a C expression to convert the - target-machine floating point value X to an unsigned integer, - rounding toward 0. X has type `REAL_VALUE_TYPE'. - -`REAL_VALUE_ATOF (STRING)' - A macro for a C expression which converts STRING, an expression - of type `char *', into a floating point number in the target - machine's representation. The value has type `REAL_VALUE_TYPE'. - -`REAL_INFINITY' - Define this macro if infinity is a possible floating point value, - and therefore division by 0 is legitimate. - -`REAL_VALUE_ISINF (X)' - A macro for a C expression which determines whether X, a floating - point value, is infinity. The value has type `int'. By default, - this is defined to call `isinf'. - -`REAL_VALUE_ISNAN (X)' - A macro for a C expression which determines whether X, a floating - point value, is a "nan" (not-a-number). The value has type - `int'. By default, this is defined to call `isnan'. - - Define the following additional macros if you want to make floating -point constant folding work while cross compiling. If you don't -define them, cross compilation is still possible, but constant folding -will not happen for floating point values. - -`REAL_ARITHMETIC (OUTPUT, CODE, X, Y)' - A macro for a C statement which calculates an arithmetic - operation of the two floating point values X and Y, both of type - `REAL_VALUE_TYPE' in the target machine's representation, to - produce a result of the same type and representation which is - stored in OUTPUT (which will be a variable). - - The operation to be performed is specified by CODE, a tree code - which will always be one of the following: `PLUS_EXPR', - `MINUS_EXPR', `MULT_EXPR', `RDIV_EXPR', `MAX_EXPR', `MIN_EXPR'. - - The expansion of this macro is responsible for checking for - overflow. If overflow happens, the macro expansion should - execute the statement `return 0;', which indicates the inability - to perform the arithmetic operation requested. - -`REAL_VALUE_NEGATE (X)' - A macro for a C expression which returns the negative of the - floating point value X. Both X and the value of the expression - have type `REAL_VALUE_TYPE' and are in the target machine's - floating point representation. - - There is no way for this macro to report overflow, since overflow - can't happen in the negation operation. - -`REAL_VALUE_TRUNCATE (X)' - A macro for a C expression which converts the double-precision - floating point value X to single-precision. - - Both X and the value of the expression have type - `REAL_VALUE_TYPE' and are in the target machine's floating point - representation. However, the value should have an appropriate bit - pattern to be output properly as a single-precision floating - constant. - - There is no way for this macro to report overflow. - -`REAL_VALUE_TO_INT (LOW, HIGH, X)' - A macro for a C expression which converts a floating point value - X into a double-precision integer which is then stored into LOW - and HIGH, two variables of type INT. - -`REAL_VALUE_FROM_INT (X, LOW, HIGH)' - A macro for a C expression which converts a double-precision - integer found in LOW and HIGH, two variables of type INT, into a - floating point value which is then stored into X. - - -File: gcc.info, Node: Misc, Prev: Cross-compilation, Up: Machine Macros +Machine-Specific Peephole Optimizers +==================================== -Miscellaneous Parameters -======================== + In addition to instruction patterns the `md' file may contain +definitions of machine-specific peephole optimizations. -`PREDICATE_CODES' - Optionally define this if you have added predicates to - `MACHINE.c'. This macro is called within an initializer of an - array of structures. The first field in the structure is the - name of a predicate and the second field is an arrary of rtl - codes. For each predicate, list all rtl codes that can be in - expressions matched by the predicate. The list should have a - trailing comma. Here is an example of two entries in the list - for a typical RISC machine: - - #define PREDICATE_CODES \ - {"gen_reg_rtx_operand", {SUBREG, REG}}, \ - {"reg_or_short_cint_operand", {SUBREG, REG, CONST_INT}}, - - Defining this macro does not affect the generated code (however, - incorrect definitions that omit an rtl code that may be matched - by the predicate can cause the compiler to malfunction). - Instead, it allows the table built by `genrecog' to be more - compact and efficient, thus speeding up the compiler. The most - important predicates to include in the list specified by this - macro are thoses used in the most insn patterns. - -`CASE_VECTOR_MODE' - An alias for a machine mode name. This is the machine mode that - elements of a jump-table should have. - -`CASE_VECTOR_PC_RELATIVE' - Define this macro if jump-tables should contain relative - addresses. - -`CASE_DROPS_THROUGH' - Define this if control falls through a `case' insn when the index - value is out of range. This means the specified default-label is - actually ignored by the `case' insn proper. - -`BYTE_LOADS_ZERO_EXTEND' - Define this macro if an instruction to load a value narrower than - a word from memory into a register also zero-extends the value to - the whole register. - -`IMPLICIT_FIX_EXPR' - An alias for a tree code that should be used by default for - conversion of floating point values to fixed point. Normally, - `FIX_ROUND_EXPR' is used. - -`FIXUNS_TRUNC_LIKE_FIX_TRUNC' - Define this macro if the same instructions that convert a floating - point number to a signed fixed point number also convert validly - to an unsigned one. - -`EASY_DIV_EXPR' - An alias for a tree code that is the easiest kind of division to - compile code for in the general case. It may be - `TRUNC_DIV_EXPR', `FLOOR_DIV_EXPR', `CEIL_DIV_EXPR' or - `ROUND_DIV_EXPR'. These four division operators differ in how - they round the result to an integer. `EASY_DIV_EXPR' is used - when it is permissible to use any of those kinds of division and - the choice should be made on the basis of efficiency. - -`MOVE_MAX' - The maximum number of bytes that a single instruction can move - quickly from memory to memory. - -`SHIFT_COUNT_TRUNCATED' - Defining this macro causes the compiler to omit a sign-extend, - zero-extend, or bitwise `and' instruction that truncates the - count of a shift operation to a width equal to the number of bits - needed to represent the size of the object being shifted. On - machines that have instructions that act on bitfields at variable - positions, including `bit test' instructions, defining - `SHIFT_COUNT_TRUNCATED' also causes truncation not to be applied - to these instructions. - - If both types of instructions truncate the count (for shifts) and - position (for bitfield operations), or if no variable-position - bitfield instructions exist, you should define this macro. - - However, on some machines, such as the 80386, truncation only - applies to shift operations and not bitfield operations. Do not - define `SHIFT_COUNT_TRUNCATED' on such machines. Instead, add - patterns to the `md' file that include the implied truncation of - the shift instructions. - -`TRULY_NOOP_TRUNCATION (OUTPREC, INPREC)' - A C expression which is nonzero if on this machine it is safe to - "convert" an integer of INPREC bits to one of OUTPREC bits (where - OUTPREC is smaller than INPREC) by merely operating on it as if - it had only OUTPREC bits. - - On many machines, this expression can be 1. - - It is reported that suboptimal code can result when - `TRULY_NOOP_TRUNCATION' returns 1 for a pair of sizes for modes - for which `MODES_TIEABLE_P' is 0. If this is the case, making - `TRULY_NOOP_TRUNCATION' return 0 in such cases may improve things. - -`STORE_FLAG_VALUE' - A C expression describing the value returned by a comparison - operator and stored by a store-flag instruction (`sCOND') when the - condition is true. This description must apply to *all* the - `sCOND' patterns and all the comparison operators. - - A value of 1 or -1 means that the instruction implementing the - comparison operator returns exactly 1 or -1 when the comparison - is true and 0 when the comparison is false. Otherwise, the value - indicates which bits of the result are guaranteed to be 1 when - the comparison is true. This value is interpreted in the mode of - the comparison operation, which is given by the mode of the first - operand in the `sCOND' pattern. Either the low bit or the sign - bit of `STORE_FLAG_VALUE' be on. Presently, only those bits are - used by the compiler. - - If `STORE_FLAG_VALUE' is neither 1 or -1, the compiler will - generate code that depends only on the specified bits. It can - also replace comparison operators with equivalent operations if - they cause the required bits to be set, even if the remaining - bits are undefined. For example, on a machine whose comparison - operators return an `SImode' value and where `STORE_FLAG_VALUE' - is defined as `0x80000000', saying that just the sign bit is - relevant, the expression - - (ne:SI (and:SI X (const_int POWER-OF-2)) (const_int 0)) - - can be converted to - - (ashift:SI X (const_int N)) - - where N is the appropriate shift count to move the bit being - tested into the sign bit. - - There is no way to describe a machine that always sets the - low-order bit for a true value, but does not guarantee the value - of any other bits, but we do not know of any machine that has - such an instruction. If you are trying to port GNU CC to such a - machine, include an instruction to perform a logical-and of the - result with 1 in the pattern for the comparison operators and let - us know (*note Bug Reporting::.). - - Often, a machine will have multiple instructions that obtain a - value from a comparison (or the condition codes). Here are rules - to guide the choice of value for `STORE_FLAG_VALUE', and hence - the instructions to be used: - - * Use the shortest sequence that yields a valid definition for - `STORE_FLAG_VALUE'. It is more efficent for the compiler to - "normalize" the value (convert it to, e.g., 1 or 0) than for - the comparison operators to do so because there may be - opportunities to combine the normalization with other - operations. - - * For equal-length sequences, use a value of 1 or -1, with -1 - being slightly preferred on machines with expensive jumps - and 1 preferred on other machines. - - * As a second choice, choose a value of `0x80000001' if - instructions exist that set both the sign and low-order bits - but do not define the others. - - * Otherwise, use a value of `0x80000000'. - - You need not define `STORE_FLAG_VALUE' if the machine has no - store-flag instructions. - -`Pmode' - An alias for the machine mode for pointers. Normally the - definition can be - - #define Pmode SImode - -`FUNCTION_MODE' - An alias for the machine mode used for memory references to - functions being called, in `call' RTL expressions. On most - machines this should be `QImode'. - -`INTEGRATE_THRESHOLD (DECL)' - A C expression for the maximum number of instructions above which - the function DECL should not be inlined. DECL is a - `FUNCTION_DECL' node. - - The default definition of this macro is 64 plus 8 times the - number of arguments that the function accepts. Some people think - a larger threshold should be used on RISC machines. - -`SCCS_DIRECTIVE' - Define this if the preprocessor should ignore `#sccs' directives - and print no error message. - -`HANDLE_PRAGMA (STREAM)' - Define this macro if you want to implement any pragmas. If - defined, it should be a C statement to be executed when `#pragma' - is seen. The argument STREAM is the stdio input stream from - which the source text can be read. - - It is generally a bad idea to implement new uses of `#pragma'. - The only reason to define this macro is for compatibility with - other compilers that do support `#pragma' for the sake of any user - programs which already use it. - -`HAVE_VPRINTF' - Define this if the library function `vprintf' is available on your - system. - -`DOLLARS_IN_IDENTIFIERS' - Define this macro to control use of the character `$' in - identifier names. The value should be 0, 1, or 2. 0 means `$' - is not allowed by default; 1 means it is allowed by default if - `-traditional' is used; 2 means it is allowed by default provided - `-ansi' is not used. 1 is the default; there is no need to - define this macro in that case. - -`DEFAULT_MAIN_RETURN' - Define this macro if the target system expects every program's - `main' function to return a standard "success" value by default - (if no other value is explicitly returned). - - The definition should be a C statement (sans semicolon) to - generate the appropriate rtl instructions. It is used only when - compiling the end of `main'. - -`HAVE_ATEXIT' - Define this if the target system supports the function `atexit' - from the ANSI C standard. If this is not defined, and - `INIT_SECTION_ASM_OP' is not defined, a default `exit' function - will be provided to support C++. - -`EXIT_BODY' - Define this if your `exit' function needs to do something besides - calling an external function `_cleanup' before terminating with - `_exit'. The `EXIT_BODY' macro is only needed if netiher - `HAVE_ATEXIT' nor `INIT_SECTION_ASM_OP' are defined. + The combiner does not notice certain peephole optimizations when the +data flow in the program does not suggest that it should try them. For +example, sometimes two consecutive insns related in purpose can be +combined even though the second one does not appear to use a register +computed in the first one. A machine-specific peephole optimizer can +detect such opportunities. + + A definition looks like this: + + (define_peephole + [INSN-PATTERN-1 + INSN-PATTERN-2 + ...] + "CONDITION" + "TEMPLATE" + "OPTIONAL INSN-ATTRIBUTES") + +The last string operand may be omitted if you are not using any +machine-specific information in this machine description. If present, +it must obey the same rules as in a `define_insn'. + + In this skeleton, INSN-PATTERN-1 and so on are patterns to match +consecutive insns. The optimization applies to a sequence of insns when +INSN-PATTERN-1 matches the first one, INSN-PATTERN-2 matches the next, +and so on. + + Each of the insns matched by a peephole must also match a +`define_insn'. Peepholes are checked only at the last stage just +before code generation, and only optionally. Therefore, any insn which +would match a peephole but no `define_insn' will cause a crash in code +generation in an unoptimized compilation, or at various optimization +stages. + + The operands of the insns are matched with `match_operands', +`match_operator', and `match_dup', as usual. What is not usual is that +the operand numbers apply to all the insn patterns in the definition. +So, you can check for identical operands in two insns by using +`match_operand' in one insn and `match_dup' in the other. + + The operand constraints used in `match_operand' patterns do not have +any direct effect on the applicability of the peephole, but they will +be validated afterward, so make sure your constraints are general enough +to apply whenever the peephole matches. If the peephole matches but +the constraints are not satisfied, the compiler will crash. + + It is safe to omit constraints in all the operands of the peephole; +or you can write constraints which serve as a double-check on the +criteria previously tested. + + Once a sequence of insns matches the patterns, the CONDITION is +checked. This is a C expression which makes the final decision whether +to perform the optimization (we do so if the expression is nonzero). If +CONDITION is omitted (in other words, the string is empty) then the +optimization is applied to every sequence of insns that matches the +patterns. + + The defined peephole optimizations are applied after register +allocation is complete. Therefore, the peephole definition can check +which operands have ended up in which kinds of registers, just by +looking at the operands. + + The way to refer to the operands in CONDITION is to write +`operands[I]' for operand number I (as matched by `(match_operand I +...)'). Use the variable `insn' to refer to the last of the insns +being matched; use `prev_nonnote_insn' to find the preceding insns. + + When optimizing computations with intermediate results, you can use +CONDITION to match only when the intermediate results are not used +elsewhere. Use the C expression `dead_or_set_p (INSN, OP)', where INSN +is the insn in which you expect the value to be used for the last time +(from the value of `insn', together with use of `prev_nonnote_insn'), +and OP is the intermediate value (from `operands[I]'). + + Applying the optimization means replacing the sequence of insns with +one new insn. The TEMPLATE controls ultimate output of assembler code +for this combined insn. It works exactly like the template of a +`define_insn'. Operand numbers in this template are the same ones used +in matching the original sequence of insns. + + The result of a defined peephole optimizer does not need to match +any of the insn patterns in the machine description; it does not even +have an opportunity to match them. The peephole optimizer definition +itself serves as the insn pattern to control how the insn is output. + + Defined peephole optimizers are run as assembler code is being +output, so the insns they produce are never combined or rearranged in +any way. + + Here is an example, taken from the 68000 machine description: + + (define_peephole + [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4))) + (set (match_operand:DF 0 "register_operand" "=f") + (match_operand:DF 1 "register_operand" "ad"))] + "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])" + "* + { + rtx xoperands[2]; + xoperands[1] = gen_rtx (REG, SImode, REGNO (operands[1]) + 1); + #ifdef MOTOROLA + output_asm_insn (\"move.l %1,(sp)\", xoperands); + output_asm_insn (\"move.l %1,-(sp)\", operands); + return \"fmove.d (sp)+,%0\"; + #else + output_asm_insn (\"movel %1,sp@\", xoperands); + output_asm_insn (\"movel %1,sp@-\", operands); + return \"fmoved sp@+,%0\"; + #endif + } + ") + + The effect of this optimization is to change + + jbsr _foobar + addql #4,sp + movel d1,sp@- + movel d0,sp@- + fmoved sp@+,fp0 + +into + + jbsr _foobar + movel d1,sp@ + movel d0,sp@- + fmoved sp@+,fp0 + + INSN-PATTERN-1 and so on look *almost* like the second operand of +`define_insn'. There is one important difference: the second operand +of `define_insn' consists of one or more RTX's enclosed in square +brackets. Usually, there is only one: then the same action can be +written as an element of a `define_peephole'. But when there are +multiple actions in a `define_insn', they are implicitly enclosed in a +`parallel'. Then you must explicitly write the `parallel', and the +square brackets within it, in the `define_peephole'. Thus, if an insn +pattern looks like this, + + (define_insn "divmodsi4" + [(set (match_operand:SI 0 "general_operand" "=d") + (div:SI (match_operand:SI 1 "general_operand" "0") + (match_operand:SI 2 "general_operand" "dmsK"))) + (set (match_operand:SI 3 "general_operand" "=d") + (mod:SI (match_dup 1) (match_dup 2)))] + "TARGET_68020" + "divsl%.l %2,%3:%0") + +then the way to mention this insn in a peephole is as follows: + + (define_peephole + [... + (parallel + [(set (match_operand:SI 0 "general_operand" "=d") + (div:SI (match_operand:SI 1 "general_operand" "0") + (match_operand:SI 2 "general_operand" "dmsK"))) + (set (match_operand:SI 3 "general_operand" "=d") + (mod:SI (match_dup 1) (match_dup 2)))]) + ...] + ...) - \ No newline at end of file