-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
funds for GNU development.
\1f
-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
-----------------------------
+\1f
+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.
+
+\1f
+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.
+
+
+\1f
+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::.
+
+\1f
+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")
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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")))]
+ ...)
+
+\1f
+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
+
+
+
+\1f
+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.
+
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
\1f
-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.
+
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
\1f
-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
-------------------------------
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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)))])
+
+\1f
+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.
+
+\1f
+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.
+\1f
+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.
+
+\1f
+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")
+
+\1f
+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.
\1f
-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.
+\1f
+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.
-
-\1f
-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.
-
-\1f
-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.
+\1f
+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/'.
+
+\1f
+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.
+
+\1f
+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.
+
+
+\1f
+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'.
-
-\1f
-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 <gcc@gcc.gnu.org>) 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:
+\1f
+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.
+
+\1f
+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'.
-
-\1f
-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.
-
-\1f
-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'.
+
+\1f
+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.
\1f
-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.
+
+
+\1f
+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.
\1f
-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.
+
+\1f
+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.
+\1f
+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.
+\1f
+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.
\1f
-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::
+
+\1f
+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.
projects / msp430-gcc.git / blobdiff