X-Git-Url: https://oss.titaniummirror.com/gitweb?a=blobdiff_plain;f=gcc%2Fdoc%2Fgccint.info-2;fp=gcc%2Fdoc%2Fgccint.info-2;h=354ae9050204012dd52999f6046ac667e3f4cfaf;hb=5a5369932a08c074943c94407697a5813002fd31;hp=7628f8f47b6f8ad3b704c2eff7b57cde85b4e810;hpb=aaf7afc53d3ed4f6c811f6ec493d857ea0459573;p=msp430-gcc.git diff --git a/gcc/doc/gccint.info-2 b/gcc/doc/gccint.info-2 index 7628f8f4..354ae905 100644 --- a/gcc/doc/gccint.info-2 +++ b/gcc/doc/gccint.info-2 @@ -1,4 +1,4 @@ -This is doc/gccint.info, produced by makeinfo version 4.5 from +This is doc/gccint.info, produced by makeinfo version 4.11 from doc/gccint.texi. INFO-DIR-SECTION Programming @@ -33,938 +33,7107 @@ software. Copies published by the Free Software Foundation raise funds for GNU development.  -File: gccint.info, Node: Back End, Prev: Front End, Up: gcc Directory +File: gccint.info, Node: Patterns, Next: Example, Prev: Overview, Up: Machine Desc + +9.2 Everything about Instruction Patterns +========================================= + +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. + + For the purpose of debugging the compiler, you may also specify a + name beginning with the `*' character. Such a name is used only + for identifying the instruction in RTL dumps; it is entirely + equivalent to having a nameless pattern for all other purposes. + + 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'. For an insn where the condition has + once matched, it can't be used to control register allocation, for + example by excluding certain hard registers or hard register + combinations. + + 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::. + + When simple substitution isn't general enough, you can specify a + piece of C code to compute the output. *Note Output Statement::. + + 5. Optionally, a vector containing the values of attributes for insns + matching this pattern. *Note Insn Attributes::. -Anatomy of a Target Back End ----------------------------- + +File: gccint.info, Node: Example, Next: RTL Template, Prev: Patterns, Up: Machine Desc + +9.3 Example of `define_insn' +============================ + +Here is an actual example of an instruction pattern, for the +68000/68020. + + (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 can also be written using braced strings: + + (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. + + `"rm"' is an operand constraint. Its meaning is explained below. + + +File: gccint.info, Node: RTL Template, Next: Output Template, Prev: Example, Up: Machine Desc + +9.4 RTL Template +================ + +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. In the case of a `define_expand', any operand numbers + used only in `match_dup' expressions have higher values than all + other operand numbers. + + 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 GCC 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 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 or delete 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. + + Note that `match_dup' should not be used to tell the compiler that + a particular register is being used for two operands (example: + `add' that adds one register to another; the second register is + both an input operand and the output operand). Use a matching + constraint (*note Simple Constraints::) for those. `match_dup' is + for the cases where one operand is used in two places in the + template, such as an instruction that computes both a quotient and + a remainder, where the opcode takes two input operands but the RTL + template has to refer to each of those twice; once for the + quotient pattern and once for the remainder pattern. + +`(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 contain 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_operation' 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'. + +`(match_insn PREDICATE)' + Match a complete insn. Unlike the other `match_*' recognizers, + `match_insn' does not take an operand number. + + The machine mode M of `match_insn' 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. + +`(match_insn2 N PREDICATE)' + Match a complete insn. + + The machine mode M of `match_insn2' 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. + + + +File: gccint.info, Node: Output Template, Next: Output Statement, Prev: RTL Template, Up: Machine Desc + +9.5 Output Templates and Operand Substitution +============================================= + +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 the macro `ASSEMBLER_DIALECT' is defined, you can use construct +of the form `{option0|option1|option2}' in the templates. These +describe multiple variants of assembler language syntax. *Note +Instruction Output::. + + +File: gccint.info, Node: Output Statement, Next: Constraints, Prev: Output Template, Up: Machine Desc + +9.6 C Statements for Assembler Output +===================================== + +Often a single fixed template string cannot produce correct and +efficient assembler code for all the cases that are recognized by a +single instruction pattern. For example, the opcodes may depend on the +kinds of operands; or some unfortunate combinations of operands may +require extra machine instructions. + + If the output control string starts with a `@', then it is actually +a series of templates, each on a separate line. (Blank lines and +leading spaces and tabs are ignored.) The templates correspond to the +pattern's constraint alternatives (*note Multi-Alternative::). For +example, if a target machine has a two-address add instruction `addr' +to add into a register and another `addm' to add a register to memory, +you might write this pattern: + + (define_insn "addsi3" + [(set (match_operand:SI 0 "general_operand" "=r,m") + (plus:SI (match_operand:SI 1 "general_operand" "0,0") + (match_operand:SI 2 "general_operand" "g,r")))] + "" + "@ + addr %2,%0 + addm %2,%0") + + If the output control string starts with a `*', then it is not an +output template but rather a piece of C program that should compute a +template. It should execute a `return' statement to return the +template-string you want. Most such templates use C string literals, +which require doublequote characters to delimit them. To include these +doublequote characters in the string, prefix each one with `\'. + + If the output control string is written as a brace block instead of a +double-quoted string, it is automatically assumed to be C code. In that +case, it is not necessary to put in a leading asterisk, or to escape the +doublequotes surrounding C string literals. + + The operands may be found in the array `operands', whose C data type +is `rtx []'. + + It is very common to select different ways of generating assembler +code based on whether an immediate operand is within a certain range. +Be careful when doing this, because the result of `INTVAL' is an +integer on the host machine. If the host machine has more bits in an +`int' than the target machine has in the mode in which the constant +will be used, then some of the bits you get from `INTVAL' will be +superfluous. For proper results, you must carefully disregard the +values of those bits. + + It is possible to output an assembler instruction and then go on to +output or compute more of them, using the subroutine `output_asm_insn'. +This receives two arguments: a template-string and a vector of +operands. The vector may be `operands', or it may be another array of +`rtx' that you declare locally and initialize yourself. + + 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 can test +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.). + + For example, suppose there are two opcodes for storing zero, `clrreg' +for registers and `clrmem' for memory locations. Here is how a pattern +could use `which_alternative' to choose between them: + + (define_insn "" + [(set (match_operand:SI 0 "general_operand" "=r,m") + (const_int 0))] + "" + { + return (which_alternative == 0 + ? "clrreg %0" : "clrmem %0"); + }) + + The example above, where the assembler code to generate was _solely_ +determined by the alternative, could also have been specified as +follows, having the output control string start with a `@': + + (define_insn "" + [(set (match_operand:SI 0 "general_operand" "=r,m") + (const_int 0))] + "" + "@ + clrreg %0 + clrmem %0") + + +File: gccint.info, Node: Constraints, Next: Standard Names, Prev: Output Statement, Up: Machine Desc + +9.7 Operand Constraints +======================= + +Each `match_operand' in an instruction pattern can specify a constraint +for the type of operands allowed. Constraints can say whether an +operand may be in a register, and which kinds of register; whether the +operand can be a memory reference, and which kinds of address; whether +the operand may be an immediate constant, and which possible values it +may have. Constraints can also require two operands to match. + +* Menu: + +* Simple Constraints:: Basic use of constraints. +* Multi-Alternative:: When an insn has two alternative constraint-patterns. +* Class Preferences:: Constraints guide which hard register to put things in. +* Modifiers:: More precise control over effects of constraints. +* Machine Constraints:: Existing constraints for some particular machines. + + +File: gccint.info, Node: Simple Constraints, Next: Multi-Alternative, Up: Constraints + +9.7.1 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: + +whitespace + Whitespace characters are ignored and can be inserted at any + position except the first. This enables each alternative for + different operands to be visually aligned in the machine + description even if they have different number of constraints and + modifiers. + +`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. + +`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 number is allowed to be more than a single digit. If multiple + digits are encountered consecutavely, they are interpreted as a + single decimal integer. There is scant chance for ambiguity, + since to-date it has never been desirable that `10' be interpreted + as matching either operand 1 _or_ operand 0. Should this be + desired, one can use multiple alternatives instead. + + 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 + CISC machines an add instruction really has only two operands, one + of them an input-output operand: + + addl #35,r12 + + Matching constraints are used in these circumstances. 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. + +OTHER-LETTERS + Other letters can be defined in machine-dependent fashion to stand + for particular classes of registers or other arbitrary operand + types. `d', `a' and `f' are defined on the 68000/68020 to stand + for data, address and floating point registers. + + The machine description macro `REG_CLASS_FROM_LETTER' has first + cut at the otherwise unused letters. If it evaluates to `NO_REGS', + then `EXTRA_CONSTRAINT' is evaluated. + + A typical use for `EXTRA_CONSTRANT' would be to distinguish certain + types of memory references that affect other insn operands. + + 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. + + If the predicate accepts a unary operator, the constraint applies to +the operand. For example, the MIPS processor at ISA level 3 supports an +instruction which adds two registers in `SImode' to produce a `DImode' +result, but only if the registers are correctly sign extended. This +predicate for the input operands accepts a `sign_extend' of an `SImode' +register. Write the constraint to indicate the type of register that +is required for the operand of the `sign_extend'. + + +File: gccint.info, Node: Multi-Alternative, Next: Class Preferences, Prev: Simple Constraints, Up: Constraints + +9.7.2 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: gccint.info, Node: Class Preferences, Next: Modifiers, Prev: Multi-Alternative, Up: Constraints + +9.7.3 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: gccint.info, Node: Modifiers, Next: Machine Constraints, Prev: Class Preferences, Up: Constraints + +9.7.4 Constraint Modifier Characters +------------------------------------ + +Here are 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. + + If you specify `=' or `+' in a constraint, you put it in the first + character of the constraint string. + +`&' + Means (in a particular alternative) that this operand is an + "earlyclobber" operand, which is modified 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. + + An input operand can be tied to an earlyclobber operand if its only + use as an input occurs before the early result is written. Adding + alternatives of this form often allows GCC to produce better code + when only some of the inputs can be affected by the earlyclobber. + See, for example, the `mulsi3' insn of the ARM. + + `&' 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: gccint.info, Node: Machine Constraints, Prev: Modifiers, Up: Constraints + +9.7.5 Constraints for Particular Machines +----------------------------------------- + +Whenever possible, you should use the general-purpose constraint letters +in `asm' arguments, since they will convey meaning more readily to +people reading your code. Failing that, use the constraint letters +that usually have very similar meanings across architectures. The most +commonly used constraints are `m' and `r' (for memory and +general-purpose registers respectively; *note Simple Constraints::), and +`I', usually the letter indicating the most common immediate-constant +format. + + For each machine architecture, the `config/MACHINE/MACHINE.h' file +defines additional constraints. These constraints are used by the +compiler itself for instruction generation, as well as for `asm' +statements; therefore, some of the constraints are not particularly +interesting for `asm'. The constraints are defined through these +macros: + +`REG_CLASS_FROM_LETTER' + Register class constraints (usually lower case). + +`CONST_OK_FOR_LETTER_P' + Immediate constant constraints, for non-floating point constants of + word size or smaller precision (usually upper case). + +`CONST_DOUBLE_OK_FOR_LETTER_P' + Immediate constant constraints, for all floating point constants + and for constants of greater than word size precision (usually + upper case). + +`EXTRA_CONSTRAINT' + Special cases of registers or memory. This macro is not required, + and is only defined for some machines. + + Inspecting these macro definitions in the compiler source for your +machine is the best way to be certain you have the right constraints. +However, here is a summary of the machine-dependent constraints +available on some particular machines. + +_ARM family--`arm.h'_ + + `f' + Floating-point register + + `F' + One of the floating-point constants 0.0, 0.5, 1.0, 2.0, 3.0, + 4.0, 5.0 or 10.0 + + `G' + Floating-point constant that would satisfy the constraint `F' + if it were negated + + `I' + Integer that is valid as an immediate operand in a data + processing instruction. That is, an integer in the range 0 + to 255 rotated by a multiple of 2 + + `J' + Integer in the range -4095 to 4095 + + `K' + Integer that satisfies constraint `I' when inverted (ones + complement) + + `L' + Integer that satisfies constraint `I' when negated (twos + complement) + + `M' + Integer in the range 0 to 32 + + `Q' + A memory reference where the exact address is in a single + register (``m'' is preferable for `asm' statements) + + `R' + An item in the constant pool + + `S' + A symbol in the text segment of the current file + +_AMD 29000 family--`a29k.h'_ + + `l' + Local register 0 + + `b' + Byte Pointer (`BP') register + + `q' + `Q' register + + `h' + Special purpose register + + `A' + First accumulator register + + `a' + Other accumulator register + + `f' + Floating point register + + `I' + Constant greater than 0, less than 0x100 + + `J' + Constant greater than 0, less than 0x10000 + + `K' + Constant whose high 24 bits are on (1) + + `L' + 16-bit constant whose high 8 bits are on (1) + + `M' + 32-bit constant whose high 16 bits are on (1) + + `N' + 32-bit negative constant that fits in 8 bits + + `O' + The constant 0x80000000 or, on the 29050, any 32-bit constant + whose low 16 bits are 0. + + `P' + 16-bit negative constant that fits in 8 bits + + `G' + `H' + A floating point constant (in `asm' statements, use the + machine independent `E' or `F' instead) + +_AVR family--`avr.h'_ + + `l' + Registers from r0 to r15 + + `a' + Registers from r16 to r23 + + `d' + Registers from r16 to r31 + + `w' + Registers from r24 to r31. These registers can be used in + `adiw' command + + `e' + Pointer register (r26-r31) + + `b' + Base pointer register (r28-r31) + + `q' + Stack pointer register (SPH:SPL) + + `t' + Temporary register r0 + + `x' + Register pair X (r27:r26) + + `y' + Register pair Y (r29:r28) + + `z' + Register pair Z (r31:r30) + + `I' + Constant greater than -1, less than 64 + + `J' + Constant greater than -64, less than 1 + + `K' + Constant integer 2 + + `L' + Constant integer 0 + + `M' + Constant that fits in 8 bits + + `N' + Constant integer -1 + + `O' + Constant integer 8, 16, or 24 + + `P' + Constant integer 1 + + `G' + A floating point constant 0.0 + +_IBM RS6000--`rs6000.h'_ + + `b' + Address base register + + `f' + Floating point register + + `h' + `MQ', `CTR', or `LINK' register + + `q' + `MQ' register + + `c' + `CTR' register + + `l' + `LINK' register + + `x' + `CR' register (condition register) number 0 + + `y' + `CR' register (condition register) + + `z' + `FPMEM' stack memory for FPR-GPR transfers + + `I' + Signed 16-bit constant + + `J' + Unsigned 16-bit constant shifted left 16 bits (use `L' + instead for `SImode' constants) + + `K' + Unsigned 16-bit constant + + `L' + Signed 16-bit constant shifted left 16 bits + + `M' + Constant larger than 31 + + `N' + Exact power of 2 + + `O' + Zero + + `P' + Constant whose negation is a signed 16-bit constant + + `G' + Floating point constant that can be loaded into a register + with one instruction per word + + `Q' + Memory operand that is an offset from a register (`m' is + preferable for `asm' statements) + + `R' + AIX TOC entry + + `S' + Constant suitable as a 64-bit mask operand + + `T' + Constant suitable as a 32-bit mask operand + + `U' + System V Release 4 small data area reference + +_Intel 386--`i386.h'_ + + `q' + `a', `b', `c', or `d' register for the i386. For x86-64 it + is equivalent to `r' class. (for 8-bit instructions that do + not use upper halves) + + `Q' + `a', `b', `c', or `d' register. (for 8-bit instructions, that + do use upper halves) + + `R' + Legacy register--equivalent to `r' class in i386 mode. (for + non-8-bit registers used together with 8-bit upper halves in + a single instruction) + + `A' + Specifies the `a' or `d' registers. This is primarily useful + for 64-bit integer values (when in 32-bit mode) intended to + be returned with the `d' register holding the most + significant bits and the `a' register holding the least + significant bits. + + `f' + Floating point register + + `t' + First (top of stack) floating point register + + `u' + Second floating point register + + `a' + `a' register + + `b' + `b' register + + `c' + `c' register + + `d' + `d' register + + `D' + `di' register + + `S' + `si' register + + `x' + `xmm' SSE register + + `y' + MMX register + + `I' + Constant in range 0 to 31 (for 32-bit shifts) + + `J' + Constant in range 0 to 63 (for 64-bit shifts) + + `K' + `0xff' + + `L' + `0xffff' + + `M' + 0, 1, 2, or 3 (shifts for `lea' instruction) + + `N' + Constant in range 0 to 255 (for `out' instruction) + + `Z' + Constant in range 0 to `0xffffffff' or symbolic reference + known to fit specified range. (for using immediates in zero + extending 32-bit to 64-bit x86-64 instructions) + + `e' + Constant in range -2147483648 to 2147483647 or symbolic + reference known to fit specified range. (for using + immediates in 64-bit x86-64 instructions) + + `G' + Standard 80387 floating point constant + +_Intel 960--`i960.h'_ + + `f' + Floating point register (`fp0' to `fp3') + + `l' + Local register (`r0' to `r15') + + `b' + Global register (`g0' to `g15') + + `d' + Any local or global register + + `I' + Integers from 0 to 31 + + `J' + 0 + + `K' + Integers from -31 to 0 + + `G' + Floating point 0 + + `H' + Floating point 1 + +_MIPS--`mips.h'_ + + `d' + General-purpose integer register + + `f' + Floating-point register (if available) + + `h' + `Hi' register + + `l' + `Lo' register + + `x' + `Hi' or `Lo' register + + `y' + General-purpose integer register + + `z' + Floating-point status register + + `I' + Signed 16-bit constant (for arithmetic instructions) + + `J' + Zero + + `K' + Zero-extended 16-bit constant (for logic instructions) + + `L' + Constant with low 16 bits zero (can be loaded with `lui') + + `M' + 32-bit constant which requires two instructions to load (a + constant which is not `I', `K', or `L') + + `N' + Negative 16-bit constant + + `O' + Exact power of two + + `P' + Positive 16-bit constant + + `G' + Floating point zero + + `Q' + Memory reference that can be loaded with more than one + instruction (`m' is preferable for `asm' statements) + + `R' + Memory reference that can be loaded with one instruction (`m' + is preferable for `asm' statements) + + `S' + Memory reference in external OSF/rose PIC format (`m' is + preferable for `asm' statements) + +_Motorola 680x0--`m68k.h'_ + + `a' + Address register + + `d' + Data register + + `f' + 68881 floating-point register, if available + + `x' + Sun FPA (floating-point) register, if available + + `y' + First 16 Sun FPA registers, if available + + `I' + Integer in the range 1 to 8 + + `J' + 16-bit signed number + + `K' + Signed number whose magnitude is greater than 0x80 + + `L' + Integer in the range -8 to -1 + + `M' + Signed number whose magnitude is greater than 0x100 + + `G' + Floating point constant that is not a 68881 constant + + `H' + Floating point constant that can be used by Sun FPA + +_Motorola 68HC11 & 68HC12 families--`m68hc11.h'_ + + `a' + Register 'a' + + `b' + Register 'b' + + `d' + Register 'd' + + `q' + An 8-bit register + + `t' + Temporary soft register _.tmp + + `u' + A soft register _.d1 to _.d31 + + `w' + Stack pointer register + + `x' + Register 'x' + + `y' + Register 'y' + + `z' + Pseudo register 'z' (replaced by 'x' or 'y' at the end) + + `A' + An address register: x, y or z + + `B' + An address register: x or y + + `D' + Register pair (x:d) to form a 32-bit value + + `L' + Constants in the range -65536 to 65535 + + `M' + Constants whose 16-bit low part is zero + + `N' + Constant integer 1 or -1 + + `O' + Constant integer 16 + + `P' + Constants in the range -8 to 2 + + +_SPARC--`sparc.h'_ + + `f' + Floating-point register that can hold 32- or 64-bit values. + + `e' + Floating-point register that can hold 64- or 128-bit values. + + `I' + Signed 13-bit constant + + `J' + Zero + + `K' + 32-bit constant with the low 12 bits clear (a constant that + can be loaded with the `sethi' instruction) + + `L' + A constant in the range supported by `movcc' instructions + + `M' + A constant in the range supported by `movrcc' instructions + + `N' + Same as `K', except that it verifies that bits that are not + in the lower 32-bit range are all zero. Must be used instead + of `K' for modes wider than `SImode' + + `G' + Floating-point zero + + `H' + Signed 13-bit constant, sign-extended to 32 or 64 bits + + `Q' + Floating-point constant whose integral representation can be + moved into an integer register using a single sethi + instruction + + `R' + Floating-point constant whose integral representation can be + moved into an integer register using a single mov instruction + + `S' + Floating-point constant whose integral representation can be + moved into an integer register using a high/lo_sum + instruction sequence + + `T' + Memory address aligned to an 8-byte boundary + + `U' + Even register + + `W' + Memory address for `e' constraint registers. + + +_TMS320C3x/C4x--`c4x.h'_ + + `a' + Auxiliary (address) register (ar0-ar7) + + `b' + Stack pointer register (sp) + + `c' + Standard (32-bit) precision integer register + + `f' + Extended (40-bit) precision register (r0-r11) + + `k' + Block count register (bk) + + `q' + Extended (40-bit) precision low register (r0-r7) + + `t' + Extended (40-bit) precision register (r0-r1) + + `u' + Extended (40-bit) precision register (r2-r3) + + `v' + Repeat count register (rc) - A back end for a target architecture in GCC has the following parts: + `x' + Index register (ir0-ir1) - * A directory `MACHINE' under `gcc/config', containing a machine - description `MACHINE.md' file (*note Machine Descriptions: Machine - Desc.), header files `MACHINE.h' and `MACHINE-protos.h' and a - source file `MACHINE.c' (*note Target Description Macros and - Functions: Target Macros.), possibly a target Makefile fragment - `t-MACHINE' (*note The Target Makefile Fragment: Target - Fragment.), and maybe some other files. The names of these files - may be changed from the defaults given by explicit specifications - in `config.gcc'. + `y' + Status (condition code) register (st) - * Entries in `config.gcc' (*note The `config.gcc' File: System - Config.) for the systems with this target architecture. + `z' + Data page register (dp) - * Documentation in `gcc/doc/invoke.texi' for any command-line - options supported by this target (*note Run-time Target - Specification: Run-time Target.). This means both entries in the - summary table of options and details of the individual options. + `G' + Floating-point zero - * Documentation in `gcc/doc/extend.texi' for any target-specific - attributes supported (*note Defining target-specific uses of - `__attribute__': Target Attributes.), including where the same - attribute is already supported on some targets, which are - enumerated in the manual. + `H' + Immediate 16-bit floating-point constant - * Documentation in `gcc/doc/extend.texi' for any target-specific - pragmas supported. + `I' + Signed 16-bit constant - * Documentation in `gcc/doc/extend.texi' of any target-specific - built-in functions supported. + `J' + Signed 8-bit constant - * Documentation in `gcc/doc/md.texi' of any target-specific - constraint letters (*note Constraints for Particular Machines: - Machine Constraints.). + `K' + Signed 5-bit constant - * A note in `gcc/doc/contrib.texi' under the person or people who - contributed the target support. + `L' + Unsigned 16-bit constant - * Entries in `gcc/doc/install.texi' for all target triplets - supported with this target architecture, giving details of any - special notes about installation for this target, or saying that - there are no special notes if there are none. + `M' + Unsigned 8-bit constant - * Possibly other support outside the `gcc' directory for runtime - libraries. FIXME: reference docs for this. The libstdc++ porting - manual needs to be installed as info for this to work, or to be a - chapter of this manual. + `N' + Ones complement of unsigned 16-bit constant - If the back end is added to the official GCC CVS repository, the -following are also necessary: + `O' + High 16-bit constant (32-bit constant with 16 LSBs zero) - * An entry for the target architecture in `readings.html' on the GCC - web site, with any relevant links. + `Q' + Indirect memory reference with signed 8-bit or index register + displacement - * A news item about the contribution of support for that target - architecture, in `index.html' on the GCC web site. + `R' + Indirect memory reference with unsigned 5-bit displacement - * Normally, one or more maintainers of that target listed in - `MAINTAINERS'. Some existing architectures may be unmaintained, - but it would be unusual to add support for a target that does not - have a maintainer when support is added. + `S' + Indirect memory reference with 1 bit or index register + displacement + + `T' + Direct memory reference + + `U' + Symbolic address + + +_S/390 and zSeries--`s390.h'_ + + `a' + Address register (general purpose register except r0) + + `d' + Data register (arbitrary general purpose register) + + `f' + Floating-point register + + `I' + Unsigned 8-bit constant (0-255) + + `J' + Unsigned 12-bit constant (0-4095) + + `K' + Signed 16-bit constant (-32768-32767) + + `L' + Unsigned 16-bit constant (0-65535) + + `Q' + Memory reference without index register + + `S' + Symbolic constant suitable for use with the `larl' instruction + + +_Xstormy16--`stormy16.h'_ + + `a' + Register r0. + + `b' + Register r1. + + `c' + Register r2. + + `d' + Register r8. + + `e' + Registers r0 through r7. + + `t' + Registers r0 and r1. + + `y' + The carry register. + + `z' + Registers r8 and r9. + + `I' + A constant between 0 and 3 inclusive. + + `J' + A constant that has exactly one bit set. + + `K' + A constant that has exactly one bit clear. + + `L' + A constant between 0 and 255 inclusive. + + `M' + A constant between -255 and 0 inclusive. + + `N' + A constant between -3 and 0 inclusive. + + `O' + A constant between 1 and 4 inclusive. + + `P' + A constant between -4 and -1 inclusive. + + `Q' + A memory reference that is a stack push. + + `R' + A memory reference that is a stack pop. + + `S' + A memory reference that refers to an constant address of + known value. + + `T' + The register indicated by Rx (not implemented yet). + + `U' + A constant that is not between 2 and 15 inclusive. + + +_Xtensa--`xtensa.h'_ + + `a' + General-purpose 32-bit register + + `b' + One-bit boolean register + + `A' + MAC16 40-bit accumulator register + + `I' + Signed 12-bit integer constant, for use in MOVI instructions + + `J' + Signed 8-bit integer constant, for use in ADDI instructions + + `K' + Integer constant valid for BccI instructions + + `L' + Unsigned constant valid for BccUI instructions + + + + +File: gccint.info, Node: Standard Names, Next: Pattern Ordering, Prev: Constraints, Up: Machine Desc + +9.8 Standard Pattern Names For Generation +========================================= + +Here is a table of the instruction names that are meaningful in the RTL +generation pass of the compiler. Giving one of these names to an +instruction pattern tells the RTL generation pass that it can use the +pattern to accomplish a certain task. + +`movM' + Here M stands for a two-letter machine mode name, in lower case. + This instruction pattern moves data with that machine mode from + operand 1 to operand 0. For example, `movsi' moves full-word data. + + If operand 0 is a `subreg' with mode M of a register whose own + mode is wider than M, the effect of this instruction is to store + the specified value in the part of the register that corresponds + to mode M. Bits outside of M, but which are within the same + target word as the `subreg' are undefined. Bits which are outside + the target word are left unchanged. + + This class of patterns is special in several ways. First of all, + each of these names up to and including full word size _must_ be + defined, because there is no other way to copy a datum from one + place to another. If there are patterns accepting operands in + larger modes, `movM' must be defined for integer modes of those + sizes. + + Second, these patterns are not used solely in the RTL generation + pass. Even the reload pass can generate move insns to copy values + from stack slots into temporary registers. When it does so, one + of the operands is a hard register and the other is an operand + that can need to be reloaded into a register. + + Therefore, when given such a pair of operands, the pattern must + generate RTL which needs no reloading and needs no temporary + registers--no registers other than the operands. For example, if + you support the pattern with a `define_expand', then in such a + case the `define_expand' mustn't call `force_reg' or any other such + function which might generate new pseudo registers. + + This requirement exists even for subword modes on a RISC machine + where fetching those modes from memory normally requires several + insns and some temporary registers. + + During reload a memory reference with an invalid address may be + passed as an operand. Such an address will be replaced with a + valid address later in the reload pass. In this case, nothing may + be done with the address except to use it as it stands. If it is + copied, it will not be replaced with a valid address. No attempt + should be made to make such an address into a valid address and no + routine (such as `change_address') that will do so may be called. + Note that `general_operand' will fail when applied to such an + address. + + The global variable `reload_in_progress' (which must be explicitly + declared if required) can be used to determine whether such special + handling is required. + + The variety of operands that have reloads depends on the rest of + the machine description, but typically on a RISC machine these can + only be pseudo registers that did not get hard registers, while on + other machines explicit memory references will get optional + reloads. + + If a scratch register is required to move an object to or from + memory, it can be allocated using `gen_reg_rtx' prior to life + analysis. + + If there are cases which need scratch registers during or after + reload, you must define `SECONDARY_INPUT_RELOAD_CLASS' and/or + `SECONDARY_OUTPUT_RELOAD_CLASS' to detect them, and provide + patterns `reload_inM' or `reload_outM' to handle them. *Note + Register Classes::. + + The global variable `no_new_pseudos' can be used to determine if it + is unsafe to create new pseudo registers. If this variable is + nonzero, then it is unsafe to call `gen_reg_rtx' to allocate a new + pseudo. + + The constraints on a `movM' must permit moving any hard register + to any other hard register provided that `HARD_REGNO_MODE_OK' + permits mode M in both registers and `REGISTER_MOVE_COST' applied + to their classes returns a value of 2. + + It is obligatory to support floating point `movM' instructions + into and out of any registers that can hold fixed point values, + because unions and structures (which have modes `SImode' or + `DImode') can be in those registers and they may have floating + point members. + + There may also be a need to support fixed point `movM' + instructions in and out of floating point registers. + Unfortunately, I have forgotten why this was so, and I don't know + whether it is still true. If `HARD_REGNO_MODE_OK' rejects fixed + point values in floating point registers, then the constraints of + the fixed point `movM' instructions must be designed to avoid ever + trying to reload into a floating point register. + +`reload_inM' +`reload_outM' + Like `movM', but used when a scratch register is required to move + between operand 0 and operand 1. Operand 2 describes the scratch + register. See the discussion of the `SECONDARY_RELOAD_CLASS' + macro in *note Register Classes::. + + There are special restrictions on the form of the `match_operand's + used in these patterns. First, only the predicate for the reload + operand is examined, i.e., `reload_in' examines operand 1, but not + the predicates for operand 0 or 2. Second, there may be only one + alternative in the constraints. Third, only a single register + class letter may be used for the constraint; subsequent constraint + letters are ignored. As a special exception, an empty constraint + string matches the `ALL_REGS' register class. This may relieve + ports of the burden of defining an `ALL_REGS' constraint letter + just for these patterns. + +`movstrictM' + Like `movM' except that if operand 0 is a `subreg' with mode M of + a register whose natural mode is wider, the `movstrictM' + instruction is guaranteed not to alter any of the register except + the part which belongs to mode M. + +`load_multiple' + Load several consecutive memory locations into consecutive + registers. Operand 0 is the first of the consecutive registers, + operand 1 is the first memory location, and operand 2 is a + constant: the number of consecutive registers. + + Define this only if the target machine really has such an + instruction; do not define this if the most efficient way of + loading consecutive registers from memory is to do them one at a + time. + + On some machines, there are restrictions as to which consecutive + registers can be stored into memory, such as particular starting or + ending register numbers or only a range of valid counts. For those + machines, use a `define_expand' (*note Expander Definitions::) and + make the pattern fail if the restrictions are not met. + + Write the generated insn as a `parallel' with elements being a + `set' of one register from the appropriate memory location (you may + also need `use' or `clobber' elements). Use a `match_parallel' + (*note RTL Template::) to recognize the insn. See `a29k.md' and + `rs6000.md' for examples of the use of this insn pattern. + +`store_multiple' + Similar to `load_multiple', but store several consecutive registers + into consecutive memory locations. Operand 0 is the first of the + consecutive memory locations, operand 1 is the first register, and + operand 2 is a constant: the number of consecutive registers. + +`pushM' + Output an push instruction. Operand 0 is value to push. Used + only when `PUSH_ROUNDING' is defined. For historical reason, this + pattern may be missing and in such case an `mov' expander is used + instead, with a `MEM' expression forming the push operation. The + `mov' expander method is deprecated. + +`addM3' + Add operand 2 and operand 1, storing the result in operand 0. All + operands must have mode M. This can be used even on two-address + machines, by means of constraints requiring operands 1 and 0 to be + the same location. + +`subM3', `mulM3' +`divM3', `udivM3', `modM3', `umodM3' +`sminM3', `smaxM3', `uminM3', `umaxM3' +`andM3', `iorM3', `xorM3' + Similar, for other arithmetic operations. + +`minM3', `maxM3' + Floating point min and max operations. If both operands are zeros, + or if either operand is NaN, then it is unspecified which of the + two operands is returned as the result. + +`mulhisi3' + Multiply operands 1 and 2, which have mode `HImode', and store a + `SImode' product in operand 0. + +`mulqihi3', `mulsidi3' + Similar widening-multiplication instructions of other widths. + +`umulqihi3', `umulhisi3', `umulsidi3' + Similar widening-multiplication instructions that do unsigned + multiplication. + +`smulM3_highpart' + Perform a signed multiplication of operands 1 and 2, which have + mode M, and store the most significant half of the product in + operand 0. The least significant half of the product is discarded. + +`umulM3_highpart' + Similar, but the multiplication is unsigned. + +`divmodM4' + Signed division that produces both a quotient and a remainder. + Operand 1 is divided by operand 2 to produce a quotient stored in + operand 0 and a remainder stored in operand 3. + + For machines with an instruction that produces both a quotient and + a remainder, provide a pattern for `divmodM4' but do not provide + patterns for `divM3' and `modM3'. This allows optimization in the + relatively common case when both the quotient and remainder are + computed. + + If an instruction that just produces a quotient or just a remainder + exists and is more efficient than the instruction that produces + both, write the output routine of `divmodM4' to call + `find_reg_note' and look for a `REG_UNUSED' note on the quotient + or remainder and generate the appropriate instruction. + +`udivmodM4' + Similar, but does unsigned division. + +`ashlM3' + Arithmetic-shift operand 1 left by a number of bits specified by + operand 2, and store the result in operand 0. Here M is the mode + of operand 0 and operand 1; operand 2's mode is specified by the + instruction pattern, and the compiler will convert the operand to + that mode before generating the instruction. + +`ashrM3', `lshrM3', `rotlM3', `rotrM3' + Other shift and rotate instructions, analogous to the `ashlM3' + instructions. + +`negM2' + Negate operand 1 and store the result in operand 0. + +`absM2' + Store the absolute value of operand 1 into operand 0. + +`sqrtM2' + Store the square root of operand 1 into operand 0. + + The `sqrt' built-in function of C always uses the mode which + corresponds to the C data type `double'. + +`ffsM2' + Store into operand 0 one plus the index of the least significant + 1-bit of operand 1. If operand 1 is zero, store zero. M is the + mode of operand 0; operand 1's mode is specified by the instruction + pattern, and the compiler will convert the operand to that mode + before generating the instruction. + + The `ffs' built-in function of C always uses the mode which + corresponds to the C data type `int'. + +`one_cmplM2' + Store the bitwise-complement of operand 1 into operand 0. + +`cmpM' + Compare operand 0 and operand 1, and set the condition codes. The + RTL pattern should look like this: + + (set (cc0) (compare (match_operand:M 0 ...) + (match_operand:M 1 ...))) + +`tstM' + Compare operand 0 against zero, and set the condition codes. The + RTL pattern should look like this: + + (set (cc0) (match_operand:M 0 ...)) + + `tstM' patterns should not be defined for machines that do not use + `(cc0)'. Doing so would confuse the optimizer since it would no + longer be clear which `set' operations were comparisons. The + `cmpM' patterns should be used instead. + +`movstrM' + Block move instruction. The addresses of the destination and + source strings are the first two operands, and both are in mode + `Pmode'. + + The number of bytes to move is the third operand, in mode M. + Usually, you specify `word_mode' for M. However, if you can + generate better code knowing the range of valid lengths is smaller + than those representable in a full word, you should provide a + pattern with a mode corresponding to the range of values you can + handle efficiently (e.g., `QImode' for values in the range 0-127; + note we avoid numbers that appear negative) and also a pattern + with `word_mode'. + + The fourth operand is the known shared alignment of the source and + destination, in the form of a `const_int' rtx. Thus, if the + compiler knows that both source and destination are word-aligned, + it may provide the value 4 for this operand. + + Descriptions of multiple `movstrM' patterns can only be beneficial + if the patterns for smaller modes have fewer restrictions on their + first, second and fourth operands. Note that the mode M in + `movstrM' does not impose any restriction on the mode of + individually moved data units in the block. + + These patterns need not give special consideration to the + possibility that the source and destination strings might overlap. + +`clrstrM' + Block clear instruction. The addresses of the destination string + is the first operand, in mode `Pmode'. The number of bytes to + clear is the second operand, in mode M. See `movstrM' for a + discussion of the choice of mode. + + The third operand is the known alignment of the destination, in + the form of a `const_int' rtx. Thus, if the compiler knows that + the destination is word-aligned, it may provide the value 4 for + this operand. + + The use for multiple `clrstrM' is as for `movstrM'. + +`cmpstrM' + Block compare instruction, with five operands. Operand 0 is the + output; it has mode M. The remaining four operands are like the + operands of `movstrM'. The two memory blocks specified are + compared byte by byte in lexicographic order. The effect of the + instruction is to store a value in operand 0 whose sign indicates + the result of the comparison. + +`strlenM' + Compute the length of a string, with three operands. Operand 0 is + the result (of mode M), operand 1 is a `mem' referring to the + first character of the string, operand 2 is the character to + search for (normally zero), and operand 3 is a constant describing + the known alignment of the beginning of the string. + +`floatMN2' + Convert signed integer operand 1 (valid for fixed point mode M) to + floating point mode N and store in operand 0 (which has mode N). + +`floatunsMN2' + Convert unsigned integer operand 1 (valid for fixed point mode M) + to floating point mode N and store in operand 0 (which has mode N). + +`fixMN2' + Convert operand 1 (valid for floating point mode M) to fixed point + mode N as a signed number and store in operand 0 (which has mode + N). This instruction's result is defined only when the value of + operand 1 is an integer. + +`fixunsMN2' + Convert operand 1 (valid for floating point mode M) to fixed point + mode N as an unsigned number and store in operand 0 (which has + mode N). This instruction's result is defined only when the value + of operand 1 is an integer. + +`ftruncM2' + Convert operand 1 (valid for floating point mode M) to an integer + value, still represented in floating point mode M, and store it in + operand 0 (valid for floating point mode M). + +`fix_truncMN2' + Like `fixMN2' but works for any floating point value of mode M by + converting the value to an integer. + +`fixuns_truncMN2' + Like `fixunsMN2' but works for any floating point value of mode M + by converting the value to an integer. + +`truncMN2' + Truncate operand 1 (valid for mode M) to mode N and store in + operand 0 (which has mode N). Both modes must be fixed point or + both floating point. + +`extendMN2' + Sign-extend operand 1 (valid for mode M) to mode N and store in + operand 0 (which has mode N). Both modes must be fixed point or + both floating point. + +`zero_extendMN2' + Zero-extend operand 1 (valid for mode M) to mode N and store in + operand 0 (which has mode N). Both modes must be fixed point. + +`extv' + Extract a bit-field from operand 1 (a register or memory operand), + where operand 2 specifies the width in bits and operand 3 the + starting bit, and store it in operand 0. Operand 0 must have mode + `word_mode'. Operand 1 may have mode `byte_mode' or `word_mode'; + often `word_mode' is allowed only for registers. Operands 2 and 3 + must be valid for `word_mode'. + + The RTL generation pass generates this instruction only with + constants for operands 2 and 3. + + The bit-field value is sign-extended to a full word integer before + it is stored in operand 0. + +`extzv' + Like `extv' except that the bit-field value is zero-extended. + +`insv' + Store operand 3 (which must be valid for `word_mode') into a + bit-field in operand 0, where operand 1 specifies the width in + bits and operand 2 the starting bit. Operand 0 may have mode + `byte_mode' or `word_mode'; often `word_mode' is allowed only for + registers. Operands 1 and 2 must be valid for `word_mode'. + + The RTL generation pass generates this instruction only with + constants for operands 1 and 2. + +`movMODEcc' + Conditionally move operand 2 or operand 3 into operand 0 according + to the comparison in operand 1. If the comparison is true, + operand 2 is moved into operand 0, otherwise operand 3 is moved. + + The mode of the operands being compared need not be the same as + the operands being moved. Some machines, sparc64 for example, + have instructions that conditionally move an integer value based + on the floating point condition codes and vice versa. + + If the machine does not have conditional move instructions, do not + define these patterns. + +`sCOND' + Store zero or nonzero in the operand according to the condition + codes. Value stored is nonzero iff the condition COND is true. + COND is the name of a comparison operation expression code, such + as `eq', `lt' or `leu'. + + You specify the mode that the operand must have when you write the + `match_operand' expression. The compiler automatically sees which + mode you have used and supplies an operand of that mode. + + The value stored for a true condition must have 1 as its low bit, + or else must be negative. Otherwise the instruction is not + suitable and you should omit it from the machine description. You + describe to the compiler exactly which value is stored by defining + the macro `STORE_FLAG_VALUE' (*note Misc::). If a description + cannot be found that can be used for all the `sCOND' patterns, you + should omit those operations from the machine description. + + These operations may fail, but should do so only in relatively + uncommon cases; if they would fail for common cases involving + integer comparisons, it is best to omit these patterns. + + If these operations are omitted, the compiler will usually + generate code that copies the constant one to the target and + branches around an assignment of zero to the target. If this code + is more efficient than the potential instructions used for the + `sCOND' pattern followed by those required to convert the result + into a 1 or a zero in `SImode', you should omit the `sCOND' + operations from the machine description. + +`bCOND' + Conditional branch instruction. Operand 0 is a `label_ref' that + refers to the label to jump to. Jump if the condition codes meet + condition COND. + + Some machines do not follow the model assumed here where a + comparison instruction is followed by a conditional branch + instruction. In that case, the `cmpM' (and `tstM') patterns should + simply store the operands away and generate all the required insns + in a `define_expand' (*note Expander Definitions::) for the + conditional branch operations. All calls to expand `bCOND' + patterns are immediately preceded by calls to expand either a + `cmpM' pattern or a `tstM' pattern. + + Machines that use a pseudo register for the condition code value, + or where the mode used for the comparison depends on the condition + being tested, should also use the above mechanism. *Note Jump + Patterns::. + + The above discussion also applies to the `movMODEcc' and `sCOND' + patterns. + +`jump' + A jump inside a function; an unconditional branch. Operand 0 is + the `label_ref' of the label to jump to. This pattern name is + mandatory on all machines. + +`call' + Subroutine call instruction returning no value. Operand 0 is the + function to call; operand 1 is the number of bytes of arguments + pushed as a `const_int'; operand 2 is the number of registers used + as operands. + + On most machines, operand 2 is not actually stored into the RTL + pattern. It is supplied for the sake of some RISC machines which + need to put this information into the assembler code; they can put + it in the RTL instead of operand 1. + + Operand 0 should be a `mem' RTX whose address is the address of the + function. Note, however, that this address can be a `symbol_ref' + expression even if it would not be a legitimate memory address on + the target machine. If it is also not a valid argument for a call + instruction, the pattern for this operation should be a + `define_expand' (*note Expander Definitions::) that places the + address into a register and uses that register in the call + instruction. + +`call_value' + Subroutine call instruction returning a value. Operand 0 is the + hard register in which the value is returned. There are three more + operands, the same as the three operands of the `call' instruction + (but with numbers increased by one). + + Subroutines that return `BLKmode' objects use the `call' insn. + +`call_pop', `call_value_pop' + Similar to `call' and `call_value', except used if defined and if + `RETURN_POPS_ARGS' is nonzero. They should emit a `parallel' that + contains both the function call and a `set' to indicate the + adjustment made to the frame pointer. + + For machines where `RETURN_POPS_ARGS' can be nonzero, the use of + these patterns increases the number of functions for which the + frame pointer can be eliminated, if desired. + +`untyped_call' + Subroutine call instruction returning a value of any type. + Operand 0 is the function to call; operand 1 is a memory location + where the result of calling the function is to be stored; operand + 2 is a `parallel' expression where each element is a `set' + expression that indicates the saving of a function return value + into the result block. + + This instruction pattern should be defined to support + `__builtin_apply' on machines where special instructions are needed + to call a subroutine with arbitrary arguments or to save the value + returned. This instruction pattern is required on machines that + have multiple registers that can hold a return value (i.e. + `FUNCTION_VALUE_REGNO_P' is true for more than one register). + +`return' + Subroutine return instruction. This instruction pattern name + should be defined only if a single instruction can do all the work + of returning from a function. + + Like the `movM' patterns, this pattern is also used after the RTL + generation phase. In this case it is to support machines where + multiple instructions are usually needed to return from a + function, but some class of functions only requires one + instruction to implement a return. Normally, the applicable + functions are those which do not need to save any registers or + allocate stack space. + + For such machines, the condition specified in this pattern should + only be true when `reload_completed' is nonzero and the function's + epilogue would only be a single instruction. For machines with + register windows, the routine `leaf_function_p' may be used to + determine if a register window push is required. + + Machines that have conditional return instructions should define + patterns such as + + (define_insn "" + [(set (pc) + (if_then_else (match_operator + 0 "comparison_operator" + [(cc0) (const_int 0)]) + (return) + (pc)))] + "CONDITION" + "...") + + where CONDITION would normally be the same condition specified on + the named `return' pattern. + +`untyped_return' + Untyped subroutine return instruction. This instruction pattern + should be defined to support `__builtin_return' on machines where + special instructions are needed to return a value of any type. + + Operand 0 is a memory location where the result of calling a + function with `__builtin_apply' is stored; operand 1 is a + `parallel' expression where each element is a `set' expression + that indicates the restoring of a function return value from the + result block. + +`nop' + No-op instruction. This instruction pattern name should always be + defined to output a no-op in assembler code. `(const_int 0)' will + do as an RTL pattern. + +`indirect_jump' + An instruction to jump to an address which is operand zero. This + pattern name is mandatory on all machines. + +`casesi' + Instruction to jump through a dispatch table, including bounds + checking. This instruction takes five operands: + + 1. The index to dispatch on, which has mode `SImode'. + + 2. The lower bound for indices in the table, an integer constant. + + 3. The total range of indices in the table--the largest index + minus the smallest one (both inclusive). + + 4. A label that precedes the table itself. + + 5. A label to jump to if the index has a value outside the + bounds. (If the machine-description macro + `CASE_DROPS_THROUGH' is defined, then an out-of-bounds index + drops through to the code following the jump table instead of + jumping to this label. In that case, this label is not + actually used by the `casesi' instruction, but it is always + provided as an operand.) + + The table is a `addr_vec' or `addr_diff_vec' inside of a + `jump_insn'. The number of elements in the table is one plus the + difference between the upper bound and the lower bound. + +`tablejump' + Instruction to jump to a variable address. This is a low-level + capability which can be used to implement a dispatch table when + there is no `casesi' pattern. + + This pattern requires two operands: the address or offset, and a + label which should immediately precede the jump table. If the + macro `CASE_VECTOR_PC_RELATIVE' evaluates to a nonzero value then + the first operand is an offset which counts from the address of + the table; otherwise, it is an absolute address to jump to. In + either case, the first operand has mode `Pmode'. + + The `tablejump' insn is always the last insn before the jump table + it uses. Its assembler code normally has no need to use the + second operand, but you should incorporate it in the RTL pattern so + that the jump optimizer will not delete the table as unreachable + code. + +`decrement_and_branch_until_zero' + Conditional branch instruction that decrements a register and + jumps if the register is nonzero. Operand 0 is the register to + decrement and test; operand 1 is the label to jump to if the + register is nonzero. *Note Looping Patterns::. + + This optional instruction pattern is only used by the combiner, + typically for loops reversed by the loop optimizer when strength + reduction is enabled. + +`doloop_end' + Conditional branch instruction that decrements a register and + jumps if the register is nonzero. This instruction takes five + operands: Operand 0 is the register to decrement and test; operand + 1 is the number of loop iterations as a `const_int' or + `const0_rtx' if this cannot be determined until run-time; operand + 2 is the actual or estimated maximum number of iterations as a + `const_int'; operand 3 is the number of enclosed loops as a + `const_int' (an innermost loop has a value of 1); operand 4 is the + label to jump to if the register is nonzero. *Note Looping + Patterns::. + + This optional instruction pattern should be defined for machines + with low-overhead looping instructions as the loop optimizer will + try to modify suitable loops to utilize it. If nested + low-overhead looping is not supported, use a `define_expand' + (*note Expander Definitions::) and make the pattern fail if + operand 3 is not `const1_rtx'. Similarly, if the actual or + estimated maximum number of iterations is too large for this + instruction, make it fail. + +`doloop_begin' + Companion instruction to `doloop_end' required for machines that + need to perform some initialization, such as loading special + registers used by a low-overhead looping instruction. If + initialization insns do not always need to be emitted, use a + `define_expand' (*note Expander Definitions::) and make it fail. + +`canonicalize_funcptr_for_compare' + Canonicalize the function pointer in operand 1 and store the result + into operand 0. + + Operand 0 is always a `reg' and has mode `Pmode'; operand 1 may be + a `reg', `mem', `symbol_ref', `const_int', etc and also has mode + `Pmode'. + + Canonicalization of a function pointer usually involves computing + the address of the function which would be called if the function + pointer were used in an indirect call. + + Only define this pattern if function pointers on the target machine + can have different values but still call the same function when + used in an indirect call. + +`save_stack_block' +`save_stack_function' +`save_stack_nonlocal' +`restore_stack_block' +`restore_stack_function' +`restore_stack_nonlocal' + Most machines save and restore the stack pointer by copying it to + or from an object of mode `Pmode'. Do not define these patterns on + such machines. + + Some machines require special handling for stack pointer saves and + restores. On those machines, define the patterns corresponding to + the non-standard cases by using a `define_expand' (*note Expander + Definitions::) that produces the required insns. The three types + of saves and restores are: + + 1. `save_stack_block' saves the stack pointer at the start of a + block that allocates a variable-sized object, and + `restore_stack_block' restores the stack pointer when the + block is exited. + + 2. `save_stack_function' and `restore_stack_function' do a + similar job for the outermost block of a function and are + used when the function allocates variable-sized objects or + calls `alloca'. Only the epilogue uses the restored stack + pointer, allowing a simpler save or restore sequence on some + machines. + + 3. `save_stack_nonlocal' is used in functions that contain labels + branched to by nested functions. It saves the stack pointer + in such a way that the inner function can use + `restore_stack_nonlocal' to restore the stack pointer. The + compiler generates code to restore the frame and argument + pointer registers, but some machines require saving and + restoring additional data such as register window information + or stack backchains. Place insns in these patterns to save + and restore any such required data. + + When saving the stack pointer, operand 0 is the save area and + operand 1 is the stack pointer. The mode used to allocate the + save area defaults to `Pmode' but you can override that choice by + defining the `STACK_SAVEAREA_MODE' macro (*note Storage Layout::). + You must specify an integral mode, or `VOIDmode' if no save area + is needed for a particular type of save (either because no save is + needed or because a machine-specific save area can be used). + Operand 0 is the stack pointer and operand 1 is the save area for + restore operations. If `save_stack_block' is defined, operand 0 + must not be `VOIDmode' since these saves can be arbitrarily nested. + + A save area is a `mem' that is at a constant offset from + `virtual_stack_vars_rtx' when the stack pointer is saved for use by + nonlocal gotos and a `reg' in the other two cases. + +`allocate_stack' + Subtract (or add if `STACK_GROWS_DOWNWARD' is undefined) operand 1 + from the stack pointer to create space for dynamically allocated + data. + + Store the resultant pointer to this space into operand 0. If you + are allocating space from the main stack, do this by emitting a + move insn to copy `virtual_stack_dynamic_rtx' to operand 0. If + you are allocating the space elsewhere, generate code to copy the + location of the space to operand 0. In the latter case, you must + ensure this space gets freed when the corresponding space on the + main stack is free. + + Do not define this pattern if all that must be done is the + subtraction. Some machines require other operations such as stack + probes or maintaining the back chain. Define this pattern to emit + those operations in addition to updating the stack pointer. + +`probe' + Some machines require instructions to be executed after space is + allocated from the stack, for example to generate a reference at + the bottom of the stack. + + If you need to emit instructions before the stack has been + adjusted, put them into the `allocate_stack' pattern. Otherwise, + define this pattern to emit the required instructions. + + No operands are provided. + +`check_stack' + If stack checking cannot be done on your system by probing the + stack with a load or store instruction (*note Stack Checking::), + define this pattern to perform the needed check and signaling an + error if the stack has overflowed. The single operand is the + location in the stack furthest from the current stack pointer that + you need to validate. Normally, on machines where this pattern is + needed, you would obtain the stack limit from a global or + thread-specific variable or register. + +`nonlocal_goto' + Emit code to generate a non-local goto, e.g., a jump from one + function to a label in an outer function. This pattern has four + arguments, each representing a value to be used in the jump. The + first argument is to be loaded into the frame pointer, the second + is the address to branch to (code to dispatch to the actual label), + the third is the address of a location where the stack is saved, + and the last is the address of the label, to be placed in the + location for the incoming static chain. + + On most machines you need not define this pattern, since GCC will + already generate the correct code, which is to load the frame + pointer and static chain, restore the stack (using the + `restore_stack_nonlocal' pattern, if defined), and jump indirectly + to the dispatcher. You need only define this pattern if this code + will not work on your machine. + +`nonlocal_goto_receiver' + This pattern, if defined, contains code needed at the target of a + nonlocal goto after the code already generated by GCC. You will + not normally need to define this pattern. A typical reason why + you might need this pattern is if some value, such as a pointer to + a global table, must be restored when the frame pointer is + restored. Note that a nonlocal goto only occurs within a + unit-of-translation, so a global table pointer that is shared by + all functions of a given module need not be restored. There are + no arguments. + +`exception_receiver' + This pattern, if defined, contains code needed at the site of an + exception handler that isn't needed at the site of a nonlocal + goto. You will not normally need to define this pattern. A + typical reason why you might need this pattern is if some value, + such as a pointer to a global table, must be restored after + control flow is branched to the handler of an exception. There + are no arguments. + +`builtin_setjmp_setup' + This pattern, if defined, contains additional code needed to + initialize the `jmp_buf'. You will not normally need to define + this pattern. A typical reason why you might need this pattern is + if some value, such as a pointer to a global table, must be + restored. Though it is preferred that the pointer value be + recalculated if possible (given the address of a label for + instance). The single argument is a pointer to the `jmp_buf'. + Note that the buffer is five words long and that the first three + are normally used by the generic mechanism. + +`builtin_setjmp_receiver' + This pattern, if defined, contains code needed at the site of an + built-in setjmp that isn't needed at the site of a nonlocal goto. + You will not normally need to define this pattern. A typical + reason why you might need this pattern is if some value, such as a + pointer to a global table, must be restored. It takes one + argument, which is the label to which builtin_longjmp transfered + control; this pattern may be emitted at a small offset from that + label. + +`builtin_longjmp' + This pattern, if defined, performs the entire action of the + longjmp. You will not normally need to define this pattern unless + you also define `builtin_setjmp_setup'. The single argument is a + pointer to the `jmp_buf'. + +`eh_return' + This pattern, if defined, affects the way `__builtin_eh_return', + and thence the call frame exception handling library routines, are + built. It is intended to handle non-trivial actions needed along + the abnormal return path. + + The pattern takes two arguments. The first is an offset to be + applied to the stack pointer. It will have been copied to some + appropriate location (typically `EH_RETURN_STACKADJ_RTX') which + will survive until after reload to when the normal epilogue is + generated. The second argument is the address of the exception + handler to which the function should return. This will normally + need to copied by the pattern to some special register or memory + location. + + This pattern only needs to be defined if call frame exception + handling is to be used, and simple moves involving + `EH_RETURN_STACKADJ_RTX' and `EH_RETURN_HANDLER_RTX' are not + sufficient. + +`prologue' + This pattern, if defined, emits RTL for entry to a function. The + function entry is responsible for setting up the stack frame, + initializing the frame pointer register, saving callee saved + registers, etc. + + Using a prologue pattern is generally preferred over defining + `TARGET_ASM_FUNCTION_PROLOGUE' to emit assembly code for the + prologue. + + The `prologue' pattern is particularly useful for targets which + perform instruction scheduling. + +`epilogue' + This pattern emits RTL for exit from a function. The function + exit is responsible for deallocating the stack frame, restoring + callee saved registers and emitting the return instruction. + + Using an epilogue pattern is generally preferred over defining + `TARGET_ASM_FUNCTION_EPILOGUE' to emit assembly code for the + epilogue. + + The `epilogue' pattern is particularly useful for targets which + perform instruction scheduling or which have delay slots for their + return instruction. + +`sibcall_epilogue' + This pattern, if defined, emits RTL for exit from a function + without the final branch back to the calling function. This + pattern will be emitted before any sibling call (aka tail call) + sites. + + The `sibcall_epilogue' pattern must not clobber any arguments used + for parameter passing or any stack slots for arguments passed to + the current function. + +`trap' + This pattern, if defined, signals an error, typically by causing + some kind of signal to be raised. Among other places, it is used + by the Java front end to signal `invalid array index' exceptions. + +`conditional_trap' + Conditional trap instruction. Operand 0 is a piece of RTL which + performs a comparison. Operand 1 is the trap code, an integer. + + A typical `conditional_trap' pattern looks like + + (define_insn "conditional_trap" + [(trap_if (match_operator 0 "trap_operator" + [(cc0) (const_int 0)]) + (match_operand 1 "const_int_operand" "i"))] + "" + "...") + +`prefetch' + This pattern, if defined, emits code for a non-faulting data + prefetch instruction. Operand 0 is the address of the memory to + prefetch. Operand 1 is a constant 1 if the prefetch is preparing + for a write to the memory address, or a constant 0 otherwise. + Operand 2 is the expected degree of temporal locality of the data + and is a value between 0 and 3, inclusive; 0 means that the data + has no temporal locality, so it need not be left in the cache + after the access; 3 means that the data has a high degree of + temporal locality and should be left in all levels of cache + possible; 1 and 2 mean, respectively, a low or moderate degree of + temporal locality. + + Targets that do not support write prefetches or locality hints can + ignore the values of operands 1 and 2. + +`cycle_display' + This pattern, if present, will be emitted by the instruction + scheduler at the beginning of each new clock cycle. This can be + used for annotating the assembler output with cycle counts. + Operand 0 is a `const_int' that holds the clock cycle. + + + +File: gccint.info, Node: Pattern Ordering, Next: Dependent Patterns, Prev: Standard Names, Up: Machine Desc + +9.9 When the Order of Patterns Matters +====================================== + +Sometimes an insn can match more than one instruction pattern. Then the +pattern that appears first in the machine description is the one used. +Therefore, more specific patterns (patterns that will match fewer +things) and faster instructions (those that will produce better code +when they do match) should usually go first in the description. + + In some cases the effect of ordering the patterns can be used to hide +a pattern when it is not valid. For example, the 68000 has an +instruction for converting a fullword to floating point and another for +converting a byte to floating point. An instruction converting an +integer to floating point could match either one. We put the pattern +to convert the fullword first to make sure that one will be used rather +than the other. (Otherwise a large integer might be generated as a +single-byte immediate quantity, which would not work.) Instead of +using this pattern ordering it would be possible to make the pattern +for convert-a-byte smart enough to deal properly with any constant +value. + + +File: gccint.info, Node: Dependent Patterns, Next: Jump Patterns, Prev: Pattern Ordering, Up: Machine Desc + +9.10 Interdependence of Patterns +================================ + +Every machine description must have a named pattern for each of the +conditional branch names `bCOND'. The recognition template must always +have the form + + (set (pc) + (if_then_else (COND (cc0) (const_int 0)) + (label_ref (match_operand 0 "" "")) + (pc))) + +In addition, every machine description must have an anonymous pattern +for each of the possible reverse-conditional branches. Their templates +look like + + (set (pc) + (if_then_else (COND (cc0) (const_int 0)) + (pc) + (label_ref (match_operand 0 "" "")))) + +They are necessary because jump optimization can turn direct-conditional +branches into reverse-conditional branches. + + It is often convenient to use the `match_operator' construct to +reduce the number of patterns that must be specified for branches. For +example, + + (define_insn "" + [(set (pc) + (if_then_else (match_operator 0 "comparison_operator" + [(cc0) (const_int 0)]) + (pc) + (label_ref (match_operand 1 "" ""))))] + "CONDITION" + "...") + + In some cases machines support instructions identical except for the +machine mode of one or more operands. For example, there may be +"sign-extend halfword" and "sign-extend byte" instructions whose +patterns are + + (set (match_operand:SI 0 ...) + (extend:SI (match_operand:HI 1 ...))) + + (set (match_operand:SI 0 ...) + (extend:SI (match_operand:QI 1 ...))) + +Constant integers do not specify a machine mode, so an instruction to +extend a constant value could match either pattern. The pattern it +actually will match is the one that appears first in the file. For +correct results, this must be the one for the widest possible mode +(`HImode', here). If the pattern matches the `QImode' instruction, the +results will be incorrect if the constant value does not actually fit +that mode. + + Such instructions to extend constants are rarely generated because +they are optimized away, but they do occasionally happen in nonoptimized +compilations. + + If a constraint in a pattern allows a constant, the reload pass may +replace a register with a constant permitted by the constraint in some +cases. Similarly for memory references. Because of this substitution, +you should not provide separate patterns for increment and decrement +instructions. Instead, they should be generated from the same pattern +that supports register-register add insns by examining the operands and +generating the appropriate machine instruction. + + +File: gccint.info, Node: Jump Patterns, Next: Looping Patterns, Prev: Dependent Patterns, Up: Machine Desc + +9.11 Defining Jump Instruction Patterns +======================================= + +For most machines, GCC assumes that the machine has a condition code. +A comparison insn sets the condition code, recording the results of both +signed and unsigned comparison of the given operands. A separate branch +insn tests the condition code and branches or not according its value. +The branch insns come in distinct signed and unsigned flavors. Many +common machines, such as the VAX, the 68000 and the 32000, work this +way. + + Some machines have distinct signed and unsigned compare +instructions, and only one set of conditional branch instructions. The +easiest way to handle these machines is to treat them just like the +others until the final stage where assembly code is written. At this +time, when outputting code for the compare instruction, peek ahead at +the following branch using `next_cc0_user (insn)'. (The variable +`insn' refers to the insn being output, in the output-writing code in +an instruction pattern.) If the RTL says that is an unsigned branch, +output an unsigned compare; otherwise output a signed compare. When +the branch itself is output, you can treat signed and unsigned branches +identically. + + The reason you can do this is that GCC always generates a pair of +consecutive RTL insns, possibly separated by `note' insns, one to set +the condition code and one to test it, and keeps the pair inviolate +until the end. + + To go with this technique, you must define the machine-description +macro `NOTICE_UPDATE_CC' to do `CC_STATUS_INIT'; in other words, no +compare instruction is superfluous. + + Some machines have compare-and-branch instructions and no condition +code. A similar technique works for them. When it is time to "output" +a compare instruction, record its operands in two static variables. +When outputting the branch-on-condition-code instruction that follows, +actually output a compare-and-branch instruction that uses the +remembered operands. + + It also works to define patterns for compare-and-branch instructions. +In optimizing compilation, the pair of compare and branch instructions +will be combined according to these patterns. But this does not happen +if optimization is not requested. So you must use one of the solutions +above in addition to any special patterns you define. + + In many RISC machines, most instructions do not affect the condition +code and there may not even be a separate condition code register. On +these machines, the restriction that the definition and use of the +condition code be adjacent insns is not necessary and can prevent +important optimizations. For example, on the IBM RS/6000, there is a +delay for taken branches unless the condition code register is set three +instructions earlier than the conditional branch. The instruction +scheduler cannot perform this optimization if it is not permitted to +separate the definition and use of the condition code register. + + On these machines, do not use `(cc0)', but instead use a register to +represent the condition code. If there is a specific condition code +register in the machine, use a hard register. If the condition code or +comparison result can be placed in any general register, or if there are +multiple condition registers, use a pseudo register. + + On some machines, the type of branch instruction generated may +depend on the way the condition code was produced; for example, on the +68k and Sparc, setting the condition code directly from an add or +subtract instruction does not clear the overflow bit the way that a test +instruction does, so a different branch instruction must be used for +some conditional branches. For machines that use `(cc0)', the set and +use of the condition code must be adjacent (separated only by `note' +insns) allowing flags in `cc_status' to be used. (*Note Condition +Code::.) Also, the comparison and branch insns can be located from +each other by using the functions `prev_cc0_setter' and `next_cc0_user'. + + However, this is not true on machines that do not use `(cc0)'. On +those machines, no assumptions can be made about the adjacency of the +compare and branch insns and the above methods cannot be used. Instead, +we use the machine mode of the condition code register to record +different formats of the condition code register. + + Registers used to store the condition code value should have a mode +that is in class `MODE_CC'. Normally, it will be `CCmode'. If +additional modes are required (as for the add example mentioned above in +the Sparc), define the macro `EXTRA_CC_MODES' to list the additional +modes required (*note Condition Code::). Also define `SELECT_CC_MODE' +to choose a mode given an operand of a compare. + + If it is known during RTL generation that a different mode will be +required (for example, if the machine has separate compare instructions +for signed and unsigned quantities, like most IBM processors), they can +be specified at that time. + + If the cases that require different modes would be made by +instruction combination, the macro `SELECT_CC_MODE' determines which +machine mode should be used for the comparison result. The patterns +should be written using that mode. To support the case of the add on +the Sparc discussed above, we have the pattern + + (define_insn "" + [(set (reg:CC_NOOV 0) + (compare:CC_NOOV + (plus:SI (match_operand:SI 0 "register_operand" "%r") + (match_operand:SI 1 "arith_operand" "rI")) + (const_int 0)))] + "" + "...") + + The `SELECT_CC_MODE' macro on the Sparc returns `CC_NOOVmode' for +comparisons whose argument is a `plus'. + + +File: gccint.info, Node: Looping Patterns, Next: Insn Canonicalizations, Prev: Jump Patterns, Up: Machine Desc + +9.12 Defining Looping Instruction Patterns +========================================== + +Some machines have special jump instructions that can be utilised to +make loops more efficient. A common example is the 68000 `dbra' +instruction which performs a decrement of a register and a branch if the +result was greater than zero. Other machines, in particular digital +signal processors (DSPs), have special block repeat instructions to +provide low-overhead loop support. For example, the TI TMS320C3x/C4x +DSPs have a block repeat instruction that loads special registers to +mark the top and end of a loop and to count the number of loop +iterations. This avoids the need for fetching and executing a +`dbra'-like instruction and avoids pipeline stalls associated with the +jump. + + GCC has three special named patterns to support low overhead looping. +They are `decrement_and_branch_until_zero', `doloop_begin', and +`doloop_end'. The first pattern, `decrement_and_branch_until_zero', is +not emitted during RTL generation but may be emitted during the +instruction combination phase. This requires the assistance of the +loop optimizer, using information collected during strength reduction, +to reverse a loop to count down to zero. Some targets also require the +loop optimizer to add a `REG_NONNEG' note to indicate that the +iteration count is always positive. This is needed if the target +performs a signed loop termination test. For example, the 68000 uses a +pattern similar to the following for its `dbra' instruction: + + (define_insn "decrement_and_branch_until_zero" + [(set (pc) + (if_then_else + (ge (plus:SI (match_operand:SI 0 "general_operand" "+d*am") + (const_int -1)) + (const_int 0)) + (label_ref (match_operand 1 "" "")) + (pc))) + (set (match_dup 0) + (plus:SI (match_dup 0) + (const_int -1)))] + "find_reg_note (insn, REG_NONNEG, 0)" + "...") + + Note that since the insn is both a jump insn and has an output, it +must deal with its own reloads, hence the `m' constraints. Also note +that since this insn is generated by the instruction combination phase +combining two sequential insns together into an implicit parallel insn, +the iteration counter needs to be biased by the same amount as the +decrement operation, in this case -1. Note that the following similar +pattern will not be matched by the combiner. + + (define_insn "decrement_and_branch_until_zero" + [(set (pc) + (if_then_else + (ge (match_operand:SI 0 "general_operand" "+d*am") + (const_int 1)) + (label_ref (match_operand 1 "" "")) + (pc))) + (set (match_dup 0) + (plus:SI (match_dup 0) + (const_int -1)))] + "find_reg_note (insn, REG_NONNEG, 0)" + "...") + + The other two special looping patterns, `doloop_begin' and +`doloop_end', are emitted by the loop optimizer for certain +well-behaved loops with a finite number of loop iterations using +information collected during strength reduction. + + The `doloop_end' pattern describes the actual looping instruction +(or the implicit looping operation) and the `doloop_begin' pattern is +an optional companion pattern that can be used for initialization +needed for some low-overhead looping instructions. + + Note that some machines require the actual looping instruction to be +emitted at the top of the loop (e.g., the TMS320C3x/C4x DSPs). Emitting +the true RTL for a looping instruction at the top of the loop can cause +problems with flow analysis. So instead, a dummy `doloop' insn is +emitted at the end of the loop. The machine dependent reorg pass checks +for the presence of this `doloop' insn and then searches back to the +top of the loop, where it inserts the true looping insn (provided there +are no instructions in the loop which would cause problems). Any +additional labels can be emitted at this point. In addition, if the +desired special iteration counter register was not allocated, this +machine dependent reorg pass could emit a traditional compare and jump +instruction pair. + + The essential difference between the +`decrement_and_branch_until_zero' and the `doloop_end' patterns is that +the loop optimizer allocates an additional pseudo register for the +latter as an iteration counter. This pseudo register cannot be used +within the loop (i.e., general induction variables cannot be derived +from it), however, in many cases the loop induction variable may become +redundant and removed by the flow pass.  -File: gccint.info, Node: Test Suites, Prev: gcc Directory, Up: Source Tree +File: gccint.info, Node: Insn Canonicalizations, Next: Expander Definitions, Prev: Looping Patterns, Up: Machine Desc + +9.13 Canonicalization of Instructions +===================================== + +There are often cases where multiple RTL expressions could represent an +operation performed by a single machine instruction. This situation is +most commonly encountered with logical, branch, and multiply-accumulate +instructions. In such cases, the compiler attempts to convert these +multiple RTL expressions into a single canonical form to reduce the +number of insn patterns required. + + In addition to algebraic simplifications, following canonicalizations +are performed: + + * For commutative and comparison operators, a constant is always + made the second operand. If a machine only supports a constant as + the second operand, only patterns that match a constant in the + second operand need be supplied. + + For these operators, if only one operand is a `neg', `not', + `mult', `plus', or `minus' expression, it will be the first + operand. + + * For the `compare' operator, a constant is always the second operand + on machines where `cc0' is used (*note Jump Patterns::). On other + machines, there are rare cases where the compiler might want to + construct a `compare' with a constant as the first operand. + However, these cases are not common enough for it to be worthwhile + to provide a pattern matching a constant as the first operand + unless the machine actually has such an instruction. + + An operand of `neg', `not', `mult', `plus', or `minus' is made the + first operand under the same conditions as above. + + * `(minus X (const_int N))' is converted to `(plus X (const_int + -N))'. + + * Within address computations (i.e., inside `mem'), a left shift is + converted into the appropriate multiplication by a power of two. + + * De`Morgan's Law is used to move bitwise negation inside a bitwise + logical-and or logical-or operation. If this results in only one + operand being a `not' expression, it will be the first one. + + A machine that has an instruction that performs a bitwise + logical-and of one operand with the bitwise negation of the other + should specify the pattern for that instruction as + + (define_insn "" + [(set (match_operand:M 0 ...) + (and:M (not:M (match_operand:M 1 ...)) + (match_operand:M 2 ...)))] + "..." + "...") + + Similarly, a pattern for a "NAND" instruction should be written + + (define_insn "" + [(set (match_operand:M 0 ...) + (ior:M (not:M (match_operand:M 1 ...)) + (not:M (match_operand:M 2 ...))))] + "..." + "...") + + In both cases, it is not necessary to include patterns for the many + logically equivalent RTL expressions. + + * The only possible RTL expressions involving both bitwise + exclusive-or and bitwise negation are `(xor:M X Y)' and `(not:M + (xor:M X Y))'. + + * The sum of three items, one of which is a constant, will only + appear in the form + + (plus:M (plus:M X Y) CONSTANT) + + * On machines that do not use `cc0', `(compare X (const_int 0))' + will be converted to X. + + * Equality comparisons of a group of bits (usually a single bit) + with zero will be written using `zero_extract' rather than the + equivalent `and' or `sign_extract' operations. + + + +File: gccint.info, Node: Expander Definitions, Next: Insn Splitting, Prev: Insn Canonicalizations, Up: Machine Desc + +9.14 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 a vector of RTL expressions representing + a sequence of separate instructions. Unlike `define_insn', there + is no implicit surrounding `PARALLEL'. + + * 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 GCC is run. This is just like the condition of a + `define_insn' that has a standard name. Therefore, 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. + + * 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. GCC 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 bit-field (`extv', `extzv', + and `insv') operations. + + If the preparation falls through (invokes neither `DONE' nor +`FAIL'), then the `define_expand' acts like a `define_insn' in that the +RTL template is used to generate the insn. + + The RTL template is not used for matching, only for generating the +initial insn list. If the preparation statement always invokes `DONE' +or `FAIL', the RTL template may be reduced to a simple list of +operands, such as this example: + + (define_expand "addsi3" + [(match_operand:SI 0 "register_operand" "") + (match_operand:SI 1 "register_operand" "") + (match_operand:SI 2 "register_operand" "")] + "" + " + { + handle_add (operands[0], operands[1], operands[2]); + DONE; + }") + + 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_INT (65535)); ") + + *Note_* If the `define_expand' is used to serve a standard binary or +unary arithmetic operation or a bit-field 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. + + +File: gccint.info, Node: Insn Splitting, Next: Including Patterns, Prev: Expander Definitions, Up: Machine Desc + +9.15 Defining How to Split Instructions +======================================= + +There are two cases where you should specify how to split a pattern into +multiple insns. On machines that have instructions requiring delay +slots (*note Delay Slots::) or that have instructions whose output is +not available for multiple cycles (*note Function Units::), the compiler +phases that optimize these cases need to be able to move insns into +one-instruction delay slots. However, some insns may generate more +than one machine instruction. These insns cannot be placed into a +delay slot. + + Often you can rewrite the single insn as a list of individual insns, +each corresponding to one machine instruction. The disadvantage of +doing so is that it will cause the compilation to be slower and require +more space. If the resulting insns are too complex, it may also +suppress some optimizations. The compiler splits the insn if there is a +reason to believe that it might improve instruction or delay slot +scheduling. + + The insn combiner phase also splits putative insns. If three insns +are merged into one insn with a complex expression that cannot be +matched by some `define_insn' pattern, the combiner phase attempts to +split the complex pattern into two insns that are recognized. Usually +it can break the complex pattern into two patterns by splitting out some +subexpression. However, in some other cases, such as performing an +addition of a large constant in two insns on a RISC machine, the way to +split the addition into two insns is machine-dependent. + + The `define_split' definition tells the compiler how to split a +complex insn into several simpler insns. It looks like this: + + (define_split + [INSN-PATTERN] + "CONDITION" + [NEW-INSN-PATTERN-1 + NEW-INSN-PATTERN-2 + ...] + "PREPARATION-STATEMENTS") + + INSN-PATTERN is a pattern that needs to be split and CONDITION is +the final condition to be tested, as in a `define_insn'. When an insn +matching INSN-PATTERN and satisfying CONDITION is found, it is replaced +in the insn list with the insns given by NEW-INSN-PATTERN-1, +NEW-INSN-PATTERN-2, etc. + + The PREPARATION-STATEMENTS are similar to those statements that are +specified for `define_expand' (*note Expander Definitions::) and are +executed before the new RTL is generated to prepare for the generated +code or emit some insns whose pattern is not fixed. Unlike those in +`define_expand', however, these statements must not generate any new +pseudo-registers. Once reload has completed, they also must not +allocate any space in the stack frame. + + Patterns are matched against INSN-PATTERN in two different +circumstances. If an insn needs to be split for delay slot scheduling +or insn scheduling, the insn is already known to be valid, which means +that it must have been matched by some `define_insn' and, if +`reload_completed' is nonzero, is known to satisfy the constraints of +that `define_insn'. In that case, the new insn patterns must also be +insns that are matched by some `define_insn' and, if `reload_completed' +is nonzero, must also satisfy the constraints of those definitions. + + As an example of this usage of `define_split', consider the following +example from `a29k.md', which splits a `sign_extend' from `HImode' to +`SImode' into a pair of shift insns: + + (define_split + [(set (match_operand:SI 0 "gen_reg_operand" "") + (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))] + "" + [(set (match_dup 0) + (ashift:SI (match_dup 1) + (const_int 16))) + (set (match_dup 0) + (ashiftrt:SI (match_dup 0) + (const_int 16)))] + " + { operands[1] = gen_lowpart (SImode, operands[1]); }") + + When the combiner phase tries to split an insn pattern, it is always +the case that the pattern is _not_ matched by any `define_insn'. The +combiner pass first tries to split a single `set' expression and then +the same `set' expression inside a `parallel', but followed by a +`clobber' of a pseudo-reg to use as a scratch register. In these +cases, the combiner expects exactly two new insn patterns to be +generated. It will verify that these patterns match some `define_insn' +definitions, so you need not do this test in the `define_split' (of +course, there is no point in writing a `define_split' that will never +produce insns that match). + + Here is an example of this use of `define_split', taken from +`rs6000.md': + + (define_split + [(set (match_operand:SI 0 "gen_reg_operand" "") + (plus:SI (match_operand:SI 1 "gen_reg_operand" "") + (match_operand:SI 2 "non_add_cint_operand" "")))] + "" + [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3))) + (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))] + " + { + int low = INTVAL (operands[2]) & 0xffff; + int high = (unsigned) INTVAL (operands[2]) >> 16; + + if (low & 0x8000) + high++, low |= 0xffff0000; + + operands[3] = GEN_INT (high << 16); + operands[4] = GEN_INT (low); + }") + + Here the predicate `non_add_cint_operand' matches any `const_int' +that is _not_ a valid operand of a single add insn. The add with the +smaller displacement is written so that it can be substituted into the +address of a subsequent operation. + + An example that uses a scratch register, from the same file, +generates an equality comparison of a register and a large constant: + + (define_split + [(set (match_operand:CC 0 "cc_reg_operand" "") + (compare:CC (match_operand:SI 1 "gen_reg_operand" "") + (match_operand:SI 2 "non_short_cint_operand" ""))) + (clobber (match_operand:SI 3 "gen_reg_operand" ""))] + "find_single_use (operands[0], insn, 0) + && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ + || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)" + [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4))) + (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))] + " + { + /* Get the constant we are comparing against, C, and see what it + looks like sign-extended to 16 bits. Then see what constant + could be XOR'ed with C to get the sign-extended value. */ + + int c = INTVAL (operands[2]); + int sextc = (c << 16) >> 16; + int xorv = c ^ sextc; + + operands[4] = GEN_INT (xorv); + operands[5] = GEN_INT (sextc); + }") + + To avoid confusion, don't write a single `define_split' that accepts +some insns that match some `define_insn' as well as some insns that +don't. Instead, write two separate `define_split' definitions, one for +the insns that are valid and one for the insns that are not valid. + + The splitter is allowed to split jump instructions into sequence of +jumps or create new jumps in while splitting non-jump instructions. As +the central flowgraph and branch prediction information needs to be +updated, several restriction apply. + + Splitting of jump instruction into sequence that over by another jump +instruction is always valid, as compiler expect identical behavior of +new jump. When new sequence contains multiple jump instructions or new +labels, more assistance is needed. Splitter is required to create only +unconditional jumps, or simple conditional jump instructions. +Additionally it must attach a `REG_BR_PROB' note to each conditional +jump. An global variable `split_branch_probability' hold the +probability of original branch in case it was an simple conditional +jump, -1 otherwise. To simplify recomputing of edge frequencies, new +sequence is required to have only forward jumps to the newly created +labels. + + For the common case where the pattern of a define_split exactly +matches the pattern of a define_insn, use `define_insn_and_split'. It +looks like this: + + (define_insn_and_split + [INSN-PATTERN] + "CONDITION" + "OUTPUT-TEMPLATE" + "SPLIT-CONDITION" + [NEW-INSN-PATTERN-1 + NEW-INSN-PATTERN-2 + ...] + "PREPARATION-STATEMENTS" + [INSN-ATTRIBUTES]) + + INSN-PATTERN, CONDITION, OUTPUT-TEMPLATE, and INSN-ATTRIBUTES are +used as in `define_insn'. The NEW-INSN-PATTERN vector and the +PREPARATION-STATEMENTS are used as in a `define_split'. The +SPLIT-CONDITION is also used as in `define_split', with the additional +behavior that if the condition starts with `&&', the condition used for +the split will be the constructed as a logical "and" of the split +condition with the insn condition. For example, from i386.md: + + (define_insn_and_split "zero_extendhisi2_and" + [(set (match_operand:SI 0 "register_operand" "=r") + (zero_extend:SI (match_operand:HI 1 "register_operand" "0"))) + (clobber (reg:CC 17))] + "TARGET_ZERO_EXTEND_WITH_AND && !optimize_size" + "#" + "&& reload_completed" + [(parallel [(set (match_dup 0) + (and:SI (match_dup 0) (const_int 65535))) + (clobber (reg:CC 17))])] + "" + [(set_attr "type" "alu1")]) + + In this case, the actual split condition will be +`TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed'. + + The `define_insn_and_split' construction provides exactly the same +functionality as two separate `define_insn' and `define_split' +patterns. It exists for compactness, and as a maintenance tool to +prevent having to ensure the two patterns' templates match. + + +File: gccint.info, Node: Including Patterns, Next: Peephole Definitions, Prev: Insn Splitting, Up: Machine Desc + +9.16 Including Patterns in Machine Descriptions. +================================================ + +The `include' pattern tells the compiler tools where to look for +patterns that are in files other than in the file `.md'. This is used +only at build time and there is no preprocessing allowed. + + It looks like: + + + (include + PATHNAME) + + For example: + + + (include "filestuff") + + Where PATHNAME is a string that specifies the the location of the +file, specifies the include file to be in +`gcc/config/target/filestuff'. The directory `gcc/config/target' is +regarded as the default directory. + + Machine descriptions may be split up into smaller more manageable +subsections and placed into subdirectories. + + By specifying: + + + (include "BOGUS/filestuff") + + the include file is specified to be in +`gcc/config/TARGET/BOGUS/filestuff'. + + Specifying an absolute path for the include file such as; + + (include "/u2/BOGUS/filestuff") + is permitted but is not encouraged. + +9.16.1 RTL Generation Tool Options for Directory Search +------------------------------------------------------- + +The `-IDIR' option specifies directories to search for machine +descriptions. For example: + + + genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md + + Add the directory DIR to the head of the list of directories to be +searched for header files. This can be used to override a system +machine definition file, substituting your own version, since these +directories are searched before the default machine description file +directories. If you use more than one `-I' option, the directories are +scanned in left-to-right order; the standard default directory come +after. + + +File: gccint.info, Node: Peephole Definitions, Next: Insn Attributes, Prev: Including Patterns, Up: Machine Desc + +9.17 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. -Test Suites -=========== + There are two forms of peephole definitions that may be used. The +original `define_peephole' is run at assembly output time to match +insns and substitute assembly text. Use of `define_peephole' is +deprecated. - GCC contains several test suites to help maintain compiler quality. -Most of the runtime libraries and language front ends in GCC have test -suites. Currently only the C language test suites are documented here; -FIXME: document the others. + A newer `define_peephole2' matches insns and substitutes new insns. +The `peephole2' pass is run after register allocation but before +scheduling, which may result in much better code for targets that do +scheduling. * Menu: -* Test Idioms:: Idioms used in test suite code. -* C Tests:: The C language test suites. -* libgcj Tests:: The Java library test suites. +* define_peephole:: RTL to Text Peephole Optimizers +* define_peephole2:: RTL to RTL Peephole Optimizers  -File: gccint.info, Node: Test Idioms, Next: C Tests, Up: Test Suites +File: gccint.info, Node: define_peephole, Next: define_peephole2, Up: Peephole Definitions + +9.17.1 RTL to Text Peephole Optimizers +-------------------------------------- + +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_active_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)))]) + ...] + ...) -Idioms Used in Test Suite Code ------------------------------- + +File: gccint.info, Node: define_peephole2, Prev: define_peephole, Up: Peephole Definitions + +9.17.2 RTL to RTL Peephole Optimizers +------------------------------------- + +The `define_peephole2' definition tells the compiler how to substitute +one sequence of instructions for another sequence, what additional +scratch registers may be needed and what their lifetimes must be. + + (define_peephole2 + [INSN-PATTERN-1 + INSN-PATTERN-2 + ...] + "CONDITION" + [NEW-INSN-PATTERN-1 + NEW-INSN-PATTERN-2 + ...] + "PREPARATION-STATEMENTS") + + The definition is almost identical to `define_split' (*note Insn +Splitting::) except that the pattern to match is not a single +instruction, but a sequence of instructions. + + It is possible to request additional scratch registers for use in the +output template. If appropriate registers are not free, the pattern +will simply not match. + + Scratch registers are requested with a `match_scratch' pattern at +the top level of the input pattern. The allocated register (initially) +will be dead at the point requested within the original sequence. If +the scratch is used at more than a single point, a `match_dup' pattern +at the top level of the input pattern marks the last position in the +input sequence at which the register must be available. + + Here is an example from the IA-32 machine description: + + (define_peephole2 + [(match_scratch:SI 2 "r") + (parallel [(set (match_operand:SI 0 "register_operand" "") + (match_operator:SI 3 "arith_or_logical_operator" + [(match_dup 0) + (match_operand:SI 1 "memory_operand" "")])) + (clobber (reg:CC 17))])] + "! optimize_size && ! TARGET_READ_MODIFY" + [(set (match_dup 2) (match_dup 1)) + (parallel [(set (match_dup 0) + (match_op_dup 3 [(match_dup 0) (match_dup 2)])) + (clobber (reg:CC 17))])] + "") + +This pattern tries to split a load from its use in the hopes that we'll +be able to schedule around the memory load latency. It allocates a +single `SImode' register of class `GENERAL_REGS' (`"r"') that needs to +be live only at the point just before the arithmetic. + + A real example requiring extended scratch lifetimes is harder to +come by, so here's a silly made-up example: + + (define_peephole2 + [(match_scratch:SI 4 "r") + (set (match_operand:SI 0 "" "") (match_operand:SI 1 "" "")) + (set (match_operand:SI 2 "" "") (match_dup 1)) + (match_dup 4) + (set (match_operand:SI 3 "" "") (match_dup 1))] + "/* determine 1 does not overlap 0 and 2 */" + [(set (match_dup 4) (match_dup 1)) + (set (match_dup 0) (match_dup 4)) + (set (match_dup 2) (match_dup 4))] + (set (match_dup 3) (match_dup 4))] + "") + +If we had not added the `(match_dup 4)' in the middle of the input +sequence, it might have been the case that the register we chose at the +beginning of the sequence is killed by the first or second `set'. + + +File: gccint.info, Node: Insn Attributes, Next: Conditional Execution, Prev: Peephole Definitions, Up: Machine Desc + +9.18 Instruction Attributes +=========================== + +In addition to describing the instruction supported by the target +machine, the `md' file also defines a group of "attributes" and a set of +values for each. Every generated insn is assigned a value for each +attribute. One possible attribute would be the effect that the insn +has on the machine's condition code. This attribute can then be used +by `NOTICE_UPDATE_CC' to track the condition codes. + +* Menu: + +* Defining Attributes:: Specifying attributes and their values. +* Expressions:: Valid expressions for attribute values. +* Tagging Insns:: Assigning attribute values to insns. +* Attr Example:: An example of assigning attributes. +* Insn Lengths:: Computing the length of insns. +* Constant Attributes:: Defining attributes that are constant. +* Delay Slots:: Defining delay slots required for a machine. +* Function Units:: Specifying information for insn scheduling. + + +File: gccint.info, Node: Defining Attributes, Next: Expressions, Up: Insn Attributes + +9.18.1 Defining Attributes and their Values +------------------------------------------- + +The `define_attr' expression is used to define each attribute required +by the target machine. It looks like: + + (define_attr NAME LIST-OF-VALUES DEFAULT) + + NAME is a string specifying the name of the attribute being defined. + + LIST-OF-VALUES is either a string that specifies a comma-separated +list of values that can be assigned to the attribute, or a null string +to indicate that the attribute takes numeric values. + + DEFAULT is an attribute expression that gives the value of this +attribute for insns that match patterns whose definition does not +include an explicit value for this attribute. *Note Attr Example::, +for more information on the handling of defaults. *Note Constant +Attributes::, for information on attributes that do not depend on any +particular insn. + + For each defined attribute, a number of definitions are written to +the `insn-attr.h' file. For cases where an explicit set of values is +specified for an attribute, the following are defined: + + * A `#define' is written for the symbol `HAVE_ATTR_NAME'. + + * An enumeral class is defined for `attr_NAME' with elements of the + form `UPPER-NAME_UPPER-VALUE' where the attribute name and value + are first converted to upper case. + + * A function `get_attr_NAME' is defined that is passed an insn and + returns the attribute value for that insn. + + For example, if the following is present in the `md' file: + + (define_attr "type" "branch,fp,load,store,arith" ...) + +the following lines will be written to the file `insn-attr.h'. + + #define HAVE_ATTR_type + enum attr_type {TYPE_BRANCH, TYPE_FP, TYPE_LOAD, + TYPE_STORE, TYPE_ARITH}; + extern enum attr_type get_attr_type (); + + If the attribute takes numeric values, no `enum' type will be +defined and the function to obtain the attribute's value will return +`int'. + + +File: gccint.info, Node: Expressions, Next: Tagging Insns, Prev: Defining Attributes, Up: Insn Attributes - In the `gcc.c-torture' test suites, test cases are commonly named -after the date on which they were added. This allows people to tell at -a glance whether a test failure is because of a recently found bug that -has not yet been fixed, or whether it may be a regression. In other -test suites, more descriptive names are used. In general C test cases -have a trailing `-N.c', starting with `-1.c', in case other test cases -with similar names are added later. - - Test cases should use `abort ()' to indicate failure and `exit (0)' -for success; on some targets these may be redefined to indicate failure -and success in other ways. - - In the `gcc.dg' test suite, it is often necessary to test that an -error is indeed a hard error and not just a warning--for example, where -it is a constraint violation in the C standard, which must become an -error with `-pedantic-errors'. The following idiom, where the first -line shown is line LINE of the file and the line that generates the -error, is used for this: - - /* { dg-bogus "warning" "warning in place of error" } */ - /* { dg-error "REGEXP" "MESSAGE" { target *-*-* } LINE } */ - - It may be necessary to check that an expression is an integer -constant expression and has a certain value. To check that `E' has -value `V', an idiom similar to the following is used: - - char x[((E) == (V) ? 1 : -1)]; - - In `gcc.dg' tests, `__typeof__' is sometimes used to make assertions -about the types of expressions. See, for example, -`gcc.dg/c99-condexpr-1.c'. The more subtle uses depend on the exact -rules for the types of conditional expressions in the C standard; see, -for example, `gcc.dg/c99-intconst-1.c'. - - It is useful to be able to test that optimizations are being made -properly. This cannot be done in all cases, but it can be done where -the optimization will lead to code being optimized away (for example, -where flow analysis or alias analysis should show that certain code -cannot be called) or to functions not being called because they have -been expanded as built-in functions. Such tests go in -`gcc.c-torture/execute'. Where code should be optimized away, a call -to a nonexistent function such as `link_failure ()' may be inserted; a -definition - - #ifndef __OPTIMIZE__ - void - link_failure (void) +9.18.2 Attribute Expressions +---------------------------- + +RTL expressions used to define attributes use the codes described above +plus a few specific to attribute definitions, to be discussed below. +Attribute value expressions must have one of the following forms: + +`(const_int I)' + The integer I specifies the value of a numeric attribute. I must + be non-negative. + + The value of a numeric attribute can be specified either with a + `const_int', or as an integer represented as a string in + `const_string', `eq_attr' (see below), `attr', `symbol_ref', + simple arithmetic expressions, and `set_attr' overrides on + specific instructions (*note Tagging Insns::). + +`(const_string VALUE)' + The string VALUE specifies a constant attribute value. If VALUE + is specified as `"*"', it means that the default value of the + attribute is to be used for the insn containing this expression. + `"*"' obviously cannot be used in the DEFAULT expression of a + `define_attr'. + + If the attribute whose value is being specified is numeric, VALUE + must be a string containing a non-negative integer (normally + `const_int' would be used in this case). Otherwise, it must + contain one of the valid values for the attribute. + +`(if_then_else TEST TRUE-VALUE FALSE-VALUE)' + TEST specifies an attribute test, whose format is defined below. + The value of this expression is TRUE-VALUE if TEST is true, + otherwise it is FALSE-VALUE. + +`(cond [TEST1 VALUE1 ...] DEFAULT)' + The first operand of this expression is a vector containing an even + number of expressions and consisting of pairs of TEST and VALUE + expressions. The value of the `cond' expression is that of the + VALUE corresponding to the first true TEST expression. If none of + the TEST expressions are true, the value of the `cond' expression + is that of the DEFAULT expression. + + TEST expressions can have one of the following forms: + +`(const_int I)' + This test is true if I is nonzero and false otherwise. + +`(not TEST)' +`(ior TEST1 TEST2)' +`(and TEST1 TEST2)' + These tests are true if the indicated logical function is true. + +`(match_operand:M N PRED CONSTRAINTS)' + This test is true if operand N of the insn whose attribute value + is being determined has mode M (this part of the test is ignored + if M is `VOIDmode') and the function specified by the string PRED + returns a nonzero value when passed operand N and mode M (this + part of the test is ignored if PRED is the null string). + + The CONSTRAINTS operand is ignored and should be the null string. + +`(le ARITH1 ARITH2)' +`(leu ARITH1 ARITH2)' +`(lt ARITH1 ARITH2)' +`(ltu ARITH1 ARITH2)' +`(gt ARITH1 ARITH2)' +`(gtu ARITH1 ARITH2)' +`(ge ARITH1 ARITH2)' +`(geu ARITH1 ARITH2)' +`(ne ARITH1 ARITH2)' +`(eq ARITH1 ARITH2)' + These tests are true if the indicated comparison of the two + arithmetic expressions is true. Arithmetic expressions are formed + with `plus', `minus', `mult', `div', `mod', `abs', `neg', `and', + `ior', `xor', `not', `ashift', `lshiftrt', and `ashiftrt' + expressions. + + `const_int' and `symbol_ref' are always valid terms (*note Insn + Lengths::,for additional forms). `symbol_ref' is a string + denoting a C expression that yields an `int' when evaluated by the + `get_attr_...' routine. It should normally be a global variable. + +`(eq_attr NAME VALUE)' + NAME is a string specifying the name of an attribute. + + VALUE is a string that is either a valid value for attribute NAME, + a comma-separated list of values, or `!' followed by a value or + list. If VALUE does not begin with a `!', this test is true if + the value of the NAME attribute of the current insn is in the list + specified by VALUE. If VALUE begins with a `!', this test is true + if the attribute's value is _not_ in the specified list. + + For example, + + (eq_attr "type" "load,store") + + is equivalent to + + (ior (eq_attr "type" "load") (eq_attr "type" "store")) + + If NAME specifies an attribute of `alternative', it refers to the + value of the compiler variable `which_alternative' (*note Output + Statement::) and the values must be small integers. For example, + + (eq_attr "alternative" "2,3") + + is equivalent to + + (ior (eq (symbol_ref "which_alternative") (const_int 2)) + (eq (symbol_ref "which_alternative") (const_int 3))) + + Note that, for most attributes, an `eq_attr' test is simplified in + cases where the value of the attribute being tested is known for + all insns matching a particular pattern. This is by far the most + common case. + +`(attr_flag NAME)' + The value of an `attr_flag' expression is true if the flag + specified by NAME is true for the `insn' currently being scheduled. + + NAME is a string specifying one of a fixed set of flags to test. + Test the flags `forward' and `backward' to determine the direction + of a conditional branch. Test the flags `very_likely', `likely', + `very_unlikely', and `unlikely' to determine if a conditional + branch is expected to be taken. + + If the `very_likely' flag is true, then the `likely' flag is also + true. Likewise for the `very_unlikely' and `unlikely' flags. + + This example describes a conditional branch delay slot which can + be nullified for forward branches that are taken (annul-true) or + for backward branches which are not taken (annul-false). + + (define_delay (eq_attr "type" "cbranch") + [(eq_attr "in_branch_delay" "true") + (and (eq_attr "in_branch_delay" "true") + (attr_flag "forward")) + (and (eq_attr "in_branch_delay" "true") + (attr_flag "backward"))]) + + The `forward' and `backward' flags are false if the current `insn' + being scheduled is not a conditional branch. + + The `very_likely' and `likely' flags are true if the `insn' being + scheduled is not a conditional branch. The `very_unlikely' and + `unlikely' flags are false if the `insn' being scheduled is not a + conditional branch. + + `attr_flag' is only used during delay slot scheduling and has no + meaning to other passes of the compiler. + +`(attr NAME)' + The value of another attribute is returned. This is most useful + for numeric attributes, as `eq_attr' and `attr_flag' produce more + efficient code for non-numeric attributes. + + +File: gccint.info, Node: Tagging Insns, Next: Attr Example, Prev: Expressions, Up: Insn Attributes + +9.18.3 Assigning Attribute Values to Insns +------------------------------------------ + +The value assigned to an attribute of an insn is primarily determined by +which pattern is matched by that insn (or which `define_peephole' +generated it). Every `define_insn' and `define_peephole' can have an +optional last argument to specify the values of attributes for matching +insns. The value of any attribute not specified in a particular insn +is set to the default value for that attribute, as specified in its +`define_attr'. Extensive use of default values for attributes permits +the specification of the values for only one or two attributes in the +definition of most insn patterns, as seen in the example in the next +section. + + The optional last argument of `define_insn' and `define_peephole' is +a vector of expressions, each of which defines the value for a single +attribute. The most general way of assigning an attribute's value is +to use a `set' expression whose first operand is an `attr' expression +giving the name of the attribute being set. The second operand of the +`set' is an attribute expression (*note Expressions::) giving the value +of the attribute. + + When the attribute value depends on the `alternative' attribute +(i.e., which is the applicable alternative in the constraint of the +insn), the `set_attr_alternative' expression can be used. It allows +the specification of a vector of attribute expressions, one for each +alternative. + + When the generality of arbitrary attribute expressions is not +required, the simpler `set_attr' expression can be used, which allows +specifying a string giving either a single attribute value or a list of +attribute values, one for each alternative. + + The form of each of the above specifications is shown below. In +each case, NAME is a string specifying the attribute to be set. + +`(set_attr NAME VALUE-STRING)' + VALUE-STRING is either a string giving the desired attribute value, + or a string containing a comma-separated list giving the values for + succeeding alternatives. The number of elements must match the + number of alternatives in the constraint of the insn pattern. + + Note that it may be useful to specify `*' for some alternative, in + which case the attribute will assume its default value for insns + matching that alternative. + +`(set_attr_alternative NAME [VALUE1 VALUE2 ...])' + Depending on the alternative of the insn, the value will be one of + the specified values. This is a shorthand for using a `cond' with + tests on the `alternative' attribute. + +`(set (attr NAME) VALUE)' + The first operand of this `set' must be the special RTL expression + `attr', whose sole operand is a string giving the name of the + attribute being set. VALUE is the value of the attribute. + + The following shows three different ways of representing the same +attribute value specification: + + (set_attr "type" "load,store,arith") + + (set_attr_alternative "type" + [(const_string "load") (const_string "store") + (const_string "arith")]) + + (set (attr "type") + (cond [(eq_attr "alternative" "1") (const_string "load") + (eq_attr "alternative" "2") (const_string "store")] + (const_string "arith"))) + + The `define_asm_attributes' expression provides a mechanism to +specify the attributes assigned to insns produced from an `asm' +statement. It has the form: + + (define_asm_attributes [ATTR-SETS]) + +where ATTR-SETS is specified the same as for both the `define_insn' and +the `define_peephole' expressions. + + These values will typically be the "worst case" attribute values. +For example, they might indicate that the condition code will be +clobbered. + + A specification for a `length' attribute is handled specially. The +way to compute the length of an `asm' insn is to multiply the length +specified in the expression `define_asm_attributes' by the number of +machine instructions specified in the `asm' statement, determined by +counting the number of semicolons and newlines in the string. +Therefore, the value of the `length' attribute specified in a +`define_asm_attributes' should be the maximum possible length of a +single machine instruction. + + +File: gccint.info, Node: Attr Example, Next: Insn Lengths, Prev: Tagging Insns, Up: Insn Attributes + +9.18.4 Example of Attribute Specifications +------------------------------------------ + +The judicious use of defaulting is important in the efficient use of +insn attributes. Typically, insns are divided into "types" and an +attribute, customarily called `type', is used to represent this value. +This attribute is normally used only to define the default value for +other attributes. An example will clarify this usage. + + Assume we have a RISC machine with a condition code and in which only +full-word operations are performed in registers. Let us assume that we +can divide all insns into loads, stores, (integer) arithmetic +operations, floating point operations, and branches. + + Here we will concern ourselves with determining the effect of an +insn on the condition code and will limit ourselves to the following +possible effects: The condition code can be set unpredictably +(clobbered), not be changed, be set to agree with the results of the +operation, or only changed if the item previously set into the +condition code has been modified. + + Here is part of a sample `md' file for such a machine: + + (define_attr "type" "load,store,arith,fp,branch" (const_string "arith")) + + (define_attr "cc" "clobber,unchanged,set,change0" + (cond [(eq_attr "type" "load") + (const_string "change0") + (eq_attr "type" "store,branch") + (const_string "unchanged") + (eq_attr "type" "arith") + (if_then_else (match_operand:SI 0 "" "") + (const_string "set") + (const_string "clobber"))] + (const_string "clobber"))) + + (define_insn "" + [(set (match_operand:SI 0 "general_operand" "=r,r,m") + (match_operand:SI 1 "general_operand" "r,m,r"))] + "" + "@ + move %0,%1 + load %0,%1 + store %0,%1" + [(set_attr "type" "arith,load,store")]) + + Note that we assume in the above example that arithmetic operations +performed on quantities smaller than a machine word clobber the +condition code since they will set the condition code to a value +corresponding to the full-word result. + + +File: gccint.info, Node: Insn Lengths, Next: Constant Attributes, Prev: Attr Example, Up: Insn Attributes + +9.18.5 Computing the Length of an Insn +-------------------------------------- + +For many machines, multiple types of branch instructions are provided, +each for different length branch displacements. In most cases, the +assembler will choose the correct instruction to use. However, when +the assembler cannot do so, GCC can when a special attribute, the +`length' attribute, is defined. This attribute must be defined to have +numeric values by specifying a null string in its `define_attr'. + + In the case of the `length' attribute, two additional forms of +arithmetic terms are allowed in test expressions: + +`(match_dup N)' + This refers to the address of operand N of the current insn, which + must be a `label_ref'. + +`(pc)' + This refers to the address of the _current_ insn. It might have + been more consistent with other usage to make this the address of + the _next_ insn but this would be confusing because the length of + the current insn is to be computed. + + For normal insns, the length will be determined by value of the +`length' attribute. In the case of `addr_vec' and `addr_diff_vec' insn +patterns, the length is computed as the number of vectors multiplied by +the size of each vector. + + Lengths are measured in addressable storage units (bytes). + + The following macros can be used to refine the length computation: + +`FIRST_INSN_ADDRESS' + When the `length' insn attribute is used, this macro specifies the + value to be assigned to the address of the first insn in a + function. If not specified, 0 is used. + +`ADJUST_INSN_LENGTH (INSN, LENGTH)' + If defined, modifies the length assigned to instruction INSN as a + function of the context in which it is used. LENGTH is an lvalue + that contains the initially computed length of the insn and should + be updated with the correct length of the insn. + + This macro will normally not be required. A case in which it is + required is the ROMP. On this machine, the size of an `addr_vec' + insn must be increased by two to compensate for the fact that + alignment may be required. + + The routine that returns `get_attr_length' (the value of the +`length' attribute) can be used by the output routine to determine the +form of the branch instruction to be written, as the example below +illustrates. + + As an example of the specification of variable-length branches, +consider the IBM 360. If we adopt the convention that a register will +be set to the starting address of a function, we can jump to labels +within 4k of the start using a four-byte instruction. Otherwise, we +need a six-byte sequence to load the address from memory and then +branch to it. + + On such a machine, a pattern for a branch instruction might be +specified as follows: + + (define_insn "jump" + [(set (pc) + (label_ref (match_operand 0 "" "")))] + "" { - abort (); + return (get_attr_length (insn) == 4 + ? "b %l0" : "l r15,=a(%l0); br r15"); } - #endif + [(set (attr "length") + (if_then_else (lt (match_dup 0) (const_int 4096)) + (const_int 4) + (const_int 6)))]) + + +File: gccint.info, Node: Constant Attributes, Next: Delay Slots, Prev: Insn Lengths, Up: Insn Attributes + +9.18.6 Constant Attributes +-------------------------- + +A special form of `define_attr', where the expression for the default +value is a `const' expression, indicates an attribute that is constant +for a given run of the compiler. Constant attributes may be used to +specify which variety of processor is used. For example, + + (define_attr "cpu" "m88100,m88110,m88000" + (const + (cond [(symbol_ref "TARGET_88100") (const_string "m88100") + (symbol_ref "TARGET_88110") (const_string "m88110")] + (const_string "m88000")))) + + (define_attr "memory" "fast,slow" + (const + (if_then_else (symbol_ref "TARGET_FAST_MEM") + (const_string "fast") + (const_string "slow")))) + + The routine generated for constant attributes has no parameters as it +does not depend on any particular insn. RTL expressions used to define +the value of a constant attribute may use the `symbol_ref' form, but +may not use either the `match_operand' form or `eq_attr' forms +involving insn attributes. + + +File: gccint.info, Node: Delay Slots, Next: Function Units, Prev: Constant Attributes, Up: Insn Attributes + +9.18.7 Delay Slot Scheduling +---------------------------- -will also be needed so that linking still succeeds when the test is run -without optimization. When all calls to a built-in function should -have been optimized and no calls to the non-built-in version of the -function should remain, that function may be defined as `static' to -call `abort ()' (although redeclaring a function as static may not work -on all targets). +The insn attribute mechanism can be used to specify the requirements for +delay slots, if any, on a target machine. An instruction is said to +require a "delay slot" if some instructions that are physically after +the instruction are executed as if they were located before it. +Classic examples are branch and call instructions, which often execute +the following instruction before the branch or call is performed. + + On some machines, conditional branch instructions can optionally +"annul" instructions in the delay slot. This means that the +instruction will not be executed for certain branch outcomes. Both +instructions that annul if the branch is true and instructions that +annul if the branch is false are supported. + + Delay slot scheduling differs from instruction scheduling in that +determining whether an instruction needs a delay slot is dependent only +on the type of instruction being generated, not on data flow between the +instructions. See the next section for a discussion of data-dependent +instruction scheduling. + + The requirement of an insn needing one or more delay slots is +indicated via the `define_delay' expression. It has the following form: + + (define_delay TEST + [DELAY-1 ANNUL-TRUE-1 ANNUL-FALSE-1 + DELAY-2 ANNUL-TRUE-2 ANNUL-FALSE-2 + ...]) + + TEST is an attribute test that indicates whether this `define_delay' +applies to a particular insn. If so, the number of required delay +slots is determined by the length of the vector specified as the second +argument. An insn placed in delay slot N must satisfy attribute test +DELAY-N. ANNUL-TRUE-N is an attribute test that specifies which insns +may be annulled if the branch is true. Similarly, ANNUL-FALSE-N +specifies which insns in the delay slot may be annulled if the branch +is false. If annulling is not supported for that delay slot, `(nil)' +should be coded. + + For example, in the common case where branch and call insns require +a single delay slot, which may contain any insn other than a branch or +call, the following would be placed in the `md' file: + + (define_delay (eq_attr "type" "branch,call") + [(eq_attr "type" "!branch,call") (nil) (nil)]) + + Multiple `define_delay' expressions may be specified. In this case, +each such expression specifies different delay slot requirements and +there must be no insn for which tests in two `define_delay' expressions +are both true. + + For example, if we have a machine that requires one delay slot for +branches but two for calls, no delay slot can contain a branch or call +insn, and any valid insn in the delay slot for the branch can be +annulled if the branch is true, we might represent this as follows: + + (define_delay (eq_attr "type" "branch") + [(eq_attr "type" "!branch,call") + (eq_attr "type" "!branch,call") + (nil)]) + + (define_delay (eq_attr "type" "call") + [(eq_attr "type" "!branch,call") (nil) (nil) + (eq_attr "type" "!branch,call") (nil) (nil)]) - FIXME: discuss non-C test suites here. + +File: gccint.info, Node: Function Units, Prev: Delay Slots, Up: Insn Attributes + +9.18.8 Specifying Function Units +-------------------------------- + +On most RISC machines, there are instructions whose results are not +available for a specific number of cycles. Common cases are +instructions that load data from memory. On many machines, a pipeline +stall will result if the data is referenced too soon after the load +instruction. + + In addition, many newer microprocessors have multiple function +units, usually one for integer and one for floating point, and often +will incur pipeline stalls when a result that is needed is not yet +ready. + + The descriptions in this section allow the specification of how much +time must elapse between the execution of an instruction and the time +when its result is used. It also allows specification of when the +execution of an instruction will delay execution of similar instructions +due to function unit conflicts. + + For the purposes of the specifications in this section, a machine is +divided into "function units", each of which execute a specific class +of instructions in first-in-first-out order. Function units that +accept one instruction each cycle and allow a result to be used in the +succeeding instruction (usually via forwarding) need not be specified. +Classic RISC microprocessors will normally have a single function unit, +which we can call `memory'. The newer "superscalar" processors will +often have function units for floating point operations, usually at +least a floating point adder and multiplier. + + Each usage of a function units by a class of insns is specified with +a `define_function_unit' expression, which looks like this: + + (define_function_unit NAME MULTIPLICITY SIMULTANEITY + TEST READY-DELAY ISSUE-DELAY + [CONFLICT-LIST]) + + NAME is a string giving the name of the function unit. + + MULTIPLICITY is an integer specifying the number of identical units +in the processor. If more than one unit is specified, they will be +scheduled independently. Only truly independent units should be +counted; a pipelined unit should be specified as a single unit. (The +only common example of a machine that has multiple function units for a +single instruction class that are truly independent and not pipelined +are the two multiply and two increment units of the CDC 6600.) + + SIMULTANEITY specifies the maximum number of insns that can be +executing in each instance of the function unit simultaneously or zero +if the unit is pipelined and has no limit. + + All `define_function_unit' definitions referring to function unit +NAME must have the same name and values for MULTIPLICITY and +SIMULTANEITY. + + TEST is an attribute test that selects the insns we are describing +in this definition. Note that an insn may use more than one function +unit and a function unit may be specified in more than one +`define_function_unit'. + + READY-DELAY is an integer that specifies the number of cycles after +which the result of the instruction can be used without introducing any +stalls. + + ISSUE-DELAY is an integer that specifies the number of cycles after +the instruction matching the TEST expression begins using this unit +until a subsequent instruction can begin. A cost of N indicates an N-1 +cycle delay. A subsequent instruction may also be delayed if an +earlier instruction has a longer READY-DELAY value. This blocking +effect is computed using the SIMULTANEITY, READY-DELAY, ISSUE-DELAY, +and CONFLICT-LIST terms. For a normal non-pipelined function unit, +SIMULTANEITY is one, the unit is taken to block for the READY-DELAY +cycles of the executing insn, and smaller values of ISSUE-DELAY are +ignored. + + CONFLICT-LIST is an optional list giving detailed conflict costs for +this unit. If specified, it is a list of condition test expressions to +be applied to insns chosen to execute in NAME following the particular +insn matching TEST that is already executing in NAME. For each insn in +the list, ISSUE-DELAY specifies the conflict cost; for insns not in the +list, the cost is zero. If not specified, CONFLICT-LIST defaults to +all instructions that use the function unit. + + Typical uses of this vector are where a floating point function unit +can pipeline either single- or double-precision operations, but not +both, or where a memory unit can pipeline loads, but not stores, etc. + + As an example, consider a classic RISC machine where the result of a +load instruction is not available for two cycles (a single "delay" +instruction is required) and where only one load instruction can be +executed simultaneously. This would be specified as: + + (define_function_unit "memory" 1 1 (eq_attr "type" "load") 2 0) + + For the case of a floating point function unit that can pipeline +either single or double precision, but not both, the following could be +specified: + + (define_function_unit + "fp" 1 0 (eq_attr "type" "sp_fp") 4 4 [(eq_attr "type" "dp_fp")]) + (define_function_unit + "fp" 1 0 (eq_attr "type" "dp_fp") 4 4 [(eq_attr "type" "sp_fp")]) + + *Note_* The scheduler attempts to avoid function unit conflicts and +uses all the specifications in the `define_function_unit' expression. +It has recently come to our attention that these specifications may not +allow modeling of some of the newer "superscalar" processors that have +insns using multiple pipelined units. These insns will cause a +potential conflict for the second unit used during their execution and +there is no way of representing that conflict. We welcome any examples +of how function unit conflicts work in such processors and suggestions +for their representation. + + +File: gccint.info, Node: Conditional Execution, Next: Constant Definitions, Prev: Insn Attributes, Up: Machine Desc + +9.19 Conditional Execution +========================== + +A number of architectures provide for some form of conditional +execution, or predication. The hallmark of this feature is the ability +to nullify most of the instructions in the instruction set. When the +instruction set is large and not entirely symmetric, it can be quite +tedious to describe these forms directly in the `.md' file. An +alternative is the `define_cond_exec' template. + + (define_cond_exec + [PREDICATE-PATTERN] + "CONDITION" + "OUTPUT-TEMPLATE") + + PREDICATE-PATTERN is the condition that must be true for the insn to +be executed at runtime and should match a relational operator. One can +use `match_operator' to match several relational operators at once. +Any `match_operand' operands must have no more than one alternative. + + CONDITION is a C expression that must be true for the generated +pattern to match. + + OUTPUT-TEMPLATE is a string similar to the `define_insn' output +template (*note Output Template::), except that the `*' and `@' special +cases do not apply. This is only useful if the assembly text for the +predicate is a simple prefix to the main insn. In order to handle the +general case, there is a global variable `current_insn_predicate' that +will contain the entire predicate if the current insn is predicated, +and will otherwise be `NULL'. + + When `define_cond_exec' is used, an implicit reference to the +`predicable' instruction attribute is made. *Note Insn Attributes::. +This attribute must be boolean (i.e. have exactly two elements in its +LIST-OF-VALUES). Further, it must not be used with complex +expressions. That is, the default and all uses in the insns must be a +simple constant, not dependent on the alternative or anything else. + + For each `define_insn' for which the `predicable' attribute is true, +a new `define_insn' pattern will be generated that matches a predicated +version of the instruction. For example, + + (define_insn "addsi" + [(set (match_operand:SI 0 "register_operand" "r") + (plus:SI (match_operand:SI 1 "register_operand" "r") + (match_operand:SI 2 "register_operand" "r")))] + "TEST1" + "add %2,%1,%0") + + (define_cond_exec + [(ne (match_operand:CC 0 "register_operand" "c") + (const_int 0))] + "TEST2" + "(%0)") + +generates a new pattern + + (define_insn "" + [(cond_exec + (ne (match_operand:CC 3 "register_operand" "c") (const_int 0)) + (set (match_operand:SI 0 "register_operand" "r") + (plus:SI (match_operand:SI 1 "register_operand" "r") + (match_operand:SI 2 "register_operand" "r"))))] + "(TEST2) && (TEST1)" + "(%3) add %2,%1,%0") + + +File: gccint.info, Node: Constant Definitions, Prev: Conditional Execution, Up: Machine Desc + +9.20 Constant Definitions +========================= + +Using literal constants inside instruction patterns reduces legibility +and can be a maintenance problem. + + To overcome this problem, you may use the `define_constants' +expression. It contains a vector of name-value pairs. From that point +on, wherever any of the names appears in the MD file, it is as if the +corresponding value had been written instead. You may use +`define_constants' multiple times; each appearance adds more constants +to the table. It is an error to redefine a constant with a different +value. + + To come back to the a29k load multiple example, instead of + + (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") + + You could write: + + (define_constants [ + (R_BP 177) + (R_FC 178) + (R_CR 179) + (R_Q 180) + ]) + + (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 R_CR)) + (clobber (reg:SI R_CR))])] + "" + "loadm 0,0,%1,%2") + + The constants that are defined with a define_constant are also output +in the insn-codes.h header file as #defines.  -File: gccint.info, Node: C Tests, Next: libgcj Tests, Prev: Test Idioms, Up: Test Suites +File: gccint.info, Node: Target Macros, Next: Host Config, Prev: Machine Desc, Up: Top + +10 Target Description Macros and Functions +****************************************** + +In addition to the file `MACHINE.md', a machine description includes a +C header file conventionally given the name `MACHINE.h' and a C source +file named `MACHINE.c'. The header file defines numerous macros that +convey the information about the target machine that does not fit into +the scheme of the `.md' file. The file `tm.h' should be a link to +`MACHINE.h'. The header file `config.h' includes `tm.h' and most +compiler source files include `config.h'. The source file defines a +variable `targetm', which is a structure containing pointers to +functions and data relating to the target machine. `MACHINE.c' should +also contain their definitions, if they are not defined elsewhere in +GCC, and other functions called through the macros defined in the `.h' +file. -C Language Test Suites ----------------------- +* Menu: - GCC contains the following C language test suites, in the -`gcc/testsuite' directory: +* Target Structure:: The `targetm' variable. +* Driver:: Controlling how the driver runs the compilation passes. +* Run-time Target:: Defining `-m' options like `-m68000' and `-m68020'. +* Per-Function Data:: Defining data structures for per-function information. +* Storage Layout:: Defining sizes and alignments of data. +* Type Layout:: Defining sizes and properties of basic user data types. +* Escape Sequences:: Defining the value of target character escape sequences +* Registers:: Naming and describing the hardware registers. +* Register Classes:: Defining the classes of hardware registers. +* Stack and Calling:: Defining which way the stack grows and by how much. +* Varargs:: Defining the varargs macros. +* Trampolines:: Code set up at run time to enter a nested function. +* Library Calls:: Controlling how library routines are implicitly called. +* Addressing Modes:: Defining addressing modes valid for memory operands. +* Condition Code:: Defining how insns update the condition code. +* Costs:: Defining relative costs of different operations. +* Scheduling:: Adjusting the behavior of the instruction scheduler. +* Sections:: Dividing storage into text, data, and other sections. +* PIC:: Macros for position independent code. +* Assembler Format:: Defining how to write insns and pseudo-ops to output. +* Debugging Info:: Defining the format of debugging output. +* Cross-compilation:: Handling floating point for cross-compilers. +* Mode Switching:: Insertion of mode-switching instructions. +* Target Attributes:: Defining target-specific uses of `__attribute__'. +* Misc:: Everything else. -`gcc.c-torture/compat' - FIXME: describe this. + +File: gccint.info, Node: Target Structure, Next: Driver, Up: Target Macros - This directory should probably not be used for new tests. +10.1 The Global `targetm' Variable +================================== -`gcc.c-torture/compile' - This test suite contains test cases that should compile, but do not - need to link or run. These test cases are compiled with several - different combinations of optimization options. All warnings are - disabled for these test cases, so this directory is not suitable if - you wish to test for the presence or absence of compiler warnings. - While special options can be set, and tests disabled on specific - platforms, by the use of `.x' files, mostly these test cases - should not contain platform dependencies. FIXME: discuss how - defines such as `NO_LABEL_VALUES' and `STACK_SIZE' are used. + -- Variable: struct gcc_target targetm + The target `.c' file must define the global `targetm' variable + which contains pointers to functions and data relating to the + target machine. The variable is declared in `target.h'; + `target-def.h' defines the macro `TARGET_INITIALIZER' which is + used to initialize the variable, and macros for the default + initializers for elements of the structure. The `.c' file should + override those macros for which the default definition is + inappropriate. For example: + #include "target.h" + #include "target-def.h" -`gcc.c-torture/execute' - This test suite contains test cases that should compile, link and - run; otherwise the same comments as for `gcc.c-torture/compile' - apply. - -`gcc.c-torture/unsorted' - FIXME: describe this. + /* Initialize the GCC target structure. */ - This directory should probably not be used for new tests. - -`gcc.dg' - This test suite contains tests using the more modern `dg' harness. - Magic comments determine whether the file is preprocessed, - compiled, linked or run. In these tests, error and warning - message texts are compared against expected texts or regular - expressions given in comments. These tests are run with the - options `-ansi -pedantic' unless other options are given in the - test. Except as noted below they are not run with multiple - optimization options. + #undef TARGET_COMP_TYPE_ATTRIBUTES + #define TARGET_COMP_TYPE_ATTRIBUTES MACHINE_comp_type_attributes -`gcc.dg/cpp' - This subdirectory contains tests of the preprocessor. + struct gcc_target targetm = TARGET_INITIALIZER; -`gcc.dg/debug' - This subdirectory contains tests for debug formats. Tests in this - subdirectory are run for each debug format that the compiler - supports. +Where a macro should be defined in the `.c' file in this manner to form +part of the `targetm' structure, it is documented below as a "Target +Hook" with a prototype. Many macros will change in future from being +defined in the `.h' file to being part of the `targetm' structure. -`gcc.dg/format' - This subdirectory contains tests of the `-Wformat' format - checking. Tests in this directory are run with and without - `-DWIDE'. - -`gcc.dg/noncompile' - This subdirectory contains tests of code that should not compile - and does not need any special compilation options. They are run - with multiple optimization options, since sometimes invalid code - crashes the compiler with optimization. - -`gcc.dg/special' - FIXME: describe this. - -`gcc.c-torture/misc-tests' - FIXME: describe this, when it should be used for new tests and - when it shouldn't. - - FIXME: merge in `testsuite/README.gcc' and discuss the format of -test cases and magic comments more. - - -File: gccint.info, Node: libgcj Tests, Prev: C Tests, Up: Test Suites - -The Java library test suites. ------------------------------ - - Runtime tests are executed via `make check' from the `testsuite' -directory of the libjava hierarchy in the build tree. Additional -runtime tests can be checked into this testsuite. - - Regression testing of the core packages in libgcj is also covered by -the Mauve test suite. The Mauve Project develops tests for the Java -Class Libraries. These tests are run as part of libgcj testing by -specifying the location of the Mauve tree when invoking `make', as in -`make MAUVEDIR=~/mauve check'. - - The Jacks project provides a test suite for Java compilers that can -be used to test changes that affect the GCJ front end. There is no -automated mechanism to run the Jacks suite as part of GCJ testing. - - We encourage developers to contribute test cases to Mauve and Jacks. - - -File: gccint.info, Node: Passes, Next: Trees, Prev: Source Tree, Up: Top - -Passes and Files of the Compiler -******************************** - - The overall control structure of the compiler is in `toplev.c'. This -file is responsible for initialization, decoding arguments, opening and -closing files, and sequencing the passes. - - The parsing pass is invoked only once, to parse the entire input. A -high level tree representation is then generated from the input, one -function at a time. This tree code is then transformed into RTL -intermediate code, and processed. The files involved in transforming -the trees into RTL are `expr.c', `expmed.c', and `stmt.c'. The order -of trees that are processed, is not necessarily the same order they are -generated from the input, due to deferred inlining, and other -considerations. - - Each time the parsing pass reads a complete function definition or -top-level declaration, it calls either the function -`rest_of_compilation', or the function `rest_of_decl_compilation' in -`toplev.c', which are responsible for all further processing necessary, -ending with output of the assembler language. All other compiler -passes run, in sequence, within `rest_of_compilation'. When that -function returns from compiling a function definition, the storage used -for that function definition's compilation is entirely freed, unless it -is an inline function, or was deferred for some reason (this can occur -in templates, for example). (*note An Inline Function is As Fast As a -Macro: (gcc)Inline.). - - Here is a list of all the passes of the compiler and their source -files. Also included is a description of where debugging dumps can be -requested with `-d' options. - - * Parsing. This pass reads the entire text of a function definition, - constructing a high level tree representation. (Because of the - semantic analysis that takes place during this pass, it does more - than is formally considered to be parsing.) - - The tree representation does not entirely follow C syntax, because - it is intended to support other languages as well. - - Language-specific data type analysis is also done in this pass, - and every tree node that represents an expression has a data type - attached. Variables are represented as declaration nodes. - - The language-independent source files for parsing are `tree.c', - `fold-const.c', and `stor-layout.c'. There are also header files - `tree.h' and `tree.def' which define the format of the tree - representation. - - C preprocessing, for language front ends, that want or require it, - is performed by cpplib, which is covered in separate - documentation. In particular, the internals are covered in *Note - Cpplib internals: (cppinternals)Top. - - The source files to parse C are `c-convert.c', `c-decl.c', - `c-errors.c', `c-lang.c', `c-objc-common.c', `c-parse.in', - `c-aux-info.c', and `c-typeck.c', along with a header file - `c-tree.h' and some files shared with Objective-C and C++. - - The source files for parsing C++ are in `cp/'. They are `parse.y', - `class.c', `cvt.c', `decl.c', `decl2.c', `except.c', `expr.c', - `init.c', `lex.c', `method.c', `ptree.c', `search.c', `spew.c', - `semantics.c', `tree.c', `typeck2.c', and `typeck.c', along with - header files `cp-tree.def', `cp-tree.h', and `decl.h'. - - The special source files for parsing Objective-C are in `objc/'. - They are `objc-act.c', `objc-tree.def', and `objc-act.h'. Certain - C-specific files are used for this as well. - - The files `c-common.c', `c-common.def', `c-format.c', `c-pragma.c', - `c-semantics.c', and `c-lex.c', along with header files - `c-common.h', `c-dump.h', `c-lex.h', and `c-pragma.h', are also - used for all of the above languages. - - * Tree optimization. This is the optimization of the tree - representation, before converting into RTL code. - - Currently, the main optimization performed here is tree-based - inlining. This is implemented in `tree-inline.c' and used by both - C and C++. Note that tree based inlining turns off rtx based - inlining (since it's more powerful, it would be a waste of time to - do rtx based inlining in addition). - - Constant folding and some arithmetic simplifications are also done - during this pass, on the tree representation. The routines that - perform these tasks are located in `fold-const.c'. - - * RTL generation. This is the conversion of syntax tree into RTL - code. + +File: gccint.info, Node: Driver, Next: Run-time Target, Prev: Target Structure, Up: Target Macros + +10.2 Controlling the Compilation Driver, `gcc' +============================================== + +You can control the compilation driver. + +`SWITCH_TAKES_ARG (CHAR)' + A C expression which determines whether the option `-CHAR' takes + arguments. The value should be the number of arguments that + option takes-zero, for many options. + + By default, this macro is defined as `DEFAULT_SWITCH_TAKES_ARG', + which handles the standard options properly. You need not define + `SWITCH_TAKES_ARG' unless you wish to add additional options which + take arguments. Any redefinition should call + `DEFAULT_SWITCH_TAKES_ARG' and then check for additional options. + +`WORD_SWITCH_TAKES_ARG (NAME)' + A C expression which determines whether the option `-NAME' takes + arguments. The value should be the number of arguments that + option takes-zero, for many options. This macro rather than + `SWITCH_TAKES_ARG' is used for multi-character option names. + + By default, this macro is defined as + `DEFAULT_WORD_SWITCH_TAKES_ARG', which handles the standard options + properly. You need not define `WORD_SWITCH_TAKES_ARG' unless you + wish to add additional options which take arguments. Any + redefinition should call `DEFAULT_WORD_SWITCH_TAKES_ARG' and then + check for additional options. + +`SWITCH_CURTAILS_COMPILATION (CHAR)' + A C expression which determines whether the option `-CHAR' stops + compilation before the generation of an executable. The value is + boolean, nonzero if the option does stop an executable from being + generated, zero otherwise. + + By default, this macro is defined as + `DEFAULT_SWITCH_CURTAILS_COMPILATION', which handles the standard + options properly. You need not define + `SWITCH_CURTAILS_COMPILATION' unless you wish to add additional + options which affect the generation of an executable. Any + redefinition should call `DEFAULT_SWITCH_CURTAILS_COMPILATION' and + then check for additional options. + +`SWITCHES_NEED_SPACES' + A string-valued C expression which enumerates the options for which + the linker needs a space between the option and its argument. + + If this macro is not defined, the default value is `""'. + +`TARGET_OPTION_TRANSLATE_TABLE' + If defined, a list of pairs of strings, the first of which is a + potential command line target to the `gcc' driver program, and the + second of which is a space-separated (tabs and other whitespace + are not supported) list of options with which to replace the first + option. The target defining this list is responsible for assuring + that the results are valid. Replacement options may not be the + `--opt' style, they must be the `-opt' style. It is the intention + of this macro to provide a mechanism for substitution that affects + the multilibs chosen, such as one option that enables many + options, some of which select multilibs. Example nonsensical + definition, where `-malt-abi', `-EB', and `-mspoo' cause different + multilibs to be chosen: + + #define TARGET_OPTION_TRANSLATE_TABLE \ + { "-fast", "-march=fast-foo -malt-abi -I/usr/fast-foo" }, \ + { "-compat", "-EB -malign=4 -mspoo" } + +`CPP_SPEC' + A C string constant that tells the GCC driver program options to + pass to CPP. It can also specify how to translate options you + give to GCC into options for GCC to pass to the CPP. + + Do not define this macro if it does not need to do anything. + +`CPLUSPLUS_CPP_SPEC' + This macro is just like `CPP_SPEC', but is used for C++, rather + than C. If you do not define this macro, then the value of + `CPP_SPEC' (if any) will be used instead. + +`NO_BUILTIN_SIZE_TYPE' + If this macro is defined, the preprocessor will not define the + built-in macro `__SIZE_TYPE__'. The macro `__SIZE_TYPE__' must + then be defined by `CPP_SPEC' instead. + + This should be defined if `SIZE_TYPE' depends on target dependent + flags which are not accessible to the preprocessor. Otherwise, it + should not be defined. + +`NO_BUILTIN_PTRDIFF_TYPE' + If this macro is defined, the preprocessor will not define the + built-in macro `__PTRDIFF_TYPE__'. The macro `__PTRDIFF_TYPE__' + must then be defined by `CPP_SPEC' instead. + + This should be defined if `PTRDIFF_TYPE' depends on target + dependent flags which are not accessible to the preprocessor. + Otherwise, it should not be defined. + +`NO_BUILTIN_WCHAR_TYPE' + If this macro is defined, the preprocessor will not define the + built-in macro `__WCHAR_TYPE__'. The macro `__WCHAR_TYPE__' must + then be defined by `CPP_SPEC' instead. + + This should be defined if `WCHAR_TYPE' depends on target dependent + flags which are not accessible to the preprocessor. Otherwise, it + should not be defined. + +`NO_BUILTIN_WINT_TYPE' + If this macro is defined, the preprocessor will not define the + built-in macro `__WINT_TYPE__'. The macro `__WINT_TYPE__' must + then be defined by `CPP_SPEC' instead. + + This should be defined if `WINT_TYPE' depends on target dependent + flags which are not accessible to the preprocessor. Otherwise, it + should not be defined. + +`CC1_SPEC' + A C string constant that tells the GCC driver program options to + pass to `cc1', `cc1plus', `f771', and the other language front + ends. It can also specify how to translate options you give to + GCC into options for GCC to pass to front ends. + + Do not define this macro if it does not need to do anything. + +`CC1PLUS_SPEC' + A C string constant that tells the GCC driver program options to + pass to `cc1plus'. It can also specify how to translate options + you give to GCC into options for GCC to pass to the `cc1plus'. + + Do not define this macro if it does not need to do anything. Note + that everything defined in CC1_SPEC is already passed to `cc1plus' + so there is no need to duplicate the contents of CC1_SPEC in + CC1PLUS_SPEC. + +`ASM_SPEC' + A C string constant that tells the GCC driver program options to + pass to the assembler. It can also specify how to translate + options you give to GCC into options for GCC to pass to the + assembler. See the file `sun3.h' for an example of this. + + Do not define this macro if it does not need to do anything. + +`ASM_FINAL_SPEC' + A C string constant that tells the GCC driver program how to run + any programs which cleanup after the normal assembler. Normally, + this is not needed. See the file `mips.h' for an example of this. + + Do not define this macro if it does not need to do anything. + +`LINK_SPEC' + A C string constant that tells the GCC driver program options to + pass to the linker. It can also specify how to translate options + you give to GCC into options for GCC to pass to the linker. + + Do not define this macro if it does not need to do anything. + +`LIB_SPEC' + Another C string constant used much like `LINK_SPEC'. The + difference between the two is that `LIB_SPEC' is used at the end + of the command given to the linker. + + If this macro is not defined, a default is provided that loads the + standard C library from the usual place. See `gcc.c'. + +`LIBGCC_SPEC' + Another C string constant that tells the GCC driver program how + and when to place a reference to `libgcc.a' into the linker + command line. This constant is placed both before and after the + value of `LIB_SPEC'. + + If this macro is not defined, the GCC driver provides a default + that passes the string `-lgcc' to the linker. + +`STARTFILE_SPEC' + Another C string constant used much like `LINK_SPEC'. The + difference between the two is that `STARTFILE_SPEC' is used at the + very beginning of the command given to the linker. + + If this macro is not defined, a default is provided that loads the + standard C startup file from the usual place. See `gcc.c'. + +`ENDFILE_SPEC' + Another C string constant used much like `LINK_SPEC'. The + difference between the two is that `ENDFILE_SPEC' is used at the + very end of the command given to the linker. + + Do not define this macro if it does not need to do anything. + +`THREAD_MODEL_SPEC' + GCC `-v' will print the thread model GCC was configured to use. + However, this doesn't work on platforms that are multilibbed on + thread models, such as AIX 4.3. On such platforms, define + `THREAD_MODEL_SPEC' such that it evaluates to a string without + blanks that names one of the recognized thread models. `%*', the + default value of this macro, will expand to the value of + `thread_file' set in `config.gcc'. + +`EXTRA_SPECS' + Define this macro to provide additional specifications to put in + the `specs' file that can be used in various specifications like + `CC1_SPEC'. + + The definition should be an initializer for an array of structures, + containing a string constant, that defines the specification name, + and a string constant that provides the specification. + + Do not define this macro if it does not need to do anything. + + `EXTRA_SPECS' is useful when an architecture contains several + related targets, which have various `..._SPECS' which are similar + to each other, and the maintainer would like one central place to + keep these definitions. + + For example, the PowerPC System V.4 targets use `EXTRA_SPECS' to + define either `_CALL_SYSV' when the System V calling sequence is + used or `_CALL_AIX' when the older AIX-based calling sequence is + used. + + The `config/rs6000/rs6000.h' target file defines: + + #define EXTRA_SPECS \ + { "cpp_sysv_default", CPP_SYSV_DEFAULT }, + + #define CPP_SYS_DEFAULT "" + + The `config/rs6000/sysv.h' target file defines: + #undef CPP_SPEC + #define CPP_SPEC \ + "%{posix: -D_POSIX_SOURCE } \ + %{mcall-sysv: -D_CALL_SYSV } %{mcall-aix: -D_CALL_AIX } \ + %{!mcall-sysv: %{!mcall-aix: %(cpp_sysv_default) }} \ + %{msoft-float: -D_SOFT_FLOAT} %{mcpu=403: -D_SOFT_FLOAT}" + + #undef CPP_SYSV_DEFAULT + #define CPP_SYSV_DEFAULT "-D_CALL_SYSV" + + while the `config/rs6000/eabiaix.h' target file defines + `CPP_SYSV_DEFAULT' as: + + #undef CPP_SYSV_DEFAULT + #define CPP_SYSV_DEFAULT "-D_CALL_AIX" + +`LINK_LIBGCC_SPECIAL' + Define this macro if the driver program should find the library + `libgcc.a' itself and should not pass `-L' options to the linker. + If you do not define this macro, the driver program will pass the + argument `-lgcc' to tell the linker to do the search and will pass + `-L' options to it. + +`LINK_LIBGCC_SPECIAL_1' + Define this macro if the driver program should find the library + `libgcc.a'. If you do not define this macro, the driver program + will pass the argument `-lgcc' to tell the linker to do the search. + This macro is similar to `LINK_LIBGCC_SPECIAL', except that it does + not affect `-L' options. + +`LINK_GCC_C_SEQUENCE_SPEC' + The sequence in which libgcc and libc are specified to the linker. + By default this is `%G %L %G'. + +`LINK_COMMAND_SPEC' + A C string constant giving the complete command line need to + execute the linker. When you do this, you will need to update + your port each time a change is made to the link command line + within `gcc.c'. Therefore, define this macro only if you need to + completely redefine the command line for invoking the linker and + there is no other way to accomplish the effect you need. + Overriding this macro may be avoidable by overriding + `LINK_GCC_C_SEQUENCE_SPEC' instead. + +`LINK_ELIMINATE_DUPLICATE_LDIRECTORIES' + A nonzero value causes `collect2' to remove duplicate + `-LDIRECTORY' search directories from linking commands. Do not + give it a nonzero value if removing duplicate search directories + changes the linker's semantics. + +`MULTILIB_DEFAULTS' + Define this macro as a C expression for the initializer of an + array of string to tell the driver program which options are + defaults for this target and thus do not need to be handled + specially when using `MULTILIB_OPTIONS'. + + Do not define this macro if `MULTILIB_OPTIONS' is not defined in + the target makefile fragment or if none of the options listed in + `MULTILIB_OPTIONS' are set by default. *Note Target Fragment::. + +`RELATIVE_PREFIX_NOT_LINKDIR' + Define this macro to tell `gcc' that it should only translate a + `-B' prefix into a `-L' linker option if the prefix indicates an + absolute file name. + +`STANDARD_EXEC_PREFIX' + Define this macro as a C string constant if you wish to override + the standard choice of `/usr/local/lib/gcc-lib/' as the default + prefix to try when searching for the executable files of the + compiler. + +`MD_EXEC_PREFIX' + If defined, this macro is an additional prefix to try after + `STANDARD_EXEC_PREFIX'. `MD_EXEC_PREFIX' is not searched when the + `-b' option is used, or the compiler is built as a cross compiler. + If you define `MD_EXEC_PREFIX', then be sure to add it to the list + of directories used to find the assembler in `configure.in'. + +`STANDARD_STARTFILE_PREFIX' + Define this macro as a C string constant if you wish to override + the standard choice of `/usr/local/lib/' as the default prefix to + try when searching for startup files such as `crt0.o'. + +`MD_STARTFILE_PREFIX' + If defined, this macro supplies an additional prefix to try after + the standard prefixes. `MD_EXEC_PREFIX' is not searched when the + `-b' option is used, or when the compiler is built as a cross + compiler. + +`MD_STARTFILE_PREFIX_1' + If defined, this macro supplies yet another prefix to try after the + standard prefixes. It is not searched when the `-b' option is + used, or when the compiler is built as a cross compiler. + +`INIT_ENVIRONMENT' + Define this macro as a C string constant if you wish to set + environment variables for programs called by the driver, such as + the assembler and loader. The driver passes the value of this + macro to `putenv' to initialize the necessary environment + variables. + +`LOCAL_INCLUDE_DIR' + Define this macro as a C string constant if you wish to override + the standard choice of `/usr/local/include' as the default prefix + to try when searching for local header files. `LOCAL_INCLUDE_DIR' + comes before `SYSTEM_INCLUDE_DIR' in the search order. + + Cross compilers do not search either `/usr/local/include' or its + replacement. + +`MODIFY_TARGET_NAME' + Define this macro if you with to define command-line switches that + modify the default target name + + For each switch, you can include a string to be appended to the + first part of the configuration name or a string to be deleted + from the configuration name, if present. The definition should be + an initializer for an array of structures. Each array element + should have three elements: the switch name (a string constant, + including the initial dash), one of the enumeration codes `ADD' or + `DELETE' to indicate whether the string should be inserted or + deleted, and the string to be inserted or deleted (a string + constant). + + For example, on a machine where `64' at the end of the + configuration name denotes a 64-bit target and you want the `-32' + and `-64' switches to select between 32- and 64-bit targets, you + would code + + #define MODIFY_TARGET_NAME \ + { { "-32", DELETE, "64"}, \ + {"-64", ADD, "64"}} + +`SYSTEM_INCLUDE_DIR' + Define this macro as a C string constant if you wish to specify a + system-specific directory to search for header files before the + standard directory. `SYSTEM_INCLUDE_DIR' comes before + `STANDARD_INCLUDE_DIR' in the search order. + + Cross compilers do not use this macro and do not search the + directory specified. + +`STANDARD_INCLUDE_DIR' + Define this macro as a C string constant if you wish to override + the standard choice of `/usr/include' as the default prefix to try + when searching for header files. + + Cross compilers do not use this macro and do not search either + `/usr/include' or its replacement. + +`STANDARD_INCLUDE_COMPONENT' + The "component" corresponding to `STANDARD_INCLUDE_DIR'. See + `INCLUDE_DEFAULTS', below, for the description of components. If + you do not define this macro, no component is used. + +`INCLUDE_DEFAULTS' + Define this macro if you wish to override the entire default + search path for include files. For a native compiler, the default + search path usually consists of `GCC_INCLUDE_DIR', + `LOCAL_INCLUDE_DIR', `SYSTEM_INCLUDE_DIR', + `GPLUSPLUS_INCLUDE_DIR', and `STANDARD_INCLUDE_DIR'. In addition, + `GPLUSPLUS_INCLUDE_DIR' and `GCC_INCLUDE_DIR' are defined + automatically by `Makefile', and specify private search areas for + GCC. The directory `GPLUSPLUS_INCLUDE_DIR' is used only for C++ + programs. + + The definition should be an initializer for an array of structures. + Each array element should have four elements: the directory name (a + string constant), the component name (also a string constant), a + flag for C++-only directories, and a flag showing that the + includes in the directory don't need to be wrapped in `extern `C'' + when compiling C++. Mark the end of the array with a null element. + + The component name denotes what GNU package the include file is + part of, if any, in all upper-case letters. For example, it might + be `GCC' or `BINUTILS'. If the package is part of a + vendor-supplied operating system, code the component name as `0'. + + For example, here is the definition used for VAX/VMS: + + #define INCLUDE_DEFAULTS \ + { \ + { "GNU_GXX_INCLUDE:", "G++", 1, 1}, \ + { "GNU_CC_INCLUDE:", "GCC", 0, 0}, \ + { "SYS$SYSROOT:[SYSLIB.]", 0, 0, 0}, \ + { ".", 0, 0, 0}, \ + { 0, 0, 0, 0} \ + } - This is where the bulk of target-parameter-dependent code is found, - since often it is necessary for strategies to apply only when - certain standard kinds of instructions are available. The purpose - of named instruction patterns is to provide this information to - the RTL generation pass. - - Optimization is done in this pass for `if'-conditions that are - comparisons, boolean operations or conditional expressions. Tail - recursion is detected at this time also. Decisions are made about - how best to arrange loops and how to output `switch' statements. - - The source files for RTL generation include `stmt.c', `calls.c', - `expr.c', `explow.c', `expmed.c', `function.c', `optabs.c' and - `emit-rtl.c'. Also, the file `insn-emit.c', generated from the - machine description by the program `genemit', is used in this - pass. The header file `expr.h' is used for communication within - this pass. - - The header files `insn-flags.h' and `insn-codes.h', generated from - the machine description by the programs `genflags' and `gencodes', - tell this pass which standard names are available for use and - which patterns correspond to them. - - Aside from debugging information output, none of the following - passes refers to the tree structure representation of the function - (only part of which is saved). - - The decision of whether the function can and should be expanded - inline in its subsequent callers is made at the end of rtl - generation. The function must meet certain criteria, currently - related to the size of the function and the types and number of - parameters it has. Note that this function may contain loops, - recursive calls to itself (tail-recursive functions can be - inlined!), gotos, in short, all constructs supported by GCC. The - file `integrate.c' contains the code to save a function's rtl for - later inlining and to inline that rtl when the function is called. - The header file `integrate.h' is also used for this purpose. - - The option `-dr' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.rtl' to - the input file name. - - * Sibiling call optimization. This pass performs tail recursion - elimination, and tail and sibling call optimizations. The purpose - of these optimizations is to reduce the overhead of function calls, - whenever possible. - - The source file of this pass is `sibcall.c' - - The option `-di' causes a debugging dump of the RTL code after - this pass is run. This dump file's name is made by appending - `.sibling' to the input file name. - - * Jump optimization. This pass simplifies jumps to the following - instruction, jumps across jumps, and jumps to jumps. It deletes - unreferenced labels and unreachable code, except that unreachable - code that contains a loop is not recognized as unreachable in this - pass. (Such loops are deleted later in the basic block analysis.) - It also converts some code originally written with jumps into - sequences of instructions that directly set values from the - results of comparisons, if the machine has such instructions. - - Jump optimization is performed two or three times. The first time - is immediately following RTL generation. The second time is after - CSE, but only if CSE says repeated jump optimization is needed. - The last time is right before the final pass. That time, - cross-jumping and deletion of no-op move instructions are done - together with the optimizations described above. - - The source file of this pass is `jump.c'. - - The option `-dj' causes a debugging dump of the RTL code after - this pass is run for the first time. This dump file's name is - made by appending `.jump' to the input file name. - - * Register scan. This pass finds the first and last use of each - register, as a guide for common subexpression elimination. Its - source is in `regclass.c'. - - * Jump threading. This pass detects a condition jump that branches - to an identical or inverse test. Such jumps can be `threaded' - through the second conditional test. The source code for this - pass is in `jump.c'. This optimization is only performed if - `-fthread-jumps' is enabled. - - * Static Single Assignment (SSA) based optimization passes. The SSA - conversion passes (to/from) are turned on by the `-fssa' option - (it is also done automatically if you enable an SSA optimization - pass). These passes utilize a form called Static Single - Assignment. In SSA form, each variable (pseudo register) is only - set once, giving you def-use and use-def chains for free, and - enabling a lot more optimization passes to be run in linear time. - Conversion to and from SSA form is handled by functions in `ssa.c'. - - The option `-de' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.ssa' to - the input file name. - * SSA Conditional Constant Propagation. Turned on by the - `-fssa-ccp' option. This pass performs conditional constant - propagation to simplify instructions including conditional - branches. This pass is more aggressive than the constant - propagation done by the CSE and GCSE passes, but operates in - linear time. - - The option `-dW' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending - `.ssaccp' to the input file name. - - * SSA Aggressive Dead Code Elimination. Turned on by the - `-fssa-dce' option. This pass performs elimination of code - considered unnecessary because it has no externally visible - effects on the program. It operates in linear time. - - The option `-dX' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending - `.ssadce' to the input file name. - - * Common subexpression elimination. This pass also does constant - propagation. Its source files are `cse.c', and `cselib.c'. If - constant propagation causes conditional jumps to become - unconditional or to become no-ops, jump optimization is run again - when CSE is finished. - - The option `-ds' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.cse' to - the input file name. - - * Global common subexpression elimination. This pass performs two - different types of GCSE depending on whether you are optimizing - for size or not (LCM based GCSE tends to increase code size for a - gain in speed, while Morel-Renvoise based GCSE does not). When - optimizing for size, GCSE is done using Morel-Renvoise Partial - Redundancy Elimination, with the exception that it does not try to - move invariants out of loops--that is left to the loop - optimization pass. If MR PRE GCSE is done, code hoisting (aka - unification) is also done, as well as load motion. If you are - optimizing for speed, LCM (lazy code motion) based GCSE is done. - LCM is based on the work of Knoop, Ruthing, and Steffen. LCM - based GCSE also does loop invariant code motion. We also perform - load and store motion when optimizing for speed. Regardless of - which type of GCSE is used, the GCSE pass also performs global - constant and copy propagation. - - The source file for this pass is `gcse.c', and the LCM routines - are in `lcm.c'. - - The option `-dG' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.gcse' to - the input file name. - - * Loop optimization. This pass moves constant expressions out of - loops, and optionally does strength-reduction and loop unrolling - as well. Its source files are `loop.c' and `unroll.c', plus the - header `loop.h' used for communication between them. Loop - unrolling uses some functions in `integrate.c' and the header - `integrate.h'. Loop dependency analysis routines are contained in - `dependence.c'. - - The option `-dL' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.loop' to - the input file name. - - * If `-frerun-cse-after-loop' was enabled, a second common - subexpression elimination pass is performed after the loop - optimization pass. Jump threading is also done again at this time - if it was specified. - - The option `-dt' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.cse2' to - the input file name. - - * Data flow analysis (`flow.c'). This pass divides the program into - basic blocks (and in the process deletes unreachable loops); then - it computes which pseudo-registers are live at each point in the - program, and makes the first instruction that uses a value point at - the instruction that computed the value. - - This pass also deletes computations whose results are never used, - and combines memory references with add or subtract instructions - to make autoincrement or autodecrement addressing. - - The option `-df' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.flow' to - the input file name. If stupid register allocation is in use, this - dump file reflects the full results of such allocation. - - * Instruction combination (`combine.c'). This pass attempts to - combine groups of two or three instructions that are related by - data flow into single instructions. It combines the RTL - expressions for the instructions by substitution, simplifies the - result using algebra, and then attempts to match the result - against the machine description. - - The option `-dc' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.combine' - to the input file name. - - * If-conversion is a transformation that transforms control - dependencies into data dependencies (IE it transforms conditional - code into a single control stream). It is implemented in the file - `ifcvt.c'. - - The option `-dE' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.ce' to - the input file name. - - * Register movement (`regmove.c'). This pass looks for cases where - matching constraints would force an instruction to need a reload, - and this reload would be a register-to-register move. It then - attempts to change the registers used by the instruction to avoid - the move instruction. - - The option `-dN' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.regmove' - to the input file name. - - * Instruction scheduling (`sched.c'). This pass looks for - instructions whose output will not be available by the time that - it is used in subsequent instructions. (Memory loads and floating - point instructions often have this behavior on RISC machines). It - re-orders instructions within a basic block to try to separate the - definition and use of items that otherwise would cause pipeline - stalls. - - Instruction scheduling is performed twice. The first time is - immediately after instruction combination and the second is - immediately after reload. - - The option `-dS' causes a debugging dump of the RTL code after this - pass is run for the first time. The dump file's name is made by - appending `.sched' to the input file name. - - * Register class preferencing. The RTL code is scanned to find out - which register class is best for each pseudo register. The source - file is `regclass.c'. - - * Local register allocation (`local-alloc.c'). This pass allocates - hard registers to pseudo registers that are used only within one - basic block. Because the basic block is linear, it can use fast - and powerful techniques to do a very good job. - - The option `-dl' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.lreg' to - the input file name. - - * Global register allocation (`global.c'). This pass allocates hard - registers for the remaining pseudo registers (those whose life - spans are not contained in one basic block). - - * Reloading. This pass renumbers pseudo registers with the hardware - registers numbers they were allocated. Pseudo registers that did - not get hard registers are replaced with stack slots. Then it - finds instructions that are invalid because a value has failed to - end up in a register, or has ended up in a register of the wrong - kind. It fixes up these instructions by reloading the - problematical values temporarily into registers. Additional - instructions are generated to do the copying. - - The reload pass also optionally eliminates the frame pointer and - inserts instructions to save and restore call-clobbered registers - around calls. - - Source files are `reload.c' and `reload1.c', plus the header - `reload.h' used for communication between them. - - The option `-dg' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.greg' to - the input file name. - - * Instruction scheduling is repeated here to try to avoid pipeline - stalls due to memory loads generated for spilled pseudo registers. - - The option `-dR' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.sched2' - to the input file name. - - * Basic block reordering. This pass implements profile guided code - positioning. If profile information is not available, various - types of static analysis are performed to make the predictions - normally coming from the profile feedback (IE execution frequency, - branch probability, etc). It is implemented in the file - `bb-reorder.c', and the various prediction routines are in - `predict.c'. - - The option `-dB' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.bbro' to - the input file name. - - * Delayed branch scheduling. This optional pass attempts to find - instructions that can go into the delay slots of other - instructions, usually jumps and calls. The source file name is - `reorg.c'. - - The option `-dd' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.dbr' to - the input file name. - - * Branch shortening. On many RISC machines, branch instructions - have a limited range. Thus, longer sequences of instructions must - be used for long branches. In this pass, the compiler figures out - what how far each instruction will be from each other instruction, - and therefore whether the usual instructions, or the longer - sequences, must be used for each branch. - - * Conversion from usage of some hard registers to usage of a register - stack may be done at this point. Currently, this is supported only - for the floating-point registers of the Intel 80387 coprocessor. - The source file name is `reg-stack.c'. - - The options `-dk' causes a debugging dump of the RTL code after - this pass. This dump file's name is made by appending `.stack' to - the input file name. - - * Final. This pass outputs the assembler code for the function. It - is also responsible for identifying spurious test and compare - instructions. Machine-specific peephole optimizations are - performed at the same time. The function entry and exit sequences - are generated directly as assembler code in this pass; they never - exist as RTL. - - The source files are `final.c' plus `insn-output.c'; the latter is - generated automatically from the machine description by the tool - `genoutput'. The header file `conditions.h' is used for - communication between these files. - - * Debugging information output. This is run after final because it - must output the stack slot offsets for pseudo registers that did - not get hard registers. Source files are `dbxout.c' for DBX - symbol table format, `sdbout.c' for SDB symbol table format, - `dwarfout.c' for DWARF symbol table format, files `dwarf2out.c' and - `dwarf2asm.c' for DWARF2 symbol table format, and `vmsdbgout.c' - for VMS debug symbol table format. - - Some additional files are used by all or many passes: - - * Every pass uses `machmode.def' and `machmode.h' which define the - machine modes. - - * Several passes use `real.h', which defines the default - representation of floating point constants and how to operate on + Here is the order of prefixes tried for exec files: + + 1. Any prefixes specified by the user with `-B'. + + 2. The environment variable `GCC_EXEC_PREFIX', if any. + + 3. The directories specified by the environment variable + `COMPILER_PATH'. + + 4. The macro `STANDARD_EXEC_PREFIX'. + + 5. `/usr/lib/gcc/'. + + 6. The macro `MD_EXEC_PREFIX', if any. + + Here is the order of prefixes tried for startfiles: + + 1. Any prefixes specified by the user with `-B'. + + 2. The environment variable `GCC_EXEC_PREFIX', if any. + + 3. The directories specified by the environment variable + `LIBRARY_PATH' (or port-specific name; native only, cross + compilers do not use this). + + 4. The macro `STANDARD_EXEC_PREFIX'. + + 5. `/usr/lib/gcc/'. + + 6. The macro `MD_EXEC_PREFIX', if any. + + 7. The macro `MD_STARTFILE_PREFIX', if any. + + 8. The macro `STANDARD_STARTFILE_PREFIX'. + + 9. `/lib/'. + + 10. `/usr/lib/'. + + +File: gccint.info, Node: Run-time Target, Next: Per-Function Data, Prev: Driver, Up: Target Macros + +10.3 Run-time Target Specification +================================== + +Here are run-time target specifications. + +`CPP_PREDEFINES' + Define this to be a string constant containing `-D' options to + define the predefined macros that identify this machine and system. + These macros will be predefined unless the `-ansi' option (or a + `-std' option for strict ISO C conformance) is specified. + + In addition, a parallel set of macros are predefined, whose names + are made by appending `__' at the beginning and at the end. These + `__' macros are permitted by the ISO standard, so they are + predefined regardless of whether `-ansi' or a `-std' option is + specified. + + For example, on the Sun, one can use the following value: + + "-Dmc68000 -Dsun -Dunix" + + The result is to define the macros `__mc68000__', `__sun__' and + `__unix__' unconditionally, and the macros `mc68000', `sun' and + `unix' provided `-ansi' is not specified. + +`extern int target_flags;' + This declaration should be present. + +`TARGET_...' + This series of macros is to allow compiler command arguments to + enable or disable the use of optional features of the target + machine. For example, one machine description serves both the + 68000 and the 68020; a command argument tells the compiler whether + it should use 68020-only instructions or not. This command + argument works by means of a macro `TARGET_68020' that tests a bit + in `target_flags'. + + Define a macro `TARGET_FEATURENAME' for each such option. Its + definition should test a bit in `target_flags'. It is recommended + that a helper macro `TARGET_MASK_FEATURENAME' is defined for each + bit-value to test, and used in `TARGET_FEATURENAME' and + `TARGET_SWITCHES'. For example: + + #define TARGET_MASK_68020 1 + #define TARGET_68020 (target_flags & TARGET_MASK_68020) + + One place where these macros are used is in the + condition-expressions of instruction patterns. Note how + `TARGET_68020' appears frequently in the 68000 machine description + file, `m68k.md'. Another place they are used is in the + definitions of the other macros in the `MACHINE.h' file. + +`TARGET_SWITCHES' + This macro defines names of command options to set and clear bits + in `target_flags'. Its definition is an initializer with a + subgrouping for each command option. + + Each subgrouping contains a string constant, that defines the + option name, a number, which contains the bits to set in + `target_flags', and a second string which is the description + displayed by `--help'. If the number is negative then the bits + specified by the number are cleared instead of being set. If the + description string is present but empty, then no help information + will be displayed for that option, but it will not count as an + undocumented option. The actual option name is made by appending + `-m' to the specified name. Non-empty description strings should + be marked with `N_(...)' for `xgettext'. Please do not mark empty + strings because the empty string is reserved by GNU gettext. + `gettext("")' returns the header entry of the message catalog with + meta information, not the empty string. + + In addition to the description for `--help', more detailed + documentation for each option should be added to `invoke.texi'. + + One of the subgroupings should have a null string. The number in + this grouping is the default value for `target_flags'. Any target + options act starting with that value. + + Here is an example which defines `-m68000' and `-m68020' with + opposite meanings, and picks the latter as the default: + + #define TARGET_SWITCHES \ + { { "68020", TARGET_MASK_68020, "" }, \ + { "68000", -TARGET_MASK_68020, \ + N_("Compile for the 68000") }, \ + { "", TARGET_MASK_68020, "" }} + +`TARGET_OPTIONS' + This macro is similar to `TARGET_SWITCHES' but defines names of + command options that have values. Its definition is an + initializer with a subgrouping for each command option. + + Each subgrouping contains a string constant, that defines the + fixed part of the option name, the address of a variable, and a + description string. Non-empty description strings should be + marked with `N_(...)' for `xgettext'. Please do not mark empty + strings because the empty string is reserved by GNU gettext. + `gettext("")' returns the header entry of the message catalog with + meta information, not the empty string. + + The variable, type `char *', is set to the variable part of the + given option if the fixed part matches. The actual option name is + made by appending `-m' to the specified name. Again, each option + should also be documented in `invoke.texi'. + + Here is an example which defines `-mshort-data-NUMBER'. If the + given option is `-mshort-data-512', the variable `m88k_short_data' + will be set to the string `"512"'. + + extern char *m88k_short_data; + #define TARGET_OPTIONS \ + { { "short-data-", &m88k_short_data, \ + N_("Specify the size of the short data section") } } + +`TARGET_VERSION' + This macro is a C statement to print on `stderr' a string + describing the particular machine description choice. Every + machine description should define `TARGET_VERSION'. For example: + + #ifdef MOTOROLA + #define TARGET_VERSION \ + fprintf (stderr, " (68k, Motorola syntax)"); + #else + #define TARGET_VERSION \ + fprintf (stderr, " (68k, MIT syntax)"); + #endif + +`OVERRIDE_OPTIONS' + Sometimes certain combinations of command options do not make + sense on a particular target machine. You can define a macro + `OVERRIDE_OPTIONS' to take account of this. This macro, if + defined, is executed once just after all the command options have + been parsed. + + Don't use this macro to turn on various extra optimizations for + `-O'. That is what `OPTIMIZATION_OPTIONS' is for. + +`OPTIMIZATION_OPTIONS (LEVEL, SIZE)' + Some machines may desire to change what optimizations are + performed for various optimization levels. This macro, if + defined, is executed once just after the optimization level is + determined and before the remainder of the command options have + been parsed. Values set in this macro are used as the default + values for the other command line options. + + LEVEL is the optimization level specified; 2 if `-O2' is + specified, 1 if `-O' is specified, and 0 if neither is specified. + + SIZE is nonzero if `-Os' is specified and zero otherwise. + + You should not use this macro to change options that are not + machine-specific. These should uniformly selected by the same + optimization level on all supported machines. Use this macro to + enable machine-specific optimizations. + + *Do not examine `write_symbols' in this macro!* The debugging + options are not supposed to alter the generated code. + +`CAN_DEBUG_WITHOUT_FP' + Define this macro if debugging can be performed even without a + frame pointer. If this macro is defined, GCC will turn on the + `-fomit-frame-pointer' option whenever `-O' is specified. + + +File: gccint.info, Node: Per-Function Data, Next: Storage Layout, Prev: Run-time Target, Up: Target Macros + +10.4 Defining data structures for per-function information. +=========================================================== + +If the target needs to store information on a per-function basis, GCC +provides a macro and a couple of variables to allow this. Note, just +using statics to store the information is a bad idea, since GCC supports +nested functions, so you can be halfway through encoding one function +when another one comes along. + + GCC defines a data structure called `struct function' which contains +all of the data specific to an individual function. This structure +contains a field called `machine' whose type is `struct +machine_function *', which can be used by targets to point to their own +specific data. + + If a target needs per-function specific data it should define the +type `struct machine_function' and also the macro `INIT_EXPANDERS'. +This macro should be used to initialize some or all of the function +pointers `init_machine_status', `free_machine_status' and +`mark_machine_status'. These pointers are explained below. + + One typical use of per-function, target specific data is to create an +RTX to hold the register containing the function's return address. This +RTX can then be used to implement the `__builtin_return_address' +function, for level 0. + + Note--earlier implementations of GCC used a single data area to hold +all of the per-function information. Thus when processing of a nested +function began the old per-function data had to be pushed onto a stack, +and when the processing was finished, it had to be popped off the +stack. GCC used to provide function pointers called +`save_machine_status' and `restore_machine_status' to handle the saving +and restoring of the target specific information. Since the single +data area approach is no longer used, these pointers are no longer +supported. + + The macro and function pointers are described below. + +`INIT_EXPANDERS' + Macro called to initialize any target specific information. This + macro is called once per function, before generation of any RTL + has begun. The intention of this macro is to allow the + initialization of the function pointers below. + +`init_machine_status' + This is a `void (*)(struct function *)' function pointer. If this + pointer is non-`NULL' it will be called once per function, before + function compilation starts, in order to allow the target to + perform any target specific initialization of the `struct + function' structure. It is intended that this would be used to + initialize the `machine' of that structure. + +`free_machine_status' + This is a `void (*)(struct function *)' function pointer. If this + pointer is non-`NULL' it will be called once per function, after + the function has been compiled, in order to allow any memory + allocated during the `init_machine_status' function call to be + freed. + +`mark_machine_status' + This is a `void (*)(struct function *)' function pointer. If this + pointer is non-`NULL' it will be called once per function in order + to mark any data items in the `struct machine_function' structure + which need garbage collection. + + + +File: gccint.info, Node: Storage Layout, Next: Type Layout, Prev: Per-Function Data, Up: Target Macros + +10.5 Storage Layout +=================== + +Note that the definitions of the macros in this table which are sizes or +alignments measured in bits do not need to be constant. They can be C +expressions that refer to static variables, such as the `target_flags'. +*Note Run-time Target::. + +`BITS_BIG_ENDIAN' + Define this macro to have the value 1 if the most significant bit + in a byte has the lowest number; otherwise define it to have the + value zero. This means that bit-field instructions count from the + most significant bit. If the machine has no bit-field + instructions, then this must still be defined, but it doesn't + matter which value it is defined to. This macro need not be a + constant. + + This macro does not affect the way structure fields are packed into + bytes or words; that is controlled by `BYTES_BIG_ENDIAN'. + +`BYTES_BIG_ENDIAN' + Define this macro to have the value 1 if the most significant byte + in a word has the lowest number. This macro need not be a + constant. + +`WORDS_BIG_ENDIAN' + Define this macro to have the value 1 if, in a multiword object, + the most significant word has the lowest number. This applies to + both memory locations and registers; GCC fundamentally assumes + that the order of words in memory is the same as the order in + registers. This macro need not be a constant. + +`LIBGCC2_WORDS_BIG_ENDIAN' + Define this macro if `WORDS_BIG_ENDIAN' is not constant. This + must be a constant value with the same meaning as + `WORDS_BIG_ENDIAN', which will be used only when compiling + `libgcc2.c'. Typically the value will be set based on + preprocessor defines. + +`FLOAT_WORDS_BIG_ENDIAN' + Define this macro to have the value 1 if `DFmode', `XFmode' or + `TFmode' floating point numbers are stored in memory with the word + containing the sign bit at the lowest address; otherwise define it + to have the value 0. This macro need not be a constant. + + You need not define this macro if the ordering is the same as for + multi-word integers. + +`BITS_PER_UNIT' + Define this macro to be the number of bits in an addressable + storage unit (byte); normally 8. + +`BITS_PER_WORD' + Number of bits in a word; normally 32. + +`MAX_BITS_PER_WORD' + Maximum number of bits in a word. If this is undefined, the + default is `BITS_PER_WORD'. Otherwise, it is the constant value + that is the largest value that `BITS_PER_WORD' can have at + run-time. + +`UNITS_PER_WORD' + Number of storage units in a word; normally 4. + +`MIN_UNITS_PER_WORD' + Minimum number of units in a word. If this is undefined, the + default is `UNITS_PER_WORD'. Otherwise, it is the constant value + that is the smallest value that `UNITS_PER_WORD' can have at + run-time. + +`POINTER_SIZE' + Width of a pointer, in bits. You must specify a value no wider + than the width of `Pmode'. If it is not equal to the width of + `Pmode', you must define `POINTERS_EXTEND_UNSIGNED'. + +`POINTERS_EXTEND_UNSIGNED' + A C expression whose value is greater than zero if pointers that + need to be extended from being `POINTER_SIZE' bits wide to `Pmode' + are to be zero-extended and zero if they are to be sign-extended. + If the value is less then zero then there must be an "ptr_extend" + instruction that extends a pointer from `POINTER_SIZE' to `Pmode'. + + You need not define this macro if the `POINTER_SIZE' is equal to + the width of `Pmode'. + +`PROMOTE_MODE (M, UNSIGNEDP, TYPE)' + A macro to update M and UNSIGNEDP when an object whose type is + TYPE and which has the specified mode and signedness is to be + stored in a register. This macro is only called when TYPE is a + scalar type. + + On most RISC machines, which only have operations that operate on + a full register, define this macro to set M to `word_mode' if M is + an integer mode narrower than `BITS_PER_WORD'. In most cases, + only integer modes should be widened because wider-precision + floating-point operations are usually more expensive than their + narrower counterparts. + + For most machines, the macro definition does not change UNSIGNEDP. + However, some machines, have instructions that preferentially + handle either signed or unsigned quantities of certain modes. For + example, on the DEC Alpha, 32-bit loads from memory and 32-bit add + instructions sign-extend the result to 64 bits. On such machines, + set UNSIGNEDP according to which kind of extension is more + efficient. + + Do not define this macro if it would never modify M. + +`PROMOTE_FUNCTION_ARGS' + Define this macro if the promotion described by `PROMOTE_MODE' + should also be done for outgoing function arguments. + +`PROMOTE_FUNCTION_RETURN' + Define this macro if the promotion described by `PROMOTE_MODE' + should also be done for the return value of functions. + + If this macro is defined, `FUNCTION_VALUE' must perform the same + promotions done by `PROMOTE_MODE'. + +`PROMOTE_FOR_CALL_ONLY' + Define this macro if the promotion described by `PROMOTE_MODE' + should _only_ be performed for outgoing function arguments or + function return values, as specified by `PROMOTE_FUNCTION_ARGS' + and `PROMOTE_FUNCTION_RETURN', respectively. + +`PARM_BOUNDARY' + Normal alignment required for function parameters on the stack, in + bits. All stack parameters receive at least this much alignment + regardless of data type. On most machines, this is the same as the + size of an integer. + +`STACK_BOUNDARY' + Define this macro to the minimum alignment enforced by hardware + for the stack pointer on this machine. The definition is a C + expression for the desired alignment (measured in bits). This + value is used as a default if `PREFERRED_STACK_BOUNDARY' is not + defined. On most machines, this should be the same as + `PARM_BOUNDARY'. + +`PREFERRED_STACK_BOUNDARY' + Define this macro if you wish to preserve a certain alignment for + the stack pointer, greater than what the hardware enforces. The + definition is a C expression for the desired alignment (measured + in bits). This macro must evaluate to a value equal to or larger + than `STACK_BOUNDARY'. + +`FORCE_PREFERRED_STACK_BOUNDARY_IN_MAIN' + A C expression that evaluates true if `PREFERRED_STACK_BOUNDARY' is + not guaranteed by the runtime and we should emit code to align the + stack at the beginning of `main'. + + If `PUSH_ROUNDING' is not defined, the stack will always be aligned + to the specified boundary. If `PUSH_ROUNDING' is defined and + specifies a less strict alignment than `PREFERRED_STACK_BOUNDARY', + the stack may be momentarily unaligned while pushing arguments. + +`FUNCTION_BOUNDARY' + Alignment required for a function entry point, in bits. + +`BIGGEST_ALIGNMENT' + Biggest alignment that any data type can require on this machine, + in bits. + +`MINIMUM_ATOMIC_ALIGNMENT' + If defined, the smallest alignment, in bits, that can be given to + an object that can be referenced in one operation, without + disturbing any nearby object. Normally, this is `BITS_PER_UNIT', + but may be larger on machines that don't have byte or half-word + store operations. + +`BIGGEST_FIELD_ALIGNMENT' + Biggest alignment that any structure or union field can require on + this machine, in bits. If defined, this overrides + `BIGGEST_ALIGNMENT' for structure and union fields only, unless + the field alignment has been set by the `__attribute__ ((aligned + (N)))' construct. + +`ADJUST_FIELD_ALIGN (FIELD, COMPUTED)' + An expression for the alignment of a structure field FIELD if the + alignment computed in the usual way (including applying of + `BIGGEST_ALIGNMENT' and `BIGGEST_FIELD_ALIGNMENT' to the + alignment) is COMPUTED. It overrides alignment only if the field + alignment has not been set by the `__attribute__ ((aligned (N)))' + construct. + +`MAX_OFILE_ALIGNMENT' + Biggest alignment supported by the object file format of this + machine. Use this macro to limit the alignment which can be + specified using the `__attribute__ ((aligned (N)))' construct. If + not defined, the default value is `BIGGEST_ALIGNMENT'. + +`DATA_ALIGNMENT (TYPE, BASIC-ALIGN)' + If defined, a C expression to compute the alignment for a variable + in the static store. TYPE is the data type, and BASIC-ALIGN is + the alignment that the object would ordinarily have. The value of + this macro is used instead of that alignment to align the object. + + If this macro is not defined, then BASIC-ALIGN is used. + + One use of this macro is to increase alignment of medium-size data + to make it all fit in fewer cache lines. Another is to cause + character arrays to be word-aligned so that `strcpy' calls that + copy constants to character arrays can be done inline. + +`CONSTANT_ALIGNMENT (CONSTANT, BASIC-ALIGN)' + If defined, a C expression to compute the alignment given to a + constant that is being placed in memory. CONSTANT is the constant + and BASIC-ALIGN is the alignment that the object would ordinarily + have. The value of this macro is used instead of that alignment to + align the object. + + If this macro is not defined, then BASIC-ALIGN is used. + + The typical use of this macro is to increase alignment for string + constants to be word aligned so that `strcpy' calls that copy + constants can be done inline. + +`LOCAL_ALIGNMENT (TYPE, BASIC-ALIGN)' + If defined, a C expression to compute the alignment for a variable + in the local store. TYPE is the data type, and BASIC-ALIGN is the + alignment that the object would ordinarily have. The value of this + macro is used instead of that alignment to align the object. + + If this macro is not defined, then BASIC-ALIGN is used. + + One use of this macro is to increase alignment of medium-size data + to make it all fit in fewer cache lines. + +`EMPTY_FIELD_BOUNDARY' + Alignment in bits to be given to a structure bit-field that + follows an empty field such as `int : 0;'. + + Note that `PCC_BITFIELD_TYPE_MATTERS' also affects the alignment + that results from an empty field. + +`STRUCTURE_SIZE_BOUNDARY' + Number of bits which any structure or union's size must be a + multiple of. Each structure or union's size is rounded up to a + multiple of this. + + If you do not define this macro, the default is the same as + `BITS_PER_UNIT'. + +`STRICT_ALIGNMENT' + Define this macro to be the value 1 if instructions will fail to + work if given data not on the nominal alignment. If instructions + will merely go slower in that case, define this macro as 0. + +`PCC_BITFIELD_TYPE_MATTERS' + Define this if you wish to imitate the way many other C compilers + handle alignment of bit-fields and the structures that contain them. - * All the passes that work with RTL use the header files `rtl.h' and - `rtl.def', and subroutines in file `rtl.c'. The tools `gen*' also - use these files to read and work with the machine description RTL. - - * All the tools that read the machine description use support - routines found in `gensupport.c', `errors.c', and `read-rtl.c'. - - * Several passes refer to the header file `insn-config.h' which - contains a few parameters (C macro definitions) generated - automatically from the machine description RTL by the tool - `genconfig'. - - * Several passes use the instruction recognizer, which consists of - `recog.c' and `recog.h', plus the files `insn-recog.c' and - `insn-extract.c' that are generated automatically from the machine - description by the tools `genrecog' and `genextract'. - - * Several passes use the header files `regs.h' which defines the - information recorded about pseudo register usage, and - `basic-block.h' which defines the information recorded about basic - blocks. - - * `hard-reg-set.h' defines the type `HARD_REG_SET', a bit-vector - with a bit for each hard register, and some macros to manipulate - it. This type is just `int' if the machine has few enough hard - registers; otherwise it is an array of `int' and some of the - macros expand into loops. - - * Several passes use instruction attributes. A definition of the - attributes defined for a particular machine is in file - `insn-attr.h', which is generated from the machine description by - the program `genattr'. The file `insn-attrtab.c' contains - subroutines to obtain the attribute values for insns. It is - generated from the machine description by the program `genattrtab'. - - -File: gccint.info, Node: Trees, Next: RTL, Prev: Passes, Up: Top - -Trees: The intermediate representation used by the C and C++ front ends -*********************************************************************** - - This chapter documents the internal representation used by GCC to -represent C and C++ source programs. When presented with a C or C++ -source program, GCC parses the program, performs semantic analysis -(including the generation of error messages), and then produces the -internal representation described here. This representation contains a -complete representation for the entire translation unit provided as -input to the front end. This representation is then typically processed -by a code-generator in order to produce machine code, but could also be -used in the creation of source browsers, intelligent editors, automatic -documentation generators, interpreters, and any other programs needing -the ability to process C or C++ code. - - This chapter explains the internal representation. In particular, it -documents the internal representation for C and C++ source constructs, -and the macros, functions, and variables that can be used to access -these constructs. The C++ representation is largely a superset of the -representation used in the C front end. There is only one construct -used in C that does not appear in the C++ front end and that is the GNU -"nested function" extension. Many of the macros documented here do not -apply in C because the corresponding language constructs do not appear -in C. - - If you are developing a "back end", be it is a code-generator or some -other tool, that uses this representation, you may occasionally find -that you need to ask questions not easily answered by the functions and -macros available here. If that situation occurs, it is quite likely -that GCC already supports the functionality you desire, but that the -interface is simply not documented here. In that case, you should ask -the GCC maintainers (via mail to ) about documenting -the functionality you require. Similarly, if you find yourself writing -functions that do not deal directly with your back end, but instead -might be useful to other people using the GCC front end, you should -submit your patches for inclusion in GCC. + The behavior is that the type written for a bit-field (`int', + `short', or other integer type) imposes an alignment for the + entire structure, as if the structure really did contain an + ordinary field of that type. In addition, the bit-field is placed + within the structure so that it would fit within such a field, not + crossing a boundary for it. + + Thus, on most machines, a bit-field whose type is written as `int' + would not cross a four-byte boundary, and would force four-byte + alignment for the whole structure. (The alignment used may not be + four bytes; it is controlled by the other alignment parameters.) + + If the macro is defined, its definition should be a C expression; + a nonzero value for the expression enables this behavior. + + Note that if this macro is not defined, or its value is zero, some + bit-fields may cross more than one alignment boundary. The + compiler can support such references if there are `insv', `extv', + and `extzv' insns that can directly reference memory. + + The other known way of making bit-fields work is to define + `STRUCTURE_SIZE_BOUNDARY' as large as `BIGGEST_ALIGNMENT'. Then + every structure can be accessed with fullwords. + + Unless the machine has bit-field instructions or you define + `STRUCTURE_SIZE_BOUNDARY' that way, you must define + `PCC_BITFIELD_TYPE_MATTERS' to have a nonzero value. + + If your aim is to make GCC use the same conventions for laying out + bit-fields as are used by another compiler, here is how to + investigate what the other compiler does. Compile and run this + program: + + struct foo1 + { + char x; + char :0; + char y; + }; + + struct foo2 + { + char x; + int :0; + char y; + }; + + main () + { + printf ("Size of foo1 is %d\n", + sizeof (struct foo1)); + printf ("Size of foo2 is %d\n", + sizeof (struct foo2)); + exit (0); + } + + If this prints 2 and 5, then the compiler's behavior is what you + would get from `PCC_BITFIELD_TYPE_MATTERS'. + +`BITFIELD_NBYTES_LIMITED' + Like `PCC_BITFIELD_TYPE_MATTERS' except that its effect is limited + to aligning a bit-field within the structure. + +`MEMBER_TYPE_FORCES_BLK (FIELD)' + Return 1 if a structure or array containing FIELD should be + accessed using `BLKMODE'. + + Normally, this is not needed. See the file `c4x.h' for an example + of how to use this macro to prevent a structure having a floating + point field from being accessed in an integer mode. + +`ROUND_TYPE_SIZE (TYPE, COMPUTED, SPECIFIED)' + Define this macro as an expression for the overall size of a type + (given by TYPE as a tree node) when the size computed in the usual + way is COMPUTED and the alignment is SPECIFIED. + + The default is to round COMPUTED up to a multiple of SPECIFIED. + +`ROUND_TYPE_SIZE_UNIT (TYPE, COMPUTED, SPECIFIED)' + Similar to `ROUND_TYPE_SIZE', but sizes and alignments are + specified in units (bytes). If you define `ROUND_TYPE_SIZE', you + must also define this macro and they must be defined consistently + with each other. + +`ROUND_TYPE_ALIGN (TYPE, COMPUTED, SPECIFIED)' + Define this macro as an expression for the alignment of a type + (given by TYPE as a tree node) if the alignment computed in the + usual way is COMPUTED and the alignment explicitly specified was + SPECIFIED. + + The default is to use SPECIFIED if it is larger; otherwise, use + the smaller of COMPUTED and `BIGGEST_ALIGNMENT' + +`MAX_FIXED_MODE_SIZE' + An integer expression for the size in bits of the largest integer + machine mode that should actually be used. All integer machine + modes of this size or smaller can be used for structures and + unions with the appropriate sizes. If this macro is undefined, + `GET_MODE_BITSIZE (DImode)' is assumed. + +`VECTOR_MODE_SUPPORTED_P(MODE)' + Define this macro to be nonzero if the port is prepared to handle + insns involving vector mode MODE. At the very least, it must have + move patterns for this mode. + +`STACK_SAVEAREA_MODE (SAVE_LEVEL)' + If defined, an expression of type `enum machine_mode' that + specifies the mode of the save area operand of a + `save_stack_LEVEL' named pattern (*note Standard Names::). + SAVE_LEVEL is one of `SAVE_BLOCK', `SAVE_FUNCTION', or + `SAVE_NONLOCAL' and selects which of the three named patterns is + having its mode specified. + + You need not define this macro if it always returns `Pmode'. You + would most commonly define this macro if the `save_stack_LEVEL' + patterns need to support both a 32- and a 64-bit mode. + +`STACK_SIZE_MODE' + If defined, an expression of type `enum machine_mode' that + specifies the mode of the size increment operand of an + `allocate_stack' named pattern (*note Standard Names::). + + You need not define this macro if it always returns `word_mode'. + You would most commonly define this macro if the `allocate_stack' + pattern needs to support both a 32- and a 64-bit mode. + +`CHECK_FLOAT_VALUE (MODE, VALUE, OVERFLOW)' + A C statement to validate the value VALUE (of type `double') for + mode MODE. This means that you check whether VALUE fits within + the possible range of values for mode MODE on this target machine. + The mode MODE is always a mode of class `MODE_FLOAT'. OVERFLOW is + nonzero if the value is already known to be out of range. + + If VALUE is not valid or if OVERFLOW is nonzero, you should set + OVERFLOW to 1 and then assign some valid value to VALUE. Allowing + an invalid value to go through the compiler can produce incorrect + assembler code which may even cause Unix assemblers to crash. + + This macro need not be defined if there is no work for it to do. + +`TARGET_FLOAT_FORMAT' + A code distinguishing the floating point format of the target + machine. There are five defined values: + + `IEEE_FLOAT_FORMAT' + This code indicates IEEE floating point. It is the default; + there is no need to define this macro when the format is IEEE. + + `VAX_FLOAT_FORMAT' + This code indicates the "D float" format used on the VAX. + + `IBM_FLOAT_FORMAT' + This code indicates the format used on the IBM System/370. + + `C4X_FLOAT_FORMAT' + This code indicates the format used on the TMS320C3x/C4x. + + `UNKNOWN_FLOAT_FORMAT' + This code indicates any other format. + + The value of this macro is compared with `HOST_FLOAT_FORMAT', which + is defined by the `configure' script, to determine whether the + target machine has the same format as the host machine. If any + other formats are actually in use on supported machines, new codes + should be defined for them. + + The ordering of the component words of floating point values + stored in memory is controlled by `FLOAT_WORDS_BIG_ENDIAN'. + + + -- Target Hook: bool TARGET_MS_BITFIELD_LAYOUT_P (tree RECORD_TYPE) + This target hook returns `true' if bit-fields in the given + RECORD_TYPE are to be laid out following the rules of Microsoft + Visual C/C++, namely: (i) a bit-field won't share the same storage + unit with the previous bit-field if their underlying types have + different sizes, and the bit-field will be aligned to the highest + alignment of the underlying types of itself and of the previous + bit-field; (ii) a zero-sized bit-field will affect the alignment of + the whole enclosing structure, even if it is unnamed; except that + (iii) a zero-sized bit-field will be disregarded unless it follows + another bit-field of non-zero size. If this hook returns `true', + other macros that control bit-field layout are ignored. -* Menu: + +File: gccint.info, Node: Type Layout, Next: Escape Sequences, Prev: Storage Layout, Up: Target Macros + +10.6 Layout of Source Language Data Types +========================================= + +These macros define the sizes and other characteristics of the standard +basic data types used in programs being compiled. Unlike the macros in +the previous section, these apply to specific features of C and related +languages, rather than to fundamental aspects of storage layout. + +`INT_TYPE_SIZE' + A C expression for the size in bits of the type `int' on the + target machine. If you don't define this, the default is one word. + +`SHORT_TYPE_SIZE' + A C expression for the size in bits of the type `short' on the + target machine. If you don't define this, the default is half a + word. (If this would be less than one storage unit, it is rounded + up to one unit.) + +`LONG_TYPE_SIZE' + A C expression for the size in bits of the type `long' on the + target machine. If you don't define this, the default is one word. + +`ADA_LONG_TYPE_SIZE' + On some machines, the size used for the Ada equivalent of the type + `long' by a native Ada compiler differs from that used by C. In + that situation, define this macro to be a C expression to be used + for the size of that type. If you don't define this, the default + is the value of `LONG_TYPE_SIZE'. + +`MAX_LONG_TYPE_SIZE' + Maximum number for the size in bits of the type `long' on the + target machine. If this is undefined, the default is + `LONG_TYPE_SIZE'. Otherwise, it is the constant value that is the + largest value that `LONG_TYPE_SIZE' can have at run-time. This is + used in `cpp'. + +`LONG_LONG_TYPE_SIZE' + A C expression for the size in bits of the type `long long' on the + target machine. If you don't define this, the default is two + words. If you want to support GNU Ada on your machine, the value + of this macro must be at least 64. + +`CHAR_TYPE_SIZE' + A C expression for the size in bits of the type `char' on the + target machine. If you don't define this, the default is + `BITS_PER_UNIT'. + +`MAX_CHAR_TYPE_SIZE' + Maximum number for the size in bits of the type `char' on the + target machine. If this is undefined, the default is + `CHAR_TYPE_SIZE'. Otherwise, it is the constant value that is the + largest value that `CHAR_TYPE_SIZE' can have at run-time. This is + used in `cpp'. + +`BOOL_TYPE_SIZE' + A C expression for the size in bits of the C++ type `bool' and C99 + type `_Bool' on the target machine. If you don't define this, and + you probably shouldn't, the default is `CHAR_TYPE_SIZE'. + +`FLOAT_TYPE_SIZE' + A C expression for the size in bits of the type `float' on the + target machine. If you don't define this, the default is one word. + +`DOUBLE_TYPE_SIZE' + A C expression for the size in bits of the type `double' on the + target machine. If you don't define this, the default is two + words. + +`LONG_DOUBLE_TYPE_SIZE' + A C expression for the size in bits of the type `long double' on + the target machine. If you don't define this, the default is two + words. + + Maximum number for the size in bits of the type `long double' on + the target machine. If this is undefined, the default is + `LONG_DOUBLE_TYPE_SIZE'. Otherwise, it is the constant value that + is the largest value that `LONG_DOUBLE_TYPE_SIZE' can have at + run-time. This is used in `cpp'. + + Define this macro to be 1 if the target machine uses 80-bit + floating-point values with 128-bit size and alignment. This is + used in `real.c'. + +`WIDEST_HARDWARE_FP_SIZE' + A C expression for the size in bits of the widest floating-point + format supported by the hardware. If you define this macro, you + must specify a value less than or equal to the value of + `LONG_DOUBLE_TYPE_SIZE'. If you do not define this macro, the + value of `LONG_DOUBLE_TYPE_SIZE' is the default. + +`DEFAULT_SIGNED_CHAR' + An expression whose value is 1 or 0, according to whether the type + `char' should be signed or unsigned by default. The user can + always override this default with the options `-fsigned-char' and + `-funsigned-char'. + +`DEFAULT_SHORT_ENUMS' + A C expression to determine whether to give an `enum' type only as + many bytes as it takes to represent the range of possible values + of that type. A nonzero value means to do that; a zero value + means all `enum' types should be allocated like `int'. + + If you don't define the macro, the default is 0. + +`SIZE_TYPE' + A C expression for a string describing the name of the data type + to use for size values. The typedef name `size_t' is defined + using the contents of the string. + + The string can contain more than one keyword. If so, separate + them with spaces, and write first any length keyword, then + `unsigned' if appropriate, and finally `int'. The string must + exactly match one of the data type names defined in the function + `init_decl_processing' in the file `c-decl.c'. You may not omit + `int' or change the order--that would cause the compiler to crash + on startup. + + If you don't define this macro, the default is `"long unsigned + int"'. + +`PTRDIFF_TYPE' + A C expression for a string describing the name of the data type + to use for the result of subtracting two pointers. The typedef + name `ptrdiff_t' is defined using the contents of the string. See + `SIZE_TYPE' above for more information. + + If you don't define this macro, the default is `"long int"'. + +`WCHAR_TYPE' + A C expression for a string describing the name of the data type + to use for wide characters. The typedef name `wchar_t' is defined + using the contents of the string. See `SIZE_TYPE' above for more + information. + + If you don't define this macro, the default is `"int"'. + +`WCHAR_TYPE_SIZE' + A C expression for the size in bits of the data type for wide + characters. This is used in `cpp', which cannot make use of + `WCHAR_TYPE'. + +`MAX_WCHAR_TYPE_SIZE' + Maximum number for the size in bits of the data type for wide + characters. If this is undefined, the default is + `WCHAR_TYPE_SIZE'. Otherwise, it is the constant value that is the + largest value that `WCHAR_TYPE_SIZE' can have at run-time. This is + used in `cpp'. + +`GCOV_TYPE_SIZE' + A C expression for the size in bits of the type used for gcov + counters on the target machine. If you don't define this, the + default is one `LONG_TYPE_SIZE' in case it is greater or equal to + 64-bit and `LONG_LONG_TYPE_SIZE' otherwise. You may want to + re-define the type to ensure atomicity for counters in + multithreaded programs. + +`WINT_TYPE' + A C expression for a string describing the name of the data type to + use for wide characters passed to `printf' and returned from + `getwc'. The typedef name `wint_t' is defined using the contents + of the string. See `SIZE_TYPE' above for more information. + + If you don't define this macro, the default is `"unsigned int"'. + +`INTMAX_TYPE' + A C expression for a string describing the name of the data type + that can represent any value of any standard or extended signed + integer type. The typedef name `intmax_t' is defined using the + contents of the string. See `SIZE_TYPE' above for more + information. + + If you don't define this macro, the default is the first of + `"int"', `"long int"', or `"long long int"' that has as much + precision as `long long int'. + +`UINTMAX_TYPE' + A C expression for a string describing the name of the data type + that can represent any value of any standard or extended unsigned + integer type. The typedef name `uintmax_t' is defined using the + contents of the string. See `SIZE_TYPE' above for more + information. + + If you don't define this macro, the default is the first of + `"unsigned int"', `"long unsigned int"', or `"long long unsigned + int"' that has as much precision as `long long unsigned int'. + +`TARGET_PTRMEMFUNC_VBIT_LOCATION' + The C++ compiler represents a pointer-to-member-function with a + struct that looks like: + + struct { + union { + void (*fn)(); + ptrdiff_t vtable_index; + }; + ptrdiff_t delta; + }; + + The C++ compiler must use one bit to indicate whether the function + that will be called through a pointer-to-member-function is + virtual. Normally, we assume that the low-order bit of a function + pointer must always be zero. Then, by ensuring that the + vtable_index is odd, we can distinguish which variant of the union + is in use. But, on some platforms function pointers can be odd, + and so this doesn't work. In that case, we use the low-order bit + of the `delta' field, and shift the remainder of the `delta' field + to the left. + + GCC will automatically make the right selection about where to + store this bit using the `FUNCTION_BOUNDARY' setting for your + platform. However, some platforms such as ARM/Thumb have + `FUNCTION_BOUNDARY' set such that functions always start at even + addresses, but the lowest bit of pointers to functions indicate + whether the function at that address is in ARM or Thumb mode. If + this is the case of your architecture, you should define this + macro to `ptrmemfunc_vbit_in_delta'. + + In general, you should not have to define this macro. On + architectures in which function addresses are always even, + according to `FUNCTION_BOUNDARY', GCC will automatically define + this macro to `ptrmemfunc_vbit_in_pfn'. + +`TARGET_VTABLE_USES_DESCRIPTORS' + Normally, the C++ compiler uses function pointers in vtables. This + macro allows the target to change to use "function descriptors" + instead. Function descriptors are found on targets for whom a + function pointer is actually a small data structure. Normally the + data structure consists of the actual code address plus a data + pointer to which the function's data is relative. + + If vtables are used, the value of this macro should be the number + of words that the function descriptor occupies. + + +File: gccint.info, Node: Escape Sequences, Next: Registers, Prev: Type Layout, Up: Target Macros + +10.7 Target Character Escape Sequences +====================================== + +By default, GCC assumes that the C character escape sequences take on +their ASCII values for the target. If this is not correct, you must +explicitly define all of the macros below. -* Deficiencies:: Topics net yet covered in this document. -* Tree overview:: All about `tree's. -* Types:: Fundamental and aggregate types. -* Scopes:: Namespaces and classes. -* Functions:: Overloading, function bodies, and linkage. -* Declarations:: Type declarations and variables. -* Attributes:: Declaration and type attributes. -* Expression trees:: From `typeid' to `throw'. - - -File: gccint.info, Node: Deficiencies, Next: Tree overview, Up: Trees - -Deficiencies -============ - - There are many places in which this document is incomplet and -incorrekt. It is, as of yet, only _preliminary_ documentation. - - -File: gccint.info, Node: Tree overview, Next: Types, Prev: Deficiencies, Up: Trees - -Overview -======== - - The central data structure used by the internal representation is the -`tree'. These nodes, while all of the C type `tree', are of many -varieties. A `tree' is a pointer type, but the object to which it -points may be of a variety of types. From this point forward, we will -refer to trees in ordinary type, rather than in `this font', except -when talking about the actual C type `tree'. - - You can tell what kind of node a particular tree is by using the -`TREE_CODE' macro. Many, many macros take a trees as input and return -trees as output. However, most macros require a certain kinds of tree -node as input. In other words, there is a type-system for trees, but -it is not reflected in the C type-system. - - For safety, it is useful to configure GCC with `--enable-checking'. -Although this results in a significant performance penalty (since all -tree types are checked at run-time), and is therefore inappropriate in a -release version, it is extremely helpful during the development process. - - Many macros behave as predicates. Many, although not all, of these -predicates end in `_P'. Do not rely on the result type of these macros -being of any particular type. You may, however, rely on the fact that -the type can be compared to `0', so that statements like - if (TEST_P (t) && !TEST_P (y)) - x = 1; - -and - int i = (TEST_P (t) != 0); - -are legal. Macros that return `int' values now may be changed to -return `tree' values, or other pointers in the future. Even those that -continue to return `int' may return multiple nonzero codes where -previously they returned only zero and one. Therefore, you should not -write code like - if (TEST_P (t) == 1) - -as this code is not guaranteed to work correctly in the future. - - You should not take the address of values returned by the macros or -functions described here. In particular, no guarantee is given that the -values are lvalues. - - In general, the names of macros are all in uppercase, while the -names of functions are entirely in lower case. There are rare -exceptions to this rule. You should assume that any macro or function -whose name is made up entirely of uppercase letters may evaluate its -arguments more than once. You may assume that a macro or function -whose name is made up entirely of lowercase letters will evaluate its -arguments only once. - - The `error_mark_node' is a special tree. Its tree code is -`ERROR_MARK', but since there is only ever one node with that code, the -usual practice is to compare the tree against `error_mark_node'. (This -test is just a test for pointer equality.) If an error has occurred -during front-end processing the flag `errorcount' will be set. If the -front end has encountered code it cannot handle, it will issue a -message to the user and set `sorrycount'. When these flags are set, -any macro or function which normally returns a tree of a particular -kind may instead return the `error_mark_node'. Thus, if you intend to -do any processing of erroneous code, you must be prepared to deal with -the `error_mark_node'. - - Occasionally, a particular tree slot (like an operand to an -expression, or a particular field in a declaration) will be referred to -as "reserved for the back end." These slots are used to store RTL when -the tree is converted to RTL for use by the GCC back end. However, if -that process is not taking place (e.g., if the front end is being hooked -up to an intelligent editor), then those slots may be used by the back -end presently in use. - - If you encounter situations that do not match this documentation, -such as tree nodes of types not mentioned here, or macros documented to -return entities of a particular kind that instead return entities of -some different kind, you have found a bug, either in the front end or in -the documentation. Please report these bugs as you would any other bug. +`TARGET_BELL' + A C constant expression for the integer value for escape sequence + `\a'. + +`TARGET_ESC' + A C constant expression for the integer value of the target escape + character. As an extension, GCC evaluates the escape sequences + `\e' and `\E' to this. + +`TARGET_BS' +`TARGET_TAB' +`TARGET_NEWLINE' + C constant expressions for the integer values for escape sequences + `\b', `\t' and `\n'. + +`TARGET_VT' +`TARGET_FF' +`TARGET_CR' + C constant expressions for the integer values for escape sequences + `\v', `\f' and `\r'. + + +File: gccint.info, Node: Registers, Next: Register Classes, Prev: Escape Sequences, Up: Target Macros + +10.8 Register Usage +=================== + +This section explains how to describe what registers the target machine +has, and how (in general) they can be used. + + The description of which registers a specific instruction can use is +done with register classes; see *note Register Classes::. For +information on using registers to access a stack frame, see *note Frame +Registers::. For passing values in registers, see *note Register +Arguments::. For returning values in registers, see *note Scalar +Return::. * Menu: -* Macros and Functions::Macros and functions that can be used with all trees. -* Identifiers:: The names of things. -* Containers:: Lists and vectors. +* Register Basics:: Number and kinds of registers. +* Allocation Order:: Order in which registers are allocated. +* Values in Registers:: What kinds of values each reg can hold. +* Leaf Functions:: Renumbering registers for leaf functions. +* Stack Registers:: Handling a register stack such as 80387.  -File: gccint.info, Node: Macros and Functions, Next: Identifiers, Up: Tree overview +File: gccint.info, Node: Register Basics, Next: Allocation Order, Up: Registers + +10.8.1 Basic Characteristics of Registers +----------------------------------------- + +Registers have various characteristics. + +`FIRST_PSEUDO_REGISTER' + Number of hardware registers known to the compiler. They receive + numbers 0 through `FIRST_PSEUDO_REGISTER-1'; thus, the first + pseudo register's number really is assigned the number + `FIRST_PSEUDO_REGISTER'. + +`FIXED_REGISTERS' + An initializer that says which registers are used for fixed + purposes all throughout the compiled code and are therefore not + available for general allocation. These would include the stack + pointer, the frame pointer (except on machines where that can be + used as a general register when no frame pointer is needed), the + program counter on machines where that is considered one of the + addressable registers, and any other numbered register with a + standard use. + + This information is expressed as a sequence of numbers, separated + by commas and surrounded by braces. The Nth number is 1 if + register N is fixed, 0 otherwise. + + The table initialized from this macro, and the table initialized by + the following one, may be overridden at run time either + automatically, by the actions of the macro + `CONDITIONAL_REGISTER_USAGE', or by the user with the command + options `-ffixed-REG', `-fcall-used-REG' and `-fcall-saved-REG'. + +`CALL_USED_REGISTERS' + Like `FIXED_REGISTERS' but has 1 for each register that is + clobbered (in general) by function calls as well as for fixed + registers. This macro therefore identifies the registers that are + not available for general allocation of values that must live + across function calls. + + If a register has 0 in `CALL_USED_REGISTERS', the compiler + automatically saves it on function entry and restores it on + function exit, if the register is used within the function. + +`CALL_REALLY_USED_REGISTERS' + Like `CALL_USED_REGISTERS' except this macro doesn't require that + the entire set of `FIXED_REGISTERS' be included. + (`CALL_USED_REGISTERS' must be a superset of `FIXED_REGISTERS'). + This macro is optional. If not specified, it defaults to the value + of `CALL_USED_REGISTERS'. + +`HARD_REGNO_CALL_PART_CLOBBERED (REGNO, MODE)' + A C expression that is nonzero if it is not permissible to store a + value of mode MODE in hard register number REGNO across a call + without some part of it being clobbered. For most machines this + macro need not be defined. It is only required for machines that + do not preserve the entire contents of a register across a call. + +`CONDITIONAL_REGISTER_USAGE' + Zero or more C statements that may conditionally modify five + variables `fixed_regs', `call_used_regs', `global_regs', + `reg_names', and `reg_class_contents', to take into account any + dependence of these register sets on target flags. The first three + of these are of type `char []' (interpreted as Boolean vectors). + `global_regs' is a `const char *[]', and `reg_class_contents' is a + `HARD_REG_SET'. Before the macro is called, `fixed_regs', + `call_used_regs', `reg_class_contents', and `reg_names' have been + initialized from `FIXED_REGISTERS', `CALL_USED_REGISTERS', + `REG_CLASS_CONTENTS', and `REGISTER_NAMES', respectively. + `global_regs' has been cleared, and any `-ffixed-REG', + `-fcall-used-REG' and `-fcall-saved-REG' command options have been + applied. + + You need not define this macro if it has no work to do. + + If the usage of an entire class of registers depends on the target + flags, you may indicate this to GCC by using this macro to modify + `fixed_regs' and `call_used_regs' to 1 for each of the registers + in the classes which should not be used by GCC. Also define the + macro `REG_CLASS_FROM_LETTER' to return `NO_REGS' if it is called + with a letter for a class that shouldn't be used. + + (However, if this class is not included in `GENERAL_REGS' and all + of the insn patterns whose constraints permit this class are + controlled by target switches, then GCC will automatically avoid + using these registers when the target switches are opposed to + them.) + +`NON_SAVING_SETJMP' + If this macro is defined and has a nonzero value, it means that + `setjmp' and related functions fail to save the registers, or that + `longjmp' fails to restore them. To compensate, the compiler + avoids putting variables in registers in functions that use + `setjmp'. + +`INCOMING_REGNO (OUT)' + Define this macro if the target machine has register windows. + This C expression returns the register number as seen by the + called function corresponding to the register number OUT as seen + by the calling function. Return OUT if register number OUT is not + an outbound register. + +`OUTGOING_REGNO (IN)' + Define this macro if the target machine has register windows. + This C expression returns the register number as seen by the + calling function corresponding to the register number IN as seen + by the called function. Return IN if register number IN is not an + inbound register. + +`LOCAL_REGNO (REGNO)' + Define this macro if the target machine has register windows. + This C expression returns true if the register is call-saved but + is in the register window. Unlike most call-saved registers, such + registers need not be explicitly restored on function exit or + during non-local gotos. + + + +File: gccint.info, Node: Allocation Order, Next: Values in Registers, Prev: Register Basics, Up: Registers + +10.8.2 Order of Allocation of Registers +--------------------------------------- + +Registers are allocated in order. + +`REG_ALLOC_ORDER' + If defined, an initializer for a vector of integers, containing the + numbers of hard registers in the order in which GCC should prefer + to use them (from most preferred to least). + + If this macro is not defined, registers are used lowest numbered + first (all else being equal). -Trees ------ + One use of this macro is on machines where the highest numbered + registers must always be saved and the save-multiple-registers + instruction supports only sequences of consecutive registers. On + such machines, define `REG_ALLOC_ORDER' to be an initializer that + lists the highest numbered allocable register first. - This section is not here yet. +`ORDER_REGS_FOR_LOCAL_ALLOC' + A C statement (sans semicolon) to choose the order in which to + allocate hard registers for pseudo-registers local to a basic + block. + + Store the desired register order in the array `reg_alloc_order'. + Element 0 should be the register to allocate first; element 1, the + next register; and so on. + + The macro body should not assume anything about the contents of + `reg_alloc_order' before execution of the macro. + + On most machines, it is not necessary to define this macro.  -File: gccint.info, Node: Identifiers, Next: Containers, Prev: Macros and Functions, Up: Tree overview +File: gccint.info, Node: Values in Registers, Next: Leaf Functions, Prev: Allocation Order, Up: Registers + +10.8.3 How Values Fit in Registers +---------------------------------- + +This section discusses the macros that describe which kinds of values +(specifically, which machine modes) each register can hold, and how many +consecutive registers are needed for a given mode. + +`HARD_REGNO_NREGS (REGNO, MODE)' + A C expression for the number of consecutive hard registers, + starting at register number REGNO, required to hold a value of mode + MODE. + + On a machine where all registers are exactly one word, a suitable + definition of this macro is + + #define HARD_REGNO_NREGS(REGNO, MODE) \ + ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \ + / UNITS_PER_WORD) + +`HARD_REGNO_MODE_OK (REGNO, MODE)' + A C expression that is nonzero if it is permissible to store a + value of mode MODE in hard register number REGNO (or in several + registers starting with that one). For a machine where all + registers are equivalent, a suitable definition is + + #define HARD_REGNO_MODE_OK(REGNO, MODE) 1 + + You need not include code to check for the numbers of fixed + registers, because the allocation mechanism considers them to be + always occupied. + + On some machines, double-precision values must be kept in even/odd + register pairs. You can implement that by defining this macro to + reject odd register numbers for such modes. + + The minimum requirement for a mode to be OK in a register is that + the `movMODE' instruction pattern support moves between the + register and other hard register in the same class and that moving + a value into the register and back out not alter it. + + Since the same instruction used to move `word_mode' will work for + all narrower integer modes, it is not necessary on any machine for + `HARD_REGNO_MODE_OK' to distinguish between these modes, provided + you define patterns `movhi', etc., to take advantage of this. This + is useful because of the interaction between `HARD_REGNO_MODE_OK' + and `MODES_TIEABLE_P'; it is very desirable for all integer modes + to be tieable. + + Many machines have special registers for floating point arithmetic. + Often people assume that floating point machine modes are allowed + only in floating point registers. This is not true. Any + registers that can hold integers can safely _hold_ a floating + point machine mode, whether or not floating arithmetic can be done + on it in those registers. Integer move instructions can be used + to move the values. + + On some machines, though, the converse is true: fixed-point machine + modes may not go in floating registers. This is true if the + floating registers normalize any value stored in them, because + storing a non-floating value there would garble it. In this case, + `HARD_REGNO_MODE_OK' should reject fixed-point machine modes in + floating registers. But if the floating registers do not + automatically normalize, if you can store any bit pattern in one + and retrieve it unchanged without a trap, then any machine mode + may go in a floating register, so you can define this macro to say + so. + + The primary significance of special floating registers is rather + that they are the registers acceptable in floating point arithmetic + instructions. However, this is of no concern to + `HARD_REGNO_MODE_OK'. You handle it by writing the proper + constraints for those instructions. + + On some machines, the floating registers are especially slow to + access, so that it is better to store a value in a stack frame + than in such a register if floating point arithmetic is not being + done. As long as the floating registers are not in class + `GENERAL_REGS', they will not be used unless some pattern's + constraint asks for one. + +`MODES_TIEABLE_P (MODE1, MODE2)' + A C expression that is nonzero if a value of mode MODE1 is + accessible in mode MODE2 without copying. + + If `HARD_REGNO_MODE_OK (R, MODE1)' and `HARD_REGNO_MODE_OK (R, + MODE2)' are always the same for any R, then `MODES_TIEABLE_P + (MODE1, MODE2)' should be nonzero. If they differ for any R, you + should define this macro to return zero unless some other + mechanism ensures the accessibility of the value in a narrower + mode. + + You should define this macro to return nonzero in as many cases as + possible since doing so will allow GCC to perform better register + allocation. + +`AVOID_CCMODE_COPIES' + Define this macro if the compiler should avoid copies to/from + `CCmode' registers. You should only define this macro if support + for copying to/from `CCmode' is incomplete. + + +File: gccint.info, Node: Leaf Functions, Next: Stack Registers, Prev: Values in Registers, Up: Registers + +10.8.4 Handling Leaf Functions +------------------------------ -Identifiers ------------ +On some machines, a leaf function (i.e., one which makes no calls) can +run more efficiently if it does not make its own register window. +Often this means it is required to receive its arguments in the +registers where they are passed by the caller, instead of the registers +where they would normally arrive. + + The special treatment for leaf functions generally applies only when +other conditions are met; for example, often they may use only those +registers for its own variables and temporaries. We use the term "leaf +function" to mean a function that is suitable for this special +handling, so that functions with no calls are not necessarily "leaf +functions". + + GCC assigns register numbers before it knows whether the function is +suitable for leaf function treatment. So it needs to renumber the +registers in order to output a leaf function. The following macros +accomplish this. + +`LEAF_REGISTERS' + Name of a char vector, indexed by hard register number, which + contains 1 for a register that is allowable in a candidate for leaf + function treatment. + + If leaf function treatment involves renumbering the registers, + then the registers marked here should be the ones before + renumbering--those that GCC would ordinarily allocate. The + registers which will actually be used in the assembler code, after + renumbering, should not be marked with 1 in this vector. + + Define this macro only if the target machine offers a way to + optimize the treatment of leaf functions. + +`LEAF_REG_REMAP (REGNO)' + A C expression whose value is the register number to which REGNO + should be renumbered, when a function is treated as a leaf + function. + + If REGNO is a register number which should not appear in a leaf + function before renumbering, then the expression should yield -1, + which will cause the compiler to abort. + + Define this macro only if the target machine offers a way to + optimize the treatment of leaf functions, and registers need to be + renumbered to do this. + + `TARGET_ASM_FUNCTION_PROLOGUE' and `TARGET_ASM_FUNCTION_EPILOGUE' +must usually treat leaf functions specially. They can test the C +variable `current_function_is_leaf' which is nonzero for leaf +functions. `current_function_is_leaf' is set prior to local register +allocation and is valid for the remaining compiler passes. They can +also test the C variable `current_function_uses_only_leaf_regs' which +is nonzero for leaf functions which only use leaf registers. +`current_function_uses_only_leaf_regs' is valid after reload and is +only useful if `LEAF_REGISTERS' is defined. - An `IDENTIFIER_NODE' represents a slightly more general concept that -the standard C or C++ concept of identifier. In particular, an -`IDENTIFIER_NODE' may contain a `$', or other extraordinary characters. + +File: gccint.info, Node: Stack Registers, Prev: Leaf Functions, Up: Registers + +10.8.5 Registers That Form a Stack +---------------------------------- - There are never two distinct `IDENTIFIER_NODE's representing the -same identifier. Therefore, you may use pointer equality to compare -`IDENTIFIER_NODE's, rather than using a routine like `strcmp'. +There are special features to handle computers where some of the +"registers" form a stack, as in the 80387 coprocessor for the 80386. +Stack registers are normally written by pushing onto the stack, and are +numbered relative to the top of the stack. - You can use the following macros to access identifiers: -`IDENTIFIER_POINTER' - The string represented by the identifier, represented as a - `char*'. This string is always `NUL'-terminated, and contains no - embedded `NUL' characters. + Currently, GCC can only handle one group of stack-like registers, and +they must be consecutively numbered. -`IDENTIFIER_LENGTH' - The length of the string returned by `IDENTIFIER_POINTER', not - including the trailing `NUL'. This value of `IDENTIFIER_LENGTH - (x)' is always the same as `strlen (IDENTIFIER_POINTER (x))'. +`STACK_REGS' + Define this if the machine has any stack-like registers. -`IDENTIFIER_OPNAME_P' - This predicate holds if the identifier represents the name of an - overloaded operator. In this case, you should not depend on the - contents of either the `IDENTIFIER_POINTER' or the - `IDENTIFIER_LENGTH'. +`FIRST_STACK_REG' + The number of the first stack-like register. This one is the top + of the stack. -`IDENTIFIER_TYPENAME_P' - This predicate holds if the identifier represents the name of a - user-defined conversion operator. In this case, the `TREE_TYPE' of - the `IDENTIFIER_NODE' holds the type to which the conversion - operator converts. +`LAST_STACK_REG' + The number of the last stack-like register. This one is the + bottom of the stack. + +File: gccint.info, Node: Register Classes, Next: Stack and Calling, Prev: Registers, Up: Target Macros + +10.9 Register Classes +===================== + +On many machines, the numbered registers are not all equivalent. For +example, certain registers may not be allowed for indexed addressing; +certain registers may not be allowed in some instructions. These +machine restrictions are described to the compiler using "register +classes". + + You define a number of register classes, giving each one a name and +saying which of the registers belong to it. Then you can specify +register classes that are allowed as operands to particular instruction +patterns. + + In general, each register will belong to several classes. In fact, +one class must be named `ALL_REGS' and contain all the registers. +Another class must be named `NO_REGS' and contain no registers. Often +the union of two classes will be another class; however, this is not +required. + + One of the classes must be named `GENERAL_REGS'. There is nothing +terribly special about the name, but the operand constraint letters `r' +and `g' specify this class. If `GENERAL_REGS' is the same as +`ALL_REGS', just define it as a macro which expands to `ALL_REGS'. + + Order the classes so that if class X is contained in class Y then X +has a lower class number than Y. + + The way classes other than `GENERAL_REGS' are specified in operand +constraints is through machine-dependent operand constraint letters. +You can define such letters to correspond to various classes, then use +them in operand constraints. + + You should define a class for the union of two classes whenever some +instruction allows both classes. For example, if an instruction allows +either a floating point (coprocessor) register or a general register +for a certain operand, you should define a class `FLOAT_OR_GENERAL_REGS' +which includes both of them. Otherwise you will get suboptimal code. + + You must also specify certain redundant information about the +register classes: for each class, which classes contain it and which +ones are contained in it; for each pair of classes, the largest class +contained in their union. + + When a value occupying several consecutive registers is expected in a +certain class, all the registers used must belong to that class. +Therefore, register classes cannot be used to enforce a requirement for +a register pair to start with an even-numbered register. The way to +specify this requirement is with `HARD_REGNO_MODE_OK'. + + Register classes used for input-operands of bitwise-and or shift +instructions have a special requirement: each such class must have, for +each fixed-point machine mode, a subclass whose registers can transfer +that mode to or from memory. For example, on some machines, the +operations for single-byte values (`QImode') are limited to certain +registers. When this is so, each register class that is used in a +bitwise-and or shift instruction must have a subclass consisting of +registers from which single-byte values can be loaded or stored. This +is so that `PREFERRED_RELOAD_CLASS' can always have a possible value to +return. + +`enum reg_class' + An enumeral type that must be defined with all the register class + names as enumeral values. `NO_REGS' must be first. `ALL_REGS' + must be the last register class, followed by one more enumeral + value, `LIM_REG_CLASSES', which is not a register class but rather + tells how many classes there are. + + Each register class has a number, which is the value of casting + the class name to type `int'. The number serves as an index in + many of the tables described below. + +`N_REG_CLASSES' + The number of distinct register classes, defined as follows: + + #define N_REG_CLASSES (int) LIM_REG_CLASSES + +`REG_CLASS_NAMES' + An initializer containing the names of the register classes as C + string constants. These names are used in writing some of the + debugging dumps. + +`REG_CLASS_CONTENTS' + An initializer containing the contents of the register classes, as + integers which are bit masks. The Nth integer specifies the + contents of class N. The way the integer MASK is interpreted is + that register R is in the class if `MASK & (1 << R)' is 1. + + When the machine has more than 32 registers, an integer does not + suffice. Then the integers are replaced by sub-initializers, + braced groupings containing several integers. Each + sub-initializer must be suitable as an initializer for the type + `HARD_REG_SET' which is defined in `hard-reg-set.h'. In this + situation, the first integer in each sub-initializer corresponds to + registers 0 through 31, the second integer to registers 32 through + 63, and so on. + +`REGNO_REG_CLASS (REGNO)' + A C expression whose value is a register class containing hard + register REGNO. In general there is more than one such class; + choose a class which is "minimal", meaning that no smaller class + also contains the register. + +`BASE_REG_CLASS' + A macro whose definition is the name of the class to which a valid + base register must belong. A base register is one used in an + address which is the register value plus a displacement. + +`MODE_BASE_REG_CLASS (MODE)' + This is a variation of the `BASE_REG_CLASS' macro which allows the + selection of a base register in a mode depenedent manner. If MODE + is VOIDmode then it should return the same value as + `BASE_REG_CLASS'. + +`INDEX_REG_CLASS' + A macro whose definition is the name of the class to which a valid + index register must belong. An index register is one used in an + address where its value is either multiplied by a scale factor or + added to another register (as well as added to a displacement). + +`REG_CLASS_FROM_LETTER (CHAR)' + A C expression which defines the machine-dependent operand + constraint letters for register classes. If CHAR is such a + letter, the value should be the register class corresponding to + it. Otherwise, the value should be `NO_REGS'. The register + letter `r', corresponding to class `GENERAL_REGS', will not be + passed to this macro; you do not need to handle it. + +`REGNO_OK_FOR_BASE_P (NUM)' + A C expression which is nonzero if register number NUM is suitable + for use as a base register in operand addresses. It may be either + a suitable hard register or a pseudo register that has been + allocated such a hard register. + +`REGNO_MODE_OK_FOR_BASE_P (NUM, MODE)' + A C expression that is just like `REGNO_OK_FOR_BASE_P', except that + that expression may examine the mode of the memory reference in + MODE. You should define this macro if the mode of the memory + reference affects whether a register may be used as a base + register. If you define this macro, the compiler will use it + instead of `REGNO_OK_FOR_BASE_P'. + +`REGNO_OK_FOR_INDEX_P (NUM)' + A C expression which is nonzero if register number NUM is suitable + for use as an index register in operand addresses. It may be + either a suitable hard register or a pseudo register that has been + allocated such a hard register. + + The difference between an index register and a base register is + that the index register may be scaled. If an address involves the + sum of two registers, neither one of them scaled, then either one + may be labeled the "base" and the other the "index"; but whichever + labeling is used must fit the machine's constraints of which + registers may serve in each capacity. The compiler will try both + labelings, looking for one that is valid, and will reload one or + both registers only if neither labeling works. + +`PREFERRED_RELOAD_CLASS (X, CLASS)' + A C expression that places additional restrictions on the register + class to use when it is necessary to copy value X into a register + in class CLASS. The value is a register class; perhaps CLASS, or + perhaps another, smaller class. On many machines, the following + definition is safe: + + #define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS + + Sometimes returning a more restrictive class makes better code. + For example, on the 68000, when X is an integer constant that is + in range for a `moveq' instruction, the value of this macro is + always `DATA_REGS' as long as CLASS includes the data registers. + Requiring a data register guarantees that a `moveq' will be used. + + If X is a `const_double', by returning `NO_REGS' you can force X + into a memory constant. This is useful on certain machines where + immediate floating values cannot be loaded into certain kinds of + registers. + +`PREFERRED_OUTPUT_RELOAD_CLASS (X, CLASS)' + Like `PREFERRED_RELOAD_CLASS', but for output reloads instead of + input reloads. If you don't define this macro, the default is to + use CLASS, unchanged. + +`LIMIT_RELOAD_CLASS (MODE, CLASS)' + A C expression that places additional restrictions on the register + class to use when it is necessary to be able to hold a value of + mode MODE in a reload register for which class CLASS would + ordinarily be used. + + Unlike `PREFERRED_RELOAD_CLASS', this macro should be used when + there are certain modes that simply can't go in certain reload + classes. + + The value is a register class; perhaps CLASS, or perhaps another, + smaller class. + + Don't define this macro unless the target machine has limitations + which require the macro to do something nontrivial. + +`SECONDARY_RELOAD_CLASS (CLASS, MODE, X)' +`SECONDARY_INPUT_RELOAD_CLASS (CLASS, MODE, X)' +`SECONDARY_OUTPUT_RELOAD_CLASS (CLASS, MODE, X)' + Many machines have some registers that cannot be copied directly + to or from memory or even from other types of registers. An + example is the `MQ' register, which on most machines, can only be + copied to or from general registers, but not memory. Some + machines allow copying all registers to and from memory, but + require a scratch register for stores to some memory locations + (e.g., those with symbolic address on the RT, and those with + certain symbolic address on the Sparc when compiling PIC). In + some cases, both an intermediate and a scratch register are + required. + + You should define these macros to indicate to the reload phase + that it may need to allocate at least one register for a reload in + addition to the register to contain the data. Specifically, if + copying X to a register CLASS in MODE requires an intermediate + register, you should define `SECONDARY_INPUT_RELOAD_CLASS' to + return the largest register class all of whose registers can be + used as intermediate registers or scratch registers. + + If copying a register CLASS in MODE to X requires an intermediate + or scratch register, `SECONDARY_OUTPUT_RELOAD_CLASS' should be + defined to return the largest register class required. If the + requirements for input and output reloads are the same, the macro + `SECONDARY_RELOAD_CLASS' should be used instead of defining both + macros identically. + + The values returned by these macros are often `GENERAL_REGS'. + Return `NO_REGS' if no spare register is needed; i.e., if X can be + directly copied to or from a register of CLASS in MODE without + requiring a scratch register. Do not define this macro if it + would always return `NO_REGS'. + + If a scratch register is required (either with or without an + intermediate register), you should define patterns for + `reload_inM' or `reload_outM', as required (*note Standard + Names::. These patterns, which will normally be implemented with + a `define_expand', should be similar to the `movM' patterns, + except that operand 2 is the scratch register. + + Define constraints for the reload register and scratch register + that contain a single register class. If the original reload + register (whose class is CLASS) can meet the constraint given in + the pattern, the value returned by these macros is used for the + class of the scratch register. Otherwise, two additional reload + registers are required. Their classes are obtained from the + constraints in the insn pattern. + + X might be a pseudo-register or a `subreg' of a pseudo-register, + which could either be in a hard register or in memory. Use + `true_regnum' to find out; it will return -1 if the pseudo is in + memory and the hard register number if it is in a register. + + These macros should not be used in the case where a particular + class of registers can only be copied to memory and not to another + class of registers. In that case, secondary reload registers are + not needed and would not be helpful. Instead, a stack location + must be used to perform the copy and the `movM' pattern should use + memory as an intermediate storage. This case often occurs between + floating-point and general registers. + +`SECONDARY_MEMORY_NEEDED (CLASS1, CLASS2, M)' + Certain machines have the property that some registers cannot be + copied to some other registers without using memory. Define this + macro on those machines to be a C expression that is nonzero if + objects of mode M in registers of CLASS1 can only be copied to + registers of class CLASS2 by storing a register of CLASS1 into + memory and loading that memory location into a register of CLASS2. + + Do not define this macro if its value would always be zero. + +`SECONDARY_MEMORY_NEEDED_RTX (MODE)' + Normally when `SECONDARY_MEMORY_NEEDED' is defined, the compiler + allocates a stack slot for a memory location needed for register + copies. If this macro is defined, the compiler instead uses the + memory location defined by this macro. + + Do not define this macro if you do not define + `SECONDARY_MEMORY_NEEDED'. + +`SECONDARY_MEMORY_NEEDED_MODE (MODE)' + When the compiler needs a secondary memory location to copy + between two registers of mode MODE, it normally allocates + sufficient memory to hold a quantity of `BITS_PER_WORD' bits and + performs the store and load operations in a mode that many bits + wide and whose class is the same as that of MODE. + + This is right thing to do on most machines because it ensures that + all bits of the register are copied and prevents accesses to the + registers in a narrower mode, which some machines prohibit for + floating-point registers. + + However, this default behavior is not correct on some machines, + such as the DEC Alpha, that store short integers in floating-point + registers differently than in integer registers. On those + machines, the default widening will not work correctly and you + must define this macro to suppress that widening in some cases. + See the file `alpha.h' for details. + + Do not define this macro if you do not define + `SECONDARY_MEMORY_NEEDED' or if widening MODE to a mode that is + `BITS_PER_WORD' bits wide is correct for your machine. + +`SMALL_REGISTER_CLASSES' + On some machines, it is risky to let hard registers live across + arbitrary insns. Typically, these machines have instructions that + require values to be in specific registers (like an accumulator), + and reload will fail if the required hard register is used for + another purpose across such an insn. + + Define `SMALL_REGISTER_CLASSES' to be an expression with a nonzero + value on these machines. When this macro has a nonzero value, the + compiler will try to minimize the lifetime of hard registers. + + It is always safe to define this macro with a nonzero value, but + if you unnecessarily define it, you will reduce the amount of + optimizations that can be performed in some cases. If you do not + define this macro with a nonzero value when it is required, the + compiler will run out of spill registers and print a fatal error + message. For most machines, you should not define this macro at + all. + +`CLASS_LIKELY_SPILLED_P (CLASS)' + A C expression whose value is nonzero if pseudos that have been + assigned to registers of class CLASS would likely be spilled + because registers of CLASS are needed for spill registers. + + The default value of this macro returns 1 if CLASS has exactly one + register and zero otherwise. On most machines, this default + should be used. Only define this macro to some other expression + if pseudos allocated by `local-alloc.c' end up in memory because + their hard registers were needed for spill registers. If this + macro returns nonzero for those classes, those pseudos will only + be allocated by `global.c', which knows how to reallocate the + pseudo to another register. If there would not be another + register available for reallocation, you should not change the + definition of this macro since the only effect of such a + definition would be to slow down register allocation. + +`CLASS_MAX_NREGS (CLASS, MODE)' + A C expression for the maximum number of consecutive registers of + class CLASS needed to hold a value of mode MODE. + + This is closely related to the macro `HARD_REGNO_NREGS'. In fact, + the value of the macro `CLASS_MAX_NREGS (CLASS, MODE)' should be + the maximum value of `HARD_REGNO_NREGS (REGNO, MODE)' for all + REGNO values in the class CLASS. + + This macro helps control the handling of multiple-word values in + the reload pass. + +`CLASS_CANNOT_CHANGE_MODE' + If defined, a C expression for a class that contains registers for + which the compiler may not change modes arbitrarily. + +`CLASS_CANNOT_CHANGE_MODE_P(FROM, TO)' + A C expression that is true if, for a register in + `CLASS_CANNOT_CHANGE_MODE', the requested mode punning is invalid. + + For the example, loading 32-bit integer or floating-point objects + into floating-point registers on the Alpha extends them to 64 bits. + Therefore loading a 64-bit object and then storing it as a 32-bit + object does not store the low-order 32 bits, as would be the case + for a normal register. Therefore, `alpha.h' defines + `CLASS_CANNOT_CHANGE_MODE' as `FLOAT_REGS' and + `CLASS_CANNOT_CHANGE_MODE_P' restricts mode changes to same-size + modes. + + Compare this to IA-64, which extends floating-point values to 82 + bits, and stores 64-bit integers in a different format than 64-bit + doubles. Therefore `CLASS_CANNOT_CHANGE_MODE_P' is always true. + + Three other special macros describe which operands fit which +constraint letters. + +`CONST_OK_FOR_LETTER_P (VALUE, C)' + A C expression that defines the machine-dependent operand + constraint letters (`I', `J', `K', ... `P') that specify + particular ranges of integer values. If C is one of those + letters, the expression should check that VALUE, an integer, is in + the appropriate range and return 1 if so, 0 otherwise. If C is + not one of those letters, the value should be 0 regardless of + VALUE. + +`CONST_DOUBLE_OK_FOR_LETTER_P (VALUE, C)' + A C expression that defines the machine-dependent operand + constraint letters that specify particular ranges of + `const_double' values (`G' or `H'). + + If C is one of those letters, the expression should check that + VALUE, an RTX of code `const_double', is in the appropriate range + and return 1 if so, 0 otherwise. If C is not one of those + letters, the value should be 0 regardless of VALUE. + + `const_double' is used for all floating-point constants and for + `DImode' fixed-point constants. A given letter can accept either + or both kinds of values. It can use `GET_MODE' to distinguish + between these kinds. + +`EXTRA_CONSTRAINT (VALUE, C)' + A C expression that defines the optional machine-dependent + constraint letters that can be used to segregate specific types of + operands, usually memory references, for the target machine. Any + letter that is not elsewhere defined and not matched by + `REG_CLASS_FROM_LETTER' may be used. Normally this macro will not + be defined. + + If it is required for a particular target machine, it should + return 1 if VALUE corresponds to the operand type represented by + the constraint letter C. If C is not defined as an extra + constraint, the value returned should be 0 regardless of VALUE. + + For example, on the ROMP, load instructions cannot have their + output in r0 if the memory reference contains a symbolic address. + Constraint letter `Q' is defined as representing a memory address + that does _not_ contain a symbolic address. An alternative is + specified with a `Q' constraint on the input and `r' on the + output. The next alternative specifies `m' on the input and a + register class that does not include r0 on the output.  -File: gccint.info, Node: Containers, Prev: Identifiers, Up: Tree overview +File: gccint.info, Node: Stack and Calling, Next: Varargs, Prev: Register Classes, Up: Target Macros -Containers ----------- +10.10 Stack Layout and Calling Conventions +========================================== - Two common container data structures can be represented directly with -tree nodes. A `TREE_LIST' is a singly linked list containing two trees -per node. These are the `TREE_PURPOSE' and `TREE_VALUE' of each node. -(Often, the `TREE_PURPOSE' contains some kind of tag, or additional -information, while the `TREE_VALUE' contains the majority of the -payload. In other cases, the `TREE_PURPOSE' is simply `NULL_TREE', -while in still others both the `TREE_PURPOSE' and `TREE_VALUE' are of -equal stature.) Given one `TREE_LIST' node, the next node is found by -following the `TREE_CHAIN'. If the `TREE_CHAIN' is `NULL_TREE', then -you have reached the end of the list. +This describes the stack layout and calling conventions. - A `TREE_VEC' is a simple vector. The `TREE_VEC_LENGTH' is an -integer (not a tree) giving the number of nodes in the vector. The -nodes themselves are accessed using the `TREE_VEC_ELT' macro, which -takes two arguments. The first is the `TREE_VEC' in question; the -second is an integer indicating which element in the vector is desired. -The elements are indexed from zero. +* Menu: + +* Frame Layout:: +* Exception Handling:: +* Stack Checking:: +* Frame Registers:: +* Elimination:: +* Stack Arguments:: +* Register Arguments:: +* Scalar Return:: +* Aggregate Return:: +* Caller Saves:: +* Function Entry:: +* Profiling:: +* Tail Calls:: + + +File: gccint.info, Node: Frame Layout, Next: Exception Handling, Up: Stack and Calling + +10.10.1 Basic Stack Layout +-------------------------- + +Here is the basic stack layout. + +`STACK_GROWS_DOWNWARD' + Define this macro if pushing a word onto the stack moves the stack + pointer to a smaller address. + + When we say, "define this macro if ...," it means that the + compiler checks this macro only with `#ifdef' so the precise + definition used does not matter. + +`STACK_PUSH_CODE' + This macro defines the operation used when something is pushed on + the stack. In RTL, a push operation will be `(set (mem + (STACK_PUSH_CODE (reg sp))) ...)' + + The choices are `PRE_DEC', `POST_DEC', `PRE_INC', and `POST_INC'. + Which of these is correct depends on the stack direction and on + whether the stack pointer points to the last item on the stack or + whether it points to the space for the next item on the stack. + + The default is `PRE_DEC' when `STACK_GROWS_DOWNWARD' is defined, + which is almost always right, and `PRE_INC' otherwise, which is + often wrong. + +`FRAME_GROWS_DOWNWARD' + Define this macro if the addresses of local variable slots are at + negative offsets from the frame pointer. + +`ARGS_GROW_DOWNWARD' + Define this macro if successive arguments to a function occupy + decreasing addresses on the stack. + +`STARTING_FRAME_OFFSET' + Offset from the frame pointer to the first local variable slot to + be allocated. + + If `FRAME_GROWS_DOWNWARD', find the next slot's offset by + subtracting the first slot's length from `STARTING_FRAME_OFFSET'. + Otherwise, it is found by adding the length of the first slot to + the value `STARTING_FRAME_OFFSET'. + +`STACK_POINTER_OFFSET' + Offset from the stack pointer register to the first location at + which outgoing arguments are placed. If not specified, the + default value of zero is used. This is the proper value for most + machines. + + If `ARGS_GROW_DOWNWARD', this is the offset to the location above + the first location at which outgoing arguments are placed. + +`FIRST_PARM_OFFSET (FUNDECL)' + Offset from the argument pointer register to the first argument's + address. On some machines it may depend on the data type of the + function. + + If `ARGS_GROW_DOWNWARD', this is the offset to the location above + the first argument's address. + +`STACK_DYNAMIC_OFFSET (FUNDECL)' + Offset from the stack pointer register to an item dynamically + allocated on the stack, e.g., by `alloca'. + + The default value for this macro is `STACK_POINTER_OFFSET' plus the + length of the outgoing arguments. The default is correct for most + machines. See `function.c' for details. + +`DYNAMIC_CHAIN_ADDRESS (FRAMEADDR)' + A C expression whose value is RTL representing the address in a + stack frame where the pointer to the caller's frame is stored. + Assume that FRAMEADDR is an RTL expression for the address of the + stack frame itself. + + If you don't define this macro, the default is to return the value + of FRAMEADDR--that is, the stack frame address is also the address + of the stack word that points to the previous frame. + +`SETUP_FRAME_ADDRESSES' + If defined, a C expression that produces the machine-specific code + to setup the stack so that arbitrary frames can be accessed. For + example, on the Sparc, we must flush all of the register windows + to the stack before we can access arbitrary stack frames. You + will seldom need to define this macro. + +`BUILTIN_SETJMP_FRAME_VALUE' + If defined, a C expression that contains an rtx that is used to + store the address of the current frame into the built in `setjmp' + buffer. The default value, `virtual_stack_vars_rtx', is correct + for most machines. One reason you may need to define this macro + is if `hard_frame_pointer_rtx' is the appropriate value on your + machine. + +`RETURN_ADDR_RTX (COUNT, FRAMEADDR)' + A C expression whose value is RTL representing the value of the + return address for the frame COUNT steps up from the current + frame, after the prologue. FRAMEADDR is the frame pointer of the + COUNT frame, or the frame pointer of the COUNT - 1 frame if + `RETURN_ADDR_IN_PREVIOUS_FRAME' is defined. + + The value of the expression must always be the correct address when + COUNT is zero, but may be `NULL_RTX' if there is not way to + determine the return address of other frames. + +`RETURN_ADDR_IN_PREVIOUS_FRAME' + Define this if the return address of a particular stack frame is + accessed from the frame pointer of the previous stack frame. + +`INCOMING_RETURN_ADDR_RTX' + A C expression whose value is RTL representing the location of the + incoming return address at the beginning of any function, before + the prologue. This RTL is either a `REG', indicating that the + return value is saved in `REG', or a `MEM' representing a location + in the stack. + + You only need to define this macro if you want to support call + frame debugging information like that provided by DWARF 2. + + If this RTL is a `REG', you should also define + `DWARF_FRAME_RETURN_COLUMN' to `DWARF_FRAME_REGNUM (REGNO)'. + +`INCOMING_FRAME_SP_OFFSET' + A C expression whose value is an integer giving the offset, in + bytes, from the value of the stack pointer register to the top of + the stack frame at the beginning of any function, before the + prologue. The top of the frame is defined to be the value of the + stack pointer in the previous frame, just before the call + instruction. + + You only need to define this macro if you want to support call + frame debugging information like that provided by DWARF 2. + +`ARG_POINTER_CFA_OFFSET (FUNDECL)' + A C expression whose value is an integer giving the offset, in + bytes, from the argument pointer to the canonical frame address + (cfa). The final value should coincide with that calculated by + `INCOMING_FRAME_SP_OFFSET'. Which is unfortunately not usable + during virtual register instantiation. + + The default value for this macro is `FIRST_PARM_OFFSET (fundecl)', + which is correct for most machines; in general, the arguments are + found immediately before the stack frame. Note that this is not + the case on some targets that save registers into the caller's + frame, such as SPARC and rs6000, and so such targets need to + define this macro. + + You only need to define this macro if the default is incorrect, + and you want to support call frame debugging information like that + provided by DWARF 2. + +`SMALL_STACK' + Define this macro if the stack size for the target is very small. + This has the effect of disabling gcc's built-in `alloca', though + `__builtin_alloca' is not affected.