1@c Copyright (C) 1988-2016 Free Software Foundation, Inc. 2@c This is part of the GCC manual. 3@c For copying conditions, see the file gcc.texi. 4 5@ifset INTERNALS 6@node Machine Desc 7@chapter Machine Descriptions 8@cindex machine descriptions 9 10A machine description has two parts: a file of instruction patterns 11(@file{.md} file) and a C header file of macro definitions. 12 13The @file{.md} file for a target machine contains a pattern for each 14instruction that the target machine supports (or at least each instruction 15that is worth telling the compiler about). It may also contain comments. 16A semicolon causes the rest of the line to be a comment, unless the semicolon 17is inside a quoted string. 18 19See the next chapter for information on the C header file. 20 21@menu 22* Overview:: How the machine description is used. 23* Patterns:: How to write instruction patterns. 24* Example:: An explained example of a @code{define_insn} pattern. 25* RTL Template:: The RTL template defines what insns match a pattern. 26* Output Template:: The output template says how to make assembler code 27 from such an insn. 28* Output Statement:: For more generality, write C code to output 29 the assembler code. 30* Predicates:: Controlling what kinds of operands can be used 31 for an insn. 32* Constraints:: Fine-tuning operand selection. 33* Standard Names:: Names mark patterns to use for code generation. 34* Pattern Ordering:: When the order of patterns makes a difference. 35* Dependent Patterns:: Having one pattern may make you need another. 36* Jump Patterns:: Special considerations for patterns for jump insns. 37* Looping Patterns:: How to define patterns for special looping insns. 38* Insn Canonicalizations::Canonicalization of Instructions 39* Expander Definitions::Generating a sequence of several RTL insns 40 for a standard operation. 41* Insn Splitting:: Splitting Instructions into Multiple Instructions. 42* Including Patterns:: Including Patterns in Machine Descriptions. 43* Peephole Definitions::Defining machine-specific peephole optimizations. 44* Insn Attributes:: Specifying the value of attributes for generated insns. 45* Conditional Execution::Generating @code{define_insn} patterns for 46 predication. 47* Define Subst:: Generating @code{define_insn} and @code{define_expand} 48 patterns from other patterns. 49* Constant Definitions::Defining symbolic constants that can be used in the 50 md file. 51* Iterators:: Using iterators to generate patterns from a template. 52@end menu 53 54@node Overview 55@section Overview of How the Machine Description is Used 56 57There are three main conversions that happen in the compiler: 58 59@enumerate 60 61@item 62The front end reads the source code and builds a parse tree. 63 64@item 65The parse tree is used to generate an RTL insn list based on named 66instruction patterns. 67 68@item 69The insn list is matched against the RTL templates to produce assembler 70code. 71 72@end enumerate 73 74For the generate pass, only the names of the insns matter, from either a 75named @code{define_insn} or a @code{define_expand}. The compiler will 76choose the pattern with the right name and apply the operands according 77to the documentation later in this chapter, without regard for the RTL 78template or operand constraints. Note that the names the compiler looks 79for are hard-coded in the compiler---it will ignore unnamed patterns and 80patterns with names it doesn't know about, but if you don't provide a 81named pattern it needs, it will abort. 82 83If a @code{define_insn} is used, the template given is inserted into the 84insn list. If a @code{define_expand} is used, one of three things 85happens, based on the condition logic. The condition logic may manually 86create new insns for the insn list, say via @code{emit_insn()}, and 87invoke @code{DONE}. For certain named patterns, it may invoke @code{FAIL} to tell the 88compiler to use an alternate way of performing that task. If it invokes 89neither @code{DONE} nor @code{FAIL}, the template given in the pattern 90is inserted, as if the @code{define_expand} were a @code{define_insn}. 91 92Once the insn list is generated, various optimization passes convert, 93replace, and rearrange the insns in the insn list. This is where the 94@code{define_split} and @code{define_peephole} patterns get used, for 95example. 96 97Finally, the insn list's RTL is matched up with the RTL templates in the 98@code{define_insn} patterns, and those patterns are used to emit the 99final assembly code. For this purpose, each named @code{define_insn} 100acts like it's unnamed, since the names are ignored. 101 102@node Patterns 103@section Everything about Instruction Patterns 104@cindex patterns 105@cindex instruction patterns 106 107@findex define_insn 108A @code{define_insn} expression is used to define instruction patterns 109to which insns may be matched. A @code{define_insn} expression contains 110an incomplete RTL expression, with pieces to be filled in later, operand 111constraints that restrict how the pieces can be filled in, and an output 112template or C code to generate the assembler output. 113 114A @code{define_insn} is an RTL expression containing four or five operands: 115 116@enumerate 117@item 118An optional name. The presence of a name indicate that this instruction 119pattern can perform a certain standard job for the RTL-generation 120pass of the compiler. This pass knows certain names and will use 121the instruction patterns with those names, if the names are defined 122in the machine description. 123 124The absence of a name is indicated by writing an empty string 125where the name should go. Nameless instruction patterns are never 126used for generating RTL code, but they may permit several simpler insns 127to be combined later on. 128 129Names that are not thus known and used in RTL-generation have no 130effect; they are equivalent to no name at all. 131 132For the purpose of debugging the compiler, you may also specify a 133name beginning with the @samp{*} character. Such a name is used only 134for identifying the instruction in RTL dumps; it is equivalent to having 135a nameless pattern for all other purposes. Names beginning with the 136@samp{*} character are not required to be unique. 137 138@item 139The @dfn{RTL template}: This is a vector of incomplete RTL expressions 140which describe the semantics of the instruction (@pxref{RTL Template}). 141It is incomplete because it may contain @code{match_operand}, 142@code{match_operator}, and @code{match_dup} expressions that stand for 143operands of the instruction. 144 145If the vector has multiple elements, the RTL template is treated as a 146@code{parallel} expression. 147 148@item 149@cindex pattern conditions 150@cindex conditions, in patterns 151The condition: This is a string which contains a C expression. When the 152compiler attempts to match RTL against a pattern, the condition is 153evaluated. If the condition evaluates to @code{true}, the match is 154permitted. The condition may be an empty string, which is treated 155as always @code{true}. 156 157@cindex named patterns and conditions 158For a named pattern, the condition may not depend on the data in the 159insn being matched, but only the target-machine-type flags. The compiler 160needs to test these conditions during initialization in order to learn 161exactly which named instructions are available in a particular run. 162 163@findex operands 164For nameless patterns, the condition is applied only when matching an 165individual insn, and only after the insn has matched the pattern's 166recognition template. The insn's operands may be found in the vector 167@code{operands}. 168 169For an insn where the condition has once matched, it 170cannot later be used to control register allocation by excluding 171certain register or value combinations. 172 173@item 174The @dfn{output template} or @dfn{output statement}: This is either 175a string, or a fragment of C code which returns a string. 176 177When simple substitution isn't general enough, you can specify a piece 178of C code to compute the output. @xref{Output Statement}. 179 180@item 181The @dfn{insn attributes}: This is an optional vector containing the values of 182attributes for insns matching this pattern (@pxref{Insn Attributes}). 183@end enumerate 184 185@node Example 186@section Example of @code{define_insn} 187@cindex @code{define_insn} example 188 189Here is an example of an instruction pattern, taken from the machine 190description for the 68000/68020. 191 192@smallexample 193(define_insn "tstsi" 194 [(set (cc0) 195 (match_operand:SI 0 "general_operand" "rm"))] 196 "" 197 "* 198@{ 199 if (TARGET_68020 || ! ADDRESS_REG_P (operands[0])) 200 return \"tstl %0\"; 201 return \"cmpl #0,%0\"; 202@}") 203@end smallexample 204 205@noindent 206This can also be written using braced strings: 207 208@smallexample 209(define_insn "tstsi" 210 [(set (cc0) 211 (match_operand:SI 0 "general_operand" "rm"))] 212 "" 213@{ 214 if (TARGET_68020 || ! ADDRESS_REG_P (operands[0])) 215 return "tstl %0"; 216 return "cmpl #0,%0"; 217@}) 218@end smallexample 219 220This describes an instruction which sets the condition codes based on the 221value of a general operand. It has no condition, so any insn with an RTL 222description of the form shown may be matched to this pattern. The name 223@samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL 224generation pass that, when it is necessary to test such a value, an insn 225to do so can be constructed using this pattern. 226 227The output control string is a piece of C code which chooses which 228output template to return based on the kind of operand and the specific 229type of CPU for which code is being generated. 230 231@samp{"rm"} is an operand constraint. Its meaning is explained below. 232 233@node RTL Template 234@section RTL Template 235@cindex RTL insn template 236@cindex generating insns 237@cindex insns, generating 238@cindex recognizing insns 239@cindex insns, recognizing 240 241The RTL template is used to define which insns match the particular pattern 242and how to find their operands. For named patterns, the RTL template also 243says how to construct an insn from specified operands. 244 245Construction involves substituting specified operands into a copy of the 246template. Matching involves determining the values that serve as the 247operands in the insn being matched. Both of these activities are 248controlled by special expression types that direct matching and 249substitution of the operands. 250 251@table @code 252@findex match_operand 253@item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint}) 254This expression is a placeholder for operand number @var{n} of 255the insn. When constructing an insn, operand number @var{n} 256will be substituted at this point. When matching an insn, whatever 257appears at this position in the insn will be taken as operand 258number @var{n}; but it must satisfy @var{predicate} or this instruction 259pattern will not match at all. 260 261Operand numbers must be chosen consecutively counting from zero in 262each instruction pattern. There may be only one @code{match_operand} 263expression in the pattern for each operand number. Usually operands 264are numbered in the order of appearance in @code{match_operand} 265expressions. In the case of a @code{define_expand}, any operand numbers 266used only in @code{match_dup} expressions have higher values than all 267other operand numbers. 268 269@var{predicate} is a string that is the name of a function that 270accepts two arguments, an expression and a machine mode. 271@xref{Predicates}. During matching, the function will be called with 272the putative operand as the expression and @var{m} as the mode 273argument (if @var{m} is not specified, @code{VOIDmode} will be used, 274which normally causes @var{predicate} to accept any mode). If it 275returns zero, this instruction pattern fails to match. 276@var{predicate} may be an empty string; then it means no test is to be 277done on the operand, so anything which occurs in this position is 278valid. 279 280Most of the time, @var{predicate} will reject modes other than @var{m}---but 281not always. For example, the predicate @code{address_operand} uses 282@var{m} as the mode of memory ref that the address should be valid for. 283Many predicates accept @code{const_int} nodes even though their mode is 284@code{VOIDmode}. 285 286@var{constraint} controls reloading and the choice of the best register 287class to use for a value, as explained later (@pxref{Constraints}). 288If the constraint would be an empty string, it can be omitted. 289 290People are often unclear on the difference between the constraint and the 291predicate. The predicate helps decide whether a given insn matches the 292pattern. The constraint plays no role in this decision; instead, it 293controls various decisions in the case of an insn which does match. 294 295@findex match_scratch 296@item (match_scratch:@var{m} @var{n} @var{constraint}) 297This expression is also a placeholder for operand number @var{n} 298and indicates that operand must be a @code{scratch} or @code{reg} 299expression. 300 301When matching patterns, this is equivalent to 302 303@smallexample 304(match_operand:@var{m} @var{n} "scratch_operand" @var{constraint}) 305@end smallexample 306 307but, when generating RTL, it produces a (@code{scratch}:@var{m}) 308expression. 309 310If the last few expressions in a @code{parallel} are @code{clobber} 311expressions whose operands are either a hard register or 312@code{match_scratch}, the combiner can add or delete them when 313necessary. @xref{Side Effects}. 314 315@findex match_dup 316@item (match_dup @var{n}) 317This expression is also a placeholder for operand number @var{n}. 318It is used when the operand needs to appear more than once in the 319insn. 320 321In construction, @code{match_dup} acts just like @code{match_operand}: 322the operand is substituted into the insn being constructed. But in 323matching, @code{match_dup} behaves differently. It assumes that operand 324number @var{n} has already been determined by a @code{match_operand} 325appearing earlier in the recognition template, and it matches only an 326identical-looking expression. 327 328Note that @code{match_dup} should not be used to tell the compiler that 329a particular register is being used for two operands (example: 330@code{add} that adds one register to another; the second register is 331both an input operand and the output operand). Use a matching 332constraint (@pxref{Simple Constraints}) for those. @code{match_dup} is for the cases where one 333operand is used in two places in the template, such as an instruction 334that computes both a quotient and a remainder, where the opcode takes 335two input operands but the RTL template has to refer to each of those 336twice; once for the quotient pattern and once for the remainder pattern. 337 338@findex match_operator 339@item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}]) 340This pattern is a kind of placeholder for a variable RTL expression 341code. 342 343When constructing an insn, it stands for an RTL expression whose 344expression code is taken from that of operand @var{n}, and whose 345operands are constructed from the patterns @var{operands}. 346 347When matching an expression, it matches an expression if the function 348@var{predicate} returns nonzero on that expression @emph{and} the 349patterns @var{operands} match the operands of the expression. 350 351Suppose that the function @code{commutative_operator} is defined as 352follows, to match any expression whose operator is one of the 353commutative arithmetic operators of RTL and whose mode is @var{mode}: 354 355@smallexample 356int 357commutative_integer_operator (x, mode) 358 rtx x; 359 machine_mode mode; 360@{ 361 enum rtx_code code = GET_CODE (x); 362 if (GET_MODE (x) != mode) 363 return 0; 364 return (GET_RTX_CLASS (code) == RTX_COMM_ARITH 365 || code == EQ || code == NE); 366@} 367@end smallexample 368 369Then the following pattern will match any RTL expression consisting 370of a commutative operator applied to two general operands: 371 372@smallexample 373(match_operator:SI 3 "commutative_operator" 374 [(match_operand:SI 1 "general_operand" "g") 375 (match_operand:SI 2 "general_operand" "g")]) 376@end smallexample 377 378Here the vector @code{[@var{operands}@dots{}]} contains two patterns 379because the expressions to be matched all contain two operands. 380 381When this pattern does match, the two operands of the commutative 382operator are recorded as operands 1 and 2 of the insn. (This is done 383by the two instances of @code{match_operand}.) Operand 3 of the insn 384will be the entire commutative expression: use @code{GET_CODE 385(operands[3])} to see which commutative operator was used. 386 387The machine mode @var{m} of @code{match_operator} works like that of 388@code{match_operand}: it is passed as the second argument to the 389predicate function, and that function is solely responsible for 390deciding whether the expression to be matched ``has'' that mode. 391 392When constructing an insn, argument 3 of the gen-function will specify 393the operation (i.e.@: the expression code) for the expression to be 394made. It should be an RTL expression, whose expression code is copied 395into a new expression whose operands are arguments 1 and 2 of the 396gen-function. The subexpressions of argument 3 are not used; 397only its expression code matters. 398 399When @code{match_operator} is used in a pattern for matching an insn, 400it usually best if the operand number of the @code{match_operator} 401is higher than that of the actual operands of the insn. This improves 402register allocation because the register allocator often looks at 403operands 1 and 2 of insns to see if it can do register tying. 404 405There is no way to specify constraints in @code{match_operator}. The 406operand of the insn which corresponds to the @code{match_operator} 407never has any constraints because it is never reloaded as a whole. 408However, if parts of its @var{operands} are matched by 409@code{match_operand} patterns, those parts may have constraints of 410their own. 411 412@findex match_op_dup 413@item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}]) 414Like @code{match_dup}, except that it applies to operators instead of 415operands. When constructing an insn, operand number @var{n} will be 416substituted at this point. But in matching, @code{match_op_dup} behaves 417differently. It assumes that operand number @var{n} has already been 418determined by a @code{match_operator} appearing earlier in the 419recognition template, and it matches only an identical-looking 420expression. 421 422@findex match_parallel 423@item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}]) 424This pattern is a placeholder for an insn that consists of a 425@code{parallel} expression with a variable number of elements. This 426expression should only appear at the top level of an insn pattern. 427 428When constructing an insn, operand number @var{n} will be substituted at 429this point. When matching an insn, it matches if the body of the insn 430is a @code{parallel} expression with at least as many elements as the 431vector of @var{subpat} expressions in the @code{match_parallel}, if each 432@var{subpat} matches the corresponding element of the @code{parallel}, 433@emph{and} the function @var{predicate} returns nonzero on the 434@code{parallel} that is the body of the insn. It is the responsibility 435of the predicate to validate elements of the @code{parallel} beyond 436those listed in the @code{match_parallel}. 437 438A typical use of @code{match_parallel} is to match load and store 439multiple expressions, which can contain a variable number of elements 440in a @code{parallel}. For example, 441 442@smallexample 443(define_insn "" 444 [(match_parallel 0 "load_multiple_operation" 445 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 446 (match_operand:SI 2 "memory_operand" "m")) 447 (use (reg:SI 179)) 448 (clobber (reg:SI 179))])] 449 "" 450 "loadm 0,0,%1,%2") 451@end smallexample 452 453This example comes from @file{a29k.md}. The function 454@code{load_multiple_operation} is defined in @file{a29k.c} and checks 455that subsequent elements in the @code{parallel} are the same as the 456@code{set} in the pattern, except that they are referencing subsequent 457registers and memory locations. 458 459An insn that matches this pattern might look like: 460 461@smallexample 462(parallel 463 [(set (reg:SI 20) (mem:SI (reg:SI 100))) 464 (use (reg:SI 179)) 465 (clobber (reg:SI 179)) 466 (set (reg:SI 21) 467 (mem:SI (plus:SI (reg:SI 100) 468 (const_int 4)))) 469 (set (reg:SI 22) 470 (mem:SI (plus:SI (reg:SI 100) 471 (const_int 8))))]) 472@end smallexample 473 474@findex match_par_dup 475@item (match_par_dup @var{n} [@var{subpat}@dots{}]) 476Like @code{match_op_dup}, but for @code{match_parallel} instead of 477@code{match_operator}. 478 479@end table 480 481@node Output Template 482@section Output Templates and Operand Substitution 483@cindex output templates 484@cindex operand substitution 485 486@cindex @samp{%} in template 487@cindex percent sign 488The @dfn{output template} is a string which specifies how to output the 489assembler code for an instruction pattern. Most of the template is a 490fixed string which is output literally. The character @samp{%} is used 491to specify where to substitute an operand; it can also be used to 492identify places where different variants of the assembler require 493different syntax. 494 495In the simplest case, a @samp{%} followed by a digit @var{n} says to output 496operand @var{n} at that point in the string. 497 498@samp{%} followed by a letter and a digit says to output an operand in an 499alternate fashion. Four letters have standard, built-in meanings described 500below. The machine description macro @code{PRINT_OPERAND} can define 501additional letters with nonstandard meanings. 502 503@samp{%c@var{digit}} can be used to substitute an operand that is a 504constant value without the syntax that normally indicates an immediate 505operand. 506 507@samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of 508the constant is negated before printing. 509 510@samp{%a@var{digit}} can be used to substitute an operand as if it were a 511memory reference, with the actual operand treated as the address. This may 512be useful when outputting a ``load address'' instruction, because often the 513assembler syntax for such an instruction requires you to write the operand 514as if it were a memory reference. 515 516@samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump 517instruction. 518 519@samp{%=} outputs a number which is unique to each instruction in the 520entire compilation. This is useful for making local labels to be 521referred to more than once in a single template that generates multiple 522assembler instructions. 523 524@samp{%} followed by a punctuation character specifies a substitution that 525does not use an operand. Only one case is standard: @samp{%%} outputs a 526@samp{%} into the assembler code. Other nonstandard cases can be 527defined in the @code{PRINT_OPERAND} macro. You must also define 528which punctuation characters are valid with the 529@code{PRINT_OPERAND_PUNCT_VALID_P} macro. 530 531@cindex \ 532@cindex backslash 533The template may generate multiple assembler instructions. Write the text 534for the instructions, with @samp{\;} between them. 535 536@cindex matching operands 537When the RTL contains two operands which are required by constraint to match 538each other, the output template must refer only to the lower-numbered operand. 539Matching operands are not always identical, and the rest of the compiler 540arranges to put the proper RTL expression for printing into the lower-numbered 541operand. 542 543One use of nonstandard letters or punctuation following @samp{%} is to 544distinguish between different assembler languages for the same machine; for 545example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax 546requires periods in most opcode names, while MIT syntax does not. For 547example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola 548syntax. The same file of patterns is used for both kinds of output syntax, 549but the character sequence @samp{%.} is used in each place where Motorola 550syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax 551defines the sequence to output a period; the macro for MIT syntax defines 552it to do nothing. 553 554@cindex @code{#} in template 555As a special case, a template consisting of the single character @code{#} 556instructs the compiler to first split the insn, and then output the 557resulting instructions separately. This helps eliminate redundancy in the 558output templates. If you have a @code{define_insn} that needs to emit 559multiple assembler instructions, and there is a matching @code{define_split} 560already defined, then you can simply use @code{#} as the output template 561instead of writing an output template that emits the multiple assembler 562instructions. 563 564If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct 565of the form @samp{@{option0|option1|option2@}} in the templates. These 566describe multiple variants of assembler language syntax. 567@xref{Instruction Output}. 568 569@node Output Statement 570@section C Statements for Assembler Output 571@cindex output statements 572@cindex C statements for assembler output 573@cindex generating assembler output 574 575Often a single fixed template string cannot produce correct and efficient 576assembler code for all the cases that are recognized by a single 577instruction pattern. For example, the opcodes may depend on the kinds of 578operands; or some unfortunate combinations of operands may require extra 579machine instructions. 580 581If the output control string starts with a @samp{@@}, then it is actually 582a series of templates, each on a separate line. (Blank lines and 583leading spaces and tabs are ignored.) The templates correspond to the 584pattern's constraint alternatives (@pxref{Multi-Alternative}). For example, 585if a target machine has a two-address add instruction @samp{addr} to add 586into a register and another @samp{addm} to add a register to memory, you 587might write this pattern: 588 589@smallexample 590(define_insn "addsi3" 591 [(set (match_operand:SI 0 "general_operand" "=r,m") 592 (plus:SI (match_operand:SI 1 "general_operand" "0,0") 593 (match_operand:SI 2 "general_operand" "g,r")))] 594 "" 595 "@@ 596 addr %2,%0 597 addm %2,%0") 598@end smallexample 599 600@cindex @code{*} in template 601@cindex asterisk in template 602If the output control string starts with a @samp{*}, then it is not an 603output template but rather a piece of C program that should compute a 604template. It should execute a @code{return} statement to return the 605template-string you want. Most such templates use C string literals, which 606require doublequote characters to delimit them. To include these 607doublequote characters in the string, prefix each one with @samp{\}. 608 609If the output control string is written as a brace block instead of a 610double-quoted string, it is automatically assumed to be C code. In that 611case, it is not necessary to put in a leading asterisk, or to escape the 612doublequotes surrounding C string literals. 613 614The operands may be found in the array @code{operands}, whose C data type 615is @code{rtx []}. 616 617It is very common to select different ways of generating assembler code 618based on whether an immediate operand is within a certain range. Be 619careful when doing this, because the result of @code{INTVAL} is an 620integer on the host machine. If the host machine has more bits in an 621@code{int} than the target machine has in the mode in which the constant 622will be used, then some of the bits you get from @code{INTVAL} will be 623superfluous. For proper results, you must carefully disregard the 624values of those bits. 625 626@findex output_asm_insn 627It is possible to output an assembler instruction and then go on to output 628or compute more of them, using the subroutine @code{output_asm_insn}. This 629receives two arguments: a template-string and a vector of operands. The 630vector may be @code{operands}, or it may be another array of @code{rtx} 631that you declare locally and initialize yourself. 632 633@findex which_alternative 634When an insn pattern has multiple alternatives in its constraints, often 635the appearance of the assembler code is determined mostly by which alternative 636was matched. When this is so, the C code can test the variable 637@code{which_alternative}, which is the ordinal number of the alternative 638that was actually satisfied (0 for the first, 1 for the second alternative, 639etc.). 640 641For example, suppose there are two opcodes for storing zero, @samp{clrreg} 642for registers and @samp{clrmem} for memory locations. Here is how 643a pattern could use @code{which_alternative} to choose between them: 644 645@smallexample 646(define_insn "" 647 [(set (match_operand:SI 0 "general_operand" "=r,m") 648 (const_int 0))] 649 "" 650 @{ 651 return (which_alternative == 0 652 ? "clrreg %0" : "clrmem %0"); 653 @}) 654@end smallexample 655 656The example above, where the assembler code to generate was 657@emph{solely} determined by the alternative, could also have been specified 658as follows, having the output control string start with a @samp{@@}: 659 660@smallexample 661@group 662(define_insn "" 663 [(set (match_operand:SI 0 "general_operand" "=r,m") 664 (const_int 0))] 665 "" 666 "@@ 667 clrreg %0 668 clrmem %0") 669@end group 670@end smallexample 671 672If you just need a little bit of C code in one (or a few) alternatives, 673you can use @samp{*} inside of a @samp{@@} multi-alternative template: 674 675@smallexample 676@group 677(define_insn "" 678 [(set (match_operand:SI 0 "general_operand" "=r,<,m") 679 (const_int 0))] 680 "" 681 "@@ 682 clrreg %0 683 * return stack_mem_p (operands[0]) ? \"push 0\" : \"clrmem %0\"; 684 clrmem %0") 685@end group 686@end smallexample 687 688@node Predicates 689@section Predicates 690@cindex predicates 691@cindex operand predicates 692@cindex operator predicates 693 694A predicate determines whether a @code{match_operand} or 695@code{match_operator} expression matches, and therefore whether the 696surrounding instruction pattern will be used for that combination of 697operands. GCC has a number of machine-independent predicates, and you 698can define machine-specific predicates as needed. By convention, 699predicates used with @code{match_operand} have names that end in 700@samp{_operand}, and those used with @code{match_operator} have names 701that end in @samp{_operator}. 702 703All predicates are Boolean functions (in the mathematical sense) of 704two arguments: the RTL expression that is being considered at that 705position in the instruction pattern, and the machine mode that the 706@code{match_operand} or @code{match_operator} specifies. In this 707section, the first argument is called @var{op} and the second argument 708@var{mode}. Predicates can be called from C as ordinary two-argument 709functions; this can be useful in output templates or other 710machine-specific code. 711 712Operand predicates can allow operands that are not actually acceptable 713to the hardware, as long as the constraints give reload the ability to 714fix them up (@pxref{Constraints}). However, GCC will usually generate 715better code if the predicates specify the requirements of the machine 716instructions as closely as possible. Reload cannot fix up operands 717that must be constants (``immediate operands''); you must use a 718predicate that allows only constants, or else enforce the requirement 719in the extra condition. 720 721@cindex predicates and machine modes 722@cindex normal predicates 723@cindex special predicates 724Most predicates handle their @var{mode} argument in a uniform manner. 725If @var{mode} is @code{VOIDmode} (unspecified), then @var{op} can have 726any mode. If @var{mode} is anything else, then @var{op} must have the 727same mode, unless @var{op} is a @code{CONST_INT} or integer 728@code{CONST_DOUBLE}. These RTL expressions always have 729@code{VOIDmode}, so it would be counterproductive to check that their 730mode matches. Instead, predicates that accept @code{CONST_INT} and/or 731integer @code{CONST_DOUBLE} check that the value stored in the 732constant will fit in the requested mode. 733 734Predicates with this behavior are called @dfn{normal}. 735@command{genrecog} can optimize the instruction recognizer based on 736knowledge of how normal predicates treat modes. It can also diagnose 737certain kinds of common errors in the use of normal predicates; for 738instance, it is almost always an error to use a normal predicate 739without specifying a mode. 740 741Predicates that do something different with their @var{mode} argument 742are called @dfn{special}. The generic predicates 743@code{address_operand} and @code{pmode_register_operand} are special 744predicates. @command{genrecog} does not do any optimizations or 745diagnosis when special predicates are used. 746 747@menu 748* Machine-Independent Predicates:: Predicates available to all back ends. 749* Defining Predicates:: How to write machine-specific predicate 750 functions. 751@end menu 752 753@node Machine-Independent Predicates 754@subsection Machine-Independent Predicates 755@cindex machine-independent predicates 756@cindex generic predicates 757 758These are the generic predicates available to all back ends. They are 759defined in @file{recog.c}. The first category of predicates allow 760only constant, or @dfn{immediate}, operands. 761 762@defun immediate_operand 763This predicate allows any sort of constant that fits in @var{mode}. 764It is an appropriate choice for instructions that take operands that 765must be constant. 766@end defun 767 768@defun const_int_operand 769This predicate allows any @code{CONST_INT} expression that fits in 770@var{mode}. It is an appropriate choice for an immediate operand that 771does not allow a symbol or label. 772@end defun 773 774@defun const_double_operand 775This predicate accepts any @code{CONST_DOUBLE} expression that has 776exactly @var{mode}. If @var{mode} is @code{VOIDmode}, it will also 777accept @code{CONST_INT}. It is intended for immediate floating point 778constants. 779@end defun 780 781@noindent 782The second category of predicates allow only some kind of machine 783register. 784 785@defun register_operand 786This predicate allows any @code{REG} or @code{SUBREG} expression that 787is valid for @var{mode}. It is often suitable for arithmetic 788instruction operands on a RISC machine. 789@end defun 790 791@defun pmode_register_operand 792This is a slight variant on @code{register_operand} which works around 793a limitation in the machine-description reader. 794 795@smallexample 796(match_operand @var{n} "pmode_register_operand" @var{constraint}) 797@end smallexample 798 799@noindent 800means exactly what 801 802@smallexample 803(match_operand:P @var{n} "register_operand" @var{constraint}) 804@end smallexample 805 806@noindent 807would mean, if the machine-description reader accepted @samp{:P} 808mode suffixes. Unfortunately, it cannot, because @code{Pmode} is an 809alias for some other mode, and might vary with machine-specific 810options. @xref{Misc}. 811@end defun 812 813@defun scratch_operand 814This predicate allows hard registers and @code{SCRATCH} expressions, 815but not pseudo-registers. It is used internally by @code{match_scratch}; 816it should not be used directly. 817@end defun 818 819@noindent 820The third category of predicates allow only some kind of memory reference. 821 822@defun memory_operand 823This predicate allows any valid reference to a quantity of mode 824@var{mode} in memory, as determined by the weak form of 825@code{GO_IF_LEGITIMATE_ADDRESS} (@pxref{Addressing Modes}). 826@end defun 827 828@defun address_operand 829This predicate is a little unusual; it allows any operand that is a 830valid expression for the @emph{address} of a quantity of mode 831@var{mode}, again determined by the weak form of 832@code{GO_IF_LEGITIMATE_ADDRESS}. To first order, if 833@samp{@w{(mem:@var{mode} (@var{exp}))}} is acceptable to 834@code{memory_operand}, then @var{exp} is acceptable to 835@code{address_operand}. Note that @var{exp} does not necessarily have 836the mode @var{mode}. 837@end defun 838 839@defun indirect_operand 840This is a stricter form of @code{memory_operand} which allows only 841memory references with a @code{general_operand} as the address 842expression. New uses of this predicate are discouraged, because 843@code{general_operand} is very permissive, so it's hard to tell what 844an @code{indirect_operand} does or does not allow. If a target has 845different requirements for memory operands for different instructions, 846it is better to define target-specific predicates which enforce the 847hardware's requirements explicitly. 848@end defun 849 850@defun push_operand 851This predicate allows a memory reference suitable for pushing a value 852onto the stack. This will be a @code{MEM} which refers to 853@code{stack_pointer_rtx}, with a side-effect in its address expression 854(@pxref{Incdec}); which one is determined by the 855@code{STACK_PUSH_CODE} macro (@pxref{Frame Layout}). 856@end defun 857 858@defun pop_operand 859This predicate allows a memory reference suitable for popping a value 860off the stack. Again, this will be a @code{MEM} referring to 861@code{stack_pointer_rtx}, with a side-effect in its address 862expression. However, this time @code{STACK_POP_CODE} is expected. 863@end defun 864 865@noindent 866The fourth category of predicates allow some combination of the above 867operands. 868 869@defun nonmemory_operand 870This predicate allows any immediate or register operand valid for @var{mode}. 871@end defun 872 873@defun nonimmediate_operand 874This predicate allows any register or memory operand valid for @var{mode}. 875@end defun 876 877@defun general_operand 878This predicate allows any immediate, register, or memory operand 879valid for @var{mode}. 880@end defun 881 882@noindent 883Finally, there are two generic operator predicates. 884 885@defun comparison_operator 886This predicate matches any expression which performs an arithmetic 887comparison in @var{mode}; that is, @code{COMPARISON_P} is true for the 888expression code. 889@end defun 890 891@defun ordered_comparison_operator 892This predicate matches any expression which performs an arithmetic 893comparison in @var{mode} and whose expression code is valid for integer 894modes; that is, the expression code will be one of @code{eq}, @code{ne}, 895@code{lt}, @code{ltu}, @code{le}, @code{leu}, @code{gt}, @code{gtu}, 896@code{ge}, @code{geu}. 897@end defun 898 899@node Defining Predicates 900@subsection Defining Machine-Specific Predicates 901@cindex defining predicates 902@findex define_predicate 903@findex define_special_predicate 904 905Many machines have requirements for their operands that cannot be 906expressed precisely using the generic predicates. You can define 907additional predicates using @code{define_predicate} and 908@code{define_special_predicate} expressions. These expressions have 909three operands: 910 911@itemize @bullet 912@item 913The name of the predicate, as it will be referred to in 914@code{match_operand} or @code{match_operator} expressions. 915 916@item 917An RTL expression which evaluates to true if the predicate allows the 918operand @var{op}, false if it does not. This expression can only use 919the following RTL codes: 920 921@table @code 922@item MATCH_OPERAND 923When written inside a predicate expression, a @code{MATCH_OPERAND} 924expression evaluates to true if the predicate it names would allow 925@var{op}. The operand number and constraint are ignored. Due to 926limitations in @command{genrecog}, you can only refer to generic 927predicates and predicates that have already been defined. 928 929@item MATCH_CODE 930This expression evaluates to true if @var{op} or a specified 931subexpression of @var{op} has one of a given list of RTX codes. 932 933The first operand of this expression is a string constant containing a 934comma-separated list of RTX code names (in lower case). These are the 935codes for which the @code{MATCH_CODE} will be true. 936 937The second operand is a string constant which indicates what 938subexpression of @var{op} to examine. If it is absent or the empty 939string, @var{op} itself is examined. Otherwise, the string constant 940must be a sequence of digits and/or lowercase letters. Each character 941indicates a subexpression to extract from the current expression; for 942the first character this is @var{op}, for the second and subsequent 943characters it is the result of the previous character. A digit 944@var{n} extracts @samp{@w{XEXP (@var{e}, @var{n})}}; a letter @var{l} 945extracts @samp{@w{XVECEXP (@var{e}, 0, @var{n})}} where @var{n} is the 946alphabetic ordinal of @var{l} (0 for `a', 1 for 'b', and so on). The 947@code{MATCH_CODE} then examines the RTX code of the subexpression 948extracted by the complete string. It is not possible to extract 949components of an @code{rtvec} that is not at position 0 within its RTX 950object. 951 952@item MATCH_TEST 953This expression has one operand, a string constant containing a C 954expression. The predicate's arguments, @var{op} and @var{mode}, are 955available with those names in the C expression. The @code{MATCH_TEST} 956evaluates to true if the C expression evaluates to a nonzero value. 957@code{MATCH_TEST} expressions must not have side effects. 958 959@item AND 960@itemx IOR 961@itemx NOT 962@itemx IF_THEN_ELSE 963The basic @samp{MATCH_} expressions can be combined using these 964logical operators, which have the semantics of the C operators 965@samp{&&}, @samp{||}, @samp{!}, and @samp{@w{? :}} respectively. As 966in Common Lisp, you may give an @code{AND} or @code{IOR} expression an 967arbitrary number of arguments; this has exactly the same effect as 968writing a chain of two-argument @code{AND} or @code{IOR} expressions. 969@end table 970 971@item 972An optional block of C code, which should execute 973@samp{@w{return true}} if the predicate is found to match and 974@samp{@w{return false}} if it does not. It must not have any side 975effects. The predicate arguments, @var{op} and @var{mode}, are 976available with those names. 977 978If a code block is present in a predicate definition, then the RTL 979expression must evaluate to true @emph{and} the code block must 980execute @samp{@w{return true}} for the predicate to allow the operand. 981The RTL expression is evaluated first; do not re-check anything in the 982code block that was checked in the RTL expression. 983@end itemize 984 985The program @command{genrecog} scans @code{define_predicate} and 986@code{define_special_predicate} expressions to determine which RTX 987codes are possibly allowed. You should always make this explicit in 988the RTL predicate expression, using @code{MATCH_OPERAND} and 989@code{MATCH_CODE}. 990 991Here is an example of a simple predicate definition, from the IA64 992machine description: 993 994@smallexample 995@group 996;; @r{True if @var{op} is a @code{SYMBOL_REF} which refers to the sdata section.} 997(define_predicate "small_addr_symbolic_operand" 998 (and (match_code "symbol_ref") 999 (match_test "SYMBOL_REF_SMALL_ADDR_P (op)"))) 1000@end group 1001@end smallexample 1002 1003@noindent 1004And here is another, showing the use of the C block. 1005 1006@smallexample 1007@group 1008;; @r{True if @var{op} is a register operand that is (or could be) a GR reg.} 1009(define_predicate "gr_register_operand" 1010 (match_operand 0 "register_operand") 1011@{ 1012 unsigned int regno; 1013 if (GET_CODE (op) == SUBREG) 1014 op = SUBREG_REG (op); 1015 1016 regno = REGNO (op); 1017 return (regno >= FIRST_PSEUDO_REGISTER || GENERAL_REGNO_P (regno)); 1018@}) 1019@end group 1020@end smallexample 1021 1022Predicates written with @code{define_predicate} automatically include 1023a test that @var{mode} is @code{VOIDmode}, or @var{op} has the same 1024mode as @var{mode}, or @var{op} is a @code{CONST_INT} or 1025@code{CONST_DOUBLE}. They do @emph{not} check specifically for 1026integer @code{CONST_DOUBLE}, nor do they test that the value of either 1027kind of constant fits in the requested mode. This is because 1028target-specific predicates that take constants usually have to do more 1029stringent value checks anyway. If you need the exact same treatment 1030of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic predicates 1031provide, use a @code{MATCH_OPERAND} subexpression to call 1032@code{const_int_operand}, @code{const_double_operand}, or 1033@code{immediate_operand}. 1034 1035Predicates written with @code{define_special_predicate} do not get any 1036automatic mode checks, and are treated as having special mode handling 1037by @command{genrecog}. 1038 1039The program @command{genpreds} is responsible for generating code to 1040test predicates. It also writes a header file containing function 1041declarations for all machine-specific predicates. It is not necessary 1042to declare these predicates in @file{@var{cpu}-protos.h}. 1043@end ifset 1044 1045@c Most of this node appears by itself (in a different place) even 1046@c when the INTERNALS flag is clear. Passages that require the internals 1047@c manual's context are conditionalized to appear only in the internals manual. 1048@ifset INTERNALS 1049@node Constraints 1050@section Operand Constraints 1051@cindex operand constraints 1052@cindex constraints 1053 1054Each @code{match_operand} in an instruction pattern can specify 1055constraints for the operands allowed. The constraints allow you to 1056fine-tune matching within the set of operands allowed by the 1057predicate. 1058 1059@end ifset 1060@ifclear INTERNALS 1061@node Constraints 1062@section Constraints for @code{asm} Operands 1063@cindex operand constraints, @code{asm} 1064@cindex constraints, @code{asm} 1065@cindex @code{asm} constraints 1066 1067Here are specific details on what constraint letters you can use with 1068@code{asm} operands. 1069@end ifclear 1070Constraints can say whether 1071an operand may be in a register, and which kinds of register; whether the 1072operand can be a memory reference, and which kinds of address; whether the 1073operand may be an immediate constant, and which possible values it may 1074have. Constraints can also require two operands to match. 1075Side-effects aren't allowed in operands of inline @code{asm}, unless 1076@samp{<} or @samp{>} constraints are used, because there is no guarantee 1077that the side-effects will happen exactly once in an instruction that can update 1078the addressing register. 1079 1080@ifset INTERNALS 1081@menu 1082* Simple Constraints:: Basic use of constraints. 1083* Multi-Alternative:: When an insn has two alternative constraint-patterns. 1084* Class Preferences:: Constraints guide which hard register to put things in. 1085* Modifiers:: More precise control over effects of constraints. 1086* Machine Constraints:: Existing constraints for some particular machines. 1087* Disable Insn Alternatives:: Disable insn alternatives using attributes. 1088* Define Constraints:: How to define machine-specific constraints. 1089* C Constraint Interface:: How to test constraints from C code. 1090@end menu 1091@end ifset 1092 1093@ifclear INTERNALS 1094@menu 1095* Simple Constraints:: Basic use of constraints. 1096* Multi-Alternative:: When an insn has two alternative constraint-patterns. 1097* Modifiers:: More precise control over effects of constraints. 1098* Machine Constraints:: Special constraints for some particular machines. 1099@end menu 1100@end ifclear 1101 1102@node Simple Constraints 1103@subsection Simple Constraints 1104@cindex simple constraints 1105 1106The simplest kind of constraint is a string full of letters, each of 1107which describes one kind of operand that is permitted. Here are 1108the letters that are allowed: 1109 1110@table @asis 1111@item whitespace 1112Whitespace characters are ignored and can be inserted at any position 1113except the first. This enables each alternative for different operands to 1114be visually aligned in the machine description even if they have different 1115number of constraints and modifiers. 1116 1117@cindex @samp{m} in constraint 1118@cindex memory references in constraints 1119@item @samp{m} 1120A memory operand is allowed, with any kind of address that the machine 1121supports in general. 1122Note that the letter used for the general memory constraint can be 1123re-defined by a back end using the @code{TARGET_MEM_CONSTRAINT} macro. 1124 1125@cindex offsettable address 1126@cindex @samp{o} in constraint 1127@item @samp{o} 1128A memory operand is allowed, but only if the address is 1129@dfn{offsettable}. This means that adding a small integer (actually, 1130the width in bytes of the operand, as determined by its machine mode) 1131may be added to the address and the result is also a valid memory 1132address. 1133 1134@cindex autoincrement/decrement addressing 1135For example, an address which is constant is offsettable; so is an 1136address that is the sum of a register and a constant (as long as a 1137slightly larger constant is also within the range of address-offsets 1138supported by the machine); but an autoincrement or autodecrement 1139address is not offsettable. More complicated indirect/indexed 1140addresses may or may not be offsettable depending on the other 1141addressing modes that the machine supports. 1142 1143Note that in an output operand which can be matched by another 1144operand, the constraint letter @samp{o} is valid only when accompanied 1145by both @samp{<} (if the target machine has predecrement addressing) 1146and @samp{>} (if the target machine has preincrement addressing). 1147 1148@cindex @samp{V} in constraint 1149@item @samp{V} 1150A memory operand that is not offsettable. In other words, anything that 1151would fit the @samp{m} constraint but not the @samp{o} constraint. 1152 1153@cindex @samp{<} in constraint 1154@item @samp{<} 1155A memory operand with autodecrement addressing (either predecrement or 1156postdecrement) is allowed. In inline @code{asm} this constraint is only 1157allowed if the operand is used exactly once in an instruction that can 1158handle the side-effects. Not using an operand with @samp{<} in constraint 1159string in the inline @code{asm} pattern at all or using it in multiple 1160instructions isn't valid, because the side-effects wouldn't be performed 1161or would be performed more than once. Furthermore, on some targets 1162the operand with @samp{<} in constraint string must be accompanied by 1163special instruction suffixes like @code{%U0} instruction suffix on PowerPC 1164or @code{%P0} on IA-64. 1165 1166@cindex @samp{>} in constraint 1167@item @samp{>} 1168A memory operand with autoincrement addressing (either preincrement or 1169postincrement) is allowed. In inline @code{asm} the same restrictions 1170as for @samp{<} apply. 1171 1172@cindex @samp{r} in constraint 1173@cindex registers in constraints 1174@item @samp{r} 1175A register operand is allowed provided that it is in a general 1176register. 1177 1178@cindex constants in constraints 1179@cindex @samp{i} in constraint 1180@item @samp{i} 1181An immediate integer operand (one with constant value) is allowed. 1182This includes symbolic constants whose values will be known only at 1183assembly time or later. 1184 1185@cindex @samp{n} in constraint 1186@item @samp{n} 1187An immediate integer operand with a known numeric value is allowed. 1188Many systems cannot support assembly-time constants for operands less 1189than a word wide. Constraints for these operands should use @samp{n} 1190rather than @samp{i}. 1191 1192@cindex @samp{I} in constraint 1193@item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P} 1194Other letters in the range @samp{I} through @samp{P} may be defined in 1195a machine-dependent fashion to permit immediate integer operands with 1196explicit integer values in specified ranges. For example, on the 119768000, @samp{I} is defined to stand for the range of values 1 to 8. 1198This is the range permitted as a shift count in the shift 1199instructions. 1200 1201@cindex @samp{E} in constraint 1202@item @samp{E} 1203An immediate floating operand (expression code @code{const_double}) is 1204allowed, but only if the target floating point format is the same as 1205that of the host machine (on which the compiler is running). 1206 1207@cindex @samp{F} in constraint 1208@item @samp{F} 1209An immediate floating operand (expression code @code{const_double} or 1210@code{const_vector}) is allowed. 1211 1212@cindex @samp{G} in constraint 1213@cindex @samp{H} in constraint 1214@item @samp{G}, @samp{H} 1215@samp{G} and @samp{H} may be defined in a machine-dependent fashion to 1216permit immediate floating operands in particular ranges of values. 1217 1218@cindex @samp{s} in constraint 1219@item @samp{s} 1220An immediate integer operand whose value is not an explicit integer is 1221allowed. 1222 1223This might appear strange; if an insn allows a constant operand with a 1224value not known at compile time, it certainly must allow any known 1225value. So why use @samp{s} instead of @samp{i}? Sometimes it allows 1226better code to be generated. 1227 1228For example, on the 68000 in a fullword instruction it is possible to 1229use an immediate operand; but if the immediate value is between @minus{}128 1230and 127, better code results from loading the value into a register and 1231using the register. This is because the load into the register can be 1232done with a @samp{moveq} instruction. We arrange for this to happen 1233by defining the letter @samp{K} to mean ``any integer outside the 1234range @minus{}128 to 127'', and then specifying @samp{Ks} in the operand 1235constraints. 1236 1237@cindex @samp{g} in constraint 1238@item @samp{g} 1239Any register, memory or immediate integer operand is allowed, except for 1240registers that are not general registers. 1241 1242@cindex @samp{X} in constraint 1243@item @samp{X} 1244@ifset INTERNALS 1245Any operand whatsoever is allowed, even if it does not satisfy 1246@code{general_operand}. This is normally used in the constraint of 1247a @code{match_scratch} when certain alternatives will not actually 1248require a scratch register. 1249@end ifset 1250@ifclear INTERNALS 1251Any operand whatsoever is allowed. 1252@end ifclear 1253 1254@cindex @samp{0} in constraint 1255@cindex digits in constraint 1256@item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{9} 1257An operand that matches the specified operand number is allowed. If a 1258digit is used together with letters within the same alternative, the 1259digit should come last. 1260 1261This number is allowed to be more than a single digit. If multiple 1262digits are encountered consecutively, they are interpreted as a single 1263decimal integer. There is scant chance for ambiguity, since to-date 1264it has never been desirable that @samp{10} be interpreted as matching 1265either operand 1 @emph{or} operand 0. Should this be desired, one 1266can use multiple alternatives instead. 1267 1268@cindex matching constraint 1269@cindex constraint, matching 1270This is called a @dfn{matching constraint} and what it really means is 1271that the assembler has only a single operand that fills two roles 1272@ifset INTERNALS 1273considered separate in the RTL insn. For example, an add insn has two 1274input operands and one output operand in the RTL, but on most CISC 1275@end ifset 1276@ifclear INTERNALS 1277which @code{asm} distinguishes. For example, an add instruction uses 1278two input operands and an output operand, but on most CISC 1279@end ifclear 1280machines an add instruction really has only two operands, one of them an 1281input-output operand: 1282 1283@smallexample 1284addl #35,r12 1285@end smallexample 1286 1287Matching constraints are used in these circumstances. 1288More precisely, the two operands that match must include one input-only 1289operand and one output-only operand. Moreover, the digit must be a 1290smaller number than the number of the operand that uses it in the 1291constraint. 1292 1293@ifset INTERNALS 1294For operands to match in a particular case usually means that they 1295are identical-looking RTL expressions. But in a few special cases 1296specific kinds of dissimilarity are allowed. For example, @code{*x} 1297as an input operand will match @code{*x++} as an output operand. 1298For proper results in such cases, the output template should always 1299use the output-operand's number when printing the operand. 1300@end ifset 1301 1302@cindex load address instruction 1303@cindex push address instruction 1304@cindex address constraints 1305@cindex @samp{p} in constraint 1306@item @samp{p} 1307An operand that is a valid memory address is allowed. This is 1308for ``load address'' and ``push address'' instructions. 1309 1310@findex address_operand 1311@samp{p} in the constraint must be accompanied by @code{address_operand} 1312as the predicate in the @code{match_operand}. This predicate interprets 1313the mode specified in the @code{match_operand} as the mode of the memory 1314reference for which the address would be valid. 1315 1316@cindex other register constraints 1317@cindex extensible constraints 1318@item @var{other-letters} 1319Other letters can be defined in machine-dependent fashion to stand for 1320particular classes of registers or other arbitrary operand types. 1321@samp{d}, @samp{a} and @samp{f} are defined on the 68000/68020 to stand 1322for data, address and floating point registers. 1323@end table 1324 1325@ifset INTERNALS 1326In order to have valid assembler code, each operand must satisfy 1327its constraint. But a failure to do so does not prevent the pattern 1328from applying to an insn. Instead, it directs the compiler to modify 1329the code so that the constraint will be satisfied. Usually this is 1330done by copying an operand into a register. 1331 1332Contrast, therefore, the two instruction patterns that follow: 1333 1334@smallexample 1335(define_insn "" 1336 [(set (match_operand:SI 0 "general_operand" "=r") 1337 (plus:SI (match_dup 0) 1338 (match_operand:SI 1 "general_operand" "r")))] 1339 "" 1340 "@dots{}") 1341@end smallexample 1342 1343@noindent 1344which has two operands, one of which must appear in two places, and 1345 1346@smallexample 1347(define_insn "" 1348 [(set (match_operand:SI 0 "general_operand" "=r") 1349 (plus:SI (match_operand:SI 1 "general_operand" "0") 1350 (match_operand:SI 2 "general_operand" "r")))] 1351 "" 1352 "@dots{}") 1353@end smallexample 1354 1355@noindent 1356which has three operands, two of which are required by a constraint to be 1357identical. If we are considering an insn of the form 1358 1359@smallexample 1360(insn @var{n} @var{prev} @var{next} 1361 (set (reg:SI 3) 1362 (plus:SI (reg:SI 6) (reg:SI 109))) 1363 @dots{}) 1364@end smallexample 1365 1366@noindent 1367the first pattern would not apply at all, because this insn does not 1368contain two identical subexpressions in the right place. The pattern would 1369say, ``That does not look like an add instruction; try other patterns''. 1370The second pattern would say, ``Yes, that's an add instruction, but there 1371is something wrong with it''. It would direct the reload pass of the 1372compiler to generate additional insns to make the constraint true. The 1373results might look like this: 1374 1375@smallexample 1376(insn @var{n2} @var{prev} @var{n} 1377 (set (reg:SI 3) (reg:SI 6)) 1378 @dots{}) 1379 1380(insn @var{n} @var{n2} @var{next} 1381 (set (reg:SI 3) 1382 (plus:SI (reg:SI 3) (reg:SI 109))) 1383 @dots{}) 1384@end smallexample 1385 1386It is up to you to make sure that each operand, in each pattern, has 1387constraints that can handle any RTL expression that could be present for 1388that operand. (When multiple alternatives are in use, each pattern must, 1389for each possible combination of operand expressions, have at least one 1390alternative which can handle that combination of operands.) The 1391constraints don't need to @emph{allow} any possible operand---when this is 1392the case, they do not constrain---but they must at least point the way to 1393reloading any possible operand so that it will fit. 1394 1395@itemize @bullet 1396@item 1397If the constraint accepts whatever operands the predicate permits, 1398there is no problem: reloading is never necessary for this operand. 1399 1400For example, an operand whose constraints permit everything except 1401registers is safe provided its predicate rejects registers. 1402 1403An operand whose predicate accepts only constant values is safe 1404provided its constraints include the letter @samp{i}. If any possible 1405constant value is accepted, then nothing less than @samp{i} will do; 1406if the predicate is more selective, then the constraints may also be 1407more selective. 1408 1409@item 1410Any operand expression can be reloaded by copying it into a register. 1411So if an operand's constraints allow some kind of register, it is 1412certain to be safe. It need not permit all classes of registers; the 1413compiler knows how to copy a register into another register of the 1414proper class in order to make an instruction valid. 1415 1416@cindex nonoffsettable memory reference 1417@cindex memory reference, nonoffsettable 1418@item 1419A nonoffsettable memory reference can be reloaded by copying the 1420address into a register. So if the constraint uses the letter 1421@samp{o}, all memory references are taken care of. 1422 1423@item 1424A constant operand can be reloaded by allocating space in memory to 1425hold it as preinitialized data. Then the memory reference can be used 1426in place of the constant. So if the constraint uses the letters 1427@samp{o} or @samp{m}, constant operands are not a problem. 1428 1429@item 1430If the constraint permits a constant and a pseudo register used in an insn 1431was not allocated to a hard register and is equivalent to a constant, 1432the register will be replaced with the constant. If the predicate does 1433not permit a constant and the insn is re-recognized for some reason, the 1434compiler will crash. Thus the predicate must always recognize any 1435objects allowed by the constraint. 1436@end itemize 1437 1438If the operand's predicate can recognize registers, but the constraint does 1439not permit them, it can make the compiler crash. When this operand happens 1440to be a register, the reload pass will be stymied, because it does not know 1441how to copy a register temporarily into memory. 1442 1443If the predicate accepts a unary operator, the constraint applies to the 1444operand. For example, the MIPS processor at ISA level 3 supports an 1445instruction which adds two registers in @code{SImode} to produce a 1446@code{DImode} result, but only if the registers are correctly sign 1447extended. This predicate for the input operands accepts a 1448@code{sign_extend} of an @code{SImode} register. Write the constraint 1449to indicate the type of register that is required for the operand of the 1450@code{sign_extend}. 1451@end ifset 1452 1453@node Multi-Alternative 1454@subsection Multiple Alternative Constraints 1455@cindex multiple alternative constraints 1456 1457Sometimes a single instruction has multiple alternative sets of possible 1458operands. For example, on the 68000, a logical-or instruction can combine 1459register or an immediate value into memory, or it can combine any kind of 1460operand into a register; but it cannot combine one memory location into 1461another. 1462 1463These constraints are represented as multiple alternatives. An alternative 1464can be described by a series of letters for each operand. The overall 1465constraint for an operand is made from the letters for this operand 1466from the first alternative, a comma, the letters for this operand from 1467the second alternative, a comma, and so on until the last alternative. 1468All operands for a single instruction must have the same number of 1469alternatives. 1470@ifset INTERNALS 1471Here is how it is done for fullword logical-or on the 68000: 1472 1473@smallexample 1474(define_insn "iorsi3" 1475 [(set (match_operand:SI 0 "general_operand" "=m,d") 1476 (ior:SI (match_operand:SI 1 "general_operand" "%0,0") 1477 (match_operand:SI 2 "general_operand" "dKs,dmKs")))] 1478 @dots{}) 1479@end smallexample 1480 1481The first alternative has @samp{m} (memory) for operand 0, @samp{0} for 1482operand 1 (meaning it must match operand 0), and @samp{dKs} for operand 14832. The second alternative has @samp{d} (data register) for operand 0, 1484@samp{0} for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and 1485@samp{%} in the constraints apply to all the alternatives; their 1486meaning is explained in the next section (@pxref{Class Preferences}). 1487 1488If all the operands fit any one alternative, the instruction is valid. 1489Otherwise, for each alternative, the compiler counts how many instructions 1490must be added to copy the operands so that that alternative applies. 1491The alternative requiring the least copying is chosen. If two alternatives 1492need the same amount of copying, the one that comes first is chosen. 1493These choices can be altered with the @samp{?} and @samp{!} characters: 1494 1495@table @code 1496@cindex @samp{?} in constraint 1497@cindex question mark 1498@item ? 1499Disparage slightly the alternative that the @samp{?} appears in, 1500as a choice when no alternative applies exactly. The compiler regards 1501this alternative as one unit more costly for each @samp{?} that appears 1502in it. 1503 1504@cindex @samp{!} in constraint 1505@cindex exclamation point 1506@item ! 1507Disparage severely the alternative that the @samp{!} appears in. 1508This alternative can still be used if it fits without reloading, 1509but if reloading is needed, some other alternative will be used. 1510 1511@cindex @samp{^} in constraint 1512@cindex caret 1513@item ^ 1514This constraint is analogous to @samp{?} but it disparages slightly 1515the alternative only if the operand with the @samp{^} needs a reload. 1516 1517@cindex @samp{$} in constraint 1518@cindex dollar sign 1519@item $ 1520This constraint is analogous to @samp{!} but it disparages severely 1521the alternative only if the operand with the @samp{$} needs a reload. 1522@end table 1523 1524When an insn pattern has multiple alternatives in its constraints, often 1525the appearance of the assembler code is determined mostly by which 1526alternative was matched. When this is so, the C code for writing the 1527assembler code can use the variable @code{which_alternative}, which is 1528the ordinal number of the alternative that was actually satisfied (0 for 1529the first, 1 for the second alternative, etc.). @xref{Output Statement}. 1530@end ifset 1531@ifclear INTERNALS 1532 1533So the first alternative for the 68000's logical-or could be written as 1534@code{"+m" (output) : "ir" (input)}. The second could be @code{"+r" 1535(output): "irm" (input)}. However, the fact that two memory locations 1536cannot be used in a single instruction prevents simply using @code{"+rm" 1537(output) : "irm" (input)}. Using multi-alternatives, this might be 1538written as @code{"+m,r" (output) : "ir,irm" (input)}. This describes 1539all the available alternatives to the compiler, allowing it to choose 1540the most efficient one for the current conditions. 1541 1542There is no way within the template to determine which alternative was 1543chosen. However you may be able to wrap your @code{asm} statements with 1544builtins such as @code{__builtin_constant_p} to achieve the desired results. 1545@end ifclear 1546 1547@ifset INTERNALS 1548@node Class Preferences 1549@subsection Register Class Preferences 1550@cindex class preference constraints 1551@cindex register class preference constraints 1552 1553@cindex voting between constraint alternatives 1554The operand constraints have another function: they enable the compiler 1555to decide which kind of hardware register a pseudo register is best 1556allocated to. The compiler examines the constraints that apply to the 1557insns that use the pseudo register, looking for the machine-dependent 1558letters such as @samp{d} and @samp{a} that specify classes of registers. 1559The pseudo register is put in whichever class gets the most ``votes''. 1560The constraint letters @samp{g} and @samp{r} also vote: they vote in 1561favor of a general register. The machine description says which registers 1562are considered general. 1563 1564Of course, on some machines all registers are equivalent, and no register 1565classes are defined. Then none of this complexity is relevant. 1566@end ifset 1567 1568@node Modifiers 1569@subsection Constraint Modifier Characters 1570@cindex modifiers in constraints 1571@cindex constraint modifier characters 1572 1573@c prevent bad page break with this line 1574Here are constraint modifier characters. 1575 1576@table @samp 1577@cindex @samp{=} in constraint 1578@item = 1579Means that this operand is written to by this instruction: 1580the previous value is discarded and replaced by new data. 1581 1582@cindex @samp{+} in constraint 1583@item + 1584Means that this operand is both read and written by the instruction. 1585 1586When the compiler fixes up the operands to satisfy the constraints, 1587it needs to know which operands are read by the instruction and 1588which are written by it. @samp{=} identifies an operand which is only 1589written; @samp{+} identifies an operand that is both read and written; all 1590other operands are assumed to only be read. 1591 1592If you specify @samp{=} or @samp{+} in a constraint, you put it in the 1593first character of the constraint string. 1594 1595@cindex @samp{&} in constraint 1596@cindex earlyclobber operand 1597@item & 1598Means (in a particular alternative) that this operand is an 1599@dfn{earlyclobber} operand, which is written before the instruction is 1600finished using the input operands. Therefore, this operand may not lie 1601in a register that is read by the instruction or as part of any memory 1602address. 1603 1604@samp{&} applies only to the alternative in which it is written. In 1605constraints with multiple alternatives, sometimes one alternative 1606requires @samp{&} while others do not. See, for example, the 1607@samp{movdf} insn of the 68000. 1608 1609A operand which is read by the instruction can be tied to an earlyclobber 1610operand if its only use as an input occurs before the early result is 1611written. Adding alternatives of this form often allows GCC to produce 1612better code when only some of the read operands can be affected by the 1613earlyclobber. See, for example, the @samp{mulsi3} insn of the ARM@. 1614 1615Furthermore, if the @dfn{earlyclobber} operand is also a read/write 1616operand, then that operand is written only after it's used. 1617 1618@samp{&} does not obviate the need to write @samp{=} or @samp{+}. As 1619@dfn{earlyclobber} operands are always written, a read-only 1620@dfn{earlyclobber} operand is ill-formed and will be rejected by the 1621compiler. 1622 1623@cindex @samp{%} in constraint 1624@item % 1625Declares the instruction to be commutative for this operand and the 1626following operand. This means that the compiler may interchange the 1627two operands if that is the cheapest way to make all operands fit the 1628constraints. @samp{%} applies to all alternatives and must appear as 1629the first character in the constraint. Only read-only operands can use 1630@samp{%}. 1631 1632@ifset INTERNALS 1633This is often used in patterns for addition instructions 1634that really have only two operands: the result must go in one of the 1635arguments. Here for example, is how the 68000 halfword-add 1636instruction is defined: 1637 1638@smallexample 1639(define_insn "addhi3" 1640 [(set (match_operand:HI 0 "general_operand" "=m,r") 1641 (plus:HI (match_operand:HI 1 "general_operand" "%0,0") 1642 (match_operand:HI 2 "general_operand" "di,g")))] 1643 @dots{}) 1644@end smallexample 1645@end ifset 1646GCC can only handle one commutative pair in an asm; if you use more, 1647the compiler may fail. Note that you need not use the modifier if 1648the two alternatives are strictly identical; this would only waste 1649time in the reload pass. 1650@ifset INTERNALS 1651The modifier is not operational after 1652register allocation, so the result of @code{define_peephole2} 1653and @code{define_split}s performed after reload cannot rely on 1654@samp{%} to make the intended insn match. 1655 1656@cindex @samp{#} in constraint 1657@item # 1658Says that all following characters, up to the next comma, are to be 1659ignored as a constraint. They are significant only for choosing 1660register preferences. 1661 1662@cindex @samp{*} in constraint 1663@item * 1664Says that the following character should be ignored when choosing 1665register preferences. @samp{*} has no effect on the meaning of the 1666constraint as a constraint, and no effect on reloading. For LRA 1667@samp{*} additionally disparages slightly the alternative if the 1668following character matches the operand. 1669 1670Here is an example: the 68000 has an instruction to sign-extend a 1671halfword in a data register, and can also sign-extend a value by 1672copying it into an address register. While either kind of register is 1673acceptable, the constraints on an address-register destination are 1674less strict, so it is best if register allocation makes an address 1675register its goal. Therefore, @samp{*} is used so that the @samp{d} 1676constraint letter (for data register) is ignored when computing 1677register preferences. 1678 1679@smallexample 1680(define_insn "extendhisi2" 1681 [(set (match_operand:SI 0 "general_operand" "=*d,a") 1682 (sign_extend:SI 1683 (match_operand:HI 1 "general_operand" "0,g")))] 1684 @dots{}) 1685@end smallexample 1686@end ifset 1687@end table 1688 1689@node Machine Constraints 1690@subsection Constraints for Particular Machines 1691@cindex machine specific constraints 1692@cindex constraints, machine specific 1693 1694Whenever possible, you should use the general-purpose constraint letters 1695in @code{asm} arguments, since they will convey meaning more readily to 1696people reading your code. Failing that, use the constraint letters 1697that usually have very similar meanings across architectures. The most 1698commonly used constraints are @samp{m} and @samp{r} (for memory and 1699general-purpose registers respectively; @pxref{Simple Constraints}), and 1700@samp{I}, usually the letter indicating the most common 1701immediate-constant format. 1702 1703Each architecture defines additional constraints. These constraints 1704are used by the compiler itself for instruction generation, as well as 1705for @code{asm} statements; therefore, some of the constraints are not 1706particularly useful for @code{asm}. Here is a summary of some of the 1707machine-dependent constraints available on some particular machines; 1708it includes both constraints that are useful for @code{asm} and 1709constraints that aren't. The compiler source file mentioned in the 1710table heading for each architecture is the definitive reference for 1711the meanings of that architecture's constraints. 1712 1713@c Please keep this table alphabetized by target! 1714@table @emph 1715@item AArch64 family---@file{config/aarch64/constraints.md} 1716@table @code 1717@item k 1718The stack pointer register (@code{SP}) 1719 1720@item w 1721Floating point or SIMD vector register 1722 1723@item I 1724Integer constant that is valid as an immediate operand in an @code{ADD} 1725instruction 1726 1727@item J 1728Integer constant that is valid as an immediate operand in a @code{SUB} 1729instruction (once negated) 1730 1731@item K 1732Integer constant that can be used with a 32-bit logical instruction 1733 1734@item L 1735Integer constant that can be used with a 64-bit logical instruction 1736 1737@item M 1738Integer constant that is valid as an immediate operand in a 32-bit @code{MOV} 1739pseudo instruction. The @code{MOV} may be assembled to one of several different 1740machine instructions depending on the value 1741 1742@item N 1743Integer constant that is valid as an immediate operand in a 64-bit @code{MOV} 1744pseudo instruction 1745 1746@item S 1747An absolute symbolic address or a label reference 1748 1749@item Y 1750Floating point constant zero 1751 1752@item Z 1753Integer constant zero 1754 1755@item Ush 1756The high part (bits 12 and upwards) of the pc-relative address of a symbol 1757within 4GB of the instruction 1758 1759@item Q 1760A memory address which uses a single base register with no offset 1761 1762@item Ump 1763A memory address suitable for a load/store pair instruction in SI, DI, SF and 1764DF modes 1765 1766@end table 1767 1768 1769@item ARC ---@file{config/arc/constraints.md} 1770@table @code 1771@item q 1772Registers usable in ARCompact 16-bit instructions: @code{r0}-@code{r3}, 1773@code{r12}-@code{r15}. This constraint can only match when the @option{-mq} 1774option is in effect. 1775 1776@item e 1777Registers usable as base-regs of memory addresses in ARCompact 16-bit memory 1778instructions: @code{r0}-@code{r3}, @code{r12}-@code{r15}, @code{sp}. 1779This constraint can only match when the @option{-mq} 1780option is in effect. 1781@item D 1782ARC FPX (dpfp) 64-bit registers. @code{D0}, @code{D1}. 1783 1784@item I 1785A signed 12-bit integer constant. 1786 1787@item Cal 1788constant for arithmetic/logical operations. This might be any constant 1789that can be put into a long immediate by the assmbler or linker without 1790involving a PIC relocation. 1791 1792@item K 1793A 3-bit unsigned integer constant. 1794 1795@item L 1796A 6-bit unsigned integer constant. 1797 1798@item CnL 1799One's complement of a 6-bit unsigned integer constant. 1800 1801@item CmL 1802Two's complement of a 6-bit unsigned integer constant. 1803 1804@item M 1805A 5-bit unsigned integer constant. 1806 1807@item O 1808A 7-bit unsigned integer constant. 1809 1810@item P 1811A 8-bit unsigned integer constant. 1812 1813@item H 1814Any const_double value. 1815@end table 1816 1817@item ARM family---@file{config/arm/constraints.md} 1818@table @code 1819 1820@item h 1821In Thumb state, the core registers @code{r8}-@code{r15}. 1822 1823@item k 1824The stack pointer register. 1825 1826@item l 1827In Thumb State the core registers @code{r0}-@code{r7}. In ARM state this 1828is an alias for the @code{r} constraint. 1829 1830@item t 1831VFP floating-point registers @code{s0}-@code{s31}. Used for 32 bit values. 1832 1833@item w 1834VFP floating-point registers @code{d0}-@code{d31} and the appropriate 1835subset @code{d0}-@code{d15} based on command line options. 1836Used for 64 bit values only. Not valid for Thumb1. 1837 1838@item y 1839The iWMMX co-processor registers. 1840 1841@item z 1842The iWMMX GR registers. 1843 1844@item G 1845The floating-point constant 0.0 1846 1847@item I 1848Integer that is valid as an immediate operand in a data processing 1849instruction. That is, an integer in the range 0 to 255 rotated by a 1850multiple of 2 1851 1852@item J 1853Integer in the range @minus{}4095 to 4095 1854 1855@item K 1856Integer that satisfies constraint @samp{I} when inverted (ones complement) 1857 1858@item L 1859Integer that satisfies constraint @samp{I} when negated (twos complement) 1860 1861@item M 1862Integer in the range 0 to 32 1863 1864@item Q 1865A memory reference where the exact address is in a single register 1866(`@samp{m}' is preferable for @code{asm} statements) 1867 1868@item R 1869An item in the constant pool 1870 1871@item S 1872A symbol in the text segment of the current file 1873 1874@item Uv 1875A memory reference suitable for VFP load/store insns (reg+constant offset) 1876 1877@item Uy 1878A memory reference suitable for iWMMXt load/store instructions. 1879 1880@item Uq 1881A memory reference suitable for the ARMv4 ldrsb instruction. 1882@end table 1883 1884@item AVR family---@file{config/avr/constraints.md} 1885@table @code 1886@item l 1887Registers from r0 to r15 1888 1889@item a 1890Registers from r16 to r23 1891 1892@item d 1893Registers from r16 to r31 1894 1895@item w 1896Registers from r24 to r31. These registers can be used in @samp{adiw} command 1897 1898@item e 1899Pointer register (r26--r31) 1900 1901@item b 1902Base pointer register (r28--r31) 1903 1904@item q 1905Stack pointer register (SPH:SPL) 1906 1907@item t 1908Temporary register r0 1909 1910@item x 1911Register pair X (r27:r26) 1912 1913@item y 1914Register pair Y (r29:r28) 1915 1916@item z 1917Register pair Z (r31:r30) 1918 1919@item I 1920Constant greater than @minus{}1, less than 64 1921 1922@item J 1923Constant greater than @minus{}64, less than 1 1924 1925@item K 1926Constant integer 2 1927 1928@item L 1929Constant integer 0 1930 1931@item M 1932Constant that fits in 8 bits 1933 1934@item N 1935Constant integer @minus{}1 1936 1937@item O 1938Constant integer 8, 16, or 24 1939 1940@item P 1941Constant integer 1 1942 1943@item G 1944A floating point constant 0.0 1945 1946@item Q 1947A memory address based on Y or Z pointer with displacement. 1948@end table 1949 1950@item Blackfin family---@file{config/bfin/constraints.md} 1951@table @code 1952@item a 1953P register 1954 1955@item d 1956D register 1957 1958@item z 1959A call clobbered P register. 1960 1961@item q@var{n} 1962A single register. If @var{n} is in the range 0 to 7, the corresponding D 1963register. If it is @code{A}, then the register P0. 1964 1965@item D 1966Even-numbered D register 1967 1968@item W 1969Odd-numbered D register 1970 1971@item e 1972Accumulator register. 1973 1974@item A 1975Even-numbered accumulator register. 1976 1977@item B 1978Odd-numbered accumulator register. 1979 1980@item b 1981I register 1982 1983@item v 1984B register 1985 1986@item f 1987M register 1988 1989@item c 1990Registers used for circular buffering, i.e. I, B, or L registers. 1991 1992@item C 1993The CC register. 1994 1995@item t 1996LT0 or LT1. 1997 1998@item k 1999LC0 or LC1. 2000 2001@item u 2002LB0 or LB1. 2003 2004@item x 2005Any D, P, B, M, I or L register. 2006 2007@item y 2008Additional registers typically used only in prologues and epilogues: RETS, 2009RETN, RETI, RETX, RETE, ASTAT, SEQSTAT and USP. 2010 2011@item w 2012Any register except accumulators or CC. 2013 2014@item Ksh 2015Signed 16 bit integer (in the range @minus{}32768 to 32767) 2016 2017@item Kuh 2018Unsigned 16 bit integer (in the range 0 to 65535) 2019 2020@item Ks7 2021Signed 7 bit integer (in the range @minus{}64 to 63) 2022 2023@item Ku7 2024Unsigned 7 bit integer (in the range 0 to 127) 2025 2026@item Ku5 2027Unsigned 5 bit integer (in the range 0 to 31) 2028 2029@item Ks4 2030Signed 4 bit integer (in the range @minus{}8 to 7) 2031 2032@item Ks3 2033Signed 3 bit integer (in the range @minus{}3 to 4) 2034 2035@item Ku3 2036Unsigned 3 bit integer (in the range 0 to 7) 2037 2038@item P@var{n} 2039Constant @var{n}, where @var{n} is a single-digit constant in the range 0 to 4. 2040 2041@item PA 2042An integer equal to one of the MACFLAG_XXX constants that is suitable for 2043use with either accumulator. 2044 2045@item PB 2046An integer equal to one of the MACFLAG_XXX constants that is suitable for 2047use only with accumulator A1. 2048 2049@item M1 2050Constant 255. 2051 2052@item M2 2053Constant 65535. 2054 2055@item J 2056An integer constant with exactly a single bit set. 2057 2058@item L 2059An integer constant with all bits set except exactly one. 2060 2061@item H 2062 2063@item Q 2064Any SYMBOL_REF. 2065@end table 2066 2067@item CR16 Architecture---@file{config/cr16/cr16.h} 2068@table @code 2069 2070@item b 2071Registers from r0 to r14 (registers without stack pointer) 2072 2073@item t 2074Register from r0 to r11 (all 16-bit registers) 2075 2076@item p 2077Register from r12 to r15 (all 32-bit registers) 2078 2079@item I 2080Signed constant that fits in 4 bits 2081 2082@item J 2083Signed constant that fits in 5 bits 2084 2085@item K 2086Signed constant that fits in 6 bits 2087 2088@item L 2089Unsigned constant that fits in 4 bits 2090 2091@item M 2092Signed constant that fits in 32 bits 2093 2094@item N 2095Check for 64 bits wide constants for add/sub instructions 2096 2097@item G 2098Floating point constant that is legal for store immediate 2099@end table 2100 2101@item Epiphany---@file{config/epiphany/constraints.md} 2102@table @code 2103@item U16 2104An unsigned 16-bit constant. 2105 2106@item K 2107An unsigned 5-bit constant. 2108 2109@item L 2110A signed 11-bit constant. 2111 2112@item Cm1 2113A signed 11-bit constant added to @minus{}1. 2114Can only match when the @option{-m1reg-@var{reg}} option is active. 2115 2116@item Cl1 2117Left-shift of @minus{}1, i.e., a bit mask with a block of leading ones, the rest 2118being a block of trailing zeroes. 2119Can only match when the @option{-m1reg-@var{reg}} option is active. 2120 2121@item Cr1 2122Right-shift of @minus{}1, i.e., a bit mask with a trailing block of ones, the 2123rest being zeroes. Or to put it another way, one less than a power of two. 2124Can only match when the @option{-m1reg-@var{reg}} option is active. 2125 2126@item Cal 2127Constant for arithmetic/logical operations. 2128This is like @code{i}, except that for position independent code, 2129no symbols / expressions needing relocations are allowed. 2130 2131@item Csy 2132Symbolic constant for call/jump instruction. 2133 2134@item Rcs 2135The register class usable in short insns. This is a register class 2136constraint, and can thus drive register allocation. 2137This constraint won't match unless @option{-mprefer-short-insn-regs} is 2138in effect. 2139 2140@item Rsc 2141The the register class of registers that can be used to hold a 2142sibcall call address. I.e., a caller-saved register. 2143 2144@item Rct 2145Core control register class. 2146 2147@item Rgs 2148The register group usable in short insns. 2149This constraint does not use a register class, so that it only 2150passively matches suitable registers, and doesn't drive register allocation. 2151 2152@ifset INTERNALS 2153@item Car 2154Constant suitable for the addsi3_r pattern. This is a valid offset 2155For byte, halfword, or word addressing. 2156@end ifset 2157 2158@item Rra 2159Matches the return address if it can be replaced with the link register. 2160 2161@item Rcc 2162Matches the integer condition code register. 2163 2164@item Sra 2165Matches the return address if it is in a stack slot. 2166 2167@item Cfm 2168Matches control register values to switch fp mode, which are encapsulated in 2169@code{UNSPEC_FP_MODE}. 2170@end table 2171 2172@item FRV---@file{config/frv/frv.h} 2173@table @code 2174@item a 2175Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}). 2176 2177@item b 2178Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}). 2179 2180@item c 2181Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and 2182@code{icc0} to @code{icc3}). 2183 2184@item d 2185Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}). 2186 2187@item e 2188Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}). 2189Odd registers are excluded not in the class but through the use of a machine 2190mode larger than 4 bytes. 2191 2192@item f 2193Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}). 2194 2195@item h 2196Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}). 2197Odd registers are excluded not in the class but through the use of a machine 2198mode larger than 4 bytes. 2199 2200@item l 2201Register in the class @code{LR_REG} (the @code{lr} register). 2202 2203@item q 2204Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}). 2205Register numbers not divisible by 4 are excluded not in the class but through 2206the use of a machine mode larger than 8 bytes. 2207 2208@item t 2209Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}). 2210 2211@item u 2212Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}). 2213 2214@item v 2215Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}). 2216 2217@item w 2218Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}). 2219 2220@item x 2221Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}). 2222Register numbers not divisible by 4 are excluded not in the class but through 2223the use of a machine mode larger than 8 bytes. 2224 2225@item z 2226Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}). 2227 2228@item A 2229Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}). 2230 2231@item B 2232Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}). 2233 2234@item C 2235Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}). 2236 2237@item G 2238Floating point constant zero 2239 2240@item I 22416-bit signed integer constant 2242 2243@item J 224410-bit signed integer constant 2245 2246@item L 224716-bit signed integer constant 2248 2249@item M 225016-bit unsigned integer constant 2251 2252@item N 225312-bit signed integer constant that is negative---i.e.@: in the 2254range of @minus{}2048 to @minus{}1 2255 2256@item O 2257Constant zero 2258 2259@item P 226012-bit signed integer constant that is greater than zero---i.e.@: in the 2261range of 1 to 2047. 2262 2263@end table 2264 2265@item FT32---@file{config/ft32/constraints.md} 2266@table @code 2267@item A 2268An absolute address 2269 2270@item B 2271An offset address 2272 2273@item W 2274A register indirect memory operand 2275 2276@item e 2277An offset address. 2278 2279@item f 2280An offset address. 2281 2282@item O 2283The constant zero or one 2284 2285@item I 2286A 16-bit signed constant (@minus{}32768 @dots{} 32767) 2287 2288@item w 2289A bitfield mask suitable for bext or bins 2290 2291@item x 2292An inverted bitfield mask suitable for bext or bins 2293 2294@item L 2295A 16-bit unsigned constant, multiple of 4 (0 @dots{} 65532) 2296 2297@item S 2298A 20-bit signed constant (@minus{}524288 @dots{} 524287) 2299 2300@item b 2301A constant for a bitfield width (1 @dots{} 16) 2302 2303@item KA 2304A 10-bit signed constant (@minus{}512 @dots{} 511) 2305 2306@end table 2307 2308@item Hewlett-Packard PA-RISC---@file{config/pa/pa.h} 2309@table @code 2310@item a 2311General register 1 2312 2313@item f 2314Floating point register 2315 2316@item q 2317Shift amount register 2318 2319@item x 2320Floating point register (deprecated) 2321 2322@item y 2323Upper floating point register (32-bit), floating point register (64-bit) 2324 2325@item Z 2326Any register 2327 2328@item I 2329Signed 11-bit integer constant 2330 2331@item J 2332Signed 14-bit integer constant 2333 2334@item K 2335Integer constant that can be deposited with a @code{zdepi} instruction 2336 2337@item L 2338Signed 5-bit integer constant 2339 2340@item M 2341Integer constant 0 2342 2343@item N 2344Integer constant that can be loaded with a @code{ldil} instruction 2345 2346@item O 2347Integer constant whose value plus one is a power of 2 2348 2349@item P 2350Integer constant that can be used for @code{and} operations in @code{depi} 2351and @code{extru} instructions 2352 2353@item S 2354Integer constant 31 2355 2356@item U 2357Integer constant 63 2358 2359@item G 2360Floating-point constant 0.0 2361 2362@item A 2363A @code{lo_sum} data-linkage-table memory operand 2364 2365@item Q 2366A memory operand that can be used as the destination operand of an 2367integer store instruction 2368 2369@item R 2370A scaled or unscaled indexed memory operand 2371 2372@item T 2373A memory operand for floating-point loads and stores 2374 2375@item W 2376A register indirect memory operand 2377@end table 2378 2379@item Intel IA-64---@file{config/ia64/ia64.h} 2380@table @code 2381@item a 2382General register @code{r0} to @code{r3} for @code{addl} instruction 2383 2384@item b 2385Branch register 2386 2387@item c 2388Predicate register (@samp{c} as in ``conditional'') 2389 2390@item d 2391Application register residing in M-unit 2392 2393@item e 2394Application register residing in I-unit 2395 2396@item f 2397Floating-point register 2398 2399@item m 2400Memory operand. If used together with @samp{<} or @samp{>}, 2401the operand can have postincrement and postdecrement which 2402require printing with @samp{%Pn} on IA-64. 2403 2404@item G 2405Floating-point constant 0.0 or 1.0 2406 2407@item I 240814-bit signed integer constant 2409 2410@item J 241122-bit signed integer constant 2412 2413@item K 24148-bit signed integer constant for logical instructions 2415 2416@item L 24178-bit adjusted signed integer constant for compare pseudo-ops 2418 2419@item M 24206-bit unsigned integer constant for shift counts 2421 2422@item N 24239-bit signed integer constant for load and store postincrements 2424 2425@item O 2426The constant zero 2427 2428@item P 24290 or @minus{}1 for @code{dep} instruction 2430 2431@item Q 2432Non-volatile memory for floating-point loads and stores 2433 2434@item R 2435Integer constant in the range 1 to 4 for @code{shladd} instruction 2436 2437@item S 2438Memory operand except postincrement and postdecrement. This is 2439now roughly the same as @samp{m} when not used together with @samp{<} 2440or @samp{>}. 2441@end table 2442 2443@item M32C---@file{config/m32c/m32c.c} 2444@table @code 2445@item Rsp 2446@itemx Rfb 2447@itemx Rsb 2448@samp{$sp}, @samp{$fb}, @samp{$sb}. 2449 2450@item Rcr 2451Any control register, when they're 16 bits wide (nothing if control 2452registers are 24 bits wide) 2453 2454@item Rcl 2455Any control register, when they're 24 bits wide. 2456 2457@item R0w 2458@itemx R1w 2459@itemx R2w 2460@itemx R3w 2461$r0, $r1, $r2, $r3. 2462 2463@item R02 2464$r0 or $r2, or $r2r0 for 32 bit values. 2465 2466@item R13 2467$r1 or $r3, or $r3r1 for 32 bit values. 2468 2469@item Rdi 2470A register that can hold a 64 bit value. 2471 2472@item Rhl 2473$r0 or $r1 (registers with addressable high/low bytes) 2474 2475@item R23 2476$r2 or $r3 2477 2478@item Raa 2479Address registers 2480 2481@item Raw 2482Address registers when they're 16 bits wide. 2483 2484@item Ral 2485Address registers when they're 24 bits wide. 2486 2487@item Rqi 2488Registers that can hold QI values. 2489 2490@item Rad 2491Registers that can be used with displacements ($a0, $a1, $sb). 2492 2493@item Rsi 2494Registers that can hold 32 bit values. 2495 2496@item Rhi 2497Registers that can hold 16 bit values. 2498 2499@item Rhc 2500Registers chat can hold 16 bit values, including all control 2501registers. 2502 2503@item Rra 2504$r0 through R1, plus $a0 and $a1. 2505 2506@item Rfl 2507The flags register. 2508 2509@item Rmm 2510The memory-based pseudo-registers $mem0 through $mem15. 2511 2512@item Rpi 2513Registers that can hold pointers (16 bit registers for r8c, m16c; 24 2514bit registers for m32cm, m32c). 2515 2516@item Rpa 2517Matches multiple registers in a PARALLEL to form a larger register. 2518Used to match function return values. 2519 2520@item Is3 2521@minus{}8 @dots{} 7 2522 2523@item IS1 2524@minus{}128 @dots{} 127 2525 2526@item IS2 2527@minus{}32768 @dots{} 32767 2528 2529@item IU2 25300 @dots{} 65535 2531 2532@item In4 2533@minus{}8 @dots{} @minus{}1 or 1 @dots{} 8 2534 2535@item In5 2536@minus{}16 @dots{} @minus{}1 or 1 @dots{} 16 2537 2538@item In6 2539@minus{}32 @dots{} @minus{}1 or 1 @dots{} 32 2540 2541@item IM2 2542@minus{}65536 @dots{} @minus{}1 2543 2544@item Ilb 2545An 8 bit value with exactly one bit set. 2546 2547@item Ilw 2548A 16 bit value with exactly one bit set. 2549 2550@item Sd 2551The common src/dest memory addressing modes. 2552 2553@item Sa 2554Memory addressed using $a0 or $a1. 2555 2556@item Si 2557Memory addressed with immediate addresses. 2558 2559@item Ss 2560Memory addressed using the stack pointer ($sp). 2561 2562@item Sf 2563Memory addressed using the frame base register ($fb). 2564 2565@item Ss 2566Memory addressed using the small base register ($sb). 2567 2568@item S1 2569$r1h 2570@end table 2571 2572@item MeP---@file{config/mep/constraints.md} 2573@table @code 2574 2575@item a 2576The $sp register. 2577 2578@item b 2579The $tp register. 2580 2581@item c 2582Any control register. 2583 2584@item d 2585Either the $hi or the $lo register. 2586 2587@item em 2588Coprocessor registers that can be directly loaded ($c0-$c15). 2589 2590@item ex 2591Coprocessor registers that can be moved to each other. 2592 2593@item er 2594Coprocessor registers that can be moved to core registers. 2595 2596@item h 2597The $hi register. 2598 2599@item j 2600The $rpc register. 2601 2602@item l 2603The $lo register. 2604 2605@item t 2606Registers which can be used in $tp-relative addressing. 2607 2608@item v 2609The $gp register. 2610 2611@item x 2612The coprocessor registers. 2613 2614@item y 2615The coprocessor control registers. 2616 2617@item z 2618The $0 register. 2619 2620@item A 2621User-defined register set A. 2622 2623@item B 2624User-defined register set B. 2625 2626@item C 2627User-defined register set C. 2628 2629@item D 2630User-defined register set D. 2631 2632@item I 2633Offsets for $gp-rel addressing. 2634 2635@item J 2636Constants that can be used directly with boolean insns. 2637 2638@item K 2639Constants that can be moved directly to registers. 2640 2641@item L 2642Small constants that can be added to registers. 2643 2644@item M 2645Long shift counts. 2646 2647@item N 2648Small constants that can be compared to registers. 2649 2650@item O 2651Constants that can be loaded into the top half of registers. 2652 2653@item S 2654Signed 8-bit immediates. 2655 2656@item T 2657Symbols encoded for $tp-rel or $gp-rel addressing. 2658 2659@item U 2660Non-constant addresses for loading/saving coprocessor registers. 2661 2662@item W 2663The top half of a symbol's value. 2664 2665@item Y 2666A register indirect address without offset. 2667 2668@item Z 2669Symbolic references to the control bus. 2670 2671@end table 2672 2673@item MicroBlaze---@file{config/microblaze/constraints.md} 2674@table @code 2675@item d 2676A general register (@code{r0} to @code{r31}). 2677 2678@item z 2679A status register (@code{rmsr}, @code{$fcc1} to @code{$fcc7}). 2680 2681@end table 2682 2683@item MIPS---@file{config/mips/constraints.md} 2684@table @code 2685@item d 2686An address register. This is equivalent to @code{r} unless 2687generating MIPS16 code. 2688 2689@item f 2690A floating-point register (if available). 2691 2692@item h 2693Formerly the @code{hi} register. This constraint is no longer supported. 2694 2695@item l 2696The @code{lo} register. Use this register to store values that are 2697no bigger than a word. 2698 2699@item x 2700The concatenated @code{hi} and @code{lo} registers. Use this register 2701to store doubleword values. 2702 2703@item c 2704A register suitable for use in an indirect jump. This will always be 2705@code{$25} for @option{-mabicalls}. 2706 2707@item v 2708Register @code{$3}. Do not use this constraint in new code; 2709it is retained only for compatibility with glibc. 2710 2711@item y 2712Equivalent to @code{r}; retained for backwards compatibility. 2713 2714@item z 2715A floating-point condition code register. 2716 2717@item I 2718A signed 16-bit constant (for arithmetic instructions). 2719 2720@item J 2721Integer zero. 2722 2723@item K 2724An unsigned 16-bit constant (for logic instructions). 2725 2726@item L 2727A signed 32-bit constant in which the lower 16 bits are zero. 2728Such constants can be loaded using @code{lui}. 2729 2730@item M 2731A constant that cannot be loaded using @code{lui}, @code{addiu} 2732or @code{ori}. 2733 2734@item N 2735A constant in the range @minus{}65535 to @minus{}1 (inclusive). 2736 2737@item O 2738A signed 15-bit constant. 2739 2740@item P 2741A constant in the range 1 to 65535 (inclusive). 2742 2743@item G 2744Floating-point zero. 2745 2746@item R 2747An address that can be used in a non-macro load or store. 2748 2749@item ZC 2750A memory operand whose address is formed by a base register and offset 2751that is suitable for use in instructions with the same addressing mode 2752as @code{ll} and @code{sc}. 2753 2754@item ZD 2755An address suitable for a @code{prefetch} instruction, or for any other 2756instruction with the same addressing mode as @code{prefetch}. 2757@end table 2758 2759@item Motorola 680x0---@file{config/m68k/constraints.md} 2760@table @code 2761@item a 2762Address register 2763 2764@item d 2765Data register 2766 2767@item f 276868881 floating-point register, if available 2769 2770@item I 2771Integer in the range 1 to 8 2772 2773@item J 277416-bit signed number 2775 2776@item K 2777Signed number whose magnitude is greater than 0x80 2778 2779@item L 2780Integer in the range @minus{}8 to @minus{}1 2781 2782@item M 2783Signed number whose magnitude is greater than 0x100 2784 2785@item N 2786Range 24 to 31, rotatert:SI 8 to 1 expressed as rotate 2787 2788@item O 278916 (for rotate using swap) 2790 2791@item P 2792Range 8 to 15, rotatert:HI 8 to 1 expressed as rotate 2793 2794@item R 2795Numbers that mov3q can handle 2796 2797@item G 2798Floating point constant that is not a 68881 constant 2799 2800@item S 2801Operands that satisfy 'm' when -mpcrel is in effect 2802 2803@item T 2804Operands that satisfy 's' when -mpcrel is not in effect 2805 2806@item Q 2807Address register indirect addressing mode 2808 2809@item U 2810Register offset addressing 2811 2812@item W 2813const_call_operand 2814 2815@item Cs 2816symbol_ref or const 2817 2818@item Ci 2819const_int 2820 2821@item C0 2822const_int 0 2823 2824@item Cj 2825Range of signed numbers that don't fit in 16 bits 2826 2827@item Cmvq 2828Integers valid for mvq 2829 2830@item Capsw 2831Integers valid for a moveq followed by a swap 2832 2833@item Cmvz 2834Integers valid for mvz 2835 2836@item Cmvs 2837Integers valid for mvs 2838 2839@item Ap 2840push_operand 2841 2842@item Ac 2843Non-register operands allowed in clr 2844 2845@end table 2846 2847@item Moxie---@file{config/moxie/constraints.md} 2848@table @code 2849@item A 2850An absolute address 2851 2852@item B 2853An offset address 2854 2855@item W 2856A register indirect memory operand 2857 2858@item I 2859A constant in the range of 0 to 255. 2860 2861@item N 2862A constant in the range of 0 to @minus{}255. 2863 2864@end table 2865 2866@item MSP430--@file{config/msp430/constraints.md} 2867@table @code 2868 2869@item R12 2870Register R12. 2871 2872@item R13 2873Register R13. 2874 2875@item K 2876Integer constant 1. 2877 2878@item L 2879Integer constant -1^20..1^19. 2880 2881@item M 2882Integer constant 1-4. 2883 2884@item Ya 2885Memory references which do not require an extended MOVX instruction. 2886 2887@item Yl 2888Memory reference, labels only. 2889 2890@item Ys 2891Memory reference, stack only. 2892 2893@end table 2894 2895@item NDS32---@file{config/nds32/constraints.md} 2896@table @code 2897@item w 2898LOW register class $r0 to $r7 constraint for V3/V3M ISA. 2899@item l 2900LOW register class $r0 to $r7. 2901@item d 2902MIDDLE register class $r0 to $r11, $r16 to $r19. 2903@item h 2904HIGH register class $r12 to $r14, $r20 to $r31. 2905@item t 2906Temporary assist register $ta (i.e.@: $r15). 2907@item k 2908Stack register $sp. 2909@item Iu03 2910Unsigned immediate 3-bit value. 2911@item In03 2912Negative immediate 3-bit value in the range of @minus{}7--0. 2913@item Iu04 2914Unsigned immediate 4-bit value. 2915@item Is05 2916Signed immediate 5-bit value. 2917@item Iu05 2918Unsigned immediate 5-bit value. 2919@item In05 2920Negative immediate 5-bit value in the range of @minus{}31--0. 2921@item Ip05 2922Unsigned immediate 5-bit value for movpi45 instruction with range 16--47. 2923@item Iu06 2924Unsigned immediate 6-bit value constraint for addri36.sp instruction. 2925@item Iu08 2926Unsigned immediate 8-bit value. 2927@item Iu09 2928Unsigned immediate 9-bit value. 2929@item Is10 2930Signed immediate 10-bit value. 2931@item Is11 2932Signed immediate 11-bit value. 2933@item Is15 2934Signed immediate 15-bit value. 2935@item Iu15 2936Unsigned immediate 15-bit value. 2937@item Ic15 2938A constant which is not in the range of imm15u but ok for bclr instruction. 2939@item Ie15 2940A constant which is not in the range of imm15u but ok for bset instruction. 2941@item It15 2942A constant which is not in the range of imm15u but ok for btgl instruction. 2943@item Ii15 2944A constant whose compliment value is in the range of imm15u 2945and ok for bitci instruction. 2946@item Is16 2947Signed immediate 16-bit value. 2948@item Is17 2949Signed immediate 17-bit value. 2950@item Is19 2951Signed immediate 19-bit value. 2952@item Is20 2953Signed immediate 20-bit value. 2954@item Ihig 2955The immediate value that can be simply set high 20-bit. 2956@item Izeb 2957The immediate value 0xff. 2958@item Izeh 2959The immediate value 0xffff. 2960@item Ixls 2961The immediate value 0x01. 2962@item Ix11 2963The immediate value 0x7ff. 2964@item Ibms 2965The immediate value with power of 2. 2966@item Ifex 2967The immediate value with power of 2 minus 1. 2968@item U33 2969Memory constraint for 333 format. 2970@item U45 2971Memory constraint for 45 format. 2972@item U37 2973Memory constraint for 37 format. 2974@end table 2975 2976@item Nios II family---@file{config/nios2/constraints.md} 2977@table @code 2978 2979@item I 2980Integer that is valid as an immediate operand in an 2981instruction taking a signed 16-bit number. Range 2982@minus{}32768 to 32767. 2983 2984@item J 2985Integer that is valid as an immediate operand in an 2986instruction taking an unsigned 16-bit number. Range 29870 to 65535. 2988 2989@item K 2990Integer that is valid as an immediate operand in an 2991instruction taking only the upper 16-bits of a 299232-bit number. Range 32-bit numbers with the lower 299316-bits being 0. 2994 2995@item L 2996Integer that is valid as an immediate operand for a 2997shift instruction. Range 0 to 31. 2998 2999@item M 3000Integer that is valid as an immediate operand for 3001only the value 0. Can be used in conjunction with 3002the format modifier @code{z} to use @code{r0} 3003instead of @code{0} in the assembly output. 3004 3005@item N 3006Integer that is valid as an immediate operand for 3007a custom instruction opcode. Range 0 to 255. 3008 3009@item P 3010An immediate operand for R2 andchi/andci instructions. 3011 3012@item S 3013Matches immediates which are addresses in the small 3014data section and therefore can be added to @code{gp} 3015as a 16-bit immediate to re-create their 32-bit value. 3016 3017@item U 3018Matches constants suitable as an operand for the rdprs and 3019cache instructions. 3020 3021@item v 3022A memory operand suitable for Nios II R2 load/store 3023exclusive instructions. 3024 3025@item w 3026A memory operand suitable for load/store IO and cache 3027instructions. 3028 3029@ifset INTERNALS 3030@item T 3031A @code{const} wrapped @code{UNSPEC} expression, 3032representing a supported PIC or TLS relocation. 3033@end ifset 3034 3035@end table 3036 3037@item PDP-11---@file{config/pdp11/constraints.md} 3038@table @code 3039@item a 3040Floating point registers AC0 through AC3. These can be loaded from/to 3041memory with a single instruction. 3042 3043@item d 3044Odd numbered general registers (R1, R3, R5). These are used for 304516-bit multiply operations. 3046 3047@item f 3048Any of the floating point registers (AC0 through AC5). 3049 3050@item G 3051Floating point constant 0. 3052 3053@item I 3054An integer constant that fits in 16 bits. 3055 3056@item J 3057An integer constant whose low order 16 bits are zero. 3058 3059@item K 3060An integer constant that does not meet the constraints for codes 3061@samp{I} or @samp{J}. 3062 3063@item L 3064The integer constant 1. 3065 3066@item M 3067The integer constant @minus{}1. 3068 3069@item N 3070The integer constant 0. 3071 3072@item O 3073Integer constants @minus{}4 through @minus{}1 and 1 through 4; shifts by these 3074amounts are handled as multiple single-bit shifts rather than a single 3075variable-length shift. 3076 3077@item Q 3078A memory reference which requires an additional word (address or 3079offset) after the opcode. 3080 3081@item R 3082A memory reference that is encoded within the opcode. 3083 3084@end table 3085 3086@item PowerPC and IBM RS6000---@file{config/rs6000/constraints.md} 3087@table @code 3088@item b 3089Address base register 3090 3091@item d 3092Floating point register (containing 64-bit value) 3093 3094@item f 3095Floating point register (containing 32-bit value) 3096 3097@item v 3098Altivec vector register 3099 3100@item wa 3101Any VSX register if the -mvsx option was used or NO_REGS. 3102 3103When using any of the register constraints (@code{wa}, @code{wd}, 3104@code{wf}, @code{wg}, @code{wh}, @code{wi}, @code{wj}, @code{wk}, 3105@code{wl}, @code{wm}, @code{wo}, @code{wp}, @code{wq}, @code{ws}, 3106@code{wt}, @code{wu}, @code{wv}, @code{ww}, or @code{wy}) 3107that take VSX registers, you must use @code{%x<n>} in the template so 3108that the correct register is used. Otherwise the register number 3109output in the assembly file will be incorrect if an Altivec register 3110is an operand of a VSX instruction that expects VSX register 3111numbering. 3112 3113@smallexample 3114asm ("xvadddp %x0,%x1,%x2" : "=wa" (v1) : "wa" (v2), "wa" (v3)); 3115@end smallexample 3116 3117is correct, but: 3118 3119@smallexample 3120asm ("xvadddp %0,%1,%2" : "=wa" (v1) : "wa" (v2), "wa" (v3)); 3121@end smallexample 3122 3123is not correct. 3124 3125If an instruction only takes Altivec registers, you do not want to use 3126@code{%x<n>}. 3127 3128@smallexample 3129asm ("xsaddqp %0,%1,%2" : "=v" (v1) : "v" (v2), "v" (v3)); 3130@end smallexample 3131 3132is correct because the @code{xsaddqp} instruction only takes Altivec 3133registers, while: 3134 3135@smallexample 3136asm ("xsaddqp %x0,%x1,%x2" : "=v" (v1) : "v" (v2), "v" (v3)); 3137@end smallexample 3138 3139is incorrect. 3140 3141@item wb 3142Altivec register if @option{-mcpu=power9} is used or NO_REGS. 3143 3144@item wd 3145VSX vector register to hold vector double data or NO_REGS. 3146 3147@item we 3148VSX register if the @option{-mcpu=power9} and @option{-m64} options 3149were used or NO_REGS. 3150 3151@item wf 3152VSX vector register to hold vector float data or NO_REGS. 3153 3154@item wg 3155If @option{-mmfpgpr} was used, a floating point register or NO_REGS. 3156 3157@item wh 3158Floating point register if direct moves are available, or NO_REGS. 3159 3160@item wi 3161FP or VSX register to hold 64-bit integers for VSX insns or NO_REGS. 3162 3163@item wj 3164FP or VSX register to hold 64-bit integers for direct moves or NO_REGS. 3165 3166@item wk 3167FP or VSX register to hold 64-bit doubles for direct moves or NO_REGS. 3168 3169@item wl 3170Floating point register if the LFIWAX instruction is enabled or NO_REGS. 3171 3172@item wm 3173VSX register if direct move instructions are enabled, or NO_REGS. 3174 3175@item wn 3176No register (NO_REGS). 3177 3178@item wo 3179VSX register to use for ISA 3.0 vector instructions, or NO_REGS. 3180 3181@item wp 3182VSX register to use for IEEE 128-bit floating point TFmode, or NO_REGS. 3183 3184@item wq 3185VSX register to use for IEEE 128-bit floating point, or NO_REGS. 3186 3187@item wr 3188General purpose register if 64-bit instructions are enabled or NO_REGS. 3189 3190@item ws 3191VSX vector register to hold scalar double values or NO_REGS. 3192 3193@item wt 3194VSX vector register to hold 128 bit integer or NO_REGS. 3195 3196@item wu 3197Altivec register to use for float/32-bit int loads/stores or NO_REGS. 3198 3199@item wv 3200Altivec register to use for double loads/stores or NO_REGS. 3201 3202@item ww 3203FP or VSX register to perform float operations under @option{-mvsx} or NO_REGS. 3204 3205@item wx 3206Floating point register if the STFIWX instruction is enabled or NO_REGS. 3207 3208@item wy 3209FP or VSX register to perform ISA 2.07 float ops or NO_REGS. 3210 3211@item wz 3212Floating point register if the LFIWZX instruction is enabled or NO_REGS. 3213 3214@item wA 3215Address base register if 64-bit instructions are enabled or NO_REGS. 3216 3217@item wD 3218Int constant that is the element number of the 64-bit scalar in a vector. 3219 3220@item wE 3221Vector constant that can be loaded with the XXSPLTIB instruction. 3222 3223@item wF 3224Memory operand suitable for power9 fusion load/stores. 3225 3226@item wG 3227Memory operand suitable for TOC fusion memory references. 3228 3229@item wL 3230Int constant that is the element number that the MFVSRLD instruction. 3231targets. 3232 3233@item wM 3234Match vector constant with all 1's if the XXLORC instruction is available. 3235 3236@item wO 3237A memory operand suitable for the ISA 3.0 vector d-form instructions. 3238 3239@item wQ 3240A memory address that will work with the @code{lq} and @code{stq} 3241instructions. 3242 3243@item wS 3244Vector constant that can be loaded with XXSPLTIB & sign extension. 3245 3246@item h 3247@samp{MQ}, @samp{CTR}, or @samp{LINK} register 3248 3249@item c 3250@samp{CTR} register 3251 3252@item l 3253@samp{LINK} register 3254 3255@item x 3256@samp{CR} register (condition register) number 0 3257 3258@item y 3259@samp{CR} register (condition register) 3260 3261@item z 3262@samp{XER[CA]} carry bit (part of the XER register) 3263 3264@item I 3265Signed 16-bit constant 3266 3267@item J 3268Unsigned 16-bit constant shifted left 16 bits (use @samp{L} instead for 3269@code{SImode} constants) 3270 3271@item K 3272Unsigned 16-bit constant 3273 3274@item L 3275Signed 16-bit constant shifted left 16 bits 3276 3277@item M 3278Constant larger than 31 3279 3280@item N 3281Exact power of 2 3282 3283@item O 3284Zero 3285 3286@item P 3287Constant whose negation is a signed 16-bit constant 3288 3289@item G 3290Floating point constant that can be loaded into a register with one 3291instruction per word 3292 3293@item H 3294Integer/Floating point constant that can be loaded into a register using 3295three instructions 3296 3297@item m 3298Memory operand. 3299Normally, @code{m} does not allow addresses that update the base register. 3300If @samp{<} or @samp{>} constraint is also used, they are allowed and 3301therefore on PowerPC targets in that case it is only safe 3302to use @samp{m<>} in an @code{asm} statement if that @code{asm} statement 3303accesses the operand exactly once. The @code{asm} statement must also 3304use @samp{%U@var{<opno>}} as a placeholder for the ``update'' flag in the 3305corresponding load or store instruction. For example: 3306 3307@smallexample 3308asm ("st%U0 %1,%0" : "=m<>" (mem) : "r" (val)); 3309@end smallexample 3310 3311is correct but: 3312 3313@smallexample 3314asm ("st %1,%0" : "=m<>" (mem) : "r" (val)); 3315@end smallexample 3316 3317is not. 3318 3319@item es 3320A ``stable'' memory operand; that is, one which does not include any 3321automodification of the base register. This used to be useful when 3322@samp{m} allowed automodification of the base register, but as those are now only 3323allowed when @samp{<} or @samp{>} is used, @samp{es} is basically the same 3324as @samp{m} without @samp{<} and @samp{>}. 3325 3326@item Q 3327Memory operand that is an offset from a register (it is usually better 3328to use @samp{m} or @samp{es} in @code{asm} statements) 3329 3330@item Z 3331Memory operand that is an indexed or indirect from a register (it is 3332usually better to use @samp{m} or @samp{es} in @code{asm} statements) 3333 3334@item R 3335AIX TOC entry 3336 3337@item a 3338Address operand that is an indexed or indirect from a register (@samp{p} is 3339preferable for @code{asm} statements) 3340 3341@item U 3342System V Release 4 small data area reference 3343 3344@item W 3345Vector constant that does not require memory 3346 3347@item j 3348Vector constant that is all zeros. 3349 3350@end table 3351 3352@item RL78---@file{config/rl78/constraints.md} 3353@table @code 3354 3355@item Int3 3356An integer constant in the range 1 @dots{} 7. 3357@item Int8 3358An integer constant in the range 0 @dots{} 255. 3359@item J 3360An integer constant in the range @minus{}255 @dots{} 0 3361@item K 3362The integer constant 1. 3363@item L 3364The integer constant -1. 3365@item M 3366The integer constant 0. 3367@item N 3368The integer constant 2. 3369@item O 3370The integer constant -2. 3371@item P 3372An integer constant in the range 1 @dots{} 15. 3373@item Qbi 3374The built-in compare types--eq, ne, gtu, ltu, geu, and leu. 3375@item Qsc 3376The synthetic compare types--gt, lt, ge, and le. 3377@item Wab 3378A memory reference with an absolute address. 3379@item Wbc 3380A memory reference using @code{BC} as a base register, with an optional offset. 3381@item Wca 3382A memory reference using @code{AX}, @code{BC}, @code{DE}, or @code{HL} for the address, for calls. 3383@item Wcv 3384A memory reference using any 16-bit register pair for the address, for calls. 3385@item Wd2 3386A memory reference using @code{DE} as a base register, with an optional offset. 3387@item Wde 3388A memory reference using @code{DE} as a base register, without any offset. 3389@item Wfr 3390Any memory reference to an address in the far address space. 3391@item Wh1 3392A memory reference using @code{HL} as a base register, with an optional one-byte offset. 3393@item Whb 3394A memory reference using @code{HL} as a base register, with @code{B} or @code{C} as the index register. 3395@item Whl 3396A memory reference using @code{HL} as a base register, without any offset. 3397@item Ws1 3398A memory reference using @code{SP} as a base register, with an optional one-byte offset. 3399@item Y 3400Any memory reference to an address in the near address space. 3401@item A 3402The @code{AX} register. 3403@item B 3404The @code{BC} register. 3405@item D 3406The @code{DE} register. 3407@item R 3408@code{A} through @code{L} registers. 3409@item S 3410The @code{SP} register. 3411@item T 3412The @code{HL} register. 3413@item Z08W 3414The 16-bit @code{R8} register. 3415@item Z10W 3416The 16-bit @code{R10} register. 3417@item Zint 3418The registers reserved for interrupts (@code{R24} to @code{R31}). 3419@item a 3420The @code{A} register. 3421@item b 3422The @code{B} register. 3423@item c 3424The @code{C} register. 3425@item d 3426The @code{D} register. 3427@item e 3428The @code{E} register. 3429@item h 3430The @code{H} register. 3431@item l 3432The @code{L} register. 3433@item v 3434The virtual registers. 3435@item w 3436The @code{PSW} register. 3437@item x 3438The @code{X} register. 3439 3440@end table 3441 3442@item RX---@file{config/rx/constraints.md} 3443@table @code 3444@item Q 3445An address which does not involve register indirect addressing or 3446pre/post increment/decrement addressing. 3447 3448@item Symbol 3449A symbol reference. 3450 3451@item Int08 3452A constant in the range @minus{}256 to 255, inclusive. 3453 3454@item Sint08 3455A constant in the range @minus{}128 to 127, inclusive. 3456 3457@item Sint16 3458A constant in the range @minus{}32768 to 32767, inclusive. 3459 3460@item Sint24 3461A constant in the range @minus{}8388608 to 8388607, inclusive. 3462 3463@item Uint04 3464A constant in the range 0 to 15, inclusive. 3465 3466@end table 3467 3468@item S/390 and zSeries---@file{config/s390/s390.h} 3469@table @code 3470@item a 3471Address register (general purpose register except r0) 3472 3473@item c 3474Condition code register 3475 3476@item d 3477Data register (arbitrary general purpose register) 3478 3479@item f 3480Floating-point register 3481 3482@item I 3483Unsigned 8-bit constant (0--255) 3484 3485@item J 3486Unsigned 12-bit constant (0--4095) 3487 3488@item K 3489Signed 16-bit constant (@minus{}32768--32767) 3490 3491@item L 3492Value appropriate as displacement. 3493@table @code 3494@item (0..4095) 3495for short displacement 3496@item (@minus{}524288..524287) 3497for long displacement 3498@end table 3499 3500@item M 3501Constant integer with a value of 0x7fffffff. 3502 3503@item N 3504Multiple letter constraint followed by 4 parameter letters. 3505@table @code 3506@item 0..9: 3507number of the part counting from most to least significant 3508@item H,Q: 3509mode of the part 3510@item D,S,H: 3511mode of the containing operand 3512@item 0,F: 3513value of the other parts (F---all bits set) 3514@end table 3515The constraint matches if the specified part of a constant 3516has a value different from its other parts. 3517 3518@item Q 3519Memory reference without index register and with short displacement. 3520 3521@item R 3522Memory reference with index register and short displacement. 3523 3524@item S 3525Memory reference without index register but with long displacement. 3526 3527@item T 3528Memory reference with index register and long displacement. 3529 3530@item U 3531Pointer with short displacement. 3532 3533@item W 3534Pointer with long displacement. 3535 3536@item Y 3537Shift count operand. 3538 3539@end table 3540 3541@need 1000 3542@item SPARC---@file{config/sparc/sparc.h} 3543@table @code 3544@item f 3545Floating-point register on the SPARC-V8 architecture and 3546lower floating-point register on the SPARC-V9 architecture. 3547 3548@item e 3549Floating-point register. It is equivalent to @samp{f} on the 3550SPARC-V8 architecture and contains both lower and upper 3551floating-point registers on the SPARC-V9 architecture. 3552 3553@item c 3554Floating-point condition code register. 3555 3556@item d 3557Lower floating-point register. It is only valid on the SPARC-V9 3558architecture when the Visual Instruction Set is available. 3559 3560@item b 3561Floating-point register. It is only valid on the SPARC-V9 architecture 3562when the Visual Instruction Set is available. 3563 3564@item h 356564-bit global or out register for the SPARC-V8+ architecture. 3566 3567@item C 3568The constant all-ones, for floating-point. 3569 3570@item A 3571Signed 5-bit constant 3572 3573@item D 3574A vector constant 3575 3576@item I 3577Signed 13-bit constant 3578 3579@item J 3580Zero 3581 3582@item K 358332-bit constant with the low 12 bits clear (a constant that can be 3584loaded with the @code{sethi} instruction) 3585 3586@item L 3587A constant in the range supported by @code{movcc} instructions (11-bit 3588signed immediate) 3589 3590@item M 3591A constant in the range supported by @code{movrcc} instructions (10-bit 3592signed immediate) 3593 3594@item N 3595Same as @samp{K}, except that it verifies that bits that are not in the 3596lower 32-bit range are all zero. Must be used instead of @samp{K} for 3597modes wider than @code{SImode} 3598 3599@item O 3600The constant 4096 3601 3602@item G 3603Floating-point zero 3604 3605@item H 3606Signed 13-bit constant, sign-extended to 32 or 64 bits 3607 3608@item P 3609The constant -1 3610 3611@item Q 3612Floating-point constant whose integral representation can 3613be moved into an integer register using a single sethi 3614instruction 3615 3616@item R 3617Floating-point constant whose integral representation can 3618be moved into an integer register using a single mov 3619instruction 3620 3621@item S 3622Floating-point constant whose integral representation can 3623be moved into an integer register using a high/lo_sum 3624instruction sequence 3625 3626@item T 3627Memory address aligned to an 8-byte boundary 3628 3629@item U 3630Even register 3631 3632@item W 3633Memory address for @samp{e} constraint registers 3634 3635@item w 3636Memory address with only a base register 3637 3638@item Y 3639Vector zero 3640 3641@end table 3642 3643@item SPU---@file{config/spu/spu.h} 3644@table @code 3645@item a 3646An immediate which can be loaded with the il/ila/ilh/ilhu instructions. const_int is treated as a 64 bit value. 3647 3648@item c 3649An immediate for and/xor/or instructions. const_int is treated as a 64 bit value. 3650 3651@item d 3652An immediate for the @code{iohl} instruction. const_int is treated as a 64 bit value. 3653 3654@item f 3655An immediate which can be loaded with @code{fsmbi}. 3656 3657@item A 3658An immediate which can be loaded with the il/ila/ilh/ilhu instructions. const_int is treated as a 32 bit value. 3659 3660@item B 3661An immediate for most arithmetic instructions. const_int is treated as a 32 bit value. 3662 3663@item C 3664An immediate for and/xor/or instructions. const_int is treated as a 32 bit value. 3665 3666@item D 3667An immediate for the @code{iohl} instruction. const_int is treated as a 32 bit value. 3668 3669@item I 3670A constant in the range [@minus{}64, 63] for shift/rotate instructions. 3671 3672@item J 3673An unsigned 7-bit constant for conversion/nop/channel instructions. 3674 3675@item K 3676A signed 10-bit constant for most arithmetic instructions. 3677 3678@item M 3679A signed 16 bit immediate for @code{stop}. 3680 3681@item N 3682An unsigned 16-bit constant for @code{iohl} and @code{fsmbi}. 3683 3684@item O 3685An unsigned 7-bit constant whose 3 least significant bits are 0. 3686 3687@item P 3688An unsigned 3-bit constant for 16-byte rotates and shifts 3689 3690@item R 3691Call operand, reg, for indirect calls 3692 3693@item S 3694Call operand, symbol, for relative calls. 3695 3696@item T 3697Call operand, const_int, for absolute calls. 3698 3699@item U 3700An immediate which can be loaded with the il/ila/ilh/ilhu instructions. const_int is sign extended to 128 bit. 3701 3702@item W 3703An immediate for shift and rotate instructions. const_int is treated as a 32 bit value. 3704 3705@item Y 3706An immediate for and/xor/or instructions. const_int is sign extended as a 128 bit. 3707 3708@item Z 3709An immediate for the @code{iohl} instruction. const_int is sign extended to 128 bit. 3710 3711@end table 3712 3713@item TI C6X family---@file{config/c6x/constraints.md} 3714@table @code 3715@item a 3716Register file A (A0--A31). 3717 3718@item b 3719Register file B (B0--B31). 3720 3721@item A 3722Predicate registers in register file A (A0--A2 on C64X and 3723higher, A1 and A2 otherwise). 3724 3725@item B 3726Predicate registers in register file B (B0--B2). 3727 3728@item C 3729A call-used register in register file B (B0--B9, B16--B31). 3730 3731@item Da 3732Register file A, excluding predicate registers (A3--A31, 3733plus A0 if not C64X or higher). 3734 3735@item Db 3736Register file B, excluding predicate registers (B3--B31). 3737 3738@item Iu4 3739Integer constant in the range 0 @dots{} 15. 3740 3741@item Iu5 3742Integer constant in the range 0 @dots{} 31. 3743 3744@item In5 3745Integer constant in the range @minus{}31 @dots{} 0. 3746 3747@item Is5 3748Integer constant in the range @minus{}16 @dots{} 15. 3749 3750@item I5x 3751Integer constant that can be the operand of an ADDA or a SUBA insn. 3752 3753@item IuB 3754Integer constant in the range 0 @dots{} 65535. 3755 3756@item IsB 3757Integer constant in the range @minus{}32768 @dots{} 32767. 3758 3759@item IsC 3760Integer constant in the range @math{-2^{20}} @dots{} @math{2^{20} - 1}. 3761 3762@item Jc 3763Integer constant that is a valid mask for the clr instruction. 3764 3765@item Js 3766Integer constant that is a valid mask for the set instruction. 3767 3768@item Q 3769Memory location with A base register. 3770 3771@item R 3772Memory location with B base register. 3773 3774@ifset INTERNALS 3775@item S0 3776On C64x+ targets, a GP-relative small data reference. 3777 3778@item S1 3779Any kind of @code{SYMBOL_REF}, for use in a call address. 3780 3781@item Si 3782Any kind of immediate operand, unless it matches the S0 constraint. 3783 3784@item T 3785Memory location with B base register, but not using a long offset. 3786 3787@item W 3788A memory operand with an address that can't be used in an unaligned access. 3789 3790@end ifset 3791@item Z 3792Register B14 (aka DP). 3793 3794@end table 3795 3796@item TILE-Gx---@file{config/tilegx/constraints.md} 3797@table @code 3798@item R00 3799@itemx R01 3800@itemx R02 3801@itemx R03 3802@itemx R04 3803@itemx R05 3804@itemx R06 3805@itemx R07 3806@itemx R08 3807@itemx R09 3808@itemx R10 3809Each of these represents a register constraint for an individual 3810register, from r0 to r10. 3811 3812@item I 3813Signed 8-bit integer constant. 3814 3815@item J 3816Signed 16-bit integer constant. 3817 3818@item K 3819Unsigned 16-bit integer constant. 3820 3821@item L 3822Integer constant that fits in one signed byte when incremented by one 3823(@minus{}129 @dots{} 126). 3824 3825@item m 3826Memory operand. If used together with @samp{<} or @samp{>}, the 3827operand can have postincrement which requires printing with @samp{%In} 3828and @samp{%in} on TILE-Gx. For example: 3829 3830@smallexample 3831asm ("st_add %I0,%1,%i0" : "=m<>" (*mem) : "r" (val)); 3832@end smallexample 3833 3834@item M 3835A bit mask suitable for the BFINS instruction. 3836 3837@item N 3838Integer constant that is a byte tiled out eight times. 3839 3840@item O 3841The integer zero constant. 3842 3843@item P 3844Integer constant that is a sign-extended byte tiled out as four shorts. 3845 3846@item Q 3847Integer constant that fits in one signed byte when incremented 3848(@minus{}129 @dots{} 126), but excluding -1. 3849 3850@item S 3851Integer constant that has all 1 bits consecutive and starting at bit 0. 3852 3853@item T 3854A 16-bit fragment of a got, tls, or pc-relative reference. 3855 3856@item U 3857Memory operand except postincrement. This is roughly the same as 3858@samp{m} when not used together with @samp{<} or @samp{>}. 3859 3860@item W 3861An 8-element vector constant with identical elements. 3862 3863@item Y 3864A 4-element vector constant with identical elements. 3865 3866@item Z0 3867The integer constant 0xffffffff. 3868 3869@item Z1 3870The integer constant 0xffffffff00000000. 3871 3872@end table 3873 3874@item TILEPro---@file{config/tilepro/constraints.md} 3875@table @code 3876@item R00 3877@itemx R01 3878@itemx R02 3879@itemx R03 3880@itemx R04 3881@itemx R05 3882@itemx R06 3883@itemx R07 3884@itemx R08 3885@itemx R09 3886@itemx R10 3887Each of these represents a register constraint for an individual 3888register, from r0 to r10. 3889 3890@item I 3891Signed 8-bit integer constant. 3892 3893@item J 3894Signed 16-bit integer constant. 3895 3896@item K 3897Nonzero integer constant with low 16 bits zero. 3898 3899@item L 3900Integer constant that fits in one signed byte when incremented by one 3901(@minus{}129 @dots{} 126). 3902 3903@item m 3904Memory operand. If used together with @samp{<} or @samp{>}, the 3905operand can have postincrement which requires printing with @samp{%In} 3906and @samp{%in} on TILEPro. For example: 3907 3908@smallexample 3909asm ("swadd %I0,%1,%i0" : "=m<>" (mem) : "r" (val)); 3910@end smallexample 3911 3912@item M 3913A bit mask suitable for the MM instruction. 3914 3915@item N 3916Integer constant that is a byte tiled out four times. 3917 3918@item O 3919The integer zero constant. 3920 3921@item P 3922Integer constant that is a sign-extended byte tiled out as two shorts. 3923 3924@item Q 3925Integer constant that fits in one signed byte when incremented 3926(@minus{}129 @dots{} 126), but excluding -1. 3927 3928@item T 3929A symbolic operand, or a 16-bit fragment of a got, tls, or pc-relative 3930reference. 3931 3932@item U 3933Memory operand except postincrement. This is roughly the same as 3934@samp{m} when not used together with @samp{<} or @samp{>}. 3935 3936@item W 3937A 4-element vector constant with identical elements. 3938 3939@item Y 3940A 2-element vector constant with identical elements. 3941 3942@end table 3943 3944@item Visium---@file{config/visium/constraints.md} 3945@table @code 3946@item b 3947EAM register @code{mdb} 3948 3949@item c 3950EAM register @code{mdc} 3951 3952@item f 3953Floating point register 3954 3955@ifset INTERNALS 3956@item k 3957Register for sibcall optimization 3958@end ifset 3959 3960@item l 3961General register, but not @code{r29}, @code{r30} and @code{r31} 3962 3963@item t 3964Register @code{r1} 3965 3966@item u 3967Register @code{r2} 3968 3969@item v 3970Register @code{r3} 3971 3972@item G 3973Floating-point constant 0.0 3974 3975@item J 3976Integer constant in the range 0 .. 65535 (16-bit immediate) 3977 3978@item K 3979Integer constant in the range 1 .. 31 (5-bit immediate) 3980 3981@item L 3982Integer constant in the range @minus{}65535 .. @minus{}1 (16-bit negative immediate) 3983 3984@item M 3985Integer constant @minus{}1 3986 3987@item O 3988Integer constant 0 3989 3990@item P 3991Integer constant 32 3992@end table 3993 3994@item x86 family---@file{config/i386/constraints.md} 3995@table @code 3996@item R 3997Legacy register---the eight integer registers available on all 3998i386 processors (@code{a}, @code{b}, @code{c}, @code{d}, 3999@code{si}, @code{di}, @code{bp}, @code{sp}). 4000 4001@item q 4002Any register accessible as @code{@var{r}l}. In 32-bit mode, @code{a}, 4003@code{b}, @code{c}, and @code{d}; in 64-bit mode, any integer register. 4004 4005@item Q 4006Any register accessible as @code{@var{r}h}: @code{a}, @code{b}, 4007@code{c}, and @code{d}. 4008 4009@ifset INTERNALS 4010@item l 4011Any register that can be used as the index in a base+index memory 4012access: that is, any general register except the stack pointer. 4013@end ifset 4014 4015@item a 4016The @code{a} register. 4017 4018@item b 4019The @code{b} register. 4020 4021@item c 4022The @code{c} register. 4023 4024@item d 4025The @code{d} register. 4026 4027@item S 4028The @code{si} register. 4029 4030@item D 4031The @code{di} register. 4032 4033@item A 4034The @code{a} and @code{d} registers. This class is used for instructions 4035that return double word results in the @code{ax:dx} register pair. Single 4036word values will be allocated either in @code{ax} or @code{dx}. 4037For example on i386 the following implements @code{rdtsc}: 4038 4039@smallexample 4040unsigned long long rdtsc (void) 4041@{ 4042 unsigned long long tick; 4043 __asm__ __volatile__("rdtsc":"=A"(tick)); 4044 return tick; 4045@} 4046@end smallexample 4047 4048This is not correct on x86-64 as it would allocate tick in either @code{ax} 4049or @code{dx}. You have to use the following variant instead: 4050 4051@smallexample 4052unsigned long long rdtsc (void) 4053@{ 4054 unsigned int tickl, tickh; 4055 __asm__ __volatile__("rdtsc":"=a"(tickl),"=d"(tickh)); 4056 return ((unsigned long long)tickh << 32)|tickl; 4057@} 4058@end smallexample 4059 4060 4061@item f 4062Any 80387 floating-point (stack) register. 4063 4064@item t 4065Top of 80387 floating-point stack (@code{%st(0)}). 4066 4067@item u 4068Second from top of 80387 floating-point stack (@code{%st(1)}). 4069 4070@item y 4071Any MMX register. 4072 4073@item x 4074Any SSE register. 4075 4076@item Yz 4077First SSE register (@code{%xmm0}). 4078 4079@ifset INTERNALS 4080@item Y2 4081Any SSE register, when SSE2 is enabled. 4082 4083@item Yi 4084Any SSE register, when SSE2 and inter-unit moves are enabled. 4085 4086@item Ym 4087Any MMX register, when inter-unit moves are enabled. 4088@end ifset 4089 4090@item I 4091Integer constant in the range 0 @dots{} 31, for 32-bit shifts. 4092 4093@item J 4094Integer constant in the range 0 @dots{} 63, for 64-bit shifts. 4095 4096@item K 4097Signed 8-bit integer constant. 4098 4099@item L 4100@code{0xFF} or @code{0xFFFF}, for andsi as a zero-extending move. 4101 4102@item M 41030, 1, 2, or 3 (shifts for the @code{lea} instruction). 4104 4105@item N 4106Unsigned 8-bit integer constant (for @code{in} and @code{out} 4107instructions). 4108 4109@ifset INTERNALS 4110@item O 4111Integer constant in the range 0 @dots{} 127, for 128-bit shifts. 4112@end ifset 4113 4114@item G 4115Standard 80387 floating point constant. 4116 4117@item C 4118SSE constant zero operand. 4119 4120@item e 412132-bit signed integer constant, or a symbolic reference known 4122to fit that range (for immediate operands in sign-extending x86-64 4123instructions). 4124 4125@item Z 412632-bit unsigned integer constant, or a symbolic reference known 4127to fit that range (for immediate operands in zero-extending x86-64 4128instructions). 4129 4130@end table 4131 4132@item Xstormy16---@file{config/stormy16/stormy16.h} 4133@table @code 4134@item a 4135Register r0. 4136 4137@item b 4138Register r1. 4139 4140@item c 4141Register r2. 4142 4143@item d 4144Register r8. 4145 4146@item e 4147Registers r0 through r7. 4148 4149@item t 4150Registers r0 and r1. 4151 4152@item y 4153The carry register. 4154 4155@item z 4156Registers r8 and r9. 4157 4158@item I 4159A constant between 0 and 3 inclusive. 4160 4161@item J 4162A constant that has exactly one bit set. 4163 4164@item K 4165A constant that has exactly one bit clear. 4166 4167@item L 4168A constant between 0 and 255 inclusive. 4169 4170@item M 4171A constant between @minus{}255 and 0 inclusive. 4172 4173@item N 4174A constant between @minus{}3 and 0 inclusive. 4175 4176@item O 4177A constant between 1 and 4 inclusive. 4178 4179@item P 4180A constant between @minus{}4 and @minus{}1 inclusive. 4181 4182@item Q 4183A memory reference that is a stack push. 4184 4185@item R 4186A memory reference that is a stack pop. 4187 4188@item S 4189A memory reference that refers to a constant address of known value. 4190 4191@item T 4192The register indicated by Rx (not implemented yet). 4193 4194@item U 4195A constant that is not between 2 and 15 inclusive. 4196 4197@item Z 4198The constant 0. 4199 4200@end table 4201 4202@item Xtensa---@file{config/xtensa/constraints.md} 4203@table @code 4204@item a 4205General-purpose 32-bit register 4206 4207@item b 4208One-bit boolean register 4209 4210@item A 4211MAC16 40-bit accumulator register 4212 4213@item I 4214Signed 12-bit integer constant, for use in MOVI instructions 4215 4216@item J 4217Signed 8-bit integer constant, for use in ADDI instructions 4218 4219@item K 4220Integer constant valid for BccI instructions 4221 4222@item L 4223Unsigned constant valid for BccUI instructions 4224 4225@end table 4226 4227@end table 4228 4229@ifset INTERNALS 4230@node Disable Insn Alternatives 4231@subsection Disable insn alternatives using the @code{enabled} attribute 4232@cindex enabled 4233 4234There are three insn attributes that may be used to selectively disable 4235instruction alternatives: 4236 4237@table @code 4238@item enabled 4239Says whether an alternative is available on the current subtarget. 4240 4241@item preferred_for_size 4242Says whether an enabled alternative should be used in code that is 4243optimized for size. 4244 4245@item preferred_for_speed 4246Says whether an enabled alternative should be used in code that is 4247optimized for speed. 4248@end table 4249 4250All these attributes should use @code{(const_int 1)} to allow an alternative 4251or @code{(const_int 0)} to disallow it. The attributes must be a static 4252property of the subtarget; they cannot for example depend on the 4253current operands, on the current optimization level, on the location 4254of the insn within the body of a loop, on whether register allocation 4255has finished, or on the current compiler pass. 4256 4257The @code{enabled} attribute is a correctness property. It tells GCC to act 4258as though the disabled alternatives were never defined in the first place. 4259This is useful when adding new instructions to an existing pattern in 4260cases where the new instructions are only available for certain cpu 4261architecture levels (typically mapped to the @code{-march=} command-line 4262option). 4263 4264In contrast, the @code{preferred_for_size} and @code{preferred_for_speed} 4265attributes are strong optimization hints rather than correctness properties. 4266@code{preferred_for_size} tells GCC which alternatives to consider when 4267adding or modifying an instruction that GCC wants to optimize for size. 4268@code{preferred_for_speed} does the same thing for speed. Note that things 4269like code motion can lead to cases where code optimized for size uses 4270alternatives that are not preferred for size, and similarly for speed. 4271 4272Although @code{define_insn}s can in principle specify the @code{enabled} 4273attribute directly, it is often clearer to have subsiduary attributes 4274for each architectural feature of interest. The @code{define_insn}s 4275can then use these subsiduary attributes to say which alternatives 4276require which features. The example below does this for @code{cpu_facility}. 4277 4278E.g. the following two patterns could easily be merged using the @code{enabled} 4279attribute: 4280 4281@smallexample 4282 4283(define_insn "*movdi_old" 4284 [(set (match_operand:DI 0 "register_operand" "=d") 4285 (match_operand:DI 1 "register_operand" " d"))] 4286 "!TARGET_NEW" 4287 "lgr %0,%1") 4288 4289(define_insn "*movdi_new" 4290 [(set (match_operand:DI 0 "register_operand" "=d,f,d") 4291 (match_operand:DI 1 "register_operand" " d,d,f"))] 4292 "TARGET_NEW" 4293 "@@ 4294 lgr %0,%1 4295 ldgr %0,%1 4296 lgdr %0,%1") 4297 4298@end smallexample 4299 4300to: 4301 4302@smallexample 4303 4304(define_insn "*movdi_combined" 4305 [(set (match_operand:DI 0 "register_operand" "=d,f,d") 4306 (match_operand:DI 1 "register_operand" " d,d,f"))] 4307 "" 4308 "@@ 4309 lgr %0,%1 4310 ldgr %0,%1 4311 lgdr %0,%1" 4312 [(set_attr "cpu_facility" "*,new,new")]) 4313 4314@end smallexample 4315 4316with the @code{enabled} attribute defined like this: 4317 4318@smallexample 4319 4320(define_attr "cpu_facility" "standard,new" (const_string "standard")) 4321 4322(define_attr "enabled" "" 4323 (cond [(eq_attr "cpu_facility" "standard") (const_int 1) 4324 (and (eq_attr "cpu_facility" "new") 4325 (ne (symbol_ref "TARGET_NEW") (const_int 0))) 4326 (const_int 1)] 4327 (const_int 0))) 4328 4329@end smallexample 4330 4331@end ifset 4332 4333@ifset INTERNALS 4334@node Define Constraints 4335@subsection Defining Machine-Specific Constraints 4336@cindex defining constraints 4337@cindex constraints, defining 4338 4339Machine-specific constraints fall into two categories: register and 4340non-register constraints. Within the latter category, constraints 4341which allow subsets of all possible memory or address operands should 4342be specially marked, to give @code{reload} more information. 4343 4344Machine-specific constraints can be given names of arbitrary length, 4345but they must be entirely composed of letters, digits, underscores 4346(@samp{_}), and angle brackets (@samp{< >}). Like C identifiers, they 4347must begin with a letter or underscore. 4348 4349In order to avoid ambiguity in operand constraint strings, no 4350constraint can have a name that begins with any other constraint's 4351name. For example, if @code{x} is defined as a constraint name, 4352@code{xy} may not be, and vice versa. As a consequence of this rule, 4353no constraint may begin with one of the generic constraint letters: 4354@samp{E F V X g i m n o p r s}. 4355 4356Register constraints correspond directly to register classes. 4357@xref{Register Classes}. There is thus not much flexibility in their 4358definitions. 4359 4360@deffn {MD Expression} define_register_constraint name regclass docstring 4361All three arguments are string constants. 4362@var{name} is the name of the constraint, as it will appear in 4363@code{match_operand} expressions. If @var{name} is a multi-letter 4364constraint its length shall be the same for all constraints starting 4365with the same letter. @var{regclass} can be either the 4366name of the corresponding register class (@pxref{Register Classes}), 4367or a C expression which evaluates to the appropriate register class. 4368If it is an expression, it must have no side effects, and it cannot 4369look at the operand. The usual use of expressions is to map some 4370register constraints to @code{NO_REGS} when the register class 4371is not available on a given subarchitecture. 4372 4373@var{docstring} is a sentence documenting the meaning of the 4374constraint. Docstrings are explained further below. 4375@end deffn 4376 4377Non-register constraints are more like predicates: the constraint 4378definition gives a Boolean expression which indicates whether the 4379constraint matches. 4380 4381@deffn {MD Expression} define_constraint name docstring exp 4382The @var{name} and @var{docstring} arguments are the same as for 4383@code{define_register_constraint}, but note that the docstring comes 4384immediately after the name for these expressions. @var{exp} is an RTL 4385expression, obeying the same rules as the RTL expressions in predicate 4386definitions. @xref{Defining Predicates}, for details. If it 4387evaluates true, the constraint matches; if it evaluates false, it 4388doesn't. Constraint expressions should indicate which RTL codes they 4389might match, just like predicate expressions. 4390 4391@code{match_test} C expressions have access to the 4392following variables: 4393 4394@table @var 4395@item op 4396The RTL object defining the operand. 4397@item mode 4398The machine mode of @var{op}. 4399@item ival 4400@samp{INTVAL (@var{op})}, if @var{op} is a @code{const_int}. 4401@item hval 4402@samp{CONST_DOUBLE_HIGH (@var{op})}, if @var{op} is an integer 4403@code{const_double}. 4404@item lval 4405@samp{CONST_DOUBLE_LOW (@var{op})}, if @var{op} is an integer 4406@code{const_double}. 4407@item rval 4408@samp{CONST_DOUBLE_REAL_VALUE (@var{op})}, if @var{op} is a floating-point 4409@code{const_double}. 4410@end table 4411 4412The @var{*val} variables should only be used once another piece of the 4413expression has verified that @var{op} is the appropriate kind of RTL 4414object. 4415@end deffn 4416 4417Most non-register constraints should be defined with 4418@code{define_constraint}. The remaining two definition expressions 4419are only appropriate for constraints that should be handled specially 4420by @code{reload} if they fail to match. 4421 4422@deffn {MD Expression} define_memory_constraint name docstring exp 4423Use this expression for constraints that match a subset of all memory 4424operands: that is, @code{reload} can make them match by converting the 4425operand to the form @samp{@w{(mem (reg @var{X}))}}, where @var{X} is a 4426base register (from the register class specified by 4427@code{BASE_REG_CLASS}, @pxref{Register Classes}). 4428 4429For example, on the S/390, some instructions do not accept arbitrary 4430memory references, but only those that do not make use of an index 4431register. The constraint letter @samp{Q} is defined to represent a 4432memory address of this type. If @samp{Q} is defined with 4433@code{define_memory_constraint}, a @samp{Q} constraint can handle any 4434memory operand, because @code{reload} knows it can simply copy the 4435memory address into a base register if required. This is analogous to 4436the way an @samp{o} constraint can handle any memory operand. 4437 4438The syntax and semantics are otherwise identical to 4439@code{define_constraint}. 4440@end deffn 4441 4442@deffn {MD Expression} define_special_memory_constraint name docstring exp 4443Use this expression for constraints that match a subset of all memory 4444operands: that is, @code{reload} can not make them match by reloading 4445the address as it is described for @code{define_memory_constraint} or 4446such address reload is undesirable with the performance point of view. 4447 4448For example, @code{define_special_memory_constraint} can be useful if 4449specifically aligned memory is necessary or desirable for some insn 4450operand. 4451 4452The syntax and semantics are otherwise identical to 4453@code{define_constraint}. 4454@end deffn 4455 4456@deffn {MD Expression} define_address_constraint name docstring exp 4457Use this expression for constraints that match a subset of all address 4458operands: that is, @code{reload} can make the constraint match by 4459converting the operand to the form @samp{@w{(reg @var{X})}}, again 4460with @var{X} a base register. 4461 4462Constraints defined with @code{define_address_constraint} can only be 4463used with the @code{address_operand} predicate, or machine-specific 4464predicates that work the same way. They are treated analogously to 4465the generic @samp{p} constraint. 4466 4467The syntax and semantics are otherwise identical to 4468@code{define_constraint}. 4469@end deffn 4470 4471For historical reasons, names beginning with the letters @samp{G H} 4472are reserved for constraints that match only @code{const_double}s, and 4473names beginning with the letters @samp{I J K L M N O P} are reserved 4474for constraints that match only @code{const_int}s. This may change in 4475the future. For the time being, constraints with these names must be 4476written in a stylized form, so that @code{genpreds} can tell you did 4477it correctly: 4478 4479@smallexample 4480@group 4481(define_constraint "[@var{GHIJKLMNOP}]@dots{}" 4482 "@var{doc}@dots{}" 4483 (and (match_code "const_int") ; @r{@code{const_double} for G/H} 4484 @var{condition}@dots{})) ; @r{usually a @code{match_test}} 4485@end group 4486@end smallexample 4487@c the semicolons line up in the formatted manual 4488 4489It is fine to use names beginning with other letters for constraints 4490that match @code{const_double}s or @code{const_int}s. 4491 4492Each docstring in a constraint definition should be one or more complete 4493sentences, marked up in Texinfo format. @emph{They are currently unused.} 4494In the future they will be copied into the GCC manual, in @ref{Machine 4495Constraints}, replacing the hand-maintained tables currently found in 4496that section. Also, in the future the compiler may use this to give 4497more helpful diagnostics when poor choice of @code{asm} constraints 4498causes a reload failure. 4499 4500If you put the pseudo-Texinfo directive @samp{@@internal} at the 4501beginning of a docstring, then (in the future) it will appear only in 4502the internals manual's version of the machine-specific constraint tables. 4503Use this for constraints that should not appear in @code{asm} statements. 4504 4505@node C Constraint Interface 4506@subsection Testing constraints from C 4507@cindex testing constraints 4508@cindex constraints, testing 4509 4510It is occasionally useful to test a constraint from C code rather than 4511implicitly via the constraint string in a @code{match_operand}. The 4512generated file @file{tm_p.h} declares a few interfaces for working 4513with constraints. At present these are defined for all constraints 4514except @code{g} (which is equivalent to @code{general_operand}). 4515 4516Some valid constraint names are not valid C identifiers, so there is a 4517mangling scheme for referring to them from C@. Constraint names that 4518do not contain angle brackets or underscores are left unchanged. 4519Underscores are doubled, each @samp{<} is replaced with @samp{_l}, and 4520each @samp{>} with @samp{_g}. Here are some examples: 4521 4522@c the @c's prevent double blank lines in the printed manual. 4523@example 4524@multitable {Original} {Mangled} 4525@item @strong{Original} @tab @strong{Mangled} @c 4526@item @code{x} @tab @code{x} @c 4527@item @code{P42x} @tab @code{P42x} @c 4528@item @code{P4_x} @tab @code{P4__x} @c 4529@item @code{P4>x} @tab @code{P4_gx} @c 4530@item @code{P4>>} @tab @code{P4_g_g} @c 4531@item @code{P4_g>} @tab @code{P4__g_g} @c 4532@end multitable 4533@end example 4534 4535Throughout this section, the variable @var{c} is either a constraint 4536in the abstract sense, or a constant from @code{enum constraint_num}; 4537the variable @var{m} is a mangled constraint name (usually as part of 4538a larger identifier). 4539 4540@deftp Enum constraint_num 4541For each constraint except @code{g}, there is a corresponding 4542enumeration constant: @samp{CONSTRAINT_} plus the mangled name of the 4543constraint. Functions that take an @code{enum constraint_num} as an 4544argument expect one of these constants. 4545@end deftp 4546 4547@deftypefun {inline bool} satisfies_constraint_@var{m} (rtx @var{exp}) 4548For each non-register constraint @var{m} except @code{g}, there is 4549one of these functions; it returns @code{true} if @var{exp} satisfies the 4550constraint. These functions are only visible if @file{rtl.h} was included 4551before @file{tm_p.h}. 4552@end deftypefun 4553 4554@deftypefun bool constraint_satisfied_p (rtx @var{exp}, enum constraint_num @var{c}) 4555Like the @code{satisfies_constraint_@var{m}} functions, but the 4556constraint to test is given as an argument, @var{c}. If @var{c} 4557specifies a register constraint, this function will always return 4558@code{false}. 4559@end deftypefun 4560 4561@deftypefun {enum reg_class} reg_class_for_constraint (enum constraint_num @var{c}) 4562Returns the register class associated with @var{c}. If @var{c} is not 4563a register constraint, or those registers are not available for the 4564currently selected subtarget, returns @code{NO_REGS}. 4565@end deftypefun 4566 4567Here is an example use of @code{satisfies_constraint_@var{m}}. In 4568peephole optimizations (@pxref{Peephole Definitions}), operand 4569constraint strings are ignored, so if there are relevant constraints, 4570they must be tested in the C condition. In the example, the 4571optimization is applied if operand 2 does @emph{not} satisfy the 4572@samp{K} constraint. (This is a simplified version of a peephole 4573definition from the i386 machine description.) 4574 4575@smallexample 4576(define_peephole2 4577 [(match_scratch:SI 3 "r") 4578 (set (match_operand:SI 0 "register_operand" "") 4579 (mult:SI (match_operand:SI 1 "memory_operand" "") 4580 (match_operand:SI 2 "immediate_operand" "")))] 4581 4582 "!satisfies_constraint_K (operands[2])" 4583 4584 [(set (match_dup 3) (match_dup 1)) 4585 (set (match_dup 0) (mult:SI (match_dup 3) (match_dup 2)))] 4586 4587 "") 4588@end smallexample 4589 4590@node Standard Names 4591@section Standard Pattern Names For Generation 4592@cindex standard pattern names 4593@cindex pattern names 4594@cindex names, pattern 4595 4596Here is a table of the instruction names that are meaningful in the RTL 4597generation pass of the compiler. Giving one of these names to an 4598instruction pattern tells the RTL generation pass that it can use the 4599pattern to accomplish a certain task. 4600 4601@table @asis 4602@cindex @code{mov@var{m}} instruction pattern 4603@item @samp{mov@var{m}} 4604Here @var{m} stands for a two-letter machine mode name, in lowercase. 4605This instruction pattern moves data with that machine mode from operand 46061 to operand 0. For example, @samp{movsi} moves full-word data. 4607 4608If operand 0 is a @code{subreg} with mode @var{m} of a register whose 4609own mode is wider than @var{m}, the effect of this instruction is 4610to store the specified value in the part of the register that corresponds 4611to mode @var{m}. Bits outside of @var{m}, but which are within the 4612same target word as the @code{subreg} are undefined. Bits which are 4613outside the target word are left unchanged. 4614 4615This class of patterns is special in several ways. First of all, each 4616of these names up to and including full word size @emph{must} be defined, 4617because there is no other way to copy a datum from one place to another. 4618If there are patterns accepting operands in larger modes, 4619@samp{mov@var{m}} must be defined for integer modes of those sizes. 4620 4621Second, these patterns are not used solely in the RTL generation pass. 4622Even the reload pass can generate move insns to copy values from stack 4623slots into temporary registers. When it does so, one of the operands is 4624a hard register and the other is an operand that can need to be reloaded 4625into a register. 4626 4627@findex force_reg 4628Therefore, when given such a pair of operands, the pattern must generate 4629RTL which needs no reloading and needs no temporary registers---no 4630registers other than the operands. For example, if you support the 4631pattern with a @code{define_expand}, then in such a case the 4632@code{define_expand} mustn't call @code{force_reg} or any other such 4633function which might generate new pseudo registers. 4634 4635This requirement exists even for subword modes on a RISC machine where 4636fetching those modes from memory normally requires several insns and 4637some temporary registers. 4638 4639@findex change_address 4640During reload a memory reference with an invalid address may be passed 4641as an operand. Such an address will be replaced with a valid address 4642later in the reload pass. In this case, nothing may be done with the 4643address except to use it as it stands. If it is copied, it will not be 4644replaced with a valid address. No attempt should be made to make such 4645an address into a valid address and no routine (such as 4646@code{change_address}) that will do so may be called. Note that 4647@code{general_operand} will fail when applied to such an address. 4648 4649@findex reload_in_progress 4650The global variable @code{reload_in_progress} (which must be explicitly 4651declared if required) can be used to determine whether such special 4652handling is required. 4653 4654The variety of operands that have reloads depends on the rest of the 4655machine description, but typically on a RISC machine these can only be 4656pseudo registers that did not get hard registers, while on other 4657machines explicit memory references will get optional reloads. 4658 4659If a scratch register is required to move an object to or from memory, 4660it can be allocated using @code{gen_reg_rtx} prior to life analysis. 4661 4662If there are cases which need scratch registers during or after reload, 4663you must provide an appropriate secondary_reload target hook. 4664 4665@findex can_create_pseudo_p 4666The macro @code{can_create_pseudo_p} can be used to determine if it 4667is unsafe to create new pseudo registers. If this variable is nonzero, then 4668it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo. 4669 4670The constraints on a @samp{mov@var{m}} must permit moving any hard 4671register to any other hard register provided that 4672@code{HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and 4673@code{TARGET_REGISTER_MOVE_COST} applied to their classes returns a value 4674of 2. 4675 4676It is obligatory to support floating point @samp{mov@var{m}} 4677instructions into and out of any registers that can hold fixed point 4678values, because unions and structures (which have modes @code{SImode} or 4679@code{DImode}) can be in those registers and they may have floating 4680point members. 4681 4682There may also be a need to support fixed point @samp{mov@var{m}} 4683instructions in and out of floating point registers. Unfortunately, I 4684have forgotten why this was so, and I don't know whether it is still 4685true. If @code{HARD_REGNO_MODE_OK} rejects fixed point values in 4686floating point registers, then the constraints of the fixed point 4687@samp{mov@var{m}} instructions must be designed to avoid ever trying to 4688reload into a floating point register. 4689 4690@cindex @code{reload_in} instruction pattern 4691@cindex @code{reload_out} instruction pattern 4692@item @samp{reload_in@var{m}} 4693@itemx @samp{reload_out@var{m}} 4694These named patterns have been obsoleted by the target hook 4695@code{secondary_reload}. 4696 4697Like @samp{mov@var{m}}, but used when a scratch register is required to 4698move between operand 0 and operand 1. Operand 2 describes the scratch 4699register. See the discussion of the @code{SECONDARY_RELOAD_CLASS} 4700macro in @pxref{Register Classes}. 4701 4702There are special restrictions on the form of the @code{match_operand}s 4703used in these patterns. First, only the predicate for the reload 4704operand is examined, i.e., @code{reload_in} examines operand 1, but not 4705the predicates for operand 0 or 2. Second, there may be only one 4706alternative in the constraints. Third, only a single register class 4707letter may be used for the constraint; subsequent constraint letters 4708are ignored. As a special exception, an empty constraint string 4709matches the @code{ALL_REGS} register class. This may relieve ports 4710of the burden of defining an @code{ALL_REGS} constraint letter just 4711for these patterns. 4712 4713@cindex @code{movstrict@var{m}} instruction pattern 4714@item @samp{movstrict@var{m}} 4715Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg} 4716with mode @var{m} of a register whose natural mode is wider, 4717the @samp{movstrict@var{m}} instruction is guaranteed not to alter 4718any of the register except the part which belongs to mode @var{m}. 4719 4720@cindex @code{movmisalign@var{m}} instruction pattern 4721@item @samp{movmisalign@var{m}} 4722This variant of a move pattern is designed to load or store a value 4723from a memory address that is not naturally aligned for its mode. 4724For a store, the memory will be in operand 0; for a load, the memory 4725will be in operand 1. The other operand is guaranteed not to be a 4726memory, so that it's easy to tell whether this is a load or store. 4727 4728This pattern is used by the autovectorizer, and when expanding a 4729@code{MISALIGNED_INDIRECT_REF} expression. 4730 4731@cindex @code{load_multiple} instruction pattern 4732@item @samp{load_multiple} 4733Load several consecutive memory locations into consecutive registers. 4734Operand 0 is the first of the consecutive registers, operand 1 4735is the first memory location, and operand 2 is a constant: the 4736number of consecutive registers. 4737 4738Define this only if the target machine really has such an instruction; 4739do not define this if the most efficient way of loading consecutive 4740registers from memory is to do them one at a time. 4741 4742On some machines, there are restrictions as to which consecutive 4743registers can be stored into memory, such as particular starting or 4744ending register numbers or only a range of valid counts. For those 4745machines, use a @code{define_expand} (@pxref{Expander Definitions}) 4746and make the pattern fail if the restrictions are not met. 4747 4748Write the generated insn as a @code{parallel} with elements being a 4749@code{set} of one register from the appropriate memory location (you may 4750also need @code{use} or @code{clobber} elements). Use a 4751@code{match_parallel} (@pxref{RTL Template}) to recognize the insn. See 4752@file{rs6000.md} for examples of the use of this insn pattern. 4753 4754@cindex @samp{store_multiple} instruction pattern 4755@item @samp{store_multiple} 4756Similar to @samp{load_multiple}, but store several consecutive registers 4757into consecutive memory locations. Operand 0 is the first of the 4758consecutive memory locations, operand 1 is the first register, and 4759operand 2 is a constant: the number of consecutive registers. 4760 4761@cindex @code{vec_load_lanes@var{m}@var{n}} instruction pattern 4762@item @samp{vec_load_lanes@var{m}@var{n}} 4763Perform an interleaved load of several vectors from memory operand 1 4764into register operand 0. Both operands have mode @var{m}. The register 4765operand is viewed as holding consecutive vectors of mode @var{n}, 4766while the memory operand is a flat array that contains the same number 4767of elements. The operation is equivalent to: 4768 4769@smallexample 4770int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4771for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4772 for (i = 0; i < c; i++) 4773 operand0[i][j] = operand1[j * c + i]; 4774@end smallexample 4775 4776For example, @samp{vec_load_lanestiv4hi} loads 8 16-bit values 4777from memory into a register of mode @samp{TI}@. The register 4778contains two consecutive vectors of mode @samp{V4HI}@. 4779 4780This pattern can only be used if: 4781@smallexample 4782TARGET_ARRAY_MODE_SUPPORTED_P (@var{n}, @var{c}) 4783@end smallexample 4784is true. GCC assumes that, if a target supports this kind of 4785instruction for some mode @var{n}, it also supports unaligned 4786loads for vectors of mode @var{n}. 4787 4788This pattern is not allowed to @code{FAIL}. 4789 4790@cindex @code{vec_store_lanes@var{m}@var{n}} instruction pattern 4791@item @samp{vec_store_lanes@var{m}@var{n}} 4792Equivalent to @samp{vec_load_lanes@var{m}@var{n}}, with the memory 4793and register operands reversed. That is, the instruction is 4794equivalent to: 4795 4796@smallexample 4797int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4798for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4799 for (i = 0; i < c; i++) 4800 operand0[j * c + i] = operand1[i][j]; 4801@end smallexample 4802 4803for a memory operand 0 and register operand 1. 4804 4805This pattern is not allowed to @code{FAIL}. 4806 4807@cindex @code{vec_set@var{m}} instruction pattern 4808@item @samp{vec_set@var{m}} 4809Set given field in the vector value. Operand 0 is the vector to modify, 4810operand 1 is new value of field and operand 2 specify the field index. 4811 4812@cindex @code{vec_extract@var{m}} instruction pattern 4813@item @samp{vec_extract@var{m}} 4814Extract given field from the vector value. Operand 1 is the vector, operand 2 4815specify field index and operand 0 place to store value into. 4816 4817@cindex @code{vec_init@var{m}} instruction pattern 4818@item @samp{vec_init@var{m}} 4819Initialize the vector to given values. Operand 0 is the vector to initialize 4820and operand 1 is parallel containing values for individual fields. 4821 4822@cindex @code{vec_cmp@var{m}@var{n}} instruction pattern 4823@item @samp{vec_cmp@var{m}@var{n}} 4824Output a vector comparison. Operand 0 of mode @var{n} is the destination for 4825predicate in operand 1 which is a signed vector comparison with operands of 4826mode @var{m} in operands 2 and 3. Predicate is computed by element-wise 4827evaluation of the vector comparison with a truth value of all-ones and a false 4828value of all-zeros. 4829 4830@cindex @code{vec_cmpu@var{m}@var{n}} instruction pattern 4831@item @samp{vec_cmpu@var{m}@var{n}} 4832Similar to @code{vec_cmp@var{m}@var{n}} but perform unsigned vector comparison. 4833 4834@cindex @code{vcond@var{m}@var{n}} instruction pattern 4835@item @samp{vcond@var{m}@var{n}} 4836Output a conditional vector move. Operand 0 is the destination to 4837receive a combination of operand 1 and operand 2, which are of mode @var{m}, 4838dependent on the outcome of the predicate in operand 3 which is a signed 4839vector comparison with operands of mode @var{n} in operands 4 and 5. The 4840modes @var{m} and @var{n} should have the same size. Operand 0 4841will be set to the value @var{op1} & @var{msk} | @var{op2} & ~@var{msk} 4842where @var{msk} is computed by element-wise evaluation of the vector 4843comparison with a truth value of all-ones and a false value of all-zeros. 4844 4845@cindex @code{vcondu@var{m}@var{n}} instruction pattern 4846@item @samp{vcondu@var{m}@var{n}} 4847Similar to @code{vcond@var{m}@var{n}} but performs unsigned vector 4848comparison. 4849 4850@cindex @code{vcond_mask_@var{m}@var{n}} instruction pattern 4851@item @samp{vcond_mask_@var{m}@var{n}} 4852Similar to @code{vcond@var{m}@var{n}} but operand 3 holds a pre-computed 4853result of vector comparison. 4854 4855@cindex @code{maskload@var{m}@var{n}} instruction pattern 4856@item @samp{maskload@var{m}@var{n}} 4857Perform a masked load of vector from memory operand 1 of mode @var{m} 4858into register operand 0. Mask is provided in register operand 2 of 4859mode @var{n}. 4860 4861This pattern is not allowed to @code{FAIL}. 4862 4863@cindex @code{maskstore@var{m}@var{n}} instruction pattern 4864@item @samp{maskstore@var{m}@var{n}} 4865Perform a masked store of vector from register operand 1 of mode @var{m} 4866into memory operand 0. Mask is provided in register operand 2 of 4867mode @var{n}. 4868 4869This pattern is not allowed to @code{FAIL}. 4870 4871@cindex @code{vec_perm@var{m}} instruction pattern 4872@item @samp{vec_perm@var{m}} 4873Output a (variable) vector permutation. Operand 0 is the destination 4874to receive elements from operand 1 and operand 2, which are of mode 4875@var{m}. Operand 3 is the @dfn{selector}. It is an integral mode 4876vector of the same width and number of elements as mode @var{m}. 4877 4878The input elements are numbered from 0 in operand 1 through 4879@math{2*@var{N}-1} in operand 2. The elements of the selector must 4880be computed modulo @math{2*@var{N}}. Note that if 4881@code{rtx_equal_p(operand1, operand2)}, this can be implemented 4882with just operand 1 and selector elements modulo @var{N}. 4883 4884In order to make things easy for a number of targets, if there is no 4885@samp{vec_perm} pattern for mode @var{m}, but there is for mode @var{q} 4886where @var{q} is a vector of @code{QImode} of the same width as @var{m}, 4887the middle-end will lower the mode @var{m} @code{VEC_PERM_EXPR} to 4888mode @var{q}. 4889 4890@cindex @code{vec_perm_const@var{m}} instruction pattern 4891@item @samp{vec_perm_const@var{m}} 4892Like @samp{vec_perm} except that the permutation is a compile-time 4893constant. That is, operand 3, the @dfn{selector}, is a @code{CONST_VECTOR}. 4894 4895Some targets cannot perform a permutation with a variable selector, 4896but can efficiently perform a constant permutation. Further, the 4897target hook @code{vec_perm_ok} is queried to determine if the 4898specific constant permutation is available efficiently; the named 4899pattern is never expanded without @code{vec_perm_ok} returning true. 4900 4901There is no need for a target to supply both @samp{vec_perm@var{m}} 4902and @samp{vec_perm_const@var{m}} if the former can trivially implement 4903the operation with, say, the vector constant loaded into a register. 4904 4905@cindex @code{push@var{m}1} instruction pattern 4906@item @samp{push@var{m}1} 4907Output a push instruction. Operand 0 is value to push. Used only when 4908@code{PUSH_ROUNDING} is defined. For historical reason, this pattern may be 4909missing and in such case an @code{mov} expander is used instead, with a 4910@code{MEM} expression forming the push operation. The @code{mov} expander 4911method is deprecated. 4912 4913@cindex @code{add@var{m}3} instruction pattern 4914@item @samp{add@var{m}3} 4915Add operand 2 and operand 1, storing the result in operand 0. All operands 4916must have mode @var{m}. This can be used even on two-address machines, by 4917means of constraints requiring operands 1 and 0 to be the same location. 4918 4919@cindex @code{ssadd@var{m}3} instruction pattern 4920@cindex @code{usadd@var{m}3} instruction pattern 4921@cindex @code{sub@var{m}3} instruction pattern 4922@cindex @code{sssub@var{m}3} instruction pattern 4923@cindex @code{ussub@var{m}3} instruction pattern 4924@cindex @code{mul@var{m}3} instruction pattern 4925@cindex @code{ssmul@var{m}3} instruction pattern 4926@cindex @code{usmul@var{m}3} instruction pattern 4927@cindex @code{div@var{m}3} instruction pattern 4928@cindex @code{ssdiv@var{m}3} instruction pattern 4929@cindex @code{udiv@var{m}3} instruction pattern 4930@cindex @code{usdiv@var{m}3} instruction pattern 4931@cindex @code{mod@var{m}3} instruction pattern 4932@cindex @code{umod@var{m}3} instruction pattern 4933@cindex @code{umin@var{m}3} instruction pattern 4934@cindex @code{umax@var{m}3} instruction pattern 4935@cindex @code{and@var{m}3} instruction pattern 4936@cindex @code{ior@var{m}3} instruction pattern 4937@cindex @code{xor@var{m}3} instruction pattern 4938@item @samp{ssadd@var{m}3}, @samp{usadd@var{m}3} 4939@itemx @samp{sub@var{m}3}, @samp{sssub@var{m}3}, @samp{ussub@var{m}3} 4940@itemx @samp{mul@var{m}3}, @samp{ssmul@var{m}3}, @samp{usmul@var{m}3} 4941@itemx @samp{div@var{m}3}, @samp{ssdiv@var{m}3} 4942@itemx @samp{udiv@var{m}3}, @samp{usdiv@var{m}3} 4943@itemx @samp{mod@var{m}3}, @samp{umod@var{m}3} 4944@itemx @samp{umin@var{m}3}, @samp{umax@var{m}3} 4945@itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3} 4946Similar, for other arithmetic operations. 4947 4948@cindex @code{addv@var{m}4} instruction pattern 4949@item @samp{addv@var{m}4} 4950Like @code{add@var{m}3} but takes a @code{code_label} as operand 3 and 4951emits code to jump to it if signed overflow occurs during the addition. 4952This pattern is used to implement the built-in functions performing 4953signed integer addition with overflow checking. 4954 4955@cindex @code{subv@var{m}4} instruction pattern 4956@cindex @code{mulv@var{m}4} instruction pattern 4957@item @samp{subv@var{m}4}, @samp{mulv@var{m}4} 4958Similar, for other signed arithmetic operations. 4959 4960@cindex @code{uaddv@var{m}4} instruction pattern 4961@item @samp{uaddv@var{m}4} 4962Like @code{addv@var{m}4} but for unsigned addition. That is to 4963say, the operation is the same as signed addition but the jump 4964is taken only on unsigned overflow. 4965 4966@cindex @code{usubv@var{m}4} instruction pattern 4967@cindex @code{umulv@var{m}4} instruction pattern 4968@item @samp{usubv@var{m}4}, @samp{umulv@var{m}4} 4969Similar, for other unsigned arithmetic operations. 4970 4971@cindex @code{addptr@var{m}3} instruction pattern 4972@item @samp{addptr@var{m}3} 4973Like @code{add@var{m}3} but is guaranteed to only be used for address 4974calculations. The expanded code is not allowed to clobber the 4975condition code. It only needs to be defined if @code{add@var{m}3} 4976sets the condition code. If adds used for address calculations and 4977normal adds are not compatible it is required to expand a distinct 4978pattern (e.g. using an unspec). The pattern is used by LRA to emit 4979address calculations. @code{add@var{m}3} is used if 4980@code{addptr@var{m}3} is not defined. 4981 4982@cindex @code{fma@var{m}4} instruction pattern 4983@item @samp{fma@var{m}4} 4984Multiply operand 2 and operand 1, then add operand 3, storing the 4985result in operand 0 without doing an intermediate rounding step. All 4986operands must have mode @var{m}. This pattern is used to implement 4987the @code{fma}, @code{fmaf}, and @code{fmal} builtin functions from 4988the ISO C99 standard. 4989 4990@cindex @code{fms@var{m}4} instruction pattern 4991@item @samp{fms@var{m}4} 4992Like @code{fma@var{m}4}, except operand 3 subtracted from the 4993product instead of added to the product. This is represented 4994in the rtl as 4995 4996@smallexample 4997(fma:@var{m} @var{op1} @var{op2} (neg:@var{m} @var{op3})) 4998@end smallexample 4999 5000@cindex @code{fnma@var{m}4} instruction pattern 5001@item @samp{fnma@var{m}4} 5002Like @code{fma@var{m}4} except that the intermediate product 5003is negated before being added to operand 3. This is represented 5004in the rtl as 5005 5006@smallexample 5007(fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} @var{op3}) 5008@end smallexample 5009 5010@cindex @code{fnms@var{m}4} instruction pattern 5011@item @samp{fnms@var{m}4} 5012Like @code{fms@var{m}4} except that the intermediate product 5013is negated before subtracting operand 3. This is represented 5014in the rtl as 5015 5016@smallexample 5017(fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} (neg:@var{m} @var{op3})) 5018@end smallexample 5019 5020@cindex @code{min@var{m}3} instruction pattern 5021@cindex @code{max@var{m}3} instruction pattern 5022@item @samp{smin@var{m}3}, @samp{smax@var{m}3} 5023Signed minimum and maximum operations. When used with floating point, 5024if both operands are zeros, or if either operand is @code{NaN}, then 5025it is unspecified which of the two operands is returned as the result. 5026 5027@cindex @code{fmin@var{m}3} instruction pattern 5028@cindex @code{fmax@var{m}3} instruction pattern 5029@item @samp{fmin@var{m}3}, @samp{fmax@var{m}3} 5030IEEE-conformant minimum and maximum operations. If one operand is a quiet 5031@code{NaN}, then the other operand is returned. If both operands are quiet 5032@code{NaN}, then a quiet @code{NaN} is returned. In the case when gcc supports 5033signalling @code{NaN} (-fsignaling-nans) an invalid floating point exception is 5034raised and a quiet @code{NaN} is returned. 5035 5036All operands have mode @var{m}, which is a scalar or vector 5037floating-point mode. These patterns are not allowed to @code{FAIL}. 5038 5039@cindex @code{reduc_smin_scal_@var{m}} instruction pattern 5040@cindex @code{reduc_smax_scal_@var{m}} instruction pattern 5041@item @samp{reduc_smin_scal_@var{m}}, @samp{reduc_smax_scal_@var{m}} 5042Find the signed minimum/maximum of the elements of a vector. The vector is 5043operand 1, and operand 0 is the scalar result, with mode equal to the mode of 5044the elements of the input vector. 5045 5046@cindex @code{reduc_umin_scal_@var{m}} instruction pattern 5047@cindex @code{reduc_umax_scal_@var{m}} instruction pattern 5048@item @samp{reduc_umin_scal_@var{m}}, @samp{reduc_umax_scal_@var{m}} 5049Find the unsigned minimum/maximum of the elements of a vector. The vector is 5050operand 1, and operand 0 is the scalar result, with mode equal to the mode of 5051the elements of the input vector. 5052 5053@cindex @code{reduc_plus_scal_@var{m}} instruction pattern 5054@item @samp{reduc_plus_scal_@var{m}} 5055Compute the sum of the elements of a vector. The vector is operand 1, and 5056operand 0 is the scalar result, with mode equal to the mode of the elements of 5057the input vector. 5058 5059@cindex @code{sdot_prod@var{m}} instruction pattern 5060@item @samp{sdot_prod@var{m}} 5061@cindex @code{udot_prod@var{m}} instruction pattern 5062@itemx @samp{udot_prod@var{m}} 5063Compute the sum of the products of two signed/unsigned elements. 5064Operand 1 and operand 2 are of the same mode. Their product, which is of a 5065wider mode, is computed and added to operand 3. Operand 3 is of a mode equal or 5066wider than the mode of the product. The result is placed in operand 0, which 5067is of the same mode as operand 3. 5068 5069@cindex @code{ssad@var{m}} instruction pattern 5070@item @samp{ssad@var{m}} 5071@cindex @code{usad@var{m}} instruction pattern 5072@item @samp{usad@var{m}} 5073Compute the sum of absolute differences of two signed/unsigned elements. 5074Operand 1 and operand 2 are of the same mode. Their absolute difference, which 5075is of a wider mode, is computed and added to operand 3. Operand 3 is of a mode 5076equal or wider than the mode of the absolute difference. The result is placed 5077in operand 0, which is of the same mode as operand 3. 5078 5079@cindex @code{widen_ssum@var{m3}} instruction pattern 5080@item @samp{widen_ssum@var{m3}} 5081@cindex @code{widen_usum@var{m3}} instruction pattern 5082@itemx @samp{widen_usum@var{m3}} 5083Operands 0 and 2 are of the same mode, which is wider than the mode of 5084operand 1. Add operand 1 to operand 2 and place the widened result in 5085operand 0. (This is used express accumulation of elements into an accumulator 5086of a wider mode.) 5087 5088@cindex @code{vec_shr_@var{m}} instruction pattern 5089@item @samp{vec_shr_@var{m}} 5090Whole vector right shift in bits, i.e. towards element 0. 5091Operand 1 is a vector to be shifted. 5092Operand 2 is an integer shift amount in bits. 5093Operand 0 is where the resulting shifted vector is stored. 5094The output and input vectors should have the same modes. 5095 5096@cindex @code{vec_pack_trunc_@var{m}} instruction pattern 5097@item @samp{vec_pack_trunc_@var{m}} 5098Narrow (demote) and merge the elements of two vectors. Operands 1 and 2 5099are vectors of the same mode having N integral or floating point elements 5100of size S@. Operand 0 is the resulting vector in which 2*N elements of 5101size N/2 are concatenated after narrowing them down using truncation. 5102 5103@cindex @code{vec_pack_ssat_@var{m}} instruction pattern 5104@cindex @code{vec_pack_usat_@var{m}} instruction pattern 5105@item @samp{vec_pack_ssat_@var{m}}, @samp{vec_pack_usat_@var{m}} 5106Narrow (demote) and merge the elements of two vectors. Operands 1 and 2 5107are vectors of the same mode having N integral elements of size S. 5108Operand 0 is the resulting vector in which the elements of the two input 5109vectors are concatenated after narrowing them down using signed/unsigned 5110saturating arithmetic. 5111 5112@cindex @code{vec_pack_sfix_trunc_@var{m}} instruction pattern 5113@cindex @code{vec_pack_ufix_trunc_@var{m}} instruction pattern 5114@item @samp{vec_pack_sfix_trunc_@var{m}}, @samp{vec_pack_ufix_trunc_@var{m}} 5115Narrow, convert to signed/unsigned integral type and merge the elements 5116of two vectors. Operands 1 and 2 are vectors of the same mode having N 5117floating point elements of size S@. Operand 0 is the resulting vector 5118in which 2*N elements of size N/2 are concatenated. 5119 5120@cindex @code{vec_unpacks_hi_@var{m}} instruction pattern 5121@cindex @code{vec_unpacks_lo_@var{m}} instruction pattern 5122@item @samp{vec_unpacks_hi_@var{m}}, @samp{vec_unpacks_lo_@var{m}} 5123Extract and widen (promote) the high/low part of a vector of signed 5124integral or floating point elements. The input vector (operand 1) has N 5125elements of size S@. Widen (promote) the high/low elements of the vector 5126using signed or floating point extension and place the resulting N/2 5127values of size 2*S in the output vector (operand 0). 5128 5129@cindex @code{vec_unpacku_hi_@var{m}} instruction pattern 5130@cindex @code{vec_unpacku_lo_@var{m}} instruction pattern 5131@item @samp{vec_unpacku_hi_@var{m}}, @samp{vec_unpacku_lo_@var{m}} 5132Extract and widen (promote) the high/low part of a vector of unsigned 5133integral elements. The input vector (operand 1) has N elements of size S. 5134Widen (promote) the high/low elements of the vector using zero extension and 5135place the resulting N/2 values of size 2*S in the output vector (operand 0). 5136 5137@cindex @code{vec_unpacks_float_hi_@var{m}} instruction pattern 5138@cindex @code{vec_unpacks_float_lo_@var{m}} instruction pattern 5139@cindex @code{vec_unpacku_float_hi_@var{m}} instruction pattern 5140@cindex @code{vec_unpacku_float_lo_@var{m}} instruction pattern 5141@item @samp{vec_unpacks_float_hi_@var{m}}, @samp{vec_unpacks_float_lo_@var{m}} 5142@itemx @samp{vec_unpacku_float_hi_@var{m}}, @samp{vec_unpacku_float_lo_@var{m}} 5143Extract, convert to floating point type and widen the high/low part of a 5144vector of signed/unsigned integral elements. The input vector (operand 1) 5145has N elements of size S@. Convert the high/low elements of the vector using 5146floating point conversion and place the resulting N/2 values of size 2*S in 5147the output vector (operand 0). 5148 5149@cindex @code{vec_widen_umult_hi_@var{m}} instruction pattern 5150@cindex @code{vec_widen_umult_lo_@var{m}} instruction pattern 5151@cindex @code{vec_widen_smult_hi_@var{m}} instruction pattern 5152@cindex @code{vec_widen_smult_lo_@var{m}} instruction pattern 5153@cindex @code{vec_widen_umult_even_@var{m}} instruction pattern 5154@cindex @code{vec_widen_umult_odd_@var{m}} instruction pattern 5155@cindex @code{vec_widen_smult_even_@var{m}} instruction pattern 5156@cindex @code{vec_widen_smult_odd_@var{m}} instruction pattern 5157@item @samp{vec_widen_umult_hi_@var{m}}, @samp{vec_widen_umult_lo_@var{m}} 5158@itemx @samp{vec_widen_smult_hi_@var{m}}, @samp{vec_widen_smult_lo_@var{m}} 5159@itemx @samp{vec_widen_umult_even_@var{m}}, @samp{vec_widen_umult_odd_@var{m}} 5160@itemx @samp{vec_widen_smult_even_@var{m}}, @samp{vec_widen_smult_odd_@var{m}} 5161Signed/Unsigned widening multiplication. The two inputs (operands 1 and 2) 5162are vectors with N signed/unsigned elements of size S@. Multiply the high/low 5163or even/odd elements of the two vectors, and put the N/2 products of size 2*S 5164in the output vector (operand 0). A target shouldn't implement even/odd pattern 5165pair if it is less efficient than lo/hi one. 5166 5167@cindex @code{vec_widen_ushiftl_hi_@var{m}} instruction pattern 5168@cindex @code{vec_widen_ushiftl_lo_@var{m}} instruction pattern 5169@cindex @code{vec_widen_sshiftl_hi_@var{m}} instruction pattern 5170@cindex @code{vec_widen_sshiftl_lo_@var{m}} instruction pattern 5171@item @samp{vec_widen_ushiftl_hi_@var{m}}, @samp{vec_widen_ushiftl_lo_@var{m}} 5172@itemx @samp{vec_widen_sshiftl_hi_@var{m}}, @samp{vec_widen_sshiftl_lo_@var{m}} 5173Signed/Unsigned widening shift left. The first input (operand 1) is a vector 5174with N signed/unsigned elements of size S@. Operand 2 is a constant. Shift 5175the high/low elements of operand 1, and put the N/2 results of size 2*S in the 5176output vector (operand 0). 5177 5178@cindex @code{mulhisi3} instruction pattern 5179@item @samp{mulhisi3} 5180Multiply operands 1 and 2, which have mode @code{HImode}, and store 5181a @code{SImode} product in operand 0. 5182 5183@cindex @code{mulqihi3} instruction pattern 5184@cindex @code{mulsidi3} instruction pattern 5185@item @samp{mulqihi3}, @samp{mulsidi3} 5186Similar widening-multiplication instructions of other widths. 5187 5188@cindex @code{umulqihi3} instruction pattern 5189@cindex @code{umulhisi3} instruction pattern 5190@cindex @code{umulsidi3} instruction pattern 5191@item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3} 5192Similar widening-multiplication instructions that do unsigned 5193multiplication. 5194 5195@cindex @code{usmulqihi3} instruction pattern 5196@cindex @code{usmulhisi3} instruction pattern 5197@cindex @code{usmulsidi3} instruction pattern 5198@item @samp{usmulqihi3}, @samp{usmulhisi3}, @samp{usmulsidi3} 5199Similar widening-multiplication instructions that interpret the first 5200operand as unsigned and the second operand as signed, then do a signed 5201multiplication. 5202 5203@cindex @code{smul@var{m}3_highpart} instruction pattern 5204@item @samp{smul@var{m}3_highpart} 5205Perform a signed multiplication of operands 1 and 2, which have mode 5206@var{m}, and store the most significant half of the product in operand 0. 5207The least significant half of the product is discarded. 5208 5209@cindex @code{umul@var{m}3_highpart} instruction pattern 5210@item @samp{umul@var{m}3_highpart} 5211Similar, but the multiplication is unsigned. 5212 5213@cindex @code{madd@var{m}@var{n}4} instruction pattern 5214@item @samp{madd@var{m}@var{n}4} 5215Multiply operands 1 and 2, sign-extend them to mode @var{n}, add 5216operand 3, and store the result in operand 0. Operands 1 and 2 5217have mode @var{m} and operands 0 and 3 have mode @var{n}. 5218Both modes must be integer or fixed-point modes and @var{n} must be twice 5219the size of @var{m}. 5220 5221In other words, @code{madd@var{m}@var{n}4} is like 5222@code{mul@var{m}@var{n}3} except that it also adds operand 3. 5223 5224These instructions are not allowed to @code{FAIL}. 5225 5226@cindex @code{umadd@var{m}@var{n}4} instruction pattern 5227@item @samp{umadd@var{m}@var{n}4} 5228Like @code{madd@var{m}@var{n}4}, but zero-extend the multiplication 5229operands instead of sign-extending them. 5230 5231@cindex @code{ssmadd@var{m}@var{n}4} instruction pattern 5232@item @samp{ssmadd@var{m}@var{n}4} 5233Like @code{madd@var{m}@var{n}4}, but all involved operations must be 5234signed-saturating. 5235 5236@cindex @code{usmadd@var{m}@var{n}4} instruction pattern 5237@item @samp{usmadd@var{m}@var{n}4} 5238Like @code{umadd@var{m}@var{n}4}, but all involved operations must be 5239unsigned-saturating. 5240 5241@cindex @code{msub@var{m}@var{n}4} instruction pattern 5242@item @samp{msub@var{m}@var{n}4} 5243Multiply operands 1 and 2, sign-extend them to mode @var{n}, subtract the 5244result from operand 3, and store the result in operand 0. Operands 1 and 2 5245have mode @var{m} and operands 0 and 3 have mode @var{n}. 5246Both modes must be integer or fixed-point modes and @var{n} must be twice 5247the size of @var{m}. 5248 5249In other words, @code{msub@var{m}@var{n}4} is like 5250@code{mul@var{m}@var{n}3} except that it also subtracts the result 5251from operand 3. 5252 5253These instructions are not allowed to @code{FAIL}. 5254 5255@cindex @code{umsub@var{m}@var{n}4} instruction pattern 5256@item @samp{umsub@var{m}@var{n}4} 5257Like @code{msub@var{m}@var{n}4}, but zero-extend the multiplication 5258operands instead of sign-extending them. 5259 5260@cindex @code{ssmsub@var{m}@var{n}4} instruction pattern 5261@item @samp{ssmsub@var{m}@var{n}4} 5262Like @code{msub@var{m}@var{n}4}, but all involved operations must be 5263signed-saturating. 5264 5265@cindex @code{usmsub@var{m}@var{n}4} instruction pattern 5266@item @samp{usmsub@var{m}@var{n}4} 5267Like @code{umsub@var{m}@var{n}4}, but all involved operations must be 5268unsigned-saturating. 5269 5270@cindex @code{divmod@var{m}4} instruction pattern 5271@item @samp{divmod@var{m}4} 5272Signed division that produces both a quotient and a remainder. 5273Operand 1 is divided by operand 2 to produce a quotient stored 5274in operand 0 and a remainder stored in operand 3. 5275 5276For machines with an instruction that produces both a quotient and a 5277remainder, provide a pattern for @samp{divmod@var{m}4} but do not 5278provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}. This 5279allows optimization in the relatively common case when both the quotient 5280and remainder are computed. 5281 5282If an instruction that just produces a quotient or just a remainder 5283exists and is more efficient than the instruction that produces both, 5284write the output routine of @samp{divmod@var{m}4} to call 5285@code{find_reg_note} and look for a @code{REG_UNUSED} note on the 5286quotient or remainder and generate the appropriate instruction. 5287 5288@cindex @code{udivmod@var{m}4} instruction pattern 5289@item @samp{udivmod@var{m}4} 5290Similar, but does unsigned division. 5291 5292@anchor{shift patterns} 5293@cindex @code{ashl@var{m}3} instruction pattern 5294@cindex @code{ssashl@var{m}3} instruction pattern 5295@cindex @code{usashl@var{m}3} instruction pattern 5296@item @samp{ashl@var{m}3}, @samp{ssashl@var{m}3}, @samp{usashl@var{m}3} 5297Arithmetic-shift operand 1 left by a number of bits specified by operand 52982, and store the result in operand 0. Here @var{m} is the mode of 5299operand 0 and operand 1; operand 2's mode is specified by the 5300instruction pattern, and the compiler will convert the operand to that 5301mode before generating the instruction. The shift or rotate expander 5302or instruction pattern should explicitly specify the mode of the operand 2, 5303it should never be @code{VOIDmode}. The meaning of out-of-range shift 5304counts can optionally be specified by @code{TARGET_SHIFT_TRUNCATION_MASK}. 5305@xref{TARGET_SHIFT_TRUNCATION_MASK}. Operand 2 is always a scalar type. 5306 5307@cindex @code{ashr@var{m}3} instruction pattern 5308@cindex @code{lshr@var{m}3} instruction pattern 5309@cindex @code{rotl@var{m}3} instruction pattern 5310@cindex @code{rotr@var{m}3} instruction pattern 5311@item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3} 5312Other shift and rotate instructions, analogous to the 5313@code{ashl@var{m}3} instructions. Operand 2 is always a scalar type. 5314 5315@cindex @code{vashl@var{m}3} instruction pattern 5316@cindex @code{vashr@var{m}3} instruction pattern 5317@cindex @code{vlshr@var{m}3} instruction pattern 5318@cindex @code{vrotl@var{m}3} instruction pattern 5319@cindex @code{vrotr@var{m}3} instruction pattern 5320@item @samp{vashl@var{m}3}, @samp{vashr@var{m}3}, @samp{vlshr@var{m}3}, @samp{vrotl@var{m}3}, @samp{vrotr@var{m}3} 5321Vector shift and rotate instructions that take vectors as operand 2 5322instead of a scalar type. 5323 5324@cindex @code{bswap@var{m}2} instruction pattern 5325@item @samp{bswap@var{m}2} 5326Reverse the order of bytes of operand 1 and store the result in operand 0. 5327 5328@cindex @code{neg@var{m}2} instruction pattern 5329@cindex @code{ssneg@var{m}2} instruction pattern 5330@cindex @code{usneg@var{m}2} instruction pattern 5331@item @samp{neg@var{m}2}, @samp{ssneg@var{m}2}, @samp{usneg@var{m}2} 5332Negate operand 1 and store the result in operand 0. 5333 5334@cindex @code{negv@var{m}3} instruction pattern 5335@item @samp{negv@var{m}3} 5336Like @code{neg@var{m}2} but takes a @code{code_label} as operand 2 and 5337emits code to jump to it if signed overflow occurs during the negation. 5338 5339@cindex @code{abs@var{m}2} instruction pattern 5340@item @samp{abs@var{m}2} 5341Store the absolute value of operand 1 into operand 0. 5342 5343@cindex @code{sqrt@var{m}2} instruction pattern 5344@item @samp{sqrt@var{m}2} 5345Store the square root of operand 1 into operand 0. Both operands have 5346mode @var{m}, which is a scalar or vector floating-point mode. 5347 5348This pattern is not allowed to @code{FAIL}. 5349 5350@cindex @code{rsqrt@var{m}2} instruction pattern 5351@item @samp{rsqrt@var{m}2} 5352Store the reciprocal of the square root of operand 1 into operand 0. 5353Both operands have mode @var{m}, which is a scalar or vector 5354floating-point mode. 5355 5356On most architectures this pattern is only approximate, so either 5357its C condition or the @code{TARGET_OPTAB_SUPPORTED_P} hook should 5358check for the appropriate math flags. (Using the C condition is 5359more direct, but using @code{TARGET_OPTAB_SUPPORTED_P} can be useful 5360if a target-specific built-in also uses the @samp{rsqrt@var{m}2} 5361pattern.) 5362 5363This pattern is not allowed to @code{FAIL}. 5364 5365@cindex @code{fmod@var{m}3} instruction pattern 5366@item @samp{fmod@var{m}3} 5367Store the remainder of dividing operand 1 by operand 2 into 5368operand 0, rounded towards zero to an integer. All operands have 5369mode @var{m}, which is a scalar or vector floating-point mode. 5370 5371This pattern is not allowed to @code{FAIL}. 5372 5373@cindex @code{remainder@var{m}3} instruction pattern 5374@item @samp{remainder@var{m}3} 5375Store the remainder of dividing operand 1 by operand 2 into 5376operand 0, rounded to the nearest integer. All operands have 5377mode @var{m}, which is a scalar or vector floating-point mode. 5378 5379This pattern is not allowed to @code{FAIL}. 5380 5381@cindex @code{scalb@var{m}3} instruction pattern 5382@item @samp{scalb@var{m}3} 5383Raise @code{FLT_RADIX} to the power of operand 2, multiply it by 5384operand 1, and store the result in operand 0. All operands have 5385mode @var{m}, which is a scalar or vector floating-point mode. 5386 5387This pattern is not allowed to @code{FAIL}. 5388 5389@cindex @code{ldexp@var{m}3} instruction pattern 5390@item @samp{ldexp@var{m}3} 5391Raise 2 to the power of operand 2, multiply it by operand 1, and store 5392the result in operand 0. Operands 0 and 1 have mode @var{m}, which is 5393a scalar or vector floating-point mode. Operand 2's mode has 5394the same number of elements as @var{m} and each element is wide 5395enough to store an @code{int}. The integers are signed. 5396 5397This pattern is not allowed to @code{FAIL}. 5398 5399@cindex @code{cos@var{m}2} instruction pattern 5400@item @samp{cos@var{m}2} 5401Store the cosine of operand 1 into operand 0. Both operands have 5402mode @var{m}, which is a scalar or vector floating-point mode. 5403 5404This pattern is not allowed to @code{FAIL}. 5405 5406@cindex @code{sin@var{m}2} instruction pattern 5407@item @samp{sin@var{m}2} 5408Store the sine of operand 1 into operand 0. Both operands have 5409mode @var{m}, which is a scalar or vector floating-point mode. 5410 5411This pattern is not allowed to @code{FAIL}. 5412 5413@cindex @code{sincos@var{m}3} instruction pattern 5414@item @samp{sincos@var{m}3} 5415Store the cosine of operand 2 into operand 0 and the sine of 5416operand 2 into operand 1. All operands have mode @var{m}, 5417which is a scalar or vector floating-point mode. 5418 5419Targets that can calculate the sine and cosine simultaneously can 5420implement this pattern as opposed to implementing individual 5421@code{sin@var{m}2} and @code{cos@var{m}2} patterns. The @code{sin} 5422and @code{cos} built-in functions will then be expanded to the 5423@code{sincos@var{m}3} pattern, with one of the output values 5424left unused. 5425 5426@cindex @code{tan@var{m}2} instruction pattern 5427@item @samp{tan@var{m}2} 5428Store the tangent of operand 1 into operand 0. Both operands have 5429mode @var{m}, which is a scalar or vector floating-point mode. 5430 5431This pattern is not allowed to @code{FAIL}. 5432 5433@cindex @code{asin@var{m}2} instruction pattern 5434@item @samp{asin@var{m}2} 5435Store the arc sine of operand 1 into operand 0. Both operands have 5436mode @var{m}, which is a scalar or vector floating-point mode. 5437 5438This pattern is not allowed to @code{FAIL}. 5439 5440@cindex @code{acos@var{m}2} instruction pattern 5441@item @samp{acos@var{m}2} 5442Store the arc cosine of operand 1 into operand 0. Both operands have 5443mode @var{m}, which is a scalar or vector floating-point mode. 5444 5445This pattern is not allowed to @code{FAIL}. 5446 5447@cindex @code{atan@var{m}2} instruction pattern 5448@item @samp{atan@var{m}2} 5449Store the arc tangent of operand 1 into operand 0. Both operands have 5450mode @var{m}, which is a scalar or vector floating-point mode. 5451 5452This pattern is not allowed to @code{FAIL}. 5453 5454@cindex @code{exp@var{m}2} instruction pattern 5455@item @samp{exp@var{m}2} 5456Raise e (the base of natural logarithms) to the power of operand 1 5457and store the result in operand 0. Both operands have mode @var{m}, 5458which is a scalar or vector floating-point mode. 5459 5460This pattern is not allowed to @code{FAIL}. 5461 5462@cindex @code{expm1@var{m}2} instruction pattern 5463@item @samp{expm1@var{m}2} 5464Raise e (the base of natural logarithms) to the power of operand 1, 5465subtract 1, and store the result in operand 0. Both operands have 5466mode @var{m}, which is a scalar or vector floating-point mode. 5467 5468For inputs close to zero, the pattern is expected to be more 5469accurate than a separate @code{exp@var{m}2} and @code{sub@var{m}3} 5470would be. 5471 5472This pattern is not allowed to @code{FAIL}. 5473 5474@cindex @code{exp10@var{m}2} instruction pattern 5475@item @samp{exp10@var{m}2} 5476Raise 10 to the power of operand 1 and store the result in operand 0. 5477Both operands have mode @var{m}, which is a scalar or vector 5478floating-point mode. 5479 5480This pattern is not allowed to @code{FAIL}. 5481 5482@cindex @code{exp2@var{m}2} instruction pattern 5483@item @samp{exp2@var{m}2} 5484Raise 2 to the power of operand 1 and store the result in operand 0. 5485Both operands have mode @var{m}, which is a scalar or vector 5486floating-point mode. 5487 5488This pattern is not allowed to @code{FAIL}. 5489 5490@cindex @code{log@var{m}2} instruction pattern 5491@item @samp{log@var{m}2} 5492Store the natural logarithm of operand 1 into operand 0. Both operands 5493have mode @var{m}, which is a scalar or vector floating-point mode. 5494 5495This pattern is not allowed to @code{FAIL}. 5496 5497@cindex @code{log1p@var{m}2} instruction pattern 5498@item @samp{log1p@var{m}2} 5499Add 1 to operand 1, compute the natural logarithm, and store 5500the result in operand 0. Both operands have mode @var{m}, which is 5501a scalar or vector floating-point mode. 5502 5503For inputs close to zero, the pattern is expected to be more 5504accurate than a separate @code{add@var{m}3} and @code{log@var{m}2} 5505would be. 5506 5507This pattern is not allowed to @code{FAIL}. 5508 5509@cindex @code{log10@var{m}2} instruction pattern 5510@item @samp{log10@var{m}2} 5511Store the base-10 logarithm of operand 1 into operand 0. Both operands 5512have mode @var{m}, which is a scalar or vector floating-point mode. 5513 5514This pattern is not allowed to @code{FAIL}. 5515 5516@cindex @code{log2@var{m}2} instruction pattern 5517@item @samp{log2@var{m}2} 5518Store the base-2 logarithm of operand 1 into operand 0. Both operands 5519have mode @var{m}, which is a scalar or vector floating-point mode. 5520 5521This pattern is not allowed to @code{FAIL}. 5522 5523@cindex @code{logb@var{m}2} instruction pattern 5524@item @samp{logb@var{m}2} 5525Store the base-@code{FLT_RADIX} logarithm of operand 1 into operand 0. 5526Both operands have mode @var{m}, which is a scalar or vector 5527floating-point mode. 5528 5529This pattern is not allowed to @code{FAIL}. 5530 5531@cindex @code{significand@var{m}2} instruction pattern 5532@item @samp{significand@var{m}2} 5533Store the significand of floating-point operand 1 in operand 0. 5534Both operands have mode @var{m}, which is a scalar or vector 5535floating-point mode. 5536 5537This pattern is not allowed to @code{FAIL}. 5538 5539@cindex @code{pow@var{m}3} instruction pattern 5540@item @samp{pow@var{m}3} 5541Store the value of operand 1 raised to the exponent operand 2 5542into operand 0. All operands have mode @var{m}, which is a scalar 5543or vector floating-point mode. 5544 5545This pattern is not allowed to @code{FAIL}. 5546 5547@cindex @code{atan2@var{m}3} instruction pattern 5548@item @samp{atan2@var{m}3} 5549Store the arc tangent (inverse tangent) of operand 1 divided by 5550operand 2 into operand 0, using the signs of both arguments to 5551determine the quadrant of the result. All operands have mode 5552@var{m}, which is a scalar or vector floating-point mode. 5553 5554This pattern is not allowed to @code{FAIL}. 5555 5556@cindex @code{floor@var{m}2} instruction pattern 5557@item @samp{floor@var{m}2} 5558Store the largest integral value not greater than operand 1 in operand 0. 5559Both operands have mode @var{m}, which is a scalar or vector 5560floating-point mode. 5561 5562This pattern is not allowed to @code{FAIL}. 5563 5564@cindex @code{btrunc@var{m}2} instruction pattern 5565@item @samp{btrunc@var{m}2} 5566Round operand 1 to an integer, towards zero, and store the result in 5567operand 0. Both operands have mode @var{m}, which is a scalar or 5568vector floating-point mode. 5569 5570This pattern is not allowed to @code{FAIL}. 5571 5572@cindex @code{round@var{m}2} instruction pattern 5573@item @samp{round@var{m}2} 5574Round operand 1 to the nearest integer, rounding away from zero in the 5575event of a tie, and store the result in operand 0. Both operands have 5576mode @var{m}, which is a scalar or vector floating-point mode. 5577 5578This pattern is not allowed to @code{FAIL}. 5579 5580@cindex @code{ceil@var{m}2} instruction pattern 5581@item @samp{ceil@var{m}2} 5582Store the smallest integral value not less than operand 1 in operand 0. 5583Both operands have mode @var{m}, which is a scalar or vector 5584floating-point mode. 5585 5586This pattern is not allowed to @code{FAIL}. 5587 5588@cindex @code{nearbyint@var{m}2} instruction pattern 5589@item @samp{nearbyint@var{m}2} 5590Round operand 1 to an integer, using the current rounding mode, and 5591store the result in operand 0. Do not raise an inexact condition when 5592the result is different from the argument. Both operands have mode 5593@var{m}, which is a scalar or vector floating-point mode. 5594 5595This pattern is not allowed to @code{FAIL}. 5596 5597@cindex @code{rint@var{m}2} instruction pattern 5598@item @samp{rint@var{m}2} 5599Round operand 1 to an integer, using the current rounding mode, and 5600store the result in operand 0. Raise an inexact condition when 5601the result is different from the argument. Both operands have mode 5602@var{m}, which is a scalar or vector floating-point mode. 5603 5604This pattern is not allowed to @code{FAIL}. 5605 5606@cindex @code{lrint@var{m}@var{n}2} 5607@item @samp{lrint@var{m}@var{n}2} 5608Convert operand 1 (valid for floating point mode @var{m}) to fixed 5609point mode @var{n} as a signed number according to the current 5610rounding mode and store in operand 0 (which has mode @var{n}). 5611 5612@cindex @code{lround@var{m}@var{n}2} 5613@item @samp{lround@var{m}@var{n}2} 5614Convert operand 1 (valid for floating point mode @var{m}) to fixed 5615point mode @var{n} as a signed number rounding to nearest and away 5616from zero and store in operand 0 (which has mode @var{n}). 5617 5618@cindex @code{lfloor@var{m}@var{n}2} 5619@item @samp{lfloor@var{m}@var{n}2} 5620Convert operand 1 (valid for floating point mode @var{m}) to fixed 5621point mode @var{n} as a signed number rounding down and store in 5622operand 0 (which has mode @var{n}). 5623 5624@cindex @code{lceil@var{m}@var{n}2} 5625@item @samp{lceil@var{m}@var{n}2} 5626Convert operand 1 (valid for floating point mode @var{m}) to fixed 5627point mode @var{n} as a signed number rounding up and store in 5628operand 0 (which has mode @var{n}). 5629 5630@cindex @code{copysign@var{m}3} instruction pattern 5631@item @samp{copysign@var{m}3} 5632Store a value with the magnitude of operand 1 and the sign of operand 56332 into operand 0. All operands have mode @var{m}, which is a scalar or 5634vector floating-point mode. 5635 5636This pattern is not allowed to @code{FAIL}. 5637 5638@cindex @code{ffs@var{m}2} instruction pattern 5639@item @samp{ffs@var{m}2} 5640Store into operand 0 one plus the index of the least significant 1-bit 5641of operand 1. If operand 1 is zero, store zero. 5642 5643@var{m} is either a scalar or vector integer mode. When it is a scalar, 5644operand 1 has mode @var{m} but operand 0 can have whatever scalar 5645integer mode is suitable for the target. The compiler will insert 5646conversion instructions as necessary (typically to convert the result 5647to the same width as @code{int}). When @var{m} is a vector, both 5648operands must have mode @var{m}. 5649 5650This pattern is not allowed to @code{FAIL}. 5651 5652@cindex @code{clrsb@var{m}2} instruction pattern 5653@item @samp{clrsb@var{m}2} 5654Count leading redundant sign bits. 5655Store into operand 0 the number of redundant sign bits in operand 1, starting 5656at the most significant bit position. 5657A redundant sign bit is defined as any sign bit after the first. As such, 5658this count will be one less than the count of leading sign bits. 5659 5660@var{m} is either a scalar or vector integer mode. When it is a scalar, 5661operand 1 has mode @var{m} but operand 0 can have whatever scalar 5662integer mode is suitable for the target. The compiler will insert 5663conversion instructions as necessary (typically to convert the result 5664to the same width as @code{int}). When @var{m} is a vector, both 5665operands must have mode @var{m}. 5666 5667This pattern is not allowed to @code{FAIL}. 5668 5669@cindex @code{clz@var{m}2} instruction pattern 5670@item @samp{clz@var{m}2} 5671Store into operand 0 the number of leading 0-bits in operand 1, starting 5672at the most significant bit position. If operand 1 is 0, the 5673@code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if 5674the result is undefined or has a useful value. 5675 5676@var{m} is either a scalar or vector integer mode. When it is a scalar, 5677operand 1 has mode @var{m} but operand 0 can have whatever scalar 5678integer mode is suitable for the target. The compiler will insert 5679conversion instructions as necessary (typically to convert the result 5680to the same width as @code{int}). When @var{m} is a vector, both 5681operands must have mode @var{m}. 5682 5683This pattern is not allowed to @code{FAIL}. 5684 5685@cindex @code{ctz@var{m}2} instruction pattern 5686@item @samp{ctz@var{m}2} 5687Store into operand 0 the number of trailing 0-bits in operand 1, starting 5688at the least significant bit position. If operand 1 is 0, the 5689@code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if 5690the result is undefined or has a useful value. 5691 5692@var{m} is either a scalar or vector integer mode. When it is a scalar, 5693operand 1 has mode @var{m} but operand 0 can have whatever scalar 5694integer mode is suitable for the target. The compiler will insert 5695conversion instructions as necessary (typically to convert the result 5696to the same width as @code{int}). When @var{m} is a vector, both 5697operands must have mode @var{m}. 5698 5699This pattern is not allowed to @code{FAIL}. 5700 5701@cindex @code{popcount@var{m}2} instruction pattern 5702@item @samp{popcount@var{m}2} 5703Store into operand 0 the number of 1-bits in operand 1. 5704 5705@var{m} is either a scalar or vector integer mode. When it is a scalar, 5706operand 1 has mode @var{m} but operand 0 can have whatever scalar 5707integer mode is suitable for the target. The compiler will insert 5708conversion instructions as necessary (typically to convert the result 5709to the same width as @code{int}). When @var{m} is a vector, both 5710operands must have mode @var{m}. 5711 5712This pattern is not allowed to @code{FAIL}. 5713 5714@cindex @code{parity@var{m}2} instruction pattern 5715@item @samp{parity@var{m}2} 5716Store into operand 0 the parity of operand 1, i.e.@: the number of 1-bits 5717in operand 1 modulo 2. 5718 5719@var{m} is either a scalar or vector integer mode. When it is a scalar, 5720operand 1 has mode @var{m} but operand 0 can have whatever scalar 5721integer mode is suitable for the target. The compiler will insert 5722conversion instructions as necessary (typically to convert the result 5723to the same width as @code{int}). When @var{m} is a vector, both 5724operands must have mode @var{m}. 5725 5726This pattern is not allowed to @code{FAIL}. 5727 5728@cindex @code{one_cmpl@var{m}2} instruction pattern 5729@item @samp{one_cmpl@var{m}2} 5730Store the bitwise-complement of operand 1 into operand 0. 5731 5732@cindex @code{movmem@var{m}} instruction pattern 5733@item @samp{movmem@var{m}} 5734Block move instruction. The destination and source blocks of memory 5735are the first two operands, and both are @code{mem:BLK}s with an 5736address in mode @code{Pmode}. 5737 5738The number of bytes to move is the third operand, in mode @var{m}. 5739Usually, you specify @code{Pmode} for @var{m}. However, if you can 5740generate better code knowing the range of valid lengths is smaller than 5741those representable in a full Pmode pointer, you should provide 5742a pattern with a 5743mode corresponding to the range of values you can handle efficiently 5744(e.g., @code{QImode} for values in the range 0--127; note we avoid numbers 5745that appear negative) and also a pattern with @code{Pmode}. 5746 5747The fourth operand is the known shared alignment of the source and 5748destination, in the form of a @code{const_int} rtx. Thus, if the 5749compiler knows that both source and destination are word-aligned, 5750it may provide the value 4 for this operand. 5751 5752Optional operands 5 and 6 specify expected alignment and size of block 5753respectively. The expected alignment differs from alignment in operand 4 5754in a way that the blocks are not required to be aligned according to it in 5755all cases. This expected alignment is also in bytes, just like operand 4. 5756Expected size, when unknown, is set to @code{(const_int -1)}. 5757 5758Descriptions of multiple @code{movmem@var{m}} patterns can only be 5759beneficial if the patterns for smaller modes have fewer restrictions 5760on their first, second and fourth operands. Note that the mode @var{m} 5761in @code{movmem@var{m}} does not impose any restriction on the mode of 5762individually moved data units in the block. 5763 5764These patterns need not give special consideration to the possibility 5765that the source and destination strings might overlap. 5766 5767@cindex @code{movstr} instruction pattern 5768@item @samp{movstr} 5769String copy instruction, with @code{stpcpy} semantics. Operand 0 is 5770an output operand in mode @code{Pmode}. The addresses of the 5771destination and source strings are operands 1 and 2, and both are 5772@code{mem:BLK}s with addresses in mode @code{Pmode}. The execution of 5773the expansion of this pattern should store in operand 0 the address in 5774which the @code{NUL} terminator was stored in the destination string. 5775 5776This patern has also several optional operands that are same as in 5777@code{setmem}. 5778 5779@cindex @code{setmem@var{m}} instruction pattern 5780@item @samp{setmem@var{m}} 5781Block set instruction. The destination string is the first operand, 5782given as a @code{mem:BLK} whose address is in mode @code{Pmode}. The 5783number of bytes to set is the second operand, in mode @var{m}. The value to 5784initialize the memory with is the third operand. Targets that only support the 5785clearing of memory should reject any value that is not the constant 0. See 5786@samp{movmem@var{m}} for a discussion of the choice of mode. 5787 5788The fourth operand is the known alignment of the destination, in the form 5789of a @code{const_int} rtx. Thus, if the compiler knows that the 5790destination is word-aligned, it may provide the value 4 for this 5791operand. 5792 5793Optional operands 5 and 6 specify expected alignment and size of block 5794respectively. The expected alignment differs from alignment in operand 4 5795in a way that the blocks are not required to be aligned according to it in 5796all cases. This expected alignment is also in bytes, just like operand 4. 5797Expected size, when unknown, is set to @code{(const_int -1)}. 5798Operand 7 is the minimal size of the block and operand 8 is the 5799maximal size of the block (NULL if it can not be represented as CONST_INT). 5800Operand 9 is the probable maximal size (i.e. we can not rely on it for correctness, 5801but it can be used for choosing proper code sequence for a given size). 5802 5803The use for multiple @code{setmem@var{m}} is as for @code{movmem@var{m}}. 5804 5805@cindex @code{cmpstrn@var{m}} instruction pattern 5806@item @samp{cmpstrn@var{m}} 5807String compare instruction, with five operands. Operand 0 is the output; 5808it has mode @var{m}. The remaining four operands are like the operands 5809of @samp{movmem@var{m}}. The two memory blocks specified are compared 5810byte by byte in lexicographic order starting at the beginning of each 5811string. The instruction is not allowed to prefetch more than one byte 5812at a time since either string may end in the first byte and reading past 5813that may access an invalid page or segment and cause a fault. The 5814comparison terminates early if the fetched bytes are different or if 5815they are equal to zero. The effect of the instruction is to store a 5816value in operand 0 whose sign indicates the result of the comparison. 5817 5818@cindex @code{cmpstr@var{m}} instruction pattern 5819@item @samp{cmpstr@var{m}} 5820String compare instruction, without known maximum length. Operand 0 is the 5821output; it has mode @var{m}. The second and third operand are the blocks of 5822memory to be compared; both are @code{mem:BLK} with an address in mode 5823@code{Pmode}. 5824 5825The fourth operand is the known shared alignment of the source and 5826destination, in the form of a @code{const_int} rtx. Thus, if the 5827compiler knows that both source and destination are word-aligned, 5828it may provide the value 4 for this operand. 5829 5830The two memory blocks specified are compared byte by byte in lexicographic 5831order starting at the beginning of each string. The instruction is not allowed 5832to prefetch more than one byte at a time since either string may end in the 5833first byte and reading past that may access an invalid page or segment and 5834cause a fault. The comparison will terminate when the fetched bytes 5835are different or if they are equal to zero. The effect of the 5836instruction is to store a value in operand 0 whose sign indicates the 5837result of the comparison. 5838 5839@cindex @code{cmpmem@var{m}} instruction pattern 5840@item @samp{cmpmem@var{m}} 5841Block compare instruction, with five operands like the operands 5842of @samp{cmpstr@var{m}}. The two memory blocks specified are compared 5843byte by byte in lexicographic order starting at the beginning of each 5844block. Unlike @samp{cmpstr@var{m}} the instruction can prefetch 5845any bytes in the two memory blocks. Also unlike @samp{cmpstr@var{m}} 5846the comparison will not stop if both bytes are zero. The effect of 5847the instruction is to store a value in operand 0 whose sign indicates 5848the result of the comparison. 5849 5850@cindex @code{strlen@var{m}} instruction pattern 5851@item @samp{strlen@var{m}} 5852Compute the length of a string, with three operands. 5853Operand 0 is the result (of mode @var{m}), operand 1 is 5854a @code{mem} referring to the first character of the string, 5855operand 2 is the character to search for (normally zero), 5856and operand 3 is a constant describing the known alignment 5857of the beginning of the string. 5858 5859@cindex @code{float@var{m}@var{n}2} instruction pattern 5860@item @samp{float@var{m}@var{n}2} 5861Convert signed integer operand 1 (valid for fixed point mode @var{m}) to 5862floating point mode @var{n} and store in operand 0 (which has mode 5863@var{n}). 5864 5865@cindex @code{floatuns@var{m}@var{n}2} instruction pattern 5866@item @samp{floatuns@var{m}@var{n}2} 5867Convert unsigned integer operand 1 (valid for fixed point mode @var{m}) 5868to floating point mode @var{n} and store in operand 0 (which has mode 5869@var{n}). 5870 5871@cindex @code{fix@var{m}@var{n}2} instruction pattern 5872@item @samp{fix@var{m}@var{n}2} 5873Convert operand 1 (valid for floating point mode @var{m}) to fixed 5874point mode @var{n} as a signed number and store in operand 0 (which 5875has mode @var{n}). This instruction's result is defined only when 5876the value of operand 1 is an integer. 5877 5878If the machine description defines this pattern, it also needs to 5879define the @code{ftrunc} pattern. 5880 5881@cindex @code{fixuns@var{m}@var{n}2} instruction pattern 5882@item @samp{fixuns@var{m}@var{n}2} 5883Convert operand 1 (valid for floating point mode @var{m}) to fixed 5884point mode @var{n} as an unsigned number and store in operand 0 (which 5885has mode @var{n}). This instruction's result is defined only when the 5886value of operand 1 is an integer. 5887 5888@cindex @code{ftrunc@var{m}2} instruction pattern 5889@item @samp{ftrunc@var{m}2} 5890Convert operand 1 (valid for floating point mode @var{m}) to an 5891integer value, still represented in floating point mode @var{m}, and 5892store it in operand 0 (valid for floating point mode @var{m}). 5893 5894@cindex @code{fix_trunc@var{m}@var{n}2} instruction pattern 5895@item @samp{fix_trunc@var{m}@var{n}2} 5896Like @samp{fix@var{m}@var{n}2} but works for any floating point value 5897of mode @var{m} by converting the value to an integer. 5898 5899@cindex @code{fixuns_trunc@var{m}@var{n}2} instruction pattern 5900@item @samp{fixuns_trunc@var{m}@var{n}2} 5901Like @samp{fixuns@var{m}@var{n}2} but works for any floating point 5902value of mode @var{m} by converting the value to an integer. 5903 5904@cindex @code{trunc@var{m}@var{n}2} instruction pattern 5905@item @samp{trunc@var{m}@var{n}2} 5906Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and 5907store in operand 0 (which has mode @var{n}). Both modes must be fixed 5908point or both floating point. 5909 5910@cindex @code{extend@var{m}@var{n}2} instruction pattern 5911@item @samp{extend@var{m}@var{n}2} 5912Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and 5913store in operand 0 (which has mode @var{n}). Both modes must be fixed 5914point or both floating point. 5915 5916@cindex @code{zero_extend@var{m}@var{n}2} instruction pattern 5917@item @samp{zero_extend@var{m}@var{n}2} 5918Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and 5919store in operand 0 (which has mode @var{n}). Both modes must be fixed 5920point. 5921 5922@cindex @code{fract@var{m}@var{n}2} instruction pattern 5923@item @samp{fract@var{m}@var{n}2} 5924Convert operand 1 of mode @var{m} to mode @var{n} and store in 5925operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} 5926could be fixed-point to fixed-point, signed integer to fixed-point, 5927fixed-point to signed integer, floating-point to fixed-point, 5928or fixed-point to floating-point. 5929When overflows or underflows happen, the results are undefined. 5930 5931@cindex @code{satfract@var{m}@var{n}2} instruction pattern 5932@item @samp{satfract@var{m}@var{n}2} 5933Convert operand 1 of mode @var{m} to mode @var{n} and store in 5934operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} 5935could be fixed-point to fixed-point, signed integer to fixed-point, 5936or floating-point to fixed-point. 5937When overflows or underflows happen, the instruction saturates the 5938results to the maximum or the minimum. 5939 5940@cindex @code{fractuns@var{m}@var{n}2} instruction pattern 5941@item @samp{fractuns@var{m}@var{n}2} 5942Convert operand 1 of mode @var{m} to mode @var{n} and store in 5943operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} 5944could be unsigned integer to fixed-point, or 5945fixed-point to unsigned integer. 5946When overflows or underflows happen, the results are undefined. 5947 5948@cindex @code{satfractuns@var{m}@var{n}2} instruction pattern 5949@item @samp{satfractuns@var{m}@var{n}2} 5950Convert unsigned integer operand 1 of mode @var{m} to fixed-point mode 5951@var{n} and store in operand 0 (which has mode @var{n}). 5952When overflows or underflows happen, the instruction saturates the 5953results to the maximum or the minimum. 5954 5955@cindex @code{extv@var{m}} instruction pattern 5956@item @samp{extv@var{m}} 5957Extract a bit-field from register operand 1, sign-extend it, and store 5958it in operand 0. Operand 2 specifies the width of the field in bits 5959and operand 3 the starting bit, which counts from the most significant 5960bit if @samp{BITS_BIG_ENDIAN} is true and from the least significant bit 5961otherwise. 5962 5963Operands 0 and 1 both have mode @var{m}. Operands 2 and 3 have a 5964target-specific mode. 5965 5966@cindex @code{extvmisalign@var{m}} instruction pattern 5967@item @samp{extvmisalign@var{m}} 5968Extract a bit-field from memory operand 1, sign extend it, and store 5969it in operand 0. Operand 2 specifies the width in bits and operand 3 5970the starting bit. The starting bit is always somewhere in the first byte of 5971operand 1; it counts from the most significant bit if @samp{BITS_BIG_ENDIAN} 5972is true and from the least significant bit otherwise. 5973 5974Operand 0 has mode @var{m} while operand 1 has @code{BLK} mode. 5975Operands 2 and 3 have a target-specific mode. 5976 5977The instruction must not read beyond the last byte of the bit-field. 5978 5979@cindex @code{extzv@var{m}} instruction pattern 5980@item @samp{extzv@var{m}} 5981Like @samp{extv@var{m}} except that the bit-field value is zero-extended. 5982 5983@cindex @code{extzvmisalign@var{m}} instruction pattern 5984@item @samp{extzvmisalign@var{m}} 5985Like @samp{extvmisalign@var{m}} except that the bit-field value is 5986zero-extended. 5987 5988@cindex @code{insv@var{m}} instruction pattern 5989@item @samp{insv@var{m}} 5990Insert operand 3 into a bit-field of register operand 0. Operand 1 5991specifies the width of the field in bits and operand 2 the starting bit, 5992which counts from the most significant bit if @samp{BITS_BIG_ENDIAN} 5993is true and from the least significant bit otherwise. 5994 5995Operands 0 and 3 both have mode @var{m}. Operands 1 and 2 have a 5996target-specific mode. 5997 5998@cindex @code{insvmisalign@var{m}} instruction pattern 5999@item @samp{insvmisalign@var{m}} 6000Insert operand 3 into a bit-field of memory operand 0. Operand 1 6001specifies the width of the field in bits and operand 2 the starting bit. 6002The starting bit is always somewhere in the first byte of operand 0; 6003it counts from the most significant bit if @samp{BITS_BIG_ENDIAN} 6004is true and from the least significant bit otherwise. 6005 6006Operand 3 has mode @var{m} while operand 0 has @code{BLK} mode. 6007Operands 1 and 2 have a target-specific mode. 6008 6009The instruction must not read or write beyond the last byte of the bit-field. 6010 6011@cindex @code{extv} instruction pattern 6012@item @samp{extv} 6013Extract a bit-field from operand 1 (a register or memory operand), where 6014operand 2 specifies the width in bits and operand 3 the starting bit, 6015and store it in operand 0. Operand 0 must have mode @code{word_mode}. 6016Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often 6017@code{word_mode} is allowed only for registers. Operands 2 and 3 must 6018be valid for @code{word_mode}. 6019 6020The RTL generation pass generates this instruction only with constants 6021for operands 2 and 3 and the constant is never zero for operand 2. 6022 6023The bit-field value is sign-extended to a full word integer 6024before it is stored in operand 0. 6025 6026This pattern is deprecated; please use @samp{extv@var{m}} and 6027@code{extvmisalign@var{m}} instead. 6028 6029@cindex @code{extzv} instruction pattern 6030@item @samp{extzv} 6031Like @samp{extv} except that the bit-field value is zero-extended. 6032 6033This pattern is deprecated; please use @samp{extzv@var{m}} and 6034@code{extzvmisalign@var{m}} instead. 6035 6036@cindex @code{insv} instruction pattern 6037@item @samp{insv} 6038Store operand 3 (which must be valid for @code{word_mode}) into a 6039bit-field in operand 0, where operand 1 specifies the width in bits and 6040operand 2 the starting bit. Operand 0 may have mode @code{byte_mode} or 6041@code{word_mode}; often @code{word_mode} is allowed only for registers. 6042Operands 1 and 2 must be valid for @code{word_mode}. 6043 6044The RTL generation pass generates this instruction only with constants 6045for operands 1 and 2 and the constant is never zero for operand 1. 6046 6047This pattern is deprecated; please use @samp{insv@var{m}} and 6048@code{insvmisalign@var{m}} instead. 6049 6050@cindex @code{mov@var{mode}cc} instruction pattern 6051@item @samp{mov@var{mode}cc} 6052Conditionally move operand 2 or operand 3 into operand 0 according to the 6053comparison in operand 1. If the comparison is true, operand 2 is moved 6054into operand 0, otherwise operand 3 is moved. 6055 6056The mode of the operands being compared need not be the same as the operands 6057being moved. Some machines, sparc64 for example, have instructions that 6058conditionally move an integer value based on the floating point condition 6059codes and vice versa. 6060 6061If the machine does not have conditional move instructions, do not 6062define these patterns. 6063 6064@cindex @code{add@var{mode}cc} instruction pattern 6065@item @samp{add@var{mode}cc} 6066Similar to @samp{mov@var{mode}cc} but for conditional addition. Conditionally 6067move operand 2 or (operands 2 + operand 3) into operand 0 according to the 6068comparison in operand 1. If the comparison is false, operand 2 is moved into 6069operand 0, otherwise (operand 2 + operand 3) is moved. 6070 6071@cindex @code{neg@var{mode}cc} instruction pattern 6072@item @samp{neg@var{mode}cc} 6073Similar to @samp{mov@var{mode}cc} but for conditional negation. Conditionally 6074move the negation of operand 2 or the unchanged operand 3 into operand 0 6075according to the comparison in operand 1. If the comparison is true, the negation 6076of operand 2 is moved into operand 0, otherwise operand 3 is moved. 6077 6078@cindex @code{not@var{mode}cc} instruction pattern 6079@item @samp{not@var{mode}cc} 6080Similar to @samp{neg@var{mode}cc} but for conditional complement. 6081Conditionally move the bitwise complement of operand 2 or the unchanged 6082operand 3 into operand 0 according to the comparison in operand 1. 6083If the comparison is true, the complement of operand 2 is moved into 6084operand 0, otherwise operand 3 is moved. 6085 6086@cindex @code{cstore@var{mode}4} instruction pattern 6087@item @samp{cstore@var{mode}4} 6088Store zero or nonzero in operand 0 according to whether a comparison 6089is true. Operand 1 is a comparison operator. Operand 2 and operand 3 6090are the first and second operand of the comparison, respectively. 6091You specify the mode that operand 0 must have when you write the 6092@code{match_operand} expression. The compiler automatically sees which 6093mode you have used and supplies an operand of that mode. 6094 6095The value stored for a true condition must have 1 as its low bit, or 6096else must be negative. Otherwise the instruction is not suitable and 6097you should omit it from the machine description. You describe to the 6098compiler exactly which value is stored by defining the macro 6099@code{STORE_FLAG_VALUE} (@pxref{Misc}). If a description cannot be 6100found that can be used for all the possible comparison operators, you 6101should pick one and use a @code{define_expand} to map all results 6102onto the one you chose. 6103 6104These operations may @code{FAIL}, but should do so only in relatively 6105uncommon cases; if they would @code{FAIL} for common cases involving 6106integer comparisons, it is best to restrict the predicates to not 6107allow these operands. Likewise if a given comparison operator will 6108always fail, independent of the operands (for floating-point modes, the 6109@code{ordered_comparison_operator} predicate is often useful in this case). 6110 6111If this pattern is omitted, the compiler will generate a conditional 6112branch---for example, it may copy a constant one to the target and branching 6113around an assignment of zero to the target---or a libcall. If the predicate 6114for operand 1 only rejects some operators, it will also try reordering the 6115operands and/or inverting the result value (e.g.@: by an exclusive OR). 6116These possibilities could be cheaper or equivalent to the instructions 6117used for the @samp{cstore@var{mode}4} pattern followed by those required 6118to convert a positive result from @code{STORE_FLAG_VALUE} to 1; in this 6119case, you can and should make operand 1's predicate reject some operators 6120in the @samp{cstore@var{mode}4} pattern, or remove the pattern altogether 6121from the machine description. 6122 6123@cindex @code{cbranch@var{mode}4} instruction pattern 6124@item @samp{cbranch@var{mode}4} 6125Conditional branch instruction combined with a compare instruction. 6126Operand 0 is a comparison operator. Operand 1 and operand 2 are the 6127first and second operands of the comparison, respectively. Operand 3 6128is the @code{code_label} to jump to. 6129 6130@cindex @code{jump} instruction pattern 6131@item @samp{jump} 6132A jump inside a function; an unconditional branch. Operand 0 is the 6133@code{code_label} to jump to. This pattern name is mandatory on all 6134machines. 6135 6136@cindex @code{call} instruction pattern 6137@item @samp{call} 6138Subroutine call instruction returning no value. Operand 0 is the 6139function to call; operand 1 is the number of bytes of arguments pushed 6140as a @code{const_int}; operand 2 is the number of registers used as 6141operands. 6142 6143On most machines, operand 2 is not actually stored into the RTL 6144pattern. It is supplied for the sake of some RISC machines which need 6145to put this information into the assembler code; they can put it in 6146the RTL instead of operand 1. 6147 6148Operand 0 should be a @code{mem} RTX whose address is the address of the 6149function. Note, however, that this address can be a @code{symbol_ref} 6150expression even if it would not be a legitimate memory address on the 6151target machine. If it is also not a valid argument for a call 6152instruction, the pattern for this operation should be a 6153@code{define_expand} (@pxref{Expander Definitions}) that places the 6154address into a register and uses that register in the call instruction. 6155 6156@cindex @code{call_value} instruction pattern 6157@item @samp{call_value} 6158Subroutine call instruction returning a value. Operand 0 is the hard 6159register in which the value is returned. There are three more 6160operands, the same as the three operands of the @samp{call} 6161instruction (but with numbers increased by one). 6162 6163Subroutines that return @code{BLKmode} objects use the @samp{call} 6164insn. 6165 6166@cindex @code{call_pop} instruction pattern 6167@cindex @code{call_value_pop} instruction pattern 6168@item @samp{call_pop}, @samp{call_value_pop} 6169Similar to @samp{call} and @samp{call_value}, except used if defined and 6170if @code{RETURN_POPS_ARGS} is nonzero. They should emit a @code{parallel} 6171that contains both the function call and a @code{set} to indicate the 6172adjustment made to the frame pointer. 6173 6174For machines where @code{RETURN_POPS_ARGS} can be nonzero, the use of these 6175patterns increases the number of functions for which the frame pointer 6176can be eliminated, if desired. 6177 6178@cindex @code{untyped_call} instruction pattern 6179@item @samp{untyped_call} 6180Subroutine call instruction returning a value of any type. Operand 0 is 6181the function to call; operand 1 is a memory location where the result of 6182calling the function is to be stored; operand 2 is a @code{parallel} 6183expression where each element is a @code{set} expression that indicates 6184the saving of a function return value into the result block. 6185 6186This instruction pattern should be defined to support 6187@code{__builtin_apply} on machines where special instructions are needed 6188to call a subroutine with arbitrary arguments or to save the value 6189returned. This instruction pattern is required on machines that have 6190multiple registers that can hold a return value 6191(i.e.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register). 6192 6193@cindex @code{return} instruction pattern 6194@item @samp{return} 6195Subroutine return instruction. This instruction pattern name should be 6196defined only if a single instruction can do all the work of returning 6197from a function. 6198 6199Like the @samp{mov@var{m}} patterns, this pattern is also used after the 6200RTL generation phase. In this case it is to support machines where 6201multiple instructions are usually needed to return from a function, but 6202some class of functions only requires one instruction to implement a 6203return. Normally, the applicable functions are those which do not need 6204to save any registers or allocate stack space. 6205 6206It is valid for this pattern to expand to an instruction using 6207@code{simple_return} if no epilogue is required. 6208 6209@cindex @code{simple_return} instruction pattern 6210@item @samp{simple_return} 6211Subroutine return instruction. This instruction pattern name should be 6212defined only if a single instruction can do all the work of returning 6213from a function on a path where no epilogue is required. This pattern 6214is very similar to the @code{return} instruction pattern, but it is emitted 6215only by the shrink-wrapping optimization on paths where the function 6216prologue has not been executed, and a function return should occur without 6217any of the effects of the epilogue. Additional uses may be introduced on 6218paths where both the prologue and the epilogue have executed. 6219 6220@findex reload_completed 6221@findex leaf_function_p 6222For such machines, the condition specified in this pattern should only 6223be true when @code{reload_completed} is nonzero and the function's 6224epilogue would only be a single instruction. For machines with register 6225windows, the routine @code{leaf_function_p} may be used to determine if 6226a register window push is required. 6227 6228Machines that have conditional return instructions should define patterns 6229such as 6230 6231@smallexample 6232(define_insn "" 6233 [(set (pc) 6234 (if_then_else (match_operator 6235 0 "comparison_operator" 6236 [(cc0) (const_int 0)]) 6237 (return) 6238 (pc)))] 6239 "@var{condition}" 6240 "@dots{}") 6241@end smallexample 6242 6243where @var{condition} would normally be the same condition specified on the 6244named @samp{return} pattern. 6245 6246@cindex @code{untyped_return} instruction pattern 6247@item @samp{untyped_return} 6248Untyped subroutine return instruction. This instruction pattern should 6249be defined to support @code{__builtin_return} on machines where special 6250instructions are needed to return a value of any type. 6251 6252Operand 0 is a memory location where the result of calling a function 6253with @code{__builtin_apply} is stored; operand 1 is a @code{parallel} 6254expression where each element is a @code{set} expression that indicates 6255the restoring of a function return value from the result block. 6256 6257@cindex @code{nop} instruction pattern 6258@item @samp{nop} 6259No-op instruction. This instruction pattern name should always be defined 6260to output a no-op in assembler code. @code{(const_int 0)} will do as an 6261RTL pattern. 6262 6263@cindex @code{indirect_jump} instruction pattern 6264@item @samp{indirect_jump} 6265An instruction to jump to an address which is operand zero. 6266This pattern name is mandatory on all machines. 6267 6268@cindex @code{casesi} instruction pattern 6269@item @samp{casesi} 6270Instruction to jump through a dispatch table, including bounds checking. 6271This instruction takes five operands: 6272 6273@enumerate 6274@item 6275The index to dispatch on, which has mode @code{SImode}. 6276 6277@item 6278The lower bound for indices in the table, an integer constant. 6279 6280@item 6281The total range of indices in the table---the largest index 6282minus the smallest one (both inclusive). 6283 6284@item 6285A label that precedes the table itself. 6286 6287@item 6288A label to jump to if the index has a value outside the bounds. 6289@end enumerate 6290 6291The table is an @code{addr_vec} or @code{addr_diff_vec} inside of a 6292@code{jump_table_data}. The number of elements in the table is one plus the 6293difference between the upper bound and the lower bound. 6294 6295@cindex @code{tablejump} instruction pattern 6296@item @samp{tablejump} 6297Instruction to jump to a variable address. This is a low-level 6298capability which can be used to implement a dispatch table when there 6299is no @samp{casesi} pattern. 6300 6301This pattern requires two operands: the address or offset, and a label 6302which should immediately precede the jump table. If the macro 6303@code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first 6304operand is an offset which counts from the address of the table; otherwise, 6305it is an absolute address to jump to. In either case, the first operand has 6306mode @code{Pmode}. 6307 6308The @samp{tablejump} insn is always the last insn before the jump 6309table it uses. Its assembler code normally has no need to use the 6310second operand, but you should incorporate it in the RTL pattern so 6311that the jump optimizer will not delete the table as unreachable code. 6312 6313 6314@cindex @code{decrement_and_branch_until_zero} instruction pattern 6315@item @samp{decrement_and_branch_until_zero} 6316Conditional branch instruction that decrements a register and 6317jumps if the register is nonzero. Operand 0 is the register to 6318decrement and test; operand 1 is the label to jump to if the 6319register is nonzero. @xref{Looping Patterns}. 6320 6321This optional instruction pattern is only used by the combiner, 6322typically for loops reversed by the loop optimizer when strength 6323reduction is enabled. 6324 6325@cindex @code{doloop_end} instruction pattern 6326@item @samp{doloop_end} 6327Conditional branch instruction that decrements a register and 6328jumps if the register is nonzero. Operand 0 is the register to 6329decrement and test; operand 1 is the label to jump to if the 6330register is nonzero. 6331@xref{Looping Patterns}. 6332 6333This optional instruction pattern should be defined for machines with 6334low-overhead looping instructions as the loop optimizer will try to 6335modify suitable loops to utilize it. The target hook 6336@code{TARGET_CAN_USE_DOLOOP_P} controls the conditions under which 6337low-overhead loops can be used. 6338 6339@cindex @code{doloop_begin} instruction pattern 6340@item @samp{doloop_begin} 6341Companion instruction to @code{doloop_end} required for machines that 6342need to perform some initialization, such as loading a special counter 6343register. Operand 1 is the associated @code{doloop_end} pattern and 6344operand 0 is the register that it decrements. 6345 6346If initialization insns do not always need to be emitted, use a 6347@code{define_expand} (@pxref{Expander Definitions}) and make it fail. 6348 6349@cindex @code{canonicalize_funcptr_for_compare} instruction pattern 6350@item @samp{canonicalize_funcptr_for_compare} 6351Canonicalize the function pointer in operand 1 and store the result 6352into operand 0. 6353 6354Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1 6355may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc 6356and also has mode @code{Pmode}. 6357 6358Canonicalization of a function pointer usually involves computing 6359the address of the function which would be called if the function 6360pointer were used in an indirect call. 6361 6362Only define this pattern if function pointers on the target machine 6363can have different values but still call the same function when 6364used in an indirect call. 6365 6366@cindex @code{save_stack_block} instruction pattern 6367@cindex @code{save_stack_function} instruction pattern 6368@cindex @code{save_stack_nonlocal} instruction pattern 6369@cindex @code{restore_stack_block} instruction pattern 6370@cindex @code{restore_stack_function} instruction pattern 6371@cindex @code{restore_stack_nonlocal} instruction pattern 6372@item @samp{save_stack_block} 6373@itemx @samp{save_stack_function} 6374@itemx @samp{save_stack_nonlocal} 6375@itemx @samp{restore_stack_block} 6376@itemx @samp{restore_stack_function} 6377@itemx @samp{restore_stack_nonlocal} 6378Most machines save and restore the stack pointer by copying it to or 6379from an object of mode @code{Pmode}. Do not define these patterns on 6380such machines. 6381 6382Some machines require special handling for stack pointer saves and 6383restores. On those machines, define the patterns corresponding to the 6384non-standard cases by using a @code{define_expand} (@pxref{Expander 6385Definitions}) that produces the required insns. The three types of 6386saves and restores are: 6387 6388@enumerate 6389@item 6390@samp{save_stack_block} saves the stack pointer at the start of a block 6391that allocates a variable-sized object, and @samp{restore_stack_block} 6392restores the stack pointer when the block is exited. 6393 6394@item 6395@samp{save_stack_function} and @samp{restore_stack_function} do a 6396similar job for the outermost block of a function and are used when the 6397function allocates variable-sized objects or calls @code{alloca}. Only 6398the epilogue uses the restored stack pointer, allowing a simpler save or 6399restore sequence on some machines. 6400 6401@item 6402@samp{save_stack_nonlocal} is used in functions that contain labels 6403branched to by nested functions. It saves the stack pointer in such a 6404way that the inner function can use @samp{restore_stack_nonlocal} to 6405restore the stack pointer. The compiler generates code to restore the 6406frame and argument pointer registers, but some machines require saving 6407and restoring additional data such as register window information or 6408stack backchains. Place insns in these patterns to save and restore any 6409such required data. 6410@end enumerate 6411 6412When saving the stack pointer, operand 0 is the save area and operand 1 6413is the stack pointer. The mode used to allocate the save area defaults 6414to @code{Pmode} but you can override that choice by defining the 6415@code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}). You must 6416specify an integral mode, or @code{VOIDmode} if no save area is needed 6417for a particular type of save (either because no save is needed or 6418because a machine-specific save area can be used). Operand 0 is the 6419stack pointer and operand 1 is the save area for restore operations. If 6420@samp{save_stack_block} is defined, operand 0 must not be 6421@code{VOIDmode} since these saves can be arbitrarily nested. 6422 6423A save area is a @code{mem} that is at a constant offset from 6424@code{virtual_stack_vars_rtx} when the stack pointer is saved for use by 6425nonlocal gotos and a @code{reg} in the other two cases. 6426 6427@cindex @code{allocate_stack} instruction pattern 6428@item @samp{allocate_stack} 6429Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from 6430the stack pointer to create space for dynamically allocated data. 6431 6432Store the resultant pointer to this space into operand 0. If you 6433are allocating space from the main stack, do this by emitting a 6434move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0. 6435If you are allocating the space elsewhere, generate code to copy the 6436location of the space to operand 0. In the latter case, you must 6437ensure this space gets freed when the corresponding space on the main 6438stack is free. 6439 6440Do not define this pattern if all that must be done is the subtraction. 6441Some machines require other operations such as stack probes or 6442maintaining the back chain. Define this pattern to emit those 6443operations in addition to updating the stack pointer. 6444 6445@cindex @code{check_stack} instruction pattern 6446@item @samp{check_stack} 6447If stack checking (@pxref{Stack Checking}) cannot be done on your system by 6448probing the stack, define this pattern to perform the needed check and signal 6449an error if the stack has overflowed. The single operand is the address in 6450the stack farthest from the current stack pointer that you need to validate. 6451Normally, on platforms where this pattern is needed, you would obtain the 6452stack limit from a global or thread-specific variable or register. 6453 6454@cindex @code{probe_stack_address} instruction pattern 6455@item @samp{probe_stack_address} 6456If stack checking (@pxref{Stack Checking}) can be done on your system by 6457probing the stack but without the need to actually access it, define this 6458pattern and signal an error if the stack has overflowed. The single operand 6459is the memory address in the stack that needs to be probed. 6460 6461@cindex @code{probe_stack} instruction pattern 6462@item @samp{probe_stack} 6463If stack checking (@pxref{Stack Checking}) can be done on your system by 6464probing the stack but doing it with a ``store zero'' instruction is not valid 6465or optimal, define this pattern to do the probing differently and signal an 6466error if the stack has overflowed. The single operand is the memory reference 6467in the stack that needs to be probed. 6468 6469@cindex @code{nonlocal_goto} instruction pattern 6470@item @samp{nonlocal_goto} 6471Emit code to generate a non-local goto, e.g., a jump from one function 6472to a label in an outer function. This pattern has four arguments, 6473each representing a value to be used in the jump. The first 6474argument is to be loaded into the frame pointer, the second is 6475the address to branch to (code to dispatch to the actual label), 6476the third is the address of a location where the stack is saved, 6477and the last is the address of the label, to be placed in the 6478location for the incoming static chain. 6479 6480On most machines you need not define this pattern, since GCC will 6481already generate the correct code, which is to load the frame pointer 6482and static chain, restore the stack (using the 6483@samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly 6484to the dispatcher. You need only define this pattern if this code will 6485not work on your machine. 6486 6487@cindex @code{nonlocal_goto_receiver} instruction pattern 6488@item @samp{nonlocal_goto_receiver} 6489This pattern, if defined, contains code needed at the target of a 6490nonlocal goto after the code already generated by GCC@. You will not 6491normally need to define this pattern. A typical reason why you might 6492need this pattern is if some value, such as a pointer to a global table, 6493must be restored when the frame pointer is restored. Note that a nonlocal 6494goto only occurs within a unit-of-translation, so a global table pointer 6495that is shared by all functions of a given module need not be restored. 6496There are no arguments. 6497 6498@cindex @code{exception_receiver} instruction pattern 6499@item @samp{exception_receiver} 6500This pattern, if defined, contains code needed at the site of an 6501exception handler that isn't needed at the site of a nonlocal goto. You 6502will not normally need to define this pattern. A typical reason why you 6503might need this pattern is if some value, such as a pointer to a global 6504table, must be restored after control flow is branched to the handler of 6505an exception. There are no arguments. 6506 6507@cindex @code{builtin_setjmp_setup} instruction pattern 6508@item @samp{builtin_setjmp_setup} 6509This pattern, if defined, contains additional code needed to initialize 6510the @code{jmp_buf}. You will not normally need to define this pattern. 6511A typical reason why you might need this pattern is if some value, such 6512as a pointer to a global table, must be restored. Though it is 6513preferred that the pointer value be recalculated if possible (given the 6514address of a label for instance). The single argument is a pointer to 6515the @code{jmp_buf}. Note that the buffer is five words long and that 6516the first three are normally used by the generic mechanism. 6517 6518@cindex @code{builtin_setjmp_receiver} instruction pattern 6519@item @samp{builtin_setjmp_receiver} 6520This pattern, if defined, contains code needed at the site of a 6521built-in setjmp that isn't needed at the site of a nonlocal goto. You 6522will not normally need to define this pattern. A typical reason why you 6523might need this pattern is if some value, such as a pointer to a global 6524table, must be restored. It takes one argument, which is the label 6525to which builtin_longjmp transferred control; this pattern may be emitted 6526at a small offset from that label. 6527 6528@cindex @code{builtin_longjmp} instruction pattern 6529@item @samp{builtin_longjmp} 6530This pattern, if defined, performs the entire action of the longjmp. 6531You will not normally need to define this pattern unless you also define 6532@code{builtin_setjmp_setup}. The single argument is a pointer to the 6533@code{jmp_buf}. 6534 6535@cindex @code{eh_return} instruction pattern 6536@item @samp{eh_return} 6537This pattern, if defined, affects the way @code{__builtin_eh_return}, 6538and thence the call frame exception handling library routines, are 6539built. It is intended to handle non-trivial actions needed along 6540the abnormal return path. 6541 6542The address of the exception handler to which the function should return 6543is passed as operand to this pattern. It will normally need to copied by 6544the pattern to some special register or memory location. 6545If the pattern needs to determine the location of the target call 6546frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX}, 6547if defined; it will have already been assigned. 6548 6549If this pattern is not defined, the default action will be to simply 6550copy the return address to @code{EH_RETURN_HANDLER_RTX}. Either 6551that macro or this pattern needs to be defined if call frame exception 6552handling is to be used. 6553 6554@cindex @code{prologue} instruction pattern 6555@anchor{prologue instruction pattern} 6556@item @samp{prologue} 6557This pattern, if defined, emits RTL for entry to a function. The function 6558entry is responsible for setting up the stack frame, initializing the frame 6559pointer register, saving callee saved registers, etc. 6560 6561Using a prologue pattern is generally preferred over defining 6562@code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue. 6563 6564The @code{prologue} pattern is particularly useful for targets which perform 6565instruction scheduling. 6566 6567@cindex @code{window_save} instruction pattern 6568@anchor{window_save instruction pattern} 6569@item @samp{window_save} 6570This pattern, if defined, emits RTL for a register window save. It should 6571be defined if the target machine has register windows but the window events 6572are decoupled from calls to subroutines. The canonical example is the SPARC 6573architecture. 6574 6575@cindex @code{epilogue} instruction pattern 6576@anchor{epilogue instruction pattern} 6577@item @samp{epilogue} 6578This pattern emits RTL for exit from a function. The function 6579exit is responsible for deallocating the stack frame, restoring callee saved 6580registers and emitting the return instruction. 6581 6582Using an epilogue pattern is generally preferred over defining 6583@code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue. 6584 6585The @code{epilogue} pattern is particularly useful for targets which perform 6586instruction scheduling or which have delay slots for their return instruction. 6587 6588@cindex @code{sibcall_epilogue} instruction pattern 6589@item @samp{sibcall_epilogue} 6590This pattern, if defined, emits RTL for exit from a function without the final 6591branch back to the calling function. This pattern will be emitted before any 6592sibling call (aka tail call) sites. 6593 6594The @code{sibcall_epilogue} pattern must not clobber any arguments used for 6595parameter passing or any stack slots for arguments passed to the current 6596function. 6597 6598@cindex @code{trap} instruction pattern 6599@item @samp{trap} 6600This pattern, if defined, signals an error, typically by causing some 6601kind of signal to be raised. Among other places, it is used by the Java 6602front end to signal `invalid array index' exceptions. 6603 6604@cindex @code{ctrap@var{MM}4} instruction pattern 6605@item @samp{ctrap@var{MM}4} 6606Conditional trap instruction. Operand 0 is a piece of RTL which 6607performs a comparison, and operands 1 and 2 are the arms of the 6608comparison. Operand 3 is the trap code, an integer. 6609 6610A typical @code{ctrap} pattern looks like 6611 6612@smallexample 6613(define_insn "ctrapsi4" 6614 [(trap_if (match_operator 0 "trap_operator" 6615 [(match_operand 1 "register_operand") 6616 (match_operand 2 "immediate_operand")]) 6617 (match_operand 3 "const_int_operand" "i"))] 6618 "" 6619 "@dots{}") 6620@end smallexample 6621 6622@cindex @code{prefetch} instruction pattern 6623@item @samp{prefetch} 6624This pattern, if defined, emits code for a non-faulting data prefetch 6625instruction. Operand 0 is the address of the memory to prefetch. Operand 1 6626is a constant 1 if the prefetch is preparing for a write to the memory 6627address, or a constant 0 otherwise. Operand 2 is the expected degree of 6628temporal locality of the data and is a value between 0 and 3, inclusive; 0 6629means that the data has no temporal locality, so it need not be left in the 6630cache after the access; 3 means that the data has a high degree of temporal 6631locality and should be left in all levels of cache possible; 1 and 2 mean, 6632respectively, a low or moderate degree of temporal locality. 6633 6634Targets that do not support write prefetches or locality hints can ignore 6635the values of operands 1 and 2. 6636 6637@cindex @code{blockage} instruction pattern 6638@item @samp{blockage} 6639This pattern defines a pseudo insn that prevents the instruction 6640scheduler and other passes from moving instructions and using register 6641equivalences across the boundary defined by the blockage insn. 6642This needs to be an UNSPEC_VOLATILE pattern or a volatile ASM. 6643 6644@cindex @code{memory_barrier} instruction pattern 6645@item @samp{memory_barrier} 6646If the target memory model is not fully synchronous, then this pattern 6647should be defined to an instruction that orders both loads and stores 6648before the instruction with respect to loads and stores after the instruction. 6649This pattern has no operands. 6650 6651@cindex @code{sync_compare_and_swap@var{mode}} instruction pattern 6652@item @samp{sync_compare_and_swap@var{mode}} 6653This pattern, if defined, emits code for an atomic compare-and-swap 6654operation. Operand 1 is the memory on which the atomic operation is 6655performed. Operand 2 is the ``old'' value to be compared against the 6656current contents of the memory location. Operand 3 is the ``new'' value 6657to store in the memory if the compare succeeds. Operand 0 is the result 6658of the operation; it should contain the contents of the memory 6659before the operation. If the compare succeeds, this should obviously be 6660a copy of operand 2. 6661 6662This pattern must show that both operand 0 and operand 1 are modified. 6663 6664This pattern must issue any memory barrier instructions such that all 6665memory operations before the atomic operation occur before the atomic 6666operation and all memory operations after the atomic operation occur 6667after the atomic operation. 6668 6669For targets where the success or failure of the compare-and-swap 6670operation is available via the status flags, it is possible to 6671avoid a separate compare operation and issue the subsequent 6672branch or store-flag operation immediately after the compare-and-swap. 6673To this end, GCC will look for a @code{MODE_CC} set in the 6674output of @code{sync_compare_and_swap@var{mode}}; if the machine 6675description includes such a set, the target should also define special 6676@code{cbranchcc4} and/or @code{cstorecc4} instructions. GCC will then 6677be able to take the destination of the @code{MODE_CC} set and pass it 6678to the @code{cbranchcc4} or @code{cstorecc4} pattern as the first 6679operand of the comparison (the second will be @code{(const_int 0)}). 6680 6681For targets where the operating system may provide support for this 6682operation via library calls, the @code{sync_compare_and_swap_optab} 6683may be initialized to a function with the same interface as the 6684@code{__sync_val_compare_and_swap_@var{n}} built-in. If the entire 6685set of @var{__sync} builtins are supported via library calls, the 6686target can initialize all of the optabs at once with 6687@code{init_sync_libfuncs}. 6688For the purposes of C++11 @code{std::atomic::is_lock_free}, it is 6689assumed that these library calls do @emph{not} use any kind of 6690interruptable locking. 6691 6692@cindex @code{sync_add@var{mode}} instruction pattern 6693@cindex @code{sync_sub@var{mode}} instruction pattern 6694@cindex @code{sync_ior@var{mode}} instruction pattern 6695@cindex @code{sync_and@var{mode}} instruction pattern 6696@cindex @code{sync_xor@var{mode}} instruction pattern 6697@cindex @code{sync_nand@var{mode}} instruction pattern 6698@item @samp{sync_add@var{mode}}, @samp{sync_sub@var{mode}} 6699@itemx @samp{sync_ior@var{mode}}, @samp{sync_and@var{mode}} 6700@itemx @samp{sync_xor@var{mode}}, @samp{sync_nand@var{mode}} 6701These patterns emit code for an atomic operation on memory. 6702Operand 0 is the memory on which the atomic operation is performed. 6703Operand 1 is the second operand to the binary operator. 6704 6705This pattern must issue any memory barrier instructions such that all 6706memory operations before the atomic operation occur before the atomic 6707operation and all memory operations after the atomic operation occur 6708after the atomic operation. 6709 6710If these patterns are not defined, the operation will be constructed 6711from a compare-and-swap operation, if defined. 6712 6713@cindex @code{sync_old_add@var{mode}} instruction pattern 6714@cindex @code{sync_old_sub@var{mode}} instruction pattern 6715@cindex @code{sync_old_ior@var{mode}} instruction pattern 6716@cindex @code{sync_old_and@var{mode}} instruction pattern 6717@cindex @code{sync_old_xor@var{mode}} instruction pattern 6718@cindex @code{sync_old_nand@var{mode}} instruction pattern 6719@item @samp{sync_old_add@var{mode}}, @samp{sync_old_sub@var{mode}} 6720@itemx @samp{sync_old_ior@var{mode}}, @samp{sync_old_and@var{mode}} 6721@itemx @samp{sync_old_xor@var{mode}}, @samp{sync_old_nand@var{mode}} 6722These patterns emit code for an atomic operation on memory, 6723and return the value that the memory contained before the operation. 6724Operand 0 is the result value, operand 1 is the memory on which the 6725atomic operation is performed, and operand 2 is the second operand 6726to the binary operator. 6727 6728This pattern must issue any memory barrier instructions such that all 6729memory operations before the atomic operation occur before the atomic 6730operation and all memory operations after the atomic operation occur 6731after the atomic operation. 6732 6733If these patterns are not defined, the operation will be constructed 6734from a compare-and-swap operation, if defined. 6735 6736@cindex @code{sync_new_add@var{mode}} instruction pattern 6737@cindex @code{sync_new_sub@var{mode}} instruction pattern 6738@cindex @code{sync_new_ior@var{mode}} instruction pattern 6739@cindex @code{sync_new_and@var{mode}} instruction pattern 6740@cindex @code{sync_new_xor@var{mode}} instruction pattern 6741@cindex @code{sync_new_nand@var{mode}} instruction pattern 6742@item @samp{sync_new_add@var{mode}}, @samp{sync_new_sub@var{mode}} 6743@itemx @samp{sync_new_ior@var{mode}}, @samp{sync_new_and@var{mode}} 6744@itemx @samp{sync_new_xor@var{mode}}, @samp{sync_new_nand@var{mode}} 6745These patterns are like their @code{sync_old_@var{op}} counterparts, 6746except that they return the value that exists in the memory location 6747after the operation, rather than before the operation. 6748 6749@cindex @code{sync_lock_test_and_set@var{mode}} instruction pattern 6750@item @samp{sync_lock_test_and_set@var{mode}} 6751This pattern takes two forms, based on the capabilities of the target. 6752In either case, operand 0 is the result of the operand, operand 1 is 6753the memory on which the atomic operation is performed, and operand 2 6754is the value to set in the lock. 6755 6756In the ideal case, this operation is an atomic exchange operation, in 6757which the previous value in memory operand is copied into the result 6758operand, and the value operand is stored in the memory operand. 6759 6760For less capable targets, any value operand that is not the constant 1 6761should be rejected with @code{FAIL}. In this case the target may use 6762an atomic test-and-set bit operation. The result operand should contain 67631 if the bit was previously set and 0 if the bit was previously clear. 6764The true contents of the memory operand are implementation defined. 6765 6766This pattern must issue any memory barrier instructions such that the 6767pattern as a whole acts as an acquire barrier, that is all memory 6768operations after the pattern do not occur until the lock is acquired. 6769 6770If this pattern is not defined, the operation will be constructed from 6771a compare-and-swap operation, if defined. 6772 6773@cindex @code{sync_lock_release@var{mode}} instruction pattern 6774@item @samp{sync_lock_release@var{mode}} 6775This pattern, if defined, releases a lock set by 6776@code{sync_lock_test_and_set@var{mode}}. Operand 0 is the memory 6777that contains the lock; operand 1 is the value to store in the lock. 6778 6779If the target doesn't implement full semantics for 6780@code{sync_lock_test_and_set@var{mode}}, any value operand which is not 6781the constant 0 should be rejected with @code{FAIL}, and the true contents 6782of the memory operand are implementation defined. 6783 6784This pattern must issue any memory barrier instructions such that the 6785pattern as a whole acts as a release barrier, that is the lock is 6786released only after all previous memory operations have completed. 6787 6788If this pattern is not defined, then a @code{memory_barrier} pattern 6789will be emitted, followed by a store of the value to the memory operand. 6790 6791@cindex @code{atomic_compare_and_swap@var{mode}} instruction pattern 6792@item @samp{atomic_compare_and_swap@var{mode}} 6793This pattern, if defined, emits code for an atomic compare-and-swap 6794operation with memory model semantics. Operand 2 is the memory on which 6795the atomic operation is performed. Operand 0 is an output operand which 6796is set to true or false based on whether the operation succeeded. Operand 67971 is an output operand which is set to the contents of the memory before 6798the operation was attempted. Operand 3 is the value that is expected to 6799be in memory. Operand 4 is the value to put in memory if the expected 6800value is found there. Operand 5 is set to 1 if this compare and swap is to 6801be treated as a weak operation. Operand 6 is the memory model to be used 6802if the operation is a success. Operand 7 is the memory model to be used 6803if the operation fails. 6804 6805If memory referred to in operand 2 contains the value in operand 3, then 6806operand 4 is stored in memory pointed to by operand 2 and fencing based on 6807the memory model in operand 6 is issued. 6808 6809If memory referred to in operand 2 does not contain the value in operand 3, 6810then fencing based on the memory model in operand 7 is issued. 6811 6812If a target does not support weak compare-and-swap operations, or the port 6813elects not to implement weak operations, the argument in operand 5 can be 6814ignored. Note a strong implementation must be provided. 6815 6816If this pattern is not provided, the @code{__atomic_compare_exchange} 6817built-in functions will utilize the legacy @code{sync_compare_and_swap} 6818pattern with an @code{__ATOMIC_SEQ_CST} memory model. 6819 6820@cindex @code{atomic_load@var{mode}} instruction pattern 6821@item @samp{atomic_load@var{mode}} 6822This pattern implements an atomic load operation with memory model 6823semantics. Operand 1 is the memory address being loaded from. Operand 0 6824is the result of the load. Operand 2 is the memory model to be used for 6825the load operation. 6826 6827If not present, the @code{__atomic_load} built-in function will either 6828resort to a normal load with memory barriers, or a compare-and-swap 6829operation if a normal load would not be atomic. 6830 6831@cindex @code{atomic_store@var{mode}} instruction pattern 6832@item @samp{atomic_store@var{mode}} 6833This pattern implements an atomic store operation with memory model 6834semantics. Operand 0 is the memory address being stored to. Operand 1 6835is the value to be written. Operand 2 is the memory model to be used for 6836the operation. 6837 6838If not present, the @code{__atomic_store} built-in function will attempt to 6839perform a normal store and surround it with any required memory fences. If 6840the store would not be atomic, then an @code{__atomic_exchange} is 6841attempted with the result being ignored. 6842 6843@cindex @code{atomic_exchange@var{mode}} instruction pattern 6844@item @samp{atomic_exchange@var{mode}} 6845This pattern implements an atomic exchange operation with memory model 6846semantics. Operand 1 is the memory location the operation is performed on. 6847Operand 0 is an output operand which is set to the original value contained 6848in the memory pointed to by operand 1. Operand 2 is the value to be 6849stored. Operand 3 is the memory model to be used. 6850 6851If this pattern is not present, the built-in function 6852@code{__atomic_exchange} will attempt to preform the operation with a 6853compare and swap loop. 6854 6855@cindex @code{atomic_add@var{mode}} instruction pattern 6856@cindex @code{atomic_sub@var{mode}} instruction pattern 6857@cindex @code{atomic_or@var{mode}} instruction pattern 6858@cindex @code{atomic_and@var{mode}} instruction pattern 6859@cindex @code{atomic_xor@var{mode}} instruction pattern 6860@cindex @code{atomic_nand@var{mode}} instruction pattern 6861@item @samp{atomic_add@var{mode}}, @samp{atomic_sub@var{mode}} 6862@itemx @samp{atomic_or@var{mode}}, @samp{atomic_and@var{mode}} 6863@itemx @samp{atomic_xor@var{mode}}, @samp{atomic_nand@var{mode}} 6864These patterns emit code for an atomic operation on memory with memory 6865model semantics. Operand 0 is the memory on which the atomic operation is 6866performed. Operand 1 is the second operand to the binary operator. 6867Operand 2 is the memory model to be used by the operation. 6868 6869If these patterns are not defined, attempts will be made to use legacy 6870@code{sync} patterns, or equivalent patterns which return a result. If 6871none of these are available a compare-and-swap loop will be used. 6872 6873@cindex @code{atomic_fetch_add@var{mode}} instruction pattern 6874@cindex @code{atomic_fetch_sub@var{mode}} instruction pattern 6875@cindex @code{atomic_fetch_or@var{mode}} instruction pattern 6876@cindex @code{atomic_fetch_and@var{mode}} instruction pattern 6877@cindex @code{atomic_fetch_xor@var{mode}} instruction pattern 6878@cindex @code{atomic_fetch_nand@var{mode}} instruction pattern 6879@item @samp{atomic_fetch_add@var{mode}}, @samp{atomic_fetch_sub@var{mode}} 6880@itemx @samp{atomic_fetch_or@var{mode}}, @samp{atomic_fetch_and@var{mode}} 6881@itemx @samp{atomic_fetch_xor@var{mode}}, @samp{atomic_fetch_nand@var{mode}} 6882These patterns emit code for an atomic operation on memory with memory 6883model semantics, and return the original value. Operand 0 is an output 6884operand which contains the value of the memory location before the 6885operation was performed. Operand 1 is the memory on which the atomic 6886operation is performed. Operand 2 is the second operand to the binary 6887operator. Operand 3 is the memory model to be used by the operation. 6888 6889If these patterns are not defined, attempts will be made to use legacy 6890@code{sync} patterns. If none of these are available a compare-and-swap 6891loop will be used. 6892 6893@cindex @code{atomic_add_fetch@var{mode}} instruction pattern 6894@cindex @code{atomic_sub_fetch@var{mode}} instruction pattern 6895@cindex @code{atomic_or_fetch@var{mode}} instruction pattern 6896@cindex @code{atomic_and_fetch@var{mode}} instruction pattern 6897@cindex @code{atomic_xor_fetch@var{mode}} instruction pattern 6898@cindex @code{atomic_nand_fetch@var{mode}} instruction pattern 6899@item @samp{atomic_add_fetch@var{mode}}, @samp{atomic_sub_fetch@var{mode}} 6900@itemx @samp{atomic_or_fetch@var{mode}}, @samp{atomic_and_fetch@var{mode}} 6901@itemx @samp{atomic_xor_fetch@var{mode}}, @samp{atomic_nand_fetch@var{mode}} 6902These patterns emit code for an atomic operation on memory with memory 6903model semantics and return the result after the operation is performed. 6904Operand 0 is an output operand which contains the value after the 6905operation. Operand 1 is the memory on which the atomic operation is 6906performed. Operand 2 is the second operand to the binary operator. 6907Operand 3 is the memory model to be used by the operation. 6908 6909If these patterns are not defined, attempts will be made to use legacy 6910@code{sync} patterns, or equivalent patterns which return the result before 6911the operation followed by the arithmetic operation required to produce the 6912result. If none of these are available a compare-and-swap loop will be 6913used. 6914 6915@cindex @code{atomic_test_and_set} instruction pattern 6916@item @samp{atomic_test_and_set} 6917This pattern emits code for @code{__builtin_atomic_test_and_set}. 6918Operand 0 is an output operand which is set to true if the previous 6919previous contents of the byte was "set", and false otherwise. Operand 1 6920is the @code{QImode} memory to be modified. Operand 2 is the memory 6921model to be used. 6922 6923The specific value that defines "set" is implementation defined, and 6924is normally based on what is performed by the native atomic test and set 6925instruction. 6926 6927@cindex @code{mem_thread_fence@var{mode}} instruction pattern 6928@item @samp{mem_thread_fence@var{mode}} 6929This pattern emits code required to implement a thread fence with 6930memory model semantics. Operand 0 is the memory model to be used. 6931 6932If this pattern is not specified, all memory models except 6933@code{__ATOMIC_RELAXED} will result in issuing a @code{sync_synchronize} 6934barrier pattern. 6935 6936@cindex @code{mem_signal_fence@var{mode}} instruction pattern 6937@item @samp{mem_signal_fence@var{mode}} 6938This pattern emits code required to implement a signal fence with 6939memory model semantics. Operand 0 is the memory model to be used. 6940 6941This pattern should impact the compiler optimizers the same way that 6942mem_signal_fence does, but it does not need to issue any barrier 6943instructions. 6944 6945If this pattern is not specified, all memory models except 6946@code{__ATOMIC_RELAXED} will result in issuing a @code{sync_synchronize} 6947barrier pattern. 6948 6949@cindex @code{get_thread_pointer@var{mode}} instruction pattern 6950@cindex @code{set_thread_pointer@var{mode}} instruction pattern 6951@item @samp{get_thread_pointer@var{mode}} 6952@itemx @samp{set_thread_pointer@var{mode}} 6953These patterns emit code that reads/sets the TLS thread pointer. Currently, 6954these are only needed if the target needs to support the 6955@code{__builtin_thread_pointer} and @code{__builtin_set_thread_pointer} 6956builtins. 6957 6958The get/set patterns have a single output/input operand respectively, 6959with @var{mode} intended to be @code{Pmode}. 6960 6961@cindex @code{stack_protect_set} instruction pattern 6962@item @samp{stack_protect_set} 6963This pattern, if defined, moves a @code{ptr_mode} value from the memory 6964in operand 1 to the memory in operand 0 without leaving the value in 6965a register afterward. This is to avoid leaking the value some place 6966that an attacker might use to rewrite the stack guard slot after 6967having clobbered it. 6968 6969If this pattern is not defined, then a plain move pattern is generated. 6970 6971@cindex @code{stack_protect_test} instruction pattern 6972@item @samp{stack_protect_test} 6973This pattern, if defined, compares a @code{ptr_mode} value from the 6974memory in operand 1 with the memory in operand 0 without leaving the 6975value in a register afterward and branches to operand 2 if the values 6976were equal. 6977 6978If this pattern is not defined, then a plain compare pattern and 6979conditional branch pattern is used. 6980 6981@cindex @code{clear_cache} instruction pattern 6982@item @samp{clear_cache} 6983This pattern, if defined, flushes the instruction cache for a region of 6984memory. The region is bounded to by the Pmode pointers in operand 0 6985inclusive and operand 1 exclusive. 6986 6987If this pattern is not defined, a call to the library function 6988@code{__clear_cache} is used. 6989 6990@end table 6991 6992@end ifset 6993@c Each of the following nodes are wrapped in separate 6994@c "@ifset INTERNALS" to work around memory limits for the default 6995@c configuration in older tetex distributions. Known to not work: 6996@c tetex-1.0.7, known to work: tetex-2.0.2. 6997@ifset INTERNALS 6998@node Pattern Ordering 6999@section When the Order of Patterns Matters 7000@cindex Pattern Ordering 7001@cindex Ordering of Patterns 7002 7003Sometimes an insn can match more than one instruction pattern. Then the 7004pattern that appears first in the machine description is the one used. 7005Therefore, more specific patterns (patterns that will match fewer things) 7006and faster instructions (those that will produce better code when they 7007do match) should usually go first in the description. 7008 7009In some cases the effect of ordering the patterns can be used to hide 7010a pattern when it is not valid. For example, the 68000 has an 7011instruction for converting a fullword to floating point and another 7012for converting a byte to floating point. An instruction converting 7013an integer to floating point could match either one. We put the 7014pattern to convert the fullword first to make sure that one will 7015be used rather than the other. (Otherwise a large integer might 7016be generated as a single-byte immediate quantity, which would not work.) 7017Instead of using this pattern ordering it would be possible to make the 7018pattern for convert-a-byte smart enough to deal properly with any 7019constant value. 7020 7021@end ifset 7022@ifset INTERNALS 7023@node Dependent Patterns 7024@section Interdependence of Patterns 7025@cindex Dependent Patterns 7026@cindex Interdependence of Patterns 7027 7028In some cases machines support instructions identical except for the 7029machine mode of one or more operands. For example, there may be 7030``sign-extend halfword'' and ``sign-extend byte'' instructions whose 7031patterns are 7032 7033@smallexample 7034(set (match_operand:SI 0 @dots{}) 7035 (extend:SI (match_operand:HI 1 @dots{}))) 7036 7037(set (match_operand:SI 0 @dots{}) 7038 (extend:SI (match_operand:QI 1 @dots{}))) 7039@end smallexample 7040 7041@noindent 7042Constant integers do not specify a machine mode, so an instruction to 7043extend a constant value could match either pattern. The pattern it 7044actually will match is the one that appears first in the file. For correct 7045results, this must be the one for the widest possible mode (@code{HImode}, 7046here). If the pattern matches the @code{QImode} instruction, the results 7047will be incorrect if the constant value does not actually fit that mode. 7048 7049Such instructions to extend constants are rarely generated because they are 7050optimized away, but they do occasionally happen in nonoptimized 7051compilations. 7052 7053If a constraint in a pattern allows a constant, the reload pass may 7054replace a register with a constant permitted by the constraint in some 7055cases. Similarly for memory references. Because of this substitution, 7056you should not provide separate patterns for increment and decrement 7057instructions. Instead, they should be generated from the same pattern 7058that supports register-register add insns by examining the operands and 7059generating the appropriate machine instruction. 7060 7061@end ifset 7062@ifset INTERNALS 7063@node Jump Patterns 7064@section Defining Jump Instruction Patterns 7065@cindex jump instruction patterns 7066@cindex defining jump instruction patterns 7067 7068GCC does not assume anything about how the machine realizes jumps. 7069The machine description should define a single pattern, usually 7070a @code{define_expand}, which expands to all the required insns. 7071 7072Usually, this would be a comparison insn to set the condition code 7073and a separate branch insn testing the condition code and branching 7074or not according to its value. For many machines, however, 7075separating compares and branches is limiting, which is why the 7076more flexible approach with one @code{define_expand} is used in GCC. 7077The machine description becomes clearer for architectures that 7078have compare-and-branch instructions but no condition code. It also 7079works better when different sets of comparison operators are supported 7080by different kinds of conditional branches (e.g. integer vs. floating-point), 7081or by conditional branches with respect to conditional stores. 7082 7083Two separate insns are always used if the machine description represents 7084a condition code register using the legacy RTL expression @code{(cc0)}, 7085and on most machines that use a separate condition code register 7086(@pxref{Condition Code}). For machines that use @code{(cc0)}, in 7087fact, the set and use of the condition code must be separate and 7088adjacent@footnote{@code{note} insns can separate them, though.}, thus 7089allowing flags in @code{cc_status} to be used (@pxref{Condition Code}) and 7090so that the comparison and branch insns could be located from each other 7091by using the functions @code{prev_cc0_setter} and @code{next_cc0_user}. 7092 7093Even in this case having a single entry point for conditional branches 7094is advantageous, because it handles equally well the case where a single 7095comparison instruction records the results of both signed and unsigned 7096comparison of the given operands (with the branch insns coming in distinct 7097signed and unsigned flavors) as in the x86 or SPARC, and the case where 7098there are distinct signed and unsigned compare instructions and only 7099one set of conditional branch instructions as in the PowerPC. 7100 7101@end ifset 7102@ifset INTERNALS 7103@node Looping Patterns 7104@section Defining Looping Instruction Patterns 7105@cindex looping instruction patterns 7106@cindex defining looping instruction patterns 7107 7108Some machines have special jump instructions that can be utilized to 7109make loops more efficient. A common example is the 68000 @samp{dbra} 7110instruction which performs a decrement of a register and a branch if the 7111result was greater than zero. Other machines, in particular digital 7112signal processors (DSPs), have special block repeat instructions to 7113provide low-overhead loop support. For example, the TI TMS320C3x/C4x 7114DSPs have a block repeat instruction that loads special registers to 7115mark the top and end of a loop and to count the number of loop 7116iterations. This avoids the need for fetching and executing a 7117@samp{dbra}-like instruction and avoids pipeline stalls associated with 7118the jump. 7119 7120GCC has three special named patterns to support low overhead looping. 7121They are @samp{decrement_and_branch_until_zero}, @samp{doloop_begin}, 7122and @samp{doloop_end}. The first pattern, 7123@samp{decrement_and_branch_until_zero}, is not emitted during RTL 7124generation but may be emitted during the instruction combination phase. 7125This requires the assistance of the loop optimizer, using information 7126collected during strength reduction, to reverse a loop to count down to 7127zero. Some targets also require the loop optimizer to add a 7128@code{REG_NONNEG} note to indicate that the iteration count is always 7129positive. This is needed if the target performs a signed loop 7130termination test. For example, the 68000 uses a pattern similar to the 7131following for its @code{dbra} instruction: 7132 7133@smallexample 7134@group 7135(define_insn "decrement_and_branch_until_zero" 7136 [(set (pc) 7137 (if_then_else 7138 (ge (plus:SI (match_operand:SI 0 "general_operand" "+d*am") 7139 (const_int -1)) 7140 (const_int 0)) 7141 (label_ref (match_operand 1 "" "")) 7142 (pc))) 7143 (set (match_dup 0) 7144 (plus:SI (match_dup 0) 7145 (const_int -1)))] 7146 "find_reg_note (insn, REG_NONNEG, 0)" 7147 "@dots{}") 7148@end group 7149@end smallexample 7150 7151Note that since the insn is both a jump insn and has an output, it must 7152deal with its own reloads, hence the `m' constraints. Also note that 7153since this insn is generated by the instruction combination phase 7154combining two sequential insns together into an implicit parallel insn, 7155the iteration counter needs to be biased by the same amount as the 7156decrement operation, in this case @minus{}1. Note that the following similar 7157pattern will not be matched by the combiner. 7158 7159@smallexample 7160@group 7161(define_insn "decrement_and_branch_until_zero" 7162 [(set (pc) 7163 (if_then_else 7164 (ge (match_operand:SI 0 "general_operand" "+d*am") 7165 (const_int 1)) 7166 (label_ref (match_operand 1 "" "")) 7167 (pc))) 7168 (set (match_dup 0) 7169 (plus:SI (match_dup 0) 7170 (const_int -1)))] 7171 "find_reg_note (insn, REG_NONNEG, 0)" 7172 "@dots{}") 7173@end group 7174@end smallexample 7175 7176The other two special looping patterns, @samp{doloop_begin} and 7177@samp{doloop_end}, are emitted by the loop optimizer for certain 7178well-behaved loops with a finite number of loop iterations using 7179information collected during strength reduction. 7180 7181The @samp{doloop_end} pattern describes the actual looping instruction 7182(or the implicit looping operation) and the @samp{doloop_begin} pattern 7183is an optional companion pattern that can be used for initialization 7184needed for some low-overhead looping instructions. 7185 7186Note that some machines require the actual looping instruction to be 7187emitted at the top of the loop (e.g., the TMS320C3x/C4x DSPs). Emitting 7188the true RTL for a looping instruction at the top of the loop can cause 7189problems with flow analysis. So instead, a dummy @code{doloop} insn is 7190emitted at the end of the loop. The machine dependent reorg pass checks 7191for the presence of this @code{doloop} insn and then searches back to 7192the top of the loop, where it inserts the true looping insn (provided 7193there are no instructions in the loop which would cause problems). Any 7194additional labels can be emitted at this point. In addition, if the 7195desired special iteration counter register was not allocated, this 7196machine dependent reorg pass could emit a traditional compare and jump 7197instruction pair. 7198 7199The essential difference between the 7200@samp{decrement_and_branch_until_zero} and the @samp{doloop_end} 7201patterns is that the loop optimizer allocates an additional pseudo 7202register for the latter as an iteration counter. This pseudo register 7203cannot be used within the loop (i.e., general induction variables cannot 7204be derived from it), however, in many cases the loop induction variable 7205may become redundant and removed by the flow pass. 7206 7207 7208@end ifset 7209@ifset INTERNALS 7210@node Insn Canonicalizations 7211@section Canonicalization of Instructions 7212@cindex canonicalization of instructions 7213@cindex insn canonicalization 7214 7215There are often cases where multiple RTL expressions could represent an 7216operation performed by a single machine instruction. This situation is 7217most commonly encountered with logical, branch, and multiply-accumulate 7218instructions. In such cases, the compiler attempts to convert these 7219multiple RTL expressions into a single canonical form to reduce the 7220number of insn patterns required. 7221 7222In addition to algebraic simplifications, following canonicalizations 7223are performed: 7224 7225@itemize @bullet 7226@item 7227For commutative and comparison operators, a constant is always made the 7228second operand. If a machine only supports a constant as the second 7229operand, only patterns that match a constant in the second operand need 7230be supplied. 7231 7232@item 7233For associative operators, a sequence of operators will always chain 7234to the left; for instance, only the left operand of an integer @code{plus} 7235can itself be a @code{plus}. @code{and}, @code{ior}, @code{xor}, 7236@code{plus}, @code{mult}, @code{smin}, @code{smax}, @code{umin}, and 7237@code{umax} are associative when applied to integers, and sometimes to 7238floating-point. 7239 7240@item 7241@cindex @code{neg}, canonicalization of 7242@cindex @code{not}, canonicalization of 7243@cindex @code{mult}, canonicalization of 7244@cindex @code{plus}, canonicalization of 7245@cindex @code{minus}, canonicalization of 7246For these operators, if only one operand is a @code{neg}, @code{not}, 7247@code{mult}, @code{plus}, or @code{minus} expression, it will be the 7248first operand. 7249 7250@item 7251In combinations of @code{neg}, @code{mult}, @code{plus}, and 7252@code{minus}, the @code{neg} operations (if any) will be moved inside 7253the operations as far as possible. For instance, 7254@code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but 7255@code{(plus (mult (neg B) C) A)} is canonicalized as 7256@code{(minus A (mult B C))}. 7257 7258@cindex @code{compare}, canonicalization of 7259@item 7260For the @code{compare} operator, a constant is always the second operand 7261if the first argument is a condition code register or @code{(cc0)}. 7262 7263@item 7264An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or 7265@code{minus} is made the first operand under the same conditions as 7266above. 7267 7268@item 7269@code{(ltu (plus @var{a} @var{b}) @var{b})} is converted to 7270@code{(ltu (plus @var{a} @var{b}) @var{a})}. Likewise with @code{geu} instead 7271of @code{ltu}. 7272 7273@item 7274@code{(minus @var{x} (const_int @var{n}))} is converted to 7275@code{(plus @var{x} (const_int @var{-n}))}. 7276 7277@item 7278Within address computations (i.e., inside @code{mem}), a left shift is 7279converted into the appropriate multiplication by a power of two. 7280 7281@cindex @code{ior}, canonicalization of 7282@cindex @code{and}, canonicalization of 7283@cindex De Morgan's law 7284@item 7285De Morgan's Law is used to move bitwise negation inside a bitwise 7286logical-and or logical-or operation. If this results in only one 7287operand being a @code{not} expression, it will be the first one. 7288 7289A machine that has an instruction that performs a bitwise logical-and of one 7290operand with the bitwise negation of the other should specify the pattern 7291for that instruction as 7292 7293@smallexample 7294(define_insn "" 7295 [(set (match_operand:@var{m} 0 @dots{}) 7296 (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) 7297 (match_operand:@var{m} 2 @dots{})))] 7298 "@dots{}" 7299 "@dots{}") 7300@end smallexample 7301 7302@noindent 7303Similarly, a pattern for a ``NAND'' instruction should be written 7304 7305@smallexample 7306(define_insn "" 7307 [(set (match_operand:@var{m} 0 @dots{}) 7308 (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) 7309 (not:@var{m} (match_operand:@var{m} 2 @dots{}))))] 7310 "@dots{}" 7311 "@dots{}") 7312@end smallexample 7313 7314In both cases, it is not necessary to include patterns for the many 7315logically equivalent RTL expressions. 7316 7317@cindex @code{xor}, canonicalization of 7318@item 7319The only possible RTL expressions involving both bitwise exclusive-or 7320and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})} 7321and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}. 7322 7323@item 7324The sum of three items, one of which is a constant, will only appear in 7325the form 7326 7327@smallexample 7328(plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant}) 7329@end smallexample 7330 7331@cindex @code{zero_extract}, canonicalization of 7332@cindex @code{sign_extract}, canonicalization of 7333@item 7334Equality comparisons of a group of bits (usually a single bit) with zero 7335will be written using @code{zero_extract} rather than the equivalent 7336@code{and} or @code{sign_extract} operations. 7337 7338@cindex @code{mult}, canonicalization of 7339@item 7340@code{(sign_extend:@var{m1} (mult:@var{m2} (sign_extend:@var{m2} @var{x}) 7341(sign_extend:@var{m2} @var{y})))} is converted to @code{(mult:@var{m1} 7342(sign_extend:@var{m1} @var{x}) (sign_extend:@var{m1} @var{y}))}, and likewise 7343for @code{zero_extend}. 7344 7345@item 7346@code{(sign_extend:@var{m1} (mult:@var{m2} (ashiftrt:@var{m2} 7347@var{x} @var{s}) (sign_extend:@var{m2} @var{y})))} is converted 7348to @code{(mult:@var{m1} (sign_extend:@var{m1} (ashiftrt:@var{m2} 7349@var{x} @var{s})) (sign_extend:@var{m1} @var{y}))}, and likewise for 7350patterns using @code{zero_extend} and @code{lshiftrt}. If the second 7351operand of @code{mult} is also a shift, then that is extended also. 7352This transformation is only applied when it can be proven that the 7353original operation had sufficient precision to prevent overflow. 7354 7355@end itemize 7356 7357Further canonicalization rules are defined in the function 7358@code{commutative_operand_precedence} in @file{gcc/rtlanal.c}. 7359 7360@end ifset 7361@ifset INTERNALS 7362@node Expander Definitions 7363@section Defining RTL Sequences for Code Generation 7364@cindex expander definitions 7365@cindex code generation RTL sequences 7366@cindex defining RTL sequences for code generation 7367 7368On some target machines, some standard pattern names for RTL generation 7369cannot be handled with single insn, but a sequence of RTL insns can 7370represent them. For these target machines, you can write a 7371@code{define_expand} to specify how to generate the sequence of RTL@. 7372 7373@findex define_expand 7374A @code{define_expand} is an RTL expression that looks almost like a 7375@code{define_insn}; but, unlike the latter, a @code{define_expand} is used 7376only for RTL generation and it can produce more than one RTL insn. 7377 7378A @code{define_expand} RTX has four operands: 7379 7380@itemize @bullet 7381@item 7382The name. Each @code{define_expand} must have a name, since the only 7383use for it is to refer to it by name. 7384 7385@item 7386The RTL template. This is a vector of RTL expressions representing 7387a sequence of separate instructions. Unlike @code{define_insn}, there 7388is no implicit surrounding @code{PARALLEL}. 7389 7390@item 7391The condition, a string containing a C expression. This expression is 7392used to express how the availability of this pattern depends on 7393subclasses of target machine, selected by command-line options when GCC 7394is run. This is just like the condition of a @code{define_insn} that 7395has a standard name. Therefore, the condition (if present) may not 7396depend on the data in the insn being matched, but only the 7397target-machine-type flags. The compiler needs to test these conditions 7398during initialization in order to learn exactly which named instructions 7399are available in a particular run. 7400 7401@item 7402The preparation statements, a string containing zero or more C 7403statements which are to be executed before RTL code is generated from 7404the RTL template. 7405 7406Usually these statements prepare temporary registers for use as 7407internal operands in the RTL template, but they can also generate RTL 7408insns directly by calling routines such as @code{emit_insn}, etc. 7409Any such insns precede the ones that come from the RTL template. 7410 7411@item 7412Optionally, a vector containing the values of attributes. @xref{Insn 7413Attributes}. 7414@end itemize 7415 7416Every RTL insn emitted by a @code{define_expand} must match some 7417@code{define_insn} in the machine description. Otherwise, the compiler 7418will crash when trying to generate code for the insn or trying to optimize 7419it. 7420 7421The RTL template, in addition to controlling generation of RTL insns, 7422also describes the operands that need to be specified when this pattern 7423is used. In particular, it gives a predicate for each operand. 7424 7425A true operand, which needs to be specified in order to generate RTL from 7426the pattern, should be described with a @code{match_operand} in its first 7427occurrence in the RTL template. This enters information on the operand's 7428predicate into the tables that record such things. GCC uses the 7429information to preload the operand into a register if that is required for 7430valid RTL code. If the operand is referred to more than once, subsequent 7431references should use @code{match_dup}. 7432 7433The RTL template may also refer to internal ``operands'' which are 7434temporary registers or labels used only within the sequence made by the 7435@code{define_expand}. Internal operands are substituted into the RTL 7436template with @code{match_dup}, never with @code{match_operand}. The 7437values of the internal operands are not passed in as arguments by the 7438compiler when it requests use of this pattern. Instead, they are computed 7439within the pattern, in the preparation statements. These statements 7440compute the values and store them into the appropriate elements of 7441@code{operands} so that @code{match_dup} can find them. 7442 7443There are two special macros defined for use in the preparation statements: 7444@code{DONE} and @code{FAIL}. Use them with a following semicolon, 7445as a statement. 7446 7447@table @code 7448 7449@findex DONE 7450@item DONE 7451Use the @code{DONE} macro to end RTL generation for the pattern. The 7452only RTL insns resulting from the pattern on this occasion will be 7453those already emitted by explicit calls to @code{emit_insn} within the 7454preparation statements; the RTL template will not be generated. 7455 7456@findex FAIL 7457@item FAIL 7458Make the pattern fail on this occasion. When a pattern fails, it means 7459that the pattern was not truly available. The calling routines in the 7460compiler will try other strategies for code generation using other patterns. 7461 7462Failure is currently supported only for binary (addition, multiplication, 7463shifting, etc.) and bit-field (@code{extv}, @code{extzv}, and @code{insv}) 7464operations. 7465@end table 7466 7467If the preparation falls through (invokes neither @code{DONE} nor 7468@code{FAIL}), then the @code{define_expand} acts like a 7469@code{define_insn} in that the RTL template is used to generate the 7470insn. 7471 7472The RTL template is not used for matching, only for generating the 7473initial insn list. If the preparation statement always invokes 7474@code{DONE} or @code{FAIL}, the RTL template may be reduced to a simple 7475list of operands, such as this example: 7476 7477@smallexample 7478@group 7479(define_expand "addsi3" 7480 [(match_operand:SI 0 "register_operand" "") 7481 (match_operand:SI 1 "register_operand" "") 7482 (match_operand:SI 2 "register_operand" "")] 7483@end group 7484@group 7485 "" 7486 " 7487@{ 7488 handle_add (operands[0], operands[1], operands[2]); 7489 DONE; 7490@}") 7491@end group 7492@end smallexample 7493 7494Here is an example, the definition of left-shift for the SPUR chip: 7495 7496@smallexample 7497@group 7498(define_expand "ashlsi3" 7499 [(set (match_operand:SI 0 "register_operand" "") 7500 (ashift:SI 7501@end group 7502@group 7503 (match_operand:SI 1 "register_operand" "") 7504 (match_operand:SI 2 "nonmemory_operand" "")))] 7505 "" 7506 " 7507@end group 7508@end smallexample 7509 7510@smallexample 7511@group 7512@{ 7513 if (GET_CODE (operands[2]) != CONST_INT 7514 || (unsigned) INTVAL (operands[2]) > 3) 7515 FAIL; 7516@}") 7517@end group 7518@end smallexample 7519 7520@noindent 7521This example uses @code{define_expand} so that it can generate an RTL insn 7522for shifting when the shift-count is in the supported range of 0 to 3 but 7523fail in other cases where machine insns aren't available. When it fails, 7524the compiler tries another strategy using different patterns (such as, a 7525library call). 7526 7527If the compiler were able to handle nontrivial condition-strings in 7528patterns with names, then it would be possible to use a 7529@code{define_insn} in that case. Here is another case (zero-extension 7530on the 68000) which makes more use of the power of @code{define_expand}: 7531 7532@smallexample 7533(define_expand "zero_extendhisi2" 7534 [(set (match_operand:SI 0 "general_operand" "") 7535 (const_int 0)) 7536 (set (strict_low_part 7537 (subreg:HI 7538 (match_dup 0) 7539 0)) 7540 (match_operand:HI 1 "general_operand" ""))] 7541 "" 7542 "operands[1] = make_safe_from (operands[1], operands[0]);") 7543@end smallexample 7544 7545@noindent 7546@findex make_safe_from 7547Here two RTL insns are generated, one to clear the entire output operand 7548and the other to copy the input operand into its low half. This sequence 7549is incorrect if the input operand refers to [the old value of] the output 7550operand, so the preparation statement makes sure this isn't so. The 7551function @code{make_safe_from} copies the @code{operands[1]} into a 7552temporary register if it refers to @code{operands[0]}. It does this 7553by emitting another RTL insn. 7554 7555Finally, a third example shows the use of an internal operand. 7556Zero-extension on the SPUR chip is done by @code{and}-ing the result 7557against a halfword mask. But this mask cannot be represented by a 7558@code{const_int} because the constant value is too large to be legitimate 7559on this machine. So it must be copied into a register with 7560@code{force_reg} and then the register used in the @code{and}. 7561 7562@smallexample 7563(define_expand "zero_extendhisi2" 7564 [(set (match_operand:SI 0 "register_operand" "") 7565 (and:SI (subreg:SI 7566 (match_operand:HI 1 "register_operand" "") 7567 0) 7568 (match_dup 2)))] 7569 "" 7570 "operands[2] 7571 = force_reg (SImode, GEN_INT (65535)); ") 7572@end smallexample 7573 7574@emph{Note:} If the @code{define_expand} is used to serve a 7575standard binary or unary arithmetic operation or a bit-field operation, 7576then the last insn it generates must not be a @code{code_label}, 7577@code{barrier} or @code{note}. It must be an @code{insn}, 7578@code{jump_insn} or @code{call_insn}. If you don't need a real insn 7579at the end, emit an insn to copy the result of the operation into 7580itself. Such an insn will generate no code, but it can avoid problems 7581in the compiler. 7582 7583@end ifset 7584@ifset INTERNALS 7585@node Insn Splitting 7586@section Defining How to Split Instructions 7587@cindex insn splitting 7588@cindex instruction splitting 7589@cindex splitting instructions 7590 7591There are two cases where you should specify how to split a pattern 7592into multiple insns. On machines that have instructions requiring 7593delay slots (@pxref{Delay Slots}) or that have instructions whose 7594output is not available for multiple cycles (@pxref{Processor pipeline 7595description}), the compiler phases that optimize these cases need to 7596be able to move insns into one-instruction delay slots. However, some 7597insns may generate more than one machine instruction. These insns 7598cannot be placed into a delay slot. 7599 7600Often you can rewrite the single insn as a list of individual insns, 7601each corresponding to one machine instruction. The disadvantage of 7602doing so is that it will cause the compilation to be slower and require 7603more space. If the resulting insns are too complex, it may also 7604suppress some optimizations. The compiler splits the insn if there is a 7605reason to believe that it might improve instruction or delay slot 7606scheduling. 7607 7608The insn combiner phase also splits putative insns. If three insns are 7609merged into one insn with a complex expression that cannot be matched by 7610some @code{define_insn} pattern, the combiner phase attempts to split 7611the complex pattern into two insns that are recognized. Usually it can 7612break the complex pattern into two patterns by splitting out some 7613subexpression. However, in some other cases, such as performing an 7614addition of a large constant in two insns on a RISC machine, the way to 7615split the addition into two insns is machine-dependent. 7616 7617@findex define_split 7618The @code{define_split} definition tells the compiler how to split a 7619complex insn into several simpler insns. It looks like this: 7620 7621@smallexample 7622(define_split 7623 [@var{insn-pattern}] 7624 "@var{condition}" 7625 [@var{new-insn-pattern-1} 7626 @var{new-insn-pattern-2} 7627 @dots{}] 7628 "@var{preparation-statements}") 7629@end smallexample 7630 7631@var{insn-pattern} is a pattern that needs to be split and 7632@var{condition} is the final condition to be tested, as in a 7633@code{define_insn}. When an insn matching @var{insn-pattern} and 7634satisfying @var{condition} is found, it is replaced in the insn list 7635with the insns given by @var{new-insn-pattern-1}, 7636@var{new-insn-pattern-2}, etc. 7637 7638The @var{preparation-statements} are similar to those statements that 7639are specified for @code{define_expand} (@pxref{Expander Definitions}) 7640and are executed before the new RTL is generated to prepare for the 7641generated code or emit some insns whose pattern is not fixed. Unlike 7642those in @code{define_expand}, however, these statements must not 7643generate any new pseudo-registers. Once reload has completed, they also 7644must not allocate any space in the stack frame. 7645 7646Patterns are matched against @var{insn-pattern} in two different 7647circumstances. If an insn needs to be split for delay slot scheduling 7648or insn scheduling, the insn is already known to be valid, which means 7649that it must have been matched by some @code{define_insn} and, if 7650@code{reload_completed} is nonzero, is known to satisfy the constraints 7651of that @code{define_insn}. In that case, the new insn patterns must 7652also be insns that are matched by some @code{define_insn} and, if 7653@code{reload_completed} is nonzero, must also satisfy the constraints 7654of those definitions. 7655 7656As an example of this usage of @code{define_split}, consider the following 7657example from @file{a29k.md}, which splits a @code{sign_extend} from 7658@code{HImode} to @code{SImode} into a pair of shift insns: 7659 7660@smallexample 7661(define_split 7662 [(set (match_operand:SI 0 "gen_reg_operand" "") 7663 (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))] 7664 "" 7665 [(set (match_dup 0) 7666 (ashift:SI (match_dup 1) 7667 (const_int 16))) 7668 (set (match_dup 0) 7669 (ashiftrt:SI (match_dup 0) 7670 (const_int 16)))] 7671 " 7672@{ operands[1] = gen_lowpart (SImode, operands[1]); @}") 7673@end smallexample 7674 7675When the combiner phase tries to split an insn pattern, it is always the 7676case that the pattern is @emph{not} matched by any @code{define_insn}. 7677The combiner pass first tries to split a single @code{set} expression 7678and then the same @code{set} expression inside a @code{parallel}, but 7679followed by a @code{clobber} of a pseudo-reg to use as a scratch 7680register. In these cases, the combiner expects exactly two new insn 7681patterns to be generated. It will verify that these patterns match some 7682@code{define_insn} definitions, so you need not do this test in the 7683@code{define_split} (of course, there is no point in writing a 7684@code{define_split} that will never produce insns that match). 7685 7686Here is an example of this use of @code{define_split}, taken from 7687@file{rs6000.md}: 7688 7689@smallexample 7690(define_split 7691 [(set (match_operand:SI 0 "gen_reg_operand" "") 7692 (plus:SI (match_operand:SI 1 "gen_reg_operand" "") 7693 (match_operand:SI 2 "non_add_cint_operand" "")))] 7694 "" 7695 [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3))) 7696 (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))] 7697" 7698@{ 7699 int low = INTVAL (operands[2]) & 0xffff; 7700 int high = (unsigned) INTVAL (operands[2]) >> 16; 7701 7702 if (low & 0x8000) 7703 high++, low |= 0xffff0000; 7704 7705 operands[3] = GEN_INT (high << 16); 7706 operands[4] = GEN_INT (low); 7707@}") 7708@end smallexample 7709 7710Here the predicate @code{non_add_cint_operand} matches any 7711@code{const_int} that is @emph{not} a valid operand of a single add 7712insn. The add with the smaller displacement is written so that it 7713can be substituted into the address of a subsequent operation. 7714 7715An example that uses a scratch register, from the same file, generates 7716an equality comparison of a register and a large constant: 7717 7718@smallexample 7719(define_split 7720 [(set (match_operand:CC 0 "cc_reg_operand" "") 7721 (compare:CC (match_operand:SI 1 "gen_reg_operand" "") 7722 (match_operand:SI 2 "non_short_cint_operand" ""))) 7723 (clobber (match_operand:SI 3 "gen_reg_operand" ""))] 7724 "find_single_use (operands[0], insn, 0) 7725 && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ 7726 || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)" 7727 [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4))) 7728 (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))] 7729 " 7730@{ 7731 /* @r{Get the constant we are comparing against, C, and see what it 7732 looks like sign-extended to 16 bits. Then see what constant 7733 could be XOR'ed with C to get the sign-extended value.} */ 7734 7735 int c = INTVAL (operands[2]); 7736 int sextc = (c << 16) >> 16; 7737 int xorv = c ^ sextc; 7738 7739 operands[4] = GEN_INT (xorv); 7740 operands[5] = GEN_INT (sextc); 7741@}") 7742@end smallexample 7743 7744To avoid confusion, don't write a single @code{define_split} that 7745accepts some insns that match some @code{define_insn} as well as some 7746insns that don't. Instead, write two separate @code{define_split} 7747definitions, one for the insns that are valid and one for the insns that 7748are not valid. 7749 7750The splitter is allowed to split jump instructions into sequence of 7751jumps or create new jumps in while splitting non-jump instructions. As 7752the central flowgraph and branch prediction information needs to be updated, 7753several restriction apply. 7754 7755Splitting of jump instruction into sequence that over by another jump 7756instruction is always valid, as compiler expect identical behavior of new 7757jump. When new sequence contains multiple jump instructions or new labels, 7758more assistance is needed. Splitter is required to create only unconditional 7759jumps, or simple conditional jump instructions. Additionally it must attach a 7760@code{REG_BR_PROB} note to each conditional jump. A global variable 7761@code{split_branch_probability} holds the probability of the original branch in case 7762it was a simple conditional jump, @minus{}1 otherwise. To simplify 7763recomputing of edge frequencies, the new sequence is required to have only 7764forward jumps to the newly created labels. 7765 7766@findex define_insn_and_split 7767For the common case where the pattern of a define_split exactly matches the 7768pattern of a define_insn, use @code{define_insn_and_split}. It looks like 7769this: 7770 7771@smallexample 7772(define_insn_and_split 7773 [@var{insn-pattern}] 7774 "@var{condition}" 7775 "@var{output-template}" 7776 "@var{split-condition}" 7777 [@var{new-insn-pattern-1} 7778 @var{new-insn-pattern-2} 7779 @dots{}] 7780 "@var{preparation-statements}" 7781 [@var{insn-attributes}]) 7782 7783@end smallexample 7784 7785@var{insn-pattern}, @var{condition}, @var{output-template}, and 7786@var{insn-attributes} are used as in @code{define_insn}. The 7787@var{new-insn-pattern} vector and the @var{preparation-statements} are used as 7788in a @code{define_split}. The @var{split-condition} is also used as in 7789@code{define_split}, with the additional behavior that if the condition starts 7790with @samp{&&}, the condition used for the split will be the constructed as a 7791logical ``and'' of the split condition with the insn condition. For example, 7792from i386.md: 7793 7794@smallexample 7795(define_insn_and_split "zero_extendhisi2_and" 7796 [(set (match_operand:SI 0 "register_operand" "=r") 7797 (zero_extend:SI (match_operand:HI 1 "register_operand" "0"))) 7798 (clobber (reg:CC 17))] 7799 "TARGET_ZERO_EXTEND_WITH_AND && !optimize_size" 7800 "#" 7801 "&& reload_completed" 7802 [(parallel [(set (match_dup 0) 7803 (and:SI (match_dup 0) (const_int 65535))) 7804 (clobber (reg:CC 17))])] 7805 "" 7806 [(set_attr "type" "alu1")]) 7807 7808@end smallexample 7809 7810In this case, the actual split condition will be 7811@samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}. 7812 7813The @code{define_insn_and_split} construction provides exactly the same 7814functionality as two separate @code{define_insn} and @code{define_split} 7815patterns. It exists for compactness, and as a maintenance tool to prevent 7816having to ensure the two patterns' templates match. 7817 7818@end ifset 7819@ifset INTERNALS 7820@node Including Patterns 7821@section Including Patterns in Machine Descriptions. 7822@cindex insn includes 7823 7824@findex include 7825The @code{include} pattern tells the compiler tools where to 7826look for patterns that are in files other than in the file 7827@file{.md}. This is used only at build time and there is no preprocessing allowed. 7828 7829It looks like: 7830 7831@smallexample 7832 7833(include 7834 @var{pathname}) 7835@end smallexample 7836 7837For example: 7838 7839@smallexample 7840 7841(include "filestuff") 7842 7843@end smallexample 7844 7845Where @var{pathname} is a string that specifies the location of the file, 7846specifies the include file to be in @file{gcc/config/target/filestuff}. The 7847directory @file{gcc/config/target} is regarded as the default directory. 7848 7849 7850Machine descriptions may be split up into smaller more manageable subsections 7851and placed into subdirectories. 7852 7853By specifying: 7854 7855@smallexample 7856 7857(include "BOGUS/filestuff") 7858 7859@end smallexample 7860 7861the include file is specified to be in @file{gcc/config/@var{target}/BOGUS/filestuff}. 7862 7863Specifying an absolute path for the include file such as; 7864@smallexample 7865 7866(include "/u2/BOGUS/filestuff") 7867 7868@end smallexample 7869is permitted but is not encouraged. 7870 7871@subsection RTL Generation Tool Options for Directory Search 7872@cindex directory options .md 7873@cindex options, directory search 7874@cindex search options 7875 7876The @option{-I@var{dir}} option specifies directories to search for machine descriptions. 7877For example: 7878 7879@smallexample 7880 7881genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md 7882 7883@end smallexample 7884 7885 7886Add the directory @var{dir} to the head of the list of directories to be 7887searched for header files. This can be used to override a system machine definition 7888file, substituting your own version, since these directories are 7889searched before the default machine description file directories. If you use more than 7890one @option{-I} option, the directories are scanned in left-to-right 7891order; the standard default directory come after. 7892 7893 7894@end ifset 7895@ifset INTERNALS 7896@node Peephole Definitions 7897@section Machine-Specific Peephole Optimizers 7898@cindex peephole optimizer definitions 7899@cindex defining peephole optimizers 7900 7901In addition to instruction patterns the @file{md} file may contain 7902definitions of machine-specific peephole optimizations. 7903 7904The combiner does not notice certain peephole optimizations when the data 7905flow in the program does not suggest that it should try them. For example, 7906sometimes two consecutive insns related in purpose can be combined even 7907though the second one does not appear to use a register computed in the 7908first one. A machine-specific peephole optimizer can detect such 7909opportunities. 7910 7911There are two forms of peephole definitions that may be used. The 7912original @code{define_peephole} is run at assembly output time to 7913match insns and substitute assembly text. Use of @code{define_peephole} 7914is deprecated. 7915 7916A newer @code{define_peephole2} matches insns and substitutes new 7917insns. The @code{peephole2} pass is run after register allocation 7918but before scheduling, which may result in much better code for 7919targets that do scheduling. 7920 7921@menu 7922* define_peephole:: RTL to Text Peephole Optimizers 7923* define_peephole2:: RTL to RTL Peephole Optimizers 7924@end menu 7925 7926@end ifset 7927@ifset INTERNALS 7928@node define_peephole 7929@subsection RTL to Text Peephole Optimizers 7930@findex define_peephole 7931 7932@need 1000 7933A definition looks like this: 7934 7935@smallexample 7936(define_peephole 7937 [@var{insn-pattern-1} 7938 @var{insn-pattern-2} 7939 @dots{}] 7940 "@var{condition}" 7941 "@var{template}" 7942 "@var{optional-insn-attributes}") 7943@end smallexample 7944 7945@noindent 7946The last string operand may be omitted if you are not using any 7947machine-specific information in this machine description. If present, 7948it must obey the same rules as in a @code{define_insn}. 7949 7950In this skeleton, @var{insn-pattern-1} and so on are patterns to match 7951consecutive insns. The optimization applies to a sequence of insns when 7952@var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches 7953the next, and so on. 7954 7955Each of the insns matched by a peephole must also match a 7956@code{define_insn}. Peepholes are checked only at the last stage just 7957before code generation, and only optionally. Therefore, any insn which 7958would match a peephole but no @code{define_insn} will cause a crash in code 7959generation in an unoptimized compilation, or at various optimization 7960stages. 7961 7962The operands of the insns are matched with @code{match_operands}, 7963@code{match_operator}, and @code{match_dup}, as usual. What is not 7964usual is that the operand numbers apply to all the insn patterns in the 7965definition. So, you can check for identical operands in two insns by 7966using @code{match_operand} in one insn and @code{match_dup} in the 7967other. 7968 7969The operand constraints used in @code{match_operand} patterns do not have 7970any direct effect on the applicability of the peephole, but they will 7971be validated afterward, so make sure your constraints are general enough 7972to apply whenever the peephole matches. If the peephole matches 7973but the constraints are not satisfied, the compiler will crash. 7974 7975It is safe to omit constraints in all the operands of the peephole; or 7976you can write constraints which serve as a double-check on the criteria 7977previously tested. 7978 7979Once a sequence of insns matches the patterns, the @var{condition} is 7980checked. This is a C expression which makes the final decision whether to 7981perform the optimization (we do so if the expression is nonzero). If 7982@var{condition} is omitted (in other words, the string is empty) then the 7983optimization is applied to every sequence of insns that matches the 7984patterns. 7985 7986The defined peephole optimizations are applied after register allocation 7987is complete. Therefore, the peephole definition can check which 7988operands have ended up in which kinds of registers, just by looking at 7989the operands. 7990 7991@findex prev_active_insn 7992The way to refer to the operands in @var{condition} is to write 7993@code{operands[@var{i}]} for operand number @var{i} (as matched by 7994@code{(match_operand @var{i} @dots{})}). Use the variable @code{insn} 7995to refer to the last of the insns being matched; use 7996@code{prev_active_insn} to find the preceding insns. 7997 7998@findex dead_or_set_p 7999When optimizing computations with intermediate results, you can use 8000@var{condition} to match only when the intermediate results are not used 8001elsewhere. Use the C expression @code{dead_or_set_p (@var{insn}, 8002@var{op})}, where @var{insn} is the insn in which you expect the value 8003to be used for the last time (from the value of @code{insn}, together 8004with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate 8005value (from @code{operands[@var{i}]}). 8006 8007Applying the optimization means replacing the sequence of insns with one 8008new insn. The @var{template} controls ultimate output of assembler code 8009for this combined insn. It works exactly like the template of a 8010@code{define_insn}. Operand numbers in this template are the same ones 8011used in matching the original sequence of insns. 8012 8013The result of a defined peephole optimizer does not need to match any of 8014the insn patterns in the machine description; it does not even have an 8015opportunity to match them. The peephole optimizer definition itself serves 8016as the insn pattern to control how the insn is output. 8017 8018Defined peephole optimizers are run as assembler code is being output, 8019so the insns they produce are never combined or rearranged in any way. 8020 8021Here is an example, taken from the 68000 machine description: 8022 8023@smallexample 8024(define_peephole 8025 [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4))) 8026 (set (match_operand:DF 0 "register_operand" "=f") 8027 (match_operand:DF 1 "register_operand" "ad"))] 8028 "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])" 8029@{ 8030 rtx xoperands[2]; 8031 xoperands[1] = gen_rtx_REG (SImode, REGNO (operands[1]) + 1); 8032#ifdef MOTOROLA 8033 output_asm_insn ("move.l %1,(sp)", xoperands); 8034 output_asm_insn ("move.l %1,-(sp)", operands); 8035 return "fmove.d (sp)+,%0"; 8036#else 8037 output_asm_insn ("movel %1,sp@@", xoperands); 8038 output_asm_insn ("movel %1,sp@@-", operands); 8039 return "fmoved sp@@+,%0"; 8040#endif 8041@}) 8042@end smallexample 8043 8044@need 1000 8045The effect of this optimization is to change 8046 8047@smallexample 8048@group 8049jbsr _foobar 8050addql #4,sp 8051movel d1,sp@@- 8052movel d0,sp@@- 8053fmoved sp@@+,fp0 8054@end group 8055@end smallexample 8056 8057@noindent 8058into 8059 8060@smallexample 8061@group 8062jbsr _foobar 8063movel d1,sp@@ 8064movel d0,sp@@- 8065fmoved sp@@+,fp0 8066@end group 8067@end smallexample 8068 8069@ignore 8070@findex CC_REVERSED 8071If a peephole matches a sequence including one or more jump insns, you must 8072take account of the flags such as @code{CC_REVERSED} which specify that the 8073condition codes are represented in an unusual manner. The compiler 8074automatically alters any ordinary conditional jumps which occur in such 8075situations, but the compiler cannot alter jumps which have been replaced by 8076peephole optimizations. So it is up to you to alter the assembler code 8077that the peephole produces. Supply C code to write the assembler output, 8078and in this C code check the condition code status flags and change the 8079assembler code as appropriate. 8080@end ignore 8081 8082@var{insn-pattern-1} and so on look @emph{almost} like the second 8083operand of @code{define_insn}. There is one important difference: the 8084second operand of @code{define_insn} consists of one or more RTX's 8085enclosed in square brackets. Usually, there is only one: then the same 8086action can be written as an element of a @code{define_peephole}. But 8087when there are multiple actions in a @code{define_insn}, they are 8088implicitly enclosed in a @code{parallel}. Then you must explicitly 8089write the @code{parallel}, and the square brackets within it, in the 8090@code{define_peephole}. Thus, if an insn pattern looks like this, 8091 8092@smallexample 8093(define_insn "divmodsi4" 8094 [(set (match_operand:SI 0 "general_operand" "=d") 8095 (div:SI (match_operand:SI 1 "general_operand" "0") 8096 (match_operand:SI 2 "general_operand" "dmsK"))) 8097 (set (match_operand:SI 3 "general_operand" "=d") 8098 (mod:SI (match_dup 1) (match_dup 2)))] 8099 "TARGET_68020" 8100 "divsl%.l %2,%3:%0") 8101@end smallexample 8102 8103@noindent 8104then the way to mention this insn in a peephole is as follows: 8105 8106@smallexample 8107(define_peephole 8108 [@dots{} 8109 (parallel 8110 [(set (match_operand:SI 0 "general_operand" "=d") 8111 (div:SI (match_operand:SI 1 "general_operand" "0") 8112 (match_operand:SI 2 "general_operand" "dmsK"))) 8113 (set (match_operand:SI 3 "general_operand" "=d") 8114 (mod:SI (match_dup 1) (match_dup 2)))]) 8115 @dots{}] 8116 @dots{}) 8117@end smallexample 8118 8119@end ifset 8120@ifset INTERNALS 8121@node define_peephole2 8122@subsection RTL to RTL Peephole Optimizers 8123@findex define_peephole2 8124 8125The @code{define_peephole2} definition tells the compiler how to 8126substitute one sequence of instructions for another sequence, 8127what additional scratch registers may be needed and what their 8128lifetimes must be. 8129 8130@smallexample 8131(define_peephole2 8132 [@var{insn-pattern-1} 8133 @var{insn-pattern-2} 8134 @dots{}] 8135 "@var{condition}" 8136 [@var{new-insn-pattern-1} 8137 @var{new-insn-pattern-2} 8138 @dots{}] 8139 "@var{preparation-statements}") 8140@end smallexample 8141 8142The definition is almost identical to @code{define_split} 8143(@pxref{Insn Splitting}) except that the pattern to match is not a 8144single instruction, but a sequence of instructions. 8145 8146It is possible to request additional scratch registers for use in the 8147output template. If appropriate registers are not free, the pattern 8148will simply not match. 8149 8150@findex match_scratch 8151@findex match_dup 8152Scratch registers are requested with a @code{match_scratch} pattern at 8153the top level of the input pattern. The allocated register (initially) will 8154be dead at the point requested within the original sequence. If the scratch 8155is used at more than a single point, a @code{match_dup} pattern at the 8156top level of the input pattern marks the last position in the input sequence 8157at which the register must be available. 8158 8159Here is an example from the IA-32 machine description: 8160 8161@smallexample 8162(define_peephole2 8163 [(match_scratch:SI 2 "r") 8164 (parallel [(set (match_operand:SI 0 "register_operand" "") 8165 (match_operator:SI 3 "arith_or_logical_operator" 8166 [(match_dup 0) 8167 (match_operand:SI 1 "memory_operand" "")])) 8168 (clobber (reg:CC 17))])] 8169 "! optimize_size && ! TARGET_READ_MODIFY" 8170 [(set (match_dup 2) (match_dup 1)) 8171 (parallel [(set (match_dup 0) 8172 (match_op_dup 3 [(match_dup 0) (match_dup 2)])) 8173 (clobber (reg:CC 17))])] 8174 "") 8175@end smallexample 8176 8177@noindent 8178This pattern tries to split a load from its use in the hopes that we'll be 8179able to schedule around the memory load latency. It allocates a single 8180@code{SImode} register of class @code{GENERAL_REGS} (@code{"r"}) that needs 8181to be live only at the point just before the arithmetic. 8182 8183A real example requiring extended scratch lifetimes is harder to come by, 8184so here's a silly made-up example: 8185 8186@smallexample 8187(define_peephole2 8188 [(match_scratch:SI 4 "r") 8189 (set (match_operand:SI 0 "" "") (match_operand:SI 1 "" "")) 8190 (set (match_operand:SI 2 "" "") (match_dup 1)) 8191 (match_dup 4) 8192 (set (match_operand:SI 3 "" "") (match_dup 1))] 8193 "/* @r{determine 1 does not overlap 0 and 2} */" 8194 [(set (match_dup 4) (match_dup 1)) 8195 (set (match_dup 0) (match_dup 4)) 8196 (set (match_dup 2) (match_dup 4)) 8197 (set (match_dup 3) (match_dup 4))] 8198 "") 8199@end smallexample 8200 8201@noindent 8202If we had not added the @code{(match_dup 4)} in the middle of the input 8203sequence, it might have been the case that the register we chose at the 8204beginning of the sequence is killed by the first or second @code{set}. 8205 8206@end ifset 8207@ifset INTERNALS 8208@node Insn Attributes 8209@section Instruction Attributes 8210@cindex insn attributes 8211@cindex instruction attributes 8212 8213In addition to describing the instruction supported by the target machine, 8214the @file{md} file also defines a group of @dfn{attributes} and a set of 8215values for each. Every generated insn is assigned a value for each attribute. 8216One possible attribute would be the effect that the insn has on the machine's 8217condition code. This attribute can then be used by @code{NOTICE_UPDATE_CC} 8218to track the condition codes. 8219 8220@menu 8221* Defining Attributes:: Specifying attributes and their values. 8222* Expressions:: Valid expressions for attribute values. 8223* Tagging Insns:: Assigning attribute values to insns. 8224* Attr Example:: An example of assigning attributes. 8225* Insn Lengths:: Computing the length of insns. 8226* Constant Attributes:: Defining attributes that are constant. 8227* Mnemonic Attribute:: Obtain the instruction mnemonic as attribute value. 8228* Delay Slots:: Defining delay slots required for a machine. 8229* Processor pipeline description:: Specifying information for insn scheduling. 8230@end menu 8231 8232@end ifset 8233@ifset INTERNALS 8234@node Defining Attributes 8235@subsection Defining Attributes and their Values 8236@cindex defining attributes and their values 8237@cindex attributes, defining 8238 8239@findex define_attr 8240The @code{define_attr} expression is used to define each attribute required 8241by the target machine. It looks like: 8242 8243@smallexample 8244(define_attr @var{name} @var{list-of-values} @var{default}) 8245@end smallexample 8246 8247@var{name} is a string specifying the name of the attribute being 8248defined. Some attributes are used in a special way by the rest of the 8249compiler. The @code{enabled} attribute can be used to conditionally 8250enable or disable insn alternatives (@pxref{Disable Insn 8251Alternatives}). The @code{predicable} attribute, together with a 8252suitable @code{define_cond_exec} (@pxref{Conditional Execution}), can 8253be used to automatically generate conditional variants of instruction 8254patterns. The @code{mnemonic} attribute can be used to check for the 8255instruction mnemonic (@pxref{Mnemonic Attribute}). The compiler 8256internally uses the names @code{ce_enabled} and @code{nonce_enabled}, 8257so they should not be used elsewhere as alternative names. 8258 8259@var{list-of-values} is either a string that specifies a comma-separated 8260list of values that can be assigned to the attribute, or a null string to 8261indicate that the attribute takes numeric values. 8262 8263@var{default} is an attribute expression that gives the value of this 8264attribute for insns that match patterns whose definition does not include 8265an explicit value for this attribute. @xref{Attr Example}, for more 8266information on the handling of defaults. @xref{Constant Attributes}, 8267for information on attributes that do not depend on any particular insn. 8268 8269@findex insn-attr.h 8270For each defined attribute, a number of definitions are written to the 8271@file{insn-attr.h} file. For cases where an explicit set of values is 8272specified for an attribute, the following are defined: 8273 8274@itemize @bullet 8275@item 8276A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}. 8277 8278@item 8279An enumerated class is defined for @samp{attr_@var{name}} with 8280elements of the form @samp{@var{upper-name}_@var{upper-value}} where 8281the attribute name and value are first converted to uppercase. 8282 8283@item 8284A function @samp{get_attr_@var{name}} is defined that is passed an insn and 8285returns the attribute value for that insn. 8286@end itemize 8287 8288For example, if the following is present in the @file{md} file: 8289 8290@smallexample 8291(define_attr "type" "branch,fp,load,store,arith" @dots{}) 8292@end smallexample 8293 8294@noindent 8295the following lines will be written to the file @file{insn-attr.h}. 8296 8297@smallexample 8298#define HAVE_ATTR_type 1 8299enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD, 8300 TYPE_STORE, TYPE_ARITH@}; 8301extern enum attr_type get_attr_type (); 8302@end smallexample 8303 8304If the attribute takes numeric values, no @code{enum} type will be 8305defined and the function to obtain the attribute's value will return 8306@code{int}. 8307 8308There are attributes which are tied to a specific meaning. These 8309attributes are not free to use for other purposes: 8310 8311@table @code 8312@item length 8313The @code{length} attribute is used to calculate the length of emitted 8314code chunks. This is especially important when verifying branch 8315distances. @xref{Insn Lengths}. 8316 8317@item enabled 8318The @code{enabled} attribute can be defined to prevent certain 8319alternatives of an insn definition from being used during code 8320generation. @xref{Disable Insn Alternatives}. 8321 8322@item mnemonic 8323The @code{mnemonic} attribute can be defined to implement instruction 8324specific checks in e.g. the pipeline description. 8325@xref{Mnemonic Attribute}. 8326@end table 8327 8328For each of these special attributes, the corresponding 8329@samp{HAVE_ATTR_@var{name}} @samp{#define} is also written when the 8330attribute is not defined; in that case, it is defined as @samp{0}. 8331 8332@findex define_enum_attr 8333@anchor{define_enum_attr} 8334Another way of defining an attribute is to use: 8335 8336@smallexample 8337(define_enum_attr "@var{attr}" "@var{enum}" @var{default}) 8338@end smallexample 8339 8340This works in just the same way as @code{define_attr}, except that 8341the list of values is taken from a separate enumeration called 8342@var{enum} (@pxref{define_enum}). This form allows you to use 8343the same list of values for several attributes without having to 8344repeat the list each time. For example: 8345 8346@smallexample 8347(define_enum "processor" [ 8348 model_a 8349 model_b 8350 @dots{} 8351]) 8352(define_enum_attr "arch" "processor" 8353 (const (symbol_ref "target_arch"))) 8354(define_enum_attr "tune" "processor" 8355 (const (symbol_ref "target_tune"))) 8356@end smallexample 8357 8358defines the same attributes as: 8359 8360@smallexample 8361(define_attr "arch" "model_a,model_b,@dots{}" 8362 (const (symbol_ref "target_arch"))) 8363(define_attr "tune" "model_a,model_b,@dots{}" 8364 (const (symbol_ref "target_tune"))) 8365@end smallexample 8366 8367but without duplicating the processor list. The second example defines two 8368separate C enums (@code{attr_arch} and @code{attr_tune}) whereas the first 8369defines a single C enum (@code{processor}). 8370@end ifset 8371@ifset INTERNALS 8372@node Expressions 8373@subsection Attribute Expressions 8374@cindex attribute expressions 8375 8376RTL expressions used to define attributes use the codes described above 8377plus a few specific to attribute definitions, to be discussed below. 8378Attribute value expressions must have one of the following forms: 8379 8380@table @code 8381@cindex @code{const_int} and attributes 8382@item (const_int @var{i}) 8383The integer @var{i} specifies the value of a numeric attribute. @var{i} 8384must be non-negative. 8385 8386The value of a numeric attribute can be specified either with a 8387@code{const_int}, or as an integer represented as a string in 8388@code{const_string}, @code{eq_attr} (see below), @code{attr}, 8389@code{symbol_ref}, simple arithmetic expressions, and @code{set_attr} 8390overrides on specific instructions (@pxref{Tagging Insns}). 8391 8392@cindex @code{const_string} and attributes 8393@item (const_string @var{value}) 8394The string @var{value} specifies a constant attribute value. 8395If @var{value} is specified as @samp{"*"}, it means that the default value of 8396the attribute is to be used for the insn containing this expression. 8397@samp{"*"} obviously cannot be used in the @var{default} expression 8398of a @code{define_attr}. 8399 8400If the attribute whose value is being specified is numeric, @var{value} 8401must be a string containing a non-negative integer (normally 8402@code{const_int} would be used in this case). Otherwise, it must 8403contain one of the valid values for the attribute. 8404 8405@cindex @code{if_then_else} and attributes 8406@item (if_then_else @var{test} @var{true-value} @var{false-value}) 8407@var{test} specifies an attribute test, whose format is defined below. 8408The value of this expression is @var{true-value} if @var{test} is true, 8409otherwise it is @var{false-value}. 8410 8411@cindex @code{cond} and attributes 8412@item (cond [@var{test1} @var{value1} @dots{}] @var{default}) 8413The first operand of this expression is a vector containing an even 8414number of expressions and consisting of pairs of @var{test} and @var{value} 8415expressions. The value of the @code{cond} expression is that of the 8416@var{value} corresponding to the first true @var{test} expression. If 8417none of the @var{test} expressions are true, the value of the @code{cond} 8418expression is that of the @var{default} expression. 8419@end table 8420 8421@var{test} expressions can have one of the following forms: 8422 8423@table @code 8424@cindex @code{const_int} and attribute tests 8425@item (const_int @var{i}) 8426This test is true if @var{i} is nonzero and false otherwise. 8427 8428@cindex @code{not} and attributes 8429@cindex @code{ior} and attributes 8430@cindex @code{and} and attributes 8431@item (not @var{test}) 8432@itemx (ior @var{test1} @var{test2}) 8433@itemx (and @var{test1} @var{test2}) 8434These tests are true if the indicated logical function is true. 8435 8436@cindex @code{match_operand} and attributes 8437@item (match_operand:@var{m} @var{n} @var{pred} @var{constraints}) 8438This test is true if operand @var{n} of the insn whose attribute value 8439is being determined has mode @var{m} (this part of the test is ignored 8440if @var{m} is @code{VOIDmode}) and the function specified by the string 8441@var{pred} returns a nonzero value when passed operand @var{n} and mode 8442@var{m} (this part of the test is ignored if @var{pred} is the null 8443string). 8444 8445The @var{constraints} operand is ignored and should be the null string. 8446 8447@cindex @code{match_test} and attributes 8448@item (match_test @var{c-expr}) 8449The test is true if C expression @var{c-expr} is true. In non-constant 8450attributes, @var{c-expr} has access to the following variables: 8451 8452@table @var 8453@item insn 8454The rtl instruction under test. 8455@item which_alternative 8456The @code{define_insn} alternative that @var{insn} matches. 8457@xref{Output Statement}. 8458@item operands 8459An array of @var{insn}'s rtl operands. 8460@end table 8461 8462@var{c-expr} behaves like the condition in a C @code{if} statement, 8463so there is no need to explicitly convert the expression into a boolean 84640 or 1 value. For example, the following two tests are equivalent: 8465 8466@smallexample 8467(match_test "x & 2") 8468(match_test "(x & 2) != 0") 8469@end smallexample 8470 8471@cindex @code{le} and attributes 8472@cindex @code{leu} and attributes 8473@cindex @code{lt} and attributes 8474@cindex @code{gt} and attributes 8475@cindex @code{gtu} and attributes 8476@cindex @code{ge} and attributes 8477@cindex @code{geu} and attributes 8478@cindex @code{ne} and attributes 8479@cindex @code{eq} and attributes 8480@cindex @code{plus} and attributes 8481@cindex @code{minus} and attributes 8482@cindex @code{mult} and attributes 8483@cindex @code{div} and attributes 8484@cindex @code{mod} and attributes 8485@cindex @code{abs} and attributes 8486@cindex @code{neg} and attributes 8487@cindex @code{ashift} and attributes 8488@cindex @code{lshiftrt} and attributes 8489@cindex @code{ashiftrt} and attributes 8490@item (le @var{arith1} @var{arith2}) 8491@itemx (leu @var{arith1} @var{arith2}) 8492@itemx (lt @var{arith1} @var{arith2}) 8493@itemx (ltu @var{arith1} @var{arith2}) 8494@itemx (gt @var{arith1} @var{arith2}) 8495@itemx (gtu @var{arith1} @var{arith2}) 8496@itemx (ge @var{arith1} @var{arith2}) 8497@itemx (geu @var{arith1} @var{arith2}) 8498@itemx (ne @var{arith1} @var{arith2}) 8499@itemx (eq @var{arith1} @var{arith2}) 8500These tests are true if the indicated comparison of the two arithmetic 8501expressions is true. Arithmetic expressions are formed with 8502@code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod}, 8503@code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not}, 8504@code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions. 8505 8506@findex get_attr 8507@code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn 8508Lengths},for additional forms). @code{symbol_ref} is a string 8509denoting a C expression that yields an @code{int} when evaluated by the 8510@samp{get_attr_@dots{}} routine. It should normally be a global 8511variable. 8512 8513@findex eq_attr 8514@item (eq_attr @var{name} @var{value}) 8515@var{name} is a string specifying the name of an attribute. 8516 8517@var{value} is a string that is either a valid value for attribute 8518@var{name}, a comma-separated list of values, or @samp{!} followed by a 8519value or list. If @var{value} does not begin with a @samp{!}, this 8520test is true if the value of the @var{name} attribute of the current 8521insn is in the list specified by @var{value}. If @var{value} begins 8522with a @samp{!}, this test is true if the attribute's value is 8523@emph{not} in the specified list. 8524 8525For example, 8526 8527@smallexample 8528(eq_attr "type" "load,store") 8529@end smallexample 8530 8531@noindent 8532is equivalent to 8533 8534@smallexample 8535(ior (eq_attr "type" "load") (eq_attr "type" "store")) 8536@end smallexample 8537 8538If @var{name} specifies an attribute of @samp{alternative}, it refers to the 8539value of the compiler variable @code{which_alternative} 8540(@pxref{Output Statement}) and the values must be small integers. For 8541example, 8542 8543@smallexample 8544(eq_attr "alternative" "2,3") 8545@end smallexample 8546 8547@noindent 8548is equivalent to 8549 8550@smallexample 8551(ior (eq (symbol_ref "which_alternative") (const_int 2)) 8552 (eq (symbol_ref "which_alternative") (const_int 3))) 8553@end smallexample 8554 8555Note that, for most attributes, an @code{eq_attr} test is simplified in cases 8556where the value of the attribute being tested is known for all insns matching 8557a particular pattern. This is by far the most common case. 8558 8559@findex attr_flag 8560@item (attr_flag @var{name}) 8561The value of an @code{attr_flag} expression is true if the flag 8562specified by @var{name} is true for the @code{insn} currently being 8563scheduled. 8564 8565@var{name} is a string specifying one of a fixed set of flags to test. 8566Test the flags @code{forward} and @code{backward} to determine the 8567direction of a conditional branch. 8568 8569This example describes a conditional branch delay slot which 8570can be nullified for forward branches that are taken (annul-true) or 8571for backward branches which are not taken (annul-false). 8572 8573@smallexample 8574(define_delay (eq_attr "type" "cbranch") 8575 [(eq_attr "in_branch_delay" "true") 8576 (and (eq_attr "in_branch_delay" "true") 8577 (attr_flag "forward")) 8578 (and (eq_attr "in_branch_delay" "true") 8579 (attr_flag "backward"))]) 8580@end smallexample 8581 8582The @code{forward} and @code{backward} flags are false if the current 8583@code{insn} being scheduled is not a conditional branch. 8584 8585@code{attr_flag} is only used during delay slot scheduling and has no 8586meaning to other passes of the compiler. 8587 8588@findex attr 8589@item (attr @var{name}) 8590The value of another attribute is returned. This is most useful 8591for numeric attributes, as @code{eq_attr} and @code{attr_flag} 8592produce more efficient code for non-numeric attributes. 8593@end table 8594 8595@end ifset 8596@ifset INTERNALS 8597@node Tagging Insns 8598@subsection Assigning Attribute Values to Insns 8599@cindex tagging insns 8600@cindex assigning attribute values to insns 8601 8602The value assigned to an attribute of an insn is primarily determined by 8603which pattern is matched by that insn (or which @code{define_peephole} 8604generated it). Every @code{define_insn} and @code{define_peephole} can 8605have an optional last argument to specify the values of attributes for 8606matching insns. The value of any attribute not specified in a particular 8607insn is set to the default value for that attribute, as specified in its 8608@code{define_attr}. Extensive use of default values for attributes 8609permits the specification of the values for only one or two attributes 8610in the definition of most insn patterns, as seen in the example in the 8611next section. 8612 8613The optional last argument of @code{define_insn} and 8614@code{define_peephole} is a vector of expressions, each of which defines 8615the value for a single attribute. The most general way of assigning an 8616attribute's value is to use a @code{set} expression whose first operand is an 8617@code{attr} expression giving the name of the attribute being set. The 8618second operand of the @code{set} is an attribute expression 8619(@pxref{Expressions}) giving the value of the attribute. 8620 8621When the attribute value depends on the @samp{alternative} attribute 8622(i.e., which is the applicable alternative in the constraint of the 8623insn), the @code{set_attr_alternative} expression can be used. It 8624allows the specification of a vector of attribute expressions, one for 8625each alternative. 8626 8627@findex set_attr 8628When the generality of arbitrary attribute expressions is not required, 8629the simpler @code{set_attr} expression can be used, which allows 8630specifying a string giving either a single attribute value or a list 8631of attribute values, one for each alternative. 8632 8633The form of each of the above specifications is shown below. In each case, 8634@var{name} is a string specifying the attribute to be set. 8635 8636@table @code 8637@item (set_attr @var{name} @var{value-string}) 8638@var{value-string} is either a string giving the desired attribute value, 8639or a string containing a comma-separated list giving the values for 8640succeeding alternatives. The number of elements must match the number 8641of alternatives in the constraint of the insn pattern. 8642 8643Note that it may be useful to specify @samp{*} for some alternative, in 8644which case the attribute will assume its default value for insns matching 8645that alternative. 8646 8647@findex set_attr_alternative 8648@item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}]) 8649Depending on the alternative of the insn, the value will be one of the 8650specified values. This is a shorthand for using a @code{cond} with 8651tests on the @samp{alternative} attribute. 8652 8653@findex attr 8654@item (set (attr @var{name}) @var{value}) 8655The first operand of this @code{set} must be the special RTL expression 8656@code{attr}, whose sole operand is a string giving the name of the 8657attribute being set. @var{value} is the value of the attribute. 8658@end table 8659 8660The following shows three different ways of representing the same 8661attribute value specification: 8662 8663@smallexample 8664(set_attr "type" "load,store,arith") 8665 8666(set_attr_alternative "type" 8667 [(const_string "load") (const_string "store") 8668 (const_string "arith")]) 8669 8670(set (attr "type") 8671 (cond [(eq_attr "alternative" "1") (const_string "load") 8672 (eq_attr "alternative" "2") (const_string "store")] 8673 (const_string "arith"))) 8674@end smallexample 8675 8676@need 1000 8677@findex define_asm_attributes 8678The @code{define_asm_attributes} expression provides a mechanism to 8679specify the attributes assigned to insns produced from an @code{asm} 8680statement. It has the form: 8681 8682@smallexample 8683(define_asm_attributes [@var{attr-sets}]) 8684@end smallexample 8685 8686@noindent 8687where @var{attr-sets} is specified the same as for both the 8688@code{define_insn} and the @code{define_peephole} expressions. 8689 8690These values will typically be the ``worst case'' attribute values. For 8691example, they might indicate that the condition code will be clobbered. 8692 8693A specification for a @code{length} attribute is handled specially. The 8694way to compute the length of an @code{asm} insn is to multiply the 8695length specified in the expression @code{define_asm_attributes} by the 8696number of machine instructions specified in the @code{asm} statement, 8697determined by counting the number of semicolons and newlines in the 8698string. Therefore, the value of the @code{length} attribute specified 8699in a @code{define_asm_attributes} should be the maximum possible length 8700of a single machine instruction. 8701 8702@end ifset 8703@ifset INTERNALS 8704@node Attr Example 8705@subsection Example of Attribute Specifications 8706@cindex attribute specifications example 8707@cindex attribute specifications 8708 8709The judicious use of defaulting is important in the efficient use of 8710insn attributes. Typically, insns are divided into @dfn{types} and an 8711attribute, customarily called @code{type}, is used to represent this 8712value. This attribute is normally used only to define the default value 8713for other attributes. An example will clarify this usage. 8714 8715Assume we have a RISC machine with a condition code and in which only 8716full-word operations are performed in registers. Let us assume that we 8717can divide all insns into loads, stores, (integer) arithmetic 8718operations, floating point operations, and branches. 8719 8720Here we will concern ourselves with determining the effect of an insn on 8721the condition code and will limit ourselves to the following possible 8722effects: The condition code can be set unpredictably (clobbered), not 8723be changed, be set to agree with the results of the operation, or only 8724changed if the item previously set into the condition code has been 8725modified. 8726 8727Here is part of a sample @file{md} file for such a machine: 8728 8729@smallexample 8730(define_attr "type" "load,store,arith,fp,branch" (const_string "arith")) 8731 8732(define_attr "cc" "clobber,unchanged,set,change0" 8733 (cond [(eq_attr "type" "load") 8734 (const_string "change0") 8735 (eq_attr "type" "store,branch") 8736 (const_string "unchanged") 8737 (eq_attr "type" "arith") 8738 (if_then_else (match_operand:SI 0 "" "") 8739 (const_string "set") 8740 (const_string "clobber"))] 8741 (const_string "clobber"))) 8742 8743(define_insn "" 8744 [(set (match_operand:SI 0 "general_operand" "=r,r,m") 8745 (match_operand:SI 1 "general_operand" "r,m,r"))] 8746 "" 8747 "@@ 8748 move %0,%1 8749 load %0,%1 8750 store %0,%1" 8751 [(set_attr "type" "arith,load,store")]) 8752@end smallexample 8753 8754Note that we assume in the above example that arithmetic operations 8755performed on quantities smaller than a machine word clobber the condition 8756code since they will set the condition code to a value corresponding to the 8757full-word result. 8758 8759@end ifset 8760@ifset INTERNALS 8761@node Insn Lengths 8762@subsection Computing the Length of an Insn 8763@cindex insn lengths, computing 8764@cindex computing the length of an insn 8765 8766For many machines, multiple types of branch instructions are provided, each 8767for different length branch displacements. In most cases, the assembler 8768will choose the correct instruction to use. However, when the assembler 8769cannot do so, GCC can when a special attribute, the @code{length} 8770attribute, is defined. This attribute must be defined to have numeric 8771values by specifying a null string in its @code{define_attr}. 8772 8773In the case of the @code{length} attribute, two additional forms of 8774arithmetic terms are allowed in test expressions: 8775 8776@table @code 8777@cindex @code{match_dup} and attributes 8778@item (match_dup @var{n}) 8779This refers to the address of operand @var{n} of the current insn, which 8780must be a @code{label_ref}. 8781 8782@cindex @code{pc} and attributes 8783@item (pc) 8784For non-branch instructions and backward branch instructions, this refers 8785to the address of the current insn. But for forward branch instructions, 8786this refers to the address of the next insn, because the length of the 8787current insn is to be computed. 8788@end table 8789 8790@cindex @code{addr_vec}, length of 8791@cindex @code{addr_diff_vec}, length of 8792For normal insns, the length will be determined by value of the 8793@code{length} attribute. In the case of @code{addr_vec} and 8794@code{addr_diff_vec} insn patterns, the length is computed as 8795the number of vectors multiplied by the size of each vector. 8796 8797Lengths are measured in addressable storage units (bytes). 8798 8799Note that it is possible to call functions via the @code{symbol_ref} 8800mechanism to compute the length of an insn. However, if you use this 8801mechanism you must provide dummy clauses to express the maximum length 8802without using the function call. You can an example of this in the 8803@code{pa} machine description for the @code{call_symref} pattern. 8804 8805The following macros can be used to refine the length computation: 8806 8807@table @code 8808@findex ADJUST_INSN_LENGTH 8809@item ADJUST_INSN_LENGTH (@var{insn}, @var{length}) 8810If defined, modifies the length assigned to instruction @var{insn} as a 8811function of the context in which it is used. @var{length} is an lvalue 8812that contains the initially computed length of the insn and should be 8813updated with the correct length of the insn. 8814 8815This macro will normally not be required. A case in which it is 8816required is the ROMP@. On this machine, the size of an @code{addr_vec} 8817insn must be increased by two to compensate for the fact that alignment 8818may be required. 8819@end table 8820 8821@findex get_attr_length 8822The routine that returns @code{get_attr_length} (the value of the 8823@code{length} attribute) can be used by the output routine to 8824determine the form of the branch instruction to be written, as the 8825example below illustrates. 8826 8827As an example of the specification of variable-length branches, consider 8828the IBM 360. If we adopt the convention that a register will be set to 8829the starting address of a function, we can jump to labels within 4k of 8830the start using a four-byte instruction. Otherwise, we need a six-byte 8831sequence to load the address from memory and then branch to it. 8832 8833On such a machine, a pattern for a branch instruction might be specified 8834as follows: 8835 8836@smallexample 8837(define_insn "jump" 8838 [(set (pc) 8839 (label_ref (match_operand 0 "" "")))] 8840 "" 8841@{ 8842 return (get_attr_length (insn) == 4 8843 ? "b %l0" : "l r15,=a(%l0); br r15"); 8844@} 8845 [(set (attr "length") 8846 (if_then_else (lt (match_dup 0) (const_int 4096)) 8847 (const_int 4) 8848 (const_int 6)))]) 8849@end smallexample 8850 8851@end ifset 8852@ifset INTERNALS 8853@node Constant Attributes 8854@subsection Constant Attributes 8855@cindex constant attributes 8856 8857A special form of @code{define_attr}, where the expression for the 8858default value is a @code{const} expression, indicates an attribute that 8859is constant for a given run of the compiler. Constant attributes may be 8860used to specify which variety of processor is used. For example, 8861 8862@smallexample 8863(define_attr "cpu" "m88100,m88110,m88000" 8864 (const 8865 (cond [(symbol_ref "TARGET_88100") (const_string "m88100") 8866 (symbol_ref "TARGET_88110") (const_string "m88110")] 8867 (const_string "m88000")))) 8868 8869(define_attr "memory" "fast,slow" 8870 (const 8871 (if_then_else (symbol_ref "TARGET_FAST_MEM") 8872 (const_string "fast") 8873 (const_string "slow")))) 8874@end smallexample 8875 8876The routine generated for constant attributes has no parameters as it 8877does not depend on any particular insn. RTL expressions used to define 8878the value of a constant attribute may use the @code{symbol_ref} form, 8879but may not use either the @code{match_operand} form or @code{eq_attr} 8880forms involving insn attributes. 8881 8882@end ifset 8883@ifset INTERNALS 8884@node Mnemonic Attribute 8885@subsection Mnemonic Attribute 8886@cindex mnemonic attribute 8887 8888The @code{mnemonic} attribute is a string type attribute holding the 8889instruction mnemonic for an insn alternative. The attribute values 8890will automatically be generated by the machine description parser if 8891there is an attribute definition in the md file: 8892 8893@smallexample 8894(define_attr "mnemonic" "unknown" (const_string "unknown")) 8895@end smallexample 8896 8897The default value can be freely chosen as long as it does not collide 8898with any of the instruction mnemonics. This value will be used 8899whenever the machine description parser is not able to determine the 8900mnemonic string. This might be the case for output templates 8901containing more than a single instruction as in 8902@code{"mvcle\t%0,%1,0\;jo\t.-4"}. 8903 8904The @code{mnemonic} attribute set is not generated automatically if the 8905instruction string is generated via C code. 8906 8907An existing @code{mnemonic} attribute set in an insn definition will not 8908be overriden by the md file parser. That way it is possible to 8909manually set the instruction mnemonics for the cases where the md file 8910parser fails to determine it automatically. 8911 8912The @code{mnemonic} attribute is useful for dealing with instruction 8913specific properties in the pipeline description without defining 8914additional insn attributes. 8915 8916@smallexample 8917(define_attr "ooo_expanded" "" 8918 (cond [(eq_attr "mnemonic" "dlr,dsgr,d,dsgf,stam,dsgfr,dlgr") 8919 (const_int 1)] 8920 (const_int 0))) 8921@end smallexample 8922 8923@end ifset 8924@ifset INTERNALS 8925@node Delay Slots 8926@subsection Delay Slot Scheduling 8927@cindex delay slots, defining 8928 8929The insn attribute mechanism can be used to specify the requirements for 8930delay slots, if any, on a target machine. An instruction is said to 8931require a @dfn{delay slot} if some instructions that are physically 8932after the instruction are executed as if they were located before it. 8933Classic examples are branch and call instructions, which often execute 8934the following instruction before the branch or call is performed. 8935 8936On some machines, conditional branch instructions can optionally 8937@dfn{annul} instructions in the delay slot. This means that the 8938instruction will not be executed for certain branch outcomes. Both 8939instructions that annul if the branch is true and instructions that 8940annul if the branch is false are supported. 8941 8942Delay slot scheduling differs from instruction scheduling in that 8943determining whether an instruction needs a delay slot is dependent only 8944on the type of instruction being generated, not on data flow between the 8945instructions. See the next section for a discussion of data-dependent 8946instruction scheduling. 8947 8948@findex define_delay 8949The requirement of an insn needing one or more delay slots is indicated 8950via the @code{define_delay} expression. It has the following form: 8951 8952@smallexample 8953(define_delay @var{test} 8954 [@var{delay-1} @var{annul-true-1} @var{annul-false-1} 8955 @var{delay-2} @var{annul-true-2} @var{annul-false-2} 8956 @dots{}]) 8957@end smallexample 8958 8959@var{test} is an attribute test that indicates whether this 8960@code{define_delay} applies to a particular insn. If so, the number of 8961required delay slots is determined by the length of the vector specified 8962as the second argument. An insn placed in delay slot @var{n} must 8963satisfy attribute test @var{delay-n}. @var{annul-true-n} is an 8964attribute test that specifies which insns may be annulled if the branch 8965is true. Similarly, @var{annul-false-n} specifies which insns in the 8966delay slot may be annulled if the branch is false. If annulling is not 8967supported for that delay slot, @code{(nil)} should be coded. 8968 8969For example, in the common case where branch and call insns require 8970a single delay slot, which may contain any insn other than a branch or 8971call, the following would be placed in the @file{md} file: 8972 8973@smallexample 8974(define_delay (eq_attr "type" "branch,call") 8975 [(eq_attr "type" "!branch,call") (nil) (nil)]) 8976@end smallexample 8977 8978Multiple @code{define_delay} expressions may be specified. In this 8979case, each such expression specifies different delay slot requirements 8980and there must be no insn for which tests in two @code{define_delay} 8981expressions are both true. 8982 8983For example, if we have a machine that requires one delay slot for branches 8984but two for calls, no delay slot can contain a branch or call insn, 8985and any valid insn in the delay slot for the branch can be annulled if the 8986branch is true, we might represent this as follows: 8987 8988@smallexample 8989(define_delay (eq_attr "type" "branch") 8990 [(eq_attr "type" "!branch,call") 8991 (eq_attr "type" "!branch,call") 8992 (nil)]) 8993 8994(define_delay (eq_attr "type" "call") 8995 [(eq_attr "type" "!branch,call") (nil) (nil) 8996 (eq_attr "type" "!branch,call") (nil) (nil)]) 8997@end smallexample 8998@c the above is *still* too long. --mew 4feb93 8999 9000@end ifset 9001@ifset INTERNALS 9002@node Processor pipeline description 9003@subsection Specifying processor pipeline description 9004@cindex processor pipeline description 9005@cindex processor functional units 9006@cindex instruction latency time 9007@cindex interlock delays 9008@cindex data dependence delays 9009@cindex reservation delays 9010@cindex pipeline hazard recognizer 9011@cindex automaton based pipeline description 9012@cindex regular expressions 9013@cindex deterministic finite state automaton 9014@cindex automaton based scheduler 9015@cindex RISC 9016@cindex VLIW 9017 9018To achieve better performance, most modern processors 9019(super-pipelined, superscalar @acronym{RISC}, and @acronym{VLIW} 9020processors) have many @dfn{functional units} on which several 9021instructions can be executed simultaneously. An instruction starts 9022execution if its issue conditions are satisfied. If not, the 9023instruction is stalled until its conditions are satisfied. Such 9024@dfn{interlock (pipeline) delay} causes interruption of the fetching 9025of successor instructions (or demands nop instructions, e.g.@: for some 9026MIPS processors). 9027 9028There are two major kinds of interlock delays in modern processors. 9029The first one is a data dependence delay determining @dfn{instruction 9030latency time}. The instruction execution is not started until all 9031source data have been evaluated by prior instructions (there are more 9032complex cases when the instruction execution starts even when the data 9033are not available but will be ready in given time after the 9034instruction execution start). Taking the data dependence delays into 9035account is simple. The data dependence (true, output, and 9036anti-dependence) delay between two instructions is given by a 9037constant. In most cases this approach is adequate. The second kind 9038of interlock delays is a reservation delay. The reservation delay 9039means that two instructions under execution will be in need of shared 9040processors resources, i.e.@: buses, internal registers, and/or 9041functional units, which are reserved for some time. Taking this kind 9042of delay into account is complex especially for modern @acronym{RISC} 9043processors. 9044 9045The task of exploiting more processor parallelism is solved by an 9046instruction scheduler. For a better solution to this problem, the 9047instruction scheduler has to have an adequate description of the 9048processor parallelism (or @dfn{pipeline description}). GCC 9049machine descriptions describe processor parallelism and functional 9050unit reservations for groups of instructions with the aid of 9051@dfn{regular expressions}. 9052 9053The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to 9054figure out the possibility of the instruction issue by the processor 9055on a given simulated processor cycle. The pipeline hazard recognizer is 9056automatically generated from the processor pipeline description. The 9057pipeline hazard recognizer generated from the machine description 9058is based on a deterministic finite state automaton (@acronym{DFA}): 9059the instruction issue is possible if there is a transition from one 9060automaton state to another one. This algorithm is very fast, and 9061furthermore, its speed is not dependent on processor 9062complexity@footnote{However, the size of the automaton depends on 9063processor complexity. To limit this effect, machine descriptions 9064can split orthogonal parts of the machine description among several 9065automata: but then, since each of these must be stepped independently, 9066this does cause a small decrease in the algorithm's performance.}. 9067 9068@cindex automaton based pipeline description 9069The rest of this section describes the directives that constitute 9070an automaton-based processor pipeline description. The order of 9071these constructions within the machine description file is not 9072important. 9073 9074@findex define_automaton 9075@cindex pipeline hazard recognizer 9076The following optional construction describes names of automata 9077generated and used for the pipeline hazards recognition. Sometimes 9078the generated finite state automaton used by the pipeline hazard 9079recognizer is large. If we use more than one automaton and bind functional 9080units to the automata, the total size of the automata is usually 9081less than the size of the single automaton. If there is no one such 9082construction, only one finite state automaton is generated. 9083 9084@smallexample 9085(define_automaton @var{automata-names}) 9086@end smallexample 9087 9088@var{automata-names} is a string giving names of the automata. The 9089names are separated by commas. All the automata should have unique names. 9090The automaton name is used in the constructions @code{define_cpu_unit} and 9091@code{define_query_cpu_unit}. 9092 9093@findex define_cpu_unit 9094@cindex processor functional units 9095Each processor functional unit used in the description of instruction 9096reservations should be described by the following construction. 9097 9098@smallexample 9099(define_cpu_unit @var{unit-names} [@var{automaton-name}]) 9100@end smallexample 9101 9102@var{unit-names} is a string giving the names of the functional units 9103separated by commas. Don't use name @samp{nothing}, it is reserved 9104for other goals. 9105 9106@var{automaton-name} is a string giving the name of the automaton with 9107which the unit is bound. The automaton should be described in 9108construction @code{define_automaton}. You should give 9109@dfn{automaton-name}, if there is a defined automaton. 9110 9111The assignment of units to automata are constrained by the uses of the 9112units in insn reservations. The most important constraint is: if a 9113unit reservation is present on a particular cycle of an alternative 9114for an insn reservation, then some unit from the same automaton must 9115be present on the same cycle for the other alternatives of the insn 9116reservation. The rest of the constraints are mentioned in the 9117description of the subsequent constructions. 9118 9119@findex define_query_cpu_unit 9120@cindex querying function unit reservations 9121The following construction describes CPU functional units analogously 9122to @code{define_cpu_unit}. The reservation of such units can be 9123queried for an automaton state. The instruction scheduler never 9124queries reservation of functional units for given automaton state. So 9125as a rule, you don't need this construction. This construction could 9126be used for future code generation goals (e.g.@: to generate 9127@acronym{VLIW} insn templates). 9128 9129@smallexample 9130(define_query_cpu_unit @var{unit-names} [@var{automaton-name}]) 9131@end smallexample 9132 9133@var{unit-names} is a string giving names of the functional units 9134separated by commas. 9135 9136@var{automaton-name} is a string giving the name of the automaton with 9137which the unit is bound. 9138 9139@findex define_insn_reservation 9140@cindex instruction latency time 9141@cindex regular expressions 9142@cindex data bypass 9143The following construction is the major one to describe pipeline 9144characteristics of an instruction. 9145 9146@smallexample 9147(define_insn_reservation @var{insn-name} @var{default_latency} 9148 @var{condition} @var{regexp}) 9149@end smallexample 9150 9151@var{default_latency} is a number giving latency time of the 9152instruction. There is an important difference between the old 9153description and the automaton based pipeline description. The latency 9154time is used for all dependencies when we use the old description. In 9155the automaton based pipeline description, the given latency time is only 9156used for true dependencies. The cost of anti-dependencies is always 9157zero and the cost of output dependencies is the difference between 9158latency times of the producing and consuming insns (if the difference 9159is negative, the cost is considered to be zero). You can always 9160change the default costs for any description by using the target hook 9161@code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}). 9162 9163@var{insn-name} is a string giving the internal name of the insn. The 9164internal names are used in constructions @code{define_bypass} and in 9165the automaton description file generated for debugging. The internal 9166name has nothing in common with the names in @code{define_insn}. It is a 9167good practice to use insn classes described in the processor manual. 9168 9169@var{condition} defines what RTL insns are described by this 9170construction. You should remember that you will be in trouble if 9171@var{condition} for two or more different 9172@code{define_insn_reservation} constructions is TRUE for an insn. In 9173this case what reservation will be used for the insn is not defined. 9174Such cases are not checked during generation of the pipeline hazards 9175recognizer because in general recognizing that two conditions may have 9176the same value is quite difficult (especially if the conditions 9177contain @code{symbol_ref}). It is also not checked during the 9178pipeline hazard recognizer work because it would slow down the 9179recognizer considerably. 9180 9181@var{regexp} is a string describing the reservation of the cpu's functional 9182units by the instruction. The reservations are described by a regular 9183expression according to the following syntax: 9184 9185@smallexample 9186 regexp = regexp "," oneof 9187 | oneof 9188 9189 oneof = oneof "|" allof 9190 | allof 9191 9192 allof = allof "+" repeat 9193 | repeat 9194 9195 repeat = element "*" number 9196 | element 9197 9198 element = cpu_function_unit_name 9199 | reservation_name 9200 | result_name 9201 | "nothing" 9202 | "(" regexp ")" 9203@end smallexample 9204 9205@itemize @bullet 9206@item 9207@samp{,} is used for describing the start of the next cycle in 9208the reservation. 9209 9210@item 9211@samp{|} is used for describing a reservation described by the first 9212regular expression @strong{or} a reservation described by the second 9213regular expression @strong{or} etc. 9214 9215@item 9216@samp{+} is used for describing a reservation described by the first 9217regular expression @strong{and} a reservation described by the 9218second regular expression @strong{and} etc. 9219 9220@item 9221@samp{*} is used for convenience and simply means a sequence in which 9222the regular expression are repeated @var{number} times with cycle 9223advancing (see @samp{,}). 9224 9225@item 9226@samp{cpu_function_unit_name} denotes reservation of the named 9227functional unit. 9228 9229@item 9230@samp{reservation_name} --- see description of construction 9231@samp{define_reservation}. 9232 9233@item 9234@samp{nothing} denotes no unit reservations. 9235@end itemize 9236 9237@findex define_reservation 9238Sometimes unit reservations for different insns contain common parts. 9239In such case, you can simplify the pipeline description by describing 9240the common part by the following construction 9241 9242@smallexample 9243(define_reservation @var{reservation-name} @var{regexp}) 9244@end smallexample 9245 9246@var{reservation-name} is a string giving name of @var{regexp}. 9247Functional unit names and reservation names are in the same name 9248space. So the reservation names should be different from the 9249functional unit names and can not be the reserved name @samp{nothing}. 9250 9251@findex define_bypass 9252@cindex instruction latency time 9253@cindex data bypass 9254The following construction is used to describe exceptions in the 9255latency time for given instruction pair. This is so called bypasses. 9256 9257@smallexample 9258(define_bypass @var{number} @var{out_insn_names} @var{in_insn_names} 9259 [@var{guard}]) 9260@end smallexample 9261 9262@var{number} defines when the result generated by the instructions 9263given in string @var{out_insn_names} will be ready for the 9264instructions given in string @var{in_insn_names}. Each of these 9265strings is a comma-separated list of filename-style globs and 9266they refer to the names of @code{define_insn_reservation}s. 9267For example: 9268@smallexample 9269(define_bypass 1 "cpu1_load_*, cpu1_store_*" "cpu1_load_*") 9270@end smallexample 9271defines a bypass between instructions that start with 9272@samp{cpu1_load_} or @samp{cpu1_store_} and those that start with 9273@samp{cpu1_load_}. 9274 9275@var{guard} is an optional string giving the name of a C function which 9276defines an additional guard for the bypass. The function will get the 9277two insns as parameters. If the function returns zero the bypass will 9278be ignored for this case. The additional guard is necessary to 9279recognize complicated bypasses, e.g.@: when the consumer is only an address 9280of insn @samp{store} (not a stored value). 9281 9282If there are more one bypass with the same output and input insns, the 9283chosen bypass is the first bypass with a guard in description whose 9284guard function returns nonzero. If there is no such bypass, then 9285bypass without the guard function is chosen. 9286 9287@findex exclusion_set 9288@findex presence_set 9289@findex final_presence_set 9290@findex absence_set 9291@findex final_absence_set 9292@cindex VLIW 9293@cindex RISC 9294The following five constructions are usually used to describe 9295@acronym{VLIW} processors, or more precisely, to describe a placement 9296of small instructions into @acronym{VLIW} instruction slots. They 9297can be used for @acronym{RISC} processors, too. 9298 9299@smallexample 9300(exclusion_set @var{unit-names} @var{unit-names}) 9301(presence_set @var{unit-names} @var{patterns}) 9302(final_presence_set @var{unit-names} @var{patterns}) 9303(absence_set @var{unit-names} @var{patterns}) 9304(final_absence_set @var{unit-names} @var{patterns}) 9305@end smallexample 9306 9307@var{unit-names} is a string giving names of functional units 9308separated by commas. 9309 9310@var{patterns} is a string giving patterns of functional units 9311separated by comma. Currently pattern is one unit or units 9312separated by white-spaces. 9313 9314The first construction (@samp{exclusion_set}) means that each 9315functional unit in the first string can not be reserved simultaneously 9316with a unit whose name is in the second string and vice versa. For 9317example, the construction is useful for describing processors 9318(e.g.@: some SPARC processors) with a fully pipelined floating point 9319functional unit which can execute simultaneously only single floating 9320point insns or only double floating point insns. 9321 9322The second construction (@samp{presence_set}) means that each 9323functional unit in the first string can not be reserved unless at 9324least one of pattern of units whose names are in the second string is 9325reserved. This is an asymmetric relation. For example, it is useful 9326for description that @acronym{VLIW} @samp{slot1} is reserved after 9327@samp{slot0} reservation. We could describe it by the following 9328construction 9329 9330@smallexample 9331(presence_set "slot1" "slot0") 9332@end smallexample 9333 9334Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0} 9335reservation. In this case we could write 9336 9337@smallexample 9338(presence_set "slot1" "slot0 b0") 9339@end smallexample 9340 9341The third construction (@samp{final_presence_set}) is analogous to 9342@samp{presence_set}. The difference between them is when checking is 9343done. When an instruction is issued in given automaton state 9344reflecting all current and planned unit reservations, the automaton 9345state is changed. The first state is a source state, the second one 9346is a result state. Checking for @samp{presence_set} is done on the 9347source state reservation, checking for @samp{final_presence_set} is 9348done on the result reservation. This construction is useful to 9349describe a reservation which is actually two subsequent reservations. 9350For example, if we use 9351 9352@smallexample 9353(presence_set "slot1" "slot0") 9354@end smallexample 9355 9356the following insn will be never issued (because @samp{slot1} requires 9357@samp{slot0} which is absent in the source state). 9358 9359@smallexample 9360(define_reservation "insn_and_nop" "slot0 + slot1") 9361@end smallexample 9362 9363but it can be issued if we use analogous @samp{final_presence_set}. 9364 9365The forth construction (@samp{absence_set}) means that each functional 9366unit in the first string can be reserved only if each pattern of units 9367whose names are in the second string is not reserved. This is an 9368asymmetric relation (actually @samp{exclusion_set} is analogous to 9369this one but it is symmetric). For example it might be useful in a 9370@acronym{VLIW} description to say that @samp{slot0} cannot be reserved 9371after either @samp{slot1} or @samp{slot2} have been reserved. This 9372can be described as: 9373 9374@smallexample 9375(absence_set "slot0" "slot1, slot2") 9376@end smallexample 9377 9378Or @samp{slot2} can not be reserved if @samp{slot0} and unit @samp{b0} 9379are reserved or @samp{slot1} and unit @samp{b1} are reserved. In 9380this case we could write 9381 9382@smallexample 9383(absence_set "slot2" "slot0 b0, slot1 b1") 9384@end smallexample 9385 9386All functional units mentioned in a set should belong to the same 9387automaton. 9388 9389The last construction (@samp{final_absence_set}) is analogous to 9390@samp{absence_set} but checking is done on the result (state) 9391reservation. See comments for @samp{final_presence_set}. 9392 9393@findex automata_option 9394@cindex deterministic finite state automaton 9395@cindex nondeterministic finite state automaton 9396@cindex finite state automaton minimization 9397You can control the generator of the pipeline hazard recognizer with 9398the following construction. 9399 9400@smallexample 9401(automata_option @var{options}) 9402@end smallexample 9403 9404@var{options} is a string giving options which affect the generated 9405code. Currently there are the following options: 9406 9407@itemize @bullet 9408@item 9409@dfn{no-minimization} makes no minimization of the automaton. This is 9410only worth to do when we are debugging the description and need to 9411look more accurately at reservations of states. 9412 9413@item 9414@dfn{time} means printing time statistics about the generation of 9415automata. 9416 9417@item 9418@dfn{stats} means printing statistics about the generated automata 9419such as the number of DFA states, NDFA states and arcs. 9420 9421@item 9422@dfn{v} means a generation of the file describing the result automata. 9423The file has suffix @samp{.dfa} and can be used for the description 9424verification and debugging. 9425 9426@item 9427@dfn{w} means a generation of warning instead of error for 9428non-critical errors. 9429 9430@item 9431@dfn{no-comb-vect} prevents the automaton generator from generating 9432two data structures and comparing them for space efficiency. Using 9433a comb vector to represent transitions may be better, but it can be 9434very expensive to construct. This option is useful if the build 9435process spends an unacceptably long time in genautomata. 9436 9437@item 9438@dfn{ndfa} makes nondeterministic finite state automata. This affects 9439the treatment of operator @samp{|} in the regular expressions. The 9440usual treatment of the operator is to try the first alternative and, 9441if the reservation is not possible, the second alternative. The 9442nondeterministic treatment means trying all alternatives, some of them 9443may be rejected by reservations in the subsequent insns. 9444 9445@item 9446@dfn{collapse-ndfa} modifies the behavior of the generator when 9447producing an automaton. An additional state transition to collapse a 9448nondeterministic @acronym{NDFA} state to a deterministic @acronym{DFA} 9449state is generated. It can be triggered by passing @code{const0_rtx} to 9450state_transition. In such an automaton, cycle advance transitions are 9451available only for these collapsed states. This option is useful for 9452ports that want to use the @code{ndfa} option, but also want to use 9453@code{define_query_cpu_unit} to assign units to insns issued in a cycle. 9454 9455@item 9456@dfn{progress} means output of a progress bar showing how many states 9457were generated so far for automaton being processed. This is useful 9458during debugging a @acronym{DFA} description. If you see too many 9459generated states, you could interrupt the generator of the pipeline 9460hazard recognizer and try to figure out a reason for generation of the 9461huge automaton. 9462@end itemize 9463 9464As an example, consider a superscalar @acronym{RISC} machine which can 9465issue three insns (two integer insns and one floating point insn) on 9466the cycle but can finish only two insns. To describe this, we define 9467the following functional units. 9468 9469@smallexample 9470(define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline") 9471(define_cpu_unit "port0, port1") 9472@end smallexample 9473 9474All simple integer insns can be executed in any integer pipeline and 9475their result is ready in two cycles. The simple integer insns are 9476issued into the first pipeline unless it is reserved, otherwise they 9477are issued into the second pipeline. Integer division and 9478multiplication insns can be executed only in the second integer 9479pipeline and their results are ready correspondingly in 8 and 4 9480cycles. The integer division is not pipelined, i.e.@: the subsequent 9481integer division insn can not be issued until the current division 9482insn finished. Floating point insns are fully pipelined and their 9483results are ready in 3 cycles. Where the result of a floating point 9484insn is used by an integer insn, an additional delay of one cycle is 9485incurred. To describe all of this we could specify 9486 9487@smallexample 9488(define_cpu_unit "div") 9489 9490(define_insn_reservation "simple" 2 (eq_attr "type" "int") 9491 "(i0_pipeline | i1_pipeline), (port0 | port1)") 9492 9493(define_insn_reservation "mult" 4 (eq_attr "type" "mult") 9494 "i1_pipeline, nothing*2, (port0 | port1)") 9495 9496(define_insn_reservation "div" 8 (eq_attr "type" "div") 9497 "i1_pipeline, div*7, div + (port0 | port1)") 9498 9499(define_insn_reservation "float" 3 (eq_attr "type" "float") 9500 "f_pipeline, nothing, (port0 | port1)) 9501 9502(define_bypass 4 "float" "simple,mult,div") 9503@end smallexample 9504 9505To simplify the description we could describe the following reservation 9506 9507@smallexample 9508(define_reservation "finish" "port0|port1") 9509@end smallexample 9510 9511and use it in all @code{define_insn_reservation} as in the following 9512construction 9513 9514@smallexample 9515(define_insn_reservation "simple" 2 (eq_attr "type" "int") 9516 "(i0_pipeline | i1_pipeline), finish") 9517@end smallexample 9518 9519 9520@end ifset 9521@ifset INTERNALS 9522@node Conditional Execution 9523@section Conditional Execution 9524@cindex conditional execution 9525@cindex predication 9526 9527A number of architectures provide for some form of conditional 9528execution, or predication. The hallmark of this feature is the 9529ability to nullify most of the instructions in the instruction set. 9530When the instruction set is large and not entirely symmetric, it 9531can be quite tedious to describe these forms directly in the 9532@file{.md} file. An alternative is the @code{define_cond_exec} template. 9533 9534@findex define_cond_exec 9535@smallexample 9536(define_cond_exec 9537 [@var{predicate-pattern}] 9538 "@var{condition}" 9539 "@var{output-template}" 9540 "@var{optional-insn-attribues}") 9541@end smallexample 9542 9543@var{predicate-pattern} is the condition that must be true for the 9544insn to be executed at runtime and should match a relational operator. 9545One can use @code{match_operator} to match several relational operators 9546at once. Any @code{match_operand} operands must have no more than one 9547alternative. 9548 9549@var{condition} is a C expression that must be true for the generated 9550pattern to match. 9551 9552@findex current_insn_predicate 9553@var{output-template} is a string similar to the @code{define_insn} 9554output template (@pxref{Output Template}), except that the @samp{*} 9555and @samp{@@} special cases do not apply. This is only useful if the 9556assembly text for the predicate is a simple prefix to the main insn. 9557In order to handle the general case, there is a global variable 9558@code{current_insn_predicate} that will contain the entire predicate 9559if the current insn is predicated, and will otherwise be @code{NULL}. 9560 9561@var{optional-insn-attributes} is an optional vector of attributes that gets 9562appended to the insn attributes of the produced cond_exec rtx. It can 9563be used to add some distinguishing attribute to cond_exec rtxs produced 9564that way. An example usage would be to use this attribute in conjunction 9565with attributes on the main pattern to disable particular alternatives under 9566certain conditions. 9567 9568When @code{define_cond_exec} is used, an implicit reference to 9569the @code{predicable} instruction attribute is made. 9570@xref{Insn Attributes}. This attribute must be a boolean (i.e.@: have 9571exactly two elements in its @var{list-of-values}), with the possible 9572values being @code{no} and @code{yes}. The default and all uses in 9573the insns must be a simple constant, not a complex expressions. It 9574may, however, depend on the alternative, by using a comma-separated 9575list of values. If that is the case, the port should also define an 9576@code{enabled} attribute (@pxref{Disable Insn Alternatives}), which 9577should also allow only @code{no} and @code{yes} as its values. 9578 9579For each @code{define_insn} for which the @code{predicable} 9580attribute is true, a new @code{define_insn} pattern will be 9581generated that matches a predicated version of the instruction. 9582For example, 9583 9584@smallexample 9585(define_insn "addsi" 9586 [(set (match_operand:SI 0 "register_operand" "r") 9587 (plus:SI (match_operand:SI 1 "register_operand" "r") 9588 (match_operand:SI 2 "register_operand" "r")))] 9589 "@var{test1}" 9590 "add %2,%1,%0") 9591 9592(define_cond_exec 9593 [(ne (match_operand:CC 0 "register_operand" "c") 9594 (const_int 0))] 9595 "@var{test2}" 9596 "(%0)") 9597@end smallexample 9598 9599@noindent 9600generates a new pattern 9601 9602@smallexample 9603(define_insn "" 9604 [(cond_exec 9605 (ne (match_operand:CC 3 "register_operand" "c") (const_int 0)) 9606 (set (match_operand:SI 0 "register_operand" "r") 9607 (plus:SI (match_operand:SI 1 "register_operand" "r") 9608 (match_operand:SI 2 "register_operand" "r"))))] 9609 "(@var{test2}) && (@var{test1})" 9610 "(%3) add %2,%1,%0") 9611@end smallexample 9612 9613@end ifset 9614@ifset INTERNALS 9615@node Define Subst 9616@section RTL Templates Transformations 9617@cindex define_subst 9618 9619For some hardware architectures there are common cases when the RTL 9620templates for the instructions can be derived from the other RTL 9621templates using simple transformations. E.g., @file{i386.md} contains 9622an RTL template for the ordinary @code{sub} instruction--- 9623@code{*subsi_1}, and for the @code{sub} instruction with subsequent 9624zero-extension---@code{*subsi_1_zext}. Such cases can be easily 9625implemented by a single meta-template capable of generating a modified 9626case based on the initial one: 9627 9628@findex define_subst 9629@smallexample 9630(define_subst "@var{name}" 9631 [@var{input-template}] 9632 "@var{condition}" 9633 [@var{output-template}]) 9634@end smallexample 9635@var{input-template} is a pattern describing the source RTL template, 9636which will be transformed. 9637 9638@var{condition} is a C expression that is conjunct with the condition 9639from the input-template to generate a condition to be used in the 9640output-template. 9641 9642@var{output-template} is a pattern that will be used in the resulting 9643template. 9644 9645@code{define_subst} mechanism is tightly coupled with the notion of the 9646subst attribute (@pxref{Subst Iterators}). The use of 9647@code{define_subst} is triggered by a reference to a subst attribute in 9648the transforming RTL template. This reference initiates duplication of 9649the source RTL template and substitution of the attributes with their 9650values. The source RTL template is left unchanged, while the copy is 9651transformed by @code{define_subst}. This transformation can fail in the 9652case when the source RTL template is not matched against the 9653input-template of the @code{define_subst}. In such case the copy is 9654deleted. 9655 9656@code{define_subst} can be used only in @code{define_insn} and 9657@code{define_expand}, it cannot be used in other expressions (e.g. in 9658@code{define_insn_and_split}). 9659 9660@menu 9661* Define Subst Example:: Example of @code{define_subst} work. 9662* Define Subst Pattern Matching:: Process of template comparison. 9663* Define Subst Output Template:: Generation of output template. 9664@end menu 9665 9666@node Define Subst Example 9667@subsection @code{define_subst} Example 9668@cindex define_subst 9669 9670To illustrate how @code{define_subst} works, let us examine a simple 9671template transformation. 9672 9673Suppose there are two kinds of instructions: one that touches flags and 9674the other that does not. The instructions of the second type could be 9675generated with the following @code{define_subst}: 9676 9677@smallexample 9678(define_subst "add_clobber_subst" 9679 [(set (match_operand:SI 0 "" "") 9680 (match_operand:SI 1 "" ""))] 9681 "" 9682 [(set (match_dup 0) 9683 (match_dup 1)) 9684 (clobber (reg:CC FLAGS_REG))] 9685@end smallexample 9686 9687This @code{define_subst} can be applied to any RTL pattern containing 9688@code{set} of mode SI and generates a copy with clobber when it is 9689applied. 9690 9691Assume there is an RTL template for a @code{max} instruction to be used 9692in @code{define_subst} mentioned above: 9693 9694@smallexample 9695(define_insn "maxsi" 9696 [(set (match_operand:SI 0 "register_operand" "=r") 9697 (max:SI 9698 (match_operand:SI 1 "register_operand" "r") 9699 (match_operand:SI 2 "register_operand" "r")))] 9700 "" 9701 "max\t@{%2, %1, %0|%0, %1, %2@}" 9702 [@dots{}]) 9703@end smallexample 9704 9705To mark the RTL template for @code{define_subst} application, 9706subst-attributes are used. They should be declared in advance: 9707 9708@smallexample 9709(define_subst_attr "add_clobber_name" "add_clobber_subst" "_noclobber" "_clobber") 9710@end smallexample 9711 9712Here @samp{add_clobber_name} is the attribute name, 9713@samp{add_clobber_subst} is the name of the corresponding 9714@code{define_subst}, the third argument (@samp{_noclobber}) is the 9715attribute value that would be substituted into the unchanged version of 9716the source RTL template, and the last argument (@samp{_clobber}) is the 9717value that would be substituted into the second, transformed, 9718version of the RTL template. 9719 9720Once the subst-attribute has been defined, it should be used in RTL 9721templates which need to be processed by the @code{define_subst}. So, 9722the original RTL template should be changed: 9723 9724@smallexample 9725(define_insn "maxsi<add_clobber_name>" 9726 [(set (match_operand:SI 0 "register_operand" "=r") 9727 (max:SI 9728 (match_operand:SI 1 "register_operand" "r") 9729 (match_operand:SI 2 "register_operand" "r")))] 9730 "" 9731 "max\t@{%2, %1, %0|%0, %1, %2@}" 9732 [@dots{}]) 9733@end smallexample 9734 9735The result of the @code{define_subst} usage would look like the following: 9736 9737@smallexample 9738(define_insn "maxsi_noclobber" 9739 [(set (match_operand:SI 0 "register_operand" "=r") 9740 (max:SI 9741 (match_operand:SI 1 "register_operand" "r") 9742 (match_operand:SI 2 "register_operand" "r")))] 9743 "" 9744 "max\t@{%2, %1, %0|%0, %1, %2@}" 9745 [@dots{}]) 9746(define_insn "maxsi_clobber" 9747 [(set (match_operand:SI 0 "register_operand" "=r") 9748 (max:SI 9749 (match_operand:SI 1 "register_operand" "r") 9750 (match_operand:SI 2 "register_operand" "r"))) 9751 (clobber (reg:CC FLAGS_REG))] 9752 "" 9753 "max\t@{%2, %1, %0|%0, %1, %2@}" 9754 [@dots{}]) 9755@end smallexample 9756 9757@node Define Subst Pattern Matching 9758@subsection Pattern Matching in @code{define_subst} 9759@cindex define_subst 9760 9761All expressions, allowed in @code{define_insn} or @code{define_expand}, 9762are allowed in the input-template of @code{define_subst}, except 9763@code{match_par_dup}, @code{match_scratch}, @code{match_parallel}. The 9764meanings of expressions in the input-template were changed: 9765 9766@code{match_operand} matches any expression (possibly, a subtree in 9767RTL-template), if modes of the @code{match_operand} and this expression 9768are the same, or mode of the @code{match_operand} is @code{VOIDmode}, or 9769this expression is @code{match_dup}, @code{match_op_dup}. If the 9770expression is @code{match_operand} too, and predicate of 9771@code{match_operand} from the input pattern is not empty, then the 9772predicates are compared. That can be used for more accurate filtering 9773of accepted RTL-templates. 9774 9775@code{match_operator} matches common operators (like @code{plus}, 9776@code{minus}), @code{unspec}, @code{unspec_volatile} operators and 9777@code{match_operator}s from the original pattern if the modes match and 9778@code{match_operator} from the input pattern has the same number of 9779operands as the operator from the original pattern. 9780 9781@node Define Subst Output Template 9782@subsection Generation of output template in @code{define_subst} 9783@cindex define_subst 9784 9785If all necessary checks for @code{define_subst} application pass, a new 9786RTL-pattern, based on the output-template, is created to replace the old 9787template. Like in input-patterns, meanings of some RTL expressions are 9788changed when they are used in output-patterns of a @code{define_subst}. 9789Thus, @code{match_dup} is used for copying the whole expression from the 9790original pattern, which matched corresponding @code{match_operand} from 9791the input pattern. 9792 9793@code{match_dup N} is used in the output template to be replaced with 9794the expression from the original pattern, which matched 9795@code{match_operand N} from the input pattern. As a consequence, 9796@code{match_dup} cannot be used to point to @code{match_operand}s from 9797the output pattern, it should always refer to a @code{match_operand} 9798from the input pattern. 9799 9800In the output template one can refer to the expressions from the 9801original pattern and create new ones. For instance, some operands could 9802be added by means of standard @code{match_operand}. 9803 9804After replacing @code{match_dup} with some RTL-subtree from the original 9805pattern, it could happen that several @code{match_operand}s in the 9806output pattern have the same indexes. It is unknown, how many and what 9807indexes would be used in the expression which would replace 9808@code{match_dup}, so such conflicts in indexes are inevitable. To 9809overcome this issue, @code{match_operands} and @code{match_operators}, 9810which were introduced into the output pattern, are renumerated when all 9811@code{match_dup}s are replaced. 9812 9813Number of alternatives in @code{match_operand}s introduced into the 9814output template @code{M} could differ from the number of alternatives in 9815the original pattern @code{N}, so in the resultant pattern there would 9816be @code{N*M} alternatives. Thus, constraints from the original pattern 9817would be duplicated @code{N} times, constraints from the output pattern 9818would be duplicated @code{M} times, producing all possible combinations. 9819@end ifset 9820 9821@ifset INTERNALS 9822@node Constant Definitions 9823@section Constant Definitions 9824@cindex constant definitions 9825@findex define_constants 9826 9827Using literal constants inside instruction patterns reduces legibility and 9828can be a maintenance problem. 9829 9830To overcome this problem, you may use the @code{define_constants} 9831expression. It contains a vector of name-value pairs. From that 9832point on, wherever any of the names appears in the MD file, it is as 9833if the corresponding value had been written instead. You may use 9834@code{define_constants} multiple times; each appearance adds more 9835constants to the table. It is an error to redefine a constant with 9836a different value. 9837 9838To come back to the a29k load multiple example, instead of 9839 9840@smallexample 9841(define_insn "" 9842 [(match_parallel 0 "load_multiple_operation" 9843 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 9844 (match_operand:SI 2 "memory_operand" "m")) 9845 (use (reg:SI 179)) 9846 (clobber (reg:SI 179))])] 9847 "" 9848 "loadm 0,0,%1,%2") 9849@end smallexample 9850 9851You could write: 9852 9853@smallexample 9854(define_constants [ 9855 (R_BP 177) 9856 (R_FC 178) 9857 (R_CR 179) 9858 (R_Q 180) 9859]) 9860 9861(define_insn "" 9862 [(match_parallel 0 "load_multiple_operation" 9863 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 9864 (match_operand:SI 2 "memory_operand" "m")) 9865 (use (reg:SI R_CR)) 9866 (clobber (reg:SI R_CR))])] 9867 "" 9868 "loadm 0,0,%1,%2") 9869@end smallexample 9870 9871The constants that are defined with a define_constant are also output 9872in the insn-codes.h header file as #defines. 9873 9874@cindex enumerations 9875@findex define_c_enum 9876You can also use the machine description file to define enumerations. 9877Like the constants defined by @code{define_constant}, these enumerations 9878are visible to both the machine description file and the main C code. 9879 9880The syntax is as follows: 9881 9882@smallexample 9883(define_c_enum "@var{name}" [ 9884 @var{value0} 9885 @var{value1} 9886 @dots{} 9887 @var{valuen} 9888]) 9889@end smallexample 9890 9891This definition causes the equivalent of the following C code to appear 9892in @file{insn-constants.h}: 9893 9894@smallexample 9895enum @var{name} @{ 9896 @var{value0} = 0, 9897 @var{value1} = 1, 9898 @dots{} 9899 @var{valuen} = @var{n} 9900@}; 9901#define NUM_@var{cname}_VALUES (@var{n} + 1) 9902@end smallexample 9903 9904where @var{cname} is the capitalized form of @var{name}. 9905It also makes each @var{valuei} available in the machine description 9906file, just as if it had been declared with: 9907 9908@smallexample 9909(define_constants [(@var{valuei} @var{i})]) 9910@end smallexample 9911 9912Each @var{valuei} is usually an upper-case identifier and usually 9913begins with @var{cname}. 9914 9915You can split the enumeration definition into as many statements as 9916you like. The above example is directly equivalent to: 9917 9918@smallexample 9919(define_c_enum "@var{name}" [@var{value0}]) 9920(define_c_enum "@var{name}" [@var{value1}]) 9921@dots{} 9922(define_c_enum "@var{name}" [@var{valuen}]) 9923@end smallexample 9924 9925Splitting the enumeration helps to improve the modularity of each 9926individual @code{.md} file. For example, if a port defines its 9927synchronization instructions in a separate @file{sync.md} file, 9928it is convenient to define all synchronization-specific enumeration 9929values in @file{sync.md} rather than in the main @file{.md} file. 9930 9931Some enumeration names have special significance to GCC: 9932 9933@table @code 9934@item unspecv 9935@findex unspec_volatile 9936If an enumeration called @code{unspecv} is defined, GCC will use it 9937when printing out @code{unspec_volatile} expressions. For example: 9938 9939@smallexample 9940(define_c_enum "unspecv" [ 9941 UNSPECV_BLOCKAGE 9942]) 9943@end smallexample 9944 9945causes GCC to print @samp{(unspec_volatile @dots{} 0)} as: 9946 9947@smallexample 9948(unspec_volatile ... UNSPECV_BLOCKAGE) 9949@end smallexample 9950 9951@item unspec 9952@findex unspec 9953If an enumeration called @code{unspec} is defined, GCC will use 9954it when printing out @code{unspec} expressions. GCC will also use 9955it when printing out @code{unspec_volatile} expressions unless an 9956@code{unspecv} enumeration is also defined. You can therefore 9957decide whether to keep separate enumerations for volatile and 9958non-volatile expressions or whether to use the same enumeration 9959for both. 9960@end table 9961 9962@findex define_enum 9963@anchor{define_enum} 9964Another way of defining an enumeration is to use @code{define_enum}: 9965 9966@smallexample 9967(define_enum "@var{name}" [ 9968 @var{value0} 9969 @var{value1} 9970 @dots{} 9971 @var{valuen} 9972]) 9973@end smallexample 9974 9975This directive implies: 9976 9977@smallexample 9978(define_c_enum "@var{name}" [ 9979 @var{cname}_@var{cvalue0} 9980 @var{cname}_@var{cvalue1} 9981 @dots{} 9982 @var{cname}_@var{cvaluen} 9983]) 9984@end smallexample 9985 9986@findex define_enum_attr 9987where @var{cvaluei} is the capitalized form of @var{valuei}. 9988However, unlike @code{define_c_enum}, the enumerations defined 9989by @code{define_enum} can be used in attribute specifications 9990(@pxref{define_enum_attr}). 9991@end ifset 9992@ifset INTERNALS 9993@node Iterators 9994@section Iterators 9995@cindex iterators in @file{.md} files 9996 9997Ports often need to define similar patterns for more than one machine 9998mode or for more than one rtx code. GCC provides some simple iterator 9999facilities to make this process easier. 10000 10001@menu 10002* Mode Iterators:: Generating variations of patterns for different modes. 10003* Code Iterators:: Doing the same for codes. 10004* Int Iterators:: Doing the same for integers. 10005* Subst Iterators:: Generating variations of patterns for define_subst. 10006@end menu 10007 10008@node Mode Iterators 10009@subsection Mode Iterators 10010@cindex mode iterators in @file{.md} files 10011 10012Ports often need to define similar patterns for two or more different modes. 10013For example: 10014 10015@itemize @bullet 10016@item 10017If a processor has hardware support for both single and double 10018floating-point arithmetic, the @code{SFmode} patterns tend to be 10019very similar to the @code{DFmode} ones. 10020 10021@item 10022If a port uses @code{SImode} pointers in one configuration and 10023@code{DImode} pointers in another, it will usually have very similar 10024@code{SImode} and @code{DImode} patterns for manipulating pointers. 10025@end itemize 10026 10027Mode iterators allow several patterns to be instantiated from one 10028@file{.md} file template. They can be used with any type of 10029rtx-based construct, such as a @code{define_insn}, 10030@code{define_split}, or @code{define_peephole2}. 10031 10032@menu 10033* Defining Mode Iterators:: Defining a new mode iterator. 10034* Substitutions:: Combining mode iterators with substitutions 10035* Examples:: Examples 10036@end menu 10037 10038@node Defining Mode Iterators 10039@subsubsection Defining Mode Iterators 10040@findex define_mode_iterator 10041 10042The syntax for defining a mode iterator is: 10043 10044@smallexample 10045(define_mode_iterator @var{name} [(@var{mode1} "@var{cond1}") @dots{} (@var{moden} "@var{condn}")]) 10046@end smallexample 10047 10048This allows subsequent @file{.md} file constructs to use the mode suffix 10049@code{:@var{name}}. Every construct that does so will be expanded 10050@var{n} times, once with every use of @code{:@var{name}} replaced by 10051@code{:@var{mode1}}, once with every use replaced by @code{:@var{mode2}}, 10052and so on. In the expansion for a particular @var{modei}, every 10053C condition will also require that @var{condi} be true. 10054 10055For example: 10056 10057@smallexample 10058(define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")]) 10059@end smallexample 10060 10061defines a new mode suffix @code{:P}. Every construct that uses 10062@code{:P} will be expanded twice, once with every @code{:P} replaced 10063by @code{:SI} and once with every @code{:P} replaced by @code{:DI}. 10064The @code{:SI} version will only apply if @code{Pmode == SImode} and 10065the @code{:DI} version will only apply if @code{Pmode == DImode}. 10066 10067As with other @file{.md} conditions, an empty string is treated 10068as ``always true''. @code{(@var{mode} "")} can also be abbreviated 10069to @code{@var{mode}}. For example: 10070 10071@smallexample 10072(define_mode_iterator GPR [SI (DI "TARGET_64BIT")]) 10073@end smallexample 10074 10075means that the @code{:DI} expansion only applies if @code{TARGET_64BIT} 10076but that the @code{:SI} expansion has no such constraint. 10077 10078Iterators are applied in the order they are defined. This can be 10079significant if two iterators are used in a construct that requires 10080substitutions. @xref{Substitutions}. 10081 10082@node Substitutions 10083@subsubsection Substitution in Mode Iterators 10084@findex define_mode_attr 10085 10086If an @file{.md} file construct uses mode iterators, each version of the 10087construct will often need slightly different strings or modes. For 10088example: 10089 10090@itemize @bullet 10091@item 10092When a @code{define_expand} defines several @code{add@var{m}3} patterns 10093(@pxref{Standard Names}), each expander will need to use the 10094appropriate mode name for @var{m}. 10095 10096@item 10097When a @code{define_insn} defines several instruction patterns, 10098each instruction will often use a different assembler mnemonic. 10099 10100@item 10101When a @code{define_insn} requires operands with different modes, 10102using an iterator for one of the operand modes usually requires a specific 10103mode for the other operand(s). 10104@end itemize 10105 10106GCC supports such variations through a system of ``mode attributes''. 10107There are two standard attributes: @code{mode}, which is the name of 10108the mode in lower case, and @code{MODE}, which is the same thing in 10109upper case. You can define other attributes using: 10110 10111@smallexample 10112(define_mode_attr @var{name} [(@var{mode1} "@var{value1}") @dots{} (@var{moden} "@var{valuen}")]) 10113@end smallexample 10114 10115where @var{name} is the name of the attribute and @var{valuei} 10116is the value associated with @var{modei}. 10117 10118When GCC replaces some @var{:iterator} with @var{:mode}, it will scan 10119each string and mode in the pattern for sequences of the form 10120@code{<@var{iterator}:@var{attr}>}, where @var{attr} is the name of a 10121mode attribute. If the attribute is defined for @var{mode}, the whole 10122@code{<@dots{}>} sequence will be replaced by the appropriate attribute 10123value. 10124 10125For example, suppose an @file{.md} file has: 10126 10127@smallexample 10128(define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")]) 10129(define_mode_attr load [(SI "lw") (DI "ld")]) 10130@end smallexample 10131 10132If one of the patterns that uses @code{:P} contains the string 10133@code{"<P:load>\t%0,%1"}, the @code{SI} version of that pattern 10134will use @code{"lw\t%0,%1"} and the @code{DI} version will use 10135@code{"ld\t%0,%1"}. 10136 10137Here is an example of using an attribute for a mode: 10138 10139@smallexample 10140(define_mode_iterator LONG [SI DI]) 10141(define_mode_attr SHORT [(SI "HI") (DI "SI")]) 10142(define_insn @dots{} 10143 (sign_extend:LONG (match_operand:<LONG:SHORT> @dots{})) @dots{}) 10144@end smallexample 10145 10146The @code{@var{iterator}:} prefix may be omitted, in which case the 10147substitution will be attempted for every iterator expansion. 10148 10149@node Examples 10150@subsubsection Mode Iterator Examples 10151 10152Here is an example from the MIPS port. It defines the following 10153modes and attributes (among others): 10154 10155@smallexample 10156(define_mode_iterator GPR [SI (DI "TARGET_64BIT")]) 10157(define_mode_attr d [(SI "") (DI "d")]) 10158@end smallexample 10159 10160and uses the following template to define both @code{subsi3} 10161and @code{subdi3}: 10162 10163@smallexample 10164(define_insn "sub<mode>3" 10165 [(set (match_operand:GPR 0 "register_operand" "=d") 10166 (minus:GPR (match_operand:GPR 1 "register_operand" "d") 10167 (match_operand:GPR 2 "register_operand" "d")))] 10168 "" 10169 "<d>subu\t%0,%1,%2" 10170 [(set_attr "type" "arith") 10171 (set_attr "mode" "<MODE>")]) 10172@end smallexample 10173 10174This is exactly equivalent to: 10175 10176@smallexample 10177(define_insn "subsi3" 10178 [(set (match_operand:SI 0 "register_operand" "=d") 10179 (minus:SI (match_operand:SI 1 "register_operand" "d") 10180 (match_operand:SI 2 "register_operand" "d")))] 10181 "" 10182 "subu\t%0,%1,%2" 10183 [(set_attr "type" "arith") 10184 (set_attr "mode" "SI")]) 10185 10186(define_insn "subdi3" 10187 [(set (match_operand:DI 0 "register_operand" "=d") 10188 (minus:DI (match_operand:DI 1 "register_operand" "d") 10189 (match_operand:DI 2 "register_operand" "d")))] 10190 "" 10191 "dsubu\t%0,%1,%2" 10192 [(set_attr "type" "arith") 10193 (set_attr "mode" "DI")]) 10194@end smallexample 10195 10196@node Code Iterators 10197@subsection Code Iterators 10198@cindex code iterators in @file{.md} files 10199@findex define_code_iterator 10200@findex define_code_attr 10201 10202Code iterators operate in a similar way to mode iterators. @xref{Mode Iterators}. 10203 10204The construct: 10205 10206@smallexample 10207(define_code_iterator @var{name} [(@var{code1} "@var{cond1}") @dots{} (@var{coden} "@var{condn}")]) 10208@end smallexample 10209 10210defines a pseudo rtx code @var{name} that can be instantiated as 10211@var{codei} if condition @var{condi} is true. Each @var{codei} 10212must have the same rtx format. @xref{RTL Classes}. 10213 10214As with mode iterators, each pattern that uses @var{name} will be 10215expanded @var{n} times, once with all uses of @var{name} replaced by 10216@var{code1}, once with all uses replaced by @var{code2}, and so on. 10217@xref{Defining Mode Iterators}. 10218 10219It is possible to define attributes for codes as well as for modes. 10220There are two standard code attributes: @code{code}, the name of the 10221code in lower case, and @code{CODE}, the name of the code in upper case. 10222Other attributes are defined using: 10223 10224@smallexample 10225(define_code_attr @var{name} [(@var{code1} "@var{value1}") @dots{} (@var{coden} "@var{valuen}")]) 10226@end smallexample 10227 10228Here's an example of code iterators in action, taken from the MIPS port: 10229 10230@smallexample 10231(define_code_iterator any_cond [unordered ordered unlt unge uneq ltgt unle ungt 10232 eq ne gt ge lt le gtu geu ltu leu]) 10233 10234(define_expand "b<code>" 10235 [(set (pc) 10236 (if_then_else (any_cond:CC (cc0) 10237 (const_int 0)) 10238 (label_ref (match_operand 0 "")) 10239 (pc)))] 10240 "" 10241@{ 10242 gen_conditional_branch (operands, <CODE>); 10243 DONE; 10244@}) 10245@end smallexample 10246 10247This is equivalent to: 10248 10249@smallexample 10250(define_expand "bunordered" 10251 [(set (pc) 10252 (if_then_else (unordered:CC (cc0) 10253 (const_int 0)) 10254 (label_ref (match_operand 0 "")) 10255 (pc)))] 10256 "" 10257@{ 10258 gen_conditional_branch (operands, UNORDERED); 10259 DONE; 10260@}) 10261 10262(define_expand "bordered" 10263 [(set (pc) 10264 (if_then_else (ordered:CC (cc0) 10265 (const_int 0)) 10266 (label_ref (match_operand 0 "")) 10267 (pc)))] 10268 "" 10269@{ 10270 gen_conditional_branch (operands, ORDERED); 10271 DONE; 10272@}) 10273 10274@dots{} 10275@end smallexample 10276 10277@node Int Iterators 10278@subsection Int Iterators 10279@cindex int iterators in @file{.md} files 10280@findex define_int_iterator 10281@findex define_int_attr 10282 10283Int iterators operate in a similar way to code iterators. @xref{Code Iterators}. 10284 10285The construct: 10286 10287@smallexample 10288(define_int_iterator @var{name} [(@var{int1} "@var{cond1}") @dots{} (@var{intn} "@var{condn}")]) 10289@end smallexample 10290 10291defines a pseudo integer constant @var{name} that can be instantiated as 10292@var{inti} if condition @var{condi} is true. Each @var{int} 10293must have the same rtx format. @xref{RTL Classes}. Int iterators can appear 10294in only those rtx fields that have 'i' as the specifier. This means that 10295each @var{int} has to be a constant defined using define_constant or 10296define_c_enum. 10297 10298As with mode and code iterators, each pattern that uses @var{name} will be 10299expanded @var{n} times, once with all uses of @var{name} replaced by 10300@var{int1}, once with all uses replaced by @var{int2}, and so on. 10301@xref{Defining Mode Iterators}. 10302 10303It is possible to define attributes for ints as well as for codes and modes. 10304Attributes are defined using: 10305 10306@smallexample 10307(define_int_attr @var{name} [(@var{int1} "@var{value1}") @dots{} (@var{intn} "@var{valuen}")]) 10308@end smallexample 10309 10310Here's an example of int iterators in action, taken from the ARM port: 10311 10312@smallexample 10313(define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG]) 10314 10315(define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")]) 10316 10317(define_insn "neon_vq<absneg><mode>" 10318 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 10319 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 10320 (match_operand:SI 2 "immediate_operand" "i")] 10321 QABSNEG))] 10322 "TARGET_NEON" 10323 "vq<absneg>.<V_s_elem>\t%<V_reg>0, %<V_reg>1" 10324 [(set_attr "type" "neon_vqneg_vqabs")] 10325) 10326 10327@end smallexample 10328 10329This is equivalent to: 10330 10331@smallexample 10332(define_insn "neon_vqabs<mode>" 10333 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 10334 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 10335 (match_operand:SI 2 "immediate_operand" "i")] 10336 UNSPEC_VQABS))] 10337 "TARGET_NEON" 10338 "vqabs.<V_s_elem>\t%<V_reg>0, %<V_reg>1" 10339 [(set_attr "type" "neon_vqneg_vqabs")] 10340) 10341 10342(define_insn "neon_vqneg<mode>" 10343 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 10344 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 10345 (match_operand:SI 2 "immediate_operand" "i")] 10346 UNSPEC_VQNEG))] 10347 "TARGET_NEON" 10348 "vqneg.<V_s_elem>\t%<V_reg>0, %<V_reg>1" 10349 [(set_attr "type" "neon_vqneg_vqabs")] 10350) 10351 10352@end smallexample 10353 10354@node Subst Iterators 10355@subsection Subst Iterators 10356@cindex subst iterators in @file{.md} files 10357@findex define_subst 10358@findex define_subst_attr 10359 10360Subst iterators are special type of iterators with the following 10361restrictions: they could not be declared explicitly, they always have 10362only two values, and they do not have explicit dedicated name. 10363Subst-iterators are triggered only when corresponding subst-attribute is 10364used in RTL-pattern. 10365 10366Subst iterators transform templates in the following way: the templates 10367are duplicated, the subst-attributes in these templates are replaced 10368with the corresponding values, and a new attribute is implicitly added 10369to the given @code{define_insn}/@code{define_expand}. The name of the 10370added attribute matches the name of @code{define_subst}. Such 10371attributes are declared implicitly, and it is not allowed to have a 10372@code{define_attr} named as a @code{define_subst}. 10373 10374Each subst iterator is linked to a @code{define_subst}. It is declared 10375implicitly by the first appearance of the corresponding 10376@code{define_subst_attr}, and it is not allowed to define it explicitly. 10377 10378Declarations of subst-attributes have the following syntax: 10379 10380@findex define_subst_attr 10381@smallexample 10382(define_subst_attr "@var{name}" 10383 "@var{subst-name}" 10384 "@var{no-subst-value}" 10385 "@var{subst-applied-value}") 10386@end smallexample 10387 10388@var{name} is a string with which the given subst-attribute could be 10389referred to. 10390 10391@var{subst-name} shows which @code{define_subst} should be applied to an 10392RTL-template if the given subst-attribute is present in the 10393RTL-template. 10394 10395@var{no-subst-value} is a value with which subst-attribute would be 10396replaced in the first copy of the original RTL-template. 10397 10398@var{subst-applied-value} is a value with which subst-attribute would be 10399replaced in the second copy of the original RTL-template. 10400 10401@end ifset 10402