--- gcc/gcc.info-10 2018/04/24 17:51:21 1.1.1.1 +++ gcc/gcc.info-10 2018/04/24 17:51:58 1.1.1.2 @@ -1,4 +1,4 @@ -This is Info file gcc.info, produced by Makeinfo-1.43 from the input +This is Info file gcc.info, produced by Makeinfo-1.44 from the input file gcc.texi. This file documents the use and the internals of the GNU compiler. @@ -24,6 +24,452 @@ approved by the Free Software Foundation English.  +File: gcc.info, Node: Simple Constraints, Next: Multi-Alternative, Prev: Constraints, Up: Constraints + +Simple Constraints +------------------ + + The simplest kind of constraint is a string full of letters, each of +which describes one kind of operand that is permitted. Here are the +letters that are allowed: + +`m' + A memory operand is allowed, with any kind of address that the + machine supports in general. + +`o' + A memory operand is allowed, but only if the address is + "offsettable". This means that adding a small integer (actually, + the width in bytes of the operand, as determined by its machine + mode) may be added to the address and the result is also a valid + memory address. + + For example, an address which is constant is offsettable; so is an + address that is the sum of a register and a constant (as long as a + slightly larger constant is also within the range of + address-offsets supported by the machine); but an autoincrement + or autodecrement address is not offsettable. More complicated + indirect/indexed addresses may or may not be offsettable + depending on the other addressing modes that the machine supports. + + Note that in an output operand which can be matched by another + operand, the constraint letter `o' is valid only when accompanied + by both `<' (if the target machine has predecrement addressing) + and `>' (if the target machine has preincrement addressing). + +`V' + A memory operand that is not offsettable. In other words, + anything that would fit the `m' constraint but not the `o' + constraint. + +`<' + A memory operand with autodecrement addressing (either + predecrement or postdecrement) is allowed. + +`>' + A memory operand with autoincrement addressing (either + preincrement or postincrement) is allowed. + +`r' + A register operand is allowed provided that it is in a general + register. + +`d', `a', `f', ... + Other letters can be defined in machine-dependent fashion to + stand for particular classes of registers. `d', `a' and `f' are + defined on the 68000/68020 to stand for data, address and floating + point registers. + +`i' + An immediate integer operand (one with constant value) is allowed. + This includes symbolic constants whose values will be known only + at assembly time. + +`n' + An immediate integer operand with a known numeric value is + allowed. Many systems cannot support assembly-time constants for + operands less than a word wide. Constraints for these operands + should use `n' rather than `i'. + +`I', `J', `K', ... `P' + Other letters in the range `I' through `P' may be defined in a + machine-dependent fashion to permit immediate integer operands + with explicit integer values in specified ranges. For example, + on the 68000, `I' is defined to stand for the range of values 1 + to 8. This is the range permitted as a shift count in the shift + instructions. + +`E' + An immediate floating operand (expression code `const_double') is + allowed, but only if the target floating point format is the same + as that of the host machine (on which the compiler is running). + +`F' + An immediate floating operand (expression code `const_double') is + allowed. + +`G', `H' + `G' and `H' may be defined in a machine-dependent fashion to + permit immediate floating operands in particular ranges of values. + +`s' + An immediate integer operand whose value is not an explicit + integer is allowed. + + This might appear strange; if an insn allows a constant operand + with a value not known at compile time, it certainly must allow + any known value. So why use `s' instead of `i'? Sometimes it + allows better code to be generated. + + For example, on the 68000 in a fullword instruction it is + possible to use an immediate operand; but if the immediate value + is between -128 and 127, better code results from loading the + value into a register and using the register. This is because + the load into the register can be done with a `moveq' + instruction. We arrange for this to happen by defining the + letter `K' to mean "any integer outside the range -128 to 127", + and then specifying `Ks' in the operand constraints. + +`g' + Any register, memory or immediate integer operand is allowed, + except for registers that are not general registers. + +`X' + Any operand whatsoever is allowed, even if it does not satisfy + `general_operand'. This is normally used in the constraint of a + `match_scratch' when certain alternatives will not actually + require a scratch register. + +`0', `1', `2', ... `9' + An operand that matches the specified operand number is allowed. + If a digit is used together with letters within the same + alternative, the digit should come last. + + This is called a "matching constraint" and what it really means is + that the assembler has only a single operand that fills two roles + considered separate in the RTL insn. For example, an add insn + has two input operands and one output operand in the RTL, but on + most machines an add instruction really has only two operands, + one of them an input-output operand. + + Matching constraints work only in circumstances like that add + insn. More precisely, the two operands that match must include + one input-only operand and one output-only operand. Moreover, + the digit must be a smaller number than the number of the operand + that uses it in the constraint. + + For operands to match in a particular case usually means that they + are identical-looking RTL expressions. But in a few special cases + specific kinds of dissimilarity are allowed. For example, `*x' + as an input operand will match `*x++' as an output operand. For + proper results in such cases, the output template should always + use the output-operand's number when printing the operand. + +`p' + An operand that is a valid memory address is allowed. This is + for "load address" and "push address" instructions. + + `p' in the constraint must be accompanied by `address_operand' as + the predicate in the `match_operand'. This predicate interprets + the mode specified in the `match_operand' as the mode of the + memory reference for which the address would be valid. + +`Q', `R', `S', ... `U' + Letters in the range `Q' through `U' may be defined in a + machine-dependent fashion to stand for arbitrary operand types. + The machine description macro `EXTRA_CONSTRAINT' is passed the + operand as its first argument and the constraint letter as its + second operand. + + A typical use for this would be to distinguish certain types of + memory references that affect other insn operands. + + Do not define these constraint letters to accept register + references (`reg'); the reload pass does not expect this and + would not handle it properly. + + In order to have valid assembler code, each operand must satisfy +its constraint. But a failure to do so does not prevent the pattern +from applying to an insn. Instead, it directs the compiler to modify +the code so that the constraint will be satisfied. Usually this is +done by copying an operand into a register. + + Contrast, therefore, the two instruction patterns that follow: + + (define_insn "" + [(set (match_operand:SI 0 "general_operand" "r") + (plus:SI (match_dup 0) + (match_operand:SI 1 "general_operand" "r")))] + "" + "...") + +which has two operands, one of which must appear in two places, and + + (define_insn "" + [(set (match_operand:SI 0 "general_operand" "r") + (plus:SI (match_operand:SI 1 "general_operand" "0") + (match_operand:SI 2 "general_operand" "r")))] + "" + "...") + +which has three operands, two of which are required by a constraint to +be identical. If we are considering an insn of the form + + (insn N PREV NEXT + (set (reg:SI 3) + (plus:SI (reg:SI 6) (reg:SI 109))) + ...) + +the first pattern would not apply at all, because this insn does not +contain two identical subexpressions in the right place. The pattern +would say, "That does not look like an add instruction; try other +patterns." The second pattern would say, "Yes, that's an add +instruction, but there is something wrong with it." It would direct +the reload pass of the compiler to generate additional insns to make +the constraint true. The results might look like this: + + (insn N2 PREV N + (set (reg:SI 3) (reg:SI 6)) + ...) + + (insn N N2 NEXT + (set (reg:SI 3) + (plus:SI (reg:SI 3) (reg:SI 109))) + ...) + + It is up to you to make sure that each operand, in each pattern, has +constraints that can handle any RTL expression that could be present +for that operand. (When multiple alternatives are in use, each +pattern must, for each possible combination of operand expressions, +have at least one alternative which can handle that combination of +operands.) The constraints don't need to *allow* any possible +operand--when this is the case, they do not constrain--but they must +at least point the way to reloading any possible operand so that it +will fit. + + * If the constraint accepts whatever operands the predicate permits, + there is no problem: reloading is never necessary for this + operand. + + For example, an operand whose constraints permit everything except + registers is safe provided its predicate rejects registers. + + An operand whose predicate accepts only constant values is safe + provided its constraints include the letter `i'. If any possible + constant value is accepted, then nothing less than `i' will do; + if the predicate is more selective, then the constraints may also + be more selective. + + * Any operand expression can be reloaded by copying it into a + register. So if an operand's constraints allow some kind of + register, it is certain to be safe. It need not permit all + classes of registers; the compiler knows how to copy a register + into another register of the proper class in order to make an + instruction valid. + + * A nonoffsettable memory reference can be reloaded by copying the + address into a register. So if the constraint uses the letter + `o', all memory references are taken care of. + + * A constant operand can be reloaded by allocating space in memory + to hold it as preinitialized data. Then the memory reference can + be used in place of the constant. So if the constraint uses the + letters `o' or `m', constant operands are not a problem. + + * If the constraint permits a constant and a pseudo register used + in an insn was not allocated to a hard register and is equivalent + to a constant, the register will be replaced with the constant. + If the predicate does not permit a constant and the insn is + re-recognized for some reason, the compiler will crash. Thus the + predicate must always recognize any objects allowed by the + constraint. + + If the operand's predicate can recognize registers, but the +constraint does not permit them, it can make the compiler crash. When +this operand happens to be a register, the reload pass will be +stymied, because it does not know how to copy a register temporarily +into memory. + + +File: gcc.info, Node: Multi-Alternative, Next: Class Preferences, Prev: Simple Constraints, Up: Constraints + +Multiple Alternative Constraints +-------------------------------- + + Sometimes a single instruction has multiple alternative sets of +possible operands. For example, on the 68000, a logical-or +instruction can combine register or an immediate value into memory, or +it can combine any kind of operand into a register; but it cannot +combine one memory location into another. + + These constraints are represented as multiple alternatives. An +alternative can be described by a series of letters for each operand. +The overall constraint for an operand is made from the letters for +this operand from the first alternative, a comma, the letters for this +operand from the second alternative, a comma, and so on until the last +alternative. Here is how it is done for fullword logical-or on the +68000: + + (define_insn "iorsi3" + [(set (match_operand:SI 0 "general_operand" "=m,d") + (ior:SI (match_operand:SI 1 "general_operand" "%0,0") + (match_operand:SI 2 "general_operand" "dKs,dmKs")))] + ...) + + The first alternative has `m' (memory) for operand 0, `0' for +operand 1 (meaning it must match operand 0), and `dKs' for operand 2. +The second alternative has `d' (data register) for operand 0, `0' for +operand 1, and `dmKs' for operand 2. The `=' and `%' in the +constraints apply to all the alternatives; their meaning is explained +in the next section (*note Class Preferences::.). + + If all the operands fit any one alternative, the instruction is +valid. Otherwise, for each alternative, the compiler counts how many +instructions must be added to copy the operands so that that +alternative applies. The alternative requiring the least copying is +chosen. If two alternatives need the same amount of copying, the one +that comes first is chosen. These choices can be altered with the `?' +and `!' characters: + +`?' + Disparage slightly the alternative that the `?' appears in, as a + choice when no alternative applies exactly. The compiler regards + this alternative as one unit more costly for each `?' that appears + in it. + +`!' + Disparage severely the alternative that the `!' appears in. This + alternative can still be used if it fits without reloading, but + if reloading is needed, some other alternative will be used. + + When an insn pattern has multiple alternatives in its constraints, +often the appearance of the assembler code is determined mostly by +which alternative was matched. When this is so, the C code for +writing the assembler code can use the variable `which_alternative', +which is the ordinal number of the alternative that was actually +satisfied (0 for the first, 1 for the second alternative, etc.). +*Note Output Statement::. + + +File: gcc.info, Node: Class Preferences, Next: Modifiers, Prev: Multi-Alternative, Up: Constraints + +Register Class Preferences +-------------------------- + + The operand constraints have another function: they enable the +compiler to decide which kind of hardware register a pseudo register +is best allocated to. The compiler examines the constraints that +apply to the insns that use the pseudo register, looking for the +machine-dependent letters such as `d' and `a' that specify classes of +registers. The pseudo register is put in whichever class gets the +most "votes". The constraint letters `g' and `r' also vote: they vote +in favor of a general register. The machine description says which +registers are considered general. + + Of course, on some machines all registers are equivalent, and no +register classes are defined. Then none of this complexity is +relevant. + + +File: gcc.info, Node: Modifiers, Next: No Constraints, Prev: Class Preferences, Up: Constraints + +Constraint Modifier Characters +------------------------------ + +`=' + Means that this operand is write-only for this instruction: the + previous value is discarded and replaced by output data. + +`+' + Means that this operand is both read and written by the + instruction. + + When the compiler fixes up the operands to satisfy the + constraints, it needs to know which operands are inputs to the + instruction and which are outputs from it. `=' identifies an + output; `+' identifies an operand that is both input and output; + all other operands are assumed to be input only. + +`&' + Means (in a particular alternative) that this operand is written + before the instruction is finished using the input operands. + Therefore, this operand may not lie in a register that is used as + an input operand or as part of any memory address. + + `&' applies only to the alternative in which it is written. In + constraints with multiple alternatives, sometimes one alternative + requires `&' while others do not. See, for example, the `movdf' + insn of the 68000. + + `&' does not obviate the need to write `='. + +`%' + Declares the instruction to be commutative for this operand and + the following operand. This means that the compiler may + interchange the two operands if that is the cheapest way to make + all operands fit the constraints. This is often used in patterns + for addition instructions that really have only two operands: the + result must go in one of the arguments. Here for example, is how + the 68000 halfword-add instruction is defined: + + (define_insn "addhi3" + [(set (match_operand:HI 0 "general_operand" "=m,r") + (plus:HI (match_operand:HI 1 "general_operand" "%0,0") + (match_operand:HI 2 "general_operand" "di,g")))] + ...) + +`#' + Says that all following characters, up to the next comma, are to + be ignored as a constraint. They are significant only for + choosing register preferences. + +`*' + Says that the following character should be ignored when choosing + register preferences. `*' has no effect on the meaning of the + constraint as a constraint, and no effect on reloading. + + Here is an example: the 68000 has an instruction to sign-extend a + halfword in a data register, and can also sign-extend a value by + copying it into an address register. While either kind of + register is acceptable, the constraints on an address-register + destination are less strict, so it is best if register allocation + makes an address register its goal. Therefore, `*' is used so + that the `d' constraint letter (for data register) is ignored + when computing register preferences. + + (define_insn "extendhisi2" + [(set (match_operand:SI 0 "general_operand" "=*d,a") + (sign_extend:SI + (match_operand:HI 1 "general_operand" "0,g")))] + ...) + + +File: gcc.info, Node: No Constraints, Prev: Modifiers, Up: Constraints + +Not Using Constraints +--------------------- + + Some machines are so clean that operand constraints are not +required. For example, on the Vax, an operand valid in one context is +valid in any other context. On such a machine, every operand +constraint would be `g', excepting only operands of "load address" +instructions which are written as if they referred to a memory +location's contents but actual refer to its address. They would have +constraint `p'. + + For such machines, instead of writing `g' and `p' for all the +constraints, you can choose to write a description with empty +constraints. Then you write `""' for the constraint in every +`match_operand'. Address operands are identified by writing an +`address' expression around the `match_operand', not by their +constraints. + + When the machine description has just empty constraints, certain +parts of compilation are skipped, making the compiler faster. However, +few machines actually do not need constraints; all machine descriptions +now in existence use constraints. + + File: gcc.info, Node: Standard Names, Next: Pattern Ordering, Prev: Constraints, Up: Machine Desc Standard Names for Patterns Used in Generation @@ -707,414 +1153,4 @@ the Sparc discussed above, we have the p The `SELECT_CC_MODE' macro on the Sparc returns `CC_NOOVmode' for comparisons whose argument is a `plus'. - -File: gcc.info, Node: Insn Canonicalizations, Next: Peephole Definitions, Prev: Jump Patterns, Up: Machine Desc - -Canonicalization of Instructions -================================ - - There are often cases where multiple RTL expressions could -represent an operation peformed by a single machine instruction. This -situation is most commonly encountered with logical, branch, and -multiply-accumulate instructions. In such cases, the compiler -attempts to convert these multiple RTL expressions into a single -canonical form to reduce the number of insn patterns required. - - In addition to algebraic simplifications, following -canonicalizations are performed: - - * For commutative and comparison operators, a constant is always - made the second operand. If a machine only supports a constant - as the second operand, only patterns that match a constant in the - second operand need be supplied. - - For these operators, if only one operand is a `neg', `not', - `mult', `plus', or `minus' expression, it will be the first - operand. - - * For the `compare' operator, a constant is always the second - operand on machines where `cc0' is used (*note Jump Patterns::.). - On other machines, there are rare cases where the compiler might - want to construct a `compare' with a constant as the first - operand. However, these cases are not common enough for it to be - worthwhile to provide a pattern matching a constant as the first - operand unless the machine actually has such an instruction. - - An operand of `neg', `not', `mult', `plus', or `minus' is made - the first operand under the same conditions as above. - - * `(minus X (const_int N))' is converted to `(plus X (const_int - -N))'. - - * Within address computations (i.e., inside `mem'), a left shift is - converted into the appropriate multiplication by a power of two. - - De`Morgan's Law is used to move bitwise negation inside a bitwise - logical-and or logical-or operation. If this results in only one - operand being a `not' expression, it will be the first one. - - A machine that has an instruction that performs a bitwise - logical-and of one operand with the bitwise negation of the other - should specify the pattern for that instruction as - - (define_insn "" - [(set (match_operand:M 0 ...) - (and:M (not:M (match_operand:M 1 ...)) - (match_operand:M 2 ...)))] - "..." - "...") - - Similarly, a pattern for a "NAND" instruction should be written - - (define_insn "" - [(set (match_operand:M 0 ...) - (ior:M (not:M (match_operand:M 1 ...)) - (not:M (match_operand:M 2 ...))))] - "..." - "...") - - In both cases, it is not necessary to include patterns for the - many logically equivalent RTL expressions. - - * The only possible RTL expressions involving both bitwise - exclusive-or and bitwise negation are `(xor:M X) Y)' and `(not:M - (xor:M X Y))'. - - * The sum of three items, one of which is a constant, will only - appear in the form - - (plus:M (plus:M X Y) CONSTANT) - - * On machines that do not use `cc0', `(compare X (const_int 0))' - will be converted to X. - - * Equality comparisons of a group of bits (usually a single bit) - with zero will be written using `zero_extract' rather than the - equivalent `and' or `sign_extract' operations. - - -File: gcc.info, Node: Peephole Definitions, Next: Expander Definitions, Prev: Insn Canonicalizations, Up: Machine Desc - -Defining Machine-Specific Peephole Optimizers -============================================= - - In addition to instruction patterns the `md' file may contain -definitions of machine-specific peephole optimizations. - - The combiner does not notice certain peephole optimizations when -the data flow in the program does not suggest that it should try them. - For example, sometimes two consecutive insns related in purpose can -be combined even though the second one does not appear to use a -register computed in the first one. A machine-specific peephole -optimizer can detect such opportunities. - - A definition looks like this: - - (define_peephole - [INSN-PATTERN-1 - INSN-PATTERN-2 - ...] - "CONDITION" - "TEMPLATE" - "OPTIONAL INSN-ATTRIBUTES") - -The last string operand may be omitted if you are not using any -machine-specific information in this machine description. If present, -it must obey the same rules as in a `define_insn'. - - In this skeleton, INSN-PATTERN-1 and so on are patterns to match -consecutive insns. The optimization applies to a sequence of insns -when INSN-PATTERN-1 matches the first one, INSN-PATTERN-2 matches the -next, and so on. - - Each of the insns matched by a peephole must also match a -`define_insn'. Peepholes are checked only at the last stage just -before code generation, and only optionally. Therefore, any insn which -would match a peephole but no `define_insn' will cause a crash in code -generation in an unoptimized compilation, or at various optimization -stages. - - The operands of the insns are matched with `match_operands', -`match_operator', and `match_dup', as usual. What is not usual is -that the operand numbers apply to all the insn patterns in the -definition. So, you can check for identical operands in two insns by -using `match_operand' in one insn and `match_dup' in the other. - - The operand constraints used in `match_operand' patterns do not have -any direct effect on the applicability of the peephole, but they will -be validated afterward, so make sure your constraints are general -enough to apply whenever the peephole matches. If the peephole matches -but the constraints are not satisfied, the compiler will crash. - - It is safe to omit constraints in all the operands of the peephole; -or you can write constraints which serve as a double-check on the -criteria previously tested. - - Once a sequence of insns matches the patterns, the CONDITION is -checked. This is a C expression which makes the final decision -whether to perform the optimization (we do so if the expression is -nonzero). If CONDITION is omitted (in other words, the string is -empty) then the optimization is applied to every sequence of insns -that matches the patterns. - - The defined peephole optimizations are applied after register -allocation is complete. Therefore, the peephole definition can check -which operands have ended up in which kinds of registers, just by -looking at the operands. - - The way to refer to the operands in CONDITION is to write -`operands[I]' for operand number I (as matched by `(match_operand I -...)'). Use the variable `insn' to refer to the last of the insns -being matched; use `prev_nonnote_insn' to find the preceding insns. - - When optimizing computations with intermediate results, you can use -CONDITION to match only when the intermediate results are not used -elsewhere. Use the C expression `dead_or_set_p (INSN, OP)', where -INSN is the insn in which you expect the value to be used for the last -time (from the value of `insn', together with use of -`prev_nonnote_insn'), and OP is the intermediate value (from -`operands[I]'). - - Applying the optimization means replacing the sequence of insns -with one new insn. The TEMPLATE controls ultimate output of assembler -code for this combined insn. It works exactly like the template of a -`define_insn'. Operand numbers in this template are the same ones -used in matching the original sequence of insns. - - The result of a defined peephole optimizer does not need to match -any of the insn patterns in the machine description; it does not even -have an opportunity to match them. The peephole optimizer definition -itself serves as the insn pattern to control how the insn is output. - - Defined peephole optimizers are run as assembler code is being -output, so the insns they produce are never combined or rearranged in -any way. - - Here is an example, taken from the 68000 machine description: - - (define_peephole - [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4))) - (set (match_operand:DF 0 "register_operand" "f") - (match_operand:DF 1 "register_operand" "ad"))] - "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])" - "* - { - rtx xoperands[2]; - xoperands[1] = gen_rtx (REG, SImode, REGNO (operands[1]) + 1); - #ifdef MOTOROLA - output_asm_insn (\"move.l %1,(sp)\", xoperands); - output_asm_insn (\"move.l %1,-(sp)\", operands); - return \"fmove.d (sp)+,%0\"; - #else - output_asm_insn (\"movel %1,sp@\", xoperands); - output_asm_insn (\"movel %1,sp@-\", operands); - return \"fmoved sp@+,%0\"; - #endif - } - ") - - The effect of this optimization is to change - - jbsr _foobar - addql #4,sp - movel d1,sp@- - movel d0,sp@- - fmoved sp@+,fp0 - -into - - jbsr _foobar - movel d1,sp@ - movel d0,sp@- - fmoved sp@+,fp0 - - INSN-PATTERN-1 and so on look *almost* like the second operand of -`define_insn'. There is one important difference: the second operand -of `define_insn' consists of one or more RTX's enclosed in square -brackets. Usually, there is only one: then the same action can be -written as an element of a `define_peephole'. But when there are -multiple actions in a `define_insn', they are implicitly enclosed in a -`parallel'. Then you must explicitly write the `parallel', and the -square brackets within it, in the `define_peephole'. Thus, if an insn -pattern looks like this, - - (define_insn "divmodsi4" - [(set (match_operand:SI 0 "general_operand" "=d") - (div:SI (match_operand:SI 1 "general_operand" "0") - (match_operand:SI 2 "general_operand" "dmsK"))) - (set (match_operand:SI 3 "general_operand" "=d") - (mod:SI (match_dup 1) (match_dup 2)))] - "TARGET_68020" - "divsl%.l %2,%3:%0") - -then the way to mention this insn in a peephole is as follows: - - (define_peephole - [... - (parallel - [(set (match_operand:SI 0 "general_operand" "=d") - (div:SI (match_operand:SI 1 "general_operand" "0") - (match_operand:SI 2 "general_operand" "dmsK"))) - (set (match_operand:SI 3 "general_operand" "=d") - (mod:SI (match_dup 1) (match_dup 2)))]) - ...] - ...) - - -File: gcc.info, Node: Expander Definitions, Next: Insn Splitting, Prev: Peephole Definitions, Up: Machine Desc - -Defining RTL Sequences for Code Generation -========================================== - - On some target machines, some standard pattern names for RTL -generation cannot be handled with single insn, but a sequence of RTL -insns can represent them. For these target machines, you can write a -`define_expand' to specify how to generate the sequence of RTL. - - A `define_expand' is an RTL expression that looks almost like a -`define_insn'; but, unlike the latter, a `define_expand' is used only -for RTL generation and it can produce more than one RTL insn. - - A `define_expand' RTX has four operands: - - * The name. Each `define_expand' must have a name, since the only - use for it is to refer to it by name. - - * The RTL template. This is just like the RTL template for a - `define_peephole' in that it is a vector of RTL expressions each - being one insn. - - * The condition, a string containing a C expression. This - expression is used to express how the availability of this - pattern depends on subclasses of target machine, selected by - command-line options when GNU CC is run. This is just like the - condition of a `define_insn' that has a standard name. - - * The preparation statements, a string containing zero or more C - statements which are to be executed before RTL code is generated - from the RTL template. - - Usually these statements prepare temporary registers for use as - internal operands in the RTL template, but they can also generate - RTL insns directly by calling routines such as `emit_insn', etc. - Any such insns precede the ones that come from the RTL template. - - Every RTL insn emitted by a `define_expand' must match some -`define_insn' in the machine description. Otherwise, the compiler -will crash when trying to generate code for the insn or trying to -optimize it. - - The RTL template, in addition to controlling generation of RTL -insns, also describes the operands that need to be specified when this -pattern is used. In particular, it gives a predicate for each operand. - - A true operand, which needs to be specified in order to generate -RTL from the pattern, should be described with a `match_operand' in -its first occurrence in the RTL template. This enters information on -the operand's predicate into the tables that record such things. GNU -CC uses the information to preload the operand into a register if that -is required for valid RTL code. If the operand is referred to more -than once, subsequent references should use `match_dup'. - - The RTL template may also refer to internal "operands" which are -temporary registers or labels used only within the sequence made by the -`define_expand'. Internal operands are substituted into the RTL -template with `match_dup', never with `match_operand'. The values of -the internal operands are not passed in as arguments by the compiler -when it requests use of this pattern. Instead, they are computed -within the pattern, in the preparation statements. These statements -compute the values and store them into the appropriate elements of -`operands' so that `match_dup' can find them. - - There are two special macros defined for use in the preparation -statements: `DONE' and `FAIL'. Use them with a following semicolon, -as a statement. - -`DONE' - Use the `DONE' macro to end RTL generation for the pattern. The - only RTL insns resulting from the pattern on this occasion will be - those already emitted by explicit calls to `emit_insn' within the - preparation statements; the RTL template will not be generated. - -`FAIL' - Make the pattern fail on this occasion. When a pattern fails, it - means that the pattern was not truly available. The calling - routines in the compiler will try other strategies for code - generation using other patterns. - - Failure is currently supported only for binary (addition, - multiplication, shifting, etc.) and bitfield (`extv', `extzv', - and `insv') operations. - - Here is an example, the definition of left-shift for the SPUR chip: - - (define_expand "ashlsi3" - [(set (match_operand:SI 0 "register_operand" "") - (ashift:SI - (match_operand:SI 1 "register_operand" "") - (match_operand:SI 2 "nonmemory_operand" "")))] - "" - " - { - if (GET_CODE (operands[2]) != CONST_INT - || (unsigned) INTVAL (operands[2]) > 3) - FAIL; - }") - -This example uses `define_expand' so that it can generate an RTL insn -for shifting when the shift-count is in the supported range of 0 to 3 -but fail in other cases where machine insns aren't available. When it -fails, the compiler tries another strategy using different patterns -(such as, a library call). - - If the compiler were able to handle nontrivial condition-strings in -patterns with names, then it would be possible to use a `define_insn' -in that case. Here is another case (zero-extension on the 68000) -which makes more use of the power of `define_expand': - - (define_expand "zero_extendhisi2" - [(set (match_operand:SI 0 "general_operand" "") - (const_int 0)) - (set (strict_low_part - (subreg:HI - (match_dup 0) - 0)) - (match_operand:HI 1 "general_operand" ""))] - "" - "operands[1] = make_safe_from (operands[1], operands[0]);") - -Here two RTL insns are generated, one to clear the entire output -operand and the other to copy the input operand into its low half. -This sequence is incorrect if the input operand refers to [the old -value of] the output operand, so the preparation statement makes sure -this isn't so. The function `make_safe_from' copies the `operands[1]' -into a temporary register if it refers to `operands[0]'. It does this -by emitting another RTL insn. - - Finally, a third example shows the use of an internal operand. -Zero-extension on the SPUR chip is done by `and'-ing the result -against a halfword mask. But this mask cannot be represented by a -`const_int' because the constant value is too large to be legitimate -on this machine. So it must be copied into a register with -`force_reg' and then the register used in the `and'. - - (define_expand "zero_extendhisi2" - [(set (match_operand:SI 0 "register_operand" "") - (and:SI (subreg:SI - (match_operand:HI 1 "register_operand" "") - 0) - (match_dup 2)))] - "" - "operands[2] - = force_reg (SImode, gen_rtx (CONST_INT, - VOIDmode, 65535)); ") - - *Note:* If the `define_expand' is used to serve a standard binary -or unary arithmetic operation or a bitfield operation, then the last -insn it generates must not be a `code_label', `barrier' or `note'. It -must be an `insn', `jump_insn' or `call_insn'. If you don't need a -real insn at the end, emit an insn to copy the result of the operation -into itself. Such an insn will generate no code, but it can avoid -problems in the compiler. -  \ No newline at end of file