-This is doc/gccint.info, produced by makeinfo version 4.5 from
-doc/gccint.texi.
-
-INFO-DIR-SECTION Programming
-START-INFO-DIR-ENTRY
-* gccint: (gccint). Internals of the GNU Compiler Collection.
-END-INFO-DIR-ENTRY
- This file documents the internals of the GNU compilers.
-
- Published by the Free Software Foundation
-59 Temple Place - Suite 330
-Boston, MA 02111-1307 USA
-
- Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-1999, 2000, 2001, 2002 Free Software Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being "GNU General Public License" and "Funding Free
-Software", the Front-Cover texts being (a) (see below), and with the
-Back-Cover Texts being (b) (see below). A copy of the license is
-included in the section entitled "GNU Free Documentation License".
-
- (a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
- (b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
-software. Copies published by the Free Software Foundation raise
-funds for GNU development.
-
-\1f
-File: gccint.info, Node: RTL Template, Next: Output Template, Prev: Example, Up: Machine Desc
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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
-
-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")))]
- ...)
-