--- gcc/gcc.info-13 2018/04/24 17:51:23 1.1 +++ gcc/gcc.info-13 2018/04/24 18:11:10 1.1.1.6 @@ -1,998 +1,1098 @@ -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. +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: Frame Registers, Next: Elimination, Prev: Frame Layout, Up: Stack and Calling - -Registers That Address the Stack Frame --------------------------------------- +File: gcc.info, Node: Insns, Next: Calls, Prev: Assembler, Up: RTL -`STACK_POINTER_REGNUM' - The register number of the stack pointer register, which must - also be a fixed register according to `FIXED_REGISTERS'. On most - machines, the hardware determines which register this is. - -`FRAME_POINTER_REGNUM' - The register number of the frame pointer register, which is used - to access automatic variables in the stack frame. On some - machines, the hardware determines which register this is. On - other machines, you can choose any register you wish for this - purpose. - -`ARG_POINTER_REGNUM' - The register number of the arg pointer register, which is used to - access the function's argument list. On some machines, this is - the same as the frame pointer register. On some machines, the - hardware determines which register this is. On other machines, - you can choose any register you wish for this purpose. If this - is not the same register as the frame pointer register, then you - must mark it as a fixed register according to `FIXED_REGISTERS', - or arrange to be able to eliminate it (*note Elimination::.). - -`STATIC_CHAIN_REGNUM' -`STATIC_CHAIN_INCOMING_REGNUM' - Register numbers used for passing a function's static chain - pointer. If register windows are used, - `STATIC_CHAIN_INCOMING_REGNUM' is the register number as seen by - the called function, while `STATIC_CHAIN_REGNUM' is the register - number as seen by the calling function. If these registers are - the same, `STATIC_CHAIN_INCOMING_REGNUM' need not be defined. - - The static chain register need not be a fixed register. - - If the static chain is passed in memory, these macros should not - be defined; instead, the next two macros should be defined. - -`STATIC_CHAIN' -`STATIC_CHAIN_INCOMING' - If the static chain is passed in memory, these macros provide rtx - giving `mem' expressions that denote where they are stored. - `STATIC_CHAIN' and `STATIC_CHAIN_INCOMING' give the locations as - seen by the calling and called functions, respectively. Often - the former will be at an offset from the stack pointer and the - latter at an offset from the frame pointer. - - The variables `stack_pointer_rtx', `frame_pointer_rtx', and - `arg_pointer_rtx' will have been initialized prior to the use of - these macros and should be used to refer to those items. +Insns +===== - If the static chain is passed in a register, the two previous - macros should be defined instead. + The RTL representation of the code for a function is a doubly-linked +chain of objects called "insns". Insns are expressions with special +codes that are used for no other purpose. Some insns are actual +instructions; others represent dispatch tables for `switch' statements; +others represent labels to jump to or various sorts of declarative +information. + + In addition to its own specific data, each insn must have a unique +id-number that distinguishes it from all other insns in the current +function (after delayed branch scheduling, copies of an insn with the +same id-number may be present in multiple places in a function, but +these copies will always be identical and will only appear inside a +`sequence'), and chain pointers to the preceding and following insns. +These three fields occupy the same position in every insn, independent +of the expression code of the insn. They could be accessed with `XEXP' +and `XINT', but instead three special macros are always used: + +`INSN_UID (I)' + Accesses the unique id of insn I. + +`PREV_INSN (I)' + Accesses the chain pointer to the insn preceding I. If I is the + first insn, this is a null pointer. + +`NEXT_INSN (I)' + Accesses the chain pointer to the insn following I. If I is the + last insn, this is a null pointer. + + The first insn in the chain is obtained by calling `get_insns'; the +last insn is the result of calling `get_last_insn'. Within the chain +delimited by these insns, the `NEXT_INSN' and `PREV_INSN' pointers must +always correspond: if INSN is not the first insn, + + NEXT_INSN (PREV_INSN (INSN)) == INSN + +is always true and if INSN is not the last insn, + + PREV_INSN (NEXT_INSN (INSN)) == INSN + +is always true. + + After delay slot scheduling, some of the insns in the chain might be +`sequence' expressions, which contain a vector of insns. The value of +`NEXT_INSN' in all but the last of these insns is the next insn in the +vector; the value of `NEXT_INSN' of the last insn in the vector is the +same as the value of `NEXT_INSN' for the `sequence' in which it is +contained. Similar rules apply for `PREV_INSN'. + + This means that the above invariants are not necessarily true for +insns inside `sequence' expressions. Specifically, if INSN is the +first insn in a `sequence', `NEXT_INSN (PREV_INSN (INSN))' is the insn +containing the `sequence' expression, as is the value of `PREV_INSN +(NEXT_INSN (INSN))' is INSN is the last insn in the `sequence' +expression. You can use these expressions to find the containing +`sequence' expression. + + Every insn has one of the following six expression codes: + +`insn' + The expression code `insn' is used for instructions that do not + jump and do not do function calls. `sequence' expressions are + always contained in insns with code `insn' even if one of those + insns should jump or do function calls. + + Insns with code `insn' have four additional fields beyond the three + mandatory ones listed above. These four are described in a table + below. + +`jump_insn' + The expression code `jump_insn' is used for instructions that may + jump (or, more generally, may contain `label_ref' expressions). If + there is an instruction to return from the current function, it is + recorded as a `jump_insn'. + + `jump_insn' insns have the same extra fields as `insn' insns, + accessed in the same way and in addition contains a field + `JUMP_LABEL' which is defined once jump optimization has completed. + + For simple conditional and unconditional jumps, this field + contains the `code_label' to which this insn will (possibly + conditionally) branch. In a more complex jump, `JUMP_LABEL' + records one of the labels that the insn refers to; the only way to + find the others is to scan the entire body of the insn. + + Return insns count as jumps, but since they do not refer to any + labels, they have zero in the `JUMP_LABEL' field. + +`call_insn' + The expression code `call_insn' is used for instructions that may + do function calls. It is important to distinguish these + instructions because they imply that certain registers and memory + locations may be altered unpredictably. + + A `call_insn' insn may be preceded by insns that contain a single + `use' expression and be followed by insns the contain a single + `clobber' expression. If so, these `use' and `clobber' + expressions are treated as being part of the function call. There + must not even be a `note' between the `call_insn' and the `use' or + `clobber' insns for this special treatment to take place. This is + somewhat of a kludge and will be removed in a later version of GNU + CC. + + `call_insn' insns have the same extra fields as `insn' insns, + accessed in the same way. + +`code_label' + A `code_label' insn represents a label that a jump insn can jump + to. It contains two special fields of data in addition to the + three standard ones. `CODE_LABEL_NUMBER' is used to hold the + "label number", a number that identifies this label uniquely among + all the labels in the compilation (not just in the current + function). Ultimately, the label is represented in the assembler + output as an assembler label, usually of the form `LN' where N is + the label number. + + When a `code_label' appears in an RTL expression, it normally + appears within a `label_ref' which represents the address of the + label, as a number. + + The field `LABEL_NUSES' is only defined once the jump optimization + phase is completed and contains the number of times this label is + referenced in the current function. + +`barrier' + Barriers are placed in the instruction stream when control cannot + flow past them. They are placed after unconditional jump + instructions to indicate that the jumps are unconditional and + after calls to `volatile' functions, which do not return (e.g., + `exit'). They contain no information beyond the three standard + fields. + +`note' + `note' insns are used to represent additional debugging and + declarative information. They contain two nonstandard fields, an + integer which is accessed with the macro `NOTE_LINE_NUMBER' and a + string accessed with `NOTE_SOURCE_FILE'. + + If `NOTE_LINE_NUMBER' is positive, the note represents the + position of a source line and `NOTE_SOURCE_FILE' is the source + file name that the line came from. These notes control generation + of line number data in the assembler output. + + Otherwise, `NOTE_LINE_NUMBER' is not really a line number but a + code with one of the following values (and `NOTE_SOURCE_FILE' must + contain a null pointer): + + `NOTE_INSN_DELETED' + Such a note is completely ignorable. Some passes of the + compiler delete insns by altering them into notes of this + kind. + + `NOTE_INSN_BLOCK_BEG' + `NOTE_INSN_BLOCK_END' + These types of notes indicate the position of the beginning + and end of a level of scoping of variable names. They + control the output of debugging information. + + `NOTE_INSN_LOOP_BEG' + `NOTE_INSN_LOOP_END' + These types of notes indicate the position of the beginning + and end of a `while' or `for' loop. They enable the loop + optimizer to find loops quickly. + + `NOTE_INSN_LOOP_CONT' + Appears at the place in a loop that `continue' statements + jump to. + + `NOTE_INSN_LOOP_VTOP' + This note indicates the place in a loop where the exit test + begins for those loops in which the exit test has been + duplicated. This position becomes another virtual start of + the loop when considering loop invariants. + + `NOTE_INSN_FUNCTION_END' + Appears near the end of the function body, just before the + label that `return' statements jump to (on machine where a + single instruction does not suffice for returning). This + note may be deleted by jump optimization. + + `NOTE_INSN_SETJMP' + Appears following each call to `setjmp' or a related function. + + These codes are printed symbolically when they appear in debugging + dumps. + + The machine mode of an insn is normally `VOIDmode', but some phases +use the mode for various purposes; for example, the reload pass sets it +to `HImode' if the insn needs reloading but not register elimination +and `QImode' if both are required. The common subexpression +elimination pass sets the mode of an insn to `QImode' when it is the +first insn in a block that has already been processed. + + Here is a table of the extra fields of `insn', `jump_insn' and +`call_insn' insns: + +`PATTERN (I)' + An expression for the side effect performed by this insn. This + must be one of the following codes: `set', `call', `use', + `clobber', `return', `asm_input', `asm_output', `addr_vec', + `addr_diff_vec', `trap_if', `unspec', `unspec_volatile', + `parallel', or `sequence'. If it is a `parallel', each element of + the `parallel' must be one these codes, except that `parallel' + expressions cannot be nested and `addr_vec' and `addr_diff_vec' + are not permitted inside a `parallel' expression. + +`INSN_CODE (I)' + An integer that says which pattern in the machine description + matches this insn, or -1 if the matching has not yet been + attempted. + + Such matching is never attempted and this field remains -1 on an + insn whose pattern consists of a single `use', `clobber', + `asm_input', `addr_vec' or `addr_diff_vec' expression. + + Matching is also never attempted on insns that result from an `asm' + statement. These contain at least one `asm_operands' expression. + The function `asm_noperands' returns a non-negative value for such + insns. + + In the debugging output, this field is printed as a number + followed by a symbolic representation that locates the pattern in + the `md' file as some small positive or negative offset from a + named pattern. + +`LOG_LINKS (I)' + A list (chain of `insn_list' expressions) giving information about + dependencies between instructions within a basic block. Neither a + jump nor a label may come between the related insns. + +`REG_NOTES (I)' + A list (chain of `expr_list' and `insn_list' expressions) giving + miscellaneous information about the insn. It is often information + pertaining to the registers used in this insn. + + The `LOG_LINKS' field of an insn is a chain of `insn_list' +expressions. Each of these has two operands: the first is an insn, and +the second is another `insn_list' expression (the next one in the +chain). The last `insn_list' in the chain has a null pointer as second +operand. The significant thing about the chain is which insns appear +in it (as first operands of `insn_list' expressions). Their order is +not significant. + + This list is originally set up by the flow analysis pass; it is a +null pointer until then. Flow only adds links for those data +dependencies which can be used for instruction combination. For each +insn, the flow analysis pass adds a link to insns which store into +registers values that are used for the first time in this insn. The +instruction scheduling pass adds extra links so that every dependence +will be represented. Links represent data dependencies, +antidependencies and output dependencies; the machine mode of the link +distinguishes these three types: antidependencies have mode +`REG_DEP_ANTI', output dependencies have mode `REG_DEP_OUTPUT', and +data dependencies have mode `VOIDmode'. + + The `REG_NOTES' field of an insn is a chain similar to the +`LOG_LINKS' field but it includes `expr_list' expressions in addition +to `insn_list' expressions. There are several kinds of register notes, +which are distinguished by the machine mode, which in a register note +is really understood as being an `enum reg_note'. The first operand OP +of the note is data whose meaning depends on the kind of note. + + The macro `REG_NOTE_KIND (X)' returns the kind of register note. +Its counterpart, the macro `PUT_REG_NOTE_KIND (X, NEWKIND)' sets the +register note type of X to be NEWKIND. + + Register notes are of three classes: They may say something about an +input to an insn, they may say something about an output of an insn, or +they may create a linkage between two insns. There are also a set of +values that are only used in `LOG_LINKS'. + + These register notes annotate inputs to an insn: + +`REG_DEAD' + The value in OP dies in this insn; that is to say, altering the + value immediately after this insn would not affect the future + behavior of the program. + + This does not necessarily mean that the register OP has no useful + value after this insn since it may also be an output of the insn. + In such a case, however, a `REG_DEAD' note would be redundant and + is usually not present until after the reload pass, but no code + relies on this fact. + +`REG_INC' + The register OP is incremented (or decremented; at this level + there is no distinction) by an embedded side effect inside this + insn. This means it appears in a `post_inc', `pre_inc', + `post_dec' or `pre_dec' expression. + +`REG_NONNEG' + The register OP is known to have a nonnegative value when this + insn is reached. This is used so that decrement and branch until + zero instructions, such as the m68k dbra, can be matched. + + The `REG_NONNEG' note is added to insns only if the machine + description has a `decrement_and_branch_until_zero' pattern. + +`REG_NO_CONFLICT' + This insn does not cause a conflict between OP and the item being + set by this insn even though it might appear that it does. In + other words, if the destination register and OP could otherwise be + assigned the same register, this insn does not prevent that + assignment. + + Insns with this note are usually part of a block that begins with a + `clobber' insn specifying a multi-word pseudo register (which will + be the output of the block), a group of insns that each set one + word of the value and have the `REG_NO_CONFLICT' note attached, + and a final insn that copies the output to itself with an attached + `REG_EQUAL' note giving the expression being computed. This block + is encapsulated with `REG_LIBCALL' and `REG_RETVAL' notes on the + first and last insns, respectively. + +`REG_LABEL' + This insn uses OP, a `code_label', but is not a `jump_insn'. The + presence of this note allows jump optimization to be aware that OP + is, in fact, being used. + + The following notes describe attributes of outputs of an insn: + +`REG_EQUIV' +`REG_EQUAL' + This note is only valid on an insn that sets only one register and + indicates that that register will be equal to OP at run time; the + scope of this equivalence differs between the two types of notes. + The value which the insn explicitly copies into the register may + look different from OP, but they will be equal at run time. If the + output of the single `set' is a `strict_low_part' expression, the + note refers to the register that is contained in `SUBREG_REG' of + the `subreg' expression. + + For `REG_EQUIV', the register is equivalent to OP throughout the + entire function, and could validly be replaced in all its + occurrences by OP. ("Validly" here refers to the data flow of the + program; simple replacement may make some insns invalid.) For + example, when a constant is loaded into a register that is never + assigned any other value, this kind of note is used. + + When a parameter is copied into a pseudo-register at entry to a + function, a note of this kind records that the register is + equivalent to the stack slot where the parameter was passed. + Although in this case the register may be set by other insns, it + is still valid to replace the register by the stack slot + throughout the function. + + In the case of `REG_EQUAL', the register that is set by this insn + will be equal to OP at run time at the end of this insn but not + necessarily elsewhere in the function. In this case, OP is + typically an arithmetic expression. For example, when a sequence + of insns such as a library call is used to perform an arithmetic + operation, this kind of note is attached to the insn that produces + or copies the final value. + + These two notes are used in different ways by the compiler passes. + `REG_EQUAL' is used by passes prior to register allocation (such as + common subexpression elimination and loop optimization) to tell + them how to think of that value. `REG_EQUIV' notes are used by + register allocation to indicate that there is an available + substitute expression (either a constant or a `mem' expression for + the location of a parameter on the stack) that may be used in + place of a register if insufficient registers are available. + + Except for stack homes for parameters, which are indicated by a + `REG_EQUIV' note and are not useful to the early optimization + passes and pseudo registers that are equivalent to a memory + location throughout there entire life, which is not detected until + later in the compilation, all equivalences are initially indicated + by an attached `REG_EQUAL' note. In the early stages of register + allocation, a `REG_EQUAL' note is changed into a `REG_EQUIV' note + if OP is a constant and the insn represents the only set of its + destination register. + + Thus, compiler passes prior to register allocation need only check + for `REG_EQUAL' notes and passes subsequent to register allocation + need only check for `REG_EQUIV' notes. + +`REG_UNUSED' + The register OP being set by this insn will not be used in a + subsequent insn. This differs from a `REG_DEAD' note, which + indicates that the value in an input will not be used subsequently. + These two notes are independent; both may be present for the same + register. + +`REG_WAS_0' + The single output of this insn contained zero before this insn. + OP is the insn that set it to zero. You can rely on this note if + it is present and OP has not been deleted or turned into a `note'; + its absence implies nothing. + + These notes describe linkages between insns. They occur in pairs: +one insn has one of a pair of notes that points to a second insn, which +has the inverse note pointing back to the first insn. + +`REG_RETVAL' + This insn copies the value of a multi-insn sequence (for example, a + library call), and OP is the first insn of the sequence (for a + library call, the first insn that was generated to set up the + arguments for the library call). + + Loop optimization uses this note to treat such a sequence as a + single operation for code motion purposes and flow analysis uses + this note to delete such sequences whose results are dead. + + A `REG_EQUAL' note will also usually be attached to this insn to + provide the expression being computed by the sequence. + +`REG_LIBCALL' + This is the inverse of `REG_RETVAL': it is placed on the first + insn of a multi-insn sequence, and it points to the last one. + +`REG_CC_SETTER' +`REG_CC_USER' + On machines that use `cc0', the insns which set and use `cc0' set + and use `cc0' are adjacent. However, when branch delay slot + filling is done, this may no longer be true. In this case a + `REG_CC_USER' note will be placed on the insn setting `cc0' to + point to the insn using `cc0' and a `REG_CC_SETTER' note will be + placed on the insn using `cc0' to point to the insn setting `cc0'. + + These values are only used in the `LOG_LINKS' field, and indicate +the type of dependency that each link represents. Links which indicate +a data dependence (a read after write dependence) do not use any code, +they simply have mode `VOIDmode', and are printed without any +descriptive text. + +`REG_DEP_ANTI' + This indicates an anti dependence (a write after read dependence). + +`REG_DEP_OUTPUT' + This indicates an output dependence (a write after write + dependence). + + For convenience, the machine mode in an `insn_list' or `expr_list' +is printed using these symbolic codes in debugging dumps. + + The only difference between the expression codes `insn_list' and +`expr_list' is that the first operand of an `insn_list' is assumed to +be an insn and is printed in debugging dumps as the insn's unique id; +the first operand of an `expr_list' is printed in the ordinary way as +an expression.  -File: gcc.info, Node: Elimination, Next: Stack Arguments, Prev: Frame Registers, Up: Stack and Calling +File: gcc.info, Node: Calls, Next: Sharing, Prev: Insns, Up: RTL -Eliminating Frame Pointer and Arg Pointer ------------------------------------------ +RTL Representation of Function-Call Insns +========================================= -`FRAME_POINTER_REQUIRED' - A C expression which is nonzero if a function must have and use a - frame pointer. This expression is evaluated in the reload pass. - If its value is nonzero the function will have a frame pointer. - - The expression can in principle examine the current function and - decide according to the facts, but on most machines the constant - 0 or the constant 1 suffices. Use 0 when the machine allows code - to be generated with no frame pointer, and doing so saves some - time or space. Use 1 when there is no possible advantage to - avoiding a frame pointer. - - In certain cases, the compiler does not know how to produce valid - code without a frame pointer. The compiler recognizes those - cases and automatically gives the function a frame pointer - regardless of what `FRAME_POINTER_REQUIRED' says. You don't need - to worry about them. - - In a function that does not require a frame pointer, the frame - pointer register can be allocated for ordinary usage, unless you - mark it as a fixed register. See `FIXED_REGISTERS' for more - information. - - This macro is ignored and need not be defined if `ELIMINABLE_REGS' - is defined. - -`INITIAL_FRAME_POINTER_OFFSET (DEPTH-VAR)' - A C statement to store in the variable DEPTH-VAR the difference - between the frame pointer and the stack pointer values - immediately after the function prologue. The value would be - computed from information such as the result of `get_frame_size - ()' and the tables of registers `regs_ever_live' and - `call_used_regs'. - - If `ELIMINABLE_REGS' is defined, this macro will be not be used - and need not be defined. Otherwise, it must be defined even if - `FRAME_POINTER_REQUIRED' is defined to always be true; in that - case, you may set DEPTH-VAR to anything. - -`ELIMINABLE_REGS' - If defined, this macro specifies a table of register pairs used to - eliminate unneeded registers that point into the stack frame. If - it is not defined, the only elimination attempted by the compiler - is to replace references to the frame pointer with references to - the stack pointer. - - The definition of this macro is a list of structure - initializations, each of which specifies an original and - replacement register. - - On some machines, the position of the argument pointer is not - known until the compilation is completed. In such a case, a - separate hard register must be used for the argument pointer. - This register can be eliminated by replacing it with either the - frame pointer or the argument pointer, depending on whether or - not the frame pointer has been eliminated. - - In this case, you might specify: - #define ELIMINABLE_REGS \ - {{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM}, \ - {ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM}, \ - {FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM}} - - Note that the elimination of the argument pointer with the stack - pointer is specified first since that is the preferred - elimination. - -`CAN_ELIMINATE (FROM-REG, TO-REG)' - A C expression that returns non-zero if the compiler is allowed - to try to replace register number FROM-REG with register number - TO-REG. This macro need only be defined if `ELIMINABLE_REGS' is - defined, and will usually be the constant 1, since most of the - cases preventing register elimination are things that the - compiler already knows about. - -`INITIAL_ELIMINATION_OFFSET (FROM-REG, TO-REG, OFFSET-VAR)' - This macro is similar to `INITIAL_FRAME_POINTER_OFFSET'. It - specifies the initial difference between the specified pair of - registers. This macro must be defined if `ELIMINABLE_REGS' is - defined. - -`LONGJMP_RESTORE_FROM_STACK' - Define this macro if the `longjmp' function restores registers - from the stack frames, rather than from those saved specifically - by `setjmp'. Certain quantities must not be kept in registers - across a call to `setjmp' on such machines. + Insns that call subroutines have the RTL expression code `call_insn'. +These insns must satisfy special rules, and their bodies must use a +special RTL expression code, `call'. + + A `call' expression has two operands, as follows: + + (call (mem:FM ADDR) NBYTES) + +Here NBYTES is an operand that represents the number of bytes of +argument data being passed to the subroutine, FM is a machine mode +(which must equal as the definition of the `FUNCTION_MODE' macro in the +machine description) and ADDR represents the address of the subroutine. + + For a subroutine that returns no value, the `call' expression as +shown above is the entire body of the insn, except that the insn might +also contain `use' or `clobber' expressions. + + For a subroutine that returns a value whose mode is not `BLKmode', +the value is returned in a hard register. If this register's number is +R, then the body of the call insn looks like this: + + (set (reg:M R) + (call (mem:FM ADDR) NBYTES)) + +This RTL expression makes it clear (to the optimizer passes) that the +appropriate register receives a useful value in this insn. + + When a subroutine returns a `BLKmode' value, it is handled by +passing to the subroutine the address of a place to store the value. +So the call insn itself does not "return" any value, and it has the +same RTL form as a call that returns nothing. + + On some machines, the call instruction itself clobbers some register, +for example to contain the return address. `call_insn' insns on these +machines should have a body which is a `parallel' that contains both +the `call' expression and `clobber' expressions that indicate which +registers are destroyed. Similarly, if the call instruction requires +some register other than the stack pointer that is not explicitly +mentioned it its RTL, a `use' subexpression should mention that +register. + + Functions that are called are assumed to modify all registers listed +in the configuration macro `CALL_USED_REGISTERS' (*note Register +Basics::.) and, with the exception of `const' functions and library +calls, to modify all of memory. + + Insns containing just `use' expressions directly precede the +`call_insn' insn to indicate which registers contain inputs to the +function. Similarly, if registers other than those in +`CALL_USED_REGISTERS' are clobbered by the called function, insns +containing a single `clobber' follow immediately after the call to +indicate which registers.  -File: gcc.info, Node: Stack Arguments, Next: Register Arguments, Prev: Elimination, Up: Stack and Calling +File: gcc.info, Node: Sharing, Next: Reading RTL, Prev: Calls, Up: RTL -Passing Function Arguments on the Stack ---------------------------------------- +Structure Sharing Assumptions +============================= - The macros in this section control how arguments are passed on the -stack. See the following section for other macros that control -passing certain arguments in registers. - -`PROMOTE_PROTOTYPES' - Define this macro if an argument declared as `char' or `short' in - a prototype should actually be passed as an `int'. In addition - to avoiding errors in certain cases of mismatch, it also makes - for better code on certain machines. - -`PUSH_ROUNDING (NPUSHED)' - A C expression that is the number of bytes actually pushed onto - the stack when an instruction attempts to push NPUSHED bytes. - - If the target machine does not have a push instruction, do not - define this macro. That directs GNU CC to use an alternate - strategy: to allocate the entire argument block and then store - the arguments into it. - - On some machines, the definition - - #define PUSH_ROUNDING(BYTES) (BYTES) - - will suffice. But on other machines, instructions that appear to - push one byte actually push two bytes in an attempt to maintain - alignment. Then the definition should be - - #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1) - -`ACCUMULATE_OUTGOING_ARGS' - If defined, the maximum amount of space required for outgoing - arguments will be computed and placed into the variable - `current_function_outgoing_args_size'. No space will be pushed - onto the stack for each call; instead, the function prologue - should increase the stack frame size by this amount. - - It is not proper to define both `PUSH_ROUNDING' and - `ACCUMULATE_OUTGOING_ARGS'. - -`REG_PARM_STACK_SPACE' - Define this macro if functions should assume that stack space has - been allocated for arguments even when their values are passed in - registers. - - The value of this macro is the size, in bytes, of the area - reserved for arguments passed in registers. - - This space can either be allocated by the caller or be a part of - the machine-dependent stack frame: `OUTGOING_REG_PARM_STACK_SPACE' - says which. - -`OUTGOING_REG_PARM_STACK_SPACE' - Define this if it is the responsibility of the caller to allocate - the area reserved for arguments passed in registers. - - If `ACCUMULATE_OUTGOING_ARGS' is defined, this macro controls - whether the space for these arguments counts in the value of - `current_function_outgoing_args_size'. - -`STACK_PARMS_IN_REG_PARM_AREA' - Define this macro if `REG_PARM_STACK_SPACE' is defined but stack - parameters don't skip the area specified by - `REG_PARM_STACK_SPACE'. - - Normally, when a parameter is not passed in registers, it is - placed on the stack beyond the `REG_PARM_STACK_SPACE' area. - Defining this macro suppresses this behavior and causes the - parameter to be passed on the stack in its natural location. - -`RETURN_POPS_ARGS (FUNTYPE, STACK-SIZE)' - A C expression that should indicate the number of bytes of its own - arguments that a function pops on returning, or 0 if the function - pops no arguments and the caller must therefore pop them all - after the function returns. - - FUNTYPE is a C variable whose value is a tree node that describes - the function in question. Normally it is a node of type - `FUNCTION_TYPE' that describes the data type of the function. - From this it is possible to obtain the data types of the value and - arguments (if known). - - When a call to a library function is being considered, FUNTYPE - will contain an identifier node for the library function. Thus, - if you need to distinguish among various library functions, you - can do so by their names. Note that "library function" in this - context means a function used to perform arithmetic, whose name - is known specially in the compiler and was not mentioned in the C - code being compiled. - - STACK-SIZE is the number of bytes of arguments passed on the - stack. If a variable number of bytes is passed, it is zero, and - argument popping will always be the responsibility of the calling - function. - - On the Vax, all functions always pop their arguments, so the - definition of this macro is STACK-SIZE. On the 68000, using the - standard calling convention, no functions pop their arguments, so - the value of the macro is always 0 in this case. But an - alternative calling convention is available in which functions - that take a fixed number of arguments pop them but other - functions (such as `printf') pop nothing (the caller pops all). - When this convention is in use, FUNTYPE is examined to determine - whether a function takes a fixed number of arguments. + The compiler assumes that certain kinds of RTL expressions are +unique; there do not exist two distinct objects representing the same +value. In other cases, it makes an opposite assumption: that no RTL +expression object of a certain kind appears in more than one place in +the containing structure. + + These assumptions refer to a single function; except for the RTL +objects that describe global variables and external functions, and a +few standard objects such as small integer constants, no RTL objects +are common to two functions. + + * Each pseudo-register has only a single `reg' object to represent + it, and therefore only a single machine mode. + + * For any symbolic label, there is only one `symbol_ref' object + referring to it. + + * There is only one `const_int' expression with value 0, only one + with value 1, and only one with value -1. Some other integer + values are also stored uniquely. + + * There is only one `pc' expression. + + * There is only one `cc0' expression. + + * There is only one `const_double' expression with value 0 for each + floating point mode. Likewise for values 1 and 2. + + * No `label_ref' or `scratch' appears in more than one place in the + RTL structure; in other words, it is safe to do a tree-walk of all + the insns in the function and assume that each time a `label_ref' + or `scratch' is seen it is distinct from all others that are seen. + + * Only one `mem' object is normally created for each static variable + or stack slot, so these objects are frequently shared in all the + places they appear. However, separate but equal objects for these + variables are occasionally made. + + * When a single `asm' statement has multiple output operands, a + distinct `asm_operands' expression is made for each output operand. + However, these all share the vector which contains the sequence of + input operands. This sharing is used later on to test whether two + `asm_operands' expressions come from the same statement, so all + optimizations must carefully preserve the sharing if they copy the + vector at all. + + * No RTL object appears in more than one place in the RTL structure + except as described above. Many passes of the compiler rely on + this by assuming that they can modify RTL objects in place without + unwanted side-effects on other insns. + + * During initial RTL generation, shared structure is freely + introduced. After all the RTL for a function has been generated, + all shared structure is copied by `unshare_all_rtl' in + `emit-rtl.c', after which the above rules are guaranteed to be + followed. + + * During the combiner pass, shared structure within an insn can exist + temporarily. However, the shared structure is copied before the + combiner is finished with the insn. This is done by calling + `copy_rtx_if_shared', which is a subroutine of `unshare_all_rtl'.  -File: gcc.info, Node: Register Arguments, Next: Scalar Return, Prev: Stack Arguments, Up: Stack and Calling +File: gcc.info, Node: Reading RTL, Prev: Sharing, Up: RTL -Passing Arguments in Registers ------------------------------- +Reading RTL +=========== - This section describes the macros which let you control how various -types of arguments are passed in registers or how they are arranged in -the stack. - -`FUNCTION_ARG (CUM, MODE, TYPE, NAMED)' - A C expression that controls whether a function argument is passed - in a register, and which register. - - The arguments are CUM, which summarizes all the previous - arguments; MODE, the machine mode of the argument; TYPE, the data - type of the argument as a tree node or 0 if that is not known - (which happens for C support library functions); and NAMED, which - is 1 for an ordinary argument and 0 for nameless arguments that - correspond to `...' in the called function's prototype. - - The value of the expression should either be a `reg' RTX for the - hard register in which to pass the argument, or zero to pass the - argument on the stack. - - For machines like the Vax and 68000, where normally all arguments - are pushed, zero suffices as a definition. - - The usual way to make the ANSI library `stdarg.h' work on a - machine where some arguments are usually passed in registers, is - to cause nameless arguments to be passed on the stack instead. - This is done by making `FUNCTION_ARG' return 0 whenever NAMED is - 0. - - You may use the macro `MUST_PASS_IN_STACK (MODE, TYPE)' in the - definition of this macro to determine if this argument is of a - type that must be passed in the stack. If `REG_PARM_STACK_SPACE' - is not defined and `FUNCTION_ARG' returns non-zero for such an - argument, the compiler will abort. If `REG_PARM_STACK_SPACE' is - defined, the argument will be computed in the stack and then - loaded into a register. - -`FUNCTION_INCOMING_ARG (CUM, MODE, TYPE, NAMED)' - Define this macro if the target machine has "register windows", so - that the register in which a function sees an arguments is not - necessarily the same as the one in which the caller passed the - argument. - - For such machines, `FUNCTION_ARG' computes the register in which - the caller passes the value, and `FUNCTION_INCOMING_ARG' should - be defined in a similar fashion to tell the function being called - where the arguments will arrive. - - If `FUNCTION_INCOMING_ARG' is not defined, `FUNCTION_ARG' serves - both purposes. - -`FUNCTION_ARG_PARTIAL_NREGS (CUM, MODE, TYPE, NAMED)' - A C expression for the number of words, at the beginning of an - argument, must be put in registers. The value must be zero for - arguments that are passed entirely in registers or that are - entirely pushed on the stack. - - On some machines, certain arguments must be passed partially in - registers and partially in memory. On these machines, typically - the first N words of arguments are passed in registers, and the - rest on the stack. If a multi-word argument (a `double' or a - structure) crosses that boundary, its first few words must be - passed in registers and the rest must be pushed. This macro - tells the compiler when this occurs, and how many of the words - should go in registers. - - `FUNCTION_ARG' for these arguments should return the first - register to be used by the caller for this argument; likewise - `FUNCTION_INCOMING_ARG', for the called function. - -`FUNCTION_ARG_PASS_BY_REFERENCE (CUM, MODE, TYPE, NAMED)' - A C expression that indicates when an argument must be passed by - reference. If nonzero for an argument, a copy of that argument - is made in memory and a pointer to the argument is passed instead - of the argument itself. The pointer is passed in whatever way is - appropriate for passing a pointer to that type. - - On machines where `REG_PARM_STACK_SPACE' is not defined, a - suitable definition of this macro might be - #define FUNCTION_ARG_PASS_BY_REFERENCE(CUM, MODE, TYPE, NAMED) \ - MUST_PASS_IN_STACK (MODE, TYPE) - -`CUMULATIVE_ARGS' - A C type for declaring a variable that is used as the first - argument of `FUNCTION_ARG' and other related values. For some - target machines, the type `int' suffices and can hold the number - of bytes of argument so far. - - There is no need to record in `CUMULATIVE_ARGS' anything about the - arguments that have been passed on the stack. The compiler has - other variables to keep track of that. For target machines on - which all arguments are passed on the stack, there is no need to - store anything in `CUMULATIVE_ARGS'; however, the data structure - must exist and should not be empty, so use `int'. - -`INIT_CUMULATIVE_ARGS (CUM, FNTYPE, LIBNAME)' - A C statement (sans semicolon) for initializing the variable CUM - for the state at the beginning of the argument list. The - variable has type `CUMULATIVE_ARGS'. The value of FNTYPE is the - tree node for the data type of the function which will receive - the args, or 0 if the args are to a compiler support library - function. - - When processing a call to a compiler support library function, - LIBNAME identifies which one. It is a `symbol_ref' rtx which - contains the name of the function, as a string. LIBNAME is 0 when - an ordinary C function call is being processed. Thus, each time - this macro is called, either LIBNAME or FNTYPE is nonzero, but - never both of them at once. - -`INIT_CUMULATIVE_INCOMING_ARGS (CUM, FNTYPE, LIBNAME)' - Like `INIT_CUMULATIVE_ARGS' but overrides it for the purposes of - finding the arguments for the function being compiled. If this - macro is undefined, `INIT_CUMULATIVE_ARGS' is used instead. - - The argument LIBNAME exists for symmetry with - `INIT_CUMULATIVE_ARGS'. The value passed for LIBNAME is always - 0, since library routines with special calling conventions are - never compiled with GNU CC. - -`FUNCTION_ARG_ADVANCE (CUM, MODE, TYPE, NAMED)' - A C statement (sans semicolon) to update the summarizer variable - CUM to advance past an argument in the argument list. The values - MODE, TYPE and NAMED describe that argument. Once this is done, - the variable CUM is suitable for analyzing the *following* - argument with `FUNCTION_ARG', etc. - - This macro need not do anything if the argument in question was - passed on the stack. The compiler knows how to track the amount - of stack space used for arguments without any special help. - -`FUNCTION_ARG_PADDING (MODE, TYPE)' - If defined, a C expression which determines whether, and in which - direction, to pad out an argument with extra space. The value - should be of type `enum direction': either `upward' to pad above - the argument, `downward' to pad below, or `none' to inhibit - padding. - - This macro does not control the *amount* of padding; that is - always just enough to reach the next multiple of - `FUNCTION_ARG_BOUNDARY'. - - This macro has a default definition which is right for most - systems. For little-endian machines, the default is to pad - upward. For big-endian machines, the default is to pad downward - for an argument of constant size shorter than an `int', and - upward otherwise. - -`FUNCTION_ARG_BOUNDARY (MODE, TYPE)' - If defined, a C expression that gives the alignment boundary, in - bits, of an argument with the specified mode and type. If it is - not defined, `PARM_BOUNDARY' is used for all arguments. - -`FUNCTION_ARG_REGNO_P (REGNO)' - A C expression that is nonzero if REGNO is the number of a hard - register in which function arguments are sometimes passed. This - does *not* include implicit arguments such as the static chain and - the structure-value address. On many machines, no registers can - be used for this purpose since all function arguments are pushed - on the stack. + To read an RTL object from a file, call `read_rtx'. It takes one +argument, a stdio stream, and returns a single RTL object. - -File: gcc.info, Node: Scalar Return, Next: Aggregate Return, Prev: Register Arguments, Up: Stack and Calling + Reading RTL from a file is very slow. This is no currently not a +problem because reading RTL occurs only as part of building the +compiler. -How Scalar Function Values Are Returned ---------------------------------------- + People frequently have the idea of using RTL stored as text in a +file as an interface between a language front end and the bulk of GNU +CC. This idea is not feasible. - This section discusses the macros that control returning scalars as -values--values that can fit in registers. + GNU CC was designed to use RTL internally only. Correct RTL for a +given program is very dependent on the particular target machine. And +the RTL does not contain all the information about the program. -`TRADITIONAL_RETURN_FLOAT' - Define this macro if `-traditional' should not cause functions - declared to return `float' to convert the value to `double'. - -`FUNCTION_VALUE (VALTYPE, FUNC)' - A C expression to create an RTX representing the place where a - function returns a value of data type VALTYPE. VALTYPE is a tree - node representing a data type. Write `TYPE_MODE (VALTYPE)' to - get the machine mode used to represent that type. On many - machines, only the mode is relevant. (Actually, on most - machines, scalar values are returned in the same place regardless - of mode). - - If the precise function being called is known, FUNC is a tree - node (`FUNCTION_DECL') for it; otherwise, FUNC is a null pointer. - This makes it possible to use a different value-returning - convention for specific functions when all their calls are known. - - `FUNCTION_VALUE' is not used for return vales with aggregate data - types, because these are returned in another way. See - `STRUCT_VALUE_REGNUM' and related macros, below. - -`FUNCTION_OUTGOING_VALUE (VALTYPE, FUNC)' - Define this macro if the target machine has "register windows" so - that the register in which a function returns its value is not - the same as the one in which the caller sees the value. - - For such machines, `FUNCTION_VALUE' computes the register in - which the caller will see the value, and - `FUNCTION_OUTGOING_VALUE' should be defined in a similar fashion - to tell the function where to put the value. - - If `FUNCTION_OUTGOING_VALUE' is not defined, `FUNCTION_VALUE' - serves both purposes. - - `FUNCTION_OUTGOING_VALUE' is not used for return vales with - aggregate data types, because these are returned in another way. - See `STRUCT_VALUE_REGNUM' and related macros, below. - -`LIBCALL_VALUE (MODE)' - A C expression to create an RTX representing the place where a - library function returns a value of mode MODE. If the precise - function being called is known, FUNC is a tree node - (`FUNCTION_DECL') for it; otherwise, FUNC is a null pointer. - This makes it possible to use a different value-returning - convention for specific functions when all their calls are known. - - Note that "library function" in this context means a compiler - support routine, used to perform arithmetic, whose name is known - specially by the compiler and was not mentioned in the C code - being compiled. - - The definition of `LIBRARY_VALUE' need not be concerned aggregate - data types, because none of the library functions returns such - types. - -`FUNCTION_VALUE_REGNO_P (REGNO)' - A C expression that is nonzero if REGNO is the number of a hard - register in which the values of called function may come back. - - A register whose use for returning values is limited to serving - as the second of a pair (for a value of type `double', say) need - not be recognized by this macro. So for most machines, this - definition suffices: - - #define FUNCTION_VALUE_REGNO_P(N) ((N) == 0) - - If the machine has register windows, so that the caller and the - called function use different registers for the return value, - this macro should recognize only the caller's register numbers. + The proper way to interface GNU CC to a new language front end is +with the "tree" data structure. There is no manual for this data +structure, but it is described in the files `tree.h' and `tree.def'.  -File: gcc.info, Node: Aggregate Return, Next: Caller Saves, Prev: Scalar Return, Up: Stack and Calling +File: gcc.info, Node: Machine Desc, Next: Target Macros, Prev: RTL, Up: Top -How Large Values Are Returnd ----------------------------- +Machine Descriptions +******************** - When a function value's mode is `BLKmode' (and in some other -cases), the value is not returned according to `FUNCTION_VALUE' (*note -Scalar Return::.). Instead, the caller passes the address of a block -of memory in which the value should be stored. This address is called -the "structure value address". - - This section describes how to control returning structure values in -memory. - -`RETURN_IN_MEMORY (TYPE)' - A C expression which can inhibit the returning of certain function - values in registers, based on the type of value. A nonzero value - says to return the function value in memory, just as large - structures are always returned. Here TYPE will be a C expression - of type `tree', representing the data type of the value. - - Note that values of mode `BLKmode' are returned in memory - regardless of this macro. Also, the option `-fpcc-struct-return' - takes effect regardless of this macro. On most systems, it is - possible to leave the macro undefined; this causes a default - definition to be used, whose value is the constant 0. - -`STRUCT_VALUE_REGNUM' - If the structure value address is passed in a register, then - `STRUCT_VALUE_REGNUM' should be the number of that register. - -`STRUCT_VALUE' - If the structure value address is not passed in a register, define - `STRUCT_VALUE' as an expression returning an RTX for the place - where the address is passed. If it returns 0, the address is - passed as an "invisible" first argument. - -`STRUCT_VALUE_INCOMING_REGNUM' - On some architectures the place where the structure value address - is found by the called function is not the same place that the - caller put it. This can be due to register windows, or it could - be because the function prologue moves it to a different place. - - If the incoming location of the structure value address is in a - register, define this macro as the register number. - -`STRUCT_VALUE_INCOMING' - If the incoming location is not a register, define - `STRUCT_VALUE_INCOMING' as an expression for an RTX for where the - called function should find the value. If it should find the - value on the stack, define this to create a `mem' which refers to - the frame pointer. A definition of 0 means that the address is - passed as an "invisible" first argument. - -`PCC_STATIC_STRUCT_RETURN' - Define this macro if the usual system convention on the target - machine for returning structures and unions is for the called - function to return the address of a static variable containing - the value. GNU CC does not normally use this convention, even if - it is the usual one, but does use it if `-fpcc-struct-value' is - specified. + A machine description has two parts: a file of instruction patterns +(`.md' file) and a C header file of macro definitions. - Do not define this if the usual system convention is for the - caller to pass an address to the subroutine. + The `.md' file for a target machine contains a pattern for each +instruction that the target machine supports (or at least each +instruction that is worth telling the compiler about). It may also +contain comments. A semicolon causes the rest of the line to be a +comment, unless the semicolon is inside a quoted string. + + See the next chapter for information on the C header file. + +* Menu: + +* Patterns:: How to write instruction patterns. +* Example:: An explained example of a `define_insn' pattern. +* RTL Template:: The RTL template defines what insns match a pattern. +* Output Template:: The output template says how to make assembler code + from such an insn. +* Output Statement:: For more generality, write C code to output + the assembler code. +* Constraints:: When not all operands are general operands. +* Standard Names:: Names mark patterns to use for code generation. +* Pattern Ordering:: When the order of patterns makes a difference. +* Dependent Patterns:: Having one pattern may make you need another. +* Jump Patterns:: Special considerations for patterns for jump insns. +* Insn Canonicalizations::Canonicalization of Instructions +* Peephole Definitions::Defining machine-specific peephole optimizations. +* Expander Definitions::Generating a sequence of several RTL insns + for a standard operation. +* Insn Splitting:: Splitting Instructions into Multiple Instructions +* Insn Attributes:: Specifying the value of attributes for generated insns.  -File: gcc.info, Node: Caller Saves, Next: Function Entry, Prev: Aggregate Return, Up: Stack and Calling +File: gcc.info, Node: Patterns, Next: Example, Up: Machine Desc + +Everything about Instruction Patterns +===================================== -Caller-Saves Register Allocation --------------------------------- + Each instruction pattern contains an incomplete RTL expression, with +pieces to be filled in later, operand constraints that restrict how the +pieces can be filled in, and an output pattern or C code to generate +the assembler output, all wrapped up in a `define_insn' expression. + + A `define_insn' is an RTL expression containing four or five +operands: + + 1. An optional name. The presence of a name indicate that this + instruction pattern can perform a certain standard job for the + RTL-generation pass of the compiler. This pass knows certain + names and will use the instruction patterns with those names, if + the names are defined in the machine description. + + The absence of a name is indicated by writing an empty string + where the name should go. Nameless instruction patterns are never + used for generating RTL code, but they may permit several simpler + insns to be combined later on. + + Names that are not thus known and used in RTL-generation have no + effect; they are equivalent to no name at all. + + 2. The "RTL template" (*note RTL Template::.) is a vector of + incomplete RTL expressions which show what the instruction should + look like. It is incomplete because it may contain + `match_operand', `match_operator', and `match_dup' expressions + that stand for operands of the instruction. + + If the vector has only one element, that element is the template + for the instruction pattern. If the vector has multiple elements, + then the instruction pattern is a `parallel' expression containing + the elements described. + + 3. A condition. This is a string which contains a C expression that + is the final test to decide whether an insn body matches this + pattern. + + For a named pattern, the condition (if present) may not depend on + the data in the insn being matched, but only the + target-machine-type flags. The compiler needs to test these + conditions during initialization in order to learn exactly which + named instructions are available in a particular run. + + For nameless patterns, the condition is applied only when matching + an individual insn, and only after the insn has matched the + pattern's recognition template. The insn's operands may be found + in the vector `operands'. + + 4. The "output template": a string that says how to output matching + insns as assembler code. `%' in this string specifies where to + substitute the value of an operand. *Note Output Template::. - If you enable it, GNU CC can save registers around function calls. -This makes it possible to use call-clobbered registers to hold -variables that must live across calls. - -`DEFAULT_CALLER_SAVES' - Define this macro if function calls on the target machine do not - preserve any registers; in other words, if `CALL_USED_REGISTERS' - has 1 for all registers. This macro enables `-fcaller-saves' by - default. Eventually that option will be enabled by default on - all machines and both the option and this macro will be - eliminated. - -`CALLER_SAVE_PROFITABLE (REFS, CALLS)' - A C expression to determine whether it is worthwhile to consider - placing a pseudo-register in a call-clobbered hard register and - saving and restoring it around each function call. The - expression should be 1 when this is worth doing, and 0 otherwise. + When simple substitution isn't general enough, you can specify a + piece of C code to compute the output. *Note Output Statement::. - If you don't define this macro, a default is used which is good - on most machines: `4 * CALLS < REFS'. + 5. Optionally, a vector containing the values of attributes for insns + matching this pattern. *Note Insn Attributes::.  -File: gcc.info, Node: Function Entry, Next: Profiling, Prev: Caller Saves, Up: Stack and Calling +File: gcc.info, Node: Example, Next: RTL Template, Prev: Patterns, Up: Machine Desc -Function Entry and Exit ------------------------ +Example of `define_insn' +======================== - This section describes the macros that output function entry -("prologue") and exit ("epilogue") code. + Here is an actual example of an instruction pattern, for the +68000/68020. -`FUNCTION_PROLOGUE (FILE, SIZE)' - A C compound statement that outputs the assembler code for entry - to a function. The prologue is responsible for setting up the - stack frame, initializing the frame pointer register, saving - registers that must be saved, and allocating SIZE additional - bytes of storage for the local variables. SIZE is an integer. - FILE is a stdio stream to which the assembler code should be - output. - - The label for the beginning of the function need not be output by - this macro. That has already been done when the macro is run. - - To determine which registers to save, the macro can refer to the - array `regs_ever_live': element R is nonzero if hard register R - is used anywhere within the function. This implies the function - prologue should save register R, provided it is not one of the - call-used registers. (`FUNCTION_EPILOGUE' must likewise use - `regs_ever_live'.) - - On machines that have "register windows", the function entry code - does not save on the stack the registers that are in the windows, - even if they are supposed to be preserved by function calls; - instead it takes appropriate steps to "push" the register stack, - if any non-call-used registers are used in the function. - - On machines where functions may or may not have frame-pointers, - the function entry code must vary accordingly; it must set up the - frame pointer if one is wanted, and not otherwise. To determine - whether a frame pointer is in wanted, the macro can refer to the - variable `frame_pointer_needed'. The variable's value will be 1 - at run time in a function that needs a frame pointer. *Note - Elimination::. - - The function entry code is responsible for allocating any stack - space required for the function. This stack space consists of - the regions listed below. In most cases, these regions are - allocated in the order listed, with the last listed region - closest to the top of the stack (the lowest address if - `STACK_GROWS_DOWNWARD' is defined, and the highest address if it - is not defined). You can use a different order for a machine if - doing so is more convenient or required for compatibility - reasons. Except in cases where required by standard or by a - debugger, there is no reason why the stack layout used by GCC - need agree with that used by other compilers for a machine. - - * A region of `current_function_pretend_args_size' bytes of - uninitialized space just underneath the first argument - arriving on the stack. (This may not be at the very start - of the allocated stack region if the calling sequence has - pushed anything else since pushing the stack arguments. But - usually, on such machines, nothing else has been pushed yet, - because the function prologue itself does all the pushing.) - This region is used on machines where an argument may be - passed partly in registers and partly in memory, and, in - some cases to support the features in `varargs.h' and - `stdargs.h'. - - * An area of memory used to save certain registers used by the - function. The size of this area, which may also include - space for such things as the return address and pointers to - previous stack frames, is machine-specific and usually - depends on which registers have been used in the function. - Machines with register windows often do not require a save - area. - - * A region of at least SIZE bytes, possibly rounded up to an - allocation boundary, to contain the local variables of the - function. On some machines, this region and the save area - may occur in the opposite order, with the save area closer - to the top of the stack. - - * Optionally, in the case that `ACCUMULATE_OUTGOING_ARGS' is - defined, a region of `current_function_outgoing_args_size' - bytes to be used for outgoing argument lists of the - function. *Note Stack Arguments::. - - Normally, it is necessary for `FUNCTION_PROLOGUE' and - `FUNCTION_EPILOGUE' to treat leaf functions specially. The C - variable `leaf_function' is nonzero for such a function. - -`EXIT_IGNORE_STACK' - Define this macro as a C expression that is nonzero if the return - instruction or the function epilogue ignores the value of the - stack pointer; in other words, if it is safe to delete an - instruction to adjust the stack pointer before a return from the - function. - - Note that this macro's value is relevant only for functions for - which frame pointers are maintained. It is never safe to delete - a final stack adjustment in a function that has no frame pointer, - and the compiler knows this regardless of `EXIT_IGNORE_STACK'. - -`FUNCTION_EPILOGUE (FILE, SIZE)' - A C compound statement that outputs the assembler code for exit - from a function. The epilogue is responsible for restoring the - saved registers and stack pointer to their values when the - function was called, and returning control to the caller. This - macro takes the same arguments as the macro `FUNCTION_PROLOGUE', - and the registers to restore are determined from `regs_ever_live' - and `CALL_USED_REGISTERS' in the same way. - - On some machines, there is a single instruction that does all the - work of returning from the function. On these machines, give that - instruction the name `return' and do not define the macro - `FUNCTION_EPILOGUE' at all. - - Do not define a pattern named `return' if you want the - `FUNCTION_EPILOGUE' to be used. If you want the target switches - to control whether return instructions or epilogues are used, - define a `return' pattern with a validity condition that tests - the target switches appropriately. If the `return' pattern's - validity condition is false, epilogues will be used. - - On machines where functions may or may not have frame-pointers, - the function exit code must vary accordingly. Sometimes the code - for these two cases is completely different. To determine - whether a frame pointer is in wanted, the macro can refer to the - variable `frame_pointer_needed'. The variable's value will be 1 - at run time in a function that needs a frame pointer. - - Normally, it is necessary for `FUNCTION_PROLOGUE' and - `FUNCTION_EPILOGUE' to treat leaf functions specially. The C - variable `leaf_function' is nonzero for such a function. *Note - Leaf Functions::. - - On some machines, some functions pop their arguments on exit while - others leave that for the caller to do. For example, the 68020 - when given `-mrtd' pops arguments in functions that take a fixed - number of arguments. - - Your definition of the macro `RETURN_POPS_ARGS' decides which - functions pop their own arguments. `FUNCTION_EPILOGUE' needs to - know what was decided. The variable `current_function_pops_args' - is the number of bytes of its arguments that a function should - pop. *Note Scalar Return::. - -`DELAY_SLOTS_FOR_EPILOGUE' - Define this macro if the function epilogue contains delay slots - to which instructions from the rest of the function can be - "moved". The definition should be a C expression whose value is - an integer representing the number of delay slots there. - -`ELIGIBLE_FOR_EPILOGUE_DELAY (INSN, N)' - A C expression that returns 1 if INSN can be placed in delay slot - number N of the epilogue. - - The argument N is an integer which identifies the delay slot now - being considered (since different slots may have different rules - of eligibility). It is never negative and is always less than - the number of epilogue delay slots (what - `DELAY_SLOTS_FOR_EPILOGUE' returns). If you reject a particular - insn for a given delay slot, in principle, it may be reconsidered - for a subsequent delay slot. Also, other insns may (at least in - principle) be considered for the so far unfilled delay slot. - - The insns accepted to fill the epilogue delay slots are put in an - RTL list made with `insn_list' objects, stored in the variable - `current_function_epilogue_delay_list'. The insn for the first - delay slot comes first in the list. Your definition of the macro - `FUNCTION_EPILOGUE' should fill the delay slots by outputting the - insns in this list, usually by calling `final_scan_insn'. + (define_insn "tstsi" + [(set (cc0) + (match_operand:SI 0 "general_operand" "rm"))] + "" + "* + { if (TARGET_68020 || ! ADDRESS_REG_P (operands[0])) + return \"tstl %0\"; + return \"cmpl #0,%0\"; }") + + This is an instruction that sets the condition codes based on the +value of a general operand. It has no condition, so any insn whose RTL +description has the form shown may be handled according to this +pattern. The name `tstsi' means "test a `SImode' value" and tells the +RTL generation pass that, when it is necessary to test such a value, an +insn to do so can be constructed using this pattern. + + The output control string is a piece of C code which chooses which +output template to return based on the kind of operand and the specific +type of CPU for which code is being generated. - You need not define this macro if you did not define - `DELAY_SLOTS_FOR_EPILOGUE'. + `"rm"' is an operand constraint. Its meaning is explained below.  -File: gcc.info, Node: Profiling, Prev: Function Entry, Up: Stack and Calling +File: gcc.info, Node: RTL Template, Next: Output Template, Prev: Example, Up: Machine Desc -Generating Code for Profiling ------------------------------ +RTL Template +============ -`FUNCTION_PROFILER (FILE, LABELNO)' - A C statement or compound statement to output to FILE some - assembler code to call the profiling subroutine `mcount'. Before - calling, the assembler code must load the address of a counter - variable into a register where `mcount' expects to find the - address. The name of this variable is `LP' followed by the - number LABELNO, so you would generate the name using `LP%d' in a - `fprintf'. - - The details of how the address should be passed to `mcount' are - determined by your operating system environment, not by GNU CC. - To figure them out, compile a small program for profiling using - the system's installed C compiler and look at the assembler code - that results. - -`PROFILE_BEFORE_PROLOGUE' - Define this macro if the code for function profiling should come - before the function prologue. Normally, the profiling code comes - after. - -`FUNCTION_BLOCK_PROFILER (FILE, LABELNO)' - A C statement or compound statement to output to FILE some - assembler code to initialize basic-block profiling for the current - object module. This code should call the subroutine - `__bb_init_func' once per object module, passing it as its sole - argument the address of a block allocated in the object module. - - The name of the block is a local symbol made with this statement: - - ASM_GENERATE_INTERNAL_LABEL (BUFFER, "LPBX", 0); - - Of course, since you are writing the definition of - `ASM_GENERATE_INTERNAL_LABEL' as well as that of this macro, you - can take a short cut in the definition of this macro and use the - name that you know will result. - - The first word of this block is a flag which will be nonzero if - the object module has already been initialized. So test this - word first, and do not call `__bb_init_func' if the flag is - nonzero. - -`BLOCK_PROFILER (FILE, BLOCKNO)' - A C statement or compound statement to increment the count - associated with the basic block number BLOCKNO. Basic blocks are - numbered separately from zero within each compilation. The count - associated with block number BLOCKNO is at index BLOCKNO in a - vector of words; the name of this array is a local symbol made - with this statement: - - ASM_GENERATE_INTERNAL_LABEL (BUFFER, "LPBX", 2); - - Of course, since you are writing the definition of - `ASM_GENERATE_INTERNAL_LABEL' as well as that of this macro, you - can take a short cut in the definition of this macro and use the - name that you know will result. + The RTL template is used to define which insns match the particular +pattern and how to find their operands. For named patterns, the RTL +template also says how to construct an insn from specified operands. + + Construction involves substituting specified operands into a copy of +the template. Matching involves determining the values that serve as +the operands in the insn being matched. Both of these activities are +controlled by special expression types that direct matching and +substitution of the operands. + +`(match_operand:M N PREDICATE CONSTRAINT)' + This expression is a placeholder for operand number N of the insn. + When constructing an insn, operand number N will be substituted + at this point. When matching an insn, whatever appears at this + position in the insn will be taken as operand number N; but it + must satisfy PREDICATE or this instruction pattern will not match + at all. + + Operand numbers must be chosen consecutively counting from zero in + each instruction pattern. There may be only one `match_operand' + expression in the pattern for each operand number. Usually + operands are numbered in the order of appearance in `match_operand' + expressions. + + PREDICATE is a string that is the name of a C function that + accepts two arguments, an expression and a machine mode. During + matching, the function will be called with the putative operand as + the expression and M as the mode argument (if M is not specified, + `VOIDmode' will be used, which normally causes PREDICATE to accept + any mode). If it returns zero, this instruction pattern fails to + match. PREDICATE may be an empty string; then it means no test is + to be done on the operand, so anything which occurs in this + position is valid. + + Most of the time, PREDICATE will reject modes other than M--but + not always. For example, the predicate `address_operand' uses M + as the mode of memory ref that the address should be valid for. + Many predicates accept `const_int' nodes even though their mode is + `VOIDmode'. + + CONSTRAINT controls reloading and the choice of the best register + class to use for a value, as explained later (*note + Constraints::.). + + People are often unclear on the difference between the constraint + and the predicate. The predicate helps decide whether a given + insn matches the pattern. The constraint plays no role in this + decision; instead, it controls various decisions in the case of an + insn which does match. + + On CISC machines, the most common PREDICATE is + `"general_operand"'. This function checks that the putative + operand is either a constant, a register or a memory reference, + and that it is valid for mode M. + + For an operand that must be a register, PREDICATE should be + `"register_operand"'. Using `"general_operand"' would be valid, + since the reload pass would copy any non-register operands through + registers, but this would make GNU CC do extra work, it would + prevent invariant operands (such as constant) from being removed + from loops, and it would prevent the register allocator from doing + the best possible job. On RISC machines, it is usually most + efficient to allow PREDICATE to accept only objects that the + constraints allow. + + For an operand that must be a constant, you must be sure to either + use `"immediate_operand"' for PREDICATE, or make the instruction + pattern's extra condition require a constant, or both. You cannot + expect the constraints to do this work! If the constraints allow + only constants, but the predicate allows something else, the + compiler will crash when that case arises. + +`(match_scratch:M N CONSTRAINT)' + This expression is also a placeholder for operand number N and + indicates that operand must be a `scratch' or `reg' expression. + + When matching patterns, this is completely equivalent to + + (match_operand:M N "scratch_operand" PRED) + + but, when generating RTL, it produces a (`scratch':M) expression. + + If the last few expressions in a `parallel' are `clobber' + expressions whose operands are either a hard register or + `match_scratch', the combiner can add them when necessary. *Note + Side Effects::. + +`(match_dup N)' + This expression is also a placeholder for operand number N. It is + used when the operand needs to appear more than once in the insn. + + In construction, `match_dup' acts just like `match_operand': the + operand is substituted into the insn being constructed. But in + matching, `match_dup' behaves differently. It assumes that operand + number N has already been determined by a `match_operand' + appearing earlier in the recognition template, and it matches only + an identical-looking expression. + +`(match_operator:M N PREDICATE [OPERANDS...])' + This pattern is a kind of placeholder for a variable RTL expression + code. + + When constructing an insn, it stands for an RTL expression whose + expression code is taken from that of operand N, and whose + operands are constructed from the patterns OPERANDS. + + When matching an expression, it matches an expression if the + function PREDICATE returns nonzero on that expression *and* the + patterns OPERANDS match the operands of the expression. + + Suppose that the function `commutative_operator' is defined as + follows, to match any expression whose operator is one of the + commutative arithmetic operators of RTL and whose mode is MODE: + + int + commutative_operator (x, mode) + rtx x; + enum machine_mode mode; + { + enum rtx_code code = GET_CODE (x); + if (GET_MODE (x) != mode) + return 0; + return (GET_RTX_CLASS (code) == 'c' + || code == EQ || code == NE); + } + + Then the following pattern will match any RTL expression consisting + of a commutative operator applied to two general operands: + + (match_operator:SI 3 "commutative_operator" + [(match_operand:SI 1 "general_operand" "g") + (match_operand:SI 2 "general_operand" "g")]) + + Here the vector `[OPERANDS...]' contains two patterns because the + expressions to be matched all contain two operands. + + When this pattern does match, the two operands of the commutative + operator are recorded as operands 1 and 2 of the insn. (This is + done by the two instances of `match_operand'.) Operand 3 of the + insn will be the entire commutative expression: use `GET_CODE + (operands[3])' to see which commutative operator was used. + + The machine mode M of `match_operator' works like that of + `match_operand': it is passed as the second argument to the + predicate function, and that function is solely responsible for + deciding whether the expression to be matched "has" that mode. + + When constructing an insn, argument 3 of the gen-function will + specify the operation (i.e. the expression code) for the + expression to be made. It should be an RTL expression, whose + expression code is copied into a new expression whose operands are + arguments 1 and 2 of the gen-function. The subexpressions of + argument 3 are not used; only its expression code matters. + + When `match_operator' is used in a pattern for matching an insn, + it usually best if the operand number of the `match_operator' is + higher than that of the actual operands of the insn. This improves + register allocation because the register allocator often looks at + operands 1 and 2 of insns to see if it can do register tying. + + There is no way to specify constraints in `match_operator'. The + operand of the insn which corresponds to the `match_operator' + never has any constraints because it is never reloaded as a whole. + However, if parts of its OPERANDS are matched by `match_operand' + patterns, those parts may have constraints of their own. + +`(match_op_dup:M N[OPERANDS...])' + Like `match_dup', except that it applies to operators instead of + operands. When constructing an insn, operand number N will be + substituted at this point. But in matching, `match_op_dup' behaves + differently. It assumes that operand number N has already been + determined by a `match_operator' appearing earlier in the + recognition template, and it matches only an identical-looking + expression. + +`(match_parallel N PREDICATE [SUBPAT...])' + This pattern is a placeholder for an insn that consists of a + `parallel' expression with a variable number of elements. This + expression should only appear at the top level of an insn pattern. + + When constructing an insn, operand number N will be substituted at + this point. When matching an insn, it matches if the body of the + insn is a `parallel' expression with at least as many elements as + the vector of SUBPAT expressions in the `match_parallel', if each + SUBPAT matches the corresponding element of the `parallel', *and* + the function PREDICATE returns nonzero on the `parallel' that is + the body of the insn. It is the responsibility of the predicate + to validate elements of the `parallel' beyond those listed in the + `match_parallel'. + + A typical use of `match_parallel' is to match load and store + multiple expressions, which can contains a variable number of + elements in a `parallel'. For example, + + (define_insn "" + [(match_parallel 0 "load_multiple_operation" + [(set (match_operand:SI 1 "gpc_reg_operand" "=r") + (match_operand:SI 2 "memory_operand" "m")) + (use (reg:SI 179)) + (clobber (reg:SI 179))])] + "" + "loadm 0,0,%1,%2") + + This example comes from `a29k.md'. The function + `load_multiple_operations' is defined in `a29k.c' and checks that + subsequent elements in the `parallel' are the same as the `set' in + the pattern, except that they are referencing subsequent registers + and memory locations. + + An insn that matches this pattern might look like: + + (parallel + [(set (reg:SI 20) (mem:SI (reg:SI 100))) + (use (reg:SI 179)) + (clobber (reg:SI 179)) + (set (reg:SI 21) + (mem:SI (plus:SI (reg:SI 100) + (const_int 4)))) + (set (reg:SI 22) + (mem:SI (plus:SI (reg:SI 100) + (const_int 8))))]) + +`(match_par_dup N [SUBPAT...])' + Like `match_op_dup', but for `match_parallel' instead of + `match_operator'. + +`(address (match_operand:M N "address_operand" ""))' + This complex of expressions is a placeholder for an operand number + N in a "load address" instruction: an operand which specifies a + memory location in the usual way, but for which the actual operand + value used is the address of the location, not the contents of the + location. + + `address' expressions never appear in RTL code, only in machine + descriptions. And they are used only in machine descriptions that + do not use the operand constraint feature. When operand + constraints are in use, the letter `p' in the constraint serves + this purpose. + + M is the machine mode of the *memory location being addressed*, + not the machine mode of the address itself. That mode is always + the same on a given target machine (it is `Pmode', which normally + is `SImode'), so there is no point in mentioning it; thus, no + machine mode is written in the `address' expression. If some day + support is added for machines in which addresses of different + kinds of objects appear differently or are used differently (such + as the PDP-10), different formats would perhaps need different + machine modes and these modes might be written in the `address' + expression.  -File: gcc.info, Node: Varargs, Next: Trampolines, Prev: Stack and Calling, Up: Machine Macros +File: gcc.info, Node: Output Template, Next: Output Statement, Prev: RTL Template, Up: Machine Desc -Implementing the Varargs Macros -=============================== +Output Templates and Operand Substitution +========================================= - GNU CC comes with an implementation of `varargs.h' and `stdarg.h' -that work without change on machines that pass arguments on the stack. - Other machines require their own implementations of varargs, and the -two machine independent header files must have conditionals to include -it. - - ANSI `stdarg.h' differs from traditional `varargs.h' mainly in the -calling convention for `va_start'. The traditional implementation -takes just one argument, which is the variable in which to store the -argument pointer. The ANSI implementation takes an additional first -argument, which is the last named argument of the function. However, -it should not use this argument. The way to find the end of the named -arguments is with the built-in functions described below. - -`__builtin_saveregs ()' - Use this built-in function to save the argument registers in - memory so that the varargs mechanism can access them. Both ANSI - and traditional versions of `va_start' must use - `__builtin_saveregs', unless you use `SETUP_INCOMING_VARARGS' - (see below) instead. - - On some machines, `__builtin_saveregs' is open-coded under the - control of the macro `EXPAND_BUILTIN_SAVEREGS'. On other - machines, it calls a routine written in assembler language, found - in `libgcc2.c'. - - Regardless of what code is generated for the call to - `__builtin_saveregs', it appears at the beginning of the function, - not where the call to `__builtin_saveregs' is written. This is - because the registers must be saved before the function starts to - use them for its own purposes. - -`__builtin_args_info (CATEGORY)' - Use this built-in function to find the first anonymous arguments - in registers. - - In general, a machine may have several categories of registers - used for arguments, each for a particular category of data types. - (For example, on some machines, floating-point registers are - used for floating-point arguments while other arguments are - passed in the general registers.) To make non-varargs functions - use the proper calling convention, you have defined the - `CUMULATIVE_ARGS' data type to record how many registers in each - category have been used so far - - `__builtin_args_info' accesses the same data structure of type - `CUMULATIVE_ARGS' after the ordinary argument layout is finished - with it, with CATEGORY specifying which word to access. Thus, the - value indicates the first unused register in a given category. - - Normally, you would use `__builtin_args_info' in the - implementation of `va_start', accessing each category just once - and storing the value in the `va_list' object. This is because - `va_list' will have to update the values, and there is no way to - alter the values accessed by `__builtin_args_info'. - -`__builtin_next_arg ()' - This is the equivalent of `__builtin_args_info', for stack - arguments. It returns the address of the first anonymous stack - argument, as type `void *'. If `ARGS_GROW_DOWNWARD', it returns - the address of the location above the first anonymous stack - argument. Use it in `va_start' to initialize the pointer for - fetching arguments from the stack. - -`__builtin_classify_type (OBJECT)' - Since each machine has its own conventions for which data types - are passed in which kind of register, your implementation of - `va_arg' has to embody these conventions. The easiest way to - categorize the specified data type is to use - `__builtin_classify_type' together with `sizeof' and - `__alignof__'. - - `__builtin_classify_type' ignores the value of OBJECT, - considering only its data type. It returns an integer describing - what kind of type that is--integer, floating, pointer, structure, - and so on. - - The file `typeclass.h' defines an enumeration that you can use to - interpret the values of `__builtin_classify_type'. - - These machine description macros help implement varargs: - -`EXPAND_BUILTIN_SAVEREGS (ARGS)' - If defined, is a C expression that produces the machine-specific - code for a call to `__builtin_saveregs'. This code will be moved - to the very beginning of the function, before any parameter - access are made. The return value of this function should be an - RTX that contains the value to use as the return of - `__builtin_saveregs'. - - The argument ARGS is a `tree_list' containing the arguments that - were passed to `__builtin_saveregs'. - - If this macro is not defined, the compiler will output an ordinary - call to the library function `__builtin_saveregs'. - -`SETUP_INCOMING_VARARGS (ARGS_SO_FAR, MODE, TYPE, PRETEND_ARGS_SIZE, SECOND_TIME)' - This macro offers an alternative to using `__builtin_saveregs' and - defining the macro `EXPAND_BUILTIN_SAVEREGS'. Use it to store the - anonymous register arguments into the stack so that all the - arguments appear to have been passed consecutively on the stack. - Once this is done, you can use the standard implementation of - varargs that works for machines that pass all their arguments on - the stack. - - The argument ARGS_SO_FAR is the `CUMULATIVE_ARGS' data structure, - containing the values that obtain after processing of the named - arguments. The arguments MODE and TYPE describe the last named - argument--its machine mode and its data type as a tree node. - - The macro implementation should do two things: first, push onto - the stack all the argument registers *not* used for the named - arguments, and second, store the size of the data thus pushed - into the `int'-valued variable whose name is supplied as the - argument PRETEND_ARGS_SIZE. The value that you store here will - serve as additional offset for setting up the stack frame. - - Because you must generate code to push the anonymous arguments at - compile time without knowing their data types, - `SETUP_INCOMING_VARARGS' is only useful on machines that have just - a single category of argument register and use it uniformly for - all data types. - - If the argument SECOND_TIME is nonzero, it means that the - arguments of the function are being analyzed for the second time. - This happens for an inline function, which is not actually - compiled until the end of the source file. The macro - `SETUP_INCOMING_VARARGS' should not generate any instructions in - this case. + The "output template" is a string which specifies how to output the +assembler code for an instruction pattern. Most of the template is a +fixed string which is output literally. The character `%' is used to +specify where to substitute an operand; it can also be used to identify +places where different variants of the assembler require different +syntax. + + In the simplest case, a `%' followed by a digit N says to output +operand N at that point in the string. + + `%' followed by a letter and a digit says to output an operand in an +alternate fashion. Four letters have standard, built-in meanings +described below. The machine description macro `PRINT_OPERAND' can +define additional letters with nonstandard meanings. + + `%cDIGIT' can be used to substitute an operand that is a constant +value without the syntax that normally indicates an immediate operand. + + `%nDIGIT' is like `%cDIGIT' except that the value of the constant is +negated before printing. + + `%aDIGIT' can be used to substitute an operand as if it were a +memory reference, with the actual operand treated as the address. This +may be useful when outputting a "load address" instruction, because +often the assembler syntax for such an instruction requires you to +write the operand as if it were a memory reference. + + `%lDIGIT' is used to substitute a `label_ref' into a jump +instruction. + + `%=' outputs a number which is unique to each instruction in the +entire compilation. This is useful for making local labels to be +referred to more than once in a single template that generates multiple +assembler instructions. + + `%' followed by a punctuation character specifies a substitution that +does not use an operand. Only one case is standard: `%%' outputs a `%' +into the assembler code. Other nonstandard cases can be defined in the +`PRINT_OPERAND' macro. You must also define which punctuation +characters are valid with the `PRINT_OPERAND_PUNCT_VALID_P' macro. + + The template may generate multiple assembler instructions. Write +the text for the instructions, with `\;' between them. + + When the RTL contains two operands which are required by constraint +to match each other, the output template must refer only to the +lower-numbered operand. Matching operands are not always identical, +and the rest of the compiler arranges to put the proper RTL expression +for printing into the lower-numbered operand. + + One use of nonstandard letters or punctuation following `%' is to +distinguish between different assembler languages for the same machine; +for example, Motorola syntax versus MIT syntax for the 68000. Motorola +syntax requires periods in most opcode names, while MIT syntax does +not. For example, the opcode `movel' in MIT syntax is `move.l' in +Motorola syntax. The same file of patterns is used for both kinds of +output syntax, but the character sequence `%.' is used in each place +where Motorola syntax wants a period. The `PRINT_OPERAND' macro for +Motorola syntax defines the sequence to output a period; the macro for +MIT syntax defines it to do nothing. + + As a special case, a template consisting of the single character `#' +instructs the compiler to first split the insn, and then output the +resulting instructions separately. This helps eliminate redundancy in +the output templates. If you have a `define_insn' that needs to emit +multiple assembler instructions, and there is an matching `define_split' +already defined, then you can simply use `#' as the output template +instead of writing an output template that emits the multiple assembler +instructions. + + If `ASSEMBLER_DIALECT' is defined, you can use +`{option0|option1|option2}' constructs in the templates. These +describe multiple variants of assembler language syntax. *Note +Instruction Output::. - \ No newline at end of file