| @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001, |
| @c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. |
| @c This is part of the GCC manual. |
| @c For copying conditions, see the file gcc.texi. |
| |
| @ifset INTERNALS |
| @node Machine Desc |
| @chapter Machine Descriptions |
| @cindex machine descriptions |
| |
| A machine description has two parts: a file of instruction patterns |
| (@file{.md} file) and a C header file of macro definitions. |
| |
| The @file{.md} file for a target machine contains a pattern for each |
| instruction that the target machine supports (or at least each instruction |
| that is worth telling the compiler about). It may also contain comments. |
| A semicolon causes the rest of the line to be a comment, unless the semicolon |
| is inside a quoted string. |
| |
| See the next chapter for information on the C header file. |
| |
| @menu |
| * Overview:: How the machine description is used. |
| * Patterns:: How to write instruction patterns. |
| * Example:: An explained example of a @code{define_insn} pattern. |
| * RTL Template:: The RTL template defines what insns match a pattern. |
| * Output Template:: The output template says how to make assembler code |
| from such an insn. |
| * Output Statement:: For more generality, write C code to output |
| the assembler code. |
| * Predicates:: Controlling what kinds of operands can be used |
| for an insn. |
| * Constraints:: Fine-tuning operand selection. |
| * Standard Names:: Names mark patterns to use for code generation. |
| * Pattern Ordering:: When the order of patterns makes a difference. |
| * Dependent Patterns:: Having one pattern may make you need another. |
| * Jump Patterns:: Special considerations for patterns for jump insns. |
| * Looping Patterns:: How to define patterns for special looping insns. |
| * Insn Canonicalizations::Canonicalization of Instructions |
| * Expander Definitions::Generating a sequence of several RTL insns |
| for a standard operation. |
| * Insn Splitting:: Splitting Instructions into Multiple Instructions. |
| * Including Patterns:: Including Patterns in Machine Descriptions. |
| * Peephole Definitions::Defining machine-specific peephole optimizations. |
| * Insn Attributes:: Specifying the value of attributes for generated insns. |
| * Conditional Execution::Generating @code{define_insn} patterns for |
| predication. |
| * Constant Definitions::Defining symbolic constants that can be used in the |
| md file. |
| * Iterators:: Using iterators to generate patterns from a template. |
| @end menu |
| |
| @node Overview |
| @section Overview of How the Machine Description is Used |
| |
| There are three main conversions that happen in the compiler: |
| |
| @enumerate |
| |
| @item |
| The front end reads the source code and builds a parse tree. |
| |
| @item |
| The parse tree is used to generate an RTL insn list based on named |
| instruction patterns. |
| |
| @item |
| The insn list is matched against the RTL templates to produce assembler |
| code. |
| |
| @end enumerate |
| |
| For the generate pass, only the names of the insns matter, from either a |
| named @code{define_insn} or a @code{define_expand}. The compiler will |
| choose the pattern with the right name and apply the operands according |
| to the documentation later in this chapter, without regard for the RTL |
| template or operand constraints. Note that the names the compiler looks |
| for are hard-coded in the compiler---it will ignore unnamed patterns and |
| patterns with names it doesn't know about, but if you don't provide a |
| named pattern it needs, it will abort. |
| |
| If a @code{define_insn} is used, the template given is inserted into the |
| insn list. If a @code{define_expand} is used, one of three things |
| happens, based on the condition logic. The condition logic may manually |
| create new insns for the insn list, say via @code{emit_insn()}, and |
| invoke @code{DONE}. For certain named patterns, it may invoke @code{FAIL} to tell the |
| compiler to use an alternate way of performing that task. If it invokes |
| neither @code{DONE} nor @code{FAIL}, the template given in the pattern |
| is inserted, as if the @code{define_expand} were a @code{define_insn}. |
| |
| Once the insn list is generated, various optimization passes convert, |
| replace, and rearrange the insns in the insn list. This is where the |
| @code{define_split} and @code{define_peephole} patterns get used, for |
| example. |
| |
| Finally, the insn list's RTL is matched up with the RTL templates in the |
| @code{define_insn} patterns, and those patterns are used to emit the |
| final assembly code. For this purpose, each named @code{define_insn} |
| acts like it's unnamed, since the names are ignored. |
| |
| @node Patterns |
| @section Everything about Instruction Patterns |
| @cindex patterns |
| @cindex instruction patterns |
| |
| @findex define_insn |
| 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 @code{define_insn} expression. |
| |
| A @code{define_insn} is an RTL expression containing four or five operands: |
| |
| @enumerate |
| @item |
| 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 @samp{*} 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. |
| |
| @item |
| The @dfn{RTL template} (@pxref{RTL Template}) is a vector of incomplete |
| RTL expressions which show what the instruction should look like. It is |
| incomplete because it may contain @code{match_operand}, |
| @code{match_operator}, and @code{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 @code{parallel} expression containing the |
| elements described. |
| |
| @item |
| @cindex pattern conditions |
| @cindex conditions, in patterns |
| 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. |
| |
| @cindex named patterns and conditions |
| 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. |
| |
| @findex operands |
| 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 |
| @code{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. |
| |
| @item |
| The @dfn{output template}: a string that says how to output matching |
| insns as assembler code. @samp{%} in this string specifies where |
| to substitute the value of an operand. @xref{Output Template}. |
| |
| When simple substitution isn't general enough, you can specify a piece |
| of C code to compute the output. @xref{Output Statement}. |
| |
| @item |
| Optionally, a vector containing the values of attributes for insns matching |
| this pattern. @xref{Insn Attributes}. |
| @end enumerate |
| |
| @node Example |
| @section Example of @code{define_insn} |
| @cindex @code{define_insn} example |
| |
| Here is an actual example of an instruction pattern, for the 68000/68020. |
| |
| @smallexample |
| (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\"; |
| @}") |
| @end smallexample |
| |
| @noindent |
| This can also be written using braced strings: |
| |
| @smallexample |
| (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"; |
| @}) |
| @end smallexample |
| |
| 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 |
| @samp{tstsi} means ``test a @code{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. |
| |
| @samp{"rm"} is an operand constraint. Its meaning is explained below. |
| |
| @node RTL Template |
| @section RTL Template |
| @cindex RTL insn template |
| @cindex generating insns |
| @cindex insns, generating |
| @cindex recognizing insns |
| @cindex insns, recognizing |
| |
| 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. |
| |
| @table @code |
| @findex match_operand |
| @item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint}) |
| This expression is a placeholder for operand number @var{n} of |
| the insn. When constructing an insn, operand number @var{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 @var{n}; but it must satisfy @var{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 @code{match_operand} |
| expression in the pattern for each operand number. Usually operands |
| are numbered in the order of appearance in @code{match_operand} |
| expressions. In the case of a @code{define_expand}, any operand numbers |
| used only in @code{match_dup} expressions have higher values than all |
| other operand numbers. |
| |
| @var{predicate} is a string that is the name of a function that |
| accepts two arguments, an expression and a machine mode. |
| @xref{Predicates}. During matching, the function will be called with |
| the putative operand as the expression and @var{m} as the mode |
| argument (if @var{m} is not specified, @code{VOIDmode} will be used, |
| which normally causes @var{predicate} to accept any mode). If it |
| returns zero, this instruction pattern fails to match. |
| @var{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, @var{predicate} will reject modes other than @var{m}---but |
| not always. For example, the predicate @code{address_operand} uses |
| @var{m} as the mode of memory ref that the address should be valid for. |
| Many predicates accept @code{const_int} nodes even though their mode is |
| @code{VOIDmode}. |
| |
| @var{constraint} controls reloading and the choice of the best register |
| class to use for a value, as explained later (@pxref{Constraints}). |
| If the constraint would be an empty string, it can be omitted. |
| |
| 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. |
| |
| @findex match_scratch |
| @item (match_scratch:@var{m} @var{n} @var{constraint}) |
| This expression is also a placeholder for operand number @var{n} |
| and indicates that operand must be a @code{scratch} or @code{reg} |
| expression. |
| |
| When matching patterns, this is equivalent to |
| |
| @smallexample |
| (match_operand:@var{m} @var{n} "scratch_operand" @var{pred}) |
| @end smallexample |
| |
| but, when generating RTL, it produces a (@code{scratch}:@var{m}) |
| expression. |
| |
| If the last few expressions in a @code{parallel} are @code{clobber} |
| expressions whose operands are either a hard register or |
| @code{match_scratch}, the combiner can add or delete them when |
| necessary. @xref{Side Effects}. |
| |
| @findex match_dup |
| @item (match_dup @var{n}) |
| This expression is also a placeholder for operand number @var{n}. |
| It is used when the operand needs to appear more than once in the |
| insn. |
| |
| In construction, @code{match_dup} acts just like @code{match_operand}: |
| the operand is substituted into the insn being constructed. But in |
| matching, @code{match_dup} behaves differently. It assumes that operand |
| number @var{n} has already been determined by a @code{match_operand} |
| appearing earlier in the recognition template, and it matches only an |
| identical-looking expression. |
| |
| Note that @code{match_dup} should not be used to tell the compiler that |
| a particular register is being used for two operands (example: |
| @code{add} that adds one register to another; the second register is |
| both an input operand and the output operand). Use a matching |
| constraint (@pxref{Simple Constraints}) for those. @code{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. |
| |
| @findex match_operator |
| @item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}]) |
| 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 @var{n}, and whose |
| operands are constructed from the patterns @var{operands}. |
| |
| When matching an expression, it matches an expression if the function |
| @var{predicate} returns nonzero on that expression @emph{and} the |
| patterns @var{operands} match the operands of the expression. |
| |
| Suppose that the function @code{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 @var{mode}: |
| |
| @smallexample |
| int |
| commutative_integer_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) == RTX_COMM_ARITH |
| || code == EQ || code == NE); |
| @} |
| @end smallexample |
| |
| Then the following pattern will match any RTL expression consisting |
| of a commutative operator applied to two general operands: |
| |
| @smallexample |
| (match_operator:SI 3 "commutative_operator" |
| [(match_operand:SI 1 "general_operand" "g") |
| (match_operand:SI 2 "general_operand" "g")]) |
| @end smallexample |
| |
| Here the vector @code{[@var{operands}@dots{}]} 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 @code{match_operand}.) Operand 3 of the insn |
| will be the entire commutative expression: use @code{GET_CODE |
| (operands[3])} to see which commutative operator was used. |
| |
| The machine mode @var{m} of @code{match_operator} works like that of |
| @code{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 @code{match_operator} is used in a pattern for matching an insn, |
| it usually best if the operand number of the @code{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 @code{match_operator}. The |
| operand of the insn which corresponds to the @code{match_operator} |
| never has any constraints because it is never reloaded as a whole. |
| However, if parts of its @var{operands} are matched by |
| @code{match_operand} patterns, those parts may have constraints of |
| their own. |
| |
| @findex match_op_dup |
| @item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}]) |
| Like @code{match_dup}, except that it applies to operators instead of |
| operands. When constructing an insn, operand number @var{n} will be |
| substituted at this point. But in matching, @code{match_op_dup} behaves |
| differently. It assumes that operand number @var{n} has already been |
| determined by a @code{match_operator} appearing earlier in the |
| recognition template, and it matches only an identical-looking |
| expression. |
| |
| @findex match_parallel |
| @item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}]) |
| This pattern is a placeholder for an insn that consists of a |
| @code{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 @var{n} will be substituted at |
| this point. When matching an insn, it matches if the body of the insn |
| is a @code{parallel} expression with at least as many elements as the |
| vector of @var{subpat} expressions in the @code{match_parallel}, if each |
| @var{subpat} matches the corresponding element of the @code{parallel}, |
| @emph{and} the function @var{predicate} returns nonzero on the |
| @code{parallel} that is the body of the insn. It is the responsibility |
| of the predicate to validate elements of the @code{parallel} beyond |
| those listed in the @code{match_parallel}. |
| |
| A typical use of @code{match_parallel} is to match load and store |
| multiple expressions, which can contain a variable number of elements |
| in a @code{parallel}. For example, |
| |
| @smallexample |
| (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") |
| @end smallexample |
| |
| This example comes from @file{a29k.md}. The function |
| @code{load_multiple_operation} is defined in @file{a29k.c} and checks |
| that subsequent elements in the @code{parallel} are the same as the |
| @code{set} in the pattern, except that they are referencing subsequent |
| registers and memory locations. |
| |
| An insn that matches this pattern might look like: |
| |
| @smallexample |
| (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))))]) |
| @end smallexample |
| |
| @findex match_par_dup |
| @item (match_par_dup @var{n} [@var{subpat}@dots{}]) |
| Like @code{match_op_dup}, but for @code{match_parallel} instead of |
| @code{match_operator}. |
| |
| @end table |
| |
| @node Output Template |
| @section Output Templates and Operand Substitution |
| @cindex output templates |
| @cindex operand substitution |
| |
| @cindex @samp{%} in template |
| @cindex percent sign |
| The @dfn{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 @samp{%} 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 @samp{%} followed by a digit @var{n} says to output |
| operand @var{n} at that point in the string. |
| |
| @samp{%} 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 @code{PRINT_OPERAND} can define |
| additional letters with nonstandard meanings. |
| |
| @samp{%c@var{digit}} can be used to substitute an operand that is a |
| constant value without the syntax that normally indicates an immediate |
| operand. |
| |
| @samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of |
| the constant is negated before printing. |
| |
| @samp{%a@var{digit}} 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. |
| |
| @samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump |
| instruction. |
| |
| @samp{%=} 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. |
| |
| @samp{%} followed by a punctuation character specifies a substitution that |
| does not use an operand. Only one case is standard: @samp{%%} outputs a |
| @samp{%} into the assembler code. Other nonstandard cases can be |
| defined in the @code{PRINT_OPERAND} macro. You must also define |
| which punctuation characters are valid with the |
| @code{PRINT_OPERAND_PUNCT_VALID_P} macro. |
| |
| @cindex \ |
| @cindex backslash |
| The template may generate multiple assembler instructions. Write the text |
| for the instructions, with @samp{\;} between them. |
| |
| @cindex matching operands |
| 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 @samp{%} 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 @samp{movel} in MIT syntax is @samp{move.l} in Motorola |
| syntax. The same file of patterns is used for both kinds of output syntax, |
| but the character sequence @samp{%.} is used in each place where Motorola |
| syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax |
| defines the sequence to output a period; the macro for MIT syntax defines |
| it to do nothing. |
| |
| @cindex @code{#} in template |
| As a special case, a template consisting of the single character @code{#} |
| 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 @code{define_insn} that needs to emit |
| multiple assembler instructions, and there is an matching @code{define_split} |
| already defined, then you can simply use @code{#} as the output template |
| instead of writing an output template that emits the multiple assembler |
| instructions. |
| |
| If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct |
| of the form @samp{@{option0|option1|option2@}} in the templates. These |
| describe multiple variants of assembler language syntax. |
| @xref{Instruction Output}. |
| |
| @node Output Statement |
| @section C Statements for Assembler Output |
| @cindex output statements |
| @cindex C statements for assembler output |
| @cindex generating 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 @samp{@@}, 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 (@pxref{Multi-Alternative}). For example, |
| if a target machine has a two-address add instruction @samp{addr} to add |
| into a register and another @samp{addm} to add a register to memory, you |
| might write this pattern: |
| |
| @smallexample |
| (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") |
| @end smallexample |
| |
| @cindex @code{*} in template |
| @cindex asterisk in template |
| If the output control string starts with a @samp{*}, then it is not an |
| output template but rather a piece of C program that should compute a |
| template. It should execute a @code{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 @samp{\}. |
| |
| 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 @code{operands}, whose C data type |
| is @code{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 @code{INTVAL} is an |
| integer on the host machine. If the host machine has more bits in an |
| @code{int} than the target machine has in the mode in which the constant |
| will be used, then some of the bits you get from @code{INTVAL} will be |
| superfluous. For proper results, you must carefully disregard the |
| values of those bits. |
| |
| @findex output_asm_insn |
| It is possible to output an assembler instruction and then go on to output |
| or compute more of them, using the subroutine @code{output_asm_insn}. This |
| receives two arguments: a template-string and a vector of operands. The |
| vector may be @code{operands}, or it may be another array of @code{rtx} |
| that you declare locally and initialize yourself. |
| |
| @findex which_alternative |
| 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 |
| @code{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, @samp{clrreg} |
| for registers and @samp{clrmem} for memory locations. Here is how |
| a pattern could use @code{which_alternative} to choose between them: |
| |
| @smallexample |
| (define_insn "" |
| [(set (match_operand:SI 0 "general_operand" "=r,m") |
| (const_int 0))] |
| "" |
| @{ |
| return (which_alternative == 0 |
| ? "clrreg %0" : "clrmem %0"); |
| @}) |
| @end smallexample |
| |
| The example above, where the assembler code to generate was |
| @emph{solely} determined by the alternative, could also have been specified |
| as follows, having the output control string start with a @samp{@@}: |
| |
| @smallexample |
| @group |
| (define_insn "" |
| [(set (match_operand:SI 0 "general_operand" "=r,m") |
| (const_int 0))] |
| "" |
| "@@ |
| clrreg %0 |
| clrmem %0") |
| @end group |
| @end smallexample |
| |
| @node Predicates |
| @section Predicates |
| @cindex predicates |
| @cindex operand predicates |
| @cindex operator predicates |
| |
| A predicate determines whether a @code{match_operand} or |
| @code{match_operator} expression matches, and therefore whether the |
| surrounding instruction pattern will be used for that combination of |
| operands. GCC has a number of machine-independent predicates, and you |
| can define machine-specific predicates as needed. By convention, |
| predicates used with @code{match_operand} have names that end in |
| @samp{_operand}, and those used with @code{match_operator} have names |
| that end in @samp{_operator}. |
| |
| All predicates are Boolean functions (in the mathematical sense) of |
| two arguments: the RTL expression that is being considered at that |
| position in the instruction pattern, and the machine mode that the |
| @code{match_operand} or @code{match_operator} specifies. In this |
| section, the first argument is called @var{op} and the second argument |
| @var{mode}. Predicates can be called from C as ordinary two-argument |
| functions; this can be useful in output templates or other |
| machine-specific code. |
| |
| Operand predicates can allow operands that are not actually acceptable |
| to the hardware, as long as the constraints give reload the ability to |
| fix them up (@pxref{Constraints}). However, GCC will usually generate |
| better code if the predicates specify the requirements of the machine |
| instructions as closely as possible. Reload cannot fix up operands |
| that must be constants (``immediate operands''); you must use a |
| predicate that allows only constants, or else enforce the requirement |
| in the extra condition. |
| |
| @cindex predicates and machine modes |
| @cindex normal predicates |
| @cindex special predicates |
| Most predicates handle their @var{mode} argument in a uniform manner. |
| If @var{mode} is @code{VOIDmode} (unspecified), then @var{op} can have |
| any mode. If @var{mode} is anything else, then @var{op} must have the |
| same mode, unless @var{op} is a @code{CONST_INT} or integer |
| @code{CONST_DOUBLE}. These RTL expressions always have |
| @code{VOIDmode}, so it would be counterproductive to check that their |
| mode matches. Instead, predicates that accept @code{CONST_INT} and/or |
| integer @code{CONST_DOUBLE} check that the value stored in the |
| constant will fit in the requested mode. |
| |
| Predicates with this behavior are called @dfn{normal}. |
| @command{genrecog} can optimize the instruction recognizer based on |
| knowledge of how normal predicates treat modes. It can also diagnose |
| certain kinds of common errors in the use of normal predicates; for |
| instance, it is almost always an error to use a normal predicate |
| without specifying a mode. |
| |
| Predicates that do something different with their @var{mode} argument |
| are called @dfn{special}. The generic predicates |
| @code{address_operand} and @code{pmode_register_operand} are special |
| predicates. @command{genrecog} does not do any optimizations or |
| diagnosis when special predicates are used. |
| |
| @menu |
| * Machine-Independent Predicates:: Predicates available to all back ends. |
| * Defining Predicates:: How to write machine-specific predicate |
| functions. |
| @end menu |
| |
| @node Machine-Independent Predicates |
| @subsection Machine-Independent Predicates |
| @cindex machine-independent predicates |
| @cindex generic predicates |
| |
| These are the generic predicates available to all back ends. They are |
| defined in @file{recog.c}. The first category of predicates allow |
| only constant, or @dfn{immediate}, operands. |
| |
| @defun immediate_operand |
| This predicate allows any sort of constant that fits in @var{mode}. |
| It is an appropriate choice for instructions that take operands that |
| must be constant. |
| @end defun |
| |
| @defun const_int_operand |
| This predicate allows any @code{CONST_INT} expression that fits in |
| @var{mode}. It is an appropriate choice for an immediate operand that |
| does not allow a symbol or label. |
| @end defun |
| |
| @defun const_double_operand |
| This predicate accepts any @code{CONST_DOUBLE} expression that has |
| exactly @var{mode}. If @var{mode} is @code{VOIDmode}, it will also |
| accept @code{CONST_INT}. It is intended for immediate floating point |
| constants. |
| @end defun |
| |
| @noindent |
| The second category of predicates allow only some kind of machine |
| register. |
| |
| @defun register_operand |
| This predicate allows any @code{REG} or @code{SUBREG} expression that |
| is valid for @var{mode}. It is often suitable for arithmetic |
| instruction operands on a RISC machine. |
| @end defun |
| |
| @defun pmode_register_operand |
| This is a slight variant on @code{register_operand} which works around |
| a limitation in the machine-description reader. |
| |
| @smallexample |
| (match_operand @var{n} "pmode_register_operand" @var{constraint}) |
| @end smallexample |
| |
| @noindent |
| means exactly what |
| |
| @smallexample |
| (match_operand:P @var{n} "register_operand" @var{constraint}) |
| @end smallexample |
| |
| @noindent |
| would mean, if the machine-description reader accepted @samp{:P} |
| mode suffixes. Unfortunately, it cannot, because @code{Pmode} is an |
| alias for some other mode, and might vary with machine-specific |
| options. @xref{Misc}. |
| @end defun |
| |
| @defun scratch_operand |
| This predicate allows hard registers and @code{SCRATCH} expressions, |
| but not pseudo-registers. It is used internally by @code{match_scratch}; |
| it should not be used directly. |
| @end defun |
| |
| @noindent |
| The third category of predicates allow only some kind of memory reference. |
| |
| @defun memory_operand |
| This predicate allows any valid reference to a quantity of mode |
| @var{mode} in memory, as determined by the weak form of |
| @code{GO_IF_LEGITIMATE_ADDRESS} (@pxref{Addressing Modes}). |
| @end defun |
| |
| @defun address_operand |
| This predicate is a little unusual; it allows any operand that is a |
| valid expression for the @emph{address} of a quantity of mode |
| @var{mode}, again determined by the weak form of |
| @code{GO_IF_LEGITIMATE_ADDRESS}. To first order, if |
| @samp{@w{(mem:@var{mode} (@var{exp}))}} is acceptable to |
| @code{memory_operand}, then @var{exp} is acceptable to |
| @code{address_operand}. Note that @var{exp} does not necessarily have |
| the mode @var{mode}. |
| @end defun |
| |
| @defun indirect_operand |
| This is a stricter form of @code{memory_operand} which allows only |
| memory references with a @code{general_operand} as the address |
| expression. New uses of this predicate are discouraged, because |
| @code{general_operand} is very permissive, so it's hard to tell what |
| an @code{indirect_operand} does or does not allow. If a target has |
| different requirements for memory operands for different instructions, |
| it is better to define target-specific predicates which enforce the |
| hardware's requirements explicitly. |
| @end defun |
| |
| @defun push_operand |
| This predicate allows a memory reference suitable for pushing a value |
| onto the stack. This will be a @code{MEM} which refers to |
| @code{stack_pointer_rtx}, with a side-effect in its address expression |
| (@pxref{Incdec}); which one is determined by the |
| @code{STACK_PUSH_CODE} macro (@pxref{Frame Layout}). |
| @end defun |
| |
| @defun pop_operand |
| This predicate allows a memory reference suitable for popping a value |
| off the stack. Again, this will be a @code{MEM} referring to |
| @code{stack_pointer_rtx}, with a side-effect in its address |
| expression. However, this time @code{STACK_POP_CODE} is expected. |
| @end defun |
| |
| @noindent |
| The fourth category of predicates allow some combination of the above |
| operands. |
| |
| @defun nonmemory_operand |
| This predicate allows any immediate or register operand valid for @var{mode}. |
| @end defun |
| |
| @defun nonimmediate_operand |
| This predicate allows any register or memory operand valid for @var{mode}. |
| @end defun |
| |
| @defun general_operand |
| This predicate allows any immediate, register, or memory operand |
| valid for @var{mode}. |
| @end defun |
| |
| @noindent |
| Finally, there is one generic operator predicate. |
| |
| @defun comparison_operator |
| This predicate matches any expression which performs an arithmetic |
| comparison in @var{mode}; that is, @code{COMPARISON_P} is true for the |
| expression code. |
| @end defun |
| |
| @node Defining Predicates |
| @subsection Defining Machine-Specific Predicates |
| @cindex defining predicates |
| @findex define_predicate |
| @findex define_special_predicate |
| |
| Many machines have requirements for their operands that cannot be |
| expressed precisely using the generic predicates. You can define |
| additional predicates using @code{define_predicate} and |
| @code{define_special_predicate} expressions. These expressions have |
| three operands: |
| |
| @itemize @bullet |
| @item |
| The name of the predicate, as it will be referred to in |
| @code{match_operand} or @code{match_operator} expressions. |
| |
| @item |
| An RTL expression which evaluates to true if the predicate allows the |
| operand @var{op}, false if it does not. This expression can only use |
| the following RTL codes: |
| |
| @table @code |
| @item MATCH_OPERAND |
| When written inside a predicate expression, a @code{MATCH_OPERAND} |
| expression evaluates to true if the predicate it names would allow |
| @var{op}. The operand number and constraint are ignored. Due to |
| limitations in @command{genrecog}, you can only refer to generic |
| predicates and predicates that have already been defined. |
| |
| @item MATCH_CODE |
| This expression evaluates to true if @var{op} or a specified |
| subexpression of @var{op} has one of a given list of RTX codes. |
| |
| The first operand of this expression is a string constant containing a |
| comma-separated list of RTX code names (in lower case). These are the |
| codes for which the @code{MATCH_CODE} will be true. |
| |
| The second operand is a string constant which indicates what |
| subexpression of @var{op} to examine. If it is absent or the empty |
| string, @var{op} itself is examined. Otherwise, the string constant |
| must be a sequence of digits and/or lowercase letters. Each character |
| indicates a subexpression to extract from the current expression; for |
| the first character this is @var{op}, for the second and subsequent |
| characters it is the result of the previous character. A digit |
| @var{n} extracts @samp{@w{XEXP (@var{e}, @var{n})}}; a letter @var{l} |
| extracts @samp{@w{XVECEXP (@var{e}, 0, @var{n})}} where @var{n} is the |
| alphabetic ordinal of @var{l} (0 for `a', 1 for 'b', and so on). The |
| @code{MATCH_CODE} then examines the RTX code of the subexpression |
| extracted by the complete string. It is not possible to extract |
| components of an @code{rtvec} that is not at position 0 within its RTX |
| object. |
| |
| @item MATCH_TEST |
| This expression has one operand, a string constant containing a C |
| expression. The predicate's arguments, @var{op} and @var{mode}, are |
| available with those names in the C expression. The @code{MATCH_TEST} |
| evaluates to true if the C expression evaluates to a nonzero value. |
| @code{MATCH_TEST} expressions must not have side effects. |
| |
| @item AND |
| @itemx IOR |
| @itemx NOT |
| @itemx IF_THEN_ELSE |
| The basic @samp{MATCH_} expressions can be combined using these |
| logical operators, which have the semantics of the C operators |
| @samp{&&}, @samp{||}, @samp{!}, and @samp{@w{? :}} respectively. As |
| in Common Lisp, you may give an @code{AND} or @code{IOR} expression an |
| arbitrary number of arguments; this has exactly the same effect as |
| writing a chain of two-argument @code{AND} or @code{IOR} expressions. |
| @end table |
| |
| @item |
| An optional block of C code, which should execute |
| @samp{@w{return true}} if the predicate is found to match and |
| @samp{@w{return false}} if it does not. It must not have any side |
| effects. The predicate arguments, @var{op} and @var{mode}, are |
| available with those names. |
| |
| If a code block is present in a predicate definition, then the RTL |
| expression must evaluate to true @emph{and} the code block must |
| execute @samp{@w{return true}} for the predicate to allow the operand. |
| The RTL expression is evaluated first; do not re-check anything in the |
| code block that was checked in the RTL expression. |
| @end itemize |
| |
| The program @command{genrecog} scans @code{define_predicate} and |
| @code{define_special_predicate} expressions to determine which RTX |
| codes are possibly allowed. You should always make this explicit in |
| the RTL predicate expression, using @code{MATCH_OPERAND} and |
| @code{MATCH_CODE}. |
| |
| Here is an example of a simple predicate definition, from the IA64 |
| machine description: |
| |
| @smallexample |
| @group |
| ;; @r{True if @var{op} is a @code{SYMBOL_REF} which refers to the sdata section.} |
| (define_predicate "small_addr_symbolic_operand" |
| (and (match_code "symbol_ref") |
| (match_test "SYMBOL_REF_SMALL_ADDR_P (op)"))) |
| @end group |
| @end smallexample |
| |
| @noindent |
| And here is another, showing the use of the C block. |
| |
| @smallexample |
| @group |
| ;; @r{True if @var{op} is a register operand that is (or could be) a GR reg.} |
| (define_predicate "gr_register_operand" |
| (match_operand 0 "register_operand") |
| @{ |
| unsigned int regno; |
| if (GET_CODE (op) == SUBREG) |
| op = SUBREG_REG (op); |
| |
| regno = REGNO (op); |
| return (regno >= FIRST_PSEUDO_REGISTER || GENERAL_REGNO_P (regno)); |
| @}) |
| @end group |
| @end smallexample |
| |
| Predicates written with @code{define_predicate} automatically include |
| a test that @var{mode} is @code{VOIDmode}, or @var{op} has the same |
| mode as @var{mode}, or @var{op} is a @code{CONST_INT} or |
| @code{CONST_DOUBLE}. They do @emph{not} check specifically for |
| integer @code{CONST_DOUBLE}, nor do they test that the value of either |
| kind of constant fits in the requested mode. This is because |
| target-specific predicates that take constants usually have to do more |
| stringent value checks anyway. If you need the exact same treatment |
| of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic predicates |
| provide, use a @code{MATCH_OPERAND} subexpression to call |
| @code{const_int_operand}, @code{const_double_operand}, or |
| @code{immediate_operand}. |
| |
| Predicates written with @code{define_special_predicate} do not get any |
| automatic mode checks, and are treated as having special mode handling |
| by @command{genrecog}. |
| |
| The program @command{genpreds} is responsible for generating code to |
| test predicates. It also writes a header file containing function |
| declarations for all machine-specific predicates. It is not necessary |
| to declare these predicates in @file{@var{cpu}-protos.h}. |
| @end ifset |
| |
| @c Most of this node appears by itself (in a different place) even |
| @c when the INTERNALS flag is clear. Passages that require the internals |
| @c manual's context are conditionalized to appear only in the internals manual. |
| @ifset INTERNALS |
| @node Constraints |
| @section Operand Constraints |
| @cindex operand constraints |
| @cindex constraints |
| |
| Each @code{match_operand} in an instruction pattern can specify |
| constraints for the operands allowed. The constraints allow you to |
| fine-tune matching within the set of operands allowed by the |
| predicate. |
| |
| @end ifset |
| @ifclear INTERNALS |
| @node Constraints |
| @section Constraints for @code{asm} Operands |
| @cindex operand constraints, @code{asm} |
| @cindex constraints, @code{asm} |
| @cindex @code{asm} constraints |
| |
| Here are specific details on what constraint letters you can use with |
| @code{asm} operands. |
| @end ifclear |
| 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. |
| |
| @ifset INTERNALS |
| @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. |
| * Define Constraints:: How to define machine-specific constraints. |
| * C Constraint Interface:: How to test constraints from C code. |
| @end menu |
| @end ifset |
| |
| @ifclear INTERNALS |
| @menu |
| * Simple Constraints:: Basic use of constraints. |
| * Multi-Alternative:: When an insn has two alternative constraint-patterns. |
| * Modifiers:: More precise control over effects of constraints. |
| * Machine Constraints:: Special constraints for some particular machines. |
| @end menu |
| @end ifclear |
| |
| @node Simple Constraints |
| @subsection Simple Constraints |
| @cindex 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: |
| |
| @table @asis |
| @item 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. |
| |
| @cindex @samp{m} in constraint |
| @cindex memory references in constraints |
| @item @samp{m} |
| A memory operand is allowed, with any kind of address that the machine |
| supports in general. |
| |
| @cindex offsettable address |
| @cindex @samp{o} in constraint |
| @item @samp{o} |
| A memory operand is allowed, but only if the address is |
| @dfn{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. |
| |
| @cindex autoincrement/decrement addressing |
| 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 @samp{o} is valid only when accompanied |
| by both @samp{<} (if the target machine has predecrement addressing) |
| and @samp{>} (if the target machine has preincrement addressing). |
| |
| @cindex @samp{V} in constraint |
| @item @samp{V} |
| A memory operand that is not offsettable. In other words, anything that |
| would fit the @samp{m} constraint but not the @samp{o} constraint. |
| |
| @cindex @samp{<} in constraint |
| @item @samp{<} |
| A memory operand with autodecrement addressing (either predecrement or |
| postdecrement) is allowed. |
| |
| @cindex @samp{>} in constraint |
| @item @samp{>} |
| A memory operand with autoincrement addressing (either preincrement or |
| postincrement) is allowed. |
| |
| @cindex @samp{r} in constraint |
| @cindex registers in constraints |
| @item @samp{r} |
| A register operand is allowed provided that it is in a general |
| register. |
| |
| @cindex constants in constraints |
| @cindex @samp{i} in constraint |
| @item @samp{i} |
| An immediate integer operand (one with constant value) is allowed. |
| This includes symbolic constants whose values will be known only at |
| assembly time or later. |
| |
| @cindex @samp{n} in constraint |
| @item @samp{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 @samp{n} |
| rather than @samp{i}. |
| |
| @cindex @samp{I} in constraint |
| @item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P} |
| Other letters in the range @samp{I} through @samp{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, @samp{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. |
| |
| @cindex @samp{E} in constraint |
| @item @samp{E} |
| An immediate floating operand (expression code @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). |
| |
| @cindex @samp{F} in constraint |
| @item @samp{F} |
| An immediate floating operand (expression code @code{const_double} or |
| @code{const_vector}) is allowed. |
| |
| @cindex @samp{G} in constraint |
| @cindex @samp{H} in constraint |
| @item @samp{G}, @samp{H} |
| @samp{G} and @samp{H} may be defined in a machine-dependent fashion to |
| permit immediate floating operands in particular ranges of values. |
| |
| @cindex @samp{s} in constraint |
| @item @samp{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 @samp{s} instead of @samp{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 @minus{}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 @samp{moveq} instruction. We arrange for this to happen |
| by defining the letter @samp{K} to mean ``any integer outside the |
| range @minus{}128 to 127'', and then specifying @samp{Ks} in the operand |
| constraints. |
| |
| @cindex @samp{g} in constraint |
| @item @samp{g} |
| Any register, memory or immediate integer operand is allowed, except for |
| registers that are not general registers. |
| |
| @cindex @samp{X} in constraint |
| @item @samp{X} |
| @ifset INTERNALS |
| Any operand whatsoever is allowed, even if it does not satisfy |
| @code{general_operand}. This is normally used in the constraint of |
| a @code{match_scratch} when certain alternatives will not actually |
| require a scratch register. |
| @end ifset |
| @ifclear INTERNALS |
| Any operand whatsoever is allowed. |
| @end ifclear |
| |
| @cindex @samp{0} in constraint |
| @cindex digits in constraint |
| @item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{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 consecutively, they are interpreted as a single |
| decimal integer. There is scant chance for ambiguity, since to-date |
| it has never been desirable that @samp{10} be interpreted as matching |
| either operand 1 @emph{or} operand 0. Should this be desired, one |
| can use multiple alternatives instead. |
| |
| @cindex matching constraint |
| @cindex constraint, matching |
| This is called a @dfn{matching constraint} and what it really means is |
| that the assembler has only a single operand that fills two roles |
| @ifset INTERNALS |
| 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 |
| @end ifset |
| @ifclear INTERNALS |
| which @code{asm} distinguishes. For example, an add instruction uses |
| two input operands and an output operand, but on most CISC |
| @end ifclear |
| machines an add instruction really has only two operands, one of them an |
| input-output operand: |
| |
| @smallexample |
| addl #35,r12 |
| @end smallexample |
| |
| 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. |
| |
| @ifset INTERNALS |
| 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, @code{*x} |
| as an input operand will match @code{*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. |
| @end ifset |
| |
| @cindex load address instruction |
| @cindex push address instruction |
| @cindex address constraints |
| @cindex @samp{p} in constraint |
| @item @samp{p} |
| An operand that is a valid memory address is allowed. This is |
| for ``load address'' and ``push address'' instructions. |
| |
| @findex address_operand |
| @samp{p} in the constraint must be accompanied by @code{address_operand} |
| as the predicate in the @code{match_operand}. This predicate interprets |
| the mode specified in the @code{match_operand} as the mode of the memory |
| reference for which the address would be valid. |
| |
| @cindex other register constraints |
| @cindex extensible constraints |
| @item @var{other-letters} |
| Other letters can be defined in machine-dependent fashion to stand for |
| particular classes of registers or other arbitrary operand types. |
| @samp{d}, @samp{a} and @samp{f} are defined on the 68000/68020 to stand |
| for data, address and floating point registers. |
| @end table |
| |
| @ifset INTERNALS |
| 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: |
| |
| @smallexample |
| (define_insn "" |
| [(set (match_operand:SI 0 "general_operand" "=r") |
| (plus:SI (match_dup 0) |
| (match_operand:SI 1 "general_operand" "r")))] |
| "" |
| "@dots{}") |
| @end smallexample |
| |
| @noindent |
| which has two operands, one of which must appear in two places, and |
| |
| @smallexample |
| (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")))] |
| "" |
| "@dots{}") |
| @end smallexample |
| |
| @noindent |
| which has three operands, two of which are required by a constraint to be |
| identical. If we are considering an insn of the form |
| |
| @smallexample |
| (insn @var{n} @var{prev} @var{next} |
| (set (reg:SI 3) |
| (plus:SI (reg:SI 6) (reg:SI 109))) |
| @dots{}) |
| @end smallexample |
| |
| @noindent |
| 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: |
| |
| @smallexample |
| (insn @var{n2} @var{prev} @var{n} |
| (set (reg:SI 3) (reg:SI 6)) |
| @dots{}) |
| |
| (insn @var{n} @var{n2} @var{next} |
| (set (reg:SI 3) |
| (plus:SI (reg:SI 3) (reg:SI 109))) |
| @dots{}) |
| @end smallexample |
| |
| 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 @emph{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. |
| |
| @itemize @bullet |
| @item |
| 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 @samp{i}. If any possible |
| constant value is accepted, then nothing less than @samp{i} will do; |
| if the predicate is more selective, then the constraints may also be |
| more selective. |
| |
| @item |
| 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. |
| |
| @cindex nonoffsettable memory reference |
| @cindex memory reference, nonoffsettable |
| @item |
| A nonoffsettable memory reference can be reloaded by copying the |
| address into a register. So if the constraint uses the letter |
| @samp{o}, all memory references are taken care of. |
| |
| @item |
| 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 |
| @samp{o} or @samp{m}, constant operands are not a problem. |
| |
| @item |
| 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. |
| @end itemize |
| |
| 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 @code{SImode} to produce a |
| @code{DImode} result, but only if the registers are correctly sign |
| extended. This predicate for the input operands accepts a |
| @code{sign_extend} of an @code{SImode} register. Write the constraint |
| to indicate the type of register that is required for the operand of the |
| @code{sign_extend}. |
| @end ifset |
| |
| @node Multi-Alternative |
| @subsection Multiple Alternative Constraints |
| @cindex 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. |
| @ifset INTERNALS |
| Here is how it is done for fullword logical-or on the 68000: |
| |
| @smallexample |
| (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")))] |
| @dots{}) |
| @end smallexample |
| |
| The first alternative has @samp{m} (memory) for operand 0, @samp{0} for |
| operand 1 (meaning it must match operand 0), and @samp{dKs} for operand |
| 2. The second alternative has @samp{d} (data register) for operand 0, |
| @samp{0} for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and |
| @samp{%} in the constraints apply to all the alternatives; their |
| meaning is explained in the next section (@pxref{Class Preferences}). |
| @end ifset |
| |
| @c FIXME Is this ? and ! stuff of use in asm()? If not, hide unless INTERNAL |
| 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 @samp{?} and @samp{!} characters: |
| |
| @table @code |
| @cindex @samp{?} in constraint |
| @cindex question mark |
| @item ? |
| Disparage slightly the alternative that the @samp{?} appears in, |
| as a choice when no alternative applies exactly. The compiler regards |
| this alternative as one unit more costly for each @samp{?} that appears |
| in it. |
| |
| @cindex @samp{!} in constraint |
| @cindex exclamation point |
| @item ! |
| Disparage severely the alternative that the @samp{!} appears in. |
| This alternative can still be used if it fits without reloading, |
| but if reloading is needed, some other alternative will be used. |
| @end table |
| |
| @ifset INTERNALS |
| 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 @code{which_alternative}, which is |
| the ordinal number of the alternative that was actually satisfied (0 for |
| the first, 1 for the second alternative, etc.). @xref{Output Statement}. |
| @end ifset |
| |
| @ifset INTERNALS |
| @node Class Preferences |
| @subsection Register Class Preferences |
| @cindex class preference constraints |
| @cindex register class preference constraints |
| |
| @cindex voting between constraint alternatives |
| 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 @samp{d} and @samp{a} that specify classes of registers. |
| The pseudo register is put in whichever class gets the most ``votes''. |
| The constraint letters @samp{g} and @samp{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. |
| @end ifset |
| |
| @node Modifiers |
| @subsection Constraint Modifier Characters |
| @cindex modifiers in constraints |
| @cindex constraint modifier characters |
| |
| @c prevent bad page break with this line |
| Here are constraint modifier characters. |
| |
| @table @samp |
| @cindex @samp{=} in constraint |
| @item = |
| Means that this operand is write-only for this instruction: the previous |
| value is discarded and replaced by output data. |
| |
| @cindex @samp{+} in constraint |
| @item + |
| 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. @samp{=} identifies an output; @samp{+} |
| identifies an operand that is both input and output; all other operands |
| are assumed to be input only. |
| |
| If you specify @samp{=} or @samp{+} in a constraint, you put it in the |
| first character of the constraint string. |
| |
| @cindex @samp{&} in constraint |
| @cindex earlyclobber operand |
| @item & |
| Means (in a particular alternative) that this operand is an |
| @dfn{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. |
| |
| @samp{&} applies only to the alternative in which it is written. In |
| constraints with multiple alternatives, sometimes one alternative |
| requires @samp{&} while others do not. See, for example, the |
| @samp{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 @samp{mulsi3} insn of the ARM@. |
| |
| @samp{&} does not obviate the need to write @samp{=}. |
| |
| @cindex @samp{%} in constraint |
| @item % |
| 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. |
| @ifset INTERNALS |
| 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: |
| |
| @smallexample |
| (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")))] |
| @dots{}) |
| @end smallexample |
| @end ifset |
| GCC can only handle one commutative pair in an asm; if you use more, |
| the compiler may fail. Note that you need not use the modifier if |
| the two alternatives are strictly identical; this would only waste |
| time in the reload pass. The modifier is not operational after |
| register allocation, so the result of @code{define_peephole2} |
| and @code{define_split}s performed after reload cannot rely on |
| @samp{%} to make the intended insn match. |
| |
| @cindex @samp{#} in constraint |
| @item # |
| 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. |
| |
| @cindex @samp{*} in constraint |
| @item * |
| Says that the following character should be ignored when choosing |
| register preferences. @samp{*} has no effect on the meaning of the |
| constraint as a constraint, and no effect on reloading. |
| |
| @ifset INTERNALS |
| 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, @samp{*} is used so that the @samp{d} |
| constraint letter (for data register) is ignored when computing |
| register preferences. |
| |
| @smallexample |
| (define_insn "extendhisi2" |
| [(set (match_operand:SI 0 "general_operand" "=*d,a") |
| (sign_extend:SI |
| (match_operand:HI 1 "general_operand" "0,g")))] |
| @dots{}) |
| @end smallexample |
| @end ifset |
| @end table |
| |
| @node Machine Constraints |
| @subsection Constraints for Particular Machines |
| @cindex machine specific constraints |
| @cindex constraints, machine specific |
| |
| Whenever possible, you should use the general-purpose constraint letters |
| in @code{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 @samp{m} and @samp{r} (for memory and |
| general-purpose registers respectively; @pxref{Simple Constraints}), and |
| @samp{I}, usually the letter indicating the most common |
| immediate-constant format. |
| |
| Each architecture defines additional constraints. These constraints |
| are used by the compiler itself for instruction generation, as well as |
| for @code{asm} statements; therefore, some of the constraints are not |
| particularly useful for @code{asm}. Here is a summary of some of the |
| machine-dependent constraints available on some particular machines; |
| it includes both constraints that are useful for @code{asm} and |
| constraints that aren't. The compiler source file mentioned in the |
| table heading for each architecture is the definitive reference for |
| the meanings of that architecture's constraints. |
| |
| @table @emph |
| @item ARM family---@file{config/arm/arm.h} |
| @table @code |
| @item f |
| Floating-point register |
| |
| @item w |
| VFP floating-point register |
| |
| @item F |
| One of the floating-point constants 0.0, 0.5, 1.0, 2.0, 3.0, 4.0, 5.0 |
| or 10.0 |
| |
| @item G |
| Floating-point constant that would satisfy the constraint @samp{F} if it |
| were negated |
| |
| @item 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 |
| |
| @item J |
| Integer in the range @minus{}4095 to 4095 |
| |
| @item K |
| Integer that satisfies constraint @samp{I} when inverted (ones complement) |
| |
| @item L |
| Integer that satisfies constraint @samp{I} when negated (twos complement) |
| |
| @item M |
| Integer in the range 0 to 32 |
| |
| @item Q |
| A memory reference where the exact address is in a single register |
| (`@samp{m}' is preferable for @code{asm} statements) |
| |
| @item R |
| An item in the constant pool |
| |
| @item S |
| A symbol in the text segment of the current file |
| |
| @item Uv |
| A memory reference suitable for VFP load/store insns (reg+constant offset) |
| |
| @item Uy |
| A memory reference suitable for iWMMXt load/store instructions. |
| |
| @item Uq |
| A memory reference suitable for the ARMv4 ldrsb instruction. |
| @end table |
| |
| @item AVR family---@file{config/avr/constraints.md} |
| @table @code |
| @item l |
| Registers from r0 to r15 |
| |
| @item a |
| Registers from r16 to r23 |
| |
| @item d |
| Registers from r16 to r31 |
| |
| @item w |
| Registers from r24 to r31. These registers can be used in @samp{adiw} command |
| |
| @item e |
| Pointer register (r26--r31) |
| |
| @item b |
| Base pointer register (r28--r31) |
| |
| @item q |
| Stack pointer register (SPH:SPL) |
| |
| @item t |
| Temporary register r0 |
| |
| @item x |
| Register pair X (r27:r26) |
| |
| @item y |
| Register pair Y (r29:r28) |
| |
| @item z |
| Register pair Z (r31:r30) |
| |
| @item I |
| Constant greater than @minus{}1, less than 64 |
| |
| @item J |
| Constant greater than @minus{}64, less than 1 |
| |
| @item K |
| Constant integer 2 |
| |
| @item L |
| Constant integer 0 |
| |
| @item M |
| Constant that fits in 8 bits |
| |
| @item N |
| Constant integer @minus{}1 |
| |
| @item O |
| Constant integer 8, 16, or 24 |
| |
| @item P |
| Constant integer 1 |
| |
| @item G |
| A floating point constant 0.0 |
| |
| @item R |
| Integer constant in the range -6 @dots{} 5. |
| |
| @item Q |
| A memory address based on Y or Z pointer with displacement. |
| @end table |
| |
| @item CRX Architecture---@file{config/crx/crx.h} |
| @table @code |
| |
| @item b |
| Registers from r0 to r14 (registers without stack pointer) |
| |
| @item l |
| Register r16 (64-bit accumulator lo register) |
| |
| @item h |
| Register r17 (64-bit accumulator hi register) |
| |
| @item k |
| Register pair r16-r17. (64-bit accumulator lo-hi pair) |
| |
| @item I |
| Constant that fits in 3 bits |
| |
| @item J |
| Constant that fits in 4 bits |
| |
| @item K |
| Constant that fits in 5 bits |
| |
| @item L |
| Constant that is one of -1, 4, -4, 7, 8, 12, 16, 20, 32, 48 |
| |
| @item G |
| Floating point constant that is legal for store immediate |
| @end table |
| |
| @item Hewlett-Packard PA-RISC---@file{config/pa/pa.h} |
| @table @code |
| @item a |
| General register 1 |
| |
| @item f |
| Floating point register |
| |
| @item q |
| Shift amount register |
| |
| @item x |
| Floating point register (deprecated) |
| |
| @item y |
| Upper floating point register (32-bit), floating point register (64-bit) |
| |
| @item Z |
| Any register |
| |
| @item I |
| Signed 11-bit integer constant |
| |
| @item J |
| Signed 14-bit integer constant |
| |
| @item K |
| Integer constant that can be deposited with a @code{zdepi} instruction |
| |
| @item L |
| Signed 5-bit integer constant |
| |
| @item M |
| Integer constant 0 |
| |
| @item N |
| Integer constant that can be loaded with a @code{ldil} instruction |
| |
| @item O |
| Integer constant whose value plus one is a power of 2 |
| |
| @item P |
| Integer constant that can be used for @code{and} operations in @code{depi} |
| and @code{extru} instructions |
| |
| @item S |
| Integer constant 31 |
| |
| @item U |
| Integer constant 63 |
| |
| @item G |
| Floating-point constant 0.0 |
| |
| @item A |
| A @code{lo_sum} data-linkage-table memory operand |
| |
| @item Q |
| A memory operand that can be used as the destination operand of an |
| integer store instruction |
| |
| @item R |
| A scaled or unscaled indexed memory operand |
| |
| @item T |
| A memory operand for floating-point loads and stores |
| |
| @item W |
| A register indirect memory operand |
| @end table |
| |
| @item PowerPC and IBM RS6000---@file{config/rs6000/rs6000.h} |
| @table @code |
| @item b |
| Address base register |
| |
| @item f |
| Floating point register |
| |
| @item v |
| Vector register |
| |
| @item h |
| @samp{MQ}, @samp{CTR}, or @samp{LINK} register |
| |
| @item q |
| @samp{MQ} register |
| |
| @item c |
| @samp{CTR} register |
| |
| @item l |
| @samp{LINK} register |
| |
| @item x |
| @samp{CR} register (condition register) number 0 |
| |
| @item y |
| @samp{CR} register (condition register) |
| |
| @item z |
| @samp{FPMEM} stack memory for FPR-GPR transfers |
| |
| @item I |
| Signed 16-bit constant |
| |
| @item J |
| Unsigned 16-bit constant shifted left 16 bits (use @samp{L} instead for |
| @code{SImode} constants) |
| |
| @item K |
| Unsigned 16-bit constant |
| |
| @item L |
| Signed 16-bit constant shifted left 16 bits |
| |
| @item M |
| Constant larger than 31 |
| |
| @item N |
| Exact power of 2 |
| |
| @item O |
| Zero |
| |
| @item P |
| Constant whose negation is a signed 16-bit constant |
| |
| @item G |
| Floating point constant that can be loaded into a register with one |
| instruction per word |
| |
| @item H |
| Integer/Floating point constant that can be loaded into a register using |
| three instructions |
| |
| @item Q |
| Memory operand that is an offset from a register (@samp{m} is preferable |
| for @code{asm} statements) |
| |
| @item Z |
| Memory operand that is an indexed or indirect from a register (@samp{m} is |
| preferable for @code{asm} statements) |
| |
| @item R |
| AIX TOC entry |
| |
| @item a |
| Address operand that is an indexed or indirect from a register (@samp{p} is |
| preferable for @code{asm} statements) |
| |
| @item S |
| Constant suitable as a 64-bit mask operand |
| |
| @item T |
| Constant suitable as a 32-bit mask operand |
| |
| @item U |
| System V Release 4 small data area reference |
| |
| @item t |
| AND masks that can be performed by two rldic@{l, r@} instructions |
| |
| @item W |
| Vector constant that does not require memory |
| |
| @end table |
| |
| @item MorphoTech family---@file{config/mt/mt.h} |
| @table @code |
| @item I |
| Constant for an arithmetic insn (16-bit signed integer). |
| |
| @item J |
| The constant 0. |
| |
| @item K |
| Constant for a logical insn (16-bit zero-extended integer). |
| |
| @item L |
| A constant that can be loaded with @code{lui} (i.e.@: the bottom 16 |
| bits are zero). |
| |
| @item M |
| A constant that takes two words to load (i.e.@: not matched by |
| @code{I}, @code{K}, or @code{L}). |
| |
| @item N |
| Negative 16-bit constants other than -65536. |
| |
| @item O |
| A 15-bit signed integer constant. |
| |
| @item P |
| A positive 16-bit constant. |
| @end table |
| |
| @item Intel 386---@file{config/i386/constraints.md} |
| @table @code |
| @item R |
| Legacy register---the eight integer registers available on all |
| i386 processors (@code{a}, @code{b}, @code{c}, @code{d}, |
| @code{si}, @code{di}, @code{bp}, @code{sp}). |
| |
| @item q |
| Any register accessible as @code{@var{r}l}. In 32-bit mode, @code{a}, |
| @code{b}, @code{c}, and @code{d}; in 64-bit mode, any integer register. |
| |
| @item Q |
| Any register accessible as @code{@var{r}h}: @code{a}, @code{b}, |
| @code{c}, and @code{d}. |
| |
| @ifset INTERNALS |
| @item l |
| Any register that can be used as the index in a base+index memory |
| access: that is, any general register except the stack pointer. |
| @end ifset |
| |
| @item a |
| The @code{a} register. |
| |
| @item b |
| The @code{b} register. |
| |
| @item c |
| The @code{c} register. |
| |
| @item d |
| The @code{d} register. |
| |
| @item S |
| The @code{si} register. |
| |
| @item D |
| The @code{di} register. |
| |
| @item A |
| The @code{a} and @code{d} registers, as a pair (for instructions that |
| return half the result in one and half in the other). |
| |
| @item f |
| Any 80387 floating-point (stack) register. |
| |
| @item t |
| Top of 80387 floating-point stack (@code{%st(0)}). |
| |
| @item u |
| Second from top of 80387 floating-point stack (@code{%st(1)}). |
| |
| @item y |
| Any MMX register. |
| |
| @item x |
| Any SSE register. |
| |
| @ifset INTERNALS |
| @item Y |
| Any SSE2 register. |
| @end ifset |
| |
| @item I |
| Integer constant in the range 0 @dots{} 31, for 32-bit shifts. |
| |
| @item J |
| Integer constant in the range 0 @dots{} 63, for 64-bit shifts. |
| |
| @item K |
| Signed 8-bit integer constant. |
| |
| @item L |
| @code{0xFF} or @code{0xFFFF}, for andsi as a zero-extending move. |
| |
| @item M |
| 0, 1, 2, or 3 (shifts for the @code{lea} instruction). |
| |
| @item N |
| Unsigned 8-bit integer constant (for @code{in} and @code{out} |
| instructions). |
| |
| @ifset INTERNALS |
| @item O |
| Integer constant in the range 0 @dots{} 127, for 128-bit shifts. |
| @end ifset |
| |
| @item G |
| Standard 80387 floating point constant. |
| |
| @item C |
| Standard SSE floating point constant. |
| |
| @item e |
| 32-bit signed integer constant, or a symbolic reference known |
| to fit that range (for immediate operands in sign-extending x86-64 |
| instructions). |
| |
| @item Z |
| 32-bit unsigned integer constant, or a symbolic reference known |
| to fit that range (for immediate operands in zero-extending x86-64 |
| instructions). |
| |
| @end table |
| |
| @item Intel IA-64---@file{config/ia64/ia64.h} |
| @table @code |
| @item a |
| General register @code{r0} to @code{r3} for @code{addl} instruction |
| |
| @item b |
| Branch register |
| |
| @item c |
| Predicate register (@samp{c} as in ``conditional'') |
| |
| @item d |
| Application register residing in M-unit |
| |
| @item e |
| Application register residing in I-unit |
| |
| @item f |
| Floating-point register |
| |
| @item m |
| Memory operand. |
| Remember that @samp{m} allows postincrement and postdecrement which |
| require printing with @samp{%Pn} on IA-64. |
| Use @samp{S} to disallow postincrement and postdecrement. |
| |
| @item G |
| Floating-point constant 0.0 or 1.0 |
| |
| @item I |
| 14-bit signed integer constant |
| |
| @item J |
| 22-bit signed integer constant |
| |
| @item K |
| 8-bit signed integer constant for logical instructions |
| |
| @item L |
| 8-bit adjusted signed integer constant for compare pseudo-ops |
| |
| @item M |
| 6-bit unsigned integer constant for shift counts |
| |
| @item N |
| 9-bit signed integer constant for load and store postincrements |
| |
| @item O |
| The constant zero |
| |
| @item P |
| 0 or @minus{}1 for @code{dep} instruction |
| |
| @item Q |
| Non-volatile memory for floating-point loads and stores |
| |
| @item R |
| Integer constant in the range 1 to 4 for @code{shladd} instruction |
| |
| @item S |
| Memory operand except postincrement and postdecrement |
| @end table |
| |
| @item FRV---@file{config/frv/frv.h} |
| @table @code |
| @item a |
| Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}). |
| |
| @item b |
| Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}). |
| |
| @item c |
| Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and |
| @code{icc0} to @code{icc3}). |
| |
| @item d |
| Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}). |
| |
| @item e |
| Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}). |
| Odd registers are excluded not in the class but through the use of a machine |
| mode larger than 4 bytes. |
| |
| @item f |
| Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}). |
| |
| @item h |
| Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}). |
| Odd registers are excluded not in the class but through the use of a machine |
| mode larger than 4 bytes. |
| |
| @item l |
| Register in the class @code{LR_REG} (the @code{lr} register). |
| |
| @item q |
| Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}). |
| Register numbers not divisible by 4 are excluded not in the class but through |
| the use of a machine mode larger than 8 bytes. |
| |
| @item t |
| Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}). |
| |
| @item u |
| Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}). |
| |
| @item v |
| Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}). |
| |
| @item w |
| Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}). |
| |
| @item x |
| Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}). |
| Register numbers not divisible by 4 are excluded not in the class but through |
| the use of a machine mode larger than 8 bytes. |
| |
| @item z |
| Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}). |
| |
| @item A |
| Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}). |
| |
| @item B |
| Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}). |
| |
| @item C |
| Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}). |
| |
| @item G |
| Floating point constant zero |
| |
| @item I |
| 6-bit signed integer constant |
| |
| @item J |
| 10-bit signed integer constant |
| |
| @item L |
| 16-bit signed integer constant |
| |
| @item M |
| 16-bit unsigned integer constant |
| |
| @item N |
| 12-bit signed integer constant that is negative---i.e.@: in the |
| range of @minus{}2048 to @minus{}1 |
| |
| @item O |
| Constant zero |
| |
| @item P |
| 12-bit signed integer constant that is greater than zero---i.e.@: in the |
| range of 1 to 2047. |
| |
| @end table |
| |
| @item Blackfin family---@file{config/bfin/bfin.h} |
| @table @code |
| @item a |
| P register |
| |
| @item d |
| D register |
| |
| @item z |
| A call clobbered P register. |
| |
| @item q@var{n} |
| A single register. If @var{n} is in the range 0 to 7, the corresponding D |
| register. If it is @code{A}, then the register P0. |
| |
| @item D |
| Even-numbered D register |
| |
| @item W |
| Odd-numbered D register |
| |
| @item e |
| Accumulator register. |
| |
| @item A |
| Even-numbered accumulator register. |
| |
| @item B |
| Odd-numbered accumulator register. |
| |
| @item b |
| I register |
| |
| @item v |
| B register |
| |
| @item f |
| M register |
| |
| @item c |
| Registers used for circular buffering, i.e. I, B, or L registers. |
| |
| @item C |
| The CC register. |
| |
| @item t |
| LT0 or LT1. |
| |
| @item k |
| LC0 or LC1. |
| |
| @item u |
| LB0 or LB1. |
| |
| @item x |
| Any D, P, B, M, I or L register. |
| |
| @item y |
| Additional registers typically used only in prologues and epilogues: RETS, |
| RETN, RETI, RETX, RETE, ASTAT, SEQSTAT and USP. |
| |
| @item w |
| Any register except accumulators or CC. |
| |
| @item Ksh |
| Signed 16 bit integer (in the range -32768 to 32767) |
| |
| @item Kuh |
| Unsigned 16 bit integer (in the range 0 to 65535) |
| |
| @item Ks7 |
| Signed 7 bit integer (in the range -64 to 63) |
| |
| @item Ku7 |
| Unsigned 7 bit integer (in the range 0 to 127) |
| |
| @item Ku5 |
| Unsigned 5 bit integer (in the range 0 to 31) |
| |
| @item Ks4 |
| Signed 4 bit integer (in the range -8 to 7) |
| |
| @item Ks3 |
| Signed 3 bit integer (in the range -3 to 4) |
| |
| @item Ku3 |
| Unsigned 3 bit integer (in the range 0 to 7) |
| |
| @item P@var{n} |
| Constant @var{n}, where @var{n} is a single-digit constant in the range 0 to 4. |
| |
| @item PA |
| An integer equal to one of the MACFLAG_XXX constants that is suitable for |
| use with either accumulator. |
| |
| @item PB |
| An integer equal to one of the MACFLAG_XXX constants that is suitable for |
| use only with accumulator A1. |
| |
| @item M1 |
| Constant 255. |
| |
| @item M2 |
| Constant 65535. |
| |
| @item J |
| An integer constant with exactly a single bit set. |
| |
| @item L |
| An integer constant with all bits set except exactly one. |
| |
| @item H |
| |
| @item Q |
| Any SYMBOL_REF. |
| @end table |
| |
| @item M32C---@file{config/m32c/m32c.c} |
| @table @code |
| @item Rsp |
| @itemx Rfb |
| @itemx Rsb |
| @samp{$sp}, @samp{$fb}, @samp{$sb}. |
| |
| @item Rcr |
| Any control register, when they're 16 bits wide (nothing if control |
| registers are 24 bits wide) |
| |
| @item Rcl |
| Any control register, when they're 24 bits wide. |
| |
| @item R0w |
| @itemx R1w |
| @itemx R2w |
| @itemx R3w |
| $r0, $r1, $r2, $r3. |
| |
| @item R02 |
| $r0 or $r2, or $r2r0 for 32 bit values. |
| |
| @item R13 |
| $r1 or $r3, or $r3r1 for 32 bit values. |
| |
| @item Rdi |
| A register that can hold a 64 bit value. |
| |
| @item Rhl |
| $r0 or $r1 (registers with addressable high/low bytes) |
| |
| @item R23 |
| $r2 or $r3 |
| |
| @item Raa |
| Address registers |
| |
| @item Raw |
| Address registers when they're 16 bits wide. |
| |
| @item Ral |
| Address registers when they're 24 bits wide. |
| |
| @item Rqi |
| Registers that can hold QI values. |
| |
| @item Rad |
| Registers that can be used with displacements ($a0, $a1, $sb). |
| |
| @item Rsi |
| Registers that can hold 32 bit values. |
| |
| @item Rhi |
| Registers that can hold 16 bit values. |
| |
| @item Rhc |
| Registers chat can hold 16 bit values, including all control |
| registers. |
| |
| @item Rra |
| $r0 through R1, plus $a0 and $a1. |
| |
| @item Rfl |
| The flags register. |
| |
| @item Rmm |
| The memory-based pseudo-registers $mem0 through $mem15. |
| |
| @item Rpi |
| Registers that can hold pointers (16 bit registers for r8c, m16c; 24 |
| bit registers for m32cm, m32c). |
| |
| @item Rpa |
| Matches multiple registers in a PARALLEL to form a larger register. |
| Used to match function return values. |
| |
| @item Is3 |
| -8 @dots{} 7 |
| |
| @item IS1 |
| -128 @dots{} 127 |
| |
| @item IS2 |
| -32768 @dots{} 32767 |
| |
| @item IU2 |
| 0 @dots{} 65535 |
| |
| @item In4 |
| -8 @dots{} -1 or 1 @dots{} 8 |
| |
| @item In5 |
| -16 @dots{} -1 or 1 @dots{} 16 |
| |
| @item In6 |
| -32 @dots{} -1 or 1 @dots{} 32 |
| |
| @item IM2 |
| -65536 @dots{} -1 |
| |
| @item Ilb |
| An 8 bit value with exactly one bit set. |
| |
| @item Ilw |
| A 16 bit value with exactly one bit set. |
| |
| @item Sd |
| The common src/dest memory addressing modes. |
| |
| @item Sa |
| Memory addressed using $a0 or $a1. |
| |
| @item Si |
| Memory addressed with immediate addresses. |
| |
| @item Ss |
| Memory addressed using the stack pointer ($sp). |
| |
| @item Sf |
| Memory addressed using the frame base register ($fb). |
| |
| @item Ss |
| Memory addressed using the small base register ($sb). |
| |
| @item S1 |
| $r1h |
| @end table |
| |
| @item MIPS---@file{config/mips/constraints.md} |
| @table @code |
| @item d |
| An address register. This is equivalent to @code{r} unless |
| generating MIPS16 code. |
| |
| @item f |
| A floating-point register (if available). |
| |
| @item h |
| The @code{hi} register. |
| |
| @item l |
| The @code{lo} register. |
| |
| @item x |
| The @code{hi} and @code{lo} registers. |
| |
| @item c |
| A register suitable for use in an indirect jump. This will always be |
| @code{$25} for @option{-mabicalls}. |
| |
| @item y |
| Equivalent to @code{r}; retained for backwards compatibility. |
| |
| @item z |
| A floating-point condition code register. |
| |
| @item I |
| A signed 16-bit constant (for arithmetic instructions). |
| |
| @item J |
| Integer zero. |
| |
| @item K |
| An unsigned 16-bit constant (for logic instructions). |
| |
| @item L |
| A signed 32-bit constant in which the lower 16 bits are zero. |
| Such constants can be loaded using @code{lui}. |
| |
| @item M |
| A constant that cannot be loaded using @code{lui}, @code{addiu} |
| or @code{ori}. |
| |
| @item N |
| A constant in the range -65535 to -1 (inclusive). |
| |
| @item O |
| A signed 15-bit constant. |
| |
| @item P |
| A constant in the range 1 to 65535 (inclusive). |
| |
| @item G |
| Floating-point zero. |
| |
| @item R |
| An address that can be used in a non-macro load or store. |
| @end table |
| |
| @item Motorola 680x0---@file{config/m68k/constraints.md} |
| @table @code |
| @item a |
| Address register |
| |
| @item d |
| Data register |
| |
| @item f |
| 68881 floating-point register, if available |
| |
| @item I |
| Integer in the range 1 to 8 |
| |
| @item J |
| 16-bit signed number |
| |
| @item K |
| Signed number whose magnitude is greater than 0x80 |
| |
| @item L |
| Integer in the range @minus{}8 to @minus{}1 |
| |
| @item M |
| Signed number whose magnitude is greater than 0x100 |
| |
| @item N |
| Range 24 to 31, rotatert:SI 8 to 1 expressed as rotate |
| |
| @item O |
| 16 (for rotate using swap) |
| |
| @item P |
| Range 8 to 15, rotatert:HI 8 to 1 expressed as rotate |
| |
| @item R |
| Numbers that mov3q can handle |
| |
| @item G |
| Floating point constant that is not a 68881 constant |
| |
| @item S |
| Operands that satisfy 'm' when -mpcrel is in effect |
| |
| @item T |
| Operands that satisfy 's' when -mpcrel is not in effect |
| |
| @item Q |
| Address register indirect addressing mode |
| |
| @item U |
| Register offset addressing |
| |
| @item W |
| const_call_operand |
| |
| @item Cs |
| symbol_ref or const |
| |
| @item Ci |
| const_int |
| |
| @item C0 |
| const_int 0 |
| |
| @item Cj |
| Range of signed numbers that don't fit in 16 bits |
| |
| @item Cmvq |
| Integers valid for mvq |
| |
| @item Capsw |
| Integers valid for a moveq followed by a swap |
| |
| @item Cmvz |
| Integers valid for mvz |
| |
| @item Cmvs |
| Integers valid for mvs |
| |
| @item Ap |
| push_operand |
| |
| @item Ac |
| Non-register operands allowed in clr |
| |
| @end table |
| |
| @item Motorola 68HC11 & 68HC12 families---@file{config/m68hc11/m68hc11.h} |
| @table @code |
| @item a |
| Register `a' |
| |
| @item b |
| Register `b' |
| |
| @item d |
| Register `d' |
| |
| @item q |
| An 8-bit register |
| |
| @item t |
| Temporary soft register _.tmp |
| |
| @item u |
| A soft register _.d1 to _.d31 |
| |
| @item w |
| Stack pointer register |
| |
| @item x |
| Register `x' |
| |
| @item y |
| Register `y' |
| |
| @item z |
| Pseudo register `z' (replaced by `x' or `y' at the end) |
| |
| @item A |
| An address register: x, y or z |
| |
| @item B |
| An address register: x or y |
| |
| @item D |
| Register pair (x:d) to form a 32-bit value |
| |
| @item L |
| Constants in the range @minus{}65536 to 65535 |
| |
| @item M |
| Constants whose 16-bit low part is zero |
| |
| @item N |
| Constant integer 1 or @minus{}1 |
| |
| @item O |
| Constant integer 16 |
| |
| @item P |
| Constants in the range @minus{}8 to 2 |
| |
| @end table |
| |
| @need 1000 |
| @item SPARC---@file{config/sparc/sparc.h} |
| @table @code |
| @item f |
| Floating-point register on the SPARC-V8 architecture and |
| lower floating-point register on the SPARC-V9 architecture. |
| |
| @item e |
| Floating-point register. It is equivalent to @samp{f} on the |
| SPARC-V8 architecture and contains both lower and upper |
| floating-point registers on the SPARC-V9 architecture. |
| |
| @item c |
| Floating-point condition code register. |
| |
| @item d |
| Lower floating-point register. It is only valid on the SPARC-V9 |
| architecture when the Visual Instruction Set is available. |
| |
| @item b |
| Floating-point register. It is only valid on the SPARC-V9 architecture |
| when the Visual Instruction Set is available. |
| |
| @item h |
| 64-bit global or out register for the SPARC-V8+ architecture. |
| |
| @item I |
| Signed 13-bit constant |
| |
| @item J |
| Zero |
| |
| @item K |
| 32-bit constant with the low 12 bits clear (a constant that can be |
| loaded with the @code{sethi} instruction) |
| |
| @item L |
| A constant in the range supported by @code{movcc} instructions |
| |
| @item M |
| A constant in the range supported by @code{movrcc} instructions |
| |
| @item N |
| Same as @samp{K}, except that it verifies that bits that are not in the |
| lower 32-bit range are all zero. Must be used instead of @samp{K} for |
| modes wider than @code{SImode} |
| |
| @item O |
| The constant 4096 |
| |
| @item G |
| Floating-point zero |
| |
| @item H |
| Signed 13-bit constant, sign-extended to 32 or 64 bits |
| |
| @item Q |
| Floating-point constant whose integral representation can |
| be moved into an integer register using a single sethi |
| instruction |
| |
| @item R |
| Floating-point constant whose integral representation can |
| be moved into an integer register using a single mov |
| instruction |
| |
| @item S |
| Floating-point constant whose integral representation can |
| be moved into an integer register using a high/lo_sum |
| instruction sequence |
| |
| @item T |
| Memory address aligned to an 8-byte boundary |
| |
| @item U |
| Even register |
| |
| @item W |
| Memory address for @samp{e} constraint registers |
| |
| @item Y |
| Vector zero |
| |
| @end table |
| |
| @item SPU---@file{config/spu/spu.h} |
| @table @code |
| @item a |
| An immediate which can be loaded with the il/ila/ilh/ilhu instructions. const_int is treated as a 64 bit value. |
| |
| @item c |
| An immediate for and/xor/or instructions. const_int is treated as a 64 bit value. |
| |
| @item d |
| An immediate for the @code{iohl} instruction. const_int is treated as a 64 bit value. |
| |
| @item f |
| An immediate which can be loaded with @code{fsmbi}. |
| |
| @item A |
| An immediate which can be loaded with the il/ila/ilh/ilhu instructions. const_int is treated as a 32 bit value. |
| |
| @item B |
| An immediate for most arithmetic instructions. const_int is treated as a 32 bit value. |
| |
| @item C |
| An immediate for and/xor/or instructions. const_int is treated as a 32 bit value. |
| |
| @item D |
| An immediate for the @code{iohl} instruction. const_int is treated as a 32 bit value. |
| |
| @item I |
| A constant in the range [-64, 63] for shift/rotate instructions. |
| |
| @item J |
| An unsigned 7-bit constant for conversion/nop/channel instructions. |
| |
| @item K |
| A signed 10-bit constant for most arithmetic instructions. |
| |
| @item M |
| A signed 16 bit immediate for @code{stop}. |
| |
| @item N |
| An unsigned 16-bit constant for @code{iohl} and @code{fsmbi}. |
| |
| @item O |
| An unsigned 7-bit constant whose 3 least significant bits are 0. |
| |
| @item P |
| An unsigned 3-bit constant for 16-byte rotates and shifts |
| |
| @item R |
| Call operand, reg, for indirect calls |
| |
| @item S |
| Call operand, symbol, for relative calls. |
| |
| @item T |
| Call operand, const_int, for absolute calls. |
| |
| @item U |
| An immediate which can be loaded with the il/ila/ilh/ilhu instructions. const_int is sign extended to 128 bit. |
| |
| @item W |
| An immediate for shift and rotate instructions. const_int is treated as a 32 bit value. |
| |
| @item Y |
| An immediate for and/xor/or instructions. const_int is sign extended as a 128 bit. |
| |
| @item Z |
| An immediate for the @code{iohl} instruction. const_int is sign extended to 128 bit. |
| |
| @end table |
| |
| @item S/390 and zSeries---@file{config/s390/s390.h} |
| @table @code |
| @item a |
| Address register (general purpose register except r0) |
| |
| @item c |
| Condition code register |
| |
| @item d |
| Data register (arbitrary general purpose register) |
| |
| @item f |
| Floating-point register |
| |
| @item I |
| Unsigned 8-bit constant (0--255) |
| |
| @item J |
| Unsigned 12-bit constant (0--4095) |
| |
| @item K |
| Signed 16-bit constant (@minus{}32768--32767) |
| |
| @item L |
| Value appropriate as displacement. |
| @table @code |
| @item (0..4095) |
| for short displacement |
| @item (-524288..524287) |
| for long displacement |
| @end table |
| |
| @item M |
| Constant integer with a value of 0x7fffffff. |
| |
| @item N |
| Multiple letter constraint followed by 4 parameter letters. |
| @table @code |
| @item 0..9: |
| number of the part counting from most to least significant |
| @item H,Q: |
| mode of the part |
| @item D,S,H: |
| mode of the containing operand |
| @item 0,F: |
| value of the other parts (F---all bits set) |
| @end table |
| The constraint matches if the specified part of a constant |
| has a value different from its other parts. |
| |
| @item Q |
| Memory reference without index register and with short displacement. |
| |
| @item R |
| Memory reference with index register and short displacement. |
| |
| @item S |
| Memory reference without index register but with long displacement. |
| |
| @item T |
| Memory reference with index register and long displacement. |
| |
| @item U |
| Pointer with short displacement. |
| |
| @item W |
| Pointer with long displacement. |
| |
| @item Y |
| Shift count operand. |
| |
| @end table |
| |
| @item Score family---@file{config/score/score.h} |
| @table @code |
| @item d |
| Registers from r0 to r32. |
| |
| @item e |
| Registers from r0 to r16. |
| |
| @item t |
| r8---r11 or r22---r27 registers. |
| |
| @item h |
| hi register. |
| |
| @item l |
| lo register. |
| |
| @item x |
| hi + lo register. |
| |
| @item q |
| cnt register. |
| |
| @item y |
| lcb register. |
| |
| @item z |
| scb register. |
| |
| @item a |
| cnt + lcb + scb register. |
| |
| @item c |
| cr0---cr15 register. |
| |
| @item b |
| cp1 registers. |
| |
| @item f |
| cp2 registers. |
| |
| @item i |
| cp3 registers. |
| |
| @item j |
| cp1 + cp2 + cp3 registers. |
| |
| @item I |
| High 16-bit constant (32-bit constant with 16 LSBs zero). |
| |
| @item J |
| Unsigned 5 bit integer (in the range 0 to 31). |
| |
| @item K |
| Unsigned 16 bit integer (in the range 0 to 65535). |
| |
| @item L |
| Signed 16 bit integer (in the range @minus{}32768 to 32767). |
| |
| @item M |
| Unsigned 14 bit integer (in the range 0 to 16383). |
| |
| @item N |
| Signed 14 bit integer (in the range @minus{}8192 to 8191). |
| |
| @item Z |
| Any SYMBOL_REF. |
| @end table |
| |
| @item Xstormy16---@file{config/stormy16/stormy16.h} |
| @table @code |
| @item a |
| Register r0. |
| |
| @item b |
| Register r1. |
| |
| @item c |
| Register r2. |
| |
| @item d |
| Register r8. |
| |
| @item e |
| Registers r0 through r7. |
| |
| @item t |
| Registers r0 and r1. |
| |
| @item y |
| The carry register. |
| |
| @item z |
| Registers r8 and r9. |
| |
| @item I |
| A constant between 0 and 3 inclusive. |
| |
| @item J |
| A constant that has exactly one bit set. |
| |
| @item K |
| A constant that has exactly one bit clear. |
| |
| @item L |
| A constant between 0 and 255 inclusive. |
| |
| @item M |
| A constant between @minus{}255 and 0 inclusive. |
| |
| @item N |
| A constant between @minus{}3 and 0 inclusive. |
| |
| @item O |
| A constant between 1 and 4 inclusive. |
| |
| @item P |
| A constant between @minus{}4 and @minus{}1 inclusive. |
| |
| @item Q |
| A memory reference that is a stack push. |
| |
| @item R |
| A memory reference that is a stack pop. |
| |
| @item S |
| A memory reference that refers to a constant address of known value. |
| |
| @item T |
| The register indicated by Rx (not implemented yet). |
| |
| @item U |
| A constant that is not between 2 and 15 inclusive. |
| |
| @item Z |
| The constant 0. |
| |
| @end table |
| |
| @item Xtensa---@file{config/xtensa/constraints.md} |
| @table @code |
| @item a |
| General-purpose 32-bit register |
| |
| @item b |
| One-bit boolean register |
| |
| @item A |
| MAC16 40-bit accumulator register |
| |
| @item I |
| Signed 12-bit integer constant, for use in MOVI instructions |
| |
| @item J |
| Signed 8-bit integer constant, for use in ADDI instructions |
| |
| @item K |
| Integer constant valid for BccI instructions |
| |
| @item L |
| Unsigned constant valid for BccUI instructions |
| |
| @end table |
| |
| @end table |
| |
| @ifset INTERNALS |
| @node Define Constraints |
| @subsection Defining Machine-Specific Constraints |
| @cindex defining constraints |
| @cindex constraints, defining |
| |
| Machine-specific constraints fall into two categories: register and |
| non-register constraints. Within the latter category, constraints |
| which allow subsets of all possible memory or address operands should |
| be specially marked, to give @code{reload} more information. |
| |
| Machine-specific constraints can be given names of arbitrary length, |
| but they must be entirely composed of letters, digits, underscores |
| (@samp{_}), and angle brackets (@samp{< >}). Like C identifiers, they |
| must begin with a letter or underscore. |
| |
| In order to avoid ambiguity in operand constraint strings, no |
| constraint can have a name that begins with any other constraint's |
| name. For example, if @code{x} is defined as a constraint name, |
| @code{xy} may not be, and vice versa. As a consequence of this rule, |
| no constraint may begin with one of the generic constraint letters: |
| @samp{E F V X g i m n o p r s}. |
| |
| Register constraints correspond directly to register classes. |
| @xref{Register Classes}. There is thus not much flexibility in their |
| definitions. |
| |
| @deffn {MD Expression} define_register_constraint name regclass docstring |
| All three arguments are string constants. |
| @var{name} is the name of the constraint, as it will appear in |
| @code{match_operand} expressions. If @var{name} is a multi-letter |
| constraint its length shall be the same for all constraints starting |
| with the same letter. @var{regclass} can be either the |
| name of the corresponding register class (@pxref{Register Classes}), |
| or a C expression which evaluates to the appropriate register class. |
| If it is an expression, it must have no side effects, and it cannot |
| look at the operand. The usual use of expressions is to map some |
| register constraints to @code{NO_REGS} when the register class |
| is not available on a given subarchitecture. |
| |
| @var{docstring} is a sentence documenting the meaning of the |
| constraint. Docstrings are explained further below. |
| @end deffn |
| |
| Non-register constraints are more like predicates: the constraint |
| definition gives a Boolean expression which indicates whether the |
| constraint matches. |
| |
| @deffn {MD Expression} define_constraint name docstring exp |
| The @var{name} and @var{docstring} arguments are the same as for |
| @code{define_register_constraint}, but note that the docstring comes |
| immediately after the name for these expressions. @var{exp} is an RTL |
| expression, obeying the same rules as the RTL expressions in predicate |
| definitions. @xref{Defining Predicates}, for details. If it |
| evaluates true, the constraint matches; if it evaluates false, it |
| doesn't. Constraint expressions should indicate which RTL codes they |
| might match, just like predicate expressions. |
| |
| @code{match_test} C expressions have access to the |
| following variables: |
| |
| @table @var |
| @item op |
| The RTL object defining the operand. |
| @item mode |
| The machine mode of @var{op}. |
| @item ival |
| @samp{INTVAL (@var{op})}, if @var{op} is a @code{const_int}. |
| @item hval |
| @samp{CONST_DOUBLE_HIGH (@var{op})}, if @var{op} is an integer |
| @code{const_double}. |
| @item lval |
| @samp{CONST_DOUBLE_LOW (@var{op})}, if @var{op} is an integer |
| @code{const_double}. |
| @item rval |
| @samp{CONST_DOUBLE_REAL_VALUE (@var{op})}, if @var{op} is a floating-point |
| @code{const_double}. |
| @end table |
| |
| The @var{*val} variables should only be used once another piece of the |
| expression has verified that @var{op} is the appropriate kind of RTL |
| object. |
| @end deffn |
| |
| Most non-register constraints should be defined with |
| @code{define_constraint}. The remaining two definition expressions |
| are only appropriate for constraints that should be handled specially |
| by @code{reload} if they fail to match. |
| |
| @deffn {MD Expression} define_memory_constraint name docstring exp |
| Use this expression for constraints that match a subset of all memory |
| operands: that is, @code{reload} can make them match by converting the |
| operand to the form @samp{@w{(mem (reg @var{X}))}}, where @var{X} is a |
| base register (from the register class specified by |
| @code{BASE_REG_CLASS}, @pxref{Register Classes}). |
| |
| For example, on the S/390, some instructions do not accept arbitrary |
| memory references, but only those that do not make use of an index |
| register. The constraint letter @samp{Q} is defined to represent a |
| memory address of this type. If @samp{Q} is defined with |
| @code{define_memory_constraint}, a @samp{Q} constraint can handle any |
| memory operand, because @code{reload} knows it can simply copy the |
| memory address into a base register if required. This is analogous to |
| the way a @samp{o} constraint can handle any memory operand. |
| |
| The syntax and semantics are otherwise identical to |
| @code{define_constraint}. |
| @end deffn |
| |
| @deffn {MD Expression} define_address_constraint name docstring exp |
| Use this expression for constraints that match a subset of all address |
| operands: that is, @code{reload} can make the constraint match by |
| converting the operand to the form @samp{@w{(reg @var{X})}}, again |
| with @var{X} a base register. |
| |
| Constraints defined with @code{define_address_constraint} can only be |
| used with the @code{address_operand} predicate, or machine-specific |
| predicates that work the same way. They are treated analogously to |
| the generic @samp{p} constraint. |
| |
| The syntax and semantics are otherwise identical to |
| @code{define_constraint}. |
| @end deffn |
| |
| For historical reasons, names beginning with the letters @samp{G H} |
| are reserved for constraints that match only @code{const_double}s, and |
| names beginning with the letters @samp{I J K L M N O P} are reserved |
| for constraints that match only @code{const_int}s. This may change in |
| the future. For the time being, constraints with these names must be |
| written in a stylized form, so that @code{genpreds} can tell you did |
| it correctly: |
| |
| @smallexample |
| @group |
| (define_constraint "[@var{GHIJKLMNOP}]@dots{}" |
| "@var{doc}@dots{}" |
| (and (match_code "const_int") ; @r{@code{const_double} for G/H} |
| @var{condition}@dots{})) ; @r{usually a @code{match_test}} |
| @end group |
| @end smallexample |
| @c the semicolons line up in the formatted manual |
| |
| It is fine to use names beginning with other letters for constraints |
| that match @code{const_double}s or @code{const_int}s. |
| |
| Each docstring in a constraint definition should be one or more complete |
| sentences, marked up in Texinfo format. @emph{They are currently unused.} |
| In the future they will be copied into the GCC manual, in @ref{Machine |
| Constraints}, replacing the hand-maintained tables currently found in |
| that section. Also, in the future the compiler may use this to give |
| more helpful diagnostics when poor choice of @code{asm} constraints |
| causes a reload failure. |
| |
| If you put the pseudo-Texinfo directive @samp{@@internal} at the |
| beginning of a docstring, then (in the future) it will appear only in |
| the internals manual's version of the machine-specific constraint tables. |
| Use this for constraints that should not appear in @code{asm} statements. |
| |
| @node C Constraint Interface |
| @subsection Testing constraints from C |
| @cindex testing constraints |
| @cindex constraints, testing |
| |
| It is occasionally useful to test a constraint from C code rather than |
| implicitly via the constraint string in a @code{match_operand}. The |
| generated file @file{tm_p.h} declares a few interfaces for working |
| with machine-specific constraints. None of these interfaces work with |
| the generic constraints described in @ref{Simple Constraints}. This |
| may change in the future. |
| |
| @strong{Warning:} @file{tm_p.h} may declare other functions that |
| operate on constraints, besides the ones documented here. Do not use |
| those functions from machine-dependent code. They exist to implement |
| the old constraint interface that machine-independent components of |
| the compiler still expect. They will change or disappear in the |
| future. |
| |
| Some valid constraint names are not valid C identifiers, so there is a |
| mangling scheme for referring to them from C@. Constraint names that |
| do not contain angle brackets or underscores are left unchanged. |
| Underscores are doubled, each @samp{<} is replaced with @samp{_l}, and |
| each @samp{>} with @samp{_g}. Here are some examples: |
| |
| @c the @c's prevent double blank lines in the printed manual. |
| @example |
| @multitable {Original} {Mangled} |
| @item @strong{Original} @tab @strong{Mangled} @c |
| @item @code{x} @tab @code{x} @c |
| @item @code{P42x} @tab @code{P42x} @c |
| @item @code{P4_x} @tab @code{P4__x} @c |
| @item @code{P4>x} @tab @code{P4_gx} @c |
| @item @code{P4>>} @tab @code{P4_g_g} @c |
| @item @code{P4_g>} @tab @code{P4__g_g} @c |
| @end multitable |
| @end example |
| |
| Throughout this section, the variable @var{c} is either a constraint |
| in the abstract sense, or a constant from @code{enum constraint_num}; |
| the variable @var{m} is a mangled constraint name (usually as part of |
| a larger identifier). |
| |
| @deftp Enum constraint_num |
| For each machine-specific constraint, there is a corresponding |
| enumeration constant: @samp{CONSTRAINT_} plus the mangled name of the |
| constraint. Functions that take an @code{enum constraint_num} as an |
| argument expect one of these constants. |
| |
| Machine-independent constraints do not have associated constants. |
| This may change in the future. |
| @end deftp |
| |
| @deftypefun {inline bool} satisfies_constraint_@var{m} (rtx @var{exp}) |
| For each machine-specific, non-register constraint @var{m}, there is |
| one of these functions; it returns @code{true} if @var{exp} satisfies the |
| constraint. These functions are only visible if @file{rtl.h} was included |
| before @file{tm_p.h}. |
| @end deftypefun |
| |
| @deftypefun bool constraint_satisfied_p (rtx @var{exp}, enum constraint_num @var{c}) |
| Like the @code{satisfies_constraint_@var{m}} functions, but the |
| constraint to test is given as an argument, @var{c}. If @var{c} |
| specifies a register constraint, this function will always return |
| @code{false}. |
| @end deftypefun |
| |
| @deftypefun {enum reg_class} regclass_for_constraint (enum constraint_num @var{c}) |
| Returns the register class associated with @var{c}. If @var{c} is not |
| a register constraint, or those registers are not available for the |
| currently selected subtarget, returns @code{NO_REGS}. |
| @end deftypefun |
| |
| Here is an example use of @code{satisfies_constraint_@var{m}}. In |
| peephole optimizations (@pxref{Peephole Definitions}), operand |
| constraint strings are ignored, so if there are relevant constraints, |
| they must be tested in the C condition. In the example, the |
| optimization is applied if operand 2 does @emph{not} satisfy the |
| @samp{K} constraint. (This is a simplified version of a peephole |
| definition from the i386 machine description.) |
| |
| @smallexample |
| (define_peephole2 |
| [(match_scratch:SI 3 "r") |
| (set (match_operand:SI 0 "register_operand" "") |
| (mult:SI (match_operand:SI 1 "memory_operand" "") |
| (match_operand:SI 2 "immediate_operand" "")))] |
| |
| "!satisfies_constraint_K (operands[2])" |
| |
| [(set (match_dup 3) (match_dup 1)) |
| (set (match_dup 0) (mult:SI (match_dup 3) (match_dup 2)))] |
| |
| "") |
| @end smallexample |
| |
| @node Standard Names |
| @section Standard Pattern Names For Generation |
| @cindex standard pattern names |
| @cindex pattern names |
| @cindex names, pattern |
| |
| 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. |
| |
| @table @asis |
| @cindex @code{mov@var{m}} instruction pattern |
| @item @samp{mov@var{m}} |
| Here @var{m} stands for a two-letter machine mode name, in lowercase. |
| This instruction pattern moves data with that machine mode from operand |
| 1 to operand 0. For example, @samp{movsi} moves full-word data. |
| |
| If operand 0 is a @code{subreg} with mode @var{m} of a register whose |
| own mode is wider than @var{m}, the effect of this instruction is |
| to store the specified value in the part of the register that corresponds |
| to mode @var{m}. Bits outside of @var{m}, but which are within the |
| same target word as the @code{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 @emph{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, |
| @samp{mov@var{m}} 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. |
| |
| @findex force_reg |
| 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 @code{define_expand}, then in such a case the |
| @code{define_expand} mustn't call @code{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. |
| |
| @findex change_address |
| 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 |
| @code{change_address}) that will do so may be called. Note that |
| @code{general_operand} will fail when applied to such an address. |
| |
| @findex reload_in_progress |
| The global variable @code{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 @code{gen_reg_rtx} prior to life analysis. |
| |
| If there are cases which need scratch registers during or after reload, |
| you must provide an appropriate secondary_reload target hook. |
| |
| @findex can_create_pseudo_p |
| The macro @code{can_create_pseudo_p} 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 @code{gen_reg_rtx} to allocate a new pseudo. |
| |
| The constraints on a @samp{mov@var{m}} must permit moving any hard |
| register to any other hard register provided that |
| @code{HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and |
| @code{REGISTER_MOVE_COST} applied to their classes returns a value of 2. |
| |
| It is obligatory to support floating point @samp{mov@var{m}} |
| instructions into and out of any registers that can hold fixed point |
| values, because unions and structures (which have modes @code{SImode} or |
| @code{DImode}) can be in those registers and they may have floating |
| point members. |
| |
| There may also be a need to support fixed point @samp{mov@var{m}} |
| 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 @code{HARD_REGNO_MODE_OK} rejects fixed point values in |
| floating point registers, then the constraints of the fixed point |
| @samp{mov@var{m}} instructions must be designed to avoid ever trying to |
| reload into a floating point register. |
| |
| @cindex @code{reload_in} instruction pattern |
| @cindex @code{reload_out} instruction pattern |
| @item @samp{reload_in@var{m}} |
| @itemx @samp{reload_out@var{m}} |
| These named patterns have been obsoleted by the target hook |
| @code{secondary_reload}. |
| |
| Like @samp{mov@var{m}}, 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 @code{SECONDARY_RELOAD_CLASS} |
| macro in @pxref{Register Classes}. |
| |
| There are special restrictions on the form of the @code{match_operand}s |
| used in these patterns. First, only the predicate for the reload |
| operand is examined, i.e., @code{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 @code{ALL_REGS} register class. This may relieve ports |
| of the burden of defining an @code{ALL_REGS} constraint letter just |
| for these patterns. |
| |
| @cindex @code{movstrict@var{m}} instruction pattern |
| @item @samp{movstrict@var{m}} |
| Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg} |
| with mode @var{m} of a register whose natural mode is wider, |
| the @samp{movstrict@var{m}} instruction is guaranteed not to alter |
| any of the register except the part which belongs to mode @var{m}. |
| |
| @cindex @code{movmisalign@var{m}} instruction pattern |
| @item @samp{movmisalign@var{m}} |
| This variant of a move pattern is designed to load or store a value |
| from a memory address that is not naturally aligned for its mode. |
| For a store, the memory will be in operand 0; for a load, the memory |
| will be in operand 1. The other operand is guaranteed not to be a |
| memory, so that it's easy to tell whether this is a load or store. |
| |
| This pattern is used by the autovectorizer, and when expanding a |
| @code{MISALIGNED_INDIRECT_REF} expression. |
| |
| @cindex @code{load_multiple} instruction pattern |
| @item @samp{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 @code{define_expand} (@pxref{Expander Definitions}) |
| and make the pattern fail if the restrictions are not met. |
| |
| Write the generated insn as a @code{parallel} with elements being a |
| @code{set} of one register from the appropriate memory location (you may |
| also need @code{use} or @code{clobber} elements). Use a |
| @code{match_parallel} (@pxref{RTL Template}) to recognize the insn. See |
| @file{rs6000.md} for examples of the use of this insn pattern. |
| |
| @cindex @samp{store_multiple} instruction pattern |
| @item @samp{store_multiple} |
| Similar to @samp{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. |
| |
| @cindex @code{vec_set@var{m}} instruction pattern |
| @item @samp{vec_set@var{m}} |
| Set given field in the vector value. Operand 0 is the vector to modify, |
| operand 1 is new value of field and operand 2 specify the field index. |
| |
| @cindex @code{vec_extract@var{m}} instruction pattern |
| @item @samp{vec_extract@var{m}} |
| Extract given field from the vector value. Operand 1 is the vector, operand 2 |
| specify field index and operand 0 place to store value into. |
| |
| @cindex @code{vec_extract_even@var{m}} instruction pattern |
| @item @samp{vec_extract_even@var{m}} |
| Extract even elements from the input vectors (operand 1 and operand 2). |
| The even elements of operand 2 are concatenated to the even elements of operand |
| 1 in their original order. The result is stored in operand 0. |
| The output and input vectors should have the same modes. |
| |
| @cindex @code{vec_extract_odd@var{m}} instruction pattern |
| @item @samp{vec_extract_odd@var{m}} |
| Extract odd elements from the input vectors (operand 1 and operand 2). |
| The odd elements of operand 2 are concatenated to the odd elements of operand |
| 1 in their original order. The result is stored in operand 0. |
| The output and input vectors should have the same modes. |
| |
| @cindex @code{vec_interleave_high@var{m}} instruction pattern |
| @item @samp{vec_interleave_high@var{m}} |
| Merge high elements of the two input vectors into the output vector. The output |
| and input vectors should have the same modes (@code{N} elements). The high |
| @code{N/2} elements of the first input vector are interleaved with the high |
| @code{N/2} elements of the second input vector. |
| |
| @cindex @code{vec_interleave_low@var{m}} instruction pattern |
| @item @samp{vec_interleave_low@var{m}} |
| Merge low elements of the two input vectors into the output vector. The output |
| and input vectors should have the same modes (@code{N} elements). The low |
| @code{N/2} elements of the first input vector are interleaved with the low |
| @code{N/2} elements of the second input vector. |
| |
| @cindex @code{vec_init@var{m}} instruction pattern |
| @item @samp{vec_init@var{m}} |
| Initialize the vector to given values. Operand 0 is the vector to initialize |
| and operand 1 is parallel containing values for individual fields. |
| |
| @cindex @code{push@var{m}1} instruction pattern |
| @item @samp{push@var{m}1} |
| Output a push instruction. Operand 0 is value to push. Used only when |
| @code{PUSH_ROUNDING} is defined. For historical reason, this pattern may be |
| missing and in such case an @code{mov} expander is used instead, with a |
| @code{MEM} expression forming the push operation. The @code{mov} expander |
| method is deprecated. |
| |
| @cindex @code{add@var{m}3} instruction pattern |
| @item @samp{add@var{m}3} |
| Add operand 2 and operand 1, storing the result in operand 0. All operands |
| must have mode @var{m}. This can be used even on two-address machines, by |
| means of constraints requiring operands 1 and 0 to be the same location. |
| |
| @cindex @code{ssadd@var{m}3} instruction pattern |
| @cindex @code{usadd@var{m}3} instruction pattern |
| @cindex @code{sub@var{m}3} instruction pattern |
| @cindex @code{sssub@var{m}3} instruction pattern |
| @cindex @code{ussub@var{m}3} instruction pattern |
| @cindex @code{mul@var{m}3} instruction pattern |
| @cindex @code{ssmul@var{m}3} instruction pattern |
| @cindex @code{usmul@var{m}3} instruction pattern |
| @cindex @code{div@var{m}3} instruction pattern |
| @cindex @code{ssdiv@var{m}3} instruction pattern |
| @cindex @code{udiv@var{m}3} instruction pattern |
| @cindex @code{usdiv@var{m}3} instruction pattern |
| @cindex @code{mod@var{m}3} instruction pattern |
| @cindex @code{umod@var{m}3} instruction pattern |
| @cindex @code{umin@var{m}3} instruction pattern |
| @cindex @code{umax@var{m}3} instruction pattern |
| @cindex @code{and@var{m}3} instruction pattern |
| @cindex @code{ior@var{m}3} instruction pattern |
| @cindex @code{xor@var{m}3} instruction pattern |
| @item @samp{ssadd@var{m}3}, @samp{usadd@var{m}3} |
| @item @samp{sub@var{m}3}, @samp{sssub@var{m}3}, @samp{ussub@var{m}3} |
| @item @samp{mul@var{m}3}, @samp{ssmul@var{m}3}, @samp{usmul@var{m}3} |
| @itemx @samp{div@var{m}3}, @samp{ssdiv@var{m}3} |
| @itemx @samp{udiv@var{m}3}, @samp{usdiv@var{m}3} |
| @itemx @samp{mod@var{m}3}, @samp{umod@var{m}3} |
| @itemx @samp{umin@var{m}3}, @samp{umax@var{m}3} |
| @itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3} |
| Similar, for other arithmetic operations. |
| |
| @cindex @code{min@var{m}3} instruction pattern |
| @cindex @code{max@var{m}3} instruction pattern |
| @item @samp{smin@var{m}3}, @samp{smax@var{m}3} |
| Signed minimum and maximum operations. When used with floating point, |
| if both operands are zeros, or if either operand is @code{NaN}, then |
| it is unspecified which of the two operands is returned as the result. |
| |
| @cindex @code{reduc_smin_@var{m}} instruction pattern |
| @cindex @code{reduc_smax_@var{m}} instruction pattern |
| @item @samp{reduc_smin_@var{m}}, @samp{reduc_smax_@var{m}} |
| Find the signed minimum/maximum of the elements of a vector. The vector is |
| operand 1, and the scalar result is stored in the least significant bits of |
| operand 0 (also a vector). The output and input vector should have the same |
| modes. |
| |
| @cindex @code{reduc_umin_@var{m}} instruction pattern |
| @cindex @code{reduc_umax_@var{m}} instruction pattern |
| @item @samp{reduc_umin_@var{m}}, @samp{reduc_umax_@var{m}} |
| Find the unsigned minimum/maximum of the elements of a vector. The vector is |
| operand 1, and the scalar result is stored in the least significant bits of |
| operand 0 (also a vector). The output and input vector should have the same |
| modes. |
| |
| @cindex @code{reduc_splus_@var{m}} instruction pattern |
| @item @samp{reduc_splus_@var{m}} |
| Compute the sum of the signed elements of a vector. The vector is operand 1, |
| and the scalar result is stored in the least significant bits of operand 0 |
| (also a vector). The output and input vector should have the same modes. |
| |
| @cindex @code{reduc_uplus_@var{m}} instruction pattern |
| @item @samp{reduc_uplus_@var{m}} |
| Compute the sum of the unsigned elements of a vector. The vector is operand 1, |
| and the scalar result is stored in the least significant bits of operand 0 |
| (also a vector). The output and input vector should have the same modes. |
| |
| @cindex @code{sdot_prod@var{m}} instruction pattern |
| @item @samp{sdot_prod@var{m}} |
| @cindex @code{udot_prod@var{m}} instruction pattern |
| @item @samp{udot_prod@var{m}} |
| Compute the sum of the products of two signed/unsigned elements. |
| Operand 1 and operand 2 are of the same mode. Their product, which is of a |
| wider mode, is computed and added to operand 3. Operand 3 is of a mode equal or |
| wider than the mode of the product. The result is placed in operand 0, which |
| is of the same mode as operand 3. |
| |
| @cindex @code{ssum_widen@var{m3}} instruction pattern |
| @item @samp{ssum_widen@var{m3}} |
| @cindex @code{usum_widen@var{m3}} instruction pattern |
| @item @samp{usum_widen@var{m3}} |
| Operands 0 and 2 are of the same mode, which is wider than the mode of |
| operand 1. Add operand 1 to operand 2 and place the widened result in |
| operand 0. (This is used express accumulation of elements into an accumulator |
| of a wider mode.) |
| |
| @cindex @code{vec_shl_@var{m}} instruction pattern |
| @cindex @code{vec_shr_@var{m}} instruction pattern |
| @item @samp{vec_shl_@var{m}}, @samp{vec_shr_@var{m}} |
| Whole vector left/right shift in bits. |
| Operand 1 is a vector to be shifted. |
| Operand 2 is an integer shift amount in bits. |
| Operand 0 is where the resulting shifted vector is stored. |
| The output and input vectors should have the same modes. |
| |
| @cindex @code{vec_pack_trunc_@var{m}} instruction pattern |
| @item @samp{vec_pack_trunc_@var{m}} |
| Narrow (demote) and merge the elements of two vectors. Operands 1 and 2 |
| are vectors of the same mode having N integral or floating point elements |
| of size S@. Operand 0 is the resulting vector in which 2*N elements of |
| size N/2 are concatenated after narrowing them down using truncation. |
| |
| @cindex @code{vec_pack_ssat_@var{m}} instruction pattern |
| @cindex @code{vec_pack_usat_@var{m}} instruction pattern |
| @item @samp{vec_pack_ssat_@var{m}}, @samp{vec_pack_usat_@var{m}} |
| Narrow (demote) and merge the elements of two vectors. Operands 1 and 2 |
| are vectors of the same mode having N integral elements of size S. |
| Operand 0 is the resulting vector in which the elements of the two input |
| vectors are concatenated after narrowing them down using signed/unsigned |
| saturating arithmetic. |
| |
| @cindex @code{vec_pack_sfix_trunc_@var{m}} instruction pattern |
| @cindex @code{vec_pack_ufix_trunc_@var{m}} instruction pattern |
| @item @samp{vec_pack_sfix_trunc_@var{m}}, @samp{vec_pack_ufix_trunc_@var{m}} |
| Narrow, convert to signed/unsigned integral type and merge the elements |
| of two vectors. Operands 1 and 2 are vectors of the same mode having N |
| floating point elements of size S@. Operand 0 is the resulting vector |
| in which 2*N elements of size N/2 are concatenated. |
| |
| @cindex @code{vec_unpacks_hi_@var{m}} instruction pattern |
| @cindex @code{vec_unpacks_lo_@var{m}} instruction pattern |
| @item @samp{vec_unpacks_hi_@var{m}}, @samp{vec_unpacks_lo_@var{m}} |
| Extract and widen (promote) the high/low part of a vector of signed |
| integral or floating point elements. The input vector (operand 1) has N |
| elements of size S@. Widen (promote) the high/low elements of the vector |
| using signed or floating point extension and place the resulting N/2 |
| values of size 2*S in the output vector (operand 0). |
| |
| @cindex @code{vec_unpacku_hi_@var{m}} instruction pattern |
| @cindex @code{vec_unpacku_lo_@var{m}} instruction pattern |
| @item @samp{vec_unpacku_hi_@var{m}}, @samp{vec_unpacku_lo_@var{m}} |
| Extract and widen (promote) the high/low part of a vector of unsigned |
| integral elements. The input vector (operand 1) has N elements of size S. |
| Widen (promote) the high/low elements of the vector using zero extension and |
| place the resulting N/2 values of size 2*S in the output vector (operand 0). |
| |
| @cindex @code{vec_unpacks_float_hi_@var{m}} instruction pattern |
| @cindex @code{vec_unpacks_float_lo_@var{m}} instruction pattern |
| @cindex @code{vec_unpacku_float_hi_@var{m}} instruction pattern |
| @cindex @code{vec_unpacku_float_lo_@var{m}} instruction pattern |
| @item @samp{vec_unpacks_float_hi_@var{m}}, @samp{vec_unpacks_float_lo_@var{m}} |
| @itemx @samp{vec_unpacku_float_hi_@var{m}}, @samp{vec_unpacku_float_lo_@var{m}} |
| Extract, convert to floating point type and widen the high/low part of a |
| vector of signed/unsigned integral elements. The input vector (operand 1) |
| has N elements of size S@. Convert the high/low elements of the vector using |
| floating point conversion and place the resulting N/2 values of size 2*S in |
| the output vector (operand 0). |
| |
| @cindex @code{vec_widen_umult_hi_@var{m}} instruction pattern |
| @cindex @code{vec_widen_umult_lo__@var{m}} instruction pattern |
| @cindex @code{vec_widen_smult_hi_@var{m}} instruction pattern |
| @cindex @code{vec_widen_smult_lo_@var{m}} instruction pattern |
| @item @samp{vec_widen_umult_hi_@var{m}}, @samp{vec_widen_umult_lo_@var{m}} |
| @itemx @samp{vec_widen_smult_hi_@var{m}}, @samp{vec_widen_smult_lo_@var{m}} |
| Signed/Unsigned widening multiplication. The two inputs (operands 1 and 2) |
| are vectors with N signed/unsigned elements of size S@. Multiply the high/low |
| elements of the two vectors, and put the N/2 products of size 2*S in the |
| output vector (operand 0). |
| |
| @cindex @code{mulhisi3} instruction pattern |
| @item @samp{mulhisi3} |
| Multiply operands 1 and 2, which have mode @code{HImode}, and store |
| a @code{SImode} product in operand 0. |
| |
| @cindex @code{mulqihi3} instruction pattern |
| @cindex @code{mulsidi3} instruction pattern |
| @item @samp{mulqihi3}, @samp{mulsidi3} |
| Similar widening-multiplication instructions of other widths. |
| |
| @cindex @code{umulqihi3} instruction pattern |
| @cindex @code{umulhisi3} instruction pattern |
| @cindex @code{umulsidi3} instruction pattern |
| @item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3} |
| Similar widening-multiplication instructions that do unsigned |
| multiplication. |
| |
| @cindex @code{usmulqihi3} instruction pattern |
| @cindex @code{usmulhisi3} instruction pattern |
| @cindex @code{usmulsidi3} instruction pattern |
| @item @samp{usmulqihi3}, @samp{usmulhisi3}, @samp{usmulsidi3} |
| Similar widening-multiplication instructions that interpret the first |
| operand as unsigned and the second operand as signed, then do a signed |
| multiplication. |
| |
| @cindex @code{smul@var{m}3_highpart} instruction pattern |
| @item @samp{smul@var{m}3_highpart} |
| Perform a signed multiplication of operands 1 and 2, which have mode |
| @var{m}, and store the most significant half of the product in operand 0. |
| The least significant half of the product is discarded. |
| |
| @cindex @code{umul@var{m}3_highpart} instruction pattern |
| @item @samp{umul@var{m}3_highpart} |
| Similar, but the multiplication is unsigned. |
| |
| @cindex @code{madd@var{m}@var{n}4} instruction pattern |
| @item @samp{madd@var{m}@var{n}4} |
| Multiply operands 1 and 2, sign-extend them to mode @var{n}, add |
| operand 3, and store the result in operand 0. Operands 1 and 2 |
| have mode @var{m} and operands 0 and 3 have mode @var{n}. |
| Both modes must be integer or fixed-point modes and @var{n} must be twice |
| the size of @var{m}. |
| |
| In other words, @code{madd@var{m}@var{n}4} is like |
| @code{mul@var{m}@var{n}3} except that it also adds operand 3. |
| |
| These instructions are not allowed to @code{FAIL}. |
| |
| @cindex @code{umadd@var{m}@var{n}4} instruction pattern |
| @item @samp{umadd@var{m}@var{n}4} |
| Like @code{madd@var{m}@var{n}4}, but zero-extend the multiplication |
| operands instead of sign-extending them. |
| |
| @cindex @code{ssmadd@var{m}@var{n}4} instruction pattern |
| @item @samp{ssmadd@var{m}@var{n}4} |
| Like @code{madd@var{m}@var{n}4}, but all involved operations must be |
| signed-saturating. |
| |
| @cindex @code{usmadd@var{m}@var{n}4} instruction pattern |
| @item @samp{usmadd@var{m}@var{n}4} |
| Like @code{umadd@var{m}@var{n}4}, but all involved operations must be |
| unsigned-saturating. |
| |
| @cindex @code{msub@var{m}@var{n}4} instruction pattern |
| @item @samp{msub@var{m}@var{n}4} |
| Multiply operands 1 and 2, sign-extend them to mode @var{n}, subtract the |
| result from operand 3, and store the result in operand 0. Operands 1 and 2 |
| have mode @var{m} and operands 0 and 3 have mode @var{n}. |
| Both modes must be integer or fixed-point modes and @var{n} must be twice |
| the size of @var{m}. |
| |
| In other words, @code{msub@var{m}@var{n}4} is like |
| @code{mul@var{m}@var{n}3} except that it also subtracts the result |
| from operand 3. |
| |
| These instructions are not allowed to @code{FAIL}. |
| |
| @cindex @code{umsub@var{m}@var{n}4} instruction pattern |
| @item @samp{umsub@var{m}@var{n}4} |
| Like @code{msub@var{m}@var{n}4}, but zero-extend the multiplication |
| operands instead of sign-extending them. |
| |
| @cindex @code{ssmsub@var{m}@var{n}4} instruction pattern |
| @item @samp{ssmsub@var{m}@var{n}4} |
| Like @code{msub@var{m}@var{n}4}, but all involved operations must be |
| signed-saturating. |
| |
| @cindex @code{usmsub@var{m}@var{n}4} instruction pattern |
| @item @samp{usmsub@var{m}@var{n}4} |
| Like @code{umsub@var{m}@var{n}4}, but all involved operations must be |
| unsigned-saturating. |
| |
| @cindex @code{divmod@var{m}4} instruction pattern |
| @item @samp{divmod@var{m}4} |
| 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 @samp{divmod@var{m}4} but do not |
| provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}. 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 @samp{divmod@var{m}4} to call |
| @code{find_reg_note} and look for a @code{REG_UNUSED} note on the |
| quotient or remainder and generate the appropriate instruction. |
| |
| @cindex @code{udivmod@var{m}4} instruction pattern |
| @item @samp{udivmod@var{m}4} |
| Similar, but does unsigned division. |
| |
| @anchor{shift patterns} |
| @cindex @code{ashl@var{m}3} instruction pattern |
| @cindex @code{ssashl@var{m}3} instruction pattern |
| @cindex @code{usashl@var{m}3} instruction pattern |
| @item @samp{ashl@var{m}3}, @samp{ssashl@var{m}3}, @samp{usashl@var{m}3} |
| Arithmetic-shift operand 1 left by a number of bits specified by operand |
| 2, and store the result in operand 0. Here @var{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. The meaning of out-of-range shift |
| counts can optionally be specified by @code{TARGET_SHIFT_TRUNCATION_MASK}. |
| @xref{TARGET_SHIFT_TRUNCATION_MASK}. |
| |
| @cindex @code{ashr@var{m}3} instruction pattern |
| @cindex @code{lshr@var{m}3} instruction pattern |
| @cindex @code{rotl@var{m}3} instruction pattern |
| @cindex @code{rotr@var{m}3} instruction pattern |
| @item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3} |
| Other shift and rotate instructions, analogous to the |
| @code{ashl@var{m}3} instructions. |
| |
| @cindex @code{neg@var{m}2} instruction pattern |
| @cindex @code{ssneg@var{m}2} instruction pattern |
| @cindex @code{usneg@var{m}2} instruction pattern |
| @item @samp{neg@var{m}2}, @samp{ssneg@var{m}2}, @samp{usneg@var{m}2} |
| Negate operand 1 and store the result in operand 0. |
| |
| @cindex @code{abs@var{m}2} instruction pattern |
| @item @samp{abs@var{m}2} |
| Store the absolute value of operand 1 into operand 0. |
| |
| @cindex @code{sqrt@var{m}2} instruction pattern |
| @item @samp{sqrt@var{m}2} |
| Store the square root of operand 1 into operand 0. |
| |
| The @code{sqrt} built-in function of C always uses the mode which |
| corresponds to the C data type @code{double} and the @code{sqrtf} |
| built-in function uses the mode which corresponds to the C data |
| type @code{float}. |
| |
| @cindex @code{fmod@var{m}3} instruction pattern |
| @item @samp{fmod@var{m}3} |
| Store the remainder of dividing operand 1 by operand 2 into |
| operand 0, rounded towards zero to an integer. |
| |
| The @code{fmod} built-in function of C always uses the mode which |
| corresponds to the C data type @code{double} and the @code{fmodf} |
| built-in function uses the mode which corresponds to the C data |
| type @code{float}. |
| |
| @cindex @code{remainder@var{m}3} instruction pattern |
| @item @samp{remainder@var{m}3} |
| Store the remainder of dividing operand 1 by operand 2 into |
| operand 0, rounded to the nearest integer. |
| |
| The @code{remainder} built-in function of C always uses the mode |
| which corresponds to the C data type @code{double} and the |
| @code{remainderf} built-in function uses the mode which corresponds |
| to the C data type @code{float}. |
| |
| @cindex @code{cos@var{m}2} instruction pattern |
| @item @samp{cos@var{m}2} |
| Store the cosine of operand 1 into operand 0. |
| |
| The @code{cos} built-in function of C always uses the mode which |
| corresponds to the C data type @code{double} and the @code{cosf} |
| built-in function uses the mode which corresponds to the C data |
| type @code{float}. |
| |
| @cindex @code{sin@var{m}2} instruction pattern |
| @item @samp{sin@var{m}2} |
| Store the sine of operand 1 into operand 0. |
| |
| The @code{sin} built-in function of C always uses the mode which |
| corresponds to the C data type @code{double} and the @code{sinf} |
| built-in function uses the mode which corresponds to the C data |
| type @code{float}. |
| |
| @cindex @code{exp@var{m}2} instruction pattern |
| @item @samp{exp@var{m}2} |
| Store the exponential of operand 1 into operand 0. |
| |
| The @code{exp} built-in function of C always uses the mode which |
| corresponds to the C data type @code{double} and the @code{expf} |
| built-in function uses the mode which corresponds to the C data |
| type @code{float}. |
| |
| @cindex @code{log@var{m}2} instruction pattern |
| @item @samp{log@var{m}2} |
| Store the natural logarithm of operand 1 into operand 0. |
| |
| The @code{log} built-in function of C always uses the mode which |
| corresponds to the C data type @code{double} and the @code{logf} |
| built-in function uses the mode which corresponds to the C data |
| type @code{float}. |
| |
| @cindex @code{pow@var{m}3} instruction pattern |
| @item @samp{pow@var{m}3} |
| Store the value of operand 1 raised to the exponent operand 2 |
| into operand 0. |
| |
| The @code{pow} built-in function of C always uses the mode which |
| corresponds to the C data type @code{double} and the @code{powf} |
| built-in function uses the mode which corresponds to the C data |
| type @code{float}. |
| |
| @cindex @code{atan2@var{m}3} instruction pattern |
| @item @samp{atan2@var{m}3} |
| Store the arc tangent (inverse tangent) of operand 1 divided by |
| operand 2 into operand 0, using the signs of both arguments to |
| determine the quadrant of the result. |
| |
| The @code{atan2} built-in function of C always uses the mode which |
| corresponds to the C data type @code{double} and the @code{atan2f} |
| built-in function uses the mode which corresponds to the C data |
| type @code{float}. |
| |
| @cindex @code{floor@var{m}2} instruction pattern |
| @item @samp{floor@var{m}2} |
| Store the largest integral value not greater than argument. |
| |
| The @code{floor} built-in function of C always uses the mode which |
| corresponds to the C data type @code{double} and the @code{floorf} |
| built-in function uses the mode which corresponds to the C data |
| type @code{float}. |
| |
| @cindex @code{btrunc@var{m}2} instruction pattern |
| @item @samp{btrunc@var{m}2} |
| Store the argument rounded to integer towards zero. |
| |
| The @code{trunc} built-in function of C always uses the mode which |
| corresponds to the C data type @code{double} and the @code{truncf} |
| built-in function uses the mode which corresponds to the C data |
| type @code{float}. |
| |
| @cindex @code{round@var{m}2} instruction pattern |
| @item @samp{round@var{m}2} |
| Store the argument rounded to integer away from zero. |
| |
| The @code{round} built-in function of C always uses the mode which |
| corresponds to the C data type @code{double} and the @code{roundf} |
| built-in function uses the mode which corresponds to the C data |
| type @code{float}. |
| |
| @cindex @code{ceil@var{m}2} instruction pattern |
| @item @samp{ceil@var{m}2} |
| Store the argument rounded to integer away from zero. |
| |
| The @code{ceil} built-in function of C always uses the mode which |
| corresponds to the C data type @code{double} and the @code{ceilf} |
| built-in function uses the mode which corresponds to the C data |
| type @code{float}. |
| |
| @cindex @code{nearbyint@var{m}2} instruction pattern |
| @item @samp{nearbyint@var{m}2} |
| Store the argument rounded according to the default rounding mode |
| |
| The @code{nearbyint} built-in function of C always uses the mode which |
| corresponds to the C data type @code{double} and the @code{nearbyintf} |
| built-in function uses the mode which corresponds to the C data |
| type @code{float}. |
| |
| @cindex @code{rint@var{m}2} instruction pattern |
| @item @samp{rint@var{m}2} |
| Store the argument rounded according to the default rounding mode and |
| raise the inexact exception when the result differs in value from |
| the argument |
| |
| The @code{rint} built-in function of C always uses the mode which |
| corresponds to the C data type @code{double} and the @code{rintf} |
| built-in function uses the mode which corresponds to the C data |
| type @code{float}. |
| |
| @cindex @code{lrint@var{m}@var{n}2} |
| @item @samp{lrint@var{m}@var{n}2} |
| Convert operand 1 (valid for floating point mode @var{m}) to fixed |
| point mode @var{n} as a signed number according to the current |
| rounding mode and store in operand 0 (which has mode @var{n}). |
| |
| @cindex @code{lround@var{m}@var{n}2} |
| @item @samp{lround@var{m}2} |
| Convert operand 1 (valid for floating point mode @var{m}) to fixed |
| point mode @var{n} as a signed number rounding to nearest and away |
| from zero and store in operand 0 (which has mode @var{n}). |
| |
| @cindex @code{lfloor@var{m}@var{n}2} |
| @item @samp{lfloor@var{m}2} |
| Convert operand 1 (valid for floating point mode @var{m}) to fixed |
| point mode @var{n} as a signed number rounding down and store in |
| operand 0 (which has mode @var{n}). |
| |
| @cindex @code{lceil@var{m}@var{n}2} |
| @item @samp{lceil@var{m}2} |
| Convert operand 1 (valid for floating point mode @var{m}) to fixed |
| point mode @var{n} as a signed number rounding up and store in |
| operand 0 (which has mode @var{n}). |
| |
| @cindex @code{copysign@var{m}3} instruction pattern |
| @item @samp{copysign@var{m}3} |
| Store a value with the magnitude of operand 1 and the sign of operand |
| 2 into operand 0. |
| |
| The @code{copysign} built-in function of C always uses the mode which |
| corresponds to the C data type @code{double} and the @code{copysignf} |
| built-in function uses the mode which corresponds to the C data |
| type @code{float}. |
| |
| @cindex @code{ffs@var{m}2} instruction pattern |
| @item @samp{ffs@var{m}2} |
| Store into operand 0 one plus the index of the least significant 1-bit |
| of operand 1. If operand 1 is zero, store zero. @var{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 @code{ffs} built-in function of C always uses the mode which |
| corresponds to the C data type @code{int}. |
| |
| @cindex @code{clz@var{m}2} instruction pattern |
| @item @samp{clz@var{m}2} |
| Store into operand 0 the number of leading 0-bits in @var{x}, starting |
| at the most significant bit position. If @var{x} is 0, the |
| @code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if |
| the result is undefined or has a useful value. |
| @var{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. |
| |
| @cindex @code{ctz@var{m}2} instruction pattern |
| @item @samp{ctz@var{m}2} |
| Store into operand 0 the number of trailing 0-bits in @var{x}, starting |
| at the least significant bit position. If @var{x} is 0, the |
| @code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if |
| the result is undefined or has a useful value. |
| @var{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. |
| |
| @cindex @code{popcount@var{m}2} instruction pattern |
| @item @samp{popcount@var{m}2} |
| Store into operand 0 the number of 1-bits in @var{x}. @var{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. |
| |
| @cindex @code{parity@var{m}2} instruction pattern |
| @item @samp{parity@var{m}2} |
| Store into operand 0 the parity of @var{x}, i.e.@: the number of 1-bits |
| in @var{x} modulo 2. @var{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. |
| |
| @cindex @code{one_cmpl@var{m}2} instruction pattern |
| @item @samp{one_cmpl@var{m}2} |
| Store the bitwise-complement of operand 1 into operand 0. |
| |
| @cindex @code{cmp@var{m}} instruction pattern |
| @item @samp{cmp@var{m}} |
| Compare operand 0 and operand 1, and set the condition codes. |
| The RTL pattern should look like this: |
| |
| @smallexample |
| (set (cc0) (compare (match_operand:@var{m} 0 @dots{}) |
| (match_operand:@var{m} 1 @dots{}))) |
| @end smallexample |
| |
| @cindex @code{tst@var{m}} instruction pattern |
| @item @samp{tst@var{m}} |
| Compare operand 0 against zero, and set the condition codes. |
| The RTL pattern should look like this: |
| |
| @smallexample |
| (set (cc0) (match_operand:@var{m} 0 @dots{})) |
| @end smallexample |
| |
| @samp{tst@var{m}} patterns should not be defined for machines that do |
| not use @code{(cc0)}. Doing so would confuse the optimizer since it |
| would no longer be clear which @code{set} operations were comparisons. |
| The @samp{cmp@var{m}} patterns should be used instead. |
| |
| @cindex @code{movmem@var{m}} instruction pattern |
| @item @samp{movmem@var{m}} |
| Block move instruction. The destination and source blocks of memory |
| are the first two operands, and both are @code{mem:BLK}s with an |
| address in mode @code{Pmode}. |
| |
| The number of bytes to move is the third operand, in mode @var{m}. |
| Usually, you specify @code{word_mode} for @var{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., @code{QImode} for values in the range 0--127; note we avoid numbers |
| that appear negative) and also a pattern with @code{word_mode}. |
| |
| The fourth operand is the known shared alignment of the source and |
| destination, in the form of a @code{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. |
| |
| Optional operands 5 and 6 specify expected alignment and size of block |
| respectively. The expected alignment differs from alignment in operand 4 |
| in a way that the blocks are not required to be aligned according to it in |
| all cases. Expected size, when unknown, is set to @code{(const_int -1)}. |
| |
| Descriptions of multiple @code{movmem@var{m}} 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 @var{m} |
| in @code{movmem@var{m}} 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. |
| |
| @cindex @code{movstr} instruction pattern |
| @item @samp{movstr} |
| String copy instruction, with @code{stpcpy} semantics. Operand 0 is |
| an output operand in mode @code{Pmode}. The addresses of the |
| destination and source strings are operands 1 and 2, and both are |
| @code{mem:BLK}s with addresses in mode @code{Pmode}. The execution of |
| the expansion of this pattern should store in operand 0 the address in |
| which the @code{NUL} terminator was stored in the destination string. |
| |
| @cindex @code{setmem@var{m}} instruction pattern |
| @item @samp{setmem@var{m}} |
| Block set instruction. The destination string is the first operand, |
| given as a @code{mem:BLK} whose address is in mode @code{Pmode}. The |
| number of bytes to set is the second operand, in mode @var{m}. The value to |
| initialize the memory with is the third operand. Targets that only support the |
| clearing of memory should reject any value that is not the constant 0. See |
| @samp{movmem@var{m}} for a discussion of the choice of mode. |
| |
| The fourth operand is the known alignment of the destination, in the form |
| of a @code{const_int} rtx. Thus, if the compiler knows that the |
| destination is word-aligned, it may provide the value 4 for this |
| operand. |
| |
| Optional operands 5 and 6 specify expected alignment and size of block |
| respectively. The expected alignment differs from alignment in operand 4 |
| in a way that the blocks are not required to be aligned according to it in |
| all cases. Expected size, when unknown, is set to @code{(const_int -1)}. |
| |
| The use for multiple @code{setmem@var{m}} is as for @code{movmem@var{m}}. |
| |
| @cindex @code{cmpstrn@var{m}} instruction pattern |
| @item @samp{cmpstrn@var{m}} |
| String compare instruction, with five operands. Operand 0 is the output; |
| it has mode @var{m}. The remaining four operands are like the operands |
| of @samp{movmem@var{m}}. The two memory blocks specified are compared |
| byte by byte in lexicographic order starting at the beginning of each |
| string. The instruction is not allowed to prefetch more than one byte |
| at a time since either string may end in the first byte and reading past |
| that may access an invalid page or segment and cause a fault. The |
| effect of the instruction is to store a value in operand 0 whose sign |
| indicates the result of the comparison. |
| |
| @cindex @code{cmpstr@var{m}} instruction pattern |
| @item @samp{cmpstr@var{m}} |
| String compare instruction, without known maximum length. Operand 0 is the |
| output; it has mode @var{m}. The second and third operand are the blocks of |
| memory to be compared; both are @code{mem:BLK} with an address in mode |
| @code{Pmode}. |
| |
| The fourth operand is the known shared alignment of the source and |
| destination, in the form of a @code{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. |
| |
| The two memory blocks specified are compared byte by byte in lexicographic |
| order starting at the beginning of each string. The instruction is not allowed |
| to prefetch more than one byte at a time since either string may end in the |
| first byte and reading past that may access an invalid page or segment and |
| cause a fault. The effect of the instruction is to store a value in operand 0 |
| whose sign indicates the result of the comparison. |
| |
| @cindex @code{cmpmem@var{m}} instruction pattern |
| @item @samp{cmpmem@var{m}} |
| Block compare instruction, with five operands like the operands |
| of @samp{cmpstr@var{m}}. The two memory blocks specified are compared |
| byte by byte in lexicographic order starting at the beginning of each |
| block. Unlike @samp{cmpstr@var{m}} the instruction can prefetch |
| any bytes in the two memory blocks. The effect of the instruction is |
| to store a value in operand 0 whose sign indicates the result of the |
| comparison. |
| |
| @cindex @code{strlen@var{m}} instruction pattern |
| @item @samp{strlen@var{m}} |
| Compute the length of a string, with three operands. |
| Operand 0 is the result (of mode @var{m}), operand 1 is |
| a @code{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. |
| |
| @cindex @code{float@var{mn}2} instruction pattern |
| @item @samp{float@var{m}@var{n}2} |
| Convert signed integer operand 1 (valid for fixed point mode @var{m}) to |
| floating point mode @var{n} and store in operand 0 (which has mode |
| @var{n}). |
| |
| @cindex @code{floatuns@var{mn}2} instruction pattern |
| @item @samp{floatuns@var{m}@var{n}2} |
| Convert unsigned integer operand 1 (valid for fixed point mode @var{m}) |
| to floating point mode @var{n} and store in operand 0 (which has mode |
| @var{n}). |
| |
| @cindex @code{fix@var{mn}2} instruction pattern |
| @item @samp{fix@var{m}@var{n}2} |
| Convert operand 1 (valid for floating point mode @var{m}) to fixed |
| point mode @var{n} as a signed number and store in operand 0 (which |
| has mode @var{n}). This instruction's result is defined only when |
| the value of operand 1 is an integer. |
| |
| If the machine description defines this pattern, it also needs to |
| define the @code{ftrunc} pattern. |
| |
| @cindex @code{fixuns@var{mn}2} instruction pattern |
| @item @samp{fixuns@var{m}@var{n}2} |
| Convert operand 1 (valid for floating point mode @var{m}) to fixed |
| point mode @var{n} as an unsigned number and store in operand 0 (which |
| has mode @var{n}). This instruction's result is defined only when the |
| value of operand 1 is an integer. |
| |
| @cindex @code{ftrunc@var{m}2} instruction pattern |
| @item @samp{ftrunc@var{m}2} |
| Convert operand 1 (valid for floating point mode @var{m}) to an |
| integer value, still represented in floating point mode @var{m}, and |
| store it in operand 0 (valid for floating point mode @var{m}). |
| |
| @cindex @code{fix_trunc@var{mn}2} instruction pattern |
| @item @samp{fix_trunc@var{m}@var{n}2} |
| Like @samp{fix@var{m}@var{n}2} but works for any floating point value |
| of mode @var{m} by converting the value to an integer. |
| |
| @cindex @code{fixuns_trunc@var{mn}2} instruction pattern |
| @item @samp{fixuns_trunc@var{m}@var{n}2} |
| Like @samp{fixuns@var{m}@var{n}2} but works for any floating point |
| value of mode @var{m} by converting the value to an integer. |
| |
| @cindex @code{trunc@var{mn}2} instruction pattern |
| @item @samp{trunc@var{m}@var{n}2} |
| Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and |
| store in operand 0 (which has mode @var{n}). Both modes must be fixed |
| point or both floating point. |
| |
| @cindex @code{extend@var{mn}2} instruction pattern |
| @item @samp{extend@var{m}@var{n}2} |
| Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and |
| store in operand 0 (which has mode @var{n}). Both modes must be fixed |
| point or both floating point. |
| |
| @cindex @code{zero_extend@var{mn}2} instruction pattern |
| @item @samp{zero_extend@var{m}@var{n}2} |
| Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and |
| store in operand 0 (which has mode @var{n}). Both modes must be fixed |
| point. |
| |
| @cindex @code{fract@var{mn}2} instruction pattern |
| @item @samp{fract@var{m}@var{n}2} |
| Convert operand 1 of mode @var{m} to mode @var{n} and store in |
| operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} |
| could be fixed-point to fixed-point, signed integer to fixed-point, |
| fixed-point to signed integer, floating-point to fixed-point, |
| or fixed-point to floating-point. |
| When overflows or underflows happen, the results are undefined. |
| |
| @cindex @code{satfract@var{mn}2} instruction pattern |
| @item @samp{satfract@var{m}@var{n}2} |
| Convert operand 1 of mode @var{m} to mode @var{n} and store in |
| operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} |
| could be fixed-point to fixed-point, signed integer to fixed-point, |
| or floating-point to fixed-point. |
| When overflows or underflows happen, the instruction saturates the |
| results to the maximum or the minimum. |
| |
| @cindex @code{fractuns@var{mn}2} instruction pattern |
| @item @samp{fractuns@var{m}@var{n}2} |
| Convert operand 1 of mode @var{m} to mode @var{n} and store in |
| operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} |
| could be unsigned integer to fixed-point, or |
| fixed-point to unsigned integer. |
| When overflows or underflows happen, the results are undefined. |
| |
| @cindex @code{satfractuns@var{mn}2} instruction pattern |
| @item @samp{satfractuns@var{m}@var{n}2} |
| Convert unsigned integer operand 1 of mode @var{m} to fixed-point mode |
| @var{n} and store in operand 0 (which has mode @var{n}). |
| When overflows or underflows happen, the instruction saturates the |
| results to the maximum or the minimum. |
| |
| @cindex @code{extv} instruction pattern |
| @item @samp{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 @code{word_mode}. |
| Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often |
| @code{word_mode} is allowed only for registers. Operands 2 and 3 must |
| be valid for @code{word_mode}. |
| |
| The RTL generation pass generates this instruction only with constants |
| for operands 2 and 3 and the constant is never zero for operand 2. |
| |
| The bit-field value is sign-extended to a full word integer |
| before it is stored in operand 0. |
| |
| @cindex @code{extzv} instruction pattern |
| @item @samp{extzv} |
| Like @samp{extv} except that the bit-field value is zero-extended. |
| |
| @cindex @code{insv} instruction pattern |
| @item @samp{insv} |
| Store operand 3 (which must be valid for @code{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 @code{byte_mode} or |
| @code{word_mode}; often @code{word_mode} is allowed only for registers. |
| Operands 1 and 2 must be valid for @code{word_mode}. |
| |
| The RTL generation pass generates this instruction only with constants |
| for operands 1 and 2 and the constant is never zero for operand 1. |
| |
| @cindex @code{mov@var{mode}cc} instruction pattern |
| @item @samp{mov@var{mode}cc} |
| 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. |
| |
| @cindex @code{add@var{mode}cc} instruction pattern |
| @item @samp{add@var{mode}cc} |
| Similar to @samp{mov@var{mode}cc} but for conditional addition. Conditionally |
| move operand 2 or (operands 2 + 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 2 + operand 3) is moved. |
| |
| @cindex @code{s@var{cond}} instruction pattern |
| @item @samp{s@var{cond}} |
| Store zero or nonzero in the operand according to the condition codes. |
| Value stored is nonzero iff the condition @var{cond} is true. |
| @var{cond} is the name of a comparison operation expression code, such |
| as @code{eq}, @code{lt} or @code{leu}. |
| |
| You specify the mode that the operand must have when you write the |
| @code{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 |
| @code{STORE_FLAG_VALUE} (@pxref{Misc}). If a description cannot be |
| found that can be used for all the @samp{s@var{cond}} 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 @samp{s@var{cond}} pattern |
| followed by those required to convert the result into a 1 or a zero in |
| @code{SImode}, you should omit the @samp{s@var{cond}} operations from |
| the machine description. |
| |
| @cindex @code{b@var{cond}} instruction pattern |
| @item @samp{b@var{cond}} |
| Conditional branch instruction. Operand 0 is a @code{label_ref} that |
| refers to the label to jump to. Jump if the condition codes meet |
| condition @var{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 @samp{cmp@var{m}} (and @samp{tst@var{m}}) patterns should |
| simply store the operands away and generate all the required insns in a |
| @code{define_expand} (@pxref{Expander Definitions}) for the conditional |
| branch operations. All calls to expand @samp{b@var{cond}} patterns are |
| immediately preceded by calls to expand either a @samp{cmp@var{m}} |
| pattern or a @samp{tst@var{m}} 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. @xref{Jump Patterns}. |
| |
| The above discussion also applies to the @samp{mov@var{mode}cc} and |
| @samp{s@var{cond}} patterns. |
| |
| @cindex @code{cbranch@var{mode}4} instruction pattern |
| @item @samp{cbranch@var{mode}4} |
| Conditional branch instruction combined with a compare instruction. |
| Operand 0 is a comparison operator. Operand 1 and operand 2 are the |
| first and second operands of the comparison, respectively. Operand 3 |
| is a @code{label_ref} that refers to the label to jump to. |
| |
| @cindex @code{jump} instruction pattern |
| @item @samp{jump} |
| A jump inside a function; an unconditional branch. Operand 0 is the |
| @code{label_ref} of the label to jump to. This pattern name is mandatory |
| on all machines. |
| |
| @cindex @code{call} instruction pattern |
| @item @samp{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 @code{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 @code{mem} RTX whose address is the address of the |
| function. Note, however, that this address can be a @code{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 |
| @code{define_expand} (@pxref{Expander Definitions}) that places the |
| address into a register and uses that register in the call instruction. |
| |
| @cindex @code{call_value} instruction pattern |
| @item @samp{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 @samp{call} |
| instruction (but with numbers increased by one). |
| |
| Subroutines that return @code{BLKmode} objects use the @samp{call} |
| insn. |
| |
| @cindex @code{call_pop} instruction pattern |
| @cindex @code{call_value_pop} instruction pattern |
| @item @samp{call_pop}, @samp{call_value_pop} |
| Similar to @samp{call} and @samp{call_value}, except used if defined and |
| if @code{RETURN_POPS_ARGS} is nonzero. They should emit a @code{parallel} |
| that contains both the function call and a @code{set} to indicate the |
| adjustment made to the frame pointer. |
| |
| For machines where @code{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. |
| |
| @cindex @code{untyped_call} instruction pattern |
| @item @samp{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 @code{parallel} |
| expression where each element is a @code{set} expression that indicates |
| the saving of a function return value into the result block. |
| |
| This instruction pattern should be defined to support |
| @code{__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.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register). |
| |
| @cindex @code{return} instruction pattern |
| @item @samp{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 @samp{mov@var{m}} 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. |
| |
| @findex reload_completed |
| @findex leaf_function_p |
| For such machines, the condition specified in this pattern should only |
| be true when @code{reload_completed} is nonzero and the function's |
| epilogue would only be a single instruction. For machines with register |
| windows, the routine @code{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 |
| |
| @smallexample |
| (define_insn "" |
| [(set (pc) |
| (if_then_else (match_operator |
| 0 "comparison_operator" |
| [(cc0) (const_int 0)]) |
| (return) |
| (pc)))] |
| "@var{condition}" |
| "@dots{}") |
| @end smallexample |
| |
| where @var{condition} would normally be the same condition specified on the |
| named @samp{return} pattern. |
| |
| @cindex @code{untyped_return} instruction pattern |
| @item @samp{untyped_return} |
| Untyped subroutine return instruction. This instruction pattern should |
| be defined to support @code{__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 @code{__builtin_apply} is stored; operand 1 is a @code{parallel} |
| expression where each element is a @code{set} expression that indicates |
| the restoring of a function return value from the result block. |
| |
| @cindex @code{nop} instruction pattern |
| @item @samp{nop} |
| No-op instruction. This instruction pattern name should always be defined |
| to output a no-op in assembler code. @code{(const_int 0)} will do as an |
| RTL pattern. |
| |
| @cindex @code{indirect_jump} instruction pattern |
| @item @samp{indirect_jump} |
| An instruction to jump to an address which is operand zero. |
| This pattern name is mandatory on all machines. |
| |
| @cindex @code{casesi} instruction pattern |
| @item @samp{casesi} |
| Instruction to jump through a dispatch table, including bounds checking. |
| This instruction takes five operands: |
| |
| @enumerate |
| @item |
| The index to dispatch on, which has mode @code{SImode}. |
| |
| @item |
| The lower bound for indices in the table, an integer constant. |
| |
| @item |
| The total range of indices in the table---the largest index |
| minus the smallest one (both inclusive). |
| |
| @item |
| A label that precedes the table itself. |
| |
| @item |
| A label to jump to if the index has a value outside the bounds. |
| @end enumerate |
| |
| The table is a @code{addr_vec} or @code{addr_diff_vec} inside of a |
| @code{jump_insn}. The number of elements in the table is one plus the |
| difference between the upper bound and the lower bound. |
| |
| @cindex @code{tablejump} instruction pattern |
| @item @samp{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 @samp{casesi} pattern. |
| |
| This pattern requires two operands: the address or offset, and a label |
| which should immediately precede the jump table. If the macro |
| @code{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 @code{Pmode}. |
| |
| The @samp{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. |
| |
| |
| @cindex @code{decrement_and_branch_until_zero} instruction pattern |
| @item @samp{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. @xref{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. |
| |
| @cindex @code{doloop_end} instruction pattern |
| @item @samp{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 @code{const_int} or @code{const0_rtx} if this cannot be |
| determined until run-time; operand 2 is the actual or estimated maximum |
| number of iterations as a @code{const_int}; operand 3 is the number of |
| enclosed loops as a @code{const_int} (an innermost loop has a value of |
| 1); operand 4 is the label to jump to if the register is nonzero. |
| @xref{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 @code{define_expand} (@pxref{Expander Definitions}) |
| and make the pattern fail if operand 3 is not @code{const1_rtx}. |
| Similarly, if the actual or estimated maximum number of iterations is |
| too large for this instruction, make it fail. |
| |
| @cindex @code{doloop_begin} instruction pattern |
| @item @samp{doloop_begin} |
| Companion instruction to @code{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 @code{define_expand} |
| (@pxref{Expander Definitions}) and make it fail. |
| |
| |
| @cindex @code{canonicalize_funcptr_for_compare} instruction pattern |
| @item @samp{canonicalize_funcptr_for_compare} |
| Canonicalize the function pointer in operand 1 and store the result |
| into operand 0. |
| |
| Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1 |
| may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc |
| and also has mode @code{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. |
| |
| @cindex @code{save_stack_block} instruction pattern |
| @cindex @code{save_stack_function} instruction pattern |
| @cindex @code{save_stack_nonlocal} instruction pattern |
| @cindex @code{restore_stack_block} instruction pattern |
| @cindex @code{restore_stack_function} instruction pattern |
| @cindex @code{restore_stack_nonlocal} instruction pattern |
| @item @samp{save_stack_block} |
| @itemx @samp{save_stack_function} |
| @itemx @samp{save_stack_nonlocal} |
| @itemx @samp{restore_stack_block} |
| @itemx @samp{restore_stack_function} |
| @itemx @samp{restore_stack_nonlocal} |
| Most machines save and restore the stack pointer by copying it to or |
| from an object of mode @code{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 @code{define_expand} (@pxref{Expander |
| Definitions}) that produces the required insns. The three types of |
| saves and restores are: |
| |
| @enumerate |
| @item |
| @samp{save_stack_block} saves the stack pointer at the start of a block |
| that allocates a variable-sized object, and @samp{restore_stack_block} |
| restores the stack pointer when the block is exited. |
| |
| @item |
| @samp{save_stack_function} and @samp{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 @code{alloca}. Only |
| the epilogue uses the restored stack pointer, allowing a simpler save or |
| restore sequence on some machines. |
| |
| @item |
| @samp{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 @samp{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. |
| @end enumerate |
| |
| 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 @code{Pmode} but you can override that choice by defining the |
| @code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}). You must |
| specify an integral mode, or @code{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 |
| @samp{save_stack_block} is defined, operand 0 must not be |
| @code{VOIDmode} since these saves can be arbitrarily nested. |
| |
| A save area is a @code{mem} that is at a constant offset from |
| @code{virtual_stack_vars_rtx} when the stack pointer is saved for use by |
| nonlocal gotos and a @code{reg} in the other two cases. |
| |
| @cindex @code{allocate_stack} instruction pattern |
| @item @samp{allocate_stack} |
| Subtract (or add if @code{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 @code{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. |
| |
| @cindex @code{check_stack} instruction pattern |
| @item @samp{check_stack} |
| If stack checking cannot be done on your system by probing the stack with |
| a load or store instruction (@pxref{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. |
| |
| @cindex @code{nonlocal_goto} instruction pattern |
| @item @samp{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 |
| @samp{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. |
| |
| @cindex @code{nonlocal_goto_receiver} instruction pattern |
| @item @samp{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. |
| |
| @cindex @code{exception_receiver} instruction pattern |
| @item @samp{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. |
| |
| @cindex @code{builtin_setjmp_setup} instruction pattern |
| @item @samp{builtin_setjmp_setup} |
| This pattern, if defined, contains additional code needed to initialize |
| the @code{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 @code{jmp_buf}. Note that the buffer is five words long and that |
| the first three are normally used by the generic mechanism. |
| |
| @cindex @code{builtin_setjmp_receiver} instruction pattern |
| @item @samp{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. |
| |
| @cindex @code{builtin_longjmp} instruction pattern |
| @item @samp{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 |
| @code{builtin_setjmp_setup}. The single argument is a pointer to the |
| @code{jmp_buf}. |
| |
| @cindex @code{eh_return} instruction pattern |
| @item @samp{eh_return} |
| This pattern, if defined, affects the way @code{__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 address of the exception handler to which the function should return |
| is passed as operand to this pattern. It will normally need to copied by |
| the pattern to some special register or memory location. |
| If the pattern needs to determine the location of the target call |
| frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX}, |
| if defined; it will have already been assigned. |
| |
| If this pattern is not defined, the default action will be to simply |
| copy the return address to @code{EH_RETURN_HANDLER_RTX}. Either |
| that macro or this pattern needs to be defined if call frame exception |
| handling is to be used. |
| |
| @cindex @code{prologue} instruction pattern |
| @anchor{prologue instruction pattern} |
| @item @samp{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 |
| @code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue. |
| |
| The @code{prologue} pattern is particularly useful for targets which perform |
| instruction scheduling. |
| |
| @cindex @code{epilogue} instruction pattern |
| @anchor{epilogue instruction pattern} |
| @item @samp{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 |
| @code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue. |
| |
| The @code{epilogue} pattern is particularly useful for targets which perform |
| instruction scheduling or which have delay slots for their return instruction. |
| |
| @cindex @code{sibcall_epilogue} instruction pattern |
| @item @samp{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 @code{sibcall_epilogue} pattern must not clobber any arguments used for |
| parameter passing or any stack slots for arguments passed to the current |
| function. |
| |
| @cindex @code{trap} instruction pattern |
| @item @samp{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. |
| |
| @cindex @code{conditional_trap} instruction pattern |
| @item @samp{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 @code{conditional_trap} pattern looks like |
| |
| @smallexample |
| (define_insn "conditional_trap" |
| [(trap_if (match_operator 0 "trap_operator" |
| [(cc0) (const_int 0)]) |
| (match_operand 1 "const_int_operand" "i"))] |
| "" |
| "@dots{}") |
| @end smallexample |
| |
| @cindex @code{prefetch} instruction pattern |
| @item @samp{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. |
| |
| @cindex @code{blockage} instruction pattern |
| @item @samp{blockage} |
| |
| This pattern defines a pseudo insn that prevents the instruction |
| scheduler from moving instructions across the boundary defined by the |
| blockage insn. Normally an UNSPEC_VOLATILE pattern. |
| |
| @cindex @code{memory_barrier} instruction pattern |
| @item @samp{memory_barrier} |
| |
| If the target memory model is not fully synchronous, then this pattern |
| should be defined to an instruction that orders both loads and stores |
| before the instruction with respect to loads and stores after the instruction. |
| This pattern has no operands. |
| |
| @cindex @code{sync_compare_and_swap@var{mode}} instruction pattern |
| @item @samp{sync_compare_and_swap@var{mode}} |
| |
| This pattern, if defined, emits code for an atomic compare-and-swap |
| operation. Operand 1 is the memory on which the atomic operation is |
| performed. Operand 2 is the ``old'' value to be compared against the |
| current contents of the memory location. Operand 3 is the ``new'' value |
| to store in the memory if the compare succeeds. Operand 0 is the result |
| of the operation; it should contain the contents of the memory |
| before the operation. If the compare succeeds, this should obviously be |
| a copy of operand 2. |
| |
| This pattern must show that both operand 0 and operand 1 are modified. |
| |
| This pattern must issue any memory barrier instructions such that all |
| memory operations before the atomic operation occur before the atomic |
| operation and all memory operations after the atomic operation occur |
| after the atomic operation. |
| |
| @cindex @code{sync_compare_and_swap_cc@var{mode}} instruction pattern |
| @item @samp{sync_compare_and_swap_cc@var{mode}} |
| |
| This pattern is just like @code{sync_compare_and_swap@var{mode}}, except |
| it should act as if compare part of the compare-and-swap were issued via |
| @code{cmp@var{m}}. This comparison will only be used with @code{EQ} and |
| @code{NE} branches and @code{setcc} operations. |
| |
| Some targets do expose the success or failure of the compare-and-swap |
| operation via the status flags. Ideally we wouldn't need a separate |
| named pattern in order to take advantage of this, but the combine pass |
| does not handle patterns with multiple sets, which is required by |
| definition for @code{sync_compare_and_swap@var{mode}}. |
| |
| @cindex @code{sync_add@var{mode}} instruction pattern |
| @cindex @code{sync_sub@var{mode}} instruction pattern |
| @cindex @code{sync_ior@var{mode}} instruction pattern |
| @cindex @code{sync_and@var{mode}} instruction pattern |
| @cindex @code{sync_xor@var{mode}} instruction pattern |
| @cindex @code{sync_nand@var{mode}} instruction pattern |
| @item @samp{sync_add@var{mode}}, @samp{sync_sub@var{mode}} |
| @itemx @samp{sync_ior@var{mode}}, @samp{sync_and@var{mode}} |
| @itemx @samp{sync_xor@var{mode}}, @samp{sync_nand@var{mode}} |
| |
| These patterns emit code for an atomic operation on memory. |
| Operand 0 is the memory on which the atomic operation is performed. |
| Operand 1 is the second operand to the binary operator. |
| |
| The ``nand'' operation is @code{~op0 & op1}. |
| |
| This pattern must issue any memory barrier instructions such that all |
| memory operations before the atomic operation occur before the atomic |
| operation and all memory operations after the atomic operation occur |
| after the atomic operation. |
| |
| If these patterns are not defined, the operation will be constructed |
| from a compare-and-swap operation, if defined. |
| |
| @cindex @code{sync_old_add@var{mode}} instruction pattern |
| @cindex @code{sync_old_sub@var{mode}} instruction pattern |
| @cindex @code{sync_old_ior@var{mode}} instruction pattern |
| @cindex @code{sync_old_and@var{mode}} instruction pattern |
| @cindex @code{sync_old_xor@var{mode}} instruction pattern |
| @cindex @code{sync_old_nand@var{mode}} instruction pattern |
| @item @samp{sync_old_add@var{mode}}, @samp{sync_old_sub@var{mode}} |
| @itemx @samp{sync_old_ior@var{mode}}, @samp{sync_old_and@var{mode}} |
| @itemx @samp{sync_old_xor@var{mode}}, @samp{sync_old_nand@var{mode}} |
| |
| These patterns are emit code for an atomic operation on memory, |
| and return the value that the memory contained before the operation. |
| Operand 0 is the result value, operand 1 is the memory on which the |
| atomic operation is performed, and operand 2 is the second operand |
| to the binary operator. |
| |
| This pattern must issue any memory barrier instructions such that all |
| memory operations before the atomic operation occur before the atomic |
| operation and all memory operations after the atomic operation occur |
| after the atomic operation. |
| |
| If these patterns are not defined, the operation will be constructed |
| from a compare-and-swap operation, if defined. |
| |
| @cindex @code{sync_new_add@var{mode}} instruction pattern |
| @cindex @code{sync_new_sub@var{mode}} instruction pattern |
| @cindex @code{sync_new_ior@var{mode}} instruction pattern |
| @cindex @code{sync_new_and@var{mode}} instruction pattern |
| @cindex @code{sync_new_xor@var{mode}} instruction pattern |
| @cindex @code{sync_new_nand@var{mode}} instruction pattern |
| @item @samp{sync_new_add@var{mode}}, @samp{sync_new_sub@var{mode}} |
| @itemx @samp{sync_new_ior@var{mode}}, @samp{sync_new_and@var{mode}} |
| @itemx @samp{sync_new_xor@var{mode}}, @samp{sync_new_nand@var{mode}} |
| |
| These patterns are like their @code{sync_old_@var{op}} counterparts, |
| except that they return the value that exists in the memory location |
| after the operation, rather than before the operation. |
| |
| @cindex @code{sync_lock_test_and_set@var{mode}} instruction pattern |
| @item @samp{sync_lock_test_and_set@var{mode}} |
| |
| This pattern takes two forms, based on the capabilities of the target. |
| In either case, operand 0 is the result of the operand, operand 1 is |
| the memory on which the atomic operation is performed, and operand 2 |
| is the value to set in the lock. |
| |
| In the ideal case, this operation is an atomic exchange operation, in |
| which the previous value in memory operand is copied into the result |
| operand, and the value operand is stored in the memory operand. |
| |
| For less capable targets, any value operand that is not the constant 1 |
| should be rejected with @code{FAIL}. In this case the target may use |
| an atomic test-and-set bit operation. The result operand should contain |
| 1 if the bit was previously set and 0 if the bit was previously clear. |
| The true contents of the memory operand are implementation defined. |
| |
| This pattern must issue any memory barrier instructions such that the |
| pattern as a whole acts as an acquire barrier, that is all memory |
| operations after the pattern do not occur until the lock is acquired. |
| |
| If this pattern is not defined, the operation will be constructed from |
| a compare-and-swap operation, if defined. |
| |
| @cindex @code{sync_lock_release@var{mode}} instruction pattern |
| @item @samp{sync_lock_release@var{mode}} |
| |
| This pattern, if defined, releases a lock set by |
| @code{sync_lock_test_and_set@var{mode}}. Operand 0 is the memory |
| that contains the lock; operand 1 is the value to store in the lock. |
| |
| If the target doesn't implement full semantics for |
| @code{sync_lock_test_and_set@var{mode}}, any value operand which is not |
| the constant 0 should be rejected with @code{FAIL}, and the true contents |
| of the memory operand are implementation defined. |
| |
| This pattern must issue any memory barrier instructions such that the |
| pattern as a whole acts as a release barrier, that is the lock is |
| released only after all previous memory operations have completed. |
| |
| If this pattern is not defined, then a @code{memory_barrier} pattern |
| will be emitted, followed by a store of the value to the memory operand. |
| |
| @cindex @code{stack_protect_set} instruction pattern |
| @item @samp{stack_protect_set} |
| |
| This pattern, if defined, moves a @code{Pmode} value from the memory |
| in operand 1 to the memory in operand 0 without leaving the value in |
| a register afterward. This is to avoid leaking the value some place |
| that an attacker might use to rewrite the stack guard slot after |
| having clobbered it. |
| |
| If this pattern is not defined, then a plain move pattern is generated. |
| |
| @cindex @code{stack_protect_test} instruction pattern |
| @item @samp{stack_protect_test} |
| |
| This pattern, if defined, compares a @code{Pmode} value from the |
| memory in operand 1 with the memory in operand 0 without leaving the |
| value in a register afterward and branches to operand 2 if the values |
| weren't equal. |
| |
| If this pattern is not defined, then a plain compare pattern and |
| conditional branch pattern is used. |
| |
| @cindex @code{clear_cache} instruction pattern |
| @item @samp{clear_cache} |
| |
| This pattern, if defined, flushes the instruction cache for a region of |
| memory. The region is bounded to by the Pmode pointers in operand 0 |
| inclusive and operand 1 exclusive. |
| |
| If this pattern is not defined, a call to the library function |
| @code{__clear_cache} is used. |
| |
| @end table |
| |
| @end ifset |
| @c Each of the following nodes are wrapped in separate |
| @c "@ifset INTERNALS" to work around memory limits for the default |
| @c configuration in older tetex distributions. Known to not work: |
| @c tetex-1.0.7, known to work: tetex-2.0.2. |
| @ifset INTERNALS |
| @node Pattern Ordering |
| @section When the Order of Patterns Matters |
| @cindex Pattern Ordering |
| @cindex Ordering of Patterns |
| |
| 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. |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Dependent Patterns |
| @section Interdependence of Patterns |
| @cindex Dependent Patterns |
| @cindex Interdependence of Patterns |
| |
| Every machine description must have a named pattern for each of the |
| conditional branch names @samp{b@var{cond}}. The recognition template |
| must always have the form |
| |
| @smallexample |
| (set (pc) |
| (if_then_else (@var{cond} (cc0) (const_int 0)) |
| (label_ref (match_operand 0 "" "")) |
| (pc))) |
| @end smallexample |
| |
| @noindent |
| In addition, every machine description must have an anonymous pattern |
| for each of the possible reverse-conditional branches. Their templates |
| look like |
| |
| @smallexample |
| (set (pc) |
| (if_then_else (@var{cond} (cc0) (const_int 0)) |
| (pc) |
| (label_ref (match_operand 0 "" "")))) |
| @end smallexample |
| |
| @noindent |
| They are necessary because jump optimization can turn direct-conditional |
| branches into reverse-conditional branches. |
| |
| It is often convenient to use the @code{match_operator} construct to |
| reduce the number of patterns that must be specified for branches. For |
| example, |
| |
| @smallexample |
| (define_insn "" |
| [(set (pc) |
| (if_then_else (match_operator 0 "comparison_operator" |
| [(cc0) (const_int 0)]) |
| (pc) |
| (label_ref (match_operand 1 "" ""))))] |
| "@var{condition}" |
| "@dots{}") |
| @end smallexample |
| |
| 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 |
| |
| @smallexample |
| (set (match_operand:SI 0 @dots{}) |
| (extend:SI (match_operand:HI 1 @dots{}))) |
| |
| (set (match_operand:SI 0 @dots{}) |
| (extend:SI (match_operand:QI 1 @dots{}))) |
| @end smallexample |
| |
| @noindent |
| 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 (@code{HImode}, |
| here). If the pattern matches the @code{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. |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Jump Patterns |
| @section Defining Jump Instruction Patterns |
| @cindex jump instruction patterns |
| @cindex 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 |
| @code{next_cc0_user (insn)}. (The variable @code{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 @code{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 |
| @code{NOTICE_UPDATE_CC} to do @code{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 @code{(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. |
| |
| @findex prev_cc0_setter |
| @findex next_cc0_user |
| 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 @code{(cc0)}, the set |
| and use of the condition code must be adjacent (separated only by |
| @code{note} insns) allowing flags in @code{cc_status} to be used. |
| (@xref{Condition Code}.) Also, the comparison and branch insns can be |
| located from each other by using the functions @code{prev_cc0_setter} |
| and @code{next_cc0_user}. |
| |
| However, this is not true on machines that do not use @code{(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 @code{MODE_CC}. Normally, it will be @code{CCmode}. If |
| additional modes are required (as for the add example mentioned above in |
| the SPARC), define them in @file{@var{machine}-modes.def} |
| (@pxref{Condition Code}). Also define @code{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 @code{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 |
| |
| @smallexample |
| (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)))] |
| "" |
| "@dots{}") |
| @end smallexample |
| |
| The @code{SELECT_CC_MODE} macro on the SPARC returns @code{CC_NOOVmode} |
| for comparisons whose argument is a @code{plus}. |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Looping Patterns |
| @section Defining Looping Instruction Patterns |
| @cindex looping instruction patterns |
| @cindex defining looping instruction patterns |
| |
| Some machines have special jump instructions that can be utilized to |
| make loops more efficient. A common example is the 68000 @samp{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 |
| @samp{dbra}-like instruction and avoids pipeline stalls associated with |
| the jump. |
| |
| GCC has three special named patterns to support low overhead looping. |
| They are @samp{decrement_and_branch_until_zero}, @samp{doloop_begin}, |
| and @samp{doloop_end}. The first pattern, |
| @samp{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 |
| @code{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 @code{dbra} instruction: |
| |
| @smallexample |
| @group |
| (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)" |
| "@dots{}") |
| @end group |
| @end smallexample |
| |
| 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 @minus{}1. Note that the following similar |
| pattern will not be matched by the combiner. |
| |
| @smallexample |
| @group |
| (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)" |
| "@dots{}") |
| @end group |
| @end smallexample |
| |
| The other two special looping patterns, @samp{doloop_begin} and |
| @samp{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 @samp{doloop_end} pattern describes the actual looping instruction |
| (or the implicit looping operation) and the @samp{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 @code{doloop} insn is |
| emitted at the end of the loop. The machine dependent reorg pass checks |
| for the presence of this @code{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 |
| @samp{decrement_and_branch_until_zero} and the @samp{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. |
| |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Insn Canonicalizations |
| @section Canonicalization of Instructions |
| @cindex canonicalization of instructions |
| @cindex insn canonicalization |
| |
| 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: |
| |
| @itemize @bullet |
| @item |
| 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. |
| |
| @item |
| For associative operators, a sequence of operators will always chain |
| to the left; for instance, only the left operand of an integer @code{plus} |
| can itself be a @code{plus}. @code{and}, @code{ior}, @code{xor}, |
| @code{plus}, @code{mult}, @code{smin}, @code{smax}, @code{umin}, and |
| @code{umax} are associative when applied to integers, and sometimes to |
| floating-point. |
| |
| @item |
| @cindex @code{neg}, canonicalization of |
| @cindex @code{not}, canonicalization of |
| @cindex @code{mult}, canonicalization of |
| @cindex @code{plus}, canonicalization of |
| @cindex @code{minus}, canonicalization of |
| For these operators, if only one operand is a @code{neg}, @code{not}, |
| @code{mult}, @code{plus}, or @code{minus} expression, it will be the |
| first operand. |
| |
| @item |
| In combinations of @code{neg}, @code{mult}, @code{plus}, and |
| @code{minus}, the @code{neg} operations (if any) will be moved inside |
| the operations as far as possible. For instance, |
| @code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but |
| @code{(plus (mult (neg A) B) C)} is canonicalized as |
| @code{(minus A (mult B C))}. |
| |
| @cindex @code{compare}, canonicalization of |
| @item |
| For the @code{compare} operator, a constant is always the second operand |
| on machines where @code{cc0} is used (@pxref{Jump Patterns}). On other |
| machines, there are rare cases where the compiler might want to construct |
| a @code{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 @code{neg}, @code{not}, @code{mult}, @code{plus}, or |
| @code{minus} is made the first operand under the same conditions as |
| above. |
| |
| @item |
| @code{(ltu (plus @var{a} @var{b}) @var{b})} is converted to |
| @code{(ltu (plus @var{a} @var{b}) @var{a})}. Likewise with @code{geu} instead |
| of @code{ltu}. |
| |
| @item |
| @code{(minus @var{x} (const_int @var{n}))} is converted to |
| @code{(plus @var{x} (const_int @var{-n}))}. |
| |
| @item |
| Within address computations (i.e., inside @code{mem}), a left shift is |
| converted into the appropriate multiplication by a power of two. |
| |
| @cindex @code{ior}, canonicalization of |
| @cindex @code{and}, canonicalization of |
| @cindex De Morgan's law |
| @item |
| 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 @code{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 |
| |
| @smallexample |
| (define_insn "" |
| [(set (match_operand:@var{m} 0 @dots{}) |
| (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) |
| (match_operand:@var{m} 2 @dots{})))] |
| "@dots{}" |
| "@dots{}") |
| @end smallexample |
| |
| @noindent |
| Similarly, a pattern for a ``NAND'' instruction should be written |
| |
| @smallexample |
| (define_insn "" |
| [(set (match_operand:@var{m} 0 @dots{}) |
| (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) |
| (not:@var{m} (match_operand:@var{m} 2 @dots{}))))] |
| "@dots{}" |
| "@dots{}") |
| @end smallexample |
| |
| In both cases, it is not necessary to include patterns for the many |
| logically equivalent RTL expressions. |
| |
| @cindex @code{xor}, canonicalization of |
| @item |
| The only possible RTL expressions involving both bitwise exclusive-or |
| and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})} |
| and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}. |
| |
| @item |
| The sum of three items, one of which is a constant, will only appear in |
| the form |
| |
| @smallexample |
| (plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant}) |
| @end smallexample |
| |
| @item |
| On machines that do not use @code{cc0}, |
| @code{(compare @var{x} (const_int 0))} will be converted to |
| @var{x}. |
| |
| @cindex @code{zero_extract}, canonicalization of |
| @cindex @code{sign_extract}, canonicalization of |
| @item |
| Equality comparisons of a group of bits (usually a single bit) with zero |
| will be written using @code{zero_extract} rather than the equivalent |
| @code{and} or @code{sign_extract} operations. |
| |
| @end itemize |
| |
| Further canonicalization rules are defined in the function |
| @code{commutative_operand_precedence} in @file{gcc/rtlanal.c}. |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Expander Definitions |
| @section Defining RTL Sequences for Code Generation |
| @cindex expander definitions |
| @cindex code generation RTL sequences |
| @cindex 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 |
| @code{define_expand} to specify how to generate the sequence of RTL@. |
| |
| @findex define_expand |
| A @code{define_expand} is an RTL expression that looks almost like a |
| @code{define_insn}; but, unlike the latter, a @code{define_expand} is used |
| only for RTL generation and it can produce more than one RTL insn. |
| |
| A @code{define_expand} RTX has four operands: |
| |
| @itemize @bullet |
| @item |
| The name. Each @code{define_expand} must have a name, since the only |
| use for it is to refer to it by name. |
| |
| @item |
| The RTL template. This is a vector of RTL expressions representing |
| a sequence of separate instructions. Unlike @code{define_insn}, there |
| is no implicit surrounding @code{PARALLEL}. |
| |
| @item |
| 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 @code{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. |
| |
| @item |
| 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 @code{emit_insn}, etc. |
| Any such insns precede the ones that come from the RTL template. |
| @end itemize |
| |
| Every RTL insn emitted by a @code{define_expand} must match some |
| @code{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 @code{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 @code{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 |
| @code{define_expand}. Internal operands are substituted into the RTL |
| template with @code{match_dup}, never with @code{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 |
| @code{operands} so that @code{match_dup} can find them. |
| |
| There are two special macros defined for use in the preparation statements: |
| @code{DONE} and @code{FAIL}. Use them with a following semicolon, |
| as a statement. |
| |
| @table @code |
| |
| @findex DONE |
| @item DONE |
| Use the @code{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 @code{emit_insn} within the |
| preparation statements; the RTL template will not be generated. |
| |
| @findex FAIL |
| @item 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 (@code{extv}, @code{extzv}, and @code{insv}) |
| operations. |
| @end table |
| |
| If the preparation falls through (invokes neither @code{DONE} nor |
| @code{FAIL}), then the @code{define_expand} acts like a |
| @code{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 |
| @code{DONE} or @code{FAIL}, the RTL template may be reduced to a simple |
| list of operands, such as this example: |
| |
| @smallexample |
| @group |
| (define_expand "addsi3" |
| [(match_operand:SI 0 "register_operand" "") |
| (match_operand:SI 1 "register_operand" "") |
| (match_operand:SI 2 "register_operand" "")] |
| @end group |
| @group |
| "" |
| " |
| @{ |
| handle_add (operands[0], operands[1], operands[2]); |
| DONE; |
| @}") |
| @end group |
| @end smallexample |
| |
| Here is an example, the definition of left-shift for the SPUR chip: |
| |
| @smallexample |
| @group |
| (define_expand "ashlsi3" |
| [(set (match_operand:SI 0 "register_operand" "") |
| (ashift:SI |
| @end group |
| @group |
| (match_operand:SI 1 "register_operand" "") |
| (match_operand:SI 2 "nonmemory_operand" "")))] |
| "" |
| " |
| @end group |
| @end smallexample |
| |
| @smallexample |
| @group |
| @{ |
| if (GET_CODE (operands[2]) != CONST_INT |
| || (unsigned) INTVAL (operands[2]) > 3) |
| FAIL; |
| @}") |
| @end group |
| @end smallexample |
| |
| @noindent |
| This example uses @code{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 |
| @code{define_insn} in that case. Here is another case (zero-extension |
| on the 68000) which makes more use of the power of @code{define_expand}: |
| |
| @smallexample |
| (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]);") |
| @end smallexample |
| |
| @noindent |
| @findex make_safe_from |
| 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 @code{make_safe_from} copies the @code{operands[1]} into a |
| temporary register if it refers to @code{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 @code{and}-ing the result |
| against a halfword mask. But this mask cannot be represented by a |
| @code{const_int} because the constant value is too large to be legitimate |
| on this machine. So it must be copied into a register with |
| @code{force_reg} and then the register used in the @code{and}. |
| |
| @smallexample |
| (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)); ") |
| @end smallexample |
| |
| @emph{Note:} If the @code{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{code_label}, |
| @code{barrier} or @code{note}. It must be an @code{insn}, |
| @code{jump_insn} or @code{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. |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Insn Splitting |
| @section Defining How to Split Instructions |
| @cindex insn splitting |
| @cindex instruction splitting |
| @cindex splitting 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 (@pxref{Delay Slots}) or that have instructions whose |
| output is not available for multiple cycles (@pxref{Processor pipeline |
| description}), 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 @code{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. |
| |
| @findex define_split |
| The @code{define_split} definition tells the compiler how to split a |
| complex insn into several simpler insns. It looks like this: |
| |
| @smallexample |
| (define_split |
| [@var{insn-pattern}] |
| "@var{condition}" |
| [@var{new-insn-pattern-1} |
| @var{new-insn-pattern-2} |
| @dots{}] |
| "@var{preparation-statements}") |
| @end smallexample |
| |
| @var{insn-pattern} is a pattern that needs to be split and |
| @var{condition} is the final condition to be tested, as in a |
| @code{define_insn}. When an insn matching @var{insn-pattern} and |
| satisfying @var{condition} is found, it is replaced in the insn list |
| with the insns given by @var{new-insn-pattern-1}, |
| @var{new-insn-pattern-2}, etc. |
| |
| The @var{preparation-statements} are similar to those statements that |
| are specified for @code{define_expand} (@pxref{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 @code{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 @var{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 @code{define_insn} and, if |
| @code{reload_completed} is nonzero, is known to satisfy the constraints |
| of that @code{define_insn}. In that case, the new insn patterns must |
| also be insns that are matched by some @code{define_insn} and, if |
| @code{reload_completed} is nonzero, must also satisfy the constraints |
| of those definitions. |
| |
| As an example of this usage of @code{define_split}, consider the following |
| example from @file{a29k.md}, which splits a @code{sign_extend} from |
| @code{HImode} to @code{SImode} into a pair of shift insns: |
| |
| @smallexample |
| (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]); @}") |
| @end smallexample |
| |
| When the combiner phase tries to split an insn pattern, it is always the |
| case that the pattern is @emph{not} matched by any @code{define_insn}. |
| The combiner pass first tries to split a single @code{set} expression |
| and then the same @code{set} expression inside a @code{parallel}, but |
| followed by a @code{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 |
| @code{define_insn} definitions, so you need not do this test in the |
| @code{define_split} (of course, there is no point in writing a |
| @code{define_split} that will never produce insns that match). |
| |
| Here is an example of this use of @code{define_split}, taken from |
| @file{rs6000.md}: |
| |
| @smallexample |
| (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); |
| @}") |
| @end smallexample |
| |
| Here the predicate @code{non_add_cint_operand} matches any |
| @code{const_int} that is @emph{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: |
| |
| @smallexample |
| (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)))] |
| " |
| @{ |
| /* @r{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); |
| @}") |
| @end smallexample |
| |
| To avoid confusion, don't write a single @code{define_split} that |
| accepts some insns that match some @code{define_insn} as well as some |
| insns that don't. Instead, write two separate @code{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 |
| @code{REG_BR_PROB} note to each conditional jump. A global variable |
| @code{split_branch_probability} holds the probability of the original branch in case |
| it was an simple conditional jump, @minus{}1 otherwise. To simplify |
| recomputing of edge frequencies, the new sequence is required to have only |
| forward jumps to the newly created labels. |
| |
| @findex define_insn_and_split |
| For the common case where the pattern of a define_split exactly matches the |
| pattern of a define_insn, use @code{define_insn_and_split}. It looks like |
| this: |
| |
| @smallexample |
| (define_insn_and_split |
| [@var{insn-pattern}] |
| "@var{condition}" |
| "@var{output-template}" |
| "@var{split-condition}" |
| [@var{new-insn-pattern-1} |
| @var{new-insn-pattern-2} |
| @dots{}] |
| "@var{preparation-statements}" |
| [@var{insn-attributes}]) |
| |
| @end smallexample |
| |
| @var{insn-pattern}, @var{condition}, @var{output-template}, and |
| @var{insn-attributes} are used as in @code{define_insn}. The |
| @var{new-insn-pattern} vector and the @var{preparation-statements} are used as |
| in a @code{define_split}. The @var{split-condition} is also used as in |
| @code{define_split}, with the additional behavior that if the condition starts |
| with @samp{&&}, 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: |
| |
| @smallexample |
| (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")]) |
| |
| @end smallexample |
| |
| In this case, the actual split condition will be |
| @samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}. |
| |
| The @code{define_insn_and_split} construction provides exactly the same |
| functionality as two separate @code{define_insn} and @code{define_split} |
| patterns. It exists for compactness, and as a maintenance tool to prevent |
| having to ensure the two patterns' templates match. |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Including Patterns |
| @section Including Patterns in Machine Descriptions. |
| @cindex insn includes |
| |
| @findex include |
| The @code{include} pattern tells the compiler tools where to |
| look for patterns that are in files other than in the file |
| @file{.md}. This is used only at build time and there is no preprocessing allowed. |
| |
| It looks like: |
| |
| @smallexample |
| |
| (include |
| @var{pathname}) |
| @end smallexample |
| |
| For example: |
| |
| @smallexample |
| |
| (include "filestuff") |
| |
| @end smallexample |
| |
| Where @var{pathname} is a string that specifies the location of the file, |
| specifies the include file to be in @file{gcc/config/target/filestuff}. The |
| directory @file{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: |
| |
| @smallexample |
| |
| (include "BOGUS/filestuff") |
| |
| @end smallexample |
| |
| the include file is specified to be in @file{gcc/config/@var{target}/BOGUS/filestuff}. |
| |
| Specifying an absolute path for the include file such as; |
| @smallexample |
| |
| (include "/u2/BOGUS/filestuff") |
| |
| @end smallexample |
| is permitted but is not encouraged. |
| |
| @subsection RTL Generation Tool Options for Directory Search |
| @cindex directory options .md |
| @cindex options, directory search |
| @cindex search options |
| |
| The @option{-I@var{dir}} option specifies directories to search for machine descriptions. |
| For example: |
| |
| @smallexample |
| |
| genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md |
| |
| @end smallexample |
| |
| |
| Add the directory @var{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 @option{-I} option, the directories are scanned in left-to-right |
| order; the standard default directory come after. |
| |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Peephole Definitions |
| @section Machine-Specific Peephole Optimizers |
| @cindex peephole optimizer definitions |
| @cindex defining peephole optimizers |
| |
| In addition to instruction patterns the @file{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. |
| |
| There are two forms of peephole definitions that may be used. The |
| original @code{define_peephole} is run at assembly output time to |
| match insns and substitute assembly text. Use of @code{define_peephole} |
| is deprecated. |
| |
| A newer @code{define_peephole2} matches insns and substitutes new |
| insns. The @code{peephole2} pass is run after register allocation |
| but before scheduling, which may result in much better code for |
| targets that do scheduling. |
| |
| @menu |
| * define_peephole:: RTL to Text Peephole Optimizers |
| * define_peephole2:: RTL to RTL Peephole Optimizers |
| @end menu |
| |
| @end ifset |
| @ifset INTERNALS |
| @node define_peephole |
| @subsection RTL to Text Peephole Optimizers |
| @findex define_peephole |
| |
| @need 1000 |
| A definition looks like this: |
| |
| @smallexample |
| (define_peephole |
| [@var{insn-pattern-1} |
| @var{insn-pattern-2} |
| @dots{}] |
| "@var{condition}" |
| "@var{template}" |
| "@var{optional-insn-attributes}") |
| @end smallexample |
| |
| @noindent |
| 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 @code{define_insn}. |
| |
| In this skeleton, @var{insn-pattern-1} and so on are patterns to match |
| consecutive insns. The optimization applies to a sequence of insns when |
| @var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches |
| the next, and so on. |
| |
| Each of the insns matched by a peephole must also match a |
| @code{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 @code{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 @code{match_operands}, |
| @code{match_operator}, and @code{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 @code{match_operand} in one insn and @code{match_dup} in the |
| other. |
| |
| The operand constraints used in @code{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 @var{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 |
| @var{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. |
| |
| @findex prev_active_insn |
| The way to refer to the operands in @var{condition} is to write |
| @code{operands[@var{i}]} for operand number @var{i} (as matched by |
| @code{(match_operand @var{i} @dots{})}). Use the variable @code{insn} |
| to refer to the last of the insns being matched; use |
| @code{prev_active_insn} to find the preceding insns. |
| |
| @findex dead_or_set_p |
| When optimizing computations with intermediate results, you can use |
| @var{condition} to match only when the intermediate results are not used |
| elsewhere. Use the C expression @code{dead_or_set_p (@var{insn}, |
| @var{op})}, where @var{insn} is the insn in which you expect the value |
| to be used for the last time (from the value of @code{insn}, together |
| with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate |
| value (from @code{operands[@var{i}]}). |
| |
| Applying the optimization means replacing the sequence of insns with one |
| new insn. The @var{template} controls ultimate output of assembler code |
| for this combined insn. It works exactly like the template of a |
| @code{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: |
| |
| @smallexample |
| (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 |
| @}) |
| @end smallexample |
| |
| @need 1000 |
| The effect of this optimization is to change |
| |
| @smallexample |
| @group |
| jbsr _foobar |
| addql #4,sp |
| movel d1,sp@@- |
| movel d0,sp@@- |
| fmoved sp@@+,fp0 |
| @end group |
| @end smallexample |
| |
| @noindent |
| into |
| |
| @smallexample |
| @group |
| jbsr _foobar |
| movel d1,sp@@ |
| movel d0,sp@@- |
| fmoved sp@@+,fp0 |
| @end group |
| @end smallexample |
| |
| @ignore |
| @findex CC_REVERSED |
| If a peephole matches a sequence including one or more jump insns, you must |
| take account of the flags such as @code{CC_REVERSED} which specify that the |
| condition codes are represented in an unusual manner. The compiler |
| automatically alters any ordinary conditional jumps which occur in such |
| situations, but the compiler cannot alter jumps which have been replaced by |
| peephole optimizations. So it is up to you to alter the assembler code |
| that the peephole produces. Supply C code to write the assembler output, |
| and in this C code check the condition code status flags and change the |
| assembler code as appropriate. |
| @end ignore |
| |
| @var{insn-pattern-1} and so on look @emph{almost} like the second |
| operand of @code{define_insn}. There is one important difference: the |
| second operand of @code{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 @code{define_peephole}. But |
| when there are multiple actions in a @code{define_insn}, they are |
| implicitly enclosed in a @code{parallel}. Then you must explicitly |
| write the @code{parallel}, and the square brackets within it, in the |
| @code{define_peephole}. Thus, if an insn pattern looks like this, |
| |
| @smallexample |
| (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") |
| @end smallexample |
| |
| @noindent |
| then the way to mention this insn in a peephole is as follows: |
| |
| @smallexample |
| (define_peephole |
| [@dots{} |
| (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)))]) |
| @dots{}] |
| @dots{}) |
| @end smallexample |
| |
| @end ifset |
| @ifset INTERNALS |
| @node define_peephole2 |
| @subsection RTL to RTL Peephole Optimizers |
| @findex define_peephole2 |
| |
| The @code{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. |
| |
| @smallexample |
| (define_peephole2 |
| [@var{insn-pattern-1} |
| @var{insn-pattern-2} |
| @dots{}] |
| "@var{condition}" |
| [@var{new-insn-pattern-1} |
| @var{new-insn-pattern-2} |
| @dots{}] |
| "@var{preparation-statements}") |
| @end smallexample |
| |
| The definition is almost identical to @code{define_split} |
| (@pxref{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. |
| |
| @findex match_scratch |
| @findex match_dup |
| Scratch registers are requested with a @code{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 @code{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: |
| |
| @smallexample |
| (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))])] |
| "") |
| @end smallexample |
| |
| @noindent |
| 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 |
| @code{SImode} register of class @code{GENERAL_REGS} (@code{"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: |
| |
| @smallexample |
| (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))] |
| "/* @r{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))] |
| "") |
| @end smallexample |
| |
| @noindent |
| If we had not added the @code{(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 @code{set}. |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Insn Attributes |
| @section Instruction Attributes |
| @cindex insn attributes |
| @cindex instruction attributes |
| |
| In addition to describing the instruction supported by the target machine, |
| the @file{md} file also defines a group of @dfn{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 @code{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. |
| * Processor pipeline description:: Specifying information for insn scheduling. |
| @end menu |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Defining Attributes |
| @subsection Defining Attributes and their Values |
| @cindex defining attributes and their values |
| @cindex attributes, defining |
| |
| @findex define_attr |
| The @code{define_attr} expression is used to define each attribute required |
| by the target machine. It looks like: |
| |
| @smallexample |
| (define_attr @var{name} @var{list-of-values} @var{default}) |
| @end smallexample |
| |
| @var{name} is a string specifying the name of the attribute being defined. |
| |
| @var{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. |
| |
| @var{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. @xref{Attr Example}, for more |
| information on the handling of defaults. @xref{Constant Attributes}, |
| for information on attributes that do not depend on any particular insn. |
| |
| @findex insn-attr.h |
| For each defined attribute, a number of definitions are written to the |
| @file{insn-attr.h} file. For cases where an explicit set of values is |
| specified for an attribute, the following are defined: |
| |
| @itemize @bullet |
| @item |
| A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}. |
| |
| @item |
| An enumerated class is defined for @samp{attr_@var{name}} with |
| elements of the form @samp{@var{upper-name}_@var{upper-value}} where |
| the attribute name and value are first converted to uppercase. |
| |
| @item |
| A function @samp{get_attr_@var{name}} is defined that is passed an insn and |
| returns the attribute value for that insn. |
| @end itemize |
| |
| For example, if the following is present in the @file{md} file: |
| |
| @smallexample |
| (define_attr "type" "branch,fp,load,store,arith" @dots{}) |
| @end smallexample |
| |
| @noindent |
| the following lines will be written to the file @file{insn-attr.h}. |
| |
| @smallexample |
| #define HAVE_ATTR_type |
| enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD, |
| TYPE_STORE, TYPE_ARITH@}; |
| extern enum attr_type get_attr_type (); |
| @end smallexample |
| |
| If the attribute takes numeric values, no @code{enum} type will be |
| defined and the function to obtain the attribute's value will return |
| @code{int}. |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Expressions |
| @subsection Attribute Expressions |
| @cindex 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: |
| |
| @table @code |
| @cindex @code{const_int} and attributes |
| @item (const_int @var{i}) |
| The integer @var{i} specifies the value of a numeric attribute. @var{i} |
| must be non-negative. |
| |
| The value of a numeric attribute can be specified either with a |
| @code{const_int}, or as an integer represented as a string in |
| @code{const_string}, @code{eq_attr} (see below), @code{attr}, |
| @code{symbol_ref}, simple arithmetic expressions, and @code{set_attr} |
| overrides on specific instructions (@pxref{Tagging Insns}). |
| |
| @cindex @code{const_string} and attributes |
| @item (const_string @var{value}) |
| The string @var{value} specifies a constant attribute value. |
| If @var{value} is specified as @samp{"*"}, it means that the default value of |
| the attribute is to be used for the insn containing this expression. |
| @samp{"*"} obviously cannot be used in the @var{default} expression |
| of a @code{define_attr}. |
| |
| If the attribute whose value is being specified is numeric, @var{value} |
| must be a string containing a non-negative integer (normally |
| @code{const_int} would be used in this case). Otherwise, it must |
| contain one of the valid values for the attribute. |
| |
| @cindex @code{if_then_else} and attributes |
| @item (if_then_else @var{test} @var{true-value} @var{false-value}) |
| @var{test} specifies an attribute test, whose format is defined below. |
| The value of this expression is @var{true-value} if @var{test} is true, |
| otherwise it is @var{false-value}. |
| |
| @cindex @code{cond} and attributes |
| @item (cond [@var{test1} @var{value1} @dots{}] @var{default}) |
| The first operand of this expression is a vector containing an even |
| number of expressions and consisting of pairs of @var{test} and @var{value} |
| expressions. The value of the @code{cond} expression is that of the |
| @var{value} corresponding to the first true @var{test} expression. If |
| none of the @var{test} expressions are true, the value of the @code{cond} |
| expression is that of the @var{default} expression. |
| @end table |
| |
| @var{test} expressions can have one of the following forms: |
| |
| @table @code |
| @cindex @code{const_int} and attribute tests |
| @item (const_int @var{i}) |
| This test is true if @var{i} is nonzero and false otherwise. |
| |
| @cindex @code{not} and attributes |
| @cindex @code{ior} and attributes |
| @cindex @code{and} and attributes |
| @item (not @var{test}) |
| @itemx (ior @var{test1} @var{test2}) |
| @itemx (and @var{test1} @var{test2}) |
| These tests are true if the indicated logical function is true. |
| |
| @cindex @code{match_operand} and attributes |
| @item (match_operand:@var{m} @var{n} @var{pred} @var{constraints}) |
| This test is true if operand @var{n} of the insn whose attribute value |
| is being determined has mode @var{m} (this part of the test is ignored |
| if @var{m} is @code{VOIDmode}) and the function specified by the string |
| @var{pred} returns a nonzero value when passed operand @var{n} and mode |
| @var{m} (this part of the test is ignored if @var{pred} is the null |
| string). |
| |
| The @var{constraints} operand is ignored and should be the null string. |
| |
| @cindex @code{le} and attributes |
| @cindex @code{leu} and attributes |
| @cindex @code{lt} and attributes |
| @cindex @code{gt} and attributes |
| @cindex @code{gtu} and attributes |
| @cindex @code{ge} and attributes |
| @cindex @code{geu} and attributes |
| @cindex @code{ne} and attributes |
| @cindex @code{eq} and attributes |
| @cindex @code{plus} and attributes |
| @cindex @code{minus} and attributes |
| @cindex @code{mult} and attributes |
| @cindex @code{div} and attributes |
| @cindex @code{mod} and attributes |
| @cindex @code{abs} and attributes |
| @cindex @code{neg} and attributes |
| @cindex @code{ashift} and attributes |
| @cindex @code{lshiftrt} and attributes |
| @cindex @code{ashiftrt} and attributes |
| @item (le @var{arith1} @var{arith2}) |
| @itemx (leu @var{arith1} @var{arith2}) |
| @itemx (lt @var{arith1} @var{arith2}) |
| @itemx (ltu @var{arith1} @var{arith2}) |
| @itemx (gt @var{arith1} @var{arith2}) |
| @itemx (gtu @var{arith1} @var{arith2}) |
| @itemx (ge @var{arith1} @var{arith2}) |
| @itemx (geu @var{arith1} @var{arith2}) |
| @itemx (ne @var{arith1} @var{arith2}) |
| @itemx (eq @var{arith1} @var{arith2}) |
| These tests are true if the indicated comparison of the two arithmetic |
| expressions is true. Arithmetic expressions are formed with |
| @code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod}, |
| @code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not}, |
| @code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions. |
| |
| @findex get_attr |
| @code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn |
| Lengths},for additional forms). @code{symbol_ref} is a string |
| denoting a C expression that yields an @code{int} when evaluated by the |
| @samp{get_attr_@dots{}} routine. It should normally be a global |
| variable. |
| |
| @findex eq_attr |
| @item (eq_attr @var{name} @var{value}) |
| @var{name} is a string specifying the name of an attribute. |
| |
| @var{value} is a string that is either a valid value for attribute |
| @var{name}, a comma-separated list of values, or @samp{!} followed by a |
| value or list. If @var{value} does not begin with a @samp{!}, this |
| test is true if the value of the @var{name} attribute of the current |
| insn is in the list specified by @var{value}. If @var{value} begins |
| with a @samp{!}, this test is true if the attribute's value is |
| @emph{not} in the specified list. |
| |
| For example, |
| |
| @smallexample |
| (eq_attr "type" "load,store") |
| @end smallexample |
| |
| @noindent |
| is equivalent to |
| |
| @smallexample |
| (ior (eq_attr "type" "load") (eq_attr "type" "store")) |
| @end smallexample |
| |
| If @var{name} specifies an attribute of @samp{alternative}, it refers to the |
| value of the compiler variable @code{which_alternative} |
| (@pxref{Output Statement}) and the values must be small integers. For |
| example, |
| |
| @smallexample |
| (eq_attr "alternative" "2,3") |
| @end smallexample |
| |
| @noindent |
| is equivalent to |
| |
| @smallexample |
| (ior (eq (symbol_ref "which_alternative") (const_int 2)) |
| (eq (symbol_ref "which_alternative") (const_int 3))) |
| @end smallexample |
| |
| Note that, for most attributes, an @code{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. |
| |
| @findex attr_flag |
| @item (attr_flag @var{name}) |
| The value of an @code{attr_flag} expression is true if the flag |
| specified by @var{name} is true for the @code{insn} currently being |
| scheduled. |
| |
| @var{name} is a string specifying one of a fixed set of flags to test. |
| Test the flags @code{forward} and @code{backward} to determine the |
| direction of a conditional branch. Test the flags @code{very_likely}, |
| @code{likely}, @code{very_unlikely}, and @code{unlikely} to determine |
| if a conditional branch is expected to be taken. |
| |
| If the @code{very_likely} flag is true, then the @code{likely} flag is also |
| true. Likewise for the @code{very_unlikely} and @code{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). |
| |
| @smallexample |
| (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"))]) |
| @end smallexample |
| |
| The @code{forward} and @code{backward} flags are false if the current |
| @code{insn} being scheduled is not a conditional branch. |
| |
| The @code{very_likely} and @code{likely} flags are true if the |
| @code{insn} being scheduled is not a conditional branch. |
| The @code{very_unlikely} and @code{unlikely} flags are false if the |
| @code{insn} being scheduled is not a conditional branch. |
| |
| @code{attr_flag} is only used during delay slot scheduling and has no |
| meaning to other passes of the compiler. |
| |
| @findex attr |
| @item (attr @var{name}) |
| The value of another attribute is returned. This is most useful |
| for numeric attributes, as @code{eq_attr} and @code{attr_flag} |
| produce more efficient code for non-numeric attributes. |
| @end table |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Tagging Insns |
| @subsection Assigning Attribute Values to Insns |
| @cindex tagging insns |
| @cindex 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 @code{define_peephole} |
| generated it). Every @code{define_insn} and @code{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 |
| @code{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 @code{define_insn} and |
| @code{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 @code{set} expression whose first operand is an |
| @code{attr} expression giving the name of the attribute being set. The |
| second operand of the @code{set} is an attribute expression |
| (@pxref{Expressions}) giving the value of the attribute. |
| |
| When the attribute value depends on the @samp{alternative} attribute |
| (i.e., which is the applicable alternative in the constraint of the |
| insn), the @code{set_attr_alternative} expression can be used. It |
| allows the specification of a vector of attribute expressions, one for |
| each alternative. |
| |
| @findex set_attr |
| When the generality of arbitrary attribute expressions is not required, |
| the simpler @code{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, |
| @var{name} is a string specifying the attribute to be set. |
| |
| @table @code |
| @item (set_attr @var{name} @var{value-string}) |
| @var{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 @samp{*} for some alternative, in |
| which case the attribute will assume its default value for insns matching |
| that alternative. |
| |
| @findex set_attr_alternative |
| @item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}]) |
| Depending on the alternative of the insn, the value will be one of the |
| specified values. This is a shorthand for using a @code{cond} with |
| tests on the @samp{alternative} attribute. |
| |
| @findex attr |
| @item (set (attr @var{name}) @var{value}) |
| The first operand of this @code{set} must be the special RTL expression |
| @code{attr}, whose sole operand is a string giving the name of the |
| attribute being set. @var{value} is the value of the attribute. |
| @end table |
| |
| The following shows three different ways of representing the same |
| attribute value specification: |
| |
| @smallexample |
| (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"))) |
| @end smallexample |
| |
| @need 1000 |
| @findex define_asm_attributes |
| The @code{define_asm_attributes} expression provides a mechanism to |
| specify the attributes assigned to insns produced from an @code{asm} |
| statement. It has the form: |
| |
| @smallexample |
| (define_asm_attributes [@var{attr-sets}]) |
| @end smallexample |
| |
| @noindent |
| where @var{attr-sets} is specified the same as for both the |
| @code{define_insn} and the @code{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 @code{length} attribute is handled specially. The |
| way to compute the length of an @code{asm} insn is to multiply the |
| length specified in the expression @code{define_asm_attributes} by the |
| number of machine instructions specified in the @code{asm} statement, |
| determined by counting the number of semicolons and newlines in the |
| string. Therefore, the value of the @code{length} attribute specified |
| in a @code{define_asm_attributes} should be the maximum possible length |
| of a single machine instruction. |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Attr Example |
| @subsection Example of Attribute Specifications |
| @cindex attribute specifications example |
| @cindex attribute specifications |
| |
| The judicious use of defaulting is important in the efficient use of |
| insn attributes. Typically, insns are divided into @dfn{types} and an |
| attribute, customarily called @code{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 @file{md} file for such a machine: |
| |
| @smallexample |
| (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")]) |
| @end smallexample |
| |
| 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. |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Insn Lengths |
| @subsection Computing the Length of an Insn |
| @cindex insn lengths, computing |
| @cindex 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 @code{length} |
| attribute, is defined. This attribute must be defined to have numeric |
| values by specifying a null string in its @code{define_attr}. |
| |
| In the case of the @code{length} attribute, two additional forms of |
| arithmetic terms are allowed in test expressions: |
| |
| @table @code |
| @cindex @code{match_dup} and attributes |
| @item (match_dup @var{n}) |
| This refers to the address of operand @var{n} of the current insn, which |
| must be a @code{label_ref}. |
| |
| @cindex @code{pc} and attributes |
| @item (pc) |
| This refers to the address of the @emph{current} insn. It might have |
| been more consistent with other usage to make this the address of the |
| @emph{next} insn but this would be confusing because the length of the |
| current insn is to be computed. |
| @end table |
| |
| @cindex @code{addr_vec}, length of |
| @cindex @code{addr_diff_vec}, length of |
| For normal insns, the length will be determined by value of the |
| @code{length} attribute. In the case of @code{addr_vec} and |
| @code{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: |
| |
| @table @code |
| @findex ADJUST_INSN_LENGTH |
| @item ADJUST_INSN_LENGTH (@var{insn}, @var{length}) |
| If defined, modifies the length assigned to instruction @var{insn} as a |
| function of the context in which it is used. @var{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 @code{addr_vec} |
| insn must be increased by two to compensate for the fact that alignment |
| may be required. |
| @end table |
| |
| @findex get_attr_length |
| The routine that returns @code{get_attr_length} (the value of the |
| @code{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: |
| |
| @smallexample |
| (define_insn "jump" |
| [(set (pc) |
| (label_ref (match_operand 0 "" "")))] |
| "" |
| @{ |
| return (get_attr_length (insn) == 4 |
| ? "b %l0" : "l r15,=a(%l0); br r15"); |
| @} |
| [(set (attr "length") |
| (if_then_else (lt (match_dup 0) (const_int 4096)) |
| (const_int 4) |
| (const_int 6)))]) |
| @end smallexample |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Constant Attributes |
| @subsection Constant Attributes |
| @cindex constant attributes |
| |
| A special form of @code{define_attr}, where the expression for the |
| default value is a @code{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, |
| |
| @smallexample |
| (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")))) |
| @end smallexample |
| |
| 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 @code{symbol_ref} form, |
| but may not use either the @code{match_operand} form or @code{eq_attr} |
| forms involving insn attributes. |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Delay Slots |
| @subsection Delay Slot Scheduling |
| @cindex delay slots, defining |
| |
| 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 @dfn{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 |
| @dfn{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. |
| |
| @findex define_delay |
| The requirement of an insn needing one or more delay slots is indicated |
| via the @code{define_delay} expression. It has the following form: |
| |
| @smallexample |
| (define_delay @var{test} |
| [@var{delay-1} @var{annul-true-1} @var{annul-false-1} |
| @var{delay-2} @var{annul-true-2} @var{annul-false-2} |
| @dots{}]) |
| @end smallexample |
| |
| @var{test} is an attribute test that indicates whether this |
| @code{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 @var{n} must |
| satisfy attribute test @var{delay-n}. @var{annul-true-n} is an |
| attribute test that specifies which insns may be annulled if the branch |
| is true. Similarly, @var{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, @code{(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 @file{md} file: |
| |
| @smallexample |
| (define_delay (eq_attr "type" "branch,call") |
| [(eq_attr "type" "!branch,call") (nil) (nil)]) |
| @end smallexample |
| |
| Multiple @code{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 @code{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: |
| |
| @smallexample |
| (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)]) |
| @end smallexample |
| @c the above is *still* too long. --mew 4feb93 |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Processor pipeline description |
| @subsection Specifying processor pipeline description |
| @cindex processor pipeline description |
| @cindex processor functional units |
| @cindex instruction latency time |
| @cindex interlock delays |
| @cindex data dependence delays |
| @cindex reservation delays |
| @cindex pipeline hazard recognizer |
| @cindex automaton based pipeline description |
| @cindex regular expressions |
| @cindex deterministic finite state automaton |
| @cindex automaton based scheduler |
| @cindex RISC |
| @cindex VLIW |
| |
| To achieve better performance, most modern processors |
| (super-pipelined, superscalar @acronym{RISC}, and @acronym{VLIW} |
| processors) have many @dfn{functional units} on which several |
| instructions can be executed simultaneously. An instruction starts |
| execution if its issue conditions are satisfied. If not, the |
| instruction is stalled until its conditions are satisfied. Such |
| @dfn{interlock (pipeline) delay} causes interruption of the fetching |
| of successor instructions (or demands nop instructions, e.g.@: for some |
| MIPS processors). |
| |
| There are two major kinds of interlock delays in modern processors. |
| The first one is a data dependence delay determining @dfn{instruction |
| latency time}. The instruction execution is not started until all |
| source data have been evaluated by prior instructions (there are more |
| complex cases when the instruction execution starts even when the data |
| are not available but will be ready in given time after the |
| instruction execution start). Taking the data dependence delays into |
| account is simple. The data dependence (true, output, and |
| anti-dependence) delay between two instructions is given by a |
| constant. In most cases this approach is adequate. The second kind |
| of interlock delays is a reservation delay. The reservation delay |
| means that two instructions under execution will be in need of shared |
| processors resources, i.e.@: buses, internal registers, and/or |
| functional units, which are reserved for some time. Taking this kind |
| of delay into account is complex especially for modern @acronym{RISC} |
| processors. |
| |
| The task of exploiting more processor parallelism is solved by an |
| instruction scheduler. For a better solution to this problem, the |
| instruction scheduler has to have an adequate description of the |
| processor parallelism (or @dfn{pipeline description}). GCC |
| machine descriptions describe processor parallelism and functional |
| unit reservations for groups of instructions with the aid of |
| @dfn{regular expressions}. |
| |
| The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to |
| figure out the possibility of the instruction issue by the processor |
| on a given simulated processor cycle. The pipeline hazard recognizer is |
| automatically generated from the processor pipeline description. The |
| pipeline hazard recognizer generated from the machine description |
| is based on a deterministic finite state automaton (@acronym{DFA}): |
| the instruction issue is possible if there is a transition from one |
| automaton state to another one. This algorithm is very fast, and |
| furthermore, its speed is not dependent on processor |
| complexity@footnote{However, the size of the automaton depends on |
| processor complexity. To limit this effect, machine descriptions |
| can split orthogonal parts of the machine description among several |
| automata: but then, since each of these must be stepped independently, |
| this does cause a small decrease in the algorithm's performance.}. |
| |
| @cindex automaton based pipeline description |
| The rest of this section describes the directives that constitute |
| an automaton-based processor pipeline description. The order of |
| these constructions within the machine description file is not |
| important. |
| |
| @findex define_automaton |
| @cindex pipeline hazard recognizer |
| The following optional construction describes names of automata |
| generated and used for the pipeline hazards recognition. Sometimes |
| the generated finite state automaton used by the pipeline hazard |
| recognizer is large. If we use more than one automaton and bind functional |
| units to the automata, the total size of the automata is usually |
| less than the size of the single automaton. If there is no one such |
| construction, only one finite state automaton is generated. |
| |
| @smallexample |
| (define_automaton @var{automata-names}) |
| @end smallexample |
| |
| @var{automata-names} is a string giving names of the automata. The |
| names are separated by commas. All the automata should have unique names. |
| The automaton name is used in the constructions @code{define_cpu_unit} and |
| @code{define_query_cpu_unit}. |
| |
| @findex define_cpu_unit |
| @cindex processor functional units |
| Each processor functional unit used in the description of instruction |
| reservations should be described by the following construction. |
| |
| @smallexample |
| (define_cpu_unit @var{unit-names} [@var{automaton-name}]) |
| @end smallexample |
| |
| @var{unit-names} is a string giving the names of the functional units |
| separated by commas. Don't use name @samp{nothing}, it is reserved |
| for other goals. |
| |
| @var{automaton-name} is a string giving the name of the automaton with |
| which the unit is bound. The automaton should be described in |
| construction @code{define_automaton}. You should give |
| @dfn{automaton-name}, if there is a defined automaton. |
| |
| The assignment of units to automata are constrained by the uses of the |
| units in insn reservations. The most important constraint is: if a |
| unit reservation is present on a particular cycle of an alternative |
| for an insn reservation, then some unit from the same automaton must |
| be present on the same cycle for the other alternatives of the insn |
| reservation. The rest of the constraints are mentioned in the |
| description of the subsequent constructions. |
| |
| @findex define_query_cpu_unit |
| @cindex querying function unit reservations |
| The following construction describes CPU functional units analogously |
| to @code{define_cpu_unit}. The reservation of such units can be |
| queried for an automaton state. The instruction scheduler never |
| queries reservation of functional units for given automaton state. So |
| as a rule, you don't need this construction. This construction could |
| be used for future code generation goals (e.g.@: to generate |
| @acronym{VLIW} insn templates). |
| |
| @smallexample |
| (define_query_cpu_unit @var{unit-names} [@var{automaton-name}]) |
| @end smallexample |
| |
| @var{unit-names} is a string giving names of the functional units |
| separated by commas. |
| |
| @var{automaton-name} is a string giving the name of the automaton with |
| which the unit is bound. |
| |
| @findex define_insn_reservation |
| @cindex instruction latency time |
| @cindex regular expressions |
| @cindex data bypass |
| The following construction is the major one to describe pipeline |
| characteristics of an instruction. |
| |
| @smallexample |
| (define_insn_reservation @var{insn-name} @var{default_latency} |
| @var{condition} @var{regexp}) |
| @end smallexample |
| |
| @var{default_latency} is a number giving latency time of the |
| instruction. There is an important difference between the old |
| description and the automaton based pipeline description. The latency |
| time is used for all dependencies when we use the old description. In |
| the automaton based pipeline description, the given latency time is only |
| used for true dependencies. The cost of anti-dependencies is always |
| zero and the cost of output dependencies is the difference between |
| latency times of the producing and consuming insns (if the difference |
| is negative, the cost is considered to be zero). You can always |
| change the default costs for any description by using the target hook |
| @code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}). |
| |
| @var{insn-name} is a string giving the internal name of the insn. The |
| internal names are used in constructions @code{define_bypass} and in |
| the automaton description file generated for debugging. The internal |
| name has nothing in common with the names in @code{define_insn}. It is a |
| good practice to use insn classes described in the processor manual. |
| |
| @var{condition} defines what RTL insns are described by this |
| construction. You should remember that you will be in trouble if |
| @var{condition} for two or more different |
| @code{define_insn_reservation} constructions is TRUE for an insn. In |
| this case what reservation will be used for the insn is not defined. |
| Such cases are not checked during generation of the pipeline hazards |
| recognizer because in general recognizing that two conditions may have |
| the same value is quite difficult (especially if the conditions |
| contain @code{symbol_ref}). It is also not checked during the |
| pipeline hazard recognizer work because it would slow down the |
| recognizer considerably. |
| |
| @var{regexp} is a string describing the reservation of the cpu's functional |
| units by the instruction. The reservations are described by a regular |
| expression according to the following syntax: |
| |
| @smallexample |
| regexp = regexp "," oneof |
| | oneof |
| |
| oneof = oneof "|" allof |
| | allof |
| |
| allof = allof "+" repeat |
| | repeat |
| |
| repeat = element "*" number |
| | element |
| |
| element = cpu_function_unit_name |
| | reservation_name |
| | result_name |
| | "nothing" |
| | "(" regexp ")" |
| @end smallexample |
| |
| @itemize @bullet |
| @item |
| @samp{,} is used for describing the start of the next cycle in |
| the reservation. |
| |
| @item |
| @samp{|} is used for describing a reservation described by the first |
| regular expression @strong{or} a reservation described by the second |
| regular expression @strong{or} etc. |
| |
| @item |
| @samp{+} is used for describing a reservation described by the first |
| regular expression @strong{and} a reservation described by the |
| second regular expression @strong{and} etc. |
| |
| @item |
| @samp{*} is used for convenience and simply means a sequence in which |
| the regular expression are repeated @var{number} times with cycle |
| advancing (see @samp{,}). |
| |
| @item |
| @samp{cpu_function_unit_name} denotes reservation of the named |
| functional unit. |
| |
| @item |
| @samp{reservation_name} --- see description of construction |
| @samp{define_reservation}. |
| |
| @item |
| @samp{nothing} denotes no unit reservations. |
| @end itemize |
| |
| @findex define_reservation |
| Sometimes unit reservations for different insns contain common parts. |
| In such case, you can simplify the pipeline description by describing |
| the common part by the following construction |
| |
| @smallexample |
| (define_reservation @var{reservation-name} @var{regexp}) |
| @end smallexample |
| |
| @var{reservation-name} is a string giving name of @var{regexp}. |
| Functional unit names and reservation names are in the same name |
| space. So the reservation names should be different from the |
| functional unit names and can not be the reserved name @samp{nothing}. |
| |
| @findex define_bypass |
| @cindex instruction latency time |
| @cindex data bypass |
| The following construction is used to describe exceptions in the |
| latency time for given instruction pair. This is so called bypasses. |
| |
| @smallexample |
| (define_bypass @var{number} @var{out_insn_names} @var{in_insn_names} |
| [@var{guard}]) |
| @end smallexample |
| |
| @var{number} defines when the result generated by the instructions |
| given in string @var{out_insn_names} will be ready for the |
| instructions given in string @var{in_insn_names}. The instructions in |
| the string are separated by commas. |
| |
| @var{guard} is an optional string giving the name of a C function which |
| defines an additional guard for the bypass. The function will get the |
| two insns as parameters. If the function returns zero the bypass will |
| be ignored for this case. The additional guard is necessary to |
| recognize complicated bypasses, e.g.@: when the consumer is only an address |
| of insn @samp{store} (not a stored value). |
| |
| @findex exclusion_set |
| @findex presence_set |
| @findex final_presence_set |
| @findex absence_set |
| @findex final_absence_set |
| @cindex VLIW |
| @cindex RISC |
| The following five constructions are usually used to describe |
| @acronym{VLIW} processors, or more precisely, to describe a placement |
| of small instructions into @acronym{VLIW} instruction slots. They |
| can be used for @acronym{RISC} processors, too. |
| |
| @smallexample |
| (exclusion_set @var{unit-names} @var{unit-names}) |
| (presence_set @var{unit-names} @var{patterns}) |
| (final_presence_set @var{unit-names} @var{patterns}) |
| (absence_set @var{unit-names} @var{patterns}) |
| (final_absence_set @var{unit-names} @var{patterns}) |
| @end smallexample |
| |
| @var{unit-names} is a string giving names of functional units |
| separated by commas. |
| |
| @var{patterns} is a string giving patterns of functional units |
| separated by comma. Currently pattern is one unit or units |
| separated by white-spaces. |
| |
| The first construction (@samp{exclusion_set}) means that each |
| functional unit in the first string can not be reserved simultaneously |
| with a unit whose name is in the second string and vice versa. For |
| example, the construction is useful for describing processors |
| (e.g.@: some SPARC processors) with a fully pipelined floating point |
| functional unit which can execute simultaneously only single floating |
| point insns or only double floating point insns. |
| |
| The second construction (@samp{presence_set}) means that each |
| functional unit in the first string can not be reserved unless at |
| least one of pattern of units whose names are in the second string is |
| reserved. This is an asymmetric relation. For example, it is useful |
| for description that @acronym{VLIW} @samp{slot1} is reserved after |
| @samp{slot0} reservation. We could describe it by the following |
| construction |
| |
| @smallexample |
| (presence_set "slot1" "slot0") |
| @end smallexample |
| |
| Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0} |
| reservation. In this case we could write |
| |
| @smallexample |
| (presence_set "slot1" "slot0 b0") |
| @end smallexample |
| |
| The third construction (@samp{final_presence_set}) is analogous to |
| @samp{presence_set}. The difference between them is when checking is |
| done. When an instruction is issued in given automaton state |
| reflecting all current and planned unit reservations, the automaton |
| state is changed. The first state is a source state, the second one |
| is a result state. Checking for @samp{presence_set} is done on the |
| source state reservation, checking for @samp{final_presence_set} is |
| done on the result reservation. This construction is useful to |
| describe a reservation which is actually two subsequent reservations. |
| For example, if we use |
| |
| @smallexample |
| (presence_set "slot1" "slot0") |
| @end smallexample |
| |
| the following insn will be never issued (because @samp{slot1} requires |
| @samp{slot0} which is absent in the source state). |
| |
| @smallexample |
| (define_reservation "insn_and_nop" "slot0 + slot1") |
| @end smallexample |
| |
| but it can be issued if we use analogous @samp{final_presence_set}. |
| |
| The forth construction (@samp{absence_set}) means that each functional |
| unit in the first string can be reserved only if each pattern of units |
| whose names are in the second string is not reserved. This is an |
| asymmetric relation (actually @samp{exclusion_set} is analogous to |
| this one but it is symmetric). For example it might be useful in a |
| @acronym{VLIW} description to say that @samp{slot0} cannot be reserved |
| after either @samp{slot1} or @samp{slot2} have been reserved. This |
| can be described as: |
| |
| @smallexample |
| (absence_set "slot0" "slot1, slot2") |
| @end smallexample |
| |
| Or @samp{slot2} can not be reserved if @samp{slot0} and unit @samp{b0} |
| are reserved or @samp{slot1} and unit @samp{b1} are reserved. In |
| this case we could write |
| |
| @smallexample |
| (absence_set "slot2" "slot0 b0, slot1 b1") |
| @end smallexample |
| |
| All functional units mentioned in a set should belong to the same |
| automaton. |
| |
| The last construction (@samp{final_absence_set}) is analogous to |
| @samp{absence_set} but checking is done on the result (state) |
| reservation. See comments for @samp{final_presence_set}. |
| |
| @findex automata_option |
| @cindex deterministic finite state automaton |
| @cindex nondeterministic finite state automaton |
| @cindex finite state automaton minimization |
| You can control the generator of the pipeline hazard recognizer with |
| the following construction. |
| |
| @smallexample |
| (automata_option @var{options}) |
| @end smallexample |
| |
| @var{options} is a string giving options which affect the generated |
| code. Currently there are the following options: |
| |
| @itemize @bullet |
| @item |
| @dfn{no-minimization} makes no minimization of the automaton. This is |
| only worth to do when we are debugging the description and need to |
| look more accurately at reservations of states. |
| |
| @item |
| @dfn{time} means printing time statistics about the generation of |
| automata. |
| |
| @item |
| @dfn{stats} means printing statistics about the generated automata |
| such as the number of DFA states, NDFA states and arcs. |
| |
| @item |
| @dfn{v} means a generation of the file describing the result automata. |
| The file has suffix @samp{.dfa} and can be used for the description |
| verification and debugging. |
| |
| @item |
| @dfn{w} means a generation of warning instead of error for |
| non-critical errors. |
| |
| @item |
| @dfn{ndfa} makes nondeterministic finite state automata. This affects |
| the treatment of operator @samp{|} in the regular expressions. The |
| usual treatment of the operator is to try the first alternative and, |
| if the reservation is not possible, the second alternative. The |
| nondeterministic treatment means trying all alternatives, some of them |
| may be rejected by reservations in the subsequent insns. |
| |
| @item |
| @dfn{progress} means output of a progress bar showing how many states |
| were generated so far for automaton being processed. This is useful |
| during debugging a @acronym{DFA} description. If you see too many |
| generated states, you could interrupt the generator of the pipeline |
| hazard recognizer and try to figure out a reason for generation of the |
| huge automaton. |
| @end itemize |
| |
| As an example, consider a superscalar @acronym{RISC} machine which can |
| issue three insns (two integer insns and one floating point insn) on |
| the cycle but can finish only two insns. To describe this, we define |
| the following functional units. |
| |
| @smallexample |
| (define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline") |
| (define_cpu_unit "port0, port1") |
| @end smallexample |
| |
| All simple integer insns can be executed in any integer pipeline and |
| their result is ready in two cycles. The simple integer insns are |
| issued into the first pipeline unless it is reserved, otherwise they |
| are issued into the second pipeline. Integer division and |
| multiplication insns can be executed only in the second integer |
| pipeline and their results are ready correspondingly in 8 and 4 |
| cycles. The integer division is not pipelined, i.e.@: the subsequent |
| integer division insn can not be issued until the current division |
| insn finished. Floating point insns are fully pipelined and their |
| results are ready in 3 cycles. Where the result of a floating point |
| insn is used by an integer insn, an additional delay of one cycle is |
| incurred. To describe all of this we could specify |
| |
| @smallexample |
| (define_cpu_unit "div") |
| |
| (define_insn_reservation "simple" 2 (eq_attr "type" "int") |
| "(i0_pipeline | i1_pipeline), (port0 | port1)") |
| |
| (define_insn_reservation "mult" 4 (eq_attr "type" "mult") |
| "i1_pipeline, nothing*2, (port0 | port1)") |
| |
| (define_insn_reservation "div" 8 (eq_attr "type" "div") |
| "i1_pipeline, div*7, div + (port0 | port1)") |
| |
| (define_insn_reservation "float" 3 (eq_attr "type" "float") |
| "f_pipeline, nothing, (port0 | port1)) |
| |
| (define_bypass 4 "float" "simple,mult,div") |
| @end smallexample |
| |
| To simplify the description we could describe the following reservation |
| |
| @smallexample |
| (define_reservation "finish" "port0|port1") |
| @end smallexample |
| |
| and use it in all @code{define_insn_reservation} as in the following |
| construction |
| |
| @smallexample |
| (define_insn_reservation "simple" 2 (eq_attr "type" "int") |
| "(i0_pipeline | i1_pipeline), finish") |
| @end smallexample |
| |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Conditional Execution |
| @section Conditional Execution |
| @cindex conditional execution |
| @cindex predication |
| |
| 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 |
| @file{.md} file. An alternative is the @code{define_cond_exec} template. |
| |
| @findex define_cond_exec |
| @smallexample |
| (define_cond_exec |
| [@var{predicate-pattern}] |
| "@var{condition}" |
| "@var{output-template}") |
| @end smallexample |
| |
| @var{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 @code{match_operator} to match several relational operators |
| at once. Any @code{match_operand} operands must have no more than one |
| alternative. |
| |
| @var{condition} is a C expression that must be true for the generated |
| pattern to match. |
| |
| @findex current_insn_predicate |
| @var{output-template} is a string similar to the @code{define_insn} |
| output template (@pxref{Output Template}), except that the @samp{*} |
| and @samp{@@} 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 |
| @code{current_insn_predicate} that will contain the entire predicate |
| if the current insn is predicated, and will otherwise be @code{NULL}. |
| |
| When @code{define_cond_exec} is used, an implicit reference to |
| the @code{predicable} instruction attribute is made. |
| @xref{Insn Attributes}. This attribute must be boolean (i.e.@: have |
| exactly two elements in its @var{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 @code{define_insn} for which the @code{predicable} |
| attribute is true, a new @code{define_insn} pattern will be |
| generated that matches a predicated version of the instruction. |
| For example, |
| |
| @smallexample |
| (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")))] |
| "@var{test1}" |
| "add %2,%1,%0") |
| |
| (define_cond_exec |
| [(ne (match_operand:CC 0 "register_operand" "c") |
| (const_int 0))] |
| "@var{test2}" |
| "(%0)") |
| @end smallexample |
| |
| @noindent |
| generates a new pattern |
| |
| @smallexample |
| (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"))))] |
| "(@var{test2}) && (@var{test1})" |
| "(%3) add %2,%1,%0") |
| @end smallexample |
| |
| @end ifset |
| @ifset INTERNALS |
| @node Constant Definitions |
| @section Constant Definitions |
| @cindex constant definitions |
| @findex define_constants |
| |
| Using literal constants inside instruction patterns reduces legibility and |
| can be a maintenance problem. |
| |
| To overcome this problem, you may use the @code{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 |
| @code{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 |
| |
| @smallexample |
| (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") |
| @end smallexample |
| |
| You could write: |
| |
| @smallexample |
| (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") |
| @end smallexample |
| |
| The constants that are defined with a define_constant are also output |
| in the insn-codes.h header file as #defines. |
| @end ifset |
| @ifset INTERNALS |
| @node Iterators |
| @section Iterators |
| @cindex iterators in @file{.md} files |
| |
| Ports often need to define similar patterns for more than one machine |
| mode or for more than one rtx code. GCC provides some simple iterator |
| facilities to make this process easier. |
| |
| @menu |
| * Mode Iterators:: Generating variations of patterns for different modes. |
| * Code Iterators:: Doing the same for codes. |
| @end menu |
| |
| @node Mode Iterators |
| @subsection Mode Iterators |
| @cindex mode iterators in @file{.md} files |
| |
| Ports often need to define similar patterns for two or more different modes. |
| For example: |
| |
| @itemize @bullet |
| @item |
| If a processor has hardware support for both single and double |
| floating-point arithmetic, the @code{SFmode} patterns tend to be |
| very similar to the @code{DFmode} ones. |
| |
| @item |
| If a port uses @code{SImode} pointers in one configuration and |
| @code{DImode} pointers in another, it will usually have very similar |
| @code{SImode} and @code{DImode} patterns for manipulating pointers. |
| @end itemize |
| |
| Mode iterators allow several patterns to be instantiated from one |
| @file{.md} file template. They can be used with any type of |
| rtx-based construct, such as a @code{define_insn}, |
| @code{define_split}, or @code{define_peephole2}. |
| |
| @menu |
| * Defining Mode Iterators:: Defining a new mode iterator. |
| * Substitutions:: Combining mode iterators with substitutions |
| * Examples:: Examples |
| @end menu |
| |
| @node Defining Mode Iterators |
| @subsubsection Defining Mode Iterators |
| @findex define_mode_iterator |
| |
| The syntax for defining a mode iterator is: |
| |
| @smallexample |
| (define_mode_iterator @var{name} [(@var{mode1} "@var{cond1}") @dots{} (@var{moden} "@var{condn}")]) |
| @end smallexample |
| |
| This allows subsequent @file{.md} file constructs to use the mode suffix |
| @code{:@var{name}}. Every construct that does so will be expanded |
| @var{n} times, once with every use of @code{:@var{name}} replaced by |
| @code{:@var{mode1}}, once with every use replaced by @code{:@var{mode2}}, |
| and so on. In the expansion for a particular @var{modei}, every |
| C condition will also require that @var{condi} be true. |
| |
| For example: |
| |
| @smallexample |
| (define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")]) |
| @end smallexample |
| |
| defines a new mode suffix @code{:P}. Every construct that uses |
| @code{:P} will be expanded twice, once with every @code{:P} replaced |
| by @code{:SI} and once with every @code{:P} replaced by @code{:DI}. |
| The @code{:SI} version will only apply if @code{Pmode == SImode} and |
| the @code{:DI} version will only apply if @code{Pmode == DImode}. |
| |
| As with other @file{.md} conditions, an empty string is treated |
| as ``always true''. @code{(@var{mode} "")} can also be abbreviated |
| to @code{@var{mode}}. For example: |
| |
| @smallexample |
| (define_mode_iterator GPR [SI (DI "TARGET_64BIT")]) |
| @end smallexample |
| |
| means that the @code{:DI} expansion only applies if @code{TARGET_64BIT} |
| but that the @code{:SI} expansion has no such constraint. |
| |
| Iterators are applied in the order they are defined. This can be |
| significant if two iterators are used in a construct that requires |
| substitutions. @xref{Substitutions}. |
| |
| @node Substitutions |
| @subsubsection Substitution in Mode Iterators |
| @findex define_mode_attr |
| |
| If an @file{.md} file construct uses mode iterators, each version of the |
| construct will often need slightly different strings or modes. For |
| example: |
| |
| @itemize @bullet |
| @item |
| When a @code{define_expand} defines several @code{add@var{m}3} patterns |
| (@pxref{Standard Names}), each expander will need to use the |
| appropriate mode name for @var{m}. |
| |
| @item |
| When a @code{define_insn} defines several instruction patterns, |
| each instruction will often use a different assembler mnemonic. |
| |
| @item |
| When a @code{define_insn} requires operands with different modes, |
| using an iterator for one of the operand modes usually requires a specific |
| mode for the other operand(s). |
| @end itemize |
| |
| GCC supports such variations through a system of ``mode attributes''. |
| There are two standard attributes: @code{mode}, which is the name of |
| the mode in lower case, and @code{MODE}, which is the same thing in |
| upper case. You can define other attributes using: |
| |
| @smallexample |
| (define_mode_attr @var{name} [(@var{mode1} "@var{value1}") @dots{} (@var{moden} "@var{valuen}")]) |
| @end smallexample |
| |
| where @var{name} is the name of the attribute and @var{valuei} |
| is the value associated with @var{modei}. |
| |
| When GCC replaces some @var{:iterator} with @var{:mode}, it will scan |
| each string and mode in the pattern for sequences of the form |
| @code{<@var{iterator}:@var{attr}>}, where @var{attr} is the name of a |
| mode attribute. If the attribute is defined for @var{mode}, the whole |
| @code{<@dots{}>} sequence will be replaced by the appropriate attribute |
| value. |
| |
| For example, suppose an @file{.md} file has: |
| |
| @smallexample |
| (define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")]) |
| (define_mode_attr load [(SI "lw") (DI "ld")]) |
| @end smallexample |
| |
| If one of the patterns that uses @code{:P} contains the string |
| @code{"<P:load>\t%0,%1"}, the @code{SI} version of that pattern |
| will use @code{"lw\t%0,%1"} and the @code{DI} version will use |
| @code{"ld\t%0,%1"}. |
| |
| Here is an example of using an attribute for a mode: |
| |
| @smallexample |
| (define_mode_iterator LONG [SI DI]) |
| (define_mode_attr SHORT [(SI "HI") (DI "SI")]) |
| (define_insn @dots{} |
| (sign_extend:LONG (match_operand:<LONG:SHORT> @dots{})) @dots{}) |
| @end smallexample |
| |
| The @code{@var{iterator}:} prefix may be omitted, in which case the |
| substitution will be attempted for every iterator expansion. |
| |
| @node Examples |
| @subsubsection Mode Iterator Examples |
| |
| Here is an example from the MIPS port. It defines the following |
| modes and attributes (among others): |
| |
| @smallexample |
| (define_mode_iterator GPR [SI (DI "TARGET_64BIT")]) |
| (define_mode_attr d [(SI "") (DI "d")]) |
| @end smallexample |
| |
| and uses the following template to define both @code{subsi3} |
| and @code{subdi3}: |
| |
| @smallexample |
| (define_insn "sub<mode>3" |
| [(set (match_operand:GPR 0 "register_operand" "=d") |
| (minus:GPR (match_operand:GPR 1 "register_operand" "d") |
| (match_operand:GPR 2 "register_operand" "d")))] |
| "" |
| "<d>subu\t%0,%1,%2" |
| [(set_attr "type" "arith") |
| (set_attr "mode" "<MODE>")]) |
| @end smallexample |
| |
| This is exactly equivalent to: |
| |
| @smallexample |
| (define_insn "subsi3" |
| [(set (match_operand:SI 0 "register_operand" "=d") |
| (minus:SI (match_operand:SI 1 "register_operand" "d") |
| (match_operand:SI 2 "register_operand" "d")))] |
| "" |
| "subu\t%0,%1,%2" |
| [(set_attr "type" "arith") |
| (set_attr "mode" "SI")]) |
| |
| (define_insn "subdi3" |
| [(set (match_operand:DI 0 "register_operand" "=d") |
| (minus:DI (match_operand:DI 1 "register_operand" "d") |
| (match_operand:DI 2 "register_operand" "d")))] |
| "" |
| "dsubu\t%0,%1,%2" |
| [(set_attr "type" "arith") |
| (set_attr "mode" "DI")]) |
| @end smallexample |
| |
| @node Code Iterators |
| @subsection Code Iterators |
| @cindex code iterators in @file{.md} files |
| @findex define_code_iterator |
| @findex define_code_attr |
| |
| Code iterators operate in a similar way to mode iterators. @xref{Mode Iterators}. |
| |
| The construct: |
| |
| @smallexample |
| (define_code_iterator @var{name} [(@var{code1} "@var{cond1}") @dots{} (@var{coden} "@var{condn}")]) |
| @end smallexample |
| |
| defines a pseudo rtx code @var{name} that can be instantiated as |
| @var{codei} if condition @var{condi} is true. Each @var{codei} |
| must have the same rtx format. @xref{RTL Classes}. |
| |
| As with mode iterators, each pattern that uses @var{name} will be |
| expanded @var{n} times, once with all uses of @var{name} replaced by |
| @var{code1}, once with all uses replaced by @var{code2}, and so on. |
| @xref{Defining Mode Iterators}. |
| |
| It is possible to define attributes for codes as well as for modes. |
| There are two standard code attributes: @code{code}, the name of the |
| code in lower case, and @code{CODE}, the name of the code in upper case. |
| Other attributes are defined using: |
| |
| @smallexample |
| (define_code_attr @var{name} [(@var{code1} "@var{value1}") @dots{} (@var{coden} "@var{valuen}")]) |
| @end smallexample |
| |
| Here's an example of code iterators in action, taken from the MIPS port: |
| |
| @smallexample |
| (define_code_iterator any_cond [unordered ordered unlt unge uneq ltgt unle ungt |
| eq ne gt ge lt le gtu geu ltu leu]) |
| |
| (define_expand "b<code>" |
| [(set (pc) |
| (if_then_else (any_cond:CC (cc0) |
| (const_int 0)) |
| (label_ref (match_operand 0 "")) |
| (pc)))] |
| "" |
| @{ |
| gen_conditional_branch (operands, <CODE>); |
| DONE; |
| @}) |
| @end smallexample |
| |
| This is equivalent to: |
| |
| @smallexample |
| (define_expand "bunordered" |
| [(set (pc) |
| (if_then_else (unordered:CC (cc0) |
| (const_int 0)) |
| (label_ref (match_operand 0 "")) |
| (pc)))] |
| "" |
| @{ |
| gen_conditional_branch (operands, UNORDERED); |
| DONE; |
| @}) |
| |
| (define_expand "bordered" |
| [(set (pc) |
| (if_then_else (ordered:CC (cc0) |
| (const_int 0)) |
| (label_ref (match_operand 0 "")) |
| (pc)))] |
| "" |
| @{ |
| gen_conditional_branch (operands, ORDERED); |
| DONE; |
| @}) |
| |
| @dots{} |
| @end smallexample |
| |
| @end ifset |