1@c Copyright (C) 1988-2020 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 @var{n}. When a name is present, the compiler 119automically generates a C++ function @samp{gen_@var{n}} that takes 120the operands of the instruction as arguments and returns the instruction's 121rtx pattern. The compiler also assigns the instruction a unique code 122@samp{CODE_FOR_@var{n}}, with all such codes belonging to an enum 123called @code{insn_code}. 124 125These names serve one of two purposes. The first is to indicate that the 126instruction performs a certain standard job for the RTL-generation 127pass of the compiler, such as a move, an addition, or a conditional 128jump. The second is to help the target generate certain target-specific 129operations, such as when implementing target-specific intrinsic functions. 130 131It is better to prefix target-specific names with the name of the 132target, to avoid any clash with current or future standard names. 133 134The absence of a name is indicated by writing an empty string 135where the name should go. Nameless instruction patterns are never 136used for generating RTL code, but they may permit several simpler insns 137to be combined later on. 138 139For the purpose of debugging the compiler, you may also specify a 140name beginning with the @samp{*} character. Such a name is used only 141for identifying the instruction in RTL dumps; it is equivalent to having 142a nameless pattern for all other purposes. Names beginning with the 143@samp{*} character are not required to be unique. 144 145The name may also have the form @samp{@@@var{n}}. This has the same 146effect as a name @samp{@var{n}}, but in addition tells the compiler to 147generate further helper functions; see @ref{Parameterized Names} for details. 148 149@item 150The @dfn{RTL template}: This is a vector of incomplete RTL expressions 151which describe the semantics of the instruction (@pxref{RTL Template}). 152It is incomplete because it may contain @code{match_operand}, 153@code{match_operator}, and @code{match_dup} expressions that stand for 154operands of the instruction. 155 156If the vector has multiple elements, the RTL template is treated as a 157@code{parallel} expression. 158 159@item 160@cindex pattern conditions 161@cindex conditions, in patterns 162The condition: This is a string which contains a C expression. When the 163compiler attempts to match RTL against a pattern, the condition is 164evaluated. If the condition evaluates to @code{true}, the match is 165permitted. The condition may be an empty string, which is treated 166as always @code{true}. 167 168@cindex named patterns and conditions 169For a named pattern, the condition may not depend on the data in the 170insn being matched, but only the target-machine-type flags. The compiler 171needs to test these conditions during initialization in order to learn 172exactly which named instructions are available in a particular run. 173 174@findex operands 175For nameless patterns, the condition is applied only when matching an 176individual insn, and only after the insn has matched the pattern's 177recognition template. The insn's operands may be found in the vector 178@code{operands}. 179 180An instruction condition cannot become more restrictive as compilation 181progresses. If the condition accepts a particular RTL instruction at 182one stage of compilation, it must continue to accept that instruction 183until the final pass. For example, @samp{!reload_completed} and 184@samp{can_create_pseudo_p ()} are both invalid instruction conditions, 185because they are true during the earlier RTL passes and false during 186the later ones. For the same reason, if a condition accepts an 187instruction before register allocation, it cannot later try to control 188register allocation by excluding certain register or value combinations. 189 190Although a condition cannot become more restrictive as compilation 191progresses, the condition for a nameless pattern @emph{can} become 192more permissive. For example, a nameless instruction can require 193@samp{reload_completed} to be true, in which case it only matches 194after register allocation. 195 196@item 197The @dfn{output template} or @dfn{output statement}: This is either 198a string, or a fragment of C code which returns a string. 199 200When simple substitution isn't general enough, you can specify a piece 201of C code to compute the output. @xref{Output Statement}. 202 203@item 204The @dfn{insn attributes}: This is an optional vector containing the values of 205attributes for insns matching this pattern (@pxref{Insn Attributes}). 206@end enumerate 207 208@node Example 209@section Example of @code{define_insn} 210@cindex @code{define_insn} example 211 212Here is an example of an instruction pattern, taken from the machine 213description for the 68000/68020. 214 215@smallexample 216(define_insn "tstsi" 217 [(set (cc0) 218 (match_operand:SI 0 "general_operand" "rm"))] 219 "" 220 "* 221@{ 222 if (TARGET_68020 || ! ADDRESS_REG_P (operands[0])) 223 return \"tstl %0\"; 224 return \"cmpl #0,%0\"; 225@}") 226@end smallexample 227 228@noindent 229This can also be written using braced strings: 230 231@smallexample 232(define_insn "tstsi" 233 [(set (cc0) 234 (match_operand:SI 0 "general_operand" "rm"))] 235 "" 236@{ 237 if (TARGET_68020 || ! ADDRESS_REG_P (operands[0])) 238 return "tstl %0"; 239 return "cmpl #0,%0"; 240@}) 241@end smallexample 242 243This describes an instruction which sets the condition codes based on the 244value of a general operand. It has no condition, so any insn with an RTL 245description of the form shown may be matched to this pattern. The name 246@samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL 247generation pass that, when it is necessary to test such a value, an insn 248to do so can be constructed using this pattern. 249 250The output control string is a piece of C code which chooses which 251output template to return based on the kind of operand and the specific 252type of CPU for which code is being generated. 253 254@samp{"rm"} is an operand constraint. Its meaning is explained below. 255 256@node RTL Template 257@section RTL Template 258@cindex RTL insn template 259@cindex generating insns 260@cindex insns, generating 261@cindex recognizing insns 262@cindex insns, recognizing 263 264The RTL template is used to define which insns match the particular pattern 265and how to find their operands. For named patterns, the RTL template also 266says how to construct an insn from specified operands. 267 268Construction involves substituting specified operands into a copy of the 269template. Matching involves determining the values that serve as the 270operands in the insn being matched. Both of these activities are 271controlled by special expression types that direct matching and 272substitution of the operands. 273 274@table @code 275@findex match_operand 276@item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint}) 277This expression is a placeholder for operand number @var{n} of 278the insn. When constructing an insn, operand number @var{n} 279will be substituted at this point. When matching an insn, whatever 280appears at this position in the insn will be taken as operand 281number @var{n}; but it must satisfy @var{predicate} or this instruction 282pattern will not match at all. 283 284Operand numbers must be chosen consecutively counting from zero in 285each instruction pattern. There may be only one @code{match_operand} 286expression in the pattern for each operand number. Usually operands 287are numbered in the order of appearance in @code{match_operand} 288expressions. In the case of a @code{define_expand}, any operand numbers 289used only in @code{match_dup} expressions have higher values than all 290other operand numbers. 291 292@var{predicate} is a string that is the name of a function that 293accepts two arguments, an expression and a machine mode. 294@xref{Predicates}. During matching, the function will be called with 295the putative operand as the expression and @var{m} as the mode 296argument (if @var{m} is not specified, @code{VOIDmode} will be used, 297which normally causes @var{predicate} to accept any mode). If it 298returns zero, this instruction pattern fails to match. 299@var{predicate} may be an empty string; then it means no test is to be 300done on the operand, so anything which occurs in this position is 301valid. 302 303Most of the time, @var{predicate} will reject modes other than @var{m}---but 304not always. For example, the predicate @code{address_operand} uses 305@var{m} as the mode of memory ref that the address should be valid for. 306Many predicates accept @code{const_int} nodes even though their mode is 307@code{VOIDmode}. 308 309@var{constraint} controls reloading and the choice of the best register 310class to use for a value, as explained later (@pxref{Constraints}). 311If the constraint would be an empty string, it can be omitted. 312 313People are often unclear on the difference between the constraint and the 314predicate. The predicate helps decide whether a given insn matches the 315pattern. The constraint plays no role in this decision; instead, it 316controls various decisions in the case of an insn which does match. 317 318@findex match_scratch 319@item (match_scratch:@var{m} @var{n} @var{constraint}) 320This expression is also a placeholder for operand number @var{n} 321and indicates that operand must be a @code{scratch} or @code{reg} 322expression. 323 324When matching patterns, this is equivalent to 325 326@smallexample 327(match_operand:@var{m} @var{n} "scratch_operand" @var{constraint}) 328@end smallexample 329 330but, when generating RTL, it produces a (@code{scratch}:@var{m}) 331expression. 332 333If the last few expressions in a @code{parallel} are @code{clobber} 334expressions whose operands are either a hard register or 335@code{match_scratch}, the combiner can add or delete them when 336necessary. @xref{Side Effects}. 337 338@findex match_dup 339@item (match_dup @var{n}) 340This expression is also a placeholder for operand number @var{n}. 341It is used when the operand needs to appear more than once in the 342insn. 343 344In construction, @code{match_dup} acts just like @code{match_operand}: 345the operand is substituted into the insn being constructed. But in 346matching, @code{match_dup} behaves differently. It assumes that operand 347number @var{n} has already been determined by a @code{match_operand} 348appearing earlier in the recognition template, and it matches only an 349identical-looking expression. 350 351Note that @code{match_dup} should not be used to tell the compiler that 352a particular register is being used for two operands (example: 353@code{add} that adds one register to another; the second register is 354both an input operand and the output operand). Use a matching 355constraint (@pxref{Simple Constraints}) for those. @code{match_dup} is for the cases where one 356operand is used in two places in the template, such as an instruction 357that computes both a quotient and a remainder, where the opcode takes 358two input operands but the RTL template has to refer to each of those 359twice; once for the quotient pattern and once for the remainder pattern. 360 361@findex match_operator 362@item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}]) 363This pattern is a kind of placeholder for a variable RTL expression 364code. 365 366When constructing an insn, it stands for an RTL expression whose 367expression code is taken from that of operand @var{n}, and whose 368operands are constructed from the patterns @var{operands}. 369 370When matching an expression, it matches an expression if the function 371@var{predicate} returns nonzero on that expression @emph{and} the 372patterns @var{operands} match the operands of the expression. 373 374Suppose that the function @code{commutative_operator} is defined as 375follows, to match any expression whose operator is one of the 376commutative arithmetic operators of RTL and whose mode is @var{mode}: 377 378@smallexample 379int 380commutative_integer_operator (x, mode) 381 rtx x; 382 machine_mode mode; 383@{ 384 enum rtx_code code = GET_CODE (x); 385 if (GET_MODE (x) != mode) 386 return 0; 387 return (GET_RTX_CLASS (code) == RTX_COMM_ARITH 388 || code == EQ || code == NE); 389@} 390@end smallexample 391 392Then the following pattern will match any RTL expression consisting 393of a commutative operator applied to two general operands: 394 395@smallexample 396(match_operator:SI 3 "commutative_operator" 397 [(match_operand:SI 1 "general_operand" "g") 398 (match_operand:SI 2 "general_operand" "g")]) 399@end smallexample 400 401Here the vector @code{[@var{operands}@dots{}]} contains two patterns 402because the expressions to be matched all contain two operands. 403 404When this pattern does match, the two operands of the commutative 405operator are recorded as operands 1 and 2 of the insn. (This is done 406by the two instances of @code{match_operand}.) Operand 3 of the insn 407will be the entire commutative expression: use @code{GET_CODE 408(operands[3])} to see which commutative operator was used. 409 410The machine mode @var{m} of @code{match_operator} works like that of 411@code{match_operand}: it is passed as the second argument to the 412predicate function, and that function is solely responsible for 413deciding whether the expression to be matched ``has'' that mode. 414 415When constructing an insn, argument 3 of the gen-function will specify 416the operation (i.e.@: the expression code) for the expression to be 417made. It should be an RTL expression, whose expression code is copied 418into a new expression whose operands are arguments 1 and 2 of the 419gen-function. The subexpressions of argument 3 are not used; 420only its expression code matters. 421 422When @code{match_operator} is used in a pattern for matching an insn, 423it usually best if the operand number of the @code{match_operator} 424is higher than that of the actual operands of the insn. This improves 425register allocation because the register allocator often looks at 426operands 1 and 2 of insns to see if it can do register tying. 427 428There is no way to specify constraints in @code{match_operator}. The 429operand of the insn which corresponds to the @code{match_operator} 430never has any constraints because it is never reloaded as a whole. 431However, if parts of its @var{operands} are matched by 432@code{match_operand} patterns, those parts may have constraints of 433their own. 434 435@findex match_op_dup 436@item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}]) 437Like @code{match_dup}, except that it applies to operators instead of 438operands. When constructing an insn, operand number @var{n} will be 439substituted at this point. But in matching, @code{match_op_dup} behaves 440differently. It assumes that operand number @var{n} has already been 441determined by a @code{match_operator} appearing earlier in the 442recognition template, and it matches only an identical-looking 443expression. 444 445@findex match_parallel 446@item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}]) 447This pattern is a placeholder for an insn that consists of a 448@code{parallel} expression with a variable number of elements. This 449expression should only appear at the top level of an insn pattern. 450 451When constructing an insn, operand number @var{n} will be substituted at 452this point. When matching an insn, it matches if the body of the insn 453is a @code{parallel} expression with at least as many elements as the 454vector of @var{subpat} expressions in the @code{match_parallel}, if each 455@var{subpat} matches the corresponding element of the @code{parallel}, 456@emph{and} the function @var{predicate} returns nonzero on the 457@code{parallel} that is the body of the insn. It is the responsibility 458of the predicate to validate elements of the @code{parallel} beyond 459those listed in the @code{match_parallel}. 460 461A typical use of @code{match_parallel} is to match load and store 462multiple expressions, which can contain a variable number of elements 463in a @code{parallel}. For example, 464 465@smallexample 466(define_insn "" 467 [(match_parallel 0 "load_multiple_operation" 468 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 469 (match_operand:SI 2 "memory_operand" "m")) 470 (use (reg:SI 179)) 471 (clobber (reg:SI 179))])] 472 "" 473 "loadm 0,0,%1,%2") 474@end smallexample 475 476This example comes from @file{a29k.md}. The function 477@code{load_multiple_operation} is defined in @file{a29k.c} and checks 478that subsequent elements in the @code{parallel} are the same as the 479@code{set} in the pattern, except that they are referencing subsequent 480registers and memory locations. 481 482An insn that matches this pattern might look like: 483 484@smallexample 485(parallel 486 [(set (reg:SI 20) (mem:SI (reg:SI 100))) 487 (use (reg:SI 179)) 488 (clobber (reg:SI 179)) 489 (set (reg:SI 21) 490 (mem:SI (plus:SI (reg:SI 100) 491 (const_int 4)))) 492 (set (reg:SI 22) 493 (mem:SI (plus:SI (reg:SI 100) 494 (const_int 8))))]) 495@end smallexample 496 497@findex match_par_dup 498@item (match_par_dup @var{n} [@var{subpat}@dots{}]) 499Like @code{match_op_dup}, but for @code{match_parallel} instead of 500@code{match_operator}. 501 502@end table 503 504@node Output Template 505@section Output Templates and Operand Substitution 506@cindex output templates 507@cindex operand substitution 508 509@cindex @samp{%} in template 510@cindex percent sign 511The @dfn{output template} is a string which specifies how to output the 512assembler code for an instruction pattern. Most of the template is a 513fixed string which is output literally. The character @samp{%} is used 514to specify where to substitute an operand; it can also be used to 515identify places where different variants of the assembler require 516different syntax. 517 518In the simplest case, a @samp{%} followed by a digit @var{n} says to output 519operand @var{n} at that point in the string. 520 521@samp{%} followed by a letter and a digit says to output an operand in an 522alternate fashion. Four letters have standard, built-in meanings described 523below. The machine description macro @code{PRINT_OPERAND} can define 524additional letters with nonstandard meanings. 525 526@samp{%c@var{digit}} can be used to substitute an operand that is a 527constant value without the syntax that normally indicates an immediate 528operand. 529 530@samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of 531the constant is negated before printing. 532 533@samp{%a@var{digit}} can be used to substitute an operand as if it were a 534memory reference, with the actual operand treated as the address. This may 535be useful when outputting a ``load address'' instruction, because often the 536assembler syntax for such an instruction requires you to write the operand 537as if it were a memory reference. 538 539@samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump 540instruction. 541 542@samp{%=} outputs a number which is unique to each instruction in the 543entire compilation. This is useful for making local labels to be 544referred to more than once in a single template that generates multiple 545assembler instructions. 546 547@samp{%} followed by a punctuation character specifies a substitution that 548does not use an operand. Only one case is standard: @samp{%%} outputs a 549@samp{%} into the assembler code. Other nonstandard cases can be 550defined in the @code{PRINT_OPERAND} macro. You must also define 551which punctuation characters are valid with the 552@code{PRINT_OPERAND_PUNCT_VALID_P} macro. 553 554@cindex \ 555@cindex backslash 556The template may generate multiple assembler instructions. Write the text 557for the instructions, with @samp{\;} between them. 558 559@cindex matching operands 560When the RTL contains two operands which are required by constraint to match 561each other, the output template must refer only to the lower-numbered operand. 562Matching operands are not always identical, and the rest of the compiler 563arranges to put the proper RTL expression for printing into the lower-numbered 564operand. 565 566One use of nonstandard letters or punctuation following @samp{%} is to 567distinguish between different assembler languages for the same machine; for 568example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax 569requires periods in most opcode names, while MIT syntax does not. For 570example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola 571syntax. The same file of patterns is used for both kinds of output syntax, 572but the character sequence @samp{%.} is used in each place where Motorola 573syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax 574defines the sequence to output a period; the macro for MIT syntax defines 575it to do nothing. 576 577@cindex @code{#} in template 578As a special case, a template consisting of the single character @code{#} 579instructs the compiler to first split the insn, and then output the 580resulting instructions separately. This helps eliminate redundancy in the 581output templates. If you have a @code{define_insn} that needs to emit 582multiple assembler instructions, and there is a matching @code{define_split} 583already defined, then you can simply use @code{#} as the output template 584instead of writing an output template that emits the multiple assembler 585instructions. 586 587Note that @code{#} only has an effect while generating assembly code; 588it does not affect whether a split occurs earlier. An associated 589@code{define_split} must exist and it must be suitable for use after 590register allocation. 591 592If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct 593of the form @samp{@{option0|option1|option2@}} in the templates. These 594describe multiple variants of assembler language syntax. 595@xref{Instruction Output}. 596 597@node Output Statement 598@section C Statements for Assembler Output 599@cindex output statements 600@cindex C statements for assembler output 601@cindex generating assembler output 602 603Often a single fixed template string cannot produce correct and efficient 604assembler code for all the cases that are recognized by a single 605instruction pattern. For example, the opcodes may depend on the kinds of 606operands; or some unfortunate combinations of operands may require extra 607machine instructions. 608 609If the output control string starts with a @samp{@@}, then it is actually 610a series of templates, each on a separate line. (Blank lines and 611leading spaces and tabs are ignored.) The templates correspond to the 612pattern's constraint alternatives (@pxref{Multi-Alternative}). For example, 613if a target machine has a two-address add instruction @samp{addr} to add 614into a register and another @samp{addm} to add a register to memory, you 615might write this pattern: 616 617@smallexample 618(define_insn "addsi3" 619 [(set (match_operand:SI 0 "general_operand" "=r,m") 620 (plus:SI (match_operand:SI 1 "general_operand" "0,0") 621 (match_operand:SI 2 "general_operand" "g,r")))] 622 "" 623 "@@ 624 addr %2,%0 625 addm %2,%0") 626@end smallexample 627 628@cindex @code{*} in template 629@cindex asterisk in template 630If the output control string starts with a @samp{*}, then it is not an 631output template but rather a piece of C program that should compute a 632template. It should execute a @code{return} statement to return the 633template-string you want. Most such templates use C string literals, which 634require doublequote characters to delimit them. To include these 635doublequote characters in the string, prefix each one with @samp{\}. 636 637If the output control string is written as a brace block instead of a 638double-quoted string, it is automatically assumed to be C code. In that 639case, it is not necessary to put in a leading asterisk, or to escape the 640doublequotes surrounding C string literals. 641 642The operands may be found in the array @code{operands}, whose C data type 643is @code{rtx []}. 644 645It is very common to select different ways of generating assembler code 646based on whether an immediate operand is within a certain range. Be 647careful when doing this, because the result of @code{INTVAL} is an 648integer on the host machine. If the host machine has more bits in an 649@code{int} than the target machine has in the mode in which the constant 650will be used, then some of the bits you get from @code{INTVAL} will be 651superfluous. For proper results, you must carefully disregard the 652values of those bits. 653 654@findex output_asm_insn 655It is possible to output an assembler instruction and then go on to output 656or compute more of them, using the subroutine @code{output_asm_insn}. This 657receives two arguments: a template-string and a vector of operands. The 658vector may be @code{operands}, or it may be another array of @code{rtx} 659that you declare locally and initialize yourself. 660 661@findex which_alternative 662When an insn pattern has multiple alternatives in its constraints, often 663the appearance of the assembler code is determined mostly by which alternative 664was matched. When this is so, the C code can test the variable 665@code{which_alternative}, which is the ordinal number of the alternative 666that was actually satisfied (0 for the first, 1 for the second alternative, 667etc.). 668 669For example, suppose there are two opcodes for storing zero, @samp{clrreg} 670for registers and @samp{clrmem} for memory locations. Here is how 671a pattern could use @code{which_alternative} to choose between them: 672 673@smallexample 674(define_insn "" 675 [(set (match_operand:SI 0 "general_operand" "=r,m") 676 (const_int 0))] 677 "" 678 @{ 679 return (which_alternative == 0 680 ? "clrreg %0" : "clrmem %0"); 681 @}) 682@end smallexample 683 684The example above, where the assembler code to generate was 685@emph{solely} determined by the alternative, could also have been specified 686as follows, having the output control string start with a @samp{@@}: 687 688@smallexample 689@group 690(define_insn "" 691 [(set (match_operand:SI 0 "general_operand" "=r,m") 692 (const_int 0))] 693 "" 694 "@@ 695 clrreg %0 696 clrmem %0") 697@end group 698@end smallexample 699 700If you just need a little bit of C code in one (or a few) alternatives, 701you can use @samp{*} inside of a @samp{@@} multi-alternative template: 702 703@smallexample 704@group 705(define_insn "" 706 [(set (match_operand:SI 0 "general_operand" "=r,<,m") 707 (const_int 0))] 708 "" 709 "@@ 710 clrreg %0 711 * return stack_mem_p (operands[0]) ? \"push 0\" : \"clrmem %0\"; 712 clrmem %0") 713@end group 714@end smallexample 715 716@node Predicates 717@section Predicates 718@cindex predicates 719@cindex operand predicates 720@cindex operator predicates 721 722A predicate determines whether a @code{match_operand} or 723@code{match_operator} expression matches, and therefore whether the 724surrounding instruction pattern will be used for that combination of 725operands. GCC has a number of machine-independent predicates, and you 726can define machine-specific predicates as needed. By convention, 727predicates used with @code{match_operand} have names that end in 728@samp{_operand}, and those used with @code{match_operator} have names 729that end in @samp{_operator}. 730 731All predicates are boolean functions (in the mathematical sense) of 732two arguments: the RTL expression that is being considered at that 733position in the instruction pattern, and the machine mode that the 734@code{match_operand} or @code{match_operator} specifies. In this 735section, the first argument is called @var{op} and the second argument 736@var{mode}. Predicates can be called from C as ordinary two-argument 737functions; this can be useful in output templates or other 738machine-specific code. 739 740Operand predicates can allow operands that are not actually acceptable 741to the hardware, as long as the constraints give reload the ability to 742fix them up (@pxref{Constraints}). However, GCC will usually generate 743better code if the predicates specify the requirements of the machine 744instructions as closely as possible. Reload cannot fix up operands 745that must be constants (``immediate operands''); you must use a 746predicate that allows only constants, or else enforce the requirement 747in the extra condition. 748 749@cindex predicates and machine modes 750@cindex normal predicates 751@cindex special predicates 752Most predicates handle their @var{mode} argument in a uniform manner. 753If @var{mode} is @code{VOIDmode} (unspecified), then @var{op} can have 754any mode. If @var{mode} is anything else, then @var{op} must have the 755same mode, unless @var{op} is a @code{CONST_INT} or integer 756@code{CONST_DOUBLE}. These RTL expressions always have 757@code{VOIDmode}, so it would be counterproductive to check that their 758mode matches. Instead, predicates that accept @code{CONST_INT} and/or 759integer @code{CONST_DOUBLE} check that the value stored in the 760constant will fit in the requested mode. 761 762Predicates with this behavior are called @dfn{normal}. 763@command{genrecog} can optimize the instruction recognizer based on 764knowledge of how normal predicates treat modes. It can also diagnose 765certain kinds of common errors in the use of normal predicates; for 766instance, it is almost always an error to use a normal predicate 767without specifying a mode. 768 769Predicates that do something different with their @var{mode} argument 770are called @dfn{special}. The generic predicates 771@code{address_operand} and @code{pmode_register_operand} are special 772predicates. @command{genrecog} does not do any optimizations or 773diagnosis when special predicates are used. 774 775@menu 776* Machine-Independent Predicates:: Predicates available to all back ends. 777* Defining Predicates:: How to write machine-specific predicate 778 functions. 779@end menu 780 781@node Machine-Independent Predicates 782@subsection Machine-Independent Predicates 783@cindex machine-independent predicates 784@cindex generic predicates 785 786These are the generic predicates available to all back ends. They are 787defined in @file{recog.c}. The first category of predicates allow 788only constant, or @dfn{immediate}, operands. 789 790@defun immediate_operand 791This predicate allows any sort of constant that fits in @var{mode}. 792It is an appropriate choice for instructions that take operands that 793must be constant. 794@end defun 795 796@defun const_int_operand 797This predicate allows any @code{CONST_INT} expression that fits in 798@var{mode}. It is an appropriate choice for an immediate operand that 799does not allow a symbol or label. 800@end defun 801 802@defun const_double_operand 803This predicate accepts any @code{CONST_DOUBLE} expression that has 804exactly @var{mode}. If @var{mode} is @code{VOIDmode}, it will also 805accept @code{CONST_INT}. It is intended for immediate floating point 806constants. 807@end defun 808 809@noindent 810The second category of predicates allow only some kind of machine 811register. 812 813@defun register_operand 814This predicate allows any @code{REG} or @code{SUBREG} expression that 815is valid for @var{mode}. It is often suitable for arithmetic 816instruction operands on a RISC machine. 817@end defun 818 819@defun pmode_register_operand 820This is a slight variant on @code{register_operand} which works around 821a limitation in the machine-description reader. 822 823@smallexample 824(match_operand @var{n} "pmode_register_operand" @var{constraint}) 825@end smallexample 826 827@noindent 828means exactly what 829 830@smallexample 831(match_operand:P @var{n} "register_operand" @var{constraint}) 832@end smallexample 833 834@noindent 835would mean, if the machine-description reader accepted @samp{:P} 836mode suffixes. Unfortunately, it cannot, because @code{Pmode} is an 837alias for some other mode, and might vary with machine-specific 838options. @xref{Misc}. 839@end defun 840 841@defun scratch_operand 842This predicate allows hard registers and @code{SCRATCH} expressions, 843but not pseudo-registers. It is used internally by @code{match_scratch}; 844it should not be used directly. 845@end defun 846 847@noindent 848The third category of predicates allow only some kind of memory reference. 849 850@defun memory_operand 851This predicate allows any valid reference to a quantity of mode 852@var{mode} in memory, as determined by the weak form of 853@code{GO_IF_LEGITIMATE_ADDRESS} (@pxref{Addressing Modes}). 854@end defun 855 856@defun address_operand 857This predicate is a little unusual; it allows any operand that is a 858valid expression for the @emph{address} of a quantity of mode 859@var{mode}, again determined by the weak form of 860@code{GO_IF_LEGITIMATE_ADDRESS}. To first order, if 861@samp{@w{(mem:@var{mode} (@var{exp}))}} is acceptable to 862@code{memory_operand}, then @var{exp} is acceptable to 863@code{address_operand}. Note that @var{exp} does not necessarily have 864the mode @var{mode}. 865@end defun 866 867@defun indirect_operand 868This is a stricter form of @code{memory_operand} which allows only 869memory references with a @code{general_operand} as the address 870expression. New uses of this predicate are discouraged, because 871@code{general_operand} is very permissive, so it's hard to tell what 872an @code{indirect_operand} does or does not allow. If a target has 873different requirements for memory operands for different instructions, 874it is better to define target-specific predicates which enforce the 875hardware's requirements explicitly. 876@end defun 877 878@defun push_operand 879This predicate allows a memory reference suitable for pushing a value 880onto the stack. This will be a @code{MEM} which refers to 881@code{stack_pointer_rtx}, with a side effect in its address expression 882(@pxref{Incdec}); which one is determined by the 883@code{STACK_PUSH_CODE} macro (@pxref{Frame Layout}). 884@end defun 885 886@defun pop_operand 887This predicate allows a memory reference suitable for popping a value 888off the stack. Again, this will be a @code{MEM} referring to 889@code{stack_pointer_rtx}, with a side effect in its address 890expression. However, this time @code{STACK_POP_CODE} is expected. 891@end defun 892 893@noindent 894The fourth category of predicates allow some combination of the above 895operands. 896 897@defun nonmemory_operand 898This predicate allows any immediate or register operand valid for @var{mode}. 899@end defun 900 901@defun nonimmediate_operand 902This predicate allows any register or memory operand valid for @var{mode}. 903@end defun 904 905@defun general_operand 906This predicate allows any immediate, register, or memory operand 907valid for @var{mode}. 908@end defun 909 910@noindent 911Finally, there are two generic operator predicates. 912 913@defun comparison_operator 914This predicate matches any expression which performs an arithmetic 915comparison in @var{mode}; that is, @code{COMPARISON_P} is true for the 916expression code. 917@end defun 918 919@defun ordered_comparison_operator 920This predicate matches any expression which performs an arithmetic 921comparison in @var{mode} and whose expression code is valid for integer 922modes; that is, the expression code will be one of @code{eq}, @code{ne}, 923@code{lt}, @code{ltu}, @code{le}, @code{leu}, @code{gt}, @code{gtu}, 924@code{ge}, @code{geu}. 925@end defun 926 927@node Defining Predicates 928@subsection Defining Machine-Specific Predicates 929@cindex defining predicates 930@findex define_predicate 931@findex define_special_predicate 932 933Many machines have requirements for their operands that cannot be 934expressed precisely using the generic predicates. You can define 935additional predicates using @code{define_predicate} and 936@code{define_special_predicate} expressions. These expressions have 937three operands: 938 939@itemize @bullet 940@item 941The name of the predicate, as it will be referred to in 942@code{match_operand} or @code{match_operator} expressions. 943 944@item 945An RTL expression which evaluates to true if the predicate allows the 946operand @var{op}, false if it does not. This expression can only use 947the following RTL codes: 948 949@table @code 950@item MATCH_OPERAND 951When written inside a predicate expression, a @code{MATCH_OPERAND} 952expression evaluates to true if the predicate it names would allow 953@var{op}. The operand number and constraint are ignored. Due to 954limitations in @command{genrecog}, you can only refer to generic 955predicates and predicates that have already been defined. 956 957@item MATCH_CODE 958This expression evaluates to true if @var{op} or a specified 959subexpression of @var{op} has one of a given list of RTX codes. 960 961The first operand of this expression is a string constant containing a 962comma-separated list of RTX code names (in lower case). These are the 963codes for which the @code{MATCH_CODE} will be true. 964 965The second operand is a string constant which indicates what 966subexpression of @var{op} to examine. If it is absent or the empty 967string, @var{op} itself is examined. Otherwise, the string constant 968must be a sequence of digits and/or lowercase letters. Each character 969indicates a subexpression to extract from the current expression; for 970the first character this is @var{op}, for the second and subsequent 971characters it is the result of the previous character. A digit 972@var{n} extracts @samp{@w{XEXP (@var{e}, @var{n})}}; a letter @var{l} 973extracts @samp{@w{XVECEXP (@var{e}, 0, @var{n})}} where @var{n} is the 974alphabetic ordinal of @var{l} (0 for `a', 1 for 'b', and so on). The 975@code{MATCH_CODE} then examines the RTX code of the subexpression 976extracted by the complete string. It is not possible to extract 977components of an @code{rtvec} that is not at position 0 within its RTX 978object. 979 980@item MATCH_TEST 981This expression has one operand, a string constant containing a C 982expression. The predicate's arguments, @var{op} and @var{mode}, are 983available with those names in the C expression. The @code{MATCH_TEST} 984evaluates to true if the C expression evaluates to a nonzero value. 985@code{MATCH_TEST} expressions must not have side effects. 986 987@item AND 988@itemx IOR 989@itemx NOT 990@itemx IF_THEN_ELSE 991The basic @samp{MATCH_} expressions can be combined using these 992logical operators, which have the semantics of the C operators 993@samp{&&}, @samp{||}, @samp{!}, and @samp{@w{? :}} respectively. As 994in Common Lisp, you may give an @code{AND} or @code{IOR} expression an 995arbitrary number of arguments; this has exactly the same effect as 996writing a chain of two-argument @code{AND} or @code{IOR} expressions. 997@end table 998 999@item 1000An optional block of C code, which should execute 1001@samp{@w{return true}} if the predicate is found to match and 1002@samp{@w{return false}} if it does not. It must not have any side 1003effects. The predicate arguments, @var{op} and @var{mode}, are 1004available with those names. 1005 1006If a code block is present in a predicate definition, then the RTL 1007expression must evaluate to true @emph{and} the code block must 1008execute @samp{@w{return true}} for the predicate to allow the operand. 1009The RTL expression is evaluated first; do not re-check anything in the 1010code block that was checked in the RTL expression. 1011@end itemize 1012 1013The program @command{genrecog} scans @code{define_predicate} and 1014@code{define_special_predicate} expressions to determine which RTX 1015codes are possibly allowed. You should always make this explicit in 1016the RTL predicate expression, using @code{MATCH_OPERAND} and 1017@code{MATCH_CODE}. 1018 1019Here is an example of a simple predicate definition, from the IA64 1020machine description: 1021 1022@smallexample 1023@group 1024;; @r{True if @var{op} is a @code{SYMBOL_REF} which refers to the sdata section.} 1025(define_predicate "small_addr_symbolic_operand" 1026 (and (match_code "symbol_ref") 1027 (match_test "SYMBOL_REF_SMALL_ADDR_P (op)"))) 1028@end group 1029@end smallexample 1030 1031@noindent 1032And here is another, showing the use of the C block. 1033 1034@smallexample 1035@group 1036;; @r{True if @var{op} is a register operand that is (or could be) a GR reg.} 1037(define_predicate "gr_register_operand" 1038 (match_operand 0 "register_operand") 1039@{ 1040 unsigned int regno; 1041 if (GET_CODE (op) == SUBREG) 1042 op = SUBREG_REG (op); 1043 1044 regno = REGNO (op); 1045 return (regno >= FIRST_PSEUDO_REGISTER || GENERAL_REGNO_P (regno)); 1046@}) 1047@end group 1048@end smallexample 1049 1050Predicates written with @code{define_predicate} automatically include 1051a test that @var{mode} is @code{VOIDmode}, or @var{op} has the same 1052mode as @var{mode}, or @var{op} is a @code{CONST_INT} or 1053@code{CONST_DOUBLE}. They do @emph{not} check specifically for 1054integer @code{CONST_DOUBLE}, nor do they test that the value of either 1055kind of constant fits in the requested mode. This is because 1056target-specific predicates that take constants usually have to do more 1057stringent value checks anyway. If you need the exact same treatment 1058of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic predicates 1059provide, use a @code{MATCH_OPERAND} subexpression to call 1060@code{const_int_operand}, @code{const_double_operand}, or 1061@code{immediate_operand}. 1062 1063Predicates written with @code{define_special_predicate} do not get any 1064automatic mode checks, and are treated as having special mode handling 1065by @command{genrecog}. 1066 1067The program @command{genpreds} is responsible for generating code to 1068test predicates. It also writes a header file containing function 1069declarations for all machine-specific predicates. It is not necessary 1070to declare these predicates in @file{@var{cpu}-protos.h}. 1071@end ifset 1072 1073@c Most of this node appears by itself (in a different place) even 1074@c when the INTERNALS flag is clear. Passages that require the internals 1075@c manual's context are conditionalized to appear only in the internals manual. 1076@ifset INTERNALS 1077@node Constraints 1078@section Operand Constraints 1079@cindex operand constraints 1080@cindex constraints 1081 1082Each @code{match_operand} in an instruction pattern can specify 1083constraints for the operands allowed. The constraints allow you to 1084fine-tune matching within the set of operands allowed by the 1085predicate. 1086 1087@end ifset 1088@ifclear INTERNALS 1089@node Constraints 1090@section Constraints for @code{asm} Operands 1091@cindex operand constraints, @code{asm} 1092@cindex constraints, @code{asm} 1093@cindex @code{asm} constraints 1094 1095Here are specific details on what constraint letters you can use with 1096@code{asm} operands. 1097@end ifclear 1098Constraints can say whether 1099an operand may be in a register, and which kinds of register; whether the 1100operand can be a memory reference, and which kinds of address; whether the 1101operand may be an immediate constant, and which possible values it may 1102have. Constraints can also require two operands to match. 1103Side-effects aren't allowed in operands of inline @code{asm}, unless 1104@samp{<} or @samp{>} constraints are used, because there is no guarantee 1105that the side effects will happen exactly once in an instruction that can update 1106the addressing register. 1107 1108@ifset INTERNALS 1109@menu 1110* Simple Constraints:: Basic use of constraints. 1111* Multi-Alternative:: When an insn has two alternative constraint-patterns. 1112* Class Preferences:: Constraints guide which hard register to put things in. 1113* Modifiers:: More precise control over effects of constraints. 1114* Machine Constraints:: Existing constraints for some particular machines. 1115* Disable Insn Alternatives:: Disable insn alternatives using attributes. 1116* Define Constraints:: How to define machine-specific constraints. 1117* C Constraint Interface:: How to test constraints from C code. 1118@end menu 1119@end ifset 1120 1121@ifclear INTERNALS 1122@menu 1123* Simple Constraints:: Basic use of constraints. 1124* Multi-Alternative:: When an insn has two alternative constraint-patterns. 1125* Modifiers:: More precise control over effects of constraints. 1126* Machine Constraints:: Special constraints for some particular machines. 1127@end menu 1128@end ifclear 1129 1130@node Simple Constraints 1131@subsection Simple Constraints 1132@cindex simple constraints 1133 1134The simplest kind of constraint is a string full of letters, each of 1135which describes one kind of operand that is permitted. Here are 1136the letters that are allowed: 1137 1138@table @asis 1139@item whitespace 1140Whitespace characters are ignored and can be inserted at any position 1141except the first. This enables each alternative for different operands to 1142be visually aligned in the machine description even if they have different 1143number of constraints and modifiers. 1144 1145@cindex @samp{m} in constraint 1146@cindex memory references in constraints 1147@item @samp{m} 1148A memory operand is allowed, with any kind of address that the machine 1149supports in general. 1150Note that the letter used for the general memory constraint can be 1151re-defined by a back end using the @code{TARGET_MEM_CONSTRAINT} macro. 1152 1153@cindex offsettable address 1154@cindex @samp{o} in constraint 1155@item @samp{o} 1156A memory operand is allowed, but only if the address is 1157@dfn{offsettable}. This means that adding a small integer (actually, 1158the width in bytes of the operand, as determined by its machine mode) 1159may be added to the address and the result is also a valid memory 1160address. 1161 1162@cindex autoincrement/decrement addressing 1163For example, an address which is constant is offsettable; so is an 1164address that is the sum of a register and a constant (as long as a 1165slightly larger constant is also within the range of address-offsets 1166supported by the machine); but an autoincrement or autodecrement 1167address is not offsettable. More complicated indirect/indexed 1168addresses may or may not be offsettable depending on the other 1169addressing modes that the machine supports. 1170 1171Note that in an output operand which can be matched by another 1172operand, the constraint letter @samp{o} is valid only when accompanied 1173by both @samp{<} (if the target machine has predecrement addressing) 1174and @samp{>} (if the target machine has preincrement addressing). 1175 1176@cindex @samp{V} in constraint 1177@item @samp{V} 1178A memory operand that is not offsettable. In other words, anything that 1179would fit the @samp{m} constraint but not the @samp{o} constraint. 1180 1181@cindex @samp{<} in constraint 1182@item @samp{<} 1183A memory operand with autodecrement addressing (either predecrement or 1184postdecrement) is allowed. In inline @code{asm} this constraint is only 1185allowed if the operand is used exactly once in an instruction that can 1186handle the side effects. Not using an operand with @samp{<} in constraint 1187string in the inline @code{asm} pattern at all or using it in multiple 1188instructions isn't valid, because the side effects wouldn't be performed 1189or would be performed more than once. Furthermore, on some targets 1190the operand with @samp{<} in constraint string must be accompanied by 1191special instruction suffixes like @code{%U0} instruction suffix on PowerPC 1192or @code{%P0} on IA-64. 1193 1194@cindex @samp{>} in constraint 1195@item @samp{>} 1196A memory operand with autoincrement addressing (either preincrement or 1197postincrement) is allowed. In inline @code{asm} the same restrictions 1198as for @samp{<} apply. 1199 1200@cindex @samp{r} in constraint 1201@cindex registers in constraints 1202@item @samp{r} 1203A register operand is allowed provided that it is in a general 1204register. 1205 1206@cindex constants in constraints 1207@cindex @samp{i} in constraint 1208@item @samp{i} 1209An immediate integer operand (one with constant value) is allowed. 1210This includes symbolic constants whose values will be known only at 1211assembly time or later. 1212 1213@cindex @samp{n} in constraint 1214@item @samp{n} 1215An immediate integer operand with a known numeric value is allowed. 1216Many systems cannot support assembly-time constants for operands less 1217than a word wide. Constraints for these operands should use @samp{n} 1218rather than @samp{i}. 1219 1220@cindex @samp{I} in constraint 1221@item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P} 1222Other letters in the range @samp{I} through @samp{P} may be defined in 1223a machine-dependent fashion to permit immediate integer operands with 1224explicit integer values in specified ranges. For example, on the 122568000, @samp{I} is defined to stand for the range of values 1 to 8. 1226This is the range permitted as a shift count in the shift 1227instructions. 1228 1229@cindex @samp{E} in constraint 1230@item @samp{E} 1231An immediate floating operand (expression code @code{const_double}) is 1232allowed, but only if the target floating point format is the same as 1233that of the host machine (on which the compiler is running). 1234 1235@cindex @samp{F} in constraint 1236@item @samp{F} 1237An immediate floating operand (expression code @code{const_double} or 1238@code{const_vector}) is allowed. 1239 1240@cindex @samp{G} in constraint 1241@cindex @samp{H} in constraint 1242@item @samp{G}, @samp{H} 1243@samp{G} and @samp{H} may be defined in a machine-dependent fashion to 1244permit immediate floating operands in particular ranges of values. 1245 1246@cindex @samp{s} in constraint 1247@item @samp{s} 1248An immediate integer operand whose value is not an explicit integer is 1249allowed. 1250 1251This might appear strange; if an insn allows a constant operand with a 1252value not known at compile time, it certainly must allow any known 1253value. So why use @samp{s} instead of @samp{i}? Sometimes it allows 1254better code to be generated. 1255 1256For example, on the 68000 in a fullword instruction it is possible to 1257use an immediate operand; but if the immediate value is between @minus{}128 1258and 127, better code results from loading the value into a register and 1259using the register. This is because the load into the register can be 1260done with a @samp{moveq} instruction. We arrange for this to happen 1261by defining the letter @samp{K} to mean ``any integer outside the 1262range @minus{}128 to 127'', and then specifying @samp{Ks} in the operand 1263constraints. 1264 1265@cindex @samp{g} in constraint 1266@item @samp{g} 1267Any register, memory or immediate integer operand is allowed, except for 1268registers that are not general registers. 1269 1270@cindex @samp{X} in constraint 1271@item @samp{X} 1272@ifset INTERNALS 1273Any operand whatsoever is allowed, even if it does not satisfy 1274@code{general_operand}. This is normally used in the constraint of 1275a @code{match_scratch} when certain alternatives will not actually 1276require a scratch register. 1277@end ifset 1278@ifclear INTERNALS 1279Any operand whatsoever is allowed. 1280@end ifclear 1281 1282@cindex @samp{0} in constraint 1283@cindex digits in constraint 1284@item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{9} 1285An operand that matches the specified operand number is allowed. If a 1286digit is used together with letters within the same alternative, the 1287digit should come last. 1288 1289This number is allowed to be more than a single digit. If multiple 1290digits are encountered consecutively, they are interpreted as a single 1291decimal integer. There is scant chance for ambiguity, since to-date 1292it has never been desirable that @samp{10} be interpreted as matching 1293either operand 1 @emph{or} operand 0. Should this be desired, one 1294can use multiple alternatives instead. 1295 1296@cindex matching constraint 1297@cindex constraint, matching 1298This is called a @dfn{matching constraint} and what it really means is 1299that the assembler has only a single operand that fills two roles 1300@ifset INTERNALS 1301considered separate in the RTL insn. For example, an add insn has two 1302input operands and one output operand in the RTL, but on most CISC 1303@end ifset 1304@ifclear INTERNALS 1305which @code{asm} distinguishes. For example, an add instruction uses 1306two input operands and an output operand, but on most CISC 1307@end ifclear 1308machines an add instruction really has only two operands, one of them an 1309input-output operand: 1310 1311@smallexample 1312addl #35,r12 1313@end smallexample 1314 1315Matching constraints are used in these circumstances. 1316More precisely, the two operands that match must include one input-only 1317operand and one output-only operand. Moreover, the digit must be a 1318smaller number than the number of the operand that uses it in the 1319constraint. 1320 1321@ifset INTERNALS 1322For operands to match in a particular case usually means that they 1323are identical-looking RTL expressions. But in a few special cases 1324specific kinds of dissimilarity are allowed. For example, @code{*x} 1325as an input operand will match @code{*x++} as an output operand. 1326For proper results in such cases, the output template should always 1327use the output-operand's number when printing the operand. 1328@end ifset 1329 1330@cindex load address instruction 1331@cindex push address instruction 1332@cindex address constraints 1333@cindex @samp{p} in constraint 1334@item @samp{p} 1335An operand that is a valid memory address is allowed. This is 1336for ``load address'' and ``push address'' instructions. 1337 1338@findex address_operand 1339@samp{p} in the constraint must be accompanied by @code{address_operand} 1340as the predicate in the @code{match_operand}. This predicate interprets 1341the mode specified in the @code{match_operand} as the mode of the memory 1342reference for which the address would be valid. 1343 1344@cindex other register constraints 1345@cindex extensible constraints 1346@item @var{other-letters} 1347Other letters can be defined in machine-dependent fashion to stand for 1348particular classes of registers or other arbitrary operand types. 1349@samp{d}, @samp{a} and @samp{f} are defined on the 68000/68020 to stand 1350for data, address and floating point registers. 1351@end table 1352 1353@ifset INTERNALS 1354In order to have valid assembler code, each operand must satisfy 1355its constraint. But a failure to do so does not prevent the pattern 1356from applying to an insn. Instead, it directs the compiler to modify 1357the code so that the constraint will be satisfied. Usually this is 1358done by copying an operand into a register. 1359 1360Contrast, therefore, the two instruction patterns that follow: 1361 1362@smallexample 1363(define_insn "" 1364 [(set (match_operand:SI 0 "general_operand" "=r") 1365 (plus:SI (match_dup 0) 1366 (match_operand:SI 1 "general_operand" "r")))] 1367 "" 1368 "@dots{}") 1369@end smallexample 1370 1371@noindent 1372which has two operands, one of which must appear in two places, and 1373 1374@smallexample 1375(define_insn "" 1376 [(set (match_operand:SI 0 "general_operand" "=r") 1377 (plus:SI (match_operand:SI 1 "general_operand" "0") 1378 (match_operand:SI 2 "general_operand" "r")))] 1379 "" 1380 "@dots{}") 1381@end smallexample 1382 1383@noindent 1384which has three operands, two of which are required by a constraint to be 1385identical. If we are considering an insn of the form 1386 1387@smallexample 1388(insn @var{n} @var{prev} @var{next} 1389 (set (reg:SI 3) 1390 (plus:SI (reg:SI 6) (reg:SI 109))) 1391 @dots{}) 1392@end smallexample 1393 1394@noindent 1395the first pattern would not apply at all, because this insn does not 1396contain two identical subexpressions in the right place. The pattern would 1397say, ``That does not look like an add instruction; try other patterns''. 1398The second pattern would say, ``Yes, that's an add instruction, but there 1399is something wrong with it''. It would direct the reload pass of the 1400compiler to generate additional insns to make the constraint true. The 1401results might look like this: 1402 1403@smallexample 1404(insn @var{n2} @var{prev} @var{n} 1405 (set (reg:SI 3) (reg:SI 6)) 1406 @dots{}) 1407 1408(insn @var{n} @var{n2} @var{next} 1409 (set (reg:SI 3) 1410 (plus:SI (reg:SI 3) (reg:SI 109))) 1411 @dots{}) 1412@end smallexample 1413 1414It is up to you to make sure that each operand, in each pattern, has 1415constraints that can handle any RTL expression that could be present for 1416that operand. (When multiple alternatives are in use, each pattern must, 1417for each possible combination of operand expressions, have at least one 1418alternative which can handle that combination of operands.) The 1419constraints don't need to @emph{allow} any possible operand---when this is 1420the case, they do not constrain---but they must at least point the way to 1421reloading any possible operand so that it will fit. 1422 1423@itemize @bullet 1424@item 1425If the constraint accepts whatever operands the predicate permits, 1426there is no problem: reloading is never necessary for this operand. 1427 1428For example, an operand whose constraints permit everything except 1429registers is safe provided its predicate rejects registers. 1430 1431An operand whose predicate accepts only constant values is safe 1432provided its constraints include the letter @samp{i}. If any possible 1433constant value is accepted, then nothing less than @samp{i} will do; 1434if the predicate is more selective, then the constraints may also be 1435more selective. 1436 1437@item 1438Any operand expression can be reloaded by copying it into a register. 1439So if an operand's constraints allow some kind of register, it is 1440certain to be safe. It need not permit all classes of registers; the 1441compiler knows how to copy a register into another register of the 1442proper class in order to make an instruction valid. 1443 1444@cindex nonoffsettable memory reference 1445@cindex memory reference, nonoffsettable 1446@item 1447A nonoffsettable memory reference can be reloaded by copying the 1448address into a register. So if the constraint uses the letter 1449@samp{o}, all memory references are taken care of. 1450 1451@item 1452A constant operand can be reloaded by allocating space in memory to 1453hold it as preinitialized data. Then the memory reference can be used 1454in place of the constant. So if the constraint uses the letters 1455@samp{o} or @samp{m}, constant operands are not a problem. 1456 1457@item 1458If the constraint permits a constant and a pseudo register used in an insn 1459was not allocated to a hard register and is equivalent to a constant, 1460the register will be replaced with the constant. If the predicate does 1461not permit a constant and the insn is re-recognized for some reason, the 1462compiler will crash. Thus the predicate must always recognize any 1463objects allowed by the constraint. 1464@end itemize 1465 1466If the operand's predicate can recognize registers, but the constraint does 1467not permit them, it can make the compiler crash. When this operand happens 1468to be a register, the reload pass will be stymied, because it does not know 1469how to copy a register temporarily into memory. 1470 1471If the predicate accepts a unary operator, the constraint applies to the 1472operand. For example, the MIPS processor at ISA level 3 supports an 1473instruction which adds two registers in @code{SImode} to produce a 1474@code{DImode} result, but only if the registers are correctly sign 1475extended. This predicate for the input operands accepts a 1476@code{sign_extend} of an @code{SImode} register. Write the constraint 1477to indicate the type of register that is required for the operand of the 1478@code{sign_extend}. 1479@end ifset 1480 1481@node Multi-Alternative 1482@subsection Multiple Alternative Constraints 1483@cindex multiple alternative constraints 1484 1485Sometimes a single instruction has multiple alternative sets of possible 1486operands. For example, on the 68000, a logical-or instruction can combine 1487register or an immediate value into memory, or it can combine any kind of 1488operand into a register; but it cannot combine one memory location into 1489another. 1490 1491These constraints are represented as multiple alternatives. An alternative 1492can be described by a series of letters for each operand. The overall 1493constraint for an operand is made from the letters for this operand 1494from the first alternative, a comma, the letters for this operand from 1495the second alternative, a comma, and so on until the last alternative. 1496All operands for a single instruction must have the same number of 1497alternatives. 1498@ifset INTERNALS 1499Here is how it is done for fullword logical-or on the 68000: 1500 1501@smallexample 1502(define_insn "iorsi3" 1503 [(set (match_operand:SI 0 "general_operand" "=m,d") 1504 (ior:SI (match_operand:SI 1 "general_operand" "%0,0") 1505 (match_operand:SI 2 "general_operand" "dKs,dmKs")))] 1506 @dots{}) 1507@end smallexample 1508 1509The first alternative has @samp{m} (memory) for operand 0, @samp{0} for 1510operand 1 (meaning it must match operand 0), and @samp{dKs} for operand 15112. The second alternative has @samp{d} (data register) for operand 0, 1512@samp{0} for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and 1513@samp{%} in the constraints apply to all the alternatives; their 1514meaning is explained in the next section (@pxref{Class Preferences}). 1515 1516If all the operands fit any one alternative, the instruction is valid. 1517Otherwise, for each alternative, the compiler counts how many instructions 1518must be added to copy the operands so that that alternative applies. 1519The alternative requiring the least copying is chosen. If two alternatives 1520need the same amount of copying, the one that comes first is chosen. 1521These choices can be altered with the @samp{?} and @samp{!} characters: 1522 1523@table @code 1524@cindex @samp{?} in constraint 1525@cindex question mark 1526@item ? 1527Disparage slightly the alternative that the @samp{?} appears in, 1528as a choice when no alternative applies exactly. The compiler regards 1529this alternative as one unit more costly for each @samp{?} that appears 1530in it. 1531 1532@cindex @samp{!} in constraint 1533@cindex exclamation point 1534@item ! 1535Disparage severely the alternative that the @samp{!} appears in. 1536This alternative can still be used if it fits without reloading, 1537but if reloading is needed, some other alternative will be used. 1538 1539@cindex @samp{^} in constraint 1540@cindex caret 1541@item ^ 1542This constraint is analogous to @samp{?} but it disparages slightly 1543the alternative only if the operand with the @samp{^} needs a reload. 1544 1545@cindex @samp{$} in constraint 1546@cindex dollar sign 1547@item $ 1548This constraint is analogous to @samp{!} but it disparages severely 1549the alternative only if the operand with the @samp{$} needs a reload. 1550@end table 1551 1552When an insn pattern has multiple alternatives in its constraints, often 1553the appearance of the assembler code is determined mostly by which 1554alternative was matched. When this is so, the C code for writing the 1555assembler code can use the variable @code{which_alternative}, which is 1556the ordinal number of the alternative that was actually satisfied (0 for 1557the first, 1 for the second alternative, etc.). @xref{Output Statement}. 1558@end ifset 1559@ifclear INTERNALS 1560 1561So the first alternative for the 68000's logical-or could be written as 1562@code{"+m" (output) : "ir" (input)}. The second could be @code{"+r" 1563(output): "irm" (input)}. However, the fact that two memory locations 1564cannot be used in a single instruction prevents simply using @code{"+rm" 1565(output) : "irm" (input)}. Using multi-alternatives, this might be 1566written as @code{"+m,r" (output) : "ir,irm" (input)}. This describes 1567all the available alternatives to the compiler, allowing it to choose 1568the most efficient one for the current conditions. 1569 1570There is no way within the template to determine which alternative was 1571chosen. However you may be able to wrap your @code{asm} statements with 1572builtins such as @code{__builtin_constant_p} to achieve the desired results. 1573@end ifclear 1574 1575@ifset INTERNALS 1576@node Class Preferences 1577@subsection Register Class Preferences 1578@cindex class preference constraints 1579@cindex register class preference constraints 1580 1581@cindex voting between constraint alternatives 1582The operand constraints have another function: they enable the compiler 1583to decide which kind of hardware register a pseudo register is best 1584allocated to. The compiler examines the constraints that apply to the 1585insns that use the pseudo register, looking for the machine-dependent 1586letters such as @samp{d} and @samp{a} that specify classes of registers. 1587The pseudo register is put in whichever class gets the most ``votes''. 1588The constraint letters @samp{g} and @samp{r} also vote: they vote in 1589favor of a general register. The machine description says which registers 1590are considered general. 1591 1592Of course, on some machines all registers are equivalent, and no register 1593classes are defined. Then none of this complexity is relevant. 1594@end ifset 1595 1596@node Modifiers 1597@subsection Constraint Modifier Characters 1598@cindex modifiers in constraints 1599@cindex constraint modifier characters 1600 1601@c prevent bad page break with this line 1602Here are constraint modifier characters. 1603 1604@table @samp 1605@cindex @samp{=} in constraint 1606@item = 1607Means that this operand is written to by this instruction: 1608the previous value is discarded and replaced by new data. 1609 1610@cindex @samp{+} in constraint 1611@item + 1612Means that this operand is both read and written by the instruction. 1613 1614When the compiler fixes up the operands to satisfy the constraints, 1615it needs to know which operands are read by the instruction and 1616which are written by it. @samp{=} identifies an operand which is only 1617written; @samp{+} identifies an operand that is both read and written; all 1618other operands are assumed to only be read. 1619 1620If you specify @samp{=} or @samp{+} in a constraint, you put it in the 1621first character of the constraint string. 1622 1623@cindex @samp{&} in constraint 1624@cindex earlyclobber operand 1625@item & 1626Means (in a particular alternative) that this operand is an 1627@dfn{earlyclobber} operand, which is written before the instruction is 1628finished using the input operands. Therefore, this operand may not lie 1629in a register that is read by the instruction or as part of any memory 1630address. 1631 1632@samp{&} applies only to the alternative in which it is written. In 1633constraints with multiple alternatives, sometimes one alternative 1634requires @samp{&} while others do not. See, for example, the 1635@samp{movdf} insn of the 68000. 1636 1637A operand which is read by the instruction can be tied to an earlyclobber 1638operand if its only use as an input occurs before the early result is 1639written. Adding alternatives of this form often allows GCC to produce 1640better code when only some of the read operands can be affected by the 1641earlyclobber. See, for example, the @samp{mulsi3} insn of the ARM@. 1642 1643Furthermore, if the @dfn{earlyclobber} operand is also a read/write 1644operand, then that operand is written only after it's used. 1645 1646@samp{&} does not obviate the need to write @samp{=} or @samp{+}. As 1647@dfn{earlyclobber} operands are always written, a read-only 1648@dfn{earlyclobber} operand is ill-formed and will be rejected by the 1649compiler. 1650 1651@cindex @samp{%} in constraint 1652@item % 1653Declares the instruction to be commutative for this operand and the 1654following operand. This means that the compiler may interchange the 1655two operands if that is the cheapest way to make all operands fit the 1656constraints. @samp{%} applies to all alternatives and must appear as 1657the first character in the constraint. Only read-only operands can use 1658@samp{%}. 1659 1660@ifset INTERNALS 1661This is often used in patterns for addition instructions 1662that really have only two operands: the result must go in one of the 1663arguments. Here for example, is how the 68000 halfword-add 1664instruction is defined: 1665 1666@smallexample 1667(define_insn "addhi3" 1668 [(set (match_operand:HI 0 "general_operand" "=m,r") 1669 (plus:HI (match_operand:HI 1 "general_operand" "%0,0") 1670 (match_operand:HI 2 "general_operand" "di,g")))] 1671 @dots{}) 1672@end smallexample 1673@end ifset 1674GCC can only handle one commutative pair in an asm; if you use more, 1675the compiler may fail. Note that you need not use the modifier if 1676the two alternatives are strictly identical; this would only waste 1677time in the reload pass. 1678@ifset INTERNALS 1679The modifier is not operational after 1680register allocation, so the result of @code{define_peephole2} 1681and @code{define_split}s performed after reload cannot rely on 1682@samp{%} to make the intended insn match. 1683 1684@cindex @samp{#} in constraint 1685@item # 1686Says that all following characters, up to the next comma, are to be 1687ignored as a constraint. They are significant only for choosing 1688register preferences. 1689 1690@cindex @samp{*} in constraint 1691@item * 1692Says that the following character should be ignored when choosing 1693register preferences. @samp{*} has no effect on the meaning of the 1694constraint as a constraint, and no effect on reloading. For LRA 1695@samp{*} additionally disparages slightly the alternative if the 1696following character matches the operand. 1697 1698Here is an example: the 68000 has an instruction to sign-extend a 1699halfword in a data register, and can also sign-extend a value by 1700copying it into an address register. While either kind of register is 1701acceptable, the constraints on an address-register destination are 1702less strict, so it is best if register allocation makes an address 1703register its goal. Therefore, @samp{*} is used so that the @samp{d} 1704constraint letter (for data register) is ignored when computing 1705register preferences. 1706 1707@smallexample 1708(define_insn "extendhisi2" 1709 [(set (match_operand:SI 0 "general_operand" "=*d,a") 1710 (sign_extend:SI 1711 (match_operand:HI 1 "general_operand" "0,g")))] 1712 @dots{}) 1713@end smallexample 1714@end ifset 1715@end table 1716 1717@node Machine Constraints 1718@subsection Constraints for Particular Machines 1719@cindex machine specific constraints 1720@cindex constraints, machine specific 1721 1722Whenever possible, you should use the general-purpose constraint letters 1723in @code{asm} arguments, since they will convey meaning more readily to 1724people reading your code. Failing that, use the constraint letters 1725that usually have very similar meanings across architectures. The most 1726commonly used constraints are @samp{m} and @samp{r} (for memory and 1727general-purpose registers respectively; @pxref{Simple Constraints}), and 1728@samp{I}, usually the letter indicating the most common 1729immediate-constant format. 1730 1731Each architecture defines additional constraints. These constraints 1732are used by the compiler itself for instruction generation, as well as 1733for @code{asm} statements; therefore, some of the constraints are not 1734particularly useful for @code{asm}. Here is a summary of some of the 1735machine-dependent constraints available on some particular machines; 1736it includes both constraints that are useful for @code{asm} and 1737constraints that aren't. The compiler source file mentioned in the 1738table heading for each architecture is the definitive reference for 1739the meanings of that architecture's constraints. 1740 1741@c Please keep this table alphabetized by target! 1742@table @emph 1743@item AArch64 family---@file{config/aarch64/constraints.md} 1744@table @code 1745@item k 1746The stack pointer register (@code{SP}) 1747 1748@item w 1749Floating point register, Advanced SIMD vector register or SVE vector register 1750 1751@item x 1752Like @code{w}, but restricted to registers 0 to 15 inclusive. 1753 1754@item y 1755Like @code{w}, but restricted to registers 0 to 7 inclusive. 1756 1757@item Upl 1758One of the low eight SVE predicate registers (@code{P0} to @code{P7}) 1759 1760@item Upa 1761Any of the SVE predicate registers (@code{P0} to @code{P15}) 1762 1763@item I 1764Integer constant that is valid as an immediate operand in an @code{ADD} 1765instruction 1766 1767@item J 1768Integer constant that is valid as an immediate operand in a @code{SUB} 1769instruction (once negated) 1770 1771@item K 1772Integer constant that can be used with a 32-bit logical instruction 1773 1774@item L 1775Integer constant that can be used with a 64-bit logical instruction 1776 1777@item M 1778Integer constant that is valid as an immediate operand in a 32-bit @code{MOV} 1779pseudo instruction. The @code{MOV} may be assembled to one of several different 1780machine instructions depending on the value 1781 1782@item N 1783Integer constant that is valid as an immediate operand in a 64-bit @code{MOV} 1784pseudo instruction 1785 1786@item S 1787An absolute symbolic address or a label reference 1788 1789@item Y 1790Floating point constant zero 1791 1792@item Z 1793Integer constant zero 1794 1795@item Ush 1796The high part (bits 12 and upwards) of the pc-relative address of a symbol 1797within 4GB of the instruction 1798 1799@item Q 1800A memory address which uses a single base register with no offset 1801 1802@item Ump 1803A memory address suitable for a load/store pair instruction in SI, DI, SF and 1804DF modes 1805 1806@end table 1807 1808 1809@item AMD GCN ---@file{config/gcn/constraints.md} 1810@table @code 1811@item I 1812Immediate integer in the range @minus{}16 to 64 1813 1814@item J 1815Immediate 16-bit signed integer 1816 1817@item Kf 1818Immediate constant @minus{}1 1819 1820@item L 1821Immediate 15-bit unsigned integer 1822 1823@item A 1824Immediate constant that can be inlined in an instruction encoding: integer 1825@minus{}16..64, or float 0.0, +/@minus{}0.5, +/@minus{}1.0, +/@minus{}2.0, 1826+/@minus{}4.0, 1.0/(2.0*PI) 1827 1828@item B 1829Immediate 32-bit signed integer that can be attached to an instruction encoding 1830 1831@item C 1832Immediate 32-bit integer in range @minus{}16..4294967295 (i.e. 32-bit unsigned 1833integer or @samp{A} constraint) 1834 1835@item DA 1836Immediate 64-bit constant that can be split into two @samp{A} constants 1837 1838@item DB 1839Immediate 64-bit constant that can be split into two @samp{B} constants 1840 1841@item U 1842Any @code{unspec} 1843 1844@item Y 1845Any @code{symbol_ref} or @code{label_ref} 1846 1847@item v 1848VGPR register 1849 1850@item Sg 1851SGPR register 1852 1853@item SD 1854SGPR registers valid for instruction destinations, including VCC, M0 and EXEC 1855 1856@item SS 1857SGPR registers valid for instruction sources, including VCC, M0, EXEC and SCC 1858 1859@item Sm 1860SGPR registers valid as a source for scalar memory instructions (excludes M0 1861and EXEC) 1862 1863@item Sv 1864SGPR registers valid as a source or destination for vector instructions 1865(excludes EXEC) 1866 1867@item ca 1868All condition registers: SCC, VCCZ, EXECZ 1869 1870@item cs 1871Scalar condition register: SCC 1872 1873@item cV 1874Vector condition register: VCC, VCC_LO, VCC_HI 1875 1876@item e 1877EXEC register (EXEC_LO and EXEC_HI) 1878 1879@item RB 1880Memory operand with address space suitable for @code{buffer_*} instructions 1881 1882@item RF 1883Memory operand with address space suitable for @code{flat_*} instructions 1884 1885@item RS 1886Memory operand with address space suitable for @code{s_*} instructions 1887 1888@item RL 1889Memory operand with address space suitable for @code{ds_*} LDS instructions 1890 1891@item RG 1892Memory operand with address space suitable for @code{ds_*} GDS instructions 1893 1894@item RD 1895Memory operand with address space suitable for any @code{ds_*} instructions 1896 1897@item RM 1898Memory operand with address space suitable for @code{global_*} instructions 1899 1900@end table 1901 1902 1903@item ARC ---@file{config/arc/constraints.md} 1904@table @code 1905@item q 1906Registers usable in ARCompact 16-bit instructions: @code{r0}-@code{r3}, 1907@code{r12}-@code{r15}. This constraint can only match when the @option{-mq} 1908option is in effect. 1909 1910@item e 1911Registers usable as base-regs of memory addresses in ARCompact 16-bit memory 1912instructions: @code{r0}-@code{r3}, @code{r12}-@code{r15}, @code{sp}. 1913This constraint can only match when the @option{-mq} 1914option is in effect. 1915@item D 1916ARC FPX (dpfp) 64-bit registers. @code{D0}, @code{D1}. 1917 1918@item I 1919A signed 12-bit integer constant. 1920 1921@item Cal 1922constant for arithmetic/logical operations. This might be any constant 1923that can be put into a long immediate by the assmbler or linker without 1924involving a PIC relocation. 1925 1926@item K 1927A 3-bit unsigned integer constant. 1928 1929@item L 1930A 6-bit unsigned integer constant. 1931 1932@item CnL 1933One's complement of a 6-bit unsigned integer constant. 1934 1935@item CmL 1936Two's complement of a 6-bit unsigned integer constant. 1937 1938@item M 1939A 5-bit unsigned integer constant. 1940 1941@item O 1942A 7-bit unsigned integer constant. 1943 1944@item P 1945A 8-bit unsigned integer constant. 1946 1947@item H 1948Any const_double value. 1949@end table 1950 1951@item ARM family---@file{config/arm/constraints.md} 1952@table @code 1953 1954@item h 1955In Thumb state, the core registers @code{r8}-@code{r15}. 1956 1957@item k 1958The stack pointer register. 1959 1960@item l 1961In Thumb State the core registers @code{r0}-@code{r7}. In ARM state this 1962is an alias for the @code{r} constraint. 1963 1964@item t 1965VFP floating-point registers @code{s0}-@code{s31}. Used for 32 bit values. 1966 1967@item w 1968VFP floating-point registers @code{d0}-@code{d31} and the appropriate 1969subset @code{d0}-@code{d15} based on command line options. 1970Used for 64 bit values only. Not valid for Thumb1. 1971 1972@item y 1973The iWMMX co-processor registers. 1974 1975@item z 1976The iWMMX GR registers. 1977 1978@item G 1979The floating-point constant 0.0 1980 1981@item I 1982Integer that is valid as an immediate operand in a data processing 1983instruction. That is, an integer in the range 0 to 255 rotated by a 1984multiple of 2 1985 1986@item J 1987Integer in the range @minus{}4095 to 4095 1988 1989@item K 1990Integer that satisfies constraint @samp{I} when inverted (ones complement) 1991 1992@item L 1993Integer that satisfies constraint @samp{I} when negated (twos complement) 1994 1995@item M 1996Integer in the range 0 to 32 1997 1998@item Q 1999A memory reference where the exact address is in a single register 2000(`@samp{m}' is preferable for @code{asm} statements) 2001 2002@item R 2003An item in the constant pool 2004 2005@item S 2006A symbol in the text segment of the current file 2007 2008@item Uv 2009A memory reference suitable for VFP load/store insns (reg+constant offset) 2010 2011@item Uy 2012A memory reference suitable for iWMMXt load/store instructions. 2013 2014@item Uq 2015A memory reference suitable for the ARMv4 ldrsb instruction. 2016@end table 2017 2018@item AVR family---@file{config/avr/constraints.md} 2019@table @code 2020@item l 2021Registers from r0 to r15 2022 2023@item a 2024Registers from r16 to r23 2025 2026@item d 2027Registers from r16 to r31 2028 2029@item w 2030Registers from r24 to r31. These registers can be used in @samp{adiw} command 2031 2032@item e 2033Pointer register (r26--r31) 2034 2035@item b 2036Base pointer register (r28--r31) 2037 2038@item q 2039Stack pointer register (SPH:SPL) 2040 2041@item t 2042Temporary register r0 2043 2044@item x 2045Register pair X (r27:r26) 2046 2047@item y 2048Register pair Y (r29:r28) 2049 2050@item z 2051Register pair Z (r31:r30) 2052 2053@item I 2054Constant greater than @minus{}1, less than 64 2055 2056@item J 2057Constant greater than @minus{}64, less than 1 2058 2059@item K 2060Constant integer 2 2061 2062@item L 2063Constant integer 0 2064 2065@item M 2066Constant that fits in 8 bits 2067 2068@item N 2069Constant integer @minus{}1 2070 2071@item O 2072Constant integer 8, 16, or 24 2073 2074@item P 2075Constant integer 1 2076 2077@item G 2078A floating point constant 0.0 2079 2080@item Q 2081A memory address based on Y or Z pointer with displacement. 2082@end table 2083 2084@item Blackfin family---@file{config/bfin/constraints.md} 2085@table @code 2086@item a 2087P register 2088 2089@item d 2090D register 2091 2092@item z 2093A call clobbered P register. 2094 2095@item q@var{n} 2096A single register. If @var{n} is in the range 0 to 7, the corresponding D 2097register. If it is @code{A}, then the register P0. 2098 2099@item D 2100Even-numbered D register 2101 2102@item W 2103Odd-numbered D register 2104 2105@item e 2106Accumulator register. 2107 2108@item A 2109Even-numbered accumulator register. 2110 2111@item B 2112Odd-numbered accumulator register. 2113 2114@item b 2115I register 2116 2117@item v 2118B register 2119 2120@item f 2121M register 2122 2123@item c 2124Registers used for circular buffering, i.e.@: I, B, or L registers. 2125 2126@item C 2127The CC register. 2128 2129@item t 2130LT0 or LT1. 2131 2132@item k 2133LC0 or LC1. 2134 2135@item u 2136LB0 or LB1. 2137 2138@item x 2139Any D, P, B, M, I or L register. 2140 2141@item y 2142Additional registers typically used only in prologues and epilogues: RETS, 2143RETN, RETI, RETX, RETE, ASTAT, SEQSTAT and USP. 2144 2145@item w 2146Any register except accumulators or CC. 2147 2148@item Ksh 2149Signed 16 bit integer (in the range @minus{}32768 to 32767) 2150 2151@item Kuh 2152Unsigned 16 bit integer (in the range 0 to 65535) 2153 2154@item Ks7 2155Signed 7 bit integer (in the range @minus{}64 to 63) 2156 2157@item Ku7 2158Unsigned 7 bit integer (in the range 0 to 127) 2159 2160@item Ku5 2161Unsigned 5 bit integer (in the range 0 to 31) 2162 2163@item Ks4 2164Signed 4 bit integer (in the range @minus{}8 to 7) 2165 2166@item Ks3 2167Signed 3 bit integer (in the range @minus{}3 to 4) 2168 2169@item Ku3 2170Unsigned 3 bit integer (in the range 0 to 7) 2171 2172@item P@var{n} 2173Constant @var{n}, where @var{n} is a single-digit constant in the range 0 to 4. 2174 2175@item PA 2176An integer equal to one of the MACFLAG_XXX constants that is suitable for 2177use with either accumulator. 2178 2179@item PB 2180An integer equal to one of the MACFLAG_XXX constants that is suitable for 2181use only with accumulator A1. 2182 2183@item M1 2184Constant 255. 2185 2186@item M2 2187Constant 65535. 2188 2189@item J 2190An integer constant with exactly a single bit set. 2191 2192@item L 2193An integer constant with all bits set except exactly one. 2194 2195@item H 2196 2197@item Q 2198Any SYMBOL_REF. 2199@end table 2200 2201@item CR16 Architecture---@file{config/cr16/cr16.h} 2202@table @code 2203 2204@item b 2205Registers from r0 to r14 (registers without stack pointer) 2206 2207@item t 2208Register from r0 to r11 (all 16-bit registers) 2209 2210@item p 2211Register from r12 to r15 (all 32-bit registers) 2212 2213@item I 2214Signed constant that fits in 4 bits 2215 2216@item J 2217Signed constant that fits in 5 bits 2218 2219@item K 2220Signed constant that fits in 6 bits 2221 2222@item L 2223Unsigned constant that fits in 4 bits 2224 2225@item M 2226Signed constant that fits in 32 bits 2227 2228@item N 2229Check for 64 bits wide constants for add/sub instructions 2230 2231@item G 2232Floating point constant that is legal for store immediate 2233@end table 2234 2235@item C-SKY---@file{config/csky/constraints.md} 2236@table @code 2237 2238@item a 2239The mini registers r0 - r7. 2240 2241@item b 2242The low registers r0 - r15. 2243 2244@item c 2245C register. 2246 2247@item y 2248HI and LO registers. 2249 2250@item l 2251LO register. 2252 2253@item h 2254HI register. 2255 2256@item v 2257Vector registers. 2258 2259@item z 2260Stack pointer register (SP). 2261@end table 2262 2263@ifset INTERNALS 2264The C-SKY back end supports a large set of additional constraints 2265that are only useful for instruction selection or splitting rather 2266than inline asm, such as constraints representing constant integer 2267ranges accepted by particular instruction encodings. 2268Refer to the source code for details. 2269@end ifset 2270 2271@item Epiphany---@file{config/epiphany/constraints.md} 2272@table @code 2273@item U16 2274An unsigned 16-bit constant. 2275 2276@item K 2277An unsigned 5-bit constant. 2278 2279@item L 2280A signed 11-bit constant. 2281 2282@item Cm1 2283A signed 11-bit constant added to @minus{}1. 2284Can only match when the @option{-m1reg-@var{reg}} option is active. 2285 2286@item Cl1 2287Left-shift of @minus{}1, i.e., a bit mask with a block of leading ones, the rest 2288being a block of trailing zeroes. 2289Can only match when the @option{-m1reg-@var{reg}} option is active. 2290 2291@item Cr1 2292Right-shift of @minus{}1, i.e., a bit mask with a trailing block of ones, the 2293rest being zeroes. Or to put it another way, one less than a power of two. 2294Can only match when the @option{-m1reg-@var{reg}} option is active. 2295 2296@item Cal 2297Constant for arithmetic/logical operations. 2298This is like @code{i}, except that for position independent code, 2299no symbols / expressions needing relocations are allowed. 2300 2301@item Csy 2302Symbolic constant for call/jump instruction. 2303 2304@item Rcs 2305The register class usable in short insns. This is a register class 2306constraint, and can thus drive register allocation. 2307This constraint won't match unless @option{-mprefer-short-insn-regs} is 2308in effect. 2309 2310@item Rsc 2311The the register class of registers that can be used to hold a 2312sibcall call address. I.e., a caller-saved register. 2313 2314@item Rct 2315Core control register class. 2316 2317@item Rgs 2318The register group usable in short insns. 2319This constraint does not use a register class, so that it only 2320passively matches suitable registers, and doesn't drive register allocation. 2321 2322@ifset INTERNALS 2323@item Car 2324Constant suitable for the addsi3_r pattern. This is a valid offset 2325For byte, halfword, or word addressing. 2326@end ifset 2327 2328@item Rra 2329Matches the return address if it can be replaced with the link register. 2330 2331@item Rcc 2332Matches the integer condition code register. 2333 2334@item Sra 2335Matches the return address if it is in a stack slot. 2336 2337@item Cfm 2338Matches control register values to switch fp mode, which are encapsulated in 2339@code{UNSPEC_FP_MODE}. 2340@end table 2341 2342@item FRV---@file{config/frv/frv.h} 2343@table @code 2344@item a 2345Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}). 2346 2347@item b 2348Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}). 2349 2350@item c 2351Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and 2352@code{icc0} to @code{icc3}). 2353 2354@item d 2355Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}). 2356 2357@item e 2358Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}). 2359Odd registers are excluded not in the class but through the use of a machine 2360mode larger than 4 bytes. 2361 2362@item f 2363Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}). 2364 2365@item h 2366Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}). 2367Odd registers are excluded not in the class but through the use of a machine 2368mode larger than 4 bytes. 2369 2370@item l 2371Register in the class @code{LR_REG} (the @code{lr} register). 2372 2373@item q 2374Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}). 2375Register numbers not divisible by 4 are excluded not in the class but through 2376the use of a machine mode larger than 8 bytes. 2377 2378@item t 2379Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}). 2380 2381@item u 2382Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}). 2383 2384@item v 2385Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}). 2386 2387@item w 2388Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}). 2389 2390@item x 2391Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}). 2392Register numbers not divisible by 4 are excluded not in the class but through 2393the use of a machine mode larger than 8 bytes. 2394 2395@item z 2396Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}). 2397 2398@item A 2399Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}). 2400 2401@item B 2402Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}). 2403 2404@item C 2405Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}). 2406 2407@item G 2408Floating point constant zero 2409 2410@item I 24116-bit signed integer constant 2412 2413@item J 241410-bit signed integer constant 2415 2416@item L 241716-bit signed integer constant 2418 2419@item M 242016-bit unsigned integer constant 2421 2422@item N 242312-bit signed integer constant that is negative---i.e.@: in the 2424range of @minus{}2048 to @minus{}1 2425 2426@item O 2427Constant zero 2428 2429@item P 243012-bit signed integer constant that is greater than zero---i.e.@: in the 2431range of 1 to 2047. 2432 2433@end table 2434 2435@item FT32---@file{config/ft32/constraints.md} 2436@table @code 2437@item A 2438An absolute address 2439 2440@item B 2441An offset address 2442 2443@item W 2444A register indirect memory operand 2445 2446@item e 2447An offset address. 2448 2449@item f 2450An offset address. 2451 2452@item O 2453The constant zero or one 2454 2455@item I 2456A 16-bit signed constant (@minus{}32768 @dots{} 32767) 2457 2458@item w 2459A bitfield mask suitable for bext or bins 2460 2461@item x 2462An inverted bitfield mask suitable for bext or bins 2463 2464@item L 2465A 16-bit unsigned constant, multiple of 4 (0 @dots{} 65532) 2466 2467@item S 2468A 20-bit signed constant (@minus{}524288 @dots{} 524287) 2469 2470@item b 2471A constant for a bitfield width (1 @dots{} 16) 2472 2473@item KA 2474A 10-bit signed constant (@minus{}512 @dots{} 511) 2475 2476@end table 2477 2478@item Hewlett-Packard PA-RISC---@file{config/pa/pa.h} 2479@table @code 2480@item a 2481General register 1 2482 2483@item f 2484Floating point register 2485 2486@item q 2487Shift amount register 2488 2489@item x 2490Floating point register (deprecated) 2491 2492@item y 2493Upper floating point register (32-bit), floating point register (64-bit) 2494 2495@item Z 2496Any register 2497 2498@item I 2499Signed 11-bit integer constant 2500 2501@item J 2502Signed 14-bit integer constant 2503 2504@item K 2505Integer constant that can be deposited with a @code{zdepi} instruction 2506 2507@item L 2508Signed 5-bit integer constant 2509 2510@item M 2511Integer constant 0 2512 2513@item N 2514Integer constant that can be loaded with a @code{ldil} instruction 2515 2516@item O 2517Integer constant whose value plus one is a power of 2 2518 2519@item P 2520Integer constant that can be used for @code{and} operations in @code{depi} 2521and @code{extru} instructions 2522 2523@item S 2524Integer constant 31 2525 2526@item U 2527Integer constant 63 2528 2529@item G 2530Floating-point constant 0.0 2531 2532@item A 2533A @code{lo_sum} data-linkage-table memory operand 2534 2535@item Q 2536A memory operand that can be used as the destination operand of an 2537integer store instruction 2538 2539@item R 2540A scaled or unscaled indexed memory operand 2541 2542@item T 2543A memory operand for floating-point loads and stores 2544 2545@item W 2546A register indirect memory operand 2547@end table 2548 2549@item Intel IA-64---@file{config/ia64/ia64.h} 2550@table @code 2551@item a 2552General register @code{r0} to @code{r3} for @code{addl} instruction 2553 2554@item b 2555Branch register 2556 2557@item c 2558Predicate register (@samp{c} as in ``conditional'') 2559 2560@item d 2561Application register residing in M-unit 2562 2563@item e 2564Application register residing in I-unit 2565 2566@item f 2567Floating-point register 2568 2569@item m 2570Memory operand. If used together with @samp{<} or @samp{>}, 2571the operand can have postincrement and postdecrement which 2572require printing with @samp{%Pn} on IA-64. 2573 2574@item G 2575Floating-point constant 0.0 or 1.0 2576 2577@item I 257814-bit signed integer constant 2579 2580@item J 258122-bit signed integer constant 2582 2583@item K 25848-bit signed integer constant for logical instructions 2585 2586@item L 25878-bit adjusted signed integer constant for compare pseudo-ops 2588 2589@item M 25906-bit unsigned integer constant for shift counts 2591 2592@item N 25939-bit signed integer constant for load and store postincrements 2594 2595@item O 2596The constant zero 2597 2598@item P 25990 or @minus{}1 for @code{dep} instruction 2600 2601@item Q 2602Non-volatile memory for floating-point loads and stores 2603 2604@item R 2605Integer constant in the range 1 to 4 for @code{shladd} instruction 2606 2607@item S 2608Memory operand except postincrement and postdecrement. This is 2609now roughly the same as @samp{m} when not used together with @samp{<} 2610or @samp{>}. 2611@end table 2612 2613@item M32C---@file{config/m32c/m32c.c} 2614@table @code 2615@item Rsp 2616@itemx Rfb 2617@itemx Rsb 2618@samp{$sp}, @samp{$fb}, @samp{$sb}. 2619 2620@item Rcr 2621Any control register, when they're 16 bits wide (nothing if control 2622registers are 24 bits wide) 2623 2624@item Rcl 2625Any control register, when they're 24 bits wide. 2626 2627@item R0w 2628@itemx R1w 2629@itemx R2w 2630@itemx R3w 2631$r0, $r1, $r2, $r3. 2632 2633@item R02 2634$r0 or $r2, or $r2r0 for 32 bit values. 2635 2636@item R13 2637$r1 or $r3, or $r3r1 for 32 bit values. 2638 2639@item Rdi 2640A register that can hold a 64 bit value. 2641 2642@item Rhl 2643$r0 or $r1 (registers with addressable high/low bytes) 2644 2645@item R23 2646$r2 or $r3 2647 2648@item Raa 2649Address registers 2650 2651@item Raw 2652Address registers when they're 16 bits wide. 2653 2654@item Ral 2655Address registers when they're 24 bits wide. 2656 2657@item Rqi 2658Registers that can hold QI values. 2659 2660@item Rad 2661Registers that can be used with displacements ($a0, $a1, $sb). 2662 2663@item Rsi 2664Registers that can hold 32 bit values. 2665 2666@item Rhi 2667Registers that can hold 16 bit values. 2668 2669@item Rhc 2670Registers chat can hold 16 bit values, including all control 2671registers. 2672 2673@item Rra 2674$r0 through R1, plus $a0 and $a1. 2675 2676@item Rfl 2677The flags register. 2678 2679@item Rmm 2680The memory-based pseudo-registers $mem0 through $mem15. 2681 2682@item Rpi 2683Registers that can hold pointers (16 bit registers for r8c, m16c; 24 2684bit registers for m32cm, m32c). 2685 2686@item Rpa 2687Matches multiple registers in a PARALLEL to form a larger register. 2688Used to match function return values. 2689 2690@item Is3 2691@minus{}8 @dots{} 7 2692 2693@item IS1 2694@minus{}128 @dots{} 127 2695 2696@item IS2 2697@minus{}32768 @dots{} 32767 2698 2699@item IU2 27000 @dots{} 65535 2701 2702@item In4 2703@minus{}8 @dots{} @minus{}1 or 1 @dots{} 8 2704 2705@item In5 2706@minus{}16 @dots{} @minus{}1 or 1 @dots{} 16 2707 2708@item In6 2709@minus{}32 @dots{} @minus{}1 or 1 @dots{} 32 2710 2711@item IM2 2712@minus{}65536 @dots{} @minus{}1 2713 2714@item Ilb 2715An 8 bit value with exactly one bit set. 2716 2717@item Ilw 2718A 16 bit value with exactly one bit set. 2719 2720@item Sd 2721The common src/dest memory addressing modes. 2722 2723@item Sa 2724Memory addressed using $a0 or $a1. 2725 2726@item Si 2727Memory addressed with immediate addresses. 2728 2729@item Ss 2730Memory addressed using the stack pointer ($sp). 2731 2732@item Sf 2733Memory addressed using the frame base register ($fb). 2734 2735@item Ss 2736Memory addressed using the small base register ($sb). 2737 2738@item S1 2739$r1h 2740@end table 2741 2742@item MicroBlaze---@file{config/microblaze/constraints.md} 2743@table @code 2744@item d 2745A general register (@code{r0} to @code{r31}). 2746 2747@item z 2748A status register (@code{rmsr}, @code{$fcc1} to @code{$fcc7}). 2749 2750@end table 2751 2752@item MIPS---@file{config/mips/constraints.md} 2753@table @code 2754@item d 2755A general-purpose register. This is equivalent to @code{r} unless 2756generating MIPS16 code, in which case the MIPS16 register set is used. 2757 2758@item f 2759A floating-point register (if available). 2760 2761@item h 2762Formerly the @code{hi} register. This constraint is no longer supported. 2763 2764@item l 2765The @code{lo} register. Use this register to store values that are 2766no bigger than a word. 2767 2768@item x 2769The concatenated @code{hi} and @code{lo} registers. Use this register 2770to store doubleword values. 2771 2772@item c 2773A register suitable for use in an indirect jump. This will always be 2774@code{$25} for @option{-mabicalls}. 2775 2776@item v 2777Register @code{$3}. Do not use this constraint in new code; 2778it is retained only for compatibility with glibc. 2779 2780@item y 2781Equivalent to @code{r}; retained for backwards compatibility. 2782 2783@item z 2784A floating-point condition code register. 2785 2786@item I 2787A signed 16-bit constant (for arithmetic instructions). 2788 2789@item J 2790Integer zero. 2791 2792@item K 2793An unsigned 16-bit constant (for logic instructions). 2794 2795@item L 2796A signed 32-bit constant in which the lower 16 bits are zero. 2797Such constants can be loaded using @code{lui}. 2798 2799@item M 2800A constant that cannot be loaded using @code{lui}, @code{addiu} 2801or @code{ori}. 2802 2803@item N 2804A constant in the range @minus{}65535 to @minus{}1 (inclusive). 2805 2806@item O 2807A signed 15-bit constant. 2808 2809@item P 2810A constant in the range 1 to 65535 (inclusive). 2811 2812@item G 2813Floating-point zero. 2814 2815@item R 2816An address that can be used in a non-macro load or store. 2817 2818@item ZC 2819A memory operand whose address is formed by a base register and offset 2820that is suitable for use in instructions with the same addressing mode 2821as @code{ll} and @code{sc}. 2822 2823@item ZD 2824An address suitable for a @code{prefetch} instruction, or for any other 2825instruction with the same addressing mode as @code{prefetch}. 2826@end table 2827 2828@item Motorola 680x0---@file{config/m68k/constraints.md} 2829@table @code 2830@item a 2831Address register 2832 2833@item d 2834Data register 2835 2836@item f 283768881 floating-point register, if available 2838 2839@item I 2840Integer in the range 1 to 8 2841 2842@item J 284316-bit signed number 2844 2845@item K 2846Signed number whose magnitude is greater than 0x80 2847 2848@item L 2849Integer in the range @minus{}8 to @minus{}1 2850 2851@item M 2852Signed number whose magnitude is greater than 0x100 2853 2854@item N 2855Range 24 to 31, rotatert:SI 8 to 1 expressed as rotate 2856 2857@item O 285816 (for rotate using swap) 2859 2860@item P 2861Range 8 to 15, rotatert:HI 8 to 1 expressed as rotate 2862 2863@item R 2864Numbers that mov3q can handle 2865 2866@item G 2867Floating point constant that is not a 68881 constant 2868 2869@item S 2870Operands that satisfy 'm' when -mpcrel is in effect 2871 2872@item T 2873Operands that satisfy 's' when -mpcrel is not in effect 2874 2875@item Q 2876Address register indirect addressing mode 2877 2878@item U 2879Register offset addressing 2880 2881@item W 2882const_call_operand 2883 2884@item Cs 2885symbol_ref or const 2886 2887@item Ci 2888const_int 2889 2890@item C0 2891const_int 0 2892 2893@item Cj 2894Range of signed numbers that don't fit in 16 bits 2895 2896@item Cmvq 2897Integers valid for mvq 2898 2899@item Capsw 2900Integers valid for a moveq followed by a swap 2901 2902@item Cmvz 2903Integers valid for mvz 2904 2905@item Cmvs 2906Integers valid for mvs 2907 2908@item Ap 2909push_operand 2910 2911@item Ac 2912Non-register operands allowed in clr 2913 2914@end table 2915 2916@item Moxie---@file{config/moxie/constraints.md} 2917@table @code 2918@item A 2919An absolute address 2920 2921@item B 2922An offset address 2923 2924@item W 2925A register indirect memory operand 2926 2927@item I 2928A constant in the range of 0 to 255. 2929 2930@item N 2931A constant in the range of 0 to @minus{}255. 2932 2933@end table 2934 2935@item MSP430--@file{config/msp430/constraints.md} 2936@table @code 2937 2938@item R12 2939Register R12. 2940 2941@item R13 2942Register R13. 2943 2944@item K 2945Integer constant 1. 2946 2947@item L 2948Integer constant -1^20..1^19. 2949 2950@item M 2951Integer constant 1-4. 2952 2953@item Ya 2954Memory references which do not require an extended MOVX instruction. 2955 2956@item Yl 2957Memory reference, labels only. 2958 2959@item Ys 2960Memory reference, stack only. 2961 2962@end table 2963 2964@item NDS32---@file{config/nds32/constraints.md} 2965@table @code 2966@item w 2967LOW register class $r0 to $r7 constraint for V3/V3M ISA. 2968@item l 2969LOW register class $r0 to $r7. 2970@item d 2971MIDDLE register class $r0 to $r11, $r16 to $r19. 2972@item h 2973HIGH register class $r12 to $r14, $r20 to $r31. 2974@item t 2975Temporary assist register $ta (i.e.@: $r15). 2976@item k 2977Stack register $sp. 2978@item Iu03 2979Unsigned immediate 3-bit value. 2980@item In03 2981Negative immediate 3-bit value in the range of @minus{}7--0. 2982@item Iu04 2983Unsigned immediate 4-bit value. 2984@item Is05 2985Signed immediate 5-bit value. 2986@item Iu05 2987Unsigned immediate 5-bit value. 2988@item In05 2989Negative immediate 5-bit value in the range of @minus{}31--0. 2990@item Ip05 2991Unsigned immediate 5-bit value for movpi45 instruction with range 16--47. 2992@item Iu06 2993Unsigned immediate 6-bit value constraint for addri36.sp instruction. 2994@item Iu08 2995Unsigned immediate 8-bit value. 2996@item Iu09 2997Unsigned immediate 9-bit value. 2998@item Is10 2999Signed immediate 10-bit value. 3000@item Is11 3001Signed immediate 11-bit value. 3002@item Is15 3003Signed immediate 15-bit value. 3004@item Iu15 3005Unsigned immediate 15-bit value. 3006@item Ic15 3007A constant which is not in the range of imm15u but ok for bclr instruction. 3008@item Ie15 3009A constant which is not in the range of imm15u but ok for bset instruction. 3010@item It15 3011A constant which is not in the range of imm15u but ok for btgl instruction. 3012@item Ii15 3013A constant whose compliment value is in the range of imm15u 3014and ok for bitci instruction. 3015@item Is16 3016Signed immediate 16-bit value. 3017@item Is17 3018Signed immediate 17-bit value. 3019@item Is19 3020Signed immediate 19-bit value. 3021@item Is20 3022Signed immediate 20-bit value. 3023@item Ihig 3024The immediate value that can be simply set high 20-bit. 3025@item Izeb 3026The immediate value 0xff. 3027@item Izeh 3028The immediate value 0xffff. 3029@item Ixls 3030The immediate value 0x01. 3031@item Ix11 3032The immediate value 0x7ff. 3033@item Ibms 3034The immediate value with power of 2. 3035@item Ifex 3036The immediate value with power of 2 minus 1. 3037@item U33 3038Memory constraint for 333 format. 3039@item U45 3040Memory constraint for 45 format. 3041@item U37 3042Memory constraint for 37 format. 3043@end table 3044 3045@item Nios II family---@file{config/nios2/constraints.md} 3046@table @code 3047 3048@item I 3049Integer that is valid as an immediate operand in an 3050instruction taking a signed 16-bit number. Range 3051@minus{}32768 to 32767. 3052 3053@item J 3054Integer that is valid as an immediate operand in an 3055instruction taking an unsigned 16-bit number. Range 30560 to 65535. 3057 3058@item K 3059Integer that is valid as an immediate operand in an 3060instruction taking only the upper 16-bits of a 306132-bit number. Range 32-bit numbers with the lower 306216-bits being 0. 3063 3064@item L 3065Integer that is valid as an immediate operand for a 3066shift instruction. Range 0 to 31. 3067 3068@item M 3069Integer that is valid as an immediate operand for 3070only the value 0. Can be used in conjunction with 3071the format modifier @code{z} to use @code{r0} 3072instead of @code{0} in the assembly output. 3073 3074@item N 3075Integer that is valid as an immediate operand for 3076a custom instruction opcode. Range 0 to 255. 3077 3078@item P 3079An immediate operand for R2 andchi/andci instructions. 3080 3081@item S 3082Matches immediates which are addresses in the small 3083data section and therefore can be added to @code{gp} 3084as a 16-bit immediate to re-create their 32-bit value. 3085 3086@item U 3087Matches constants suitable as an operand for the rdprs and 3088cache instructions. 3089 3090@item v 3091A memory operand suitable for Nios II R2 load/store 3092exclusive instructions. 3093 3094@item w 3095A memory operand suitable for load/store IO and cache 3096instructions. 3097 3098@ifset INTERNALS 3099@item T 3100A @code{const} wrapped @code{UNSPEC} expression, 3101representing a supported PIC or TLS relocation. 3102@end ifset 3103 3104@end table 3105 3106@item OpenRISC---@file{config/or1k/constraints.md} 3107@table @code 3108@item I 3109Integer that is valid as an immediate operand in an 3110instruction taking a signed 16-bit number. Range 3111@minus{}32768 to 32767. 3112 3113@item K 3114Integer that is valid as an immediate operand in an 3115instruction taking an unsigned 16-bit number. Range 31160 to 65535. 3117 3118@item M 3119Signed 16-bit constant shifted left 16 bits. (Used with @code{l.movhi}) 3120 3121@item O 3122Zero 3123 3124@ifset INTERNALS 3125@item c 3126Register usable for sibcalls. 3127@end ifset 3128 3129@end table 3130 3131@item PDP-11---@file{config/pdp11/constraints.md} 3132@table @code 3133@item a 3134Floating point registers AC0 through AC3. These can be loaded from/to 3135memory with a single instruction. 3136 3137@item d 3138Odd numbered general registers (R1, R3, R5). These are used for 313916-bit multiply operations. 3140 3141@item D 3142A memory reference that is encoded within the opcode, but not 3143auto-increment or auto-decrement. 3144 3145@item f 3146Any of the floating point registers (AC0 through AC5). 3147 3148@item G 3149Floating point constant 0. 3150 3151@item h 3152Floating point registers AC4 and AC5. These cannot be loaded from/to 3153memory with a single instruction. 3154 3155@item I 3156An integer constant that fits in 16 bits. 3157 3158@item J 3159An integer constant whose low order 16 bits are zero. 3160 3161@item K 3162An integer constant that does not meet the constraints for codes 3163@samp{I} or @samp{J}. 3164 3165@item L 3166The integer constant 1. 3167 3168@item M 3169The integer constant @minus{}1. 3170 3171@item N 3172The integer constant 0. 3173 3174@item O 3175Integer constants 0 through 3; shifts by these 3176amounts are handled as multiple single-bit shifts rather than a single 3177variable-length shift. 3178 3179@item Q 3180A memory reference which requires an additional word (address or 3181offset) after the opcode. 3182 3183@item R 3184A memory reference that is encoded within the opcode. 3185 3186@end table 3187 3188@item PowerPC and IBM RS6000---@file{config/rs6000/constraints.md} 3189@table @code 3190@item r 3191A general purpose register (GPR), @code{r0}@dots{}@code{r31}. 3192 3193@item b 3194A base register. Like @code{r}, but @code{r0} is not allowed, so 3195@code{r1}@dots{}@code{r31}. 3196 3197@item f 3198A floating point register (FPR), @code{f0}@dots{}@code{f31}. 3199 3200@item d 3201A floating point register. This is the same as @code{f} nowadays; 3202historically @code{f} was for single-precision and @code{d} was for 3203double-precision floating point. 3204 3205@item v 3206An Altivec vector register (VR), @code{v0}@dots{}@code{v31}. 3207 3208@item wa 3209A VSX register (VSR), @code{vs0}@dots{}@code{vs63}. This is either an 3210FPR (@code{vs0}@dots{}@code{vs31} are @code{f0}@dots{}@code{f31}) or a VR 3211(@code{vs32}@dots{}@code{vs63} are @code{v0}@dots{}@code{v31}). 3212 3213When using @code{wa}, you should use the @code{%x} output modifier, so that 3214the correct register number is printed. For example: 3215 3216@smallexample 3217asm ("xvadddp %x0,%x1,%x2" 3218 : "=wa" (v1) 3219 : "wa" (v2), "wa" (v3)); 3220@end smallexample 3221 3222You should not use @code{%x} for @code{v} operands: 3223 3224@smallexample 3225asm ("xsaddqp %0,%1,%2" 3226 : "=v" (v1) 3227 : "v" (v2), "v" (v3)); 3228@end smallexample 3229 3230@ifset INTERNALS 3231@item h 3232A special register (@code{vrsave}, @code{ctr}, or @code{lr}). 3233@end ifset 3234 3235@item c 3236The count register, @code{ctr}. 3237 3238@item l 3239The link register, @code{lr}. 3240 3241@item x 3242Condition register field 0, @code{cr0}. 3243 3244@item y 3245Any condition register field, @code{cr0}@dots{}@code{cr7}. 3246 3247@ifset INTERNALS 3248@item z 3249The carry bit, @code{XER[CA]}. 3250 3251@item we 3252Like @code{wa}, if @option{-mpower9-vector} and @option{-m64} are used; 3253otherwise, @code{NO_REGS}. 3254 3255@item wn 3256No register (@code{NO_REGS}). 3257 3258@item wr 3259Like @code{r}, if @option{-mpowerpc64} is used; otherwise, @code{NO_REGS}. 3260 3261@item wx 3262Like @code{d}, if @option{-mpowerpc-gfxopt} is used; otherwise, @code{NO_REGS}. 3263 3264@item wA 3265Like @code{b}, if @option{-mpowerpc64} is used; otherwise, @code{NO_REGS}. 3266 3267@item wB 3268Signed 5-bit constant integer that can be loaded into an Altivec register. 3269 3270@item wD 3271Int constant that is the element number of the 64-bit scalar in a vector. 3272 3273@item wE 3274Vector constant that can be loaded with the XXSPLTIB instruction. 3275 3276@item wF 3277Memory operand suitable for power8 GPR load fusion. 3278 3279@item wL 3280Int constant that is the element number mfvsrld accesses in a vector. 3281 3282@item wM 3283Match vector constant with all 1's if the XXLORC instruction is available. 3284 3285@item wO 3286Memory operand suitable for the ISA 3.0 vector d-form instructions. 3287 3288@item wQ 3289Memory operand suitable for the load/store quad instructions. 3290 3291@item wS 3292Vector constant that can be loaded with XXSPLTIB & sign extension. 3293 3294@item wY 3295A memory operand for a DS-form instruction. 3296 3297@item wZ 3298An indexed or indirect memory operand, ignoring the bottom 4 bits. 3299@end ifset 3300 3301@item I 3302A signed 16-bit constant. 3303 3304@item J 3305An unsigned 16-bit constant shifted left 16 bits (use @code{L} instead 3306for @code{SImode} constants). 3307 3308@item K 3309An unsigned 16-bit constant. 3310 3311@item L 3312A signed 16-bit constant shifted left 16 bits. 3313 3314@ifset INTERNALS 3315@item M 3316An integer constant greater than 31. 3317 3318@item N 3319An exact power of 2. 3320 3321@item O 3322The integer constant zero. 3323 3324@item P 3325A constant whose negation is a signed 16-bit constant. 3326@end ifset 3327 3328@item eI 3329A signed 34-bit integer constant if prefixed instructions are supported. 3330 3331@ifset INTERNALS 3332@item G 3333A floating point constant that can be loaded into a register with one 3334instruction per word. 3335 3336@item H 3337A floating point constant that can be loaded into a register using 3338three instructions. 3339@end ifset 3340 3341@item m 3342A memory operand. 3343Normally, @code{m} does not allow addresses that update the base register. 3344If the @code{<} or @code{>} constraint is also used, they are allowed and 3345therefore on PowerPC targets in that case it is only safe 3346to use @code{m<>} in an @code{asm} statement if that @code{asm} statement 3347accesses the operand exactly once. The @code{asm} statement must also 3348use @code{%U@var{<opno>}} as a placeholder for the ``update'' flag in the 3349corresponding load or store instruction. For example: 3350 3351@smallexample 3352asm ("st%U0 %1,%0" : "=m<>" (mem) : "r" (val)); 3353@end smallexample 3354 3355is correct but: 3356 3357@smallexample 3358asm ("st %1,%0" : "=m<>" (mem) : "r" (val)); 3359@end smallexample 3360 3361is not. 3362 3363@ifset INTERNALS 3364@item es 3365A ``stable'' memory operand; that is, one which does not include any 3366automodification of the base register. This used to be useful when 3367@code{m} allowed automodification of the base register, but as those 3368are now only allowed when @code{<} or @code{>} is used, @code{es} is 3369basically the same as @code{m} without @code{<} and @code{>}. 3370@end ifset 3371 3372@item Q 3373A memory operand addressed by just a base register. 3374 3375@ifset INTERNALS 3376@item Y 3377A memory operand for a DQ-form instruction. 3378@end ifset 3379 3380@item Z 3381A memory operand accessed with indexed or indirect addressing. 3382 3383@ifset INTERNALS 3384@item R 3385An AIX TOC entry. 3386@end ifset 3387 3388@item a 3389An indexed or indirect address. 3390 3391@ifset INTERNALS 3392@item U 3393A V.4 small data reference. 3394 3395@item W 3396A vector constant that does not require memory. 3397 3398@item j 3399The zero vector constant. 3400@end ifset 3401 3402@end table 3403 3404@item PRU---@file{config/pru/constraints.md} 3405@table @code 3406@item I 3407An unsigned 8-bit integer constant. 3408 3409@item J 3410An unsigned 16-bit integer constant. 3411 3412@item L 3413An unsigned 5-bit integer constant (for shift counts). 3414 3415@item T 3416A text segment (program memory) constant label. 3417 3418@item Z 3419Integer constant zero. 3420 3421@end table 3422 3423@item RL78---@file{config/rl78/constraints.md} 3424@table @code 3425 3426@item Int3 3427An integer constant in the range 1 @dots{} 7. 3428@item Int8 3429An integer constant in the range 0 @dots{} 255. 3430@item J 3431An integer constant in the range @minus{}255 @dots{} 0 3432@item K 3433The integer constant 1. 3434@item L 3435The integer constant -1. 3436@item M 3437The integer constant 0. 3438@item N 3439The integer constant 2. 3440@item O 3441The integer constant -2. 3442@item P 3443An integer constant in the range 1 @dots{} 15. 3444@item Qbi 3445The built-in compare types--eq, ne, gtu, ltu, geu, and leu. 3446@item Qsc 3447The synthetic compare types--gt, lt, ge, and le. 3448@item Wab 3449A memory reference with an absolute address. 3450@item Wbc 3451A memory reference using @code{BC} as a base register, with an optional offset. 3452@item Wca 3453A memory reference using @code{AX}, @code{BC}, @code{DE}, or @code{HL} for the address, for calls. 3454@item Wcv 3455A memory reference using any 16-bit register pair for the address, for calls. 3456@item Wd2 3457A memory reference using @code{DE} as a base register, with an optional offset. 3458@item Wde 3459A memory reference using @code{DE} as a base register, without any offset. 3460@item Wfr 3461Any memory reference to an address in the far address space. 3462@item Wh1 3463A memory reference using @code{HL} as a base register, with an optional one-byte offset. 3464@item Whb 3465A memory reference using @code{HL} as a base register, with @code{B} or @code{C} as the index register. 3466@item Whl 3467A memory reference using @code{HL} as a base register, without any offset. 3468@item Ws1 3469A memory reference using @code{SP} as a base register, with an optional one-byte offset. 3470@item Y 3471Any memory reference to an address in the near address space. 3472@item A 3473The @code{AX} register. 3474@item B 3475The @code{BC} register. 3476@item D 3477The @code{DE} register. 3478@item R 3479@code{A} through @code{L} registers. 3480@item S 3481The @code{SP} register. 3482@item T 3483The @code{HL} register. 3484@item Z08W 3485The 16-bit @code{R8} register. 3486@item Z10W 3487The 16-bit @code{R10} register. 3488@item Zint 3489The registers reserved for interrupts (@code{R24} to @code{R31}). 3490@item a 3491The @code{A} register. 3492@item b 3493The @code{B} register. 3494@item c 3495The @code{C} register. 3496@item d 3497The @code{D} register. 3498@item e 3499The @code{E} register. 3500@item h 3501The @code{H} register. 3502@item l 3503The @code{L} register. 3504@item v 3505The virtual registers. 3506@item w 3507The @code{PSW} register. 3508@item x 3509The @code{X} register. 3510 3511@end table 3512 3513@item RISC-V---@file{config/riscv/constraints.md} 3514@table @code 3515 3516@item f 3517A floating-point register (if available). 3518 3519@item I 3520An I-type 12-bit signed immediate. 3521 3522@item J 3523Integer zero. 3524 3525@item K 3526A 5-bit unsigned immediate for CSR access instructions. 3527 3528@item A 3529An address that is held in a general-purpose register. 3530 3531@end table 3532 3533@item RX---@file{config/rx/constraints.md} 3534@table @code 3535@item Q 3536An address which does not involve register indirect addressing or 3537pre/post increment/decrement addressing. 3538 3539@item Symbol 3540A symbol reference. 3541 3542@item Int08 3543A constant in the range @minus{}256 to 255, inclusive. 3544 3545@item Sint08 3546A constant in the range @minus{}128 to 127, inclusive. 3547 3548@item Sint16 3549A constant in the range @minus{}32768 to 32767, inclusive. 3550 3551@item Sint24 3552A constant in the range @minus{}8388608 to 8388607, inclusive. 3553 3554@item Uint04 3555A constant in the range 0 to 15, inclusive. 3556 3557@end table 3558 3559@item S/390 and zSeries---@file{config/s390/s390.h} 3560@table @code 3561@item a 3562Address register (general purpose register except r0) 3563 3564@item c 3565Condition code register 3566 3567@item d 3568Data register (arbitrary general purpose register) 3569 3570@item f 3571Floating-point register 3572 3573@item I 3574Unsigned 8-bit constant (0--255) 3575 3576@item J 3577Unsigned 12-bit constant (0--4095) 3578 3579@item K 3580Signed 16-bit constant (@minus{}32768--32767) 3581 3582@item L 3583Value appropriate as displacement. 3584@table @code 3585@item (0..4095) 3586for short displacement 3587@item (@minus{}524288..524287) 3588for long displacement 3589@end table 3590 3591@item M 3592Constant integer with a value of 0x7fffffff. 3593 3594@item N 3595Multiple letter constraint followed by 4 parameter letters. 3596@table @code 3597@item 0..9: 3598number of the part counting from most to least significant 3599@item H,Q: 3600mode of the part 3601@item D,S,H: 3602mode of the containing operand 3603@item 0,F: 3604value of the other parts (F---all bits set) 3605@end table 3606The constraint matches if the specified part of a constant 3607has a value different from its other parts. 3608 3609@item Q 3610Memory reference without index register and with short displacement. 3611 3612@item R 3613Memory reference with index register and short displacement. 3614 3615@item S 3616Memory reference without index register but with long displacement. 3617 3618@item T 3619Memory reference with index register and long displacement. 3620 3621@item U 3622Pointer with short displacement. 3623 3624@item W 3625Pointer with long displacement. 3626 3627@item Y 3628Shift count operand. 3629 3630@end table 3631 3632@need 1000 3633@item SPARC---@file{config/sparc/sparc.h} 3634@table @code 3635@item f 3636Floating-point register on the SPARC-V8 architecture and 3637lower floating-point register on the SPARC-V9 architecture. 3638 3639@item e 3640Floating-point register. It is equivalent to @samp{f} on the 3641SPARC-V8 architecture and contains both lower and upper 3642floating-point registers on the SPARC-V9 architecture. 3643 3644@item c 3645Floating-point condition code register. 3646 3647@item d 3648Lower floating-point register. It is only valid on the SPARC-V9 3649architecture when the Visual Instruction Set is available. 3650 3651@item b 3652Floating-point register. It is only valid on the SPARC-V9 architecture 3653when the Visual Instruction Set is available. 3654 3655@item h 365664-bit global or out register for the SPARC-V8+ architecture. 3657 3658@item C 3659The constant all-ones, for floating-point. 3660 3661@item A 3662Signed 5-bit constant 3663 3664@item D 3665A vector constant 3666 3667@item I 3668Signed 13-bit constant 3669 3670@item J 3671Zero 3672 3673@item K 367432-bit constant with the low 12 bits clear (a constant that can be 3675loaded with the @code{sethi} instruction) 3676 3677@item L 3678A constant in the range supported by @code{movcc} instructions (11-bit 3679signed immediate) 3680 3681@item M 3682A constant in the range supported by @code{movrcc} instructions (10-bit 3683signed immediate) 3684 3685@item N 3686Same as @samp{K}, except that it verifies that bits that are not in the 3687lower 32-bit range are all zero. Must be used instead of @samp{K} for 3688modes wider than @code{SImode} 3689 3690@item O 3691The constant 4096 3692 3693@item G 3694Floating-point zero 3695 3696@item H 3697Signed 13-bit constant, sign-extended to 32 or 64 bits 3698 3699@item P 3700The constant -1 3701 3702@item Q 3703Floating-point constant whose integral representation can 3704be moved into an integer register using a single sethi 3705instruction 3706 3707@item R 3708Floating-point constant whose integral representation can 3709be moved into an integer register using a single mov 3710instruction 3711 3712@item S 3713Floating-point constant whose integral representation can 3714be moved into an integer register using a high/lo_sum 3715instruction sequence 3716 3717@item T 3718Memory address aligned to an 8-byte boundary 3719 3720@item U 3721Even register 3722 3723@item W 3724Memory address for @samp{e} constraint registers 3725 3726@item w 3727Memory address with only a base register 3728 3729@item Y 3730Vector zero 3731 3732@end table 3733 3734@item TI C6X family---@file{config/c6x/constraints.md} 3735@table @code 3736@item a 3737Register file A (A0--A31). 3738 3739@item b 3740Register file B (B0--B31). 3741 3742@item A 3743Predicate registers in register file A (A0--A2 on C64X and 3744higher, A1 and A2 otherwise). 3745 3746@item B 3747Predicate registers in register file B (B0--B2). 3748 3749@item C 3750A call-used register in register file B (B0--B9, B16--B31). 3751 3752@item Da 3753Register file A, excluding predicate registers (A3--A31, 3754plus A0 if not C64X or higher). 3755 3756@item Db 3757Register file B, excluding predicate registers (B3--B31). 3758 3759@item Iu4 3760Integer constant in the range 0 @dots{} 15. 3761 3762@item Iu5 3763Integer constant in the range 0 @dots{} 31. 3764 3765@item In5 3766Integer constant in the range @minus{}31 @dots{} 0. 3767 3768@item Is5 3769Integer constant in the range @minus{}16 @dots{} 15. 3770 3771@item I5x 3772Integer constant that can be the operand of an ADDA or a SUBA insn. 3773 3774@item IuB 3775Integer constant in the range 0 @dots{} 65535. 3776 3777@item IsB 3778Integer constant in the range @minus{}32768 @dots{} 32767. 3779 3780@item IsC 3781Integer constant in the range @math{-2^{20}} @dots{} @math{2^{20} - 1}. 3782 3783@item Jc 3784Integer constant that is a valid mask for the clr instruction. 3785 3786@item Js 3787Integer constant that is a valid mask for the set instruction. 3788 3789@item Q 3790Memory location with A base register. 3791 3792@item R 3793Memory location with B base register. 3794 3795@ifset INTERNALS 3796@item S0 3797On C64x+ targets, a GP-relative small data reference. 3798 3799@item S1 3800Any kind of @code{SYMBOL_REF}, for use in a call address. 3801 3802@item Si 3803Any kind of immediate operand, unless it matches the S0 constraint. 3804 3805@item T 3806Memory location with B base register, but not using a long offset. 3807 3808@item W 3809A memory operand with an address that cannot be used in an unaligned access. 3810 3811@end ifset 3812@item Z 3813Register B14 (aka DP). 3814 3815@end table 3816 3817@item TILE-Gx---@file{config/tilegx/constraints.md} 3818@table @code 3819@item R00 3820@itemx R01 3821@itemx R02 3822@itemx R03 3823@itemx R04 3824@itemx R05 3825@itemx R06 3826@itemx R07 3827@itemx R08 3828@itemx R09 3829@itemx R10 3830Each of these represents a register constraint for an individual 3831register, from r0 to r10. 3832 3833@item I 3834Signed 8-bit integer constant. 3835 3836@item J 3837Signed 16-bit integer constant. 3838 3839@item K 3840Unsigned 16-bit integer constant. 3841 3842@item L 3843Integer constant that fits in one signed byte when incremented by one 3844(@minus{}129 @dots{} 126). 3845 3846@item m 3847Memory operand. If used together with @samp{<} or @samp{>}, the 3848operand can have postincrement which requires printing with @samp{%In} 3849and @samp{%in} on TILE-Gx. For example: 3850 3851@smallexample 3852asm ("st_add %I0,%1,%i0" : "=m<>" (*mem) : "r" (val)); 3853@end smallexample 3854 3855@item M 3856A bit mask suitable for the BFINS instruction. 3857 3858@item N 3859Integer constant that is a byte tiled out eight times. 3860 3861@item O 3862The integer zero constant. 3863 3864@item P 3865Integer constant that is a sign-extended byte tiled out as four shorts. 3866 3867@item Q 3868Integer constant that fits in one signed byte when incremented 3869(@minus{}129 @dots{} 126), but excluding -1. 3870 3871@item S 3872Integer constant that has all 1 bits consecutive and starting at bit 0. 3873 3874@item T 3875A 16-bit fragment of a got, tls, or pc-relative reference. 3876 3877@item U 3878Memory operand except postincrement. This is roughly the same as 3879@samp{m} when not used together with @samp{<} or @samp{>}. 3880 3881@item W 3882An 8-element vector constant with identical elements. 3883 3884@item Y 3885A 4-element vector constant with identical elements. 3886 3887@item Z0 3888The integer constant 0xffffffff. 3889 3890@item Z1 3891The integer constant 0xffffffff00000000. 3892 3893@end table 3894 3895@item TILEPro---@file{config/tilepro/constraints.md} 3896@table @code 3897@item R00 3898@itemx R01 3899@itemx R02 3900@itemx R03 3901@itemx R04 3902@itemx R05 3903@itemx R06 3904@itemx R07 3905@itemx R08 3906@itemx R09 3907@itemx R10 3908Each of these represents a register constraint for an individual 3909register, from r0 to r10. 3910 3911@item I 3912Signed 8-bit integer constant. 3913 3914@item J 3915Signed 16-bit integer constant. 3916 3917@item K 3918Nonzero integer constant with low 16 bits zero. 3919 3920@item L 3921Integer constant that fits in one signed byte when incremented by one 3922(@minus{}129 @dots{} 126). 3923 3924@item m 3925Memory operand. If used together with @samp{<} or @samp{>}, the 3926operand can have postincrement which requires printing with @samp{%In} 3927and @samp{%in} on TILEPro. For example: 3928 3929@smallexample 3930asm ("swadd %I0,%1,%i0" : "=m<>" (mem) : "r" (val)); 3931@end smallexample 3932 3933@item M 3934A bit mask suitable for the MM instruction. 3935 3936@item N 3937Integer constant that is a byte tiled out four times. 3938 3939@item O 3940The integer zero constant. 3941 3942@item P 3943Integer constant that is a sign-extended byte tiled out as two shorts. 3944 3945@item Q 3946Integer constant that fits in one signed byte when incremented 3947(@minus{}129 @dots{} 126), but excluding -1. 3948 3949@item T 3950A symbolic operand, or a 16-bit fragment of a got, tls, or pc-relative 3951reference. 3952 3953@item U 3954Memory operand except postincrement. This is roughly the same as 3955@samp{m} when not used together with @samp{<} or @samp{>}. 3956 3957@item W 3958A 4-element vector constant with identical elements. 3959 3960@item Y 3961A 2-element vector constant with identical elements. 3962 3963@end table 3964 3965@item Visium---@file{config/visium/constraints.md} 3966@table @code 3967@item b 3968EAM register @code{mdb} 3969 3970@item c 3971EAM register @code{mdc} 3972 3973@item f 3974Floating point register 3975 3976@ifset INTERNALS 3977@item k 3978Register for sibcall optimization 3979@end ifset 3980 3981@item l 3982General register, but not @code{r29}, @code{r30} and @code{r31} 3983 3984@item t 3985Register @code{r1} 3986 3987@item u 3988Register @code{r2} 3989 3990@item v 3991Register @code{r3} 3992 3993@item G 3994Floating-point constant 0.0 3995 3996@item J 3997Integer constant in the range 0 .. 65535 (16-bit immediate) 3998 3999@item K 4000Integer constant in the range 1 .. 31 (5-bit immediate) 4001 4002@item L 4003Integer constant in the range @minus{}65535 .. @minus{}1 (16-bit negative immediate) 4004 4005@item M 4006Integer constant @minus{}1 4007 4008@item O 4009Integer constant 0 4010 4011@item P 4012Integer constant 32 4013@end table 4014 4015@item x86 family---@file{config/i386/constraints.md} 4016@table @code 4017@item R 4018Legacy register---the eight integer registers available on all 4019i386 processors (@code{a}, @code{b}, @code{c}, @code{d}, 4020@code{si}, @code{di}, @code{bp}, @code{sp}). 4021 4022@item q 4023Any register accessible as @code{@var{r}l}. In 32-bit mode, @code{a}, 4024@code{b}, @code{c}, and @code{d}; in 64-bit mode, any integer register. 4025 4026@item Q 4027Any register accessible as @code{@var{r}h}: @code{a}, @code{b}, 4028@code{c}, and @code{d}. 4029 4030@ifset INTERNALS 4031@item l 4032Any register that can be used as the index in a base+index memory 4033access: that is, any general register except the stack pointer. 4034@end ifset 4035 4036@item a 4037The @code{a} register. 4038 4039@item b 4040The @code{b} register. 4041 4042@item c 4043The @code{c} register. 4044 4045@item d 4046The @code{d} register. 4047 4048@item S 4049The @code{si} register. 4050 4051@item D 4052The @code{di} register. 4053 4054@item A 4055The @code{a} and @code{d} registers. This class is used for instructions 4056that return double word results in the @code{ax:dx} register pair. Single 4057word values will be allocated either in @code{ax} or @code{dx}. 4058For example on i386 the following implements @code{rdtsc}: 4059 4060@smallexample 4061unsigned long long rdtsc (void) 4062@{ 4063 unsigned long long tick; 4064 __asm__ __volatile__("rdtsc":"=A"(tick)); 4065 return tick; 4066@} 4067@end smallexample 4068 4069This is not correct on x86-64 as it would allocate tick in either @code{ax} 4070or @code{dx}. You have to use the following variant instead: 4071 4072@smallexample 4073unsigned long long rdtsc (void) 4074@{ 4075 unsigned int tickl, tickh; 4076 __asm__ __volatile__("rdtsc":"=a"(tickl),"=d"(tickh)); 4077 return ((unsigned long long)tickh << 32)|tickl; 4078@} 4079@end smallexample 4080 4081@item U 4082The call-clobbered integer registers. 4083 4084@item f 4085Any 80387 floating-point (stack) register. 4086 4087@item t 4088Top of 80387 floating-point stack (@code{%st(0)}). 4089 4090@item u 4091Second from top of 80387 floating-point stack (@code{%st(1)}). 4092 4093@ifset INTERNALS 4094@item Yk 4095Any mask register that can be used as a predicate, i.e.@: @code{k1-k7}. 4096 4097@item k 4098Any mask register. 4099@end ifset 4100 4101@item y 4102Any MMX register. 4103 4104@item x 4105Any SSE register. 4106 4107@item v 4108Any EVEX encodable SSE register (@code{%xmm0-%xmm31}). 4109 4110@ifset INTERNALS 4111@item w 4112Any bound register. 4113@end ifset 4114 4115@item Yz 4116First SSE register (@code{%xmm0}). 4117 4118@ifset INTERNALS 4119@item Yi 4120Any SSE register, when SSE2 and inter-unit moves are enabled. 4121 4122@item Yj 4123Any SSE register, when SSE2 and inter-unit moves from vector registers are enabled. 4124 4125@item Ym 4126Any MMX register, when inter-unit moves are enabled. 4127 4128@item Yn 4129Any MMX register, when inter-unit moves from vector registers are enabled. 4130 4131@item Yp 4132Any integer register when @code{TARGET_PARTIAL_REG_STALL} is disabled. 4133 4134@item Ya 4135Any integer register when zero extensions with @code{AND} are disabled. 4136 4137@item Yb 4138Any register that can be used as the GOT base when calling@* 4139@code{___tls_get_addr}: that is, any general register except @code{a} 4140and @code{sp} registers, for @option{-fno-plt} if linker supports it. 4141Otherwise, @code{b} register. 4142 4143@item Yf 4144Any x87 register when 80387 floating-point arithmetic is enabled. 4145 4146@item Yr 4147Lower SSE register when avoiding REX prefix and all SSE registers otherwise. 4148 4149@item Yv 4150For AVX512VL, any EVEX-encodable SSE register (@code{%xmm0-%xmm31}), 4151otherwise any SSE register. 4152 4153@item Yh 4154Any EVEX-encodable SSE register, that has number factor of four. 4155 4156@item Bf 4157Flags register operand. 4158 4159@item Bg 4160GOT memory operand. 4161 4162@item Bm 4163Vector memory operand. 4164 4165@item Bc 4166Constant memory operand. 4167 4168@item Bn 4169Memory operand without REX prefix. 4170 4171@item Bs 4172Sibcall memory operand. 4173 4174@item Bw 4175Call memory operand. 4176 4177@item Bz 4178Constant call address operand. 4179 4180@item BC 4181SSE constant -1 operand. 4182@end ifset 4183 4184@item I 4185Integer constant in the range 0 @dots{} 31, for 32-bit shifts. 4186 4187@item J 4188Integer constant in the range 0 @dots{} 63, for 64-bit shifts. 4189 4190@item K 4191Signed 8-bit integer constant. 4192 4193@item L 4194@code{0xFF} or @code{0xFFFF}, for andsi as a zero-extending move. 4195 4196@item M 41970, 1, 2, or 3 (shifts for the @code{lea} instruction). 4198 4199@item N 4200Unsigned 8-bit integer constant (for @code{in} and @code{out} 4201instructions). 4202 4203@ifset INTERNALS 4204@item O 4205Integer constant in the range 0 @dots{} 127, for 128-bit shifts. 4206@end ifset 4207 4208@item G 4209Standard 80387 floating point constant. 4210 4211@item C 4212SSE constant zero operand. 4213 4214@item e 421532-bit signed integer constant, or a symbolic reference known 4216to fit that range (for immediate operands in sign-extending x86-64 4217instructions). 4218 4219@item We 422032-bit signed integer constant, or a symbolic reference known 4221to fit that range (for sign-extending conversion operations that 4222require non-@code{VOIDmode} immediate operands). 4223 4224@item Wz 422532-bit unsigned integer constant, or a symbolic reference known 4226to fit that range (for zero-extending conversion operations that 4227require non-@code{VOIDmode} immediate operands). 4228 4229@item Wd 4230128-bit integer constant where both the high and low 64-bit word 4231satisfy the @code{e} constraint. 4232 4233@item Z 423432-bit unsigned integer constant, or a symbolic reference known 4235to fit that range (for immediate operands in zero-extending x86-64 4236instructions). 4237 4238@item Tv 4239VSIB address operand. 4240 4241@item Ts 4242Address operand without segment register. 4243 4244@end table 4245 4246@item Xstormy16---@file{config/stormy16/stormy16.h} 4247@table @code 4248@item a 4249Register r0. 4250 4251@item b 4252Register r1. 4253 4254@item c 4255Register r2. 4256 4257@item d 4258Register r8. 4259 4260@item e 4261Registers r0 through r7. 4262 4263@item t 4264Registers r0 and r1. 4265 4266@item y 4267The carry register. 4268 4269@item z 4270Registers r8 and r9. 4271 4272@item I 4273A constant between 0 and 3 inclusive. 4274 4275@item J 4276A constant that has exactly one bit set. 4277 4278@item K 4279A constant that has exactly one bit clear. 4280 4281@item L 4282A constant between 0 and 255 inclusive. 4283 4284@item M 4285A constant between @minus{}255 and 0 inclusive. 4286 4287@item N 4288A constant between @minus{}3 and 0 inclusive. 4289 4290@item O 4291A constant between 1 and 4 inclusive. 4292 4293@item P 4294A constant between @minus{}4 and @minus{}1 inclusive. 4295 4296@item Q 4297A memory reference that is a stack push. 4298 4299@item R 4300A memory reference that is a stack pop. 4301 4302@item S 4303A memory reference that refers to a constant address of known value. 4304 4305@item T 4306The register indicated by Rx (not implemented yet). 4307 4308@item U 4309A constant that is not between 2 and 15 inclusive. 4310 4311@item Z 4312The constant 0. 4313 4314@end table 4315 4316@item Xtensa---@file{config/xtensa/constraints.md} 4317@table @code 4318@item a 4319General-purpose 32-bit register 4320 4321@item b 4322One-bit boolean register 4323 4324@item A 4325MAC16 40-bit accumulator register 4326 4327@item I 4328Signed 12-bit integer constant, for use in MOVI instructions 4329 4330@item J 4331Signed 8-bit integer constant, for use in ADDI instructions 4332 4333@item K 4334Integer constant valid for BccI instructions 4335 4336@item L 4337Unsigned constant valid for BccUI instructions 4338 4339@end table 4340 4341@end table 4342 4343@ifset INTERNALS 4344@node Disable Insn Alternatives 4345@subsection Disable insn alternatives using the @code{enabled} attribute 4346@cindex enabled 4347 4348There are three insn attributes that may be used to selectively disable 4349instruction alternatives: 4350 4351@table @code 4352@item enabled 4353Says whether an alternative is available on the current subtarget. 4354 4355@item preferred_for_size 4356Says whether an enabled alternative should be used in code that is 4357optimized for size. 4358 4359@item preferred_for_speed 4360Says whether an enabled alternative should be used in code that is 4361optimized for speed. 4362@end table 4363 4364All these attributes should use @code{(const_int 1)} to allow an alternative 4365or @code{(const_int 0)} to disallow it. The attributes must be a static 4366property of the subtarget; they cannot for example depend on the 4367current operands, on the current optimization level, on the location 4368of the insn within the body of a loop, on whether register allocation 4369has finished, or on the current compiler pass. 4370 4371The @code{enabled} attribute is a correctness property. It tells GCC to act 4372as though the disabled alternatives were never defined in the first place. 4373This is useful when adding new instructions to an existing pattern in 4374cases where the new instructions are only available for certain cpu 4375architecture levels (typically mapped to the @code{-march=} command-line 4376option). 4377 4378In contrast, the @code{preferred_for_size} and @code{preferred_for_speed} 4379attributes are strong optimization hints rather than correctness properties. 4380@code{preferred_for_size} tells GCC which alternatives to consider when 4381adding or modifying an instruction that GCC wants to optimize for size. 4382@code{preferred_for_speed} does the same thing for speed. Note that things 4383like code motion can lead to cases where code optimized for size uses 4384alternatives that are not preferred for size, and similarly for speed. 4385 4386Although @code{define_insn}s can in principle specify the @code{enabled} 4387attribute directly, it is often clearer to have subsiduary attributes 4388for each architectural feature of interest. The @code{define_insn}s 4389can then use these subsiduary attributes to say which alternatives 4390require which features. The example below does this for @code{cpu_facility}. 4391 4392E.g. the following two patterns could easily be merged using the @code{enabled} 4393attribute: 4394 4395@smallexample 4396 4397(define_insn "*movdi_old" 4398 [(set (match_operand:DI 0 "register_operand" "=d") 4399 (match_operand:DI 1 "register_operand" " d"))] 4400 "!TARGET_NEW" 4401 "lgr %0,%1") 4402 4403(define_insn "*movdi_new" 4404 [(set (match_operand:DI 0 "register_operand" "=d,f,d") 4405 (match_operand:DI 1 "register_operand" " d,d,f"))] 4406 "TARGET_NEW" 4407 "@@ 4408 lgr %0,%1 4409 ldgr %0,%1 4410 lgdr %0,%1") 4411 4412@end smallexample 4413 4414to: 4415 4416@smallexample 4417 4418(define_insn "*movdi_combined" 4419 [(set (match_operand:DI 0 "register_operand" "=d,f,d") 4420 (match_operand:DI 1 "register_operand" " d,d,f"))] 4421 "" 4422 "@@ 4423 lgr %0,%1 4424 ldgr %0,%1 4425 lgdr %0,%1" 4426 [(set_attr "cpu_facility" "*,new,new")]) 4427 4428@end smallexample 4429 4430with the @code{enabled} attribute defined like this: 4431 4432@smallexample 4433 4434(define_attr "cpu_facility" "standard,new" (const_string "standard")) 4435 4436(define_attr "enabled" "" 4437 (cond [(eq_attr "cpu_facility" "standard") (const_int 1) 4438 (and (eq_attr "cpu_facility" "new") 4439 (ne (symbol_ref "TARGET_NEW") (const_int 0))) 4440 (const_int 1)] 4441 (const_int 0))) 4442 4443@end smallexample 4444 4445@end ifset 4446 4447@ifset INTERNALS 4448@node Define Constraints 4449@subsection Defining Machine-Specific Constraints 4450@cindex defining constraints 4451@cindex constraints, defining 4452 4453Machine-specific constraints fall into two categories: register and 4454non-register constraints. Within the latter category, constraints 4455which allow subsets of all possible memory or address operands should 4456be specially marked, to give @code{reload} more information. 4457 4458Machine-specific constraints can be given names of arbitrary length, 4459but they must be entirely composed of letters, digits, underscores 4460(@samp{_}), and angle brackets (@samp{< >}). Like C identifiers, they 4461must begin with a letter or underscore. 4462 4463In order to avoid ambiguity in operand constraint strings, no 4464constraint can have a name that begins with any other constraint's 4465name. For example, if @code{x} is defined as a constraint name, 4466@code{xy} may not be, and vice versa. As a consequence of this rule, 4467no constraint may begin with one of the generic constraint letters: 4468@samp{E F V X g i m n o p r s}. 4469 4470Register constraints correspond directly to register classes. 4471@xref{Register Classes}. There is thus not much flexibility in their 4472definitions. 4473 4474@deffn {MD Expression} define_register_constraint name regclass docstring 4475All three arguments are string constants. 4476@var{name} is the name of the constraint, as it will appear in 4477@code{match_operand} expressions. If @var{name} is a multi-letter 4478constraint its length shall be the same for all constraints starting 4479with the same letter. @var{regclass} can be either the 4480name of the corresponding register class (@pxref{Register Classes}), 4481or a C expression which evaluates to the appropriate register class. 4482If it is an expression, it must have no side effects, and it cannot 4483look at the operand. The usual use of expressions is to map some 4484register constraints to @code{NO_REGS} when the register class 4485is not available on a given subarchitecture. 4486 4487@var{docstring} is a sentence documenting the meaning of the 4488constraint. Docstrings are explained further below. 4489@end deffn 4490 4491Non-register constraints are more like predicates: the constraint 4492definition gives a boolean expression which indicates whether the 4493constraint matches. 4494 4495@deffn {MD Expression} define_constraint name docstring exp 4496The @var{name} and @var{docstring} arguments are the same as for 4497@code{define_register_constraint}, but note that the docstring comes 4498immediately after the name for these expressions. @var{exp} is an RTL 4499expression, obeying the same rules as the RTL expressions in predicate 4500definitions. @xref{Defining Predicates}, for details. If it 4501evaluates true, the constraint matches; if it evaluates false, it 4502doesn't. Constraint expressions should indicate which RTL codes they 4503might match, just like predicate expressions. 4504 4505@code{match_test} C expressions have access to the 4506following variables: 4507 4508@table @var 4509@item op 4510The RTL object defining the operand. 4511@item mode 4512The machine mode of @var{op}. 4513@item ival 4514@samp{INTVAL (@var{op})}, if @var{op} is a @code{const_int}. 4515@item hval 4516@samp{CONST_DOUBLE_HIGH (@var{op})}, if @var{op} is an integer 4517@code{const_double}. 4518@item lval 4519@samp{CONST_DOUBLE_LOW (@var{op})}, if @var{op} is an integer 4520@code{const_double}. 4521@item rval 4522@samp{CONST_DOUBLE_REAL_VALUE (@var{op})}, if @var{op} is a floating-point 4523@code{const_double}. 4524@end table 4525 4526The @var{*val} variables should only be used once another piece of the 4527expression has verified that @var{op} is the appropriate kind of RTL 4528object. 4529@end deffn 4530 4531Most non-register constraints should be defined with 4532@code{define_constraint}. The remaining two definition expressions 4533are only appropriate for constraints that should be handled specially 4534by @code{reload} if they fail to match. 4535 4536@deffn {MD Expression} define_memory_constraint name docstring exp 4537Use this expression for constraints that match a subset of all memory 4538operands: that is, @code{reload} can make them match by converting the 4539operand to the form @samp{@w{(mem (reg @var{X}))}}, where @var{X} is a 4540base register (from the register class specified by 4541@code{BASE_REG_CLASS}, @pxref{Register Classes}). 4542 4543For example, on the S/390, some instructions do not accept arbitrary 4544memory references, but only those that do not make use of an index 4545register. The constraint letter @samp{Q} is defined to represent a 4546memory address of this type. If @samp{Q} is defined with 4547@code{define_memory_constraint}, a @samp{Q} constraint can handle any 4548memory operand, because @code{reload} knows it can simply copy the 4549memory address into a base register if required. This is analogous to 4550the way an @samp{o} constraint can handle any memory operand. 4551 4552The syntax and semantics are otherwise identical to 4553@code{define_constraint}. 4554@end deffn 4555 4556@deffn {MD Expression} define_special_memory_constraint name docstring exp 4557Use this expression for constraints that match a subset of all memory 4558operands: that is, @code{reload} cannot make them match by reloading 4559the address as it is described for @code{define_memory_constraint} or 4560such address reload is undesirable with the performance point of view. 4561 4562For example, @code{define_special_memory_constraint} can be useful if 4563specifically aligned memory is necessary or desirable for some insn 4564operand. 4565 4566The syntax and semantics are otherwise identical to 4567@code{define_constraint}. 4568@end deffn 4569 4570@deffn {MD Expression} define_address_constraint name docstring exp 4571Use this expression for constraints that match a subset of all address 4572operands: that is, @code{reload} can make the constraint match by 4573converting the operand to the form @samp{@w{(reg @var{X})}}, again 4574with @var{X} a base register. 4575 4576Constraints defined with @code{define_address_constraint} can only be 4577used with the @code{address_operand} predicate, or machine-specific 4578predicates that work the same way. They are treated analogously to 4579the generic @samp{p} constraint. 4580 4581The syntax and semantics are otherwise identical to 4582@code{define_constraint}. 4583@end deffn 4584 4585For historical reasons, names beginning with the letters @samp{G H} 4586are reserved for constraints that match only @code{const_double}s, and 4587names beginning with the letters @samp{I J K L M N O P} are reserved 4588for constraints that match only @code{const_int}s. This may change in 4589the future. For the time being, constraints with these names must be 4590written in a stylized form, so that @code{genpreds} can tell you did 4591it correctly: 4592 4593@smallexample 4594@group 4595(define_constraint "[@var{GHIJKLMNOP}]@dots{}" 4596 "@var{doc}@dots{}" 4597 (and (match_code "const_int") ; @r{@code{const_double} for G/H} 4598 @var{condition}@dots{})) ; @r{usually a @code{match_test}} 4599@end group 4600@end smallexample 4601@c the semicolons line up in the formatted manual 4602 4603It is fine to use names beginning with other letters for constraints 4604that match @code{const_double}s or @code{const_int}s. 4605 4606Each docstring in a constraint definition should be one or more complete 4607sentences, marked up in Texinfo format. @emph{They are currently unused.} 4608In the future they will be copied into the GCC manual, in @ref{Machine 4609Constraints}, replacing the hand-maintained tables currently found in 4610that section. Also, in the future the compiler may use this to give 4611more helpful diagnostics when poor choice of @code{asm} constraints 4612causes a reload failure. 4613 4614If you put the pseudo-Texinfo directive @samp{@@internal} at the 4615beginning of a docstring, then (in the future) it will appear only in 4616the internals manual's version of the machine-specific constraint tables. 4617Use this for constraints that should not appear in @code{asm} statements. 4618 4619@node C Constraint Interface 4620@subsection Testing constraints from C 4621@cindex testing constraints 4622@cindex constraints, testing 4623 4624It is occasionally useful to test a constraint from C code rather than 4625implicitly via the constraint string in a @code{match_operand}. The 4626generated file @file{tm_p.h} declares a few interfaces for working 4627with constraints. At present these are defined for all constraints 4628except @code{g} (which is equivalent to @code{general_operand}). 4629 4630Some valid constraint names are not valid C identifiers, so there is a 4631mangling scheme for referring to them from C@. Constraint names that 4632do not contain angle brackets or underscores are left unchanged. 4633Underscores are doubled, each @samp{<} is replaced with @samp{_l}, and 4634each @samp{>} with @samp{_g}. Here are some examples: 4635 4636@c the @c's prevent double blank lines in the printed manual. 4637@example 4638@multitable {Original} {Mangled} 4639@item @strong{Original} @tab @strong{Mangled} @c 4640@item @code{x} @tab @code{x} @c 4641@item @code{P42x} @tab @code{P42x} @c 4642@item @code{P4_x} @tab @code{P4__x} @c 4643@item @code{P4>x} @tab @code{P4_gx} @c 4644@item @code{P4>>} @tab @code{P4_g_g} @c 4645@item @code{P4_g>} @tab @code{P4__g_g} @c 4646@end multitable 4647@end example 4648 4649Throughout this section, the variable @var{c} is either a constraint 4650in the abstract sense, or a constant from @code{enum constraint_num}; 4651the variable @var{m} is a mangled constraint name (usually as part of 4652a larger identifier). 4653 4654@deftp Enum constraint_num 4655For each constraint except @code{g}, there is a corresponding 4656enumeration constant: @samp{CONSTRAINT_} plus the mangled name of the 4657constraint. Functions that take an @code{enum constraint_num} as an 4658argument expect one of these constants. 4659@end deftp 4660 4661@deftypefun {inline bool} satisfies_constraint_@var{m} (rtx @var{exp}) 4662For each non-register constraint @var{m} except @code{g}, there is 4663one of these functions; it returns @code{true} if @var{exp} satisfies the 4664constraint. These functions are only visible if @file{rtl.h} was included 4665before @file{tm_p.h}. 4666@end deftypefun 4667 4668@deftypefun bool constraint_satisfied_p (rtx @var{exp}, enum constraint_num @var{c}) 4669Like the @code{satisfies_constraint_@var{m}} functions, but the 4670constraint to test is given as an argument, @var{c}. If @var{c} 4671specifies a register constraint, this function will always return 4672@code{false}. 4673@end deftypefun 4674 4675@deftypefun {enum reg_class} reg_class_for_constraint (enum constraint_num @var{c}) 4676Returns the register class associated with @var{c}. If @var{c} is not 4677a register constraint, or those registers are not available for the 4678currently selected subtarget, returns @code{NO_REGS}. 4679@end deftypefun 4680 4681Here is an example use of @code{satisfies_constraint_@var{m}}. In 4682peephole optimizations (@pxref{Peephole Definitions}), operand 4683constraint strings are ignored, so if there are relevant constraints, 4684they must be tested in the C condition. In the example, the 4685optimization is applied if operand 2 does @emph{not} satisfy the 4686@samp{K} constraint. (This is a simplified version of a peephole 4687definition from the i386 machine description.) 4688 4689@smallexample 4690(define_peephole2 4691 [(match_scratch:SI 3 "r") 4692 (set (match_operand:SI 0 "register_operand" "") 4693 (mult:SI (match_operand:SI 1 "memory_operand" "") 4694 (match_operand:SI 2 "immediate_operand" "")))] 4695 4696 "!satisfies_constraint_K (operands[2])" 4697 4698 [(set (match_dup 3) (match_dup 1)) 4699 (set (match_dup 0) (mult:SI (match_dup 3) (match_dup 2)))] 4700 4701 "") 4702@end smallexample 4703 4704@node Standard Names 4705@section Standard Pattern Names For Generation 4706@cindex standard pattern names 4707@cindex pattern names 4708@cindex names, pattern 4709 4710Here is a table of the instruction names that are meaningful in the RTL 4711generation pass of the compiler. Giving one of these names to an 4712instruction pattern tells the RTL generation pass that it can use the 4713pattern to accomplish a certain task. 4714 4715@table @asis 4716@cindex @code{mov@var{m}} instruction pattern 4717@item @samp{mov@var{m}} 4718Here @var{m} stands for a two-letter machine mode name, in lowercase. 4719This instruction pattern moves data with that machine mode from operand 47201 to operand 0. For example, @samp{movsi} moves full-word data. 4721 4722If operand 0 is a @code{subreg} with mode @var{m} of a register whose 4723own mode is wider than @var{m}, the effect of this instruction is 4724to store the specified value in the part of the register that corresponds 4725to mode @var{m}. Bits outside of @var{m}, but which are within the 4726same target word as the @code{subreg} are undefined. Bits which are 4727outside the target word are left unchanged. 4728 4729This class of patterns is special in several ways. First of all, each 4730of these names up to and including full word size @emph{must} be defined, 4731because there is no other way to copy a datum from one place to another. 4732If there are patterns accepting operands in larger modes, 4733@samp{mov@var{m}} must be defined for integer modes of those sizes. 4734 4735Second, these patterns are not used solely in the RTL generation pass. 4736Even the reload pass can generate move insns to copy values from stack 4737slots into temporary registers. When it does so, one of the operands is 4738a hard register and the other is an operand that can need to be reloaded 4739into a register. 4740 4741@findex force_reg 4742Therefore, when given such a pair of operands, the pattern must generate 4743RTL which needs no reloading and needs no temporary registers---no 4744registers other than the operands. For example, if you support the 4745pattern with a @code{define_expand}, then in such a case the 4746@code{define_expand} mustn't call @code{force_reg} or any other such 4747function which might generate new pseudo registers. 4748 4749This requirement exists even for subword modes on a RISC machine where 4750fetching those modes from memory normally requires several insns and 4751some temporary registers. 4752 4753@findex change_address 4754During reload a memory reference with an invalid address may be passed 4755as an operand. Such an address will be replaced with a valid address 4756later in the reload pass. In this case, nothing may be done with the 4757address except to use it as it stands. If it is copied, it will not be 4758replaced with a valid address. No attempt should be made to make such 4759an address into a valid address and no routine (such as 4760@code{change_address}) that will do so may be called. Note that 4761@code{general_operand} will fail when applied to such an address. 4762 4763@findex reload_in_progress 4764The global variable @code{reload_in_progress} (which must be explicitly 4765declared if required) can be used to determine whether such special 4766handling is required. 4767 4768The variety of operands that have reloads depends on the rest of the 4769machine description, but typically on a RISC machine these can only be 4770pseudo registers that did not get hard registers, while on other 4771machines explicit memory references will get optional reloads. 4772 4773If a scratch register is required to move an object to or from memory, 4774it can be allocated using @code{gen_reg_rtx} prior to life analysis. 4775 4776If there are cases which need scratch registers during or after reload, 4777you must provide an appropriate secondary_reload target hook. 4778 4779@findex can_create_pseudo_p 4780The macro @code{can_create_pseudo_p} can be used to determine if it 4781is unsafe to create new pseudo registers. If this variable is nonzero, then 4782it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo. 4783 4784The constraints on a @samp{mov@var{m}} must permit moving any hard 4785register to any other hard register provided that 4786@code{TARGET_HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and 4787@code{TARGET_REGISTER_MOVE_COST} applied to their classes returns a value 4788of 2. 4789 4790It is obligatory to support floating point @samp{mov@var{m}} 4791instructions into and out of any registers that can hold fixed point 4792values, because unions and structures (which have modes @code{SImode} or 4793@code{DImode}) can be in those registers and they may have floating 4794point members. 4795 4796There may also be a need to support fixed point @samp{mov@var{m}} 4797instructions in and out of floating point registers. Unfortunately, I 4798have forgotten why this was so, and I don't know whether it is still 4799true. If @code{TARGET_HARD_REGNO_MODE_OK} rejects fixed point values in 4800floating point registers, then the constraints of the fixed point 4801@samp{mov@var{m}} instructions must be designed to avoid ever trying to 4802reload into a floating point register. 4803 4804@cindex @code{reload_in} instruction pattern 4805@cindex @code{reload_out} instruction pattern 4806@item @samp{reload_in@var{m}} 4807@itemx @samp{reload_out@var{m}} 4808These named patterns have been obsoleted by the target hook 4809@code{secondary_reload}. 4810 4811Like @samp{mov@var{m}}, but used when a scratch register is required to 4812move between operand 0 and operand 1. Operand 2 describes the scratch 4813register. See the discussion of the @code{SECONDARY_RELOAD_CLASS} 4814macro in @pxref{Register Classes}. 4815 4816There are special restrictions on the form of the @code{match_operand}s 4817used in these patterns. First, only the predicate for the reload 4818operand is examined, i.e., @code{reload_in} examines operand 1, but not 4819the predicates for operand 0 or 2. Second, there may be only one 4820alternative in the constraints. Third, only a single register class 4821letter may be used for the constraint; subsequent constraint letters 4822are ignored. As a special exception, an empty constraint string 4823matches the @code{ALL_REGS} register class. This may relieve ports 4824of the burden of defining an @code{ALL_REGS} constraint letter just 4825for these patterns. 4826 4827@cindex @code{movstrict@var{m}} instruction pattern 4828@item @samp{movstrict@var{m}} 4829Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg} 4830with mode @var{m} of a register whose natural mode is wider, 4831the @samp{movstrict@var{m}} instruction is guaranteed not to alter 4832any of the register except the part which belongs to mode @var{m}. 4833 4834@cindex @code{movmisalign@var{m}} instruction pattern 4835@item @samp{movmisalign@var{m}} 4836This variant of a move pattern is designed to load or store a value 4837from a memory address that is not naturally aligned for its mode. 4838For a store, the memory will be in operand 0; for a load, the memory 4839will be in operand 1. The other operand is guaranteed not to be a 4840memory, so that it's easy to tell whether this is a load or store. 4841 4842This pattern is used by the autovectorizer, and when expanding a 4843@code{MISALIGNED_INDIRECT_REF} expression. 4844 4845@cindex @code{load_multiple} instruction pattern 4846@item @samp{load_multiple} 4847Load several consecutive memory locations into consecutive registers. 4848Operand 0 is the first of the consecutive registers, operand 1 4849is the first memory location, and operand 2 is a constant: the 4850number of consecutive registers. 4851 4852Define this only if the target machine really has such an instruction; 4853do not define this if the most efficient way of loading consecutive 4854registers from memory is to do them one at a time. 4855 4856On some machines, there are restrictions as to which consecutive 4857registers can be stored into memory, such as particular starting or 4858ending register numbers or only a range of valid counts. For those 4859machines, use a @code{define_expand} (@pxref{Expander Definitions}) 4860and make the pattern fail if the restrictions are not met. 4861 4862Write the generated insn as a @code{parallel} with elements being a 4863@code{set} of one register from the appropriate memory location (you may 4864also need @code{use} or @code{clobber} elements). Use a 4865@code{match_parallel} (@pxref{RTL Template}) to recognize the insn. See 4866@file{rs6000.md} for examples of the use of this insn pattern. 4867 4868@cindex @samp{store_multiple} instruction pattern 4869@item @samp{store_multiple} 4870Similar to @samp{load_multiple}, but store several consecutive registers 4871into consecutive memory locations. Operand 0 is the first of the 4872consecutive memory locations, operand 1 is the first register, and 4873operand 2 is a constant: the number of consecutive registers. 4874 4875@cindex @code{vec_load_lanes@var{m}@var{n}} instruction pattern 4876@item @samp{vec_load_lanes@var{m}@var{n}} 4877Perform an interleaved load of several vectors from memory operand 1 4878into register operand 0. Both operands have mode @var{m}. The register 4879operand is viewed as holding consecutive vectors of mode @var{n}, 4880while the memory operand is a flat array that contains the same number 4881of elements. The operation is equivalent to: 4882 4883@smallexample 4884int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4885for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4886 for (i = 0; i < c; i++) 4887 operand0[i][j] = operand1[j * c + i]; 4888@end smallexample 4889 4890For example, @samp{vec_load_lanestiv4hi} loads 8 16-bit values 4891from memory into a register of mode @samp{TI}@. The register 4892contains two consecutive vectors of mode @samp{V4HI}@. 4893 4894This pattern can only be used if: 4895@smallexample 4896TARGET_ARRAY_MODE_SUPPORTED_P (@var{n}, @var{c}) 4897@end smallexample 4898is true. GCC assumes that, if a target supports this kind of 4899instruction for some mode @var{n}, it also supports unaligned 4900loads for vectors of mode @var{n}. 4901 4902This pattern is not allowed to @code{FAIL}. 4903 4904@cindex @code{vec_mask_load_lanes@var{m}@var{n}} instruction pattern 4905@item @samp{vec_mask_load_lanes@var{m}@var{n}} 4906Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional 4907mask operand (operand 2) that specifies which elements of the destination 4908vectors should be loaded. Other elements of the destination 4909vectors are set to zero. The operation is equivalent to: 4910 4911@smallexample 4912int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4913for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4914 if (operand2[j]) 4915 for (i = 0; i < c; i++) 4916 operand0[i][j] = operand1[j * c + i]; 4917 else 4918 for (i = 0; i < c; i++) 4919 operand0[i][j] = 0; 4920@end smallexample 4921 4922This pattern is not allowed to @code{FAIL}. 4923 4924@cindex @code{vec_store_lanes@var{m}@var{n}} instruction pattern 4925@item @samp{vec_store_lanes@var{m}@var{n}} 4926Equivalent to @samp{vec_load_lanes@var{m}@var{n}}, with the memory 4927and register operands reversed. That is, the instruction is 4928equivalent to: 4929 4930@smallexample 4931int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4932for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4933 for (i = 0; i < c; i++) 4934 operand0[j * c + i] = operand1[i][j]; 4935@end smallexample 4936 4937for a memory operand 0 and register operand 1. 4938 4939This pattern is not allowed to @code{FAIL}. 4940 4941@cindex @code{vec_mask_store_lanes@var{m}@var{n}} instruction pattern 4942@item @samp{vec_mask_store_lanes@var{m}@var{n}} 4943Like @samp{vec_store_lanes@var{m}@var{n}}, but takes an additional 4944mask operand (operand 2) that specifies which elements of the source 4945vectors should be stored. The operation is equivalent to: 4946 4947@smallexample 4948int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4949for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4950 if (operand2[j]) 4951 for (i = 0; i < c; i++) 4952 operand0[j * c + i] = operand1[i][j]; 4953@end smallexample 4954 4955This pattern is not allowed to @code{FAIL}. 4956 4957@cindex @code{gather_load@var{m}@var{n}} instruction pattern 4958@item @samp{gather_load@var{m}@var{n}} 4959Load several separate memory locations into a vector of mode @var{m}. 4960Operand 1 is a scalar base address and operand 2 is a vector of mode @var{n} 4961containing offsets from that base. Operand 0 is a destination vector with 4962the same number of elements as @var{n}. For each element index @var{i}: 4963 4964@itemize @bullet 4965@item 4966extend the offset element @var{i} to address width, using zero 4967extension if operand 3 is 1 and sign extension if operand 3 is zero; 4968@item 4969multiply the extended offset by operand 4; 4970@item 4971add the result to the base; and 4972@item 4973load the value at that address into element @var{i} of operand 0. 4974@end itemize 4975 4976The value of operand 3 does not matter if the offsets are already 4977address width. 4978 4979@cindex @code{mask_gather_load@var{m}@var{n}} instruction pattern 4980@item @samp{mask_gather_load@var{m}@var{n}} 4981Like @samp{gather_load@var{m}@var{n}}, but takes an extra mask operand as 4982operand 5. Bit @var{i} of the mask is set if element @var{i} 4983of the result should be loaded from memory and clear if element @var{i} 4984of the result should be set to zero. 4985 4986@cindex @code{scatter_store@var{m}@var{n}} instruction pattern 4987@item @samp{scatter_store@var{m}@var{n}} 4988Store a vector of mode @var{m} into several distinct memory locations. 4989Operand 0 is a scalar base address and operand 1 is a vector of mode 4990@var{n} containing offsets from that base. Operand 4 is the vector of 4991values that should be stored, which has the same number of elements as 4992@var{n}. For each element index @var{i}: 4993 4994@itemize @bullet 4995@item 4996extend the offset element @var{i} to address width, using zero 4997extension if operand 2 is 1 and sign extension if operand 2 is zero; 4998@item 4999multiply the extended offset by operand 3; 5000@item 5001add the result to the base; and 5002@item 5003store element @var{i} of operand 4 to that address. 5004@end itemize 5005 5006The value of operand 2 does not matter if the offsets are already 5007address width. 5008 5009@cindex @code{mask_scatter_store@var{m}@var{n}} instruction pattern 5010@item @samp{mask_scatter_store@var{m}@var{n}} 5011Like @samp{scatter_store@var{m}@var{n}}, but takes an extra mask operand as 5012operand 5. Bit @var{i} of the mask is set if element @var{i} 5013of the result should be stored to memory. 5014 5015@cindex @code{vec_set@var{m}} instruction pattern 5016@item @samp{vec_set@var{m}} 5017Set given field in the vector value. Operand 0 is the vector to modify, 5018operand 1 is new value of field and operand 2 specify the field index. 5019 5020@cindex @code{vec_extract@var{m}@var{n}} instruction pattern 5021@item @samp{vec_extract@var{m}@var{n}} 5022Extract given field from the vector value. Operand 1 is the vector, operand 2 5023specify field index and operand 0 place to store value into. The 5024@var{n} mode is the mode of the field or vector of fields that should be 5025extracted, should be either element mode of the vector mode @var{m}, or 5026a vector mode with the same element mode and smaller number of elements. 5027If @var{n} is a vector mode, the index is counted in units of that mode. 5028 5029@cindex @code{vec_init@var{m}@var{n}} instruction pattern 5030@item @samp{vec_init@var{m}@var{n}} 5031Initialize the vector to given values. Operand 0 is the vector to initialize 5032and operand 1 is parallel containing values for individual fields. The 5033@var{n} mode is the mode of the elements, should be either element mode of 5034the vector mode @var{m}, or a vector mode with the same element mode and 5035smaller number of elements. 5036 5037@cindex @code{vec_duplicate@var{m}} instruction pattern 5038@item @samp{vec_duplicate@var{m}} 5039Initialize vector output operand 0 so that each element has the value given 5040by scalar input operand 1. The vector has mode @var{m} and the scalar has 5041the mode appropriate for one element of @var{m}. 5042 5043This pattern only handles duplicates of non-constant inputs. Constant 5044vectors go through the @code{mov@var{m}} pattern instead. 5045 5046This pattern is not allowed to @code{FAIL}. 5047 5048@cindex @code{vec_series@var{m}} instruction pattern 5049@item @samp{vec_series@var{m}} 5050Initialize vector output operand 0 so that element @var{i} is equal to 5051operand 1 plus @var{i} times operand 2. In other words, create a linear 5052series whose base value is operand 1 and whose step is operand 2. 5053 5054The vector output has mode @var{m} and the scalar inputs have the mode 5055appropriate for one element of @var{m}. This pattern is not used for 5056floating-point vectors, in order to avoid having to specify the 5057rounding behavior for @var{i} > 1. 5058 5059This pattern is not allowed to @code{FAIL}. 5060 5061@cindex @code{while_ult@var{m}@var{n}} instruction pattern 5062@item @code{while_ult@var{m}@var{n}} 5063Set operand 0 to a mask that is true while incrementing operand 1 5064gives a value that is less than operand 2. Operand 0 has mode @var{n} 5065and operands 1 and 2 are scalar integers of mode @var{m}. 5066The operation is equivalent to: 5067 5068@smallexample 5069operand0[0] = operand1 < operand2; 5070for (i = 1; i < GET_MODE_NUNITS (@var{n}); i++) 5071 operand0[i] = operand0[i - 1] && (operand1 + i < operand2); 5072@end smallexample 5073 5074@cindex @code{check_raw_ptrs@var{m}} instruction pattern 5075@item @samp{check_raw_ptrs@var{m}} 5076Check whether, given two pointers @var{a} and @var{b} and a length @var{len}, 5077a write of @var{len} bytes at @var{a} followed by a read of @var{len} bytes 5078at @var{b} can be split into interleaved byte accesses 5079@samp{@var{a}[0], @var{b}[0], @var{a}[1], @var{b}[1], @dots{}} 5080without affecting the dependencies between the bytes. Set operand 0 5081to true if the split is possible and false otherwise. 5082 5083Operands 1, 2 and 3 provide the values of @var{a}, @var{b} and @var{len} 5084respectively. Operand 4 is a constant integer that provides the known 5085common alignment of @var{a} and @var{b}. All inputs have mode @var{m}. 5086 5087This split is possible if: 5088 5089@smallexample 5090@var{a} == @var{b} || @var{a} + @var{len} <= @var{b} || @var{b} + @var{len} <= @var{a} 5091@end smallexample 5092 5093You should only define this pattern if the target has a way of accelerating 5094the test without having to do the individual comparisons. 5095 5096@cindex @code{check_war_ptrs@var{m}} instruction pattern 5097@item @samp{check_war_ptrs@var{m}} 5098Like @samp{check_raw_ptrs@var{m}}, but with the read and write swapped round. 5099The split is possible in this case if: 5100 5101@smallexample 5102@var{b} <= @var{a} || @var{a} + @var{len} <= @var{b} 5103@end smallexample 5104 5105@cindex @code{vec_cmp@var{m}@var{n}} instruction pattern 5106@item @samp{vec_cmp@var{m}@var{n}} 5107Output a vector comparison. Operand 0 of mode @var{n} is the destination for 5108predicate in operand 1 which is a signed vector comparison with operands of 5109mode @var{m} in operands 2 and 3. Predicate is computed by element-wise 5110evaluation of the vector comparison with a truth value of all-ones and a false 5111value of all-zeros. 5112 5113@cindex @code{vec_cmpu@var{m}@var{n}} instruction pattern 5114@item @samp{vec_cmpu@var{m}@var{n}} 5115Similar to @code{vec_cmp@var{m}@var{n}} but perform unsigned vector comparison. 5116 5117@cindex @code{vec_cmpeq@var{m}@var{n}} instruction pattern 5118@item @samp{vec_cmpeq@var{m}@var{n}} 5119Similar to @code{vec_cmp@var{m}@var{n}} but perform equality or non-equality 5120vector comparison only. If @code{vec_cmp@var{m}@var{n}} 5121or @code{vec_cmpu@var{m}@var{n}} instruction pattern is supported, 5122it will be preferred over @code{vec_cmpeq@var{m}@var{n}}, so there is 5123no need to define this instruction pattern if the others are supported. 5124 5125@cindex @code{vcond@var{m}@var{n}} instruction pattern 5126@item @samp{vcond@var{m}@var{n}} 5127Output a conditional vector move. Operand 0 is the destination to 5128receive a combination of operand 1 and operand 2, which are of mode @var{m}, 5129dependent on the outcome of the predicate in operand 3 which is a signed 5130vector comparison with operands of mode @var{n} in operands 4 and 5. The 5131modes @var{m} and @var{n} should have the same size. Operand 0 5132will be set to the value @var{op1} & @var{msk} | @var{op2} & ~@var{msk} 5133where @var{msk} is computed by element-wise evaluation of the vector 5134comparison with a truth value of all-ones and a false value of all-zeros. 5135 5136@cindex @code{vcondu@var{m}@var{n}} instruction pattern 5137@item @samp{vcondu@var{m}@var{n}} 5138Similar to @code{vcond@var{m}@var{n}} but performs unsigned vector 5139comparison. 5140 5141@cindex @code{vcondeq@var{m}@var{n}} instruction pattern 5142@item @samp{vcondeq@var{m}@var{n}} 5143Similar to @code{vcond@var{m}@var{n}} but performs equality or 5144non-equality vector comparison only. If @code{vcond@var{m}@var{n}} 5145or @code{vcondu@var{m}@var{n}} instruction pattern is supported, 5146it will be preferred over @code{vcondeq@var{m}@var{n}}, so there is 5147no need to define this instruction pattern if the others are supported. 5148 5149@cindex @code{vcond_mask_@var{m}@var{n}} instruction pattern 5150@item @samp{vcond_mask_@var{m}@var{n}} 5151Similar to @code{vcond@var{m}@var{n}} but operand 3 holds a pre-computed 5152result of vector comparison. 5153 5154@cindex @code{maskload@var{m}@var{n}} instruction pattern 5155@item @samp{maskload@var{m}@var{n}} 5156Perform a masked load of vector from memory operand 1 of mode @var{m} 5157into register operand 0. Mask is provided in register operand 2 of 5158mode @var{n}. 5159 5160This pattern is not allowed to @code{FAIL}. 5161 5162@cindex @code{maskstore@var{m}@var{n}} instruction pattern 5163@item @samp{maskstore@var{m}@var{n}} 5164Perform a masked store of vector from register operand 1 of mode @var{m} 5165into memory operand 0. Mask is provided in register operand 2 of 5166mode @var{n}. 5167 5168This pattern is not allowed to @code{FAIL}. 5169 5170@cindex @code{vec_perm@var{m}} instruction pattern 5171@item @samp{vec_perm@var{m}} 5172Output a (variable) vector permutation. Operand 0 is the destination 5173to receive elements from operand 1 and operand 2, which are of mode 5174@var{m}. Operand 3 is the @dfn{selector}. It is an integral mode 5175vector of the same width and number of elements as mode @var{m}. 5176 5177The input elements are numbered from 0 in operand 1 through 5178@math{2*@var{N}-1} in operand 2. The elements of the selector must 5179be computed modulo @math{2*@var{N}}. Note that if 5180@code{rtx_equal_p(operand1, operand2)}, this can be implemented 5181with just operand 1 and selector elements modulo @var{N}. 5182 5183In order to make things easy for a number of targets, if there is no 5184@samp{vec_perm} pattern for mode @var{m}, but there is for mode @var{q} 5185where @var{q} is a vector of @code{QImode} of the same width as @var{m}, 5186the middle-end will lower the mode @var{m} @code{VEC_PERM_EXPR} to 5187mode @var{q}. 5188 5189See also @code{TARGET_VECTORIZER_VEC_PERM_CONST}, which performs 5190the analogous operation for constant selectors. 5191 5192@cindex @code{push@var{m}1} instruction pattern 5193@item @samp{push@var{m}1} 5194Output a push instruction. Operand 0 is value to push. Used only when 5195@code{PUSH_ROUNDING} is defined. For historical reason, this pattern may be 5196missing and in such case an @code{mov} expander is used instead, with a 5197@code{MEM} expression forming the push operation. The @code{mov} expander 5198method is deprecated. 5199 5200@cindex @code{add@var{m}3} instruction pattern 5201@item @samp{add@var{m}3} 5202Add operand 2 and operand 1, storing the result in operand 0. All operands 5203must have mode @var{m}. This can be used even on two-address machines, by 5204means of constraints requiring operands 1 and 0 to be the same location. 5205 5206@cindex @code{ssadd@var{m}3} instruction pattern 5207@cindex @code{usadd@var{m}3} instruction pattern 5208@cindex @code{sub@var{m}3} instruction pattern 5209@cindex @code{sssub@var{m}3} instruction pattern 5210@cindex @code{ussub@var{m}3} instruction pattern 5211@cindex @code{mul@var{m}3} instruction pattern 5212@cindex @code{ssmul@var{m}3} instruction pattern 5213@cindex @code{usmul@var{m}3} instruction pattern 5214@cindex @code{div@var{m}3} instruction pattern 5215@cindex @code{ssdiv@var{m}3} instruction pattern 5216@cindex @code{udiv@var{m}3} instruction pattern 5217@cindex @code{usdiv@var{m}3} instruction pattern 5218@cindex @code{mod@var{m}3} instruction pattern 5219@cindex @code{umod@var{m}3} instruction pattern 5220@cindex @code{umin@var{m}3} instruction pattern 5221@cindex @code{umax@var{m}3} instruction pattern 5222@cindex @code{and@var{m}3} instruction pattern 5223@cindex @code{ior@var{m}3} instruction pattern 5224@cindex @code{xor@var{m}3} instruction pattern 5225@item @samp{ssadd@var{m}3}, @samp{usadd@var{m}3} 5226@itemx @samp{sub@var{m}3}, @samp{sssub@var{m}3}, @samp{ussub@var{m}3} 5227@itemx @samp{mul@var{m}3}, @samp{ssmul@var{m}3}, @samp{usmul@var{m}3} 5228@itemx @samp{div@var{m}3}, @samp{ssdiv@var{m}3} 5229@itemx @samp{udiv@var{m}3}, @samp{usdiv@var{m}3} 5230@itemx @samp{mod@var{m}3}, @samp{umod@var{m}3} 5231@itemx @samp{umin@var{m}3}, @samp{umax@var{m}3} 5232@itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3} 5233Similar, for other arithmetic operations. 5234 5235@cindex @code{addv@var{m}4} instruction pattern 5236@item @samp{addv@var{m}4} 5237Like @code{add@var{m}3} but takes a @code{code_label} as operand 3 and 5238emits code to jump to it if signed overflow occurs during the addition. 5239This pattern is used to implement the built-in functions performing 5240signed integer addition with overflow checking. 5241 5242@cindex @code{subv@var{m}4} instruction pattern 5243@cindex @code{mulv@var{m}4} instruction pattern 5244@item @samp{subv@var{m}4}, @samp{mulv@var{m}4} 5245Similar, for other signed arithmetic operations. 5246 5247@cindex @code{uaddv@var{m}4} instruction pattern 5248@item @samp{uaddv@var{m}4} 5249Like @code{addv@var{m}4} but for unsigned addition. That is to 5250say, the operation is the same as signed addition but the jump 5251is taken only on unsigned overflow. 5252 5253@cindex @code{usubv@var{m}4} instruction pattern 5254@cindex @code{umulv@var{m}4} instruction pattern 5255@item @samp{usubv@var{m}4}, @samp{umulv@var{m}4} 5256Similar, for other unsigned arithmetic operations. 5257 5258@cindex @code{addptr@var{m}3} instruction pattern 5259@item @samp{addptr@var{m}3} 5260Like @code{add@var{m}3} but is guaranteed to only be used for address 5261calculations. The expanded code is not allowed to clobber the 5262condition code. It only needs to be defined if @code{add@var{m}3} 5263sets the condition code. If adds used for address calculations and 5264normal adds are not compatible it is required to expand a distinct 5265pattern (e.g.@: using an unspec). The pattern is used by LRA to emit 5266address calculations. @code{add@var{m}3} is used if 5267@code{addptr@var{m}3} is not defined. 5268 5269@cindex @code{fma@var{m}4} instruction pattern 5270@item @samp{fma@var{m}4} 5271Multiply operand 2 and operand 1, then add operand 3, storing the 5272result in operand 0 without doing an intermediate rounding step. All 5273operands must have mode @var{m}. This pattern is used to implement 5274the @code{fma}, @code{fmaf}, and @code{fmal} builtin functions from 5275the ISO C99 standard. 5276 5277@cindex @code{fms@var{m}4} instruction pattern 5278@item @samp{fms@var{m}4} 5279Like @code{fma@var{m}4}, except operand 3 subtracted from the 5280product instead of added to the product. This is represented 5281in the rtl as 5282 5283@smallexample 5284(fma:@var{m} @var{op1} @var{op2} (neg:@var{m} @var{op3})) 5285@end smallexample 5286 5287@cindex @code{fnma@var{m}4} instruction pattern 5288@item @samp{fnma@var{m}4} 5289Like @code{fma@var{m}4} except that the intermediate product 5290is negated before being added to operand 3. This is represented 5291in the rtl as 5292 5293@smallexample 5294(fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} @var{op3}) 5295@end smallexample 5296 5297@cindex @code{fnms@var{m}4} instruction pattern 5298@item @samp{fnms@var{m}4} 5299Like @code{fms@var{m}4} except that the intermediate product 5300is negated before subtracting operand 3. This is represented 5301in the rtl as 5302 5303@smallexample 5304(fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} (neg:@var{m} @var{op3})) 5305@end smallexample 5306 5307@cindex @code{min@var{m}3} instruction pattern 5308@cindex @code{max@var{m}3} instruction pattern 5309@item @samp{smin@var{m}3}, @samp{smax@var{m}3} 5310Signed minimum and maximum operations. When used with floating point, 5311if both operands are zeros, or if either operand is @code{NaN}, then 5312it is unspecified which of the two operands is returned as the result. 5313 5314@cindex @code{fmin@var{m}3} instruction pattern 5315@cindex @code{fmax@var{m}3} instruction pattern 5316@item @samp{fmin@var{m}3}, @samp{fmax@var{m}3} 5317IEEE-conformant minimum and maximum operations. If one operand is a quiet 5318@code{NaN}, then the other operand is returned. If both operands are quiet 5319@code{NaN}, then a quiet @code{NaN} is returned. In the case when gcc supports 5320signaling @code{NaN} (-fsignaling-nans) an invalid floating point exception is 5321raised and a quiet @code{NaN} is returned. 5322 5323All operands have mode @var{m}, which is a scalar or vector 5324floating-point mode. These patterns are not allowed to @code{FAIL}. 5325 5326@cindex @code{reduc_smin_scal_@var{m}} instruction pattern 5327@cindex @code{reduc_smax_scal_@var{m}} instruction pattern 5328@item @samp{reduc_smin_scal_@var{m}}, @samp{reduc_smax_scal_@var{m}} 5329Find the signed minimum/maximum of the elements of a vector. The vector is 5330operand 1, and operand 0 is the scalar result, with mode equal to the mode of 5331the elements of the input vector. 5332 5333@cindex @code{reduc_umin_scal_@var{m}} instruction pattern 5334@cindex @code{reduc_umax_scal_@var{m}} instruction pattern 5335@item @samp{reduc_umin_scal_@var{m}}, @samp{reduc_umax_scal_@var{m}} 5336Find the unsigned minimum/maximum of the elements of a vector. The vector is 5337operand 1, and operand 0 is the scalar result, with mode equal to the mode of 5338the elements of the input vector. 5339 5340@cindex @code{reduc_plus_scal_@var{m}} instruction pattern 5341@item @samp{reduc_plus_scal_@var{m}} 5342Compute the sum of the elements of a vector. The vector is operand 1, and 5343operand 0 is the scalar result, with mode equal to the mode of the elements of 5344the input vector. 5345 5346@cindex @code{reduc_and_scal_@var{m}} instruction pattern 5347@item @samp{reduc_and_scal_@var{m}} 5348@cindex @code{reduc_ior_scal_@var{m}} instruction pattern 5349@itemx @samp{reduc_ior_scal_@var{m}} 5350@cindex @code{reduc_xor_scal_@var{m}} instruction pattern 5351@itemx @samp{reduc_xor_scal_@var{m}} 5352Compute the bitwise @code{AND}/@code{IOR}/@code{XOR} reduction of the elements 5353of a vector of mode @var{m}. Operand 1 is the vector input and operand 0 5354is the scalar result. The mode of the scalar result is the same as one 5355element of @var{m}. 5356 5357@cindex @code{extract_last_@var{m}} instruction pattern 5358@item @code{extract_last_@var{m}} 5359Find the last set bit in mask operand 1 and extract the associated element 5360of vector operand 2. Store the result in scalar operand 0. Operand 2 5361has vector mode @var{m} while operand 0 has the mode appropriate for one 5362element of @var{m}. Operand 1 has the usual mask mode for vectors of mode 5363@var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}. 5364 5365@cindex @code{fold_extract_last_@var{m}} instruction pattern 5366@item @code{fold_extract_last_@var{m}} 5367If any bits of mask operand 2 are set, find the last set bit, extract 5368the associated element from vector operand 3, and store the result 5369in operand 0. Store operand 1 in operand 0 otherwise. Operand 3 5370has mode @var{m} and operands 0 and 1 have the mode appropriate for 5371one element of @var{m}. Operand 2 has the usual mask mode for vectors 5372of mode @var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}. 5373 5374@cindex @code{fold_left_plus_@var{m}} instruction pattern 5375@item @code{fold_left_plus_@var{m}} 5376Take scalar operand 1 and successively add each element from vector 5377operand 2. Store the result in scalar operand 0. The vector has 5378mode @var{m} and the scalars have the mode appropriate for one 5379element of @var{m}. The operation is strictly in-order: there is 5380no reassociation. 5381 5382@cindex @code{mask_fold_left_plus_@var{m}} instruction pattern 5383@item @code{mask_fold_left_plus_@var{m}} 5384Like @samp{fold_left_plus_@var{m}}, but takes an additional mask operand 5385(operand 3) that specifies which elements of the source vector should be added. 5386 5387@cindex @code{sdot_prod@var{m}} instruction pattern 5388@item @samp{sdot_prod@var{m}} 5389@cindex @code{udot_prod@var{m}} instruction pattern 5390@itemx @samp{udot_prod@var{m}} 5391Compute the sum of the products of two signed/unsigned elements. 5392Operand 1 and operand 2 are of the same mode. Their product, which is of a 5393wider mode, is computed and added to operand 3. Operand 3 is of a mode equal or 5394wider than the mode of the product. The result is placed in operand 0, which 5395is of the same mode as operand 3. 5396 5397@cindex @code{ssad@var{m}} instruction pattern 5398@item @samp{ssad@var{m}} 5399@cindex @code{usad@var{m}} instruction pattern 5400@item @samp{usad@var{m}} 5401Compute the sum of absolute differences of two signed/unsigned elements. 5402Operand 1 and operand 2 are of the same mode. Their absolute difference, which 5403is of a wider mode, is computed and added to operand 3. Operand 3 is of a mode 5404equal or wider than the mode of the absolute difference. The result is placed 5405in operand 0, which is of the same mode as operand 3. 5406 5407@cindex @code{widen_ssum@var{m3}} instruction pattern 5408@item @samp{widen_ssum@var{m3}} 5409@cindex @code{widen_usum@var{m3}} instruction pattern 5410@itemx @samp{widen_usum@var{m3}} 5411Operands 0 and 2 are of the same mode, which is wider than the mode of 5412operand 1. Add operand 1 to operand 2 and place the widened result in 5413operand 0. (This is used express accumulation of elements into an accumulator 5414of a wider mode.) 5415 5416@cindex @code{smulhs@var{m3}} instruction pattern 5417@item @samp{smulhs@var{m3}} 5418@cindex @code{umulhs@var{m3}} instruction pattern 5419@itemx @samp{umulhs@var{m3}} 5420Signed/unsigned multiply high with scale. This is equivalent to the C code: 5421@smallexample 5422narrow op0, op1, op2; 5423@dots{} 5424op0 = (narrow) (((wide) op1 * (wide) op2) >> (N / 2 - 1)); 5425@end smallexample 5426where the sign of @samp{narrow} determines whether this is a signed 5427or unsigned operation, and @var{N} is the size of @samp{wide} in bits. 5428 5429@cindex @code{smulhrs@var{m3}} instruction pattern 5430@item @samp{smulhrs@var{m3}} 5431@cindex @code{umulhrs@var{m3}} instruction pattern 5432@itemx @samp{umulhrs@var{m3}} 5433Signed/unsigned multiply high with round and scale. This is 5434equivalent to the C code: 5435@smallexample 5436narrow op0, op1, op2; 5437@dots{} 5438op0 = (narrow) (((((wide) op1 * (wide) op2) >> (N / 2 - 2)) + 1) >> 1); 5439@end smallexample 5440where the sign of @samp{narrow} determines whether this is a signed 5441or unsigned operation, and @var{N} is the size of @samp{wide} in bits. 5442 5443@cindex @code{sdiv_pow2@var{m3}} instruction pattern 5444@item @samp{sdiv_pow2@var{m3}} 5445@cindex @code{sdiv_pow2@var{m3}} instruction pattern 5446@itemx @samp{sdiv_pow2@var{m3}} 5447Signed division by power-of-2 immediate. Equivalent to: 5448@smallexample 5449signed op0, op1; 5450@dots{} 5451op0 = op1 / (1 << imm); 5452@end smallexample 5453 5454@cindex @code{vec_shl_insert_@var{m}} instruction pattern 5455@item @samp{vec_shl_insert_@var{m}} 5456Shift the elements in vector input operand 1 left one element (i.e.@: 5457away from element 0) and fill the vacated element 0 with the scalar 5458in operand 2. Store the result in vector output operand 0. Operands 54590 and 1 have mode @var{m} and operand 2 has the mode appropriate for 5460one element of @var{m}. 5461 5462@cindex @code{vec_shl_@var{m}} instruction pattern 5463@item @samp{vec_shl_@var{m}} 5464Whole vector left shift in bits, i.e.@: away from element 0. 5465Operand 1 is a vector to be shifted. 5466Operand 2 is an integer shift amount in bits. 5467Operand 0 is where the resulting shifted vector is stored. 5468The output and input vectors should have the same modes. 5469 5470@cindex @code{vec_shr_@var{m}} instruction pattern 5471@item @samp{vec_shr_@var{m}} 5472Whole vector right shift in bits, i.e.@: towards element 0. 5473Operand 1 is a vector to be shifted. 5474Operand 2 is an integer shift amount in bits. 5475Operand 0 is where the resulting shifted vector is stored. 5476The output and input vectors should have the same modes. 5477 5478@cindex @code{vec_pack_trunc_@var{m}} instruction pattern 5479@item @samp{vec_pack_trunc_@var{m}} 5480Narrow (demote) and merge the elements of two vectors. Operands 1 and 2 5481are vectors of the same mode having N integral or floating point elements 5482of size S@. Operand 0 is the resulting vector in which 2*N elements of 5483size S/2 are concatenated after narrowing them down using truncation. 5484 5485@cindex @code{vec_pack_sbool_trunc_@var{m}} instruction pattern 5486@item @samp{vec_pack_sbool_trunc_@var{m}} 5487Narrow and merge the elements of two vectors. Operands 1 and 2 are vectors 5488of the same type having N boolean elements. Operand 0 is the resulting 5489vector in which 2*N elements are concatenated. The last operand (operand 3) 5490is the number of elements in the output vector 2*N as a @code{CONST_INT}. 5491This instruction pattern is used when all the vector input and output 5492operands have the same scalar mode @var{m} and thus using 5493@code{vec_pack_trunc_@var{m}} would be ambiguous. 5494 5495@cindex @code{vec_pack_ssat_@var{m}} instruction pattern 5496@cindex @code{vec_pack_usat_@var{m}} instruction pattern 5497@item @samp{vec_pack_ssat_@var{m}}, @samp{vec_pack_usat_@var{m}} 5498Narrow (demote) and merge the elements of two vectors. Operands 1 and 2 5499are vectors of the same mode having N integral elements of size S. 5500Operand 0 is the resulting vector in which the elements of the two input 5501vectors are concatenated after narrowing them down using signed/unsigned 5502saturating arithmetic. 5503 5504@cindex @code{vec_pack_sfix_trunc_@var{m}} instruction pattern 5505@cindex @code{vec_pack_ufix_trunc_@var{m}} instruction pattern 5506@item @samp{vec_pack_sfix_trunc_@var{m}}, @samp{vec_pack_ufix_trunc_@var{m}} 5507Narrow, convert to signed/unsigned integral type and merge the elements 5508of two vectors. Operands 1 and 2 are vectors of the same mode having N 5509floating point elements of size S@. Operand 0 is the resulting vector 5510in which 2*N elements of size S/2 are concatenated. 5511 5512@cindex @code{vec_packs_float_@var{m}} instruction pattern 5513@cindex @code{vec_packu_float_@var{m}} instruction pattern 5514@item @samp{vec_packs_float_@var{m}}, @samp{vec_packu_float_@var{m}} 5515Narrow, convert to floating point type and merge the elements 5516of two vectors. Operands 1 and 2 are vectors of the same mode having N 5517signed/unsigned integral elements of size S@. Operand 0 is the resulting vector 5518in which 2*N elements of size S/2 are concatenated. 5519 5520@cindex @code{vec_unpacks_hi_@var{m}} instruction pattern 5521@cindex @code{vec_unpacks_lo_@var{m}} instruction pattern 5522@item @samp{vec_unpacks_hi_@var{m}}, @samp{vec_unpacks_lo_@var{m}} 5523Extract and widen (promote) the high/low part of a vector of signed 5524integral or floating point elements. The input vector (operand 1) has N 5525elements of size S@. Widen (promote) the high/low elements of the vector 5526using signed or floating point extension and place the resulting N/2 5527values of size 2*S in the output vector (operand 0). 5528 5529@cindex @code{vec_unpacku_hi_@var{m}} instruction pattern 5530@cindex @code{vec_unpacku_lo_@var{m}} instruction pattern 5531@item @samp{vec_unpacku_hi_@var{m}}, @samp{vec_unpacku_lo_@var{m}} 5532Extract and widen (promote) the high/low part of a vector of unsigned 5533integral elements. The input vector (operand 1) has N elements of size S. 5534Widen (promote) the high/low elements of the vector using zero extension and 5535place the resulting N/2 values of size 2*S in the output vector (operand 0). 5536 5537@cindex @code{vec_unpacks_sbool_hi_@var{m}} instruction pattern 5538@cindex @code{vec_unpacks_sbool_lo_@var{m}} instruction pattern 5539@item @samp{vec_unpacks_sbool_hi_@var{m}}, @samp{vec_unpacks_sbool_lo_@var{m}} 5540Extract the high/low part of a vector of boolean elements that have scalar 5541mode @var{m}. The input vector (operand 1) has N elements, the output 5542vector (operand 0) has N/2 elements. The last operand (operand 2) is the 5543number of elements of the input vector N as a @code{CONST_INT}. These 5544patterns are used if both the input and output vectors have the same scalar 5545mode @var{m} and thus using @code{vec_unpacks_hi_@var{m}} or 5546@code{vec_unpacks_lo_@var{m}} would be ambiguous. 5547 5548@cindex @code{vec_unpacks_float_hi_@var{m}} instruction pattern 5549@cindex @code{vec_unpacks_float_lo_@var{m}} instruction pattern 5550@cindex @code{vec_unpacku_float_hi_@var{m}} instruction pattern 5551@cindex @code{vec_unpacku_float_lo_@var{m}} instruction pattern 5552@item @samp{vec_unpacks_float_hi_@var{m}}, @samp{vec_unpacks_float_lo_@var{m}} 5553@itemx @samp{vec_unpacku_float_hi_@var{m}}, @samp{vec_unpacku_float_lo_@var{m}} 5554Extract, convert to floating point type and widen the high/low part of a 5555vector of signed/unsigned integral elements. The input vector (operand 1) 5556has N elements of size S@. Convert the high/low elements of the vector using 5557floating point conversion and place the resulting N/2 values of size 2*S in 5558the output vector (operand 0). 5559 5560@cindex @code{vec_unpack_sfix_trunc_hi_@var{m}} instruction pattern 5561@cindex @code{vec_unpack_sfix_trunc_lo_@var{m}} instruction pattern 5562@cindex @code{vec_unpack_ufix_trunc_hi_@var{m}} instruction pattern 5563@cindex @code{vec_unpack_ufix_trunc_lo_@var{m}} instruction pattern 5564@item @samp{vec_unpack_sfix_trunc_hi_@var{m}}, 5565@itemx @samp{vec_unpack_sfix_trunc_lo_@var{m}} 5566@itemx @samp{vec_unpack_ufix_trunc_hi_@var{m}} 5567@itemx @samp{vec_unpack_ufix_trunc_lo_@var{m}} 5568Extract, convert to signed/unsigned integer type and widen the high/low part of a 5569vector of floating point elements. The input vector (operand 1) 5570has N elements of size S@. Convert the high/low elements of the vector 5571to integers and place the resulting N/2 values of size 2*S in 5572the output vector (operand 0). 5573 5574@cindex @code{vec_widen_umult_hi_@var{m}} instruction pattern 5575@cindex @code{vec_widen_umult_lo_@var{m}} instruction pattern 5576@cindex @code{vec_widen_smult_hi_@var{m}} instruction pattern 5577@cindex @code{vec_widen_smult_lo_@var{m}} instruction pattern 5578@cindex @code{vec_widen_umult_even_@var{m}} instruction pattern 5579@cindex @code{vec_widen_umult_odd_@var{m}} instruction pattern 5580@cindex @code{vec_widen_smult_even_@var{m}} instruction pattern 5581@cindex @code{vec_widen_smult_odd_@var{m}} instruction pattern 5582@item @samp{vec_widen_umult_hi_@var{m}}, @samp{vec_widen_umult_lo_@var{m}} 5583@itemx @samp{vec_widen_smult_hi_@var{m}}, @samp{vec_widen_smult_lo_@var{m}} 5584@itemx @samp{vec_widen_umult_even_@var{m}}, @samp{vec_widen_umult_odd_@var{m}} 5585@itemx @samp{vec_widen_smult_even_@var{m}}, @samp{vec_widen_smult_odd_@var{m}} 5586Signed/Unsigned widening multiplication. The two inputs (operands 1 and 2) 5587are vectors with N signed/unsigned elements of size S@. Multiply the high/low 5588or even/odd elements of the two vectors, and put the N/2 products of size 2*S 5589in the output vector (operand 0). A target shouldn't implement even/odd pattern 5590pair if it is less efficient than lo/hi one. 5591 5592@cindex @code{vec_widen_ushiftl_hi_@var{m}} instruction pattern 5593@cindex @code{vec_widen_ushiftl_lo_@var{m}} instruction pattern 5594@cindex @code{vec_widen_sshiftl_hi_@var{m}} instruction pattern 5595@cindex @code{vec_widen_sshiftl_lo_@var{m}} instruction pattern 5596@item @samp{vec_widen_ushiftl_hi_@var{m}}, @samp{vec_widen_ushiftl_lo_@var{m}} 5597@itemx @samp{vec_widen_sshiftl_hi_@var{m}}, @samp{vec_widen_sshiftl_lo_@var{m}} 5598Signed/Unsigned widening shift left. The first input (operand 1) is a vector 5599with N signed/unsigned elements of size S@. Operand 2 is a constant. Shift 5600the high/low elements of operand 1, and put the N/2 results of size 2*S in the 5601output vector (operand 0). 5602 5603@cindex @code{mulhisi3} instruction pattern 5604@item @samp{mulhisi3} 5605Multiply operands 1 and 2, which have mode @code{HImode}, and store 5606a @code{SImode} product in operand 0. 5607 5608@cindex @code{mulqihi3} instruction pattern 5609@cindex @code{mulsidi3} instruction pattern 5610@item @samp{mulqihi3}, @samp{mulsidi3} 5611Similar widening-multiplication instructions of other widths. 5612 5613@cindex @code{umulqihi3} instruction pattern 5614@cindex @code{umulhisi3} instruction pattern 5615@cindex @code{umulsidi3} instruction pattern 5616@item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3} 5617Similar widening-multiplication instructions that do unsigned 5618multiplication. 5619 5620@cindex @code{usmulqihi3} instruction pattern 5621@cindex @code{usmulhisi3} instruction pattern 5622@cindex @code{usmulsidi3} instruction pattern 5623@item @samp{usmulqihi3}, @samp{usmulhisi3}, @samp{usmulsidi3} 5624Similar widening-multiplication instructions that interpret the first 5625operand as unsigned and the second operand as signed, then do a signed 5626multiplication. 5627 5628@cindex @code{smul@var{m}3_highpart} instruction pattern 5629@item @samp{smul@var{m}3_highpart} 5630Perform a signed multiplication of operands 1 and 2, which have mode 5631@var{m}, and store the most significant half of the product in operand 0. 5632The least significant half of the product is discarded. 5633 5634@cindex @code{umul@var{m}3_highpart} instruction pattern 5635@item @samp{umul@var{m}3_highpart} 5636Similar, but the multiplication is unsigned. 5637 5638@cindex @code{madd@var{m}@var{n}4} instruction pattern 5639@item @samp{madd@var{m}@var{n}4} 5640Multiply operands 1 and 2, sign-extend them to mode @var{n}, add 5641operand 3, and store the result in operand 0. Operands 1 and 2 5642have mode @var{m} and operands 0 and 3 have mode @var{n}. 5643Both modes must be integer or fixed-point modes and @var{n} must be twice 5644the size of @var{m}. 5645 5646In other words, @code{madd@var{m}@var{n}4} is like 5647@code{mul@var{m}@var{n}3} except that it also adds operand 3. 5648 5649These instructions are not allowed to @code{FAIL}. 5650 5651@cindex @code{umadd@var{m}@var{n}4} instruction pattern 5652@item @samp{umadd@var{m}@var{n}4} 5653Like @code{madd@var{m}@var{n}4}, but zero-extend the multiplication 5654operands instead of sign-extending them. 5655 5656@cindex @code{ssmadd@var{m}@var{n}4} instruction pattern 5657@item @samp{ssmadd@var{m}@var{n}4} 5658Like @code{madd@var{m}@var{n}4}, but all involved operations must be 5659signed-saturating. 5660 5661@cindex @code{usmadd@var{m}@var{n}4} instruction pattern 5662@item @samp{usmadd@var{m}@var{n}4} 5663Like @code{umadd@var{m}@var{n}4}, but all involved operations must be 5664unsigned-saturating. 5665 5666@cindex @code{msub@var{m}@var{n}4} instruction pattern 5667@item @samp{msub@var{m}@var{n}4} 5668Multiply operands 1 and 2, sign-extend them to mode @var{n}, subtract the 5669result from operand 3, and store the result in operand 0. Operands 1 and 2 5670have mode @var{m} and operands 0 and 3 have mode @var{n}. 5671Both modes must be integer or fixed-point modes and @var{n} must be twice 5672the size of @var{m}. 5673 5674In other words, @code{msub@var{m}@var{n}4} is like 5675@code{mul@var{m}@var{n}3} except that it also subtracts the result 5676from operand 3. 5677 5678These instructions are not allowed to @code{FAIL}. 5679 5680@cindex @code{umsub@var{m}@var{n}4} instruction pattern 5681@item @samp{umsub@var{m}@var{n}4} 5682Like @code{msub@var{m}@var{n}4}, but zero-extend the multiplication 5683operands instead of sign-extending them. 5684 5685@cindex @code{ssmsub@var{m}@var{n}4} instruction pattern 5686@item @samp{ssmsub@var{m}@var{n}4} 5687Like @code{msub@var{m}@var{n}4}, but all involved operations must be 5688signed-saturating. 5689 5690@cindex @code{usmsub@var{m}@var{n}4} instruction pattern 5691@item @samp{usmsub@var{m}@var{n}4} 5692Like @code{umsub@var{m}@var{n}4}, but all involved operations must be 5693unsigned-saturating. 5694 5695@cindex @code{divmod@var{m}4} instruction pattern 5696@item @samp{divmod@var{m}4} 5697Signed division that produces both a quotient and a remainder. 5698Operand 1 is divided by operand 2 to produce a quotient stored 5699in operand 0 and a remainder stored in operand 3. 5700 5701For machines with an instruction that produces both a quotient and a 5702remainder, provide a pattern for @samp{divmod@var{m}4} but do not 5703provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}. This 5704allows optimization in the relatively common case when both the quotient 5705and remainder are computed. 5706 5707If an instruction that just produces a quotient or just a remainder 5708exists and is more efficient than the instruction that produces both, 5709write the output routine of @samp{divmod@var{m}4} to call 5710@code{find_reg_note} and look for a @code{REG_UNUSED} note on the 5711quotient or remainder and generate the appropriate instruction. 5712 5713@cindex @code{udivmod@var{m}4} instruction pattern 5714@item @samp{udivmod@var{m}4} 5715Similar, but does unsigned division. 5716 5717@anchor{shift patterns} 5718@cindex @code{ashl@var{m}3} instruction pattern 5719@cindex @code{ssashl@var{m}3} instruction pattern 5720@cindex @code{usashl@var{m}3} instruction pattern 5721@item @samp{ashl@var{m}3}, @samp{ssashl@var{m}3}, @samp{usashl@var{m}3} 5722Arithmetic-shift operand 1 left by a number of bits specified by operand 57232, and store the result in operand 0. Here @var{m} is the mode of 5724operand 0 and operand 1; operand 2's mode is specified by the 5725instruction pattern, and the compiler will convert the operand to that 5726mode before generating the instruction. The shift or rotate expander 5727or instruction pattern should explicitly specify the mode of the operand 2, 5728it should never be @code{VOIDmode}. The meaning of out-of-range shift 5729counts can optionally be specified by @code{TARGET_SHIFT_TRUNCATION_MASK}. 5730@xref{TARGET_SHIFT_TRUNCATION_MASK}. Operand 2 is always a scalar type. 5731 5732@cindex @code{ashr@var{m}3} instruction pattern 5733@cindex @code{lshr@var{m}3} instruction pattern 5734@cindex @code{rotl@var{m}3} instruction pattern 5735@cindex @code{rotr@var{m}3} instruction pattern 5736@item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3} 5737Other shift and rotate instructions, analogous to the 5738@code{ashl@var{m}3} instructions. Operand 2 is always a scalar type. 5739 5740@cindex @code{vashl@var{m}3} instruction pattern 5741@cindex @code{vashr@var{m}3} instruction pattern 5742@cindex @code{vlshr@var{m}3} instruction pattern 5743@cindex @code{vrotl@var{m}3} instruction pattern 5744@cindex @code{vrotr@var{m}3} instruction pattern 5745@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} 5746Vector shift and rotate instructions that take vectors as operand 2 5747instead of a scalar type. 5748 5749@cindex @code{avg@var{m}3_floor} instruction pattern 5750@cindex @code{uavg@var{m}3_floor} instruction pattern 5751@item @samp{avg@var{m}3_floor} 5752@itemx @samp{uavg@var{m}3_floor} 5753Signed and unsigned average instructions. These instructions add 5754operands 1 and 2 without truncation, divide the result by 2, 5755round towards -Inf, and store the result in operand 0. This is 5756equivalent to the C code: 5757@smallexample 5758narrow op0, op1, op2; 5759@dots{} 5760op0 = (narrow) (((wide) op1 + (wide) op2) >> 1); 5761@end smallexample 5762where the sign of @samp{narrow} determines whether this is a signed 5763or unsigned operation. 5764 5765@cindex @code{avg@var{m}3_ceil} instruction pattern 5766@cindex @code{uavg@var{m}3_ceil} instruction pattern 5767@item @samp{avg@var{m}3_ceil} 5768@itemx @samp{uavg@var{m}3_ceil} 5769Like @samp{avg@var{m}3_floor} and @samp{uavg@var{m}3_floor}, but round 5770towards +Inf. This is equivalent to the C code: 5771@smallexample 5772narrow op0, op1, op2; 5773@dots{} 5774op0 = (narrow) (((wide) op1 + (wide) op2 + 1) >> 1); 5775@end smallexample 5776 5777@cindex @code{bswap@var{m}2} instruction pattern 5778@item @samp{bswap@var{m}2} 5779Reverse the order of bytes of operand 1 and store the result in operand 0. 5780 5781@cindex @code{neg@var{m}2} instruction pattern 5782@cindex @code{ssneg@var{m}2} instruction pattern 5783@cindex @code{usneg@var{m}2} instruction pattern 5784@item @samp{neg@var{m}2}, @samp{ssneg@var{m}2}, @samp{usneg@var{m}2} 5785Negate operand 1 and store the result in operand 0. 5786 5787@cindex @code{negv@var{m}3} instruction pattern 5788@item @samp{negv@var{m}3} 5789Like @code{neg@var{m}2} but takes a @code{code_label} as operand 2 and 5790emits code to jump to it if signed overflow occurs during the negation. 5791 5792@cindex @code{abs@var{m}2} instruction pattern 5793@item @samp{abs@var{m}2} 5794Store the absolute value of operand 1 into operand 0. 5795 5796@cindex @code{sqrt@var{m}2} instruction pattern 5797@item @samp{sqrt@var{m}2} 5798Store the square root of operand 1 into operand 0. Both operands have 5799mode @var{m}, which is a scalar or vector floating-point mode. 5800 5801This pattern is not allowed to @code{FAIL}. 5802 5803@cindex @code{rsqrt@var{m}2} instruction pattern 5804@item @samp{rsqrt@var{m}2} 5805Store the reciprocal of the square root of operand 1 into operand 0. 5806Both operands have mode @var{m}, which is a scalar or vector 5807floating-point mode. 5808 5809On most architectures this pattern is only approximate, so either 5810its C condition or the @code{TARGET_OPTAB_SUPPORTED_P} hook should 5811check for the appropriate math flags. (Using the C condition is 5812more direct, but using @code{TARGET_OPTAB_SUPPORTED_P} can be useful 5813if a target-specific built-in also uses the @samp{rsqrt@var{m}2} 5814pattern.) 5815 5816This pattern is not allowed to @code{FAIL}. 5817 5818@cindex @code{fmod@var{m}3} instruction pattern 5819@item @samp{fmod@var{m}3} 5820Store the remainder of dividing operand 1 by operand 2 into 5821operand 0, rounded towards zero to an integer. All operands have 5822mode @var{m}, which is a scalar or vector floating-point mode. 5823 5824This pattern is not allowed to @code{FAIL}. 5825 5826@cindex @code{remainder@var{m}3} instruction pattern 5827@item @samp{remainder@var{m}3} 5828Store the remainder of dividing operand 1 by operand 2 into 5829operand 0, rounded to the nearest integer. All operands have 5830mode @var{m}, which is a scalar or vector floating-point mode. 5831 5832This pattern is not allowed to @code{FAIL}. 5833 5834@cindex @code{scalb@var{m}3} instruction pattern 5835@item @samp{scalb@var{m}3} 5836Raise @code{FLT_RADIX} to the power of operand 2, multiply it by 5837operand 1, and store the result in operand 0. All operands have 5838mode @var{m}, which is a scalar or vector floating-point mode. 5839 5840This pattern is not allowed to @code{FAIL}. 5841 5842@cindex @code{ldexp@var{m}3} instruction pattern 5843@item @samp{ldexp@var{m}3} 5844Raise 2 to the power of operand 2, multiply it by operand 1, and store 5845the result in operand 0. Operands 0 and 1 have mode @var{m}, which is 5846a scalar or vector floating-point mode. Operand 2's mode has 5847the same number of elements as @var{m} and each element is wide 5848enough to store an @code{int}. The integers are signed. 5849 5850This pattern is not allowed to @code{FAIL}. 5851 5852@cindex @code{cos@var{m}2} instruction pattern 5853@item @samp{cos@var{m}2} 5854Store the cosine of operand 1 into operand 0. Both operands have 5855mode @var{m}, which is a scalar or vector floating-point mode. 5856 5857This pattern is not allowed to @code{FAIL}. 5858 5859@cindex @code{sin@var{m}2} instruction pattern 5860@item @samp{sin@var{m}2} 5861Store the sine of operand 1 into operand 0. Both operands have 5862mode @var{m}, which is a scalar or vector floating-point mode. 5863 5864This pattern is not allowed to @code{FAIL}. 5865 5866@cindex @code{sincos@var{m}3} instruction pattern 5867@item @samp{sincos@var{m}3} 5868Store the cosine of operand 2 into operand 0 and the sine of 5869operand 2 into operand 1. All operands have mode @var{m}, 5870which is a scalar or vector floating-point mode. 5871 5872Targets that can calculate the sine and cosine simultaneously can 5873implement this pattern as opposed to implementing individual 5874@code{sin@var{m}2} and @code{cos@var{m}2} patterns. The @code{sin} 5875and @code{cos} built-in functions will then be expanded to the 5876@code{sincos@var{m}3} pattern, with one of the output values 5877left unused. 5878 5879@cindex @code{tan@var{m}2} instruction pattern 5880@item @samp{tan@var{m}2} 5881Store the tangent of operand 1 into operand 0. Both operands have 5882mode @var{m}, which is a scalar or vector floating-point mode. 5883 5884This pattern is not allowed to @code{FAIL}. 5885 5886@cindex @code{asin@var{m}2} instruction pattern 5887@item @samp{asin@var{m}2} 5888Store the arc sine of operand 1 into operand 0. Both operands have 5889mode @var{m}, which is a scalar or vector floating-point mode. 5890 5891This pattern is not allowed to @code{FAIL}. 5892 5893@cindex @code{acos@var{m}2} instruction pattern 5894@item @samp{acos@var{m}2} 5895Store the arc cosine of operand 1 into operand 0. Both operands have 5896mode @var{m}, which is a scalar or vector floating-point mode. 5897 5898This pattern is not allowed to @code{FAIL}. 5899 5900@cindex @code{atan@var{m}2} instruction pattern 5901@item @samp{atan@var{m}2} 5902Store the arc tangent of operand 1 into operand 0. Both operands have 5903mode @var{m}, which is a scalar or vector floating-point mode. 5904 5905This pattern is not allowed to @code{FAIL}. 5906 5907@cindex @code{exp@var{m}2} instruction pattern 5908@item @samp{exp@var{m}2} 5909Raise e (the base of natural logarithms) to the power of operand 1 5910and store the result in operand 0. Both operands have mode @var{m}, 5911which is a scalar or vector floating-point mode. 5912 5913This pattern is not allowed to @code{FAIL}. 5914 5915@cindex @code{expm1@var{m}2} instruction pattern 5916@item @samp{expm1@var{m}2} 5917Raise e (the base of natural logarithms) to the power of operand 1, 5918subtract 1, and store the result in operand 0. Both operands have 5919mode @var{m}, which is a scalar or vector floating-point mode. 5920 5921For inputs close to zero, the pattern is expected to be more 5922accurate than a separate @code{exp@var{m}2} and @code{sub@var{m}3} 5923would be. 5924 5925This pattern is not allowed to @code{FAIL}. 5926 5927@cindex @code{exp10@var{m}2} instruction pattern 5928@item @samp{exp10@var{m}2} 5929Raise 10 to the power of operand 1 and store the result in operand 0. 5930Both operands have mode @var{m}, which is a scalar or vector 5931floating-point mode. 5932 5933This pattern is not allowed to @code{FAIL}. 5934 5935@cindex @code{exp2@var{m}2} instruction pattern 5936@item @samp{exp2@var{m}2} 5937Raise 2 to the power of operand 1 and store the result in operand 0. 5938Both operands have mode @var{m}, which is a scalar or vector 5939floating-point mode. 5940 5941This pattern is not allowed to @code{FAIL}. 5942 5943@cindex @code{log@var{m}2} instruction pattern 5944@item @samp{log@var{m}2} 5945Store the natural logarithm of operand 1 into operand 0. Both operands 5946have mode @var{m}, which is a scalar or vector floating-point mode. 5947 5948This pattern is not allowed to @code{FAIL}. 5949 5950@cindex @code{log1p@var{m}2} instruction pattern 5951@item @samp{log1p@var{m}2} 5952Add 1 to operand 1, compute the natural logarithm, and store 5953the result in operand 0. Both operands have mode @var{m}, which is 5954a scalar or vector floating-point mode. 5955 5956For inputs close to zero, the pattern is expected to be more 5957accurate than a separate @code{add@var{m}3} and @code{log@var{m}2} 5958would be. 5959 5960This pattern is not allowed to @code{FAIL}. 5961 5962@cindex @code{log10@var{m}2} instruction pattern 5963@item @samp{log10@var{m}2} 5964Store the base-10 logarithm of operand 1 into operand 0. Both operands 5965have mode @var{m}, which is a scalar or vector floating-point mode. 5966 5967This pattern is not allowed to @code{FAIL}. 5968 5969@cindex @code{log2@var{m}2} instruction pattern 5970@item @samp{log2@var{m}2} 5971Store the base-2 logarithm of operand 1 into operand 0. Both operands 5972have mode @var{m}, which is a scalar or vector floating-point mode. 5973 5974This pattern is not allowed to @code{FAIL}. 5975 5976@cindex @code{logb@var{m}2} instruction pattern 5977@item @samp{logb@var{m}2} 5978Store the base-@code{FLT_RADIX} logarithm of operand 1 into operand 0. 5979Both operands have mode @var{m}, which is a scalar or vector 5980floating-point mode. 5981 5982This pattern is not allowed to @code{FAIL}. 5983 5984@cindex @code{significand@var{m}2} instruction pattern 5985@item @samp{significand@var{m}2} 5986Store the significand of floating-point operand 1 in operand 0. 5987Both operands have mode @var{m}, which is a scalar or vector 5988floating-point mode. 5989 5990This pattern is not allowed to @code{FAIL}. 5991 5992@cindex @code{pow@var{m}3} instruction pattern 5993@item @samp{pow@var{m}3} 5994Store the value of operand 1 raised to the exponent operand 2 5995into operand 0. All operands have mode @var{m}, which is a scalar 5996or vector floating-point mode. 5997 5998This pattern is not allowed to @code{FAIL}. 5999 6000@cindex @code{atan2@var{m}3} instruction pattern 6001@item @samp{atan2@var{m}3} 6002Store the arc tangent (inverse tangent) of operand 1 divided by 6003operand 2 into operand 0, using the signs of both arguments to 6004determine the quadrant of the result. All operands have mode 6005@var{m}, which is a scalar or vector floating-point mode. 6006 6007This pattern is not allowed to @code{FAIL}. 6008 6009@cindex @code{floor@var{m}2} instruction pattern 6010@item @samp{floor@var{m}2} 6011Store the largest integral value not greater than operand 1 in operand 0. 6012Both operands have mode @var{m}, which is a scalar or vector 6013floating-point mode. If @option{-ffp-int-builtin-inexact} is in 6014effect, the ``inexact'' exception may be raised for noninteger 6015operands; otherwise, it may not. 6016 6017This pattern is not allowed to @code{FAIL}. 6018 6019@cindex @code{btrunc@var{m}2} instruction pattern 6020@item @samp{btrunc@var{m}2} 6021Round operand 1 to an integer, towards zero, and store the result in 6022operand 0. Both operands have mode @var{m}, which is a scalar or 6023vector floating-point mode. If @option{-ffp-int-builtin-inexact} is 6024in effect, the ``inexact'' exception may be raised for noninteger 6025operands; otherwise, it may not. 6026 6027This pattern is not allowed to @code{FAIL}. 6028 6029@cindex @code{round@var{m}2} instruction pattern 6030@item @samp{round@var{m}2} 6031Round operand 1 to the nearest integer, rounding away from zero in the 6032event of a tie, and store the result in operand 0. Both operands have 6033mode @var{m}, which is a scalar or vector floating-point mode. If 6034@option{-ffp-int-builtin-inexact} is in effect, the ``inexact'' 6035exception may be raised for noninteger operands; otherwise, it may 6036not. 6037 6038This pattern is not allowed to @code{FAIL}. 6039 6040@cindex @code{ceil@var{m}2} instruction pattern 6041@item @samp{ceil@var{m}2} 6042Store the smallest integral value not less than operand 1 in operand 0. 6043Both operands have mode @var{m}, which is a scalar or vector 6044floating-point mode. If @option{-ffp-int-builtin-inexact} is in 6045effect, the ``inexact'' exception may be raised for noninteger 6046operands; otherwise, it may not. 6047 6048This pattern is not allowed to @code{FAIL}. 6049 6050@cindex @code{nearbyint@var{m}2} instruction pattern 6051@item @samp{nearbyint@var{m}2} 6052Round operand 1 to an integer, using the current rounding mode, and 6053store the result in operand 0. Do not raise an inexact condition when 6054the result is different from the argument. Both operands have mode 6055@var{m}, which is a scalar or vector floating-point mode. 6056 6057This pattern is not allowed to @code{FAIL}. 6058 6059@cindex @code{rint@var{m}2} instruction pattern 6060@item @samp{rint@var{m}2} 6061Round operand 1 to an integer, using the current rounding mode, and 6062store the result in operand 0. Raise an inexact condition when 6063the result is different from the argument. Both operands have mode 6064@var{m}, which is a scalar or vector floating-point mode. 6065 6066This pattern is not allowed to @code{FAIL}. 6067 6068@cindex @code{lrint@var{m}@var{n}2} 6069@item @samp{lrint@var{m}@var{n}2} 6070Convert operand 1 (valid for floating point mode @var{m}) to fixed 6071point mode @var{n} as a signed number according to the current 6072rounding mode and store in operand 0 (which has mode @var{n}). 6073 6074@cindex @code{lround@var{m}@var{n}2} 6075@item @samp{lround@var{m}@var{n}2} 6076Convert operand 1 (valid for floating point mode @var{m}) to fixed 6077point mode @var{n} as a signed number rounding to nearest and away 6078from zero and store in operand 0 (which has mode @var{n}). 6079 6080@cindex @code{lfloor@var{m}@var{n}2} 6081@item @samp{lfloor@var{m}@var{n}2} 6082Convert operand 1 (valid for floating point mode @var{m}) to fixed 6083point mode @var{n} as a signed number rounding down and store in 6084operand 0 (which has mode @var{n}). 6085 6086@cindex @code{lceil@var{m}@var{n}2} 6087@item @samp{lceil@var{m}@var{n}2} 6088Convert operand 1 (valid for floating point mode @var{m}) to fixed 6089point mode @var{n} as a signed number rounding up and store in 6090operand 0 (which has mode @var{n}). 6091 6092@cindex @code{copysign@var{m}3} instruction pattern 6093@item @samp{copysign@var{m}3} 6094Store a value with the magnitude of operand 1 and the sign of operand 60952 into operand 0. All operands have mode @var{m}, which is a scalar or 6096vector floating-point mode. 6097 6098This pattern is not allowed to @code{FAIL}. 6099 6100@cindex @code{xorsign@var{m}3} instruction pattern 6101@item @samp{xorsign@var{m}3} 6102Equivalent to @samp{op0 = op1 * copysign (1.0, op2)}: store a value with 6103the magnitude of operand 1 and the sign of operand 2 into operand 0. 6104All operands have mode @var{m}, which is a scalar or vector 6105floating-point mode. 6106 6107This pattern is not allowed to @code{FAIL}. 6108 6109@cindex @code{ffs@var{m}2} instruction pattern 6110@item @samp{ffs@var{m}2} 6111Store into operand 0 one plus the index of the least significant 1-bit 6112of operand 1. If operand 1 is zero, store zero. 6113 6114@var{m} is either a scalar or vector integer mode. When it is a scalar, 6115operand 1 has mode @var{m} but operand 0 can have whatever scalar 6116integer mode is suitable for the target. The compiler will insert 6117conversion instructions as necessary (typically to convert the result 6118to the same width as @code{int}). When @var{m} is a vector, both 6119operands must have mode @var{m}. 6120 6121This pattern is not allowed to @code{FAIL}. 6122 6123@cindex @code{clrsb@var{m}2} instruction pattern 6124@item @samp{clrsb@var{m}2} 6125Count leading redundant sign bits. 6126Store into operand 0 the number of redundant sign bits in operand 1, starting 6127at the most significant bit position. 6128A redundant sign bit is defined as any sign bit after the first. As such, 6129this count will be one less than the count of leading sign bits. 6130 6131@var{m} is either a scalar or vector integer mode. When it is a scalar, 6132operand 1 has mode @var{m} but operand 0 can have whatever scalar 6133integer mode is suitable for the target. The compiler will insert 6134conversion instructions as necessary (typically to convert the result 6135to the same width as @code{int}). When @var{m} is a vector, both 6136operands must have mode @var{m}. 6137 6138This pattern is not allowed to @code{FAIL}. 6139 6140@cindex @code{clz@var{m}2} instruction pattern 6141@item @samp{clz@var{m}2} 6142Store into operand 0 the number of leading 0-bits in operand 1, starting 6143at the most significant bit position. If operand 1 is 0, the 6144@code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if 6145the result is undefined or has a useful value. 6146 6147@var{m} is either a scalar or vector integer mode. When it is a scalar, 6148operand 1 has mode @var{m} but operand 0 can have whatever scalar 6149integer mode is suitable for the target. The compiler will insert 6150conversion instructions as necessary (typically to convert the result 6151to the same width as @code{int}). When @var{m} is a vector, both 6152operands must have mode @var{m}. 6153 6154This pattern is not allowed to @code{FAIL}. 6155 6156@cindex @code{ctz@var{m}2} instruction pattern 6157@item @samp{ctz@var{m}2} 6158Store into operand 0 the number of trailing 0-bits in operand 1, starting 6159at the least significant bit position. If operand 1 is 0, the 6160@code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if 6161the result is undefined or has a useful value. 6162 6163@var{m} is either a scalar or vector integer mode. When it is a scalar, 6164operand 1 has mode @var{m} but operand 0 can have whatever scalar 6165integer mode is suitable for the target. The compiler will insert 6166conversion instructions as necessary (typically to convert the result 6167to the same width as @code{int}). When @var{m} is a vector, both 6168operands must have mode @var{m}. 6169 6170This pattern is not allowed to @code{FAIL}. 6171 6172@cindex @code{popcount@var{m}2} instruction pattern 6173@item @samp{popcount@var{m}2} 6174Store into operand 0 the number of 1-bits in operand 1. 6175 6176@var{m} is either a scalar or vector integer mode. When it is a scalar, 6177operand 1 has mode @var{m} but operand 0 can have whatever scalar 6178integer mode is suitable for the target. The compiler will insert 6179conversion instructions as necessary (typically to convert the result 6180to the same width as @code{int}). When @var{m} is a vector, both 6181operands must have mode @var{m}. 6182 6183This pattern is not allowed to @code{FAIL}. 6184 6185@cindex @code{parity@var{m}2} instruction pattern 6186@item @samp{parity@var{m}2} 6187Store into operand 0 the parity of operand 1, i.e.@: the number of 1-bits 6188in operand 1 modulo 2. 6189 6190@var{m} is either a scalar or vector integer mode. When it is a scalar, 6191operand 1 has mode @var{m} but operand 0 can have whatever scalar 6192integer mode is suitable for the target. The compiler will insert 6193conversion instructions as necessary (typically to convert the result 6194to the same width as @code{int}). When @var{m} is a vector, both 6195operands must have mode @var{m}. 6196 6197This pattern is not allowed to @code{FAIL}. 6198 6199@cindex @code{one_cmpl@var{m}2} instruction pattern 6200@item @samp{one_cmpl@var{m}2} 6201Store the bitwise-complement of operand 1 into operand 0. 6202 6203@cindex @code{cpymem@var{m}} instruction pattern 6204@item @samp{cpymem@var{m}} 6205Block copy instruction. The destination and source blocks of memory 6206are the first two operands, and both are @code{mem:BLK}s with an 6207address in mode @code{Pmode}. 6208 6209The number of bytes to copy is the third operand, in mode @var{m}. 6210Usually, you specify @code{Pmode} for @var{m}. However, if you can 6211generate better code knowing the range of valid lengths is smaller than 6212those representable in a full Pmode pointer, you should provide 6213a pattern with a 6214mode corresponding to the range of values you can handle efficiently 6215(e.g., @code{QImode} for values in the range 0--127; note we avoid numbers 6216that appear negative) and also a pattern with @code{Pmode}. 6217 6218The fourth operand is the known shared alignment of the source and 6219destination, in the form of a @code{const_int} rtx. Thus, if the 6220compiler knows that both source and destination are word-aligned, 6221it may provide the value 4 for this operand. 6222 6223Optional operands 5 and 6 specify expected alignment and size of block 6224respectively. The expected alignment differs from alignment in operand 4 6225in a way that the blocks are not required to be aligned according to it in 6226all cases. This expected alignment is also in bytes, just like operand 4. 6227Expected size, when unknown, is set to @code{(const_int -1)}. 6228 6229Descriptions of multiple @code{cpymem@var{m}} patterns can only be 6230beneficial if the patterns for smaller modes have fewer restrictions 6231on their first, second and fourth operands. Note that the mode @var{m} 6232in @code{cpymem@var{m}} does not impose any restriction on the mode of 6233individually copied data units in the block. 6234 6235The @code{cpymem@var{m}} patterns need not give special consideration 6236to the possibility that the source and destination strings might 6237overlap. These patterns are used to do inline expansion of 6238@code{__builtin_memcpy}. 6239 6240@cindex @code{movmem@var{m}} instruction pattern 6241@item @samp{movmem@var{m}} 6242Block move instruction. The destination and source blocks of memory 6243are the first two operands, and both are @code{mem:BLK}s with an 6244address in mode @code{Pmode}. 6245 6246The number of bytes to copy is the third operand, in mode @var{m}. 6247Usually, you specify @code{Pmode} for @var{m}. However, if you can 6248generate better code knowing the range of valid lengths is smaller than 6249those representable in a full Pmode pointer, you should provide 6250a pattern with a 6251mode corresponding to the range of values you can handle efficiently 6252(e.g., @code{QImode} for values in the range 0--127; note we avoid numbers 6253that appear negative) and also a pattern with @code{Pmode}. 6254 6255The fourth operand is the known shared alignment of the source and 6256destination, in the form of a @code{const_int} rtx. Thus, if the 6257compiler knows that both source and destination are word-aligned, 6258it may provide the value 4 for this operand. 6259 6260Optional operands 5 and 6 specify expected alignment and size of block 6261respectively. The expected alignment differs from alignment in operand 4 6262in a way that the blocks are not required to be aligned according to it in 6263all cases. This expected alignment is also in bytes, just like operand 4. 6264Expected size, when unknown, is set to @code{(const_int -1)}. 6265 6266Descriptions of multiple @code{movmem@var{m}} patterns can only be 6267beneficial if the patterns for smaller modes have fewer restrictions 6268on their first, second and fourth operands. Note that the mode @var{m} 6269in @code{movmem@var{m}} does not impose any restriction on the mode of 6270individually copied data units in the block. 6271 6272The @code{movmem@var{m}} patterns must correctly handle the case where 6273the source and destination strings overlap. These patterns are used to 6274do inline expansion of @code{__builtin_memmove}. 6275 6276@cindex @code{movstr} instruction pattern 6277@item @samp{movstr} 6278String copy instruction, with @code{stpcpy} semantics. Operand 0 is 6279an output operand in mode @code{Pmode}. The addresses of the 6280destination and source strings are operands 1 and 2, and both are 6281@code{mem:BLK}s with addresses in mode @code{Pmode}. The execution of 6282the expansion of this pattern should store in operand 0 the address in 6283which the @code{NUL} terminator was stored in the destination string. 6284 6285This pattern has also several optional operands that are same as in 6286@code{setmem}. 6287 6288@cindex @code{setmem@var{m}} instruction pattern 6289@item @samp{setmem@var{m}} 6290Block set instruction. The destination string is the first operand, 6291given as a @code{mem:BLK} whose address is in mode @code{Pmode}. The 6292number of bytes to set is the second operand, in mode @var{m}. The value to 6293initialize the memory with is the third operand. Targets that only support the 6294clearing of memory should reject any value that is not the constant 0. See 6295@samp{cpymem@var{m}} for a discussion of the choice of mode. 6296 6297The fourth operand is the known alignment of the destination, in the form 6298of a @code{const_int} rtx. Thus, if the compiler knows that the 6299destination is word-aligned, it may provide the value 4 for this 6300operand. 6301 6302Optional operands 5 and 6 specify expected alignment and size of block 6303respectively. The expected alignment differs from alignment in operand 4 6304in a way that the blocks are not required to be aligned according to it in 6305all cases. This expected alignment is also in bytes, just like operand 4. 6306Expected size, when unknown, is set to @code{(const_int -1)}. 6307Operand 7 is the minimal size of the block and operand 8 is the 6308maximal size of the block (NULL if it cannot be represented as CONST_INT). 6309Operand 9 is the probable maximal size (i.e.@: we cannot rely on it for 6310correctness, but it can be used for choosing proper code sequence for a 6311given size). 6312 6313The use for multiple @code{setmem@var{m}} is as for @code{cpymem@var{m}}. 6314 6315@cindex @code{cmpstrn@var{m}} instruction pattern 6316@item @samp{cmpstrn@var{m}} 6317String compare instruction, with five operands. Operand 0 is the output; 6318it has mode @var{m}. The remaining four operands are like the operands 6319of @samp{cpymem@var{m}}. The two memory blocks specified are compared 6320byte by byte in lexicographic order starting at the beginning of each 6321string. The instruction is not allowed to prefetch more than one byte 6322at a time since either string may end in the first byte and reading past 6323that may access an invalid page or segment and cause a fault. The 6324comparison terminates early if the fetched bytes are different or if 6325they are equal to zero. The effect of the instruction is to store a 6326value in operand 0 whose sign indicates the result of the comparison. 6327 6328@cindex @code{cmpstr@var{m}} instruction pattern 6329@item @samp{cmpstr@var{m}} 6330String compare instruction, without known maximum length. Operand 0 is the 6331output; it has mode @var{m}. The second and third operand are the blocks of 6332memory to be compared; both are @code{mem:BLK} with an address in mode 6333@code{Pmode}. 6334 6335The fourth operand is the known shared alignment of the source and 6336destination, in the form of a @code{const_int} rtx. Thus, if the 6337compiler knows that both source and destination are word-aligned, 6338it may provide the value 4 for this operand. 6339 6340The two memory blocks specified are compared byte by byte in lexicographic 6341order starting at the beginning of each string. The instruction is not allowed 6342to prefetch more than one byte at a time since either string may end in the 6343first byte and reading past that may access an invalid page or segment and 6344cause a fault. The comparison will terminate when the fetched bytes 6345are different or if they are equal to zero. The effect of the 6346instruction is to store a value in operand 0 whose sign indicates the 6347result of the comparison. 6348 6349@cindex @code{cmpmem@var{m}} instruction pattern 6350@item @samp{cmpmem@var{m}} 6351Block compare instruction, with five operands like the operands 6352of @samp{cmpstr@var{m}}. The two memory blocks specified are compared 6353byte by byte in lexicographic order starting at the beginning of each 6354block. Unlike @samp{cmpstr@var{m}} the instruction can prefetch 6355any bytes in the two memory blocks. Also unlike @samp{cmpstr@var{m}} 6356the comparison will not stop if both bytes are zero. The effect of 6357the instruction is to store a value in operand 0 whose sign indicates 6358the result of the comparison. 6359 6360@cindex @code{strlen@var{m}} instruction pattern 6361@item @samp{strlen@var{m}} 6362Compute the length of a string, with three operands. 6363Operand 0 is the result (of mode @var{m}), operand 1 is 6364a @code{mem} referring to the first character of the string, 6365operand 2 is the character to search for (normally zero), 6366and operand 3 is a constant describing the known alignment 6367of the beginning of the string. 6368 6369@cindex @code{float@var{m}@var{n}2} instruction pattern 6370@item @samp{float@var{m}@var{n}2} 6371Convert signed integer operand 1 (valid for fixed point mode @var{m}) to 6372floating point mode @var{n} and store in operand 0 (which has mode 6373@var{n}). 6374 6375@cindex @code{floatuns@var{m}@var{n}2} instruction pattern 6376@item @samp{floatuns@var{m}@var{n}2} 6377Convert unsigned integer operand 1 (valid for fixed point mode @var{m}) 6378to floating point mode @var{n} and store in operand 0 (which has mode 6379@var{n}). 6380 6381@cindex @code{fix@var{m}@var{n}2} instruction pattern 6382@item @samp{fix@var{m}@var{n}2} 6383Convert operand 1 (valid for floating point mode @var{m}) to fixed 6384point mode @var{n} as a signed number and store in operand 0 (which 6385has mode @var{n}). This instruction's result is defined only when 6386the value of operand 1 is an integer. 6387 6388If the machine description defines this pattern, it also needs to 6389define the @code{ftrunc} pattern. 6390 6391@cindex @code{fixuns@var{m}@var{n}2} instruction pattern 6392@item @samp{fixuns@var{m}@var{n}2} 6393Convert operand 1 (valid for floating point mode @var{m}) to fixed 6394point mode @var{n} as an unsigned number and store in operand 0 (which 6395has mode @var{n}). This instruction's result is defined only when the 6396value of operand 1 is an integer. 6397 6398@cindex @code{ftrunc@var{m}2} instruction pattern 6399@item @samp{ftrunc@var{m}2} 6400Convert operand 1 (valid for floating point mode @var{m}) to an 6401integer value, still represented in floating point mode @var{m}, and 6402store it in operand 0 (valid for floating point mode @var{m}). 6403 6404@cindex @code{fix_trunc@var{m}@var{n}2} instruction pattern 6405@item @samp{fix_trunc@var{m}@var{n}2} 6406Like @samp{fix@var{m}@var{n}2} but works for any floating point value 6407of mode @var{m} by converting the value to an integer. 6408 6409@cindex @code{fixuns_trunc@var{m}@var{n}2} instruction pattern 6410@item @samp{fixuns_trunc@var{m}@var{n}2} 6411Like @samp{fixuns@var{m}@var{n}2} but works for any floating point 6412value of mode @var{m} by converting the value to an integer. 6413 6414@cindex @code{trunc@var{m}@var{n}2} instruction pattern 6415@item @samp{trunc@var{m}@var{n}2} 6416Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and 6417store in operand 0 (which has mode @var{n}). Both modes must be fixed 6418point or both floating point. 6419 6420@cindex @code{extend@var{m}@var{n}2} instruction pattern 6421@item @samp{extend@var{m}@var{n}2} 6422Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and 6423store in operand 0 (which has mode @var{n}). Both modes must be fixed 6424point or both floating point. 6425 6426@cindex @code{zero_extend@var{m}@var{n}2} instruction pattern 6427@item @samp{zero_extend@var{m}@var{n}2} 6428Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and 6429store in operand 0 (which has mode @var{n}). Both modes must be fixed 6430point. 6431 6432@cindex @code{fract@var{m}@var{n}2} instruction pattern 6433@item @samp{fract@var{m}@var{n}2} 6434Convert operand 1 of mode @var{m} to mode @var{n} and store in 6435operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} 6436could be fixed-point to fixed-point, signed integer to fixed-point, 6437fixed-point to signed integer, floating-point to fixed-point, 6438or fixed-point to floating-point. 6439When overflows or underflows happen, the results are undefined. 6440 6441@cindex @code{satfract@var{m}@var{n}2} instruction pattern 6442@item @samp{satfract@var{m}@var{n}2} 6443Convert operand 1 of mode @var{m} to mode @var{n} and store in 6444operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} 6445could be fixed-point to fixed-point, signed integer to fixed-point, 6446or floating-point to fixed-point. 6447When overflows or underflows happen, the instruction saturates the 6448results to the maximum or the minimum. 6449 6450@cindex @code{fractuns@var{m}@var{n}2} instruction pattern 6451@item @samp{fractuns@var{m}@var{n}2} 6452Convert operand 1 of mode @var{m} to mode @var{n} and store in 6453operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} 6454could be unsigned integer to fixed-point, or 6455fixed-point to unsigned integer. 6456When overflows or underflows happen, the results are undefined. 6457 6458@cindex @code{satfractuns@var{m}@var{n}2} instruction pattern 6459@item @samp{satfractuns@var{m}@var{n}2} 6460Convert unsigned integer operand 1 of mode @var{m} to fixed-point mode 6461@var{n} and store in operand 0 (which has mode @var{n}). 6462When overflows or underflows happen, the instruction saturates the 6463results to the maximum or the minimum. 6464 6465@cindex @code{extv@var{m}} instruction pattern 6466@item @samp{extv@var{m}} 6467Extract a bit-field from register operand 1, sign-extend it, and store 6468it in operand 0. Operand 2 specifies the width of the field in bits 6469and operand 3 the starting bit, which counts from the most significant 6470bit if @samp{BITS_BIG_ENDIAN} is true and from the least significant bit 6471otherwise. 6472 6473Operands 0 and 1 both have mode @var{m}. Operands 2 and 3 have a 6474target-specific mode. 6475 6476@cindex @code{extvmisalign@var{m}} instruction pattern 6477@item @samp{extvmisalign@var{m}} 6478Extract a bit-field from memory operand 1, sign extend it, and store 6479it in operand 0. Operand 2 specifies the width in bits and operand 3 6480the starting bit. The starting bit is always somewhere in the first byte of 6481operand 1; it counts from the most significant bit if @samp{BITS_BIG_ENDIAN} 6482is true and from the least significant bit otherwise. 6483 6484Operand 0 has mode @var{m} while operand 1 has @code{BLK} mode. 6485Operands 2 and 3 have a target-specific mode. 6486 6487The instruction must not read beyond the last byte of the bit-field. 6488 6489@cindex @code{extzv@var{m}} instruction pattern 6490@item @samp{extzv@var{m}} 6491Like @samp{extv@var{m}} except that the bit-field value is zero-extended. 6492 6493@cindex @code{extzvmisalign@var{m}} instruction pattern 6494@item @samp{extzvmisalign@var{m}} 6495Like @samp{extvmisalign@var{m}} except that the bit-field value is 6496zero-extended. 6497 6498@cindex @code{insv@var{m}} instruction pattern 6499@item @samp{insv@var{m}} 6500Insert operand 3 into a bit-field of register operand 0. Operand 1 6501specifies the width of the field in bits and operand 2 the starting bit, 6502which counts from the most significant bit if @samp{BITS_BIG_ENDIAN} 6503is true and from the least significant bit otherwise. 6504 6505Operands 0 and 3 both have mode @var{m}. Operands 1 and 2 have a 6506target-specific mode. 6507 6508@cindex @code{insvmisalign@var{m}} instruction pattern 6509@item @samp{insvmisalign@var{m}} 6510Insert operand 3 into a bit-field of memory operand 0. Operand 1 6511specifies the width of the field in bits and operand 2 the starting bit. 6512The starting bit is always somewhere in the first byte of operand 0; 6513it counts from the most significant bit if @samp{BITS_BIG_ENDIAN} 6514is true and from the least significant bit otherwise. 6515 6516Operand 3 has mode @var{m} while operand 0 has @code{BLK} mode. 6517Operands 1 and 2 have a target-specific mode. 6518 6519The instruction must not read or write beyond the last byte of the bit-field. 6520 6521@cindex @code{extv} instruction pattern 6522@item @samp{extv} 6523Extract a bit-field from operand 1 (a register or memory operand), where 6524operand 2 specifies the width in bits and operand 3 the starting bit, 6525and store it in operand 0. Operand 0 must have mode @code{word_mode}. 6526Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often 6527@code{word_mode} is allowed only for registers. Operands 2 and 3 must 6528be valid for @code{word_mode}. 6529 6530The RTL generation pass generates this instruction only with constants 6531for operands 2 and 3 and the constant is never zero for operand 2. 6532 6533The bit-field value is sign-extended to a full word integer 6534before it is stored in operand 0. 6535 6536This pattern is deprecated; please use @samp{extv@var{m}} and 6537@code{extvmisalign@var{m}} instead. 6538 6539@cindex @code{extzv} instruction pattern 6540@item @samp{extzv} 6541Like @samp{extv} except that the bit-field value is zero-extended. 6542 6543This pattern is deprecated; please use @samp{extzv@var{m}} and 6544@code{extzvmisalign@var{m}} instead. 6545 6546@cindex @code{insv} instruction pattern 6547@item @samp{insv} 6548Store operand 3 (which must be valid for @code{word_mode}) into a 6549bit-field in operand 0, where operand 1 specifies the width in bits and 6550operand 2 the starting bit. Operand 0 may have mode @code{byte_mode} or 6551@code{word_mode}; often @code{word_mode} is allowed only for registers. 6552Operands 1 and 2 must be valid for @code{word_mode}. 6553 6554The RTL generation pass generates this instruction only with constants 6555for operands 1 and 2 and the constant is never zero for operand 1. 6556 6557This pattern is deprecated; please use @samp{insv@var{m}} and 6558@code{insvmisalign@var{m}} instead. 6559 6560@cindex @code{mov@var{mode}cc} instruction pattern 6561@item @samp{mov@var{mode}cc} 6562Conditionally move operand 2 or operand 3 into operand 0 according to the 6563comparison in operand 1. If the comparison is true, operand 2 is moved 6564into operand 0, otherwise operand 3 is moved. 6565 6566The mode of the operands being compared need not be the same as the operands 6567being moved. Some machines, sparc64 for example, have instructions that 6568conditionally move an integer value based on the floating point condition 6569codes and vice versa. 6570 6571If the machine does not have conditional move instructions, do not 6572define these patterns. 6573 6574@cindex @code{add@var{mode}cc} instruction pattern 6575@item @samp{add@var{mode}cc} 6576Similar to @samp{mov@var{mode}cc} but for conditional addition. Conditionally 6577move operand 2 or (operands 2 + operand 3) into operand 0 according to the 6578comparison in operand 1. If the comparison is false, operand 2 is moved into 6579operand 0, otherwise (operand 2 + operand 3) is moved. 6580 6581@cindex @code{cond_add@var{mode}} instruction pattern 6582@cindex @code{cond_sub@var{mode}} instruction pattern 6583@cindex @code{cond_mul@var{mode}} instruction pattern 6584@cindex @code{cond_div@var{mode}} instruction pattern 6585@cindex @code{cond_udiv@var{mode}} instruction pattern 6586@cindex @code{cond_mod@var{mode}} instruction pattern 6587@cindex @code{cond_umod@var{mode}} instruction pattern 6588@cindex @code{cond_and@var{mode}} instruction pattern 6589@cindex @code{cond_ior@var{mode}} instruction pattern 6590@cindex @code{cond_xor@var{mode}} instruction pattern 6591@cindex @code{cond_smin@var{mode}} instruction pattern 6592@cindex @code{cond_smax@var{mode}} instruction pattern 6593@cindex @code{cond_umin@var{mode}} instruction pattern 6594@cindex @code{cond_umax@var{mode}} instruction pattern 6595@item @samp{cond_add@var{mode}} 6596@itemx @samp{cond_sub@var{mode}} 6597@itemx @samp{cond_mul@var{mode}} 6598@itemx @samp{cond_div@var{mode}} 6599@itemx @samp{cond_udiv@var{mode}} 6600@itemx @samp{cond_mod@var{mode}} 6601@itemx @samp{cond_umod@var{mode}} 6602@itemx @samp{cond_and@var{mode}} 6603@itemx @samp{cond_ior@var{mode}} 6604@itemx @samp{cond_xor@var{mode}} 6605@itemx @samp{cond_smin@var{mode}} 6606@itemx @samp{cond_smax@var{mode}} 6607@itemx @samp{cond_umin@var{mode}} 6608@itemx @samp{cond_umax@var{mode}} 6609When operand 1 is true, perform an operation on operands 2 and 3 and 6610store the result in operand 0, otherwise store operand 4 in operand 0. 6611The operation works elementwise if the operands are vectors. 6612 6613The scalar case is equivalent to: 6614 6615@smallexample 6616op0 = op1 ? op2 @var{op} op3 : op4; 6617@end smallexample 6618 6619while the vector case is equivalent to: 6620 6621@smallexample 6622for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++) 6623 op0[i] = op1[i] ? op2[i] @var{op} op3[i] : op4[i]; 6624@end smallexample 6625 6626where, for example, @var{op} is @code{+} for @samp{cond_add@var{mode}}. 6627 6628When defined for floating-point modes, the contents of @samp{op3[i]} 6629are not interpreted if @samp{op1[i]} is false, just like they would not 6630be in a normal C @samp{?:} condition. 6631 6632Operands 0, 2, 3 and 4 all have mode @var{m}. Operand 1 is a scalar 6633integer if @var{m} is scalar, otherwise it has the mode returned by 6634@code{TARGET_VECTORIZE_GET_MASK_MODE}. 6635 6636@cindex @code{cond_fma@var{mode}} instruction pattern 6637@cindex @code{cond_fms@var{mode}} instruction pattern 6638@cindex @code{cond_fnma@var{mode}} instruction pattern 6639@cindex @code{cond_fnms@var{mode}} instruction pattern 6640@item @samp{cond_fma@var{mode}} 6641@itemx @samp{cond_fms@var{mode}} 6642@itemx @samp{cond_fnma@var{mode}} 6643@itemx @samp{cond_fnms@var{mode}} 6644Like @samp{cond_add@var{m}}, except that the conditional operation 6645takes 3 operands rather than two. For example, the vector form of 6646@samp{cond_fma@var{mode}} is equivalent to: 6647 6648@smallexample 6649for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++) 6650 op0[i] = op1[i] ? fma (op2[i], op3[i], op4[i]) : op5[i]; 6651@end smallexample 6652 6653@cindex @code{neg@var{mode}cc} instruction pattern 6654@item @samp{neg@var{mode}cc} 6655Similar to @samp{mov@var{mode}cc} but for conditional negation. Conditionally 6656move the negation of operand 2 or the unchanged operand 3 into operand 0 6657according to the comparison in operand 1. If the comparison is true, the negation 6658of operand 2 is moved into operand 0, otherwise operand 3 is moved. 6659 6660@cindex @code{not@var{mode}cc} instruction pattern 6661@item @samp{not@var{mode}cc} 6662Similar to @samp{neg@var{mode}cc} but for conditional complement. 6663Conditionally move the bitwise complement of operand 2 or the unchanged 6664operand 3 into operand 0 according to the comparison in operand 1. 6665If the comparison is true, the complement of operand 2 is moved into 6666operand 0, otherwise operand 3 is moved. 6667 6668@cindex @code{cstore@var{mode}4} instruction pattern 6669@item @samp{cstore@var{mode}4} 6670Store zero or nonzero in operand 0 according to whether a comparison 6671is true. Operand 1 is a comparison operator. Operand 2 and operand 3 6672are the first and second operand of the comparison, respectively. 6673You specify the mode that operand 0 must have when you write the 6674@code{match_operand} expression. The compiler automatically sees which 6675mode you have used and supplies an operand of that mode. 6676 6677The value stored for a true condition must have 1 as its low bit, or 6678else must be negative. Otherwise the instruction is not suitable and 6679you should omit it from the machine description. You describe to the 6680compiler exactly which value is stored by defining the macro 6681@code{STORE_FLAG_VALUE} (@pxref{Misc}). If a description cannot be 6682found that can be used for all the possible comparison operators, you 6683should pick one and use a @code{define_expand} to map all results 6684onto the one you chose. 6685 6686These operations may @code{FAIL}, but should do so only in relatively 6687uncommon cases; if they would @code{FAIL} for common cases involving 6688integer comparisons, it is best to restrict the predicates to not 6689allow these operands. Likewise if a given comparison operator will 6690always fail, independent of the operands (for floating-point modes, the 6691@code{ordered_comparison_operator} predicate is often useful in this case). 6692 6693If this pattern is omitted, the compiler will generate a conditional 6694branch---for example, it may copy a constant one to the target and branching 6695around an assignment of zero to the target---or a libcall. If the predicate 6696for operand 1 only rejects some operators, it will also try reordering the 6697operands and/or inverting the result value (e.g.@: by an exclusive OR). 6698These possibilities could be cheaper or equivalent to the instructions 6699used for the @samp{cstore@var{mode}4} pattern followed by those required 6700to convert a positive result from @code{STORE_FLAG_VALUE} to 1; in this 6701case, you can and should make operand 1's predicate reject some operators 6702in the @samp{cstore@var{mode}4} pattern, or remove the pattern altogether 6703from the machine description. 6704 6705@cindex @code{cbranch@var{mode}4} instruction pattern 6706@item @samp{cbranch@var{mode}4} 6707Conditional branch instruction combined with a compare instruction. 6708Operand 0 is a comparison operator. Operand 1 and operand 2 are the 6709first and second operands of the comparison, respectively. Operand 3 6710is the @code{code_label} to jump to. 6711 6712@cindex @code{jump} instruction pattern 6713@item @samp{jump} 6714A jump inside a function; an unconditional branch. Operand 0 is the 6715@code{code_label} to jump to. This pattern name is mandatory on all 6716machines. 6717 6718@cindex @code{call} instruction pattern 6719@item @samp{call} 6720Subroutine call instruction returning no value. Operand 0 is the 6721function to call; operand 1 is the number of bytes of arguments pushed 6722as a @code{const_int}; operand 2 is the number of registers used as 6723operands. 6724 6725On most machines, operand 2 is not actually stored into the RTL 6726pattern. It is supplied for the sake of some RISC machines which need 6727to put this information into the assembler code; they can put it in 6728the RTL instead of operand 1. 6729 6730Operand 0 should be a @code{mem} RTX whose address is the address of the 6731function. Note, however, that this address can be a @code{symbol_ref} 6732expression even if it would not be a legitimate memory address on the 6733target machine. If it is also not a valid argument for a call 6734instruction, the pattern for this operation should be a 6735@code{define_expand} (@pxref{Expander Definitions}) that places the 6736address into a register and uses that register in the call instruction. 6737 6738@cindex @code{call_value} instruction pattern 6739@item @samp{call_value} 6740Subroutine call instruction returning a value. Operand 0 is the hard 6741register in which the value is returned. There are three more 6742operands, the same as the three operands of the @samp{call} 6743instruction (but with numbers increased by one). 6744 6745Subroutines that return @code{BLKmode} objects use the @samp{call} 6746insn. 6747 6748@cindex @code{call_pop} instruction pattern 6749@cindex @code{call_value_pop} instruction pattern 6750@item @samp{call_pop}, @samp{call_value_pop} 6751Similar to @samp{call} and @samp{call_value}, except used if defined and 6752if @code{RETURN_POPS_ARGS} is nonzero. They should emit a @code{parallel} 6753that contains both the function call and a @code{set} to indicate the 6754adjustment made to the frame pointer. 6755 6756For machines where @code{RETURN_POPS_ARGS} can be nonzero, the use of these 6757patterns increases the number of functions for which the frame pointer 6758can be eliminated, if desired. 6759 6760@cindex @code{untyped_call} instruction pattern 6761@item @samp{untyped_call} 6762Subroutine call instruction returning a value of any type. Operand 0 is 6763the function to call; operand 1 is a memory location where the result of 6764calling the function is to be stored; operand 2 is a @code{parallel} 6765expression where each element is a @code{set} expression that indicates 6766the saving of a function return value into the result block. 6767 6768This instruction pattern should be defined to support 6769@code{__builtin_apply} on machines where special instructions are needed 6770to call a subroutine with arbitrary arguments or to save the value 6771returned. This instruction pattern is required on machines that have 6772multiple registers that can hold a return value 6773(i.e.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register). 6774 6775@cindex @code{return} instruction pattern 6776@item @samp{return} 6777Subroutine return instruction. This instruction pattern name should be 6778defined only if a single instruction can do all the work of returning 6779from a function. 6780 6781Like the @samp{mov@var{m}} patterns, this pattern is also used after the 6782RTL generation phase. In this case it is to support machines where 6783multiple instructions are usually needed to return from a function, but 6784some class of functions only requires one instruction to implement a 6785return. Normally, the applicable functions are those which do not need 6786to save any registers or allocate stack space. 6787 6788It is valid for this pattern to expand to an instruction using 6789@code{simple_return} if no epilogue is required. 6790 6791@cindex @code{simple_return} instruction pattern 6792@item @samp{simple_return} 6793Subroutine return instruction. This instruction pattern name should be 6794defined only if a single instruction can do all the work of returning 6795from a function on a path where no epilogue is required. This pattern 6796is very similar to the @code{return} instruction pattern, but it is emitted 6797only by the shrink-wrapping optimization on paths where the function 6798prologue has not been executed, and a function return should occur without 6799any of the effects of the epilogue. Additional uses may be introduced on 6800paths where both the prologue and the epilogue have executed. 6801 6802@findex reload_completed 6803@findex leaf_function_p 6804For such machines, the condition specified in this pattern should only 6805be true when @code{reload_completed} is nonzero and the function's 6806epilogue would only be a single instruction. For machines with register 6807windows, the routine @code{leaf_function_p} may be used to determine if 6808a register window push is required. 6809 6810Machines that have conditional return instructions should define patterns 6811such as 6812 6813@smallexample 6814(define_insn "" 6815 [(set (pc) 6816 (if_then_else (match_operator 6817 0 "comparison_operator" 6818 [(cc0) (const_int 0)]) 6819 (return) 6820 (pc)))] 6821 "@var{condition}" 6822 "@dots{}") 6823@end smallexample 6824 6825where @var{condition} would normally be the same condition specified on the 6826named @samp{return} pattern. 6827 6828@cindex @code{untyped_return} instruction pattern 6829@item @samp{untyped_return} 6830Untyped subroutine return instruction. This instruction pattern should 6831be defined to support @code{__builtin_return} on machines where special 6832instructions are needed to return a value of any type. 6833 6834Operand 0 is a memory location where the result of calling a function 6835with @code{__builtin_apply} is stored; operand 1 is a @code{parallel} 6836expression where each element is a @code{set} expression that indicates 6837the restoring of a function return value from the result block. 6838 6839@cindex @code{nop} instruction pattern 6840@item @samp{nop} 6841No-op instruction. This instruction pattern name should always be defined 6842to output a no-op in assembler code. @code{(const_int 0)} will do as an 6843RTL pattern. 6844 6845@cindex @code{indirect_jump} instruction pattern 6846@item @samp{indirect_jump} 6847An instruction to jump to an address which is operand zero. 6848This pattern name is mandatory on all machines. 6849 6850@cindex @code{casesi} instruction pattern 6851@item @samp{casesi} 6852Instruction to jump through a dispatch table, including bounds checking. 6853This instruction takes five operands: 6854 6855@enumerate 6856@item 6857The index to dispatch on, which has mode @code{SImode}. 6858 6859@item 6860The lower bound for indices in the table, an integer constant. 6861 6862@item 6863The total range of indices in the table---the largest index 6864minus the smallest one (both inclusive). 6865 6866@item 6867A label that precedes the table itself. 6868 6869@item 6870A label to jump to if the index has a value outside the bounds. 6871@end enumerate 6872 6873The table is an @code{addr_vec} or @code{addr_diff_vec} inside of a 6874@code{jump_table_data}. The number of elements in the table is one plus the 6875difference between the upper bound and the lower bound. 6876 6877@cindex @code{tablejump} instruction pattern 6878@item @samp{tablejump} 6879Instruction to jump to a variable address. This is a low-level 6880capability which can be used to implement a dispatch table when there 6881is no @samp{casesi} pattern. 6882 6883This pattern requires two operands: the address or offset, and a label 6884which should immediately precede the jump table. If the macro 6885@code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first 6886operand is an offset which counts from the address of the table; otherwise, 6887it is an absolute address to jump to. In either case, the first operand has 6888mode @code{Pmode}. 6889 6890The @samp{tablejump} insn is always the last insn before the jump 6891table it uses. Its assembler code normally has no need to use the 6892second operand, but you should incorporate it in the RTL pattern so 6893that the jump optimizer will not delete the table as unreachable code. 6894 6895 6896@cindex @code{doloop_end} instruction pattern 6897@item @samp{doloop_end} 6898Conditional branch instruction that decrements a register and 6899jumps if the register is nonzero. Operand 0 is the register to 6900decrement and test; operand 1 is the label to jump to if the 6901register is nonzero. 6902@xref{Looping Patterns}. 6903 6904This optional instruction pattern should be defined for machines with 6905low-overhead looping instructions as the loop optimizer will try to 6906modify suitable loops to utilize it. The target hook 6907@code{TARGET_CAN_USE_DOLOOP_P} controls the conditions under which 6908low-overhead loops can be used. 6909 6910@cindex @code{doloop_begin} instruction pattern 6911@item @samp{doloop_begin} 6912Companion instruction to @code{doloop_end} required for machines that 6913need to perform some initialization, such as loading a special counter 6914register. Operand 1 is the associated @code{doloop_end} pattern and 6915operand 0 is the register that it decrements. 6916 6917If initialization insns do not always need to be emitted, use a 6918@code{define_expand} (@pxref{Expander Definitions}) and make it fail. 6919 6920@cindex @code{canonicalize_funcptr_for_compare} instruction pattern 6921@item @samp{canonicalize_funcptr_for_compare} 6922Canonicalize the function pointer in operand 1 and store the result 6923into operand 0. 6924 6925Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1 6926may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc 6927and also has mode @code{Pmode}. 6928 6929Canonicalization of a function pointer usually involves computing 6930the address of the function which would be called if the function 6931pointer were used in an indirect call. 6932 6933Only define this pattern if function pointers on the target machine 6934can have different values but still call the same function when 6935used in an indirect call. 6936 6937@cindex @code{save_stack_block} instruction pattern 6938@cindex @code{save_stack_function} instruction pattern 6939@cindex @code{save_stack_nonlocal} instruction pattern 6940@cindex @code{restore_stack_block} instruction pattern 6941@cindex @code{restore_stack_function} instruction pattern 6942@cindex @code{restore_stack_nonlocal} instruction pattern 6943@item @samp{save_stack_block} 6944@itemx @samp{save_stack_function} 6945@itemx @samp{save_stack_nonlocal} 6946@itemx @samp{restore_stack_block} 6947@itemx @samp{restore_stack_function} 6948@itemx @samp{restore_stack_nonlocal} 6949Most machines save and restore the stack pointer by copying it to or 6950from an object of mode @code{Pmode}. Do not define these patterns on 6951such machines. 6952 6953Some machines require special handling for stack pointer saves and 6954restores. On those machines, define the patterns corresponding to the 6955non-standard cases by using a @code{define_expand} (@pxref{Expander 6956Definitions}) that produces the required insns. The three types of 6957saves and restores are: 6958 6959@enumerate 6960@item 6961@samp{save_stack_block} saves the stack pointer at the start of a block 6962that allocates a variable-sized object, and @samp{restore_stack_block} 6963restores the stack pointer when the block is exited. 6964 6965@item 6966@samp{save_stack_function} and @samp{restore_stack_function} do a 6967similar job for the outermost block of a function and are used when the 6968function allocates variable-sized objects or calls @code{alloca}. Only 6969the epilogue uses the restored stack pointer, allowing a simpler save or 6970restore sequence on some machines. 6971 6972@item 6973@samp{save_stack_nonlocal} is used in functions that contain labels 6974branched to by nested functions. It saves the stack pointer in such a 6975way that the inner function can use @samp{restore_stack_nonlocal} to 6976restore the stack pointer. The compiler generates code to restore the 6977frame and argument pointer registers, but some machines require saving 6978and restoring additional data such as register window information or 6979stack backchains. Place insns in these patterns to save and restore any 6980such required data. 6981@end enumerate 6982 6983When saving the stack pointer, operand 0 is the save area and operand 1 6984is the stack pointer. The mode used to allocate the save area defaults 6985to @code{Pmode} but you can override that choice by defining the 6986@code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}). You must 6987specify an integral mode, or @code{VOIDmode} if no save area is needed 6988for a particular type of save (either because no save is needed or 6989because a machine-specific save area can be used). Operand 0 is the 6990stack pointer and operand 1 is the save area for restore operations. If 6991@samp{save_stack_block} is defined, operand 0 must not be 6992@code{VOIDmode} since these saves can be arbitrarily nested. 6993 6994A save area is a @code{mem} that is at a constant offset from 6995@code{virtual_stack_vars_rtx} when the stack pointer is saved for use by 6996nonlocal gotos and a @code{reg} in the other two cases. 6997 6998@cindex @code{allocate_stack} instruction pattern 6999@item @samp{allocate_stack} 7000Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from 7001the stack pointer to create space for dynamically allocated data. 7002 7003Store the resultant pointer to this space into operand 0. If you 7004are allocating space from the main stack, do this by emitting a 7005move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0. 7006If you are allocating the space elsewhere, generate code to copy the 7007location of the space to operand 0. In the latter case, you must 7008ensure this space gets freed when the corresponding space on the main 7009stack is free. 7010 7011Do not define this pattern if all that must be done is the subtraction. 7012Some machines require other operations such as stack probes or 7013maintaining the back chain. Define this pattern to emit those 7014operations in addition to updating the stack pointer. 7015 7016@cindex @code{check_stack} instruction pattern 7017@item @samp{check_stack} 7018If stack checking (@pxref{Stack Checking}) cannot be done on your system by 7019probing the stack, define this pattern to perform the needed check and signal 7020an error if the stack has overflowed. The single operand is the address in 7021the stack farthest from the current stack pointer that you need to validate. 7022Normally, on platforms where this pattern is needed, you would obtain the 7023stack limit from a global or thread-specific variable or register. 7024 7025@cindex @code{probe_stack_address} instruction pattern 7026@item @samp{probe_stack_address} 7027If stack checking (@pxref{Stack Checking}) can be done on your system by 7028probing the stack but without the need to actually access it, define this 7029pattern and signal an error if the stack has overflowed. The single operand 7030is the memory address in the stack that needs to be probed. 7031 7032@cindex @code{probe_stack} instruction pattern 7033@item @samp{probe_stack} 7034If stack checking (@pxref{Stack Checking}) can be done on your system by 7035probing the stack but doing it with a ``store zero'' instruction is not valid 7036or optimal, define this pattern to do the probing differently and signal an 7037error if the stack has overflowed. The single operand is the memory reference 7038in the stack that needs to be probed. 7039 7040@cindex @code{nonlocal_goto} instruction pattern 7041@item @samp{nonlocal_goto} 7042Emit code to generate a non-local goto, e.g., a jump from one function 7043to a label in an outer function. This pattern has four arguments, 7044each representing a value to be used in the jump. The first 7045argument is to be loaded into the frame pointer, the second is 7046the address to branch to (code to dispatch to the actual label), 7047the third is the address of a location where the stack is saved, 7048and the last is the address of the label, to be placed in the 7049location for the incoming static chain. 7050 7051On most machines you need not define this pattern, since GCC will 7052already generate the correct code, which is to load the frame pointer 7053and static chain, restore the stack (using the 7054@samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly 7055to the dispatcher. You need only define this pattern if this code will 7056not work on your machine. 7057 7058@cindex @code{nonlocal_goto_receiver} instruction pattern 7059@item @samp{nonlocal_goto_receiver} 7060This pattern, if defined, contains code needed at the target of a 7061nonlocal goto after the code already generated by GCC@. You will not 7062normally need to define this pattern. A typical reason why you might 7063need this pattern is if some value, such as a pointer to a global table, 7064must be restored when the frame pointer is restored. Note that a nonlocal 7065goto only occurs within a unit-of-translation, so a global table pointer 7066that is shared by all functions of a given module need not be restored. 7067There are no arguments. 7068 7069@cindex @code{exception_receiver} instruction pattern 7070@item @samp{exception_receiver} 7071This pattern, if defined, contains code needed at the site of an 7072exception handler that isn't needed at the site of a nonlocal goto. You 7073will not normally need to define this pattern. A typical reason why you 7074might need this pattern is if some value, such as a pointer to a global 7075table, must be restored after control flow is branched to the handler of 7076an exception. There are no arguments. 7077 7078@cindex @code{builtin_setjmp_setup} instruction pattern 7079@item @samp{builtin_setjmp_setup} 7080This pattern, if defined, contains additional code needed to initialize 7081the @code{jmp_buf}. You will not normally need to define this pattern. 7082A typical reason why you might need this pattern is if some value, such 7083as a pointer to a global table, must be restored. Though it is 7084preferred that the pointer value be recalculated if possible (given the 7085address of a label for instance). The single argument is a pointer to 7086the @code{jmp_buf}. Note that the buffer is five words long and that 7087the first three are normally used by the generic mechanism. 7088 7089@cindex @code{builtin_setjmp_receiver} instruction pattern 7090@item @samp{builtin_setjmp_receiver} 7091This pattern, if defined, contains code needed at the site of a 7092built-in setjmp that isn't needed at the site of a nonlocal goto. You 7093will not normally need to define this pattern. A typical reason why you 7094might need this pattern is if some value, such as a pointer to a global 7095table, must be restored. It takes one argument, which is the label 7096to which builtin_longjmp transferred control; this pattern may be emitted 7097at a small offset from that label. 7098 7099@cindex @code{builtin_longjmp} instruction pattern 7100@item @samp{builtin_longjmp} 7101This pattern, if defined, performs the entire action of the longjmp. 7102You will not normally need to define this pattern unless you also define 7103@code{builtin_setjmp_setup}. The single argument is a pointer to the 7104@code{jmp_buf}. 7105 7106@cindex @code{eh_return} instruction pattern 7107@item @samp{eh_return} 7108This pattern, if defined, affects the way @code{__builtin_eh_return}, 7109and thence the call frame exception handling library routines, are 7110built. It is intended to handle non-trivial actions needed along 7111the abnormal return path. 7112 7113The address of the exception handler to which the function should return 7114is passed as operand to this pattern. It will normally need to copied by 7115the pattern to some special register or memory location. 7116If the pattern needs to determine the location of the target call 7117frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX}, 7118if defined; it will have already been assigned. 7119 7120If this pattern is not defined, the default action will be to simply 7121copy the return address to @code{EH_RETURN_HANDLER_RTX}. Either 7122that macro or this pattern needs to be defined if call frame exception 7123handling is to be used. 7124 7125@cindex @code{prologue} instruction pattern 7126@anchor{prologue instruction pattern} 7127@item @samp{prologue} 7128This pattern, if defined, emits RTL for entry to a function. The function 7129entry is responsible for setting up the stack frame, initializing the frame 7130pointer register, saving callee saved registers, etc. 7131 7132Using a prologue pattern is generally preferred over defining 7133@code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue. 7134 7135The @code{prologue} pattern is particularly useful for targets which perform 7136instruction scheduling. 7137 7138@cindex @code{window_save} instruction pattern 7139@anchor{window_save instruction pattern} 7140@item @samp{window_save} 7141This pattern, if defined, emits RTL for a register window save. It should 7142be defined if the target machine has register windows but the window events 7143are decoupled from calls to subroutines. The canonical example is the SPARC 7144architecture. 7145 7146@cindex @code{epilogue} instruction pattern 7147@anchor{epilogue instruction pattern} 7148@item @samp{epilogue} 7149This pattern emits RTL for exit from a function. The function 7150exit is responsible for deallocating the stack frame, restoring callee saved 7151registers and emitting the return instruction. 7152 7153Using an epilogue pattern is generally preferred over defining 7154@code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue. 7155 7156The @code{epilogue} pattern is particularly useful for targets which perform 7157instruction scheduling or which have delay slots for their return instruction. 7158 7159@cindex @code{sibcall_epilogue} instruction pattern 7160@item @samp{sibcall_epilogue} 7161This pattern, if defined, emits RTL for exit from a function without the final 7162branch back to the calling function. This pattern will be emitted before any 7163sibling call (aka tail call) sites. 7164 7165The @code{sibcall_epilogue} pattern must not clobber any arguments used for 7166parameter passing or any stack slots for arguments passed to the current 7167function. 7168 7169@cindex @code{trap} instruction pattern 7170@item @samp{trap} 7171This pattern, if defined, signals an error, typically by causing some 7172kind of signal to be raised. 7173 7174@cindex @code{ctrap@var{MM}4} instruction pattern 7175@item @samp{ctrap@var{MM}4} 7176Conditional trap instruction. Operand 0 is a piece of RTL which 7177performs a comparison, and operands 1 and 2 are the arms of the 7178comparison. Operand 3 is the trap code, an integer. 7179 7180A typical @code{ctrap} pattern looks like 7181 7182@smallexample 7183(define_insn "ctrapsi4" 7184 [(trap_if (match_operator 0 "trap_operator" 7185 [(match_operand 1 "register_operand") 7186 (match_operand 2 "immediate_operand")]) 7187 (match_operand 3 "const_int_operand" "i"))] 7188 "" 7189 "@dots{}") 7190@end smallexample 7191 7192@cindex @code{prefetch} instruction pattern 7193@item @samp{prefetch} 7194This pattern, if defined, emits code for a non-faulting data prefetch 7195instruction. Operand 0 is the address of the memory to prefetch. Operand 1 7196is a constant 1 if the prefetch is preparing for a write to the memory 7197address, or a constant 0 otherwise. Operand 2 is the expected degree of 7198temporal locality of the data and is a value between 0 and 3, inclusive; 0 7199means that the data has no temporal locality, so it need not be left in the 7200cache after the access; 3 means that the data has a high degree of temporal 7201locality and should be left in all levels of cache possible; 1 and 2 mean, 7202respectively, a low or moderate degree of temporal locality. 7203 7204Targets that do not support write prefetches or locality hints can ignore 7205the values of operands 1 and 2. 7206 7207@cindex @code{blockage} instruction pattern 7208@item @samp{blockage} 7209This pattern defines a pseudo insn that prevents the instruction 7210scheduler and other passes from moving instructions and using register 7211equivalences across the boundary defined by the blockage insn. 7212This needs to be an UNSPEC_VOLATILE pattern or a volatile ASM. 7213 7214@cindex @code{memory_blockage} instruction pattern 7215@item @samp{memory_blockage} 7216This pattern, if defined, represents a compiler memory barrier, and will be 7217placed at points across which RTL passes may not propagate memory accesses. 7218This instruction needs to read and write volatile BLKmode memory. It does 7219not need to generate any machine instruction. If this pattern is not defined, 7220the compiler falls back to emitting an instruction corresponding 7221to @code{asm volatile ("" ::: "memory")}. 7222 7223@cindex @code{memory_barrier} instruction pattern 7224@item @samp{memory_barrier} 7225If the target memory model is not fully synchronous, then this pattern 7226should be defined to an instruction that orders both loads and stores 7227before the instruction with respect to loads and stores after the instruction. 7228This pattern has no operands. 7229 7230@cindex @code{speculation_barrier} instruction pattern 7231@item @samp{speculation_barrier} 7232If the target can support speculative execution, then this pattern should 7233be defined to an instruction that will block subsequent execution until 7234any prior speculation conditions has been resolved. The pattern must also 7235ensure that the compiler cannot move memory operations past the barrier, 7236so it needs to be an UNSPEC_VOLATILE pattern. The pattern has no 7237operands. 7238 7239If this pattern is not defined then the default expansion of 7240@code{__builtin_speculation_safe_value} will emit a warning. You can 7241suppress this warning by defining this pattern with a final condition 7242of @code{0} (zero), which tells the compiler that a speculation 7243barrier is not needed for this target. 7244 7245@cindex @code{sync_compare_and_swap@var{mode}} instruction pattern 7246@item @samp{sync_compare_and_swap@var{mode}} 7247This pattern, if defined, emits code for an atomic compare-and-swap 7248operation. Operand 1 is the memory on which the atomic operation is 7249performed. Operand 2 is the ``old'' value to be compared against the 7250current contents of the memory location. Operand 3 is the ``new'' value 7251to store in the memory if the compare succeeds. Operand 0 is the result 7252of the operation; it should contain the contents of the memory 7253before the operation. If the compare succeeds, this should obviously be 7254a copy of operand 2. 7255 7256This pattern must show that both operand 0 and operand 1 are modified. 7257 7258This pattern must issue any memory barrier instructions such that all 7259memory operations before the atomic operation occur before the atomic 7260operation and all memory operations after the atomic operation occur 7261after the atomic operation. 7262 7263For targets where the success or failure of the compare-and-swap 7264operation is available via the status flags, it is possible to 7265avoid a separate compare operation and issue the subsequent 7266branch or store-flag operation immediately after the compare-and-swap. 7267To this end, GCC will look for a @code{MODE_CC} set in the 7268output of @code{sync_compare_and_swap@var{mode}}; if the machine 7269description includes such a set, the target should also define special 7270@code{cbranchcc4} and/or @code{cstorecc4} instructions. GCC will then 7271be able to take the destination of the @code{MODE_CC} set and pass it 7272to the @code{cbranchcc4} or @code{cstorecc4} pattern as the first 7273operand of the comparison (the second will be @code{(const_int 0)}). 7274 7275For targets where the operating system may provide support for this 7276operation via library calls, the @code{sync_compare_and_swap_optab} 7277may be initialized to a function with the same interface as the 7278@code{__sync_val_compare_and_swap_@var{n}} built-in. If the entire 7279set of @var{__sync} builtins are supported via library calls, the 7280target can initialize all of the optabs at once with 7281@code{init_sync_libfuncs}. 7282For the purposes of C++11 @code{std::atomic::is_lock_free}, it is 7283assumed that these library calls do @emph{not} use any kind of 7284interruptable locking. 7285 7286@cindex @code{sync_add@var{mode}} instruction pattern 7287@cindex @code{sync_sub@var{mode}} instruction pattern 7288@cindex @code{sync_ior@var{mode}} instruction pattern 7289@cindex @code{sync_and@var{mode}} instruction pattern 7290@cindex @code{sync_xor@var{mode}} instruction pattern 7291@cindex @code{sync_nand@var{mode}} instruction pattern 7292@item @samp{sync_add@var{mode}}, @samp{sync_sub@var{mode}} 7293@itemx @samp{sync_ior@var{mode}}, @samp{sync_and@var{mode}} 7294@itemx @samp{sync_xor@var{mode}}, @samp{sync_nand@var{mode}} 7295These patterns emit code for an atomic operation on memory. 7296Operand 0 is the memory on which the atomic operation is performed. 7297Operand 1 is the second operand to the binary operator. 7298 7299This pattern must issue any memory barrier instructions such that all 7300memory operations before the atomic operation occur before the atomic 7301operation and all memory operations after the atomic operation occur 7302after the atomic operation. 7303 7304If these patterns are not defined, the operation will be constructed 7305from a compare-and-swap operation, if defined. 7306 7307@cindex @code{sync_old_add@var{mode}} instruction pattern 7308@cindex @code{sync_old_sub@var{mode}} instruction pattern 7309@cindex @code{sync_old_ior@var{mode}} instruction pattern 7310@cindex @code{sync_old_and@var{mode}} instruction pattern 7311@cindex @code{sync_old_xor@var{mode}} instruction pattern 7312@cindex @code{sync_old_nand@var{mode}} instruction pattern 7313@item @samp{sync_old_add@var{mode}}, @samp{sync_old_sub@var{mode}} 7314@itemx @samp{sync_old_ior@var{mode}}, @samp{sync_old_and@var{mode}} 7315@itemx @samp{sync_old_xor@var{mode}}, @samp{sync_old_nand@var{mode}} 7316These patterns emit code for an atomic operation on memory, 7317and return the value that the memory contained before the operation. 7318Operand 0 is the result value, operand 1 is the memory on which the 7319atomic operation is performed, and operand 2 is the second operand 7320to the binary operator. 7321 7322This pattern must issue any memory barrier instructions such that all 7323memory operations before the atomic operation occur before the atomic 7324operation and all memory operations after the atomic operation occur 7325after the atomic operation. 7326 7327If these patterns are not defined, the operation will be constructed 7328from a compare-and-swap operation, if defined. 7329 7330@cindex @code{sync_new_add@var{mode}} instruction pattern 7331@cindex @code{sync_new_sub@var{mode}} instruction pattern 7332@cindex @code{sync_new_ior@var{mode}} instruction pattern 7333@cindex @code{sync_new_and@var{mode}} instruction pattern 7334@cindex @code{sync_new_xor@var{mode}} instruction pattern 7335@cindex @code{sync_new_nand@var{mode}} instruction pattern 7336@item @samp{sync_new_add@var{mode}}, @samp{sync_new_sub@var{mode}} 7337@itemx @samp{sync_new_ior@var{mode}}, @samp{sync_new_and@var{mode}} 7338@itemx @samp{sync_new_xor@var{mode}}, @samp{sync_new_nand@var{mode}} 7339These patterns are like their @code{sync_old_@var{op}} counterparts, 7340except that they return the value that exists in the memory location 7341after the operation, rather than before the operation. 7342 7343@cindex @code{sync_lock_test_and_set@var{mode}} instruction pattern 7344@item @samp{sync_lock_test_and_set@var{mode}} 7345This pattern takes two forms, based on the capabilities of the target. 7346In either case, operand 0 is the result of the operand, operand 1 is 7347the memory on which the atomic operation is performed, and operand 2 7348is the value to set in the lock. 7349 7350In the ideal case, this operation is an atomic exchange operation, in 7351which the previous value in memory operand is copied into the result 7352operand, and the value operand is stored in the memory operand. 7353 7354For less capable targets, any value operand that is not the constant 1 7355should be rejected with @code{FAIL}. In this case the target may use 7356an atomic test-and-set bit operation. The result operand should contain 73571 if the bit was previously set and 0 if the bit was previously clear. 7358The true contents of the memory operand are implementation defined. 7359 7360This pattern must issue any memory barrier instructions such that the 7361pattern as a whole acts as an acquire barrier, that is all memory 7362operations after the pattern do not occur until the lock is acquired. 7363 7364If this pattern is not defined, the operation will be constructed from 7365a compare-and-swap operation, if defined. 7366 7367@cindex @code{sync_lock_release@var{mode}} instruction pattern 7368@item @samp{sync_lock_release@var{mode}} 7369This pattern, if defined, releases a lock set by 7370@code{sync_lock_test_and_set@var{mode}}. Operand 0 is the memory 7371that contains the lock; operand 1 is the value to store in the lock. 7372 7373If the target doesn't implement full semantics for 7374@code{sync_lock_test_and_set@var{mode}}, any value operand which is not 7375the constant 0 should be rejected with @code{FAIL}, and the true contents 7376of the memory operand are implementation defined. 7377 7378This pattern must issue any memory barrier instructions such that the 7379pattern as a whole acts as a release barrier, that is the lock is 7380released only after all previous memory operations have completed. 7381 7382If this pattern is not defined, then a @code{memory_barrier} pattern 7383will be emitted, followed by a store of the value to the memory operand. 7384 7385@cindex @code{atomic_compare_and_swap@var{mode}} instruction pattern 7386@item @samp{atomic_compare_and_swap@var{mode}} 7387This pattern, if defined, emits code for an atomic compare-and-swap 7388operation with memory model semantics. Operand 2 is the memory on which 7389the atomic operation is performed. Operand 0 is an output operand which 7390is set to true or false based on whether the operation succeeded. Operand 73911 is an output operand which is set to the contents of the memory before 7392the operation was attempted. Operand 3 is the value that is expected to 7393be in memory. Operand 4 is the value to put in memory if the expected 7394value is found there. Operand 5 is set to 1 if this compare and swap is to 7395be treated as a weak operation. Operand 6 is the memory model to be used 7396if the operation is a success. Operand 7 is the memory model to be used 7397if the operation fails. 7398 7399If memory referred to in operand 2 contains the value in operand 3, then 7400operand 4 is stored in memory pointed to by operand 2 and fencing based on 7401the memory model in operand 6 is issued. 7402 7403If memory referred to in operand 2 does not contain the value in operand 3, 7404then fencing based on the memory model in operand 7 is issued. 7405 7406If a target does not support weak compare-and-swap operations, or the port 7407elects not to implement weak operations, the argument in operand 5 can be 7408ignored. Note a strong implementation must be provided. 7409 7410If this pattern is not provided, the @code{__atomic_compare_exchange} 7411built-in functions will utilize the legacy @code{sync_compare_and_swap} 7412pattern with an @code{__ATOMIC_SEQ_CST} memory model. 7413 7414@cindex @code{atomic_load@var{mode}} instruction pattern 7415@item @samp{atomic_load@var{mode}} 7416This pattern implements an atomic load operation with memory model 7417semantics. Operand 1 is the memory address being loaded from. Operand 0 7418is the result of the load. Operand 2 is the memory model to be used for 7419the load operation. 7420 7421If not present, the @code{__atomic_load} built-in function will either 7422resort to a normal load with memory barriers, or a compare-and-swap 7423operation if a normal load would not be atomic. 7424 7425@cindex @code{atomic_store@var{mode}} instruction pattern 7426@item @samp{atomic_store@var{mode}} 7427This pattern implements an atomic store operation with memory model 7428semantics. Operand 0 is the memory address being stored to. Operand 1 7429is the value to be written. Operand 2 is the memory model to be used for 7430the operation. 7431 7432If not present, the @code{__atomic_store} built-in function will attempt to 7433perform a normal store and surround it with any required memory fences. If 7434the store would not be atomic, then an @code{__atomic_exchange} is 7435attempted with the result being ignored. 7436 7437@cindex @code{atomic_exchange@var{mode}} instruction pattern 7438@item @samp{atomic_exchange@var{mode}} 7439This pattern implements an atomic exchange operation with memory model 7440semantics. Operand 1 is the memory location the operation is performed on. 7441Operand 0 is an output operand which is set to the original value contained 7442in the memory pointed to by operand 1. Operand 2 is the value to be 7443stored. Operand 3 is the memory model to be used. 7444 7445If this pattern is not present, the built-in function 7446@code{__atomic_exchange} will attempt to preform the operation with a 7447compare and swap loop. 7448 7449@cindex @code{atomic_add@var{mode}} instruction pattern 7450@cindex @code{atomic_sub@var{mode}} instruction pattern 7451@cindex @code{atomic_or@var{mode}} instruction pattern 7452@cindex @code{atomic_and@var{mode}} instruction pattern 7453@cindex @code{atomic_xor@var{mode}} instruction pattern 7454@cindex @code{atomic_nand@var{mode}} instruction pattern 7455@item @samp{atomic_add@var{mode}}, @samp{atomic_sub@var{mode}} 7456@itemx @samp{atomic_or@var{mode}}, @samp{atomic_and@var{mode}} 7457@itemx @samp{atomic_xor@var{mode}}, @samp{atomic_nand@var{mode}} 7458These patterns emit code for an atomic operation on memory with memory 7459model semantics. Operand 0 is the memory on which the atomic operation is 7460performed. Operand 1 is the second operand to the binary operator. 7461Operand 2 is the memory model to be used by the operation. 7462 7463If these patterns are not defined, attempts will be made to use legacy 7464@code{sync} patterns, or equivalent patterns which return a result. If 7465none of these are available a compare-and-swap loop will be used. 7466 7467@cindex @code{atomic_fetch_add@var{mode}} instruction pattern 7468@cindex @code{atomic_fetch_sub@var{mode}} instruction pattern 7469@cindex @code{atomic_fetch_or@var{mode}} instruction pattern 7470@cindex @code{atomic_fetch_and@var{mode}} instruction pattern 7471@cindex @code{atomic_fetch_xor@var{mode}} instruction pattern 7472@cindex @code{atomic_fetch_nand@var{mode}} instruction pattern 7473@item @samp{atomic_fetch_add@var{mode}}, @samp{atomic_fetch_sub@var{mode}} 7474@itemx @samp{atomic_fetch_or@var{mode}}, @samp{atomic_fetch_and@var{mode}} 7475@itemx @samp{atomic_fetch_xor@var{mode}}, @samp{atomic_fetch_nand@var{mode}} 7476These patterns emit code for an atomic operation on memory with memory 7477model semantics, and return the original value. Operand 0 is an output 7478operand which contains the value of the memory location before the 7479operation was performed. Operand 1 is the memory on which the atomic 7480operation is performed. Operand 2 is the second operand to the binary 7481operator. Operand 3 is the memory model to be used by the operation. 7482 7483If these patterns are not defined, attempts will be made to use legacy 7484@code{sync} patterns. If none of these are available a compare-and-swap 7485loop will be used. 7486 7487@cindex @code{atomic_add_fetch@var{mode}} instruction pattern 7488@cindex @code{atomic_sub_fetch@var{mode}} instruction pattern 7489@cindex @code{atomic_or_fetch@var{mode}} instruction pattern 7490@cindex @code{atomic_and_fetch@var{mode}} instruction pattern 7491@cindex @code{atomic_xor_fetch@var{mode}} instruction pattern 7492@cindex @code{atomic_nand_fetch@var{mode}} instruction pattern 7493@item @samp{atomic_add_fetch@var{mode}}, @samp{atomic_sub_fetch@var{mode}} 7494@itemx @samp{atomic_or_fetch@var{mode}}, @samp{atomic_and_fetch@var{mode}} 7495@itemx @samp{atomic_xor_fetch@var{mode}}, @samp{atomic_nand_fetch@var{mode}} 7496These patterns emit code for an atomic operation on memory with memory 7497model semantics and return the result after the operation is performed. 7498Operand 0 is an output operand which contains the value after the 7499operation. Operand 1 is the memory on which the atomic operation is 7500performed. Operand 2 is the second operand to the binary operator. 7501Operand 3 is the memory model to be used by the operation. 7502 7503If these patterns are not defined, attempts will be made to use legacy 7504@code{sync} patterns, or equivalent patterns which return the result before 7505the operation followed by the arithmetic operation required to produce the 7506result. If none of these are available a compare-and-swap loop will be 7507used. 7508 7509@cindex @code{atomic_test_and_set} instruction pattern 7510@item @samp{atomic_test_and_set} 7511This pattern emits code for @code{__builtin_atomic_test_and_set}. 7512Operand 0 is an output operand which is set to true if the previous 7513previous contents of the byte was "set", and false otherwise. Operand 1 7514is the @code{QImode} memory to be modified. Operand 2 is the memory 7515model to be used. 7516 7517The specific value that defines "set" is implementation defined, and 7518is normally based on what is performed by the native atomic test and set 7519instruction. 7520 7521@cindex @code{atomic_bit_test_and_set@var{mode}} instruction pattern 7522@cindex @code{atomic_bit_test_and_complement@var{mode}} instruction pattern 7523@cindex @code{atomic_bit_test_and_reset@var{mode}} instruction pattern 7524@item @samp{atomic_bit_test_and_set@var{mode}} 7525@itemx @samp{atomic_bit_test_and_complement@var{mode}} 7526@itemx @samp{atomic_bit_test_and_reset@var{mode}} 7527These patterns emit code for an atomic bitwise operation on memory with memory 7528model semantics, and return the original value of the specified bit. 7529Operand 0 is an output operand which contains the value of the specified bit 7530from the memory location before the operation was performed. Operand 1 is the 7531memory on which the atomic operation is performed. Operand 2 is the bit within 7532the operand, starting with least significant bit. Operand 3 is the memory model 7533to be used by the operation. Operand 4 is a flag - it is @code{const1_rtx} 7534if operand 0 should contain the original value of the specified bit in the 7535least significant bit of the operand, and @code{const0_rtx} if the bit should 7536be in its original position in the operand. 7537@code{atomic_bit_test_and_set@var{mode}} atomically sets the specified bit after 7538remembering its original value, @code{atomic_bit_test_and_complement@var{mode}} 7539inverts the specified bit and @code{atomic_bit_test_and_reset@var{mode}} clears 7540the specified bit. 7541 7542If these patterns are not defined, attempts will be made to use 7543@code{atomic_fetch_or@var{mode}}, @code{atomic_fetch_xor@var{mode}} or 7544@code{atomic_fetch_and@var{mode}} instruction patterns, or their @code{sync} 7545counterparts. If none of these are available a compare-and-swap 7546loop will be used. 7547 7548@cindex @code{mem_thread_fence} instruction pattern 7549@item @samp{mem_thread_fence} 7550This pattern emits code required to implement a thread fence with 7551memory model semantics. Operand 0 is the memory model to be used. 7552 7553For the @code{__ATOMIC_RELAXED} model no instructions need to be issued 7554and this expansion is not invoked. 7555 7556The compiler always emits a compiler memory barrier regardless of what 7557expanding this pattern produced. 7558 7559If this pattern is not defined, the compiler falls back to expanding the 7560@code{memory_barrier} pattern, then to emitting @code{__sync_synchronize} 7561library call, and finally to just placing a compiler memory barrier. 7562 7563@cindex @code{get_thread_pointer@var{mode}} instruction pattern 7564@cindex @code{set_thread_pointer@var{mode}} instruction pattern 7565@item @samp{get_thread_pointer@var{mode}} 7566@itemx @samp{set_thread_pointer@var{mode}} 7567These patterns emit code that reads/sets the TLS thread pointer. Currently, 7568these are only needed if the target needs to support the 7569@code{__builtin_thread_pointer} and @code{__builtin_set_thread_pointer} 7570builtins. 7571 7572The get/set patterns have a single output/input operand respectively, 7573with @var{mode} intended to be @code{Pmode}. 7574 7575@cindex @code{stack_protect_combined_set} instruction pattern 7576@item @samp{stack_protect_combined_set} 7577This pattern, if defined, moves a @code{ptr_mode} value from an address 7578whose declaration RTX is given in operand 1 to the memory in operand 0 7579without leaving the value in a register afterward. If several 7580instructions are needed by the target to perform the operation (eg. to 7581load the address from a GOT entry then load the @code{ptr_mode} value 7582and finally store it), it is the backend's responsibility to ensure no 7583intermediate result gets spilled. This is to avoid leaking the value 7584some place that an attacker might use to rewrite the stack guard slot 7585after having clobbered it. 7586 7587If this pattern is not defined, then the address declaration is 7588expanded first in the standard way and a @code{stack_protect_set} 7589pattern is then generated to move the value from that address to the 7590address in operand 0. 7591 7592@cindex @code{stack_protect_set} instruction pattern 7593@item @samp{stack_protect_set} 7594This pattern, if defined, moves a @code{ptr_mode} value from the valid 7595memory location in operand 1 to the memory in operand 0 without leaving 7596the value in a register afterward. This is to avoid leaking the value 7597some place that an attacker might use to rewrite the stack guard slot 7598after having clobbered it. 7599 7600Note: on targets where the addressing modes do not allow to load 7601directly from stack guard address, the address is expanded in a standard 7602way first which could cause some spills. 7603 7604If this pattern is not defined, then a plain move pattern is generated. 7605 7606@cindex @code{stack_protect_combined_test} instruction pattern 7607@item @samp{stack_protect_combined_test} 7608This pattern, if defined, compares a @code{ptr_mode} value from an 7609address whose declaration RTX is given in operand 1 with the memory in 7610operand 0 without leaving the value in a register afterward and 7611branches to operand 2 if the values were equal. If several 7612instructions are needed by the target to perform the operation (eg. to 7613load the address from a GOT entry then load the @code{ptr_mode} value 7614and finally store it), it is the backend's responsibility to ensure no 7615intermediate result gets spilled. This is to avoid leaking the value 7616some place that an attacker might use to rewrite the stack guard slot 7617after having clobbered it. 7618 7619If this pattern is not defined, then the address declaration is 7620expanded first in the standard way and a @code{stack_protect_test} 7621pattern is then generated to compare the value from that address to the 7622value at the memory in operand 0. 7623 7624@cindex @code{stack_protect_test} instruction pattern 7625@item @samp{stack_protect_test} 7626This pattern, if defined, compares a @code{ptr_mode} value from the 7627valid memory location in operand 1 with the memory in operand 0 without 7628leaving the value in a register afterward and branches to operand 2 if 7629the values were equal. 7630 7631If this pattern is not defined, then a plain compare pattern and 7632conditional branch pattern is used. 7633 7634@cindex @code{clear_cache} instruction pattern 7635@item @samp{clear_cache} 7636This pattern, if defined, flushes the instruction cache for a region of 7637memory. The region is bounded to by the Pmode pointers in operand 0 7638inclusive and operand 1 exclusive. 7639 7640If this pattern is not defined, a call to the library function 7641@code{__clear_cache} is used. 7642 7643@end table 7644 7645@end ifset 7646@c Each of the following nodes are wrapped in separate 7647@c "@ifset INTERNALS" to work around memory limits for the default 7648@c configuration in older tetex distributions. Known to not work: 7649@c tetex-1.0.7, known to work: tetex-2.0.2. 7650@ifset INTERNALS 7651@node Pattern Ordering 7652@section When the Order of Patterns Matters 7653@cindex Pattern Ordering 7654@cindex Ordering of Patterns 7655 7656Sometimes an insn can match more than one instruction pattern. Then the 7657pattern that appears first in the machine description is the one used. 7658Therefore, more specific patterns (patterns that will match fewer things) 7659and faster instructions (those that will produce better code when they 7660do match) should usually go first in the description. 7661 7662In some cases the effect of ordering the patterns can be used to hide 7663a pattern when it is not valid. For example, the 68000 has an 7664instruction for converting a fullword to floating point and another 7665for converting a byte to floating point. An instruction converting 7666an integer to floating point could match either one. We put the 7667pattern to convert the fullword first to make sure that one will 7668be used rather than the other. (Otherwise a large integer might 7669be generated as a single-byte immediate quantity, which would not work.) 7670Instead of using this pattern ordering it would be possible to make the 7671pattern for convert-a-byte smart enough to deal properly with any 7672constant value. 7673 7674@end ifset 7675@ifset INTERNALS 7676@node Dependent Patterns 7677@section Interdependence of Patterns 7678@cindex Dependent Patterns 7679@cindex Interdependence of Patterns 7680 7681In some cases machines support instructions identical except for the 7682machine mode of one or more operands. For example, there may be 7683``sign-extend halfword'' and ``sign-extend byte'' instructions whose 7684patterns are 7685 7686@smallexample 7687(set (match_operand:SI 0 @dots{}) 7688 (extend:SI (match_operand:HI 1 @dots{}))) 7689 7690(set (match_operand:SI 0 @dots{}) 7691 (extend:SI (match_operand:QI 1 @dots{}))) 7692@end smallexample 7693 7694@noindent 7695Constant integers do not specify a machine mode, so an instruction to 7696extend a constant value could match either pattern. The pattern it 7697actually will match is the one that appears first in the file. For correct 7698results, this must be the one for the widest possible mode (@code{HImode}, 7699here). If the pattern matches the @code{QImode} instruction, the results 7700will be incorrect if the constant value does not actually fit that mode. 7701 7702Such instructions to extend constants are rarely generated because they are 7703optimized away, but they do occasionally happen in nonoptimized 7704compilations. 7705 7706If a constraint in a pattern allows a constant, the reload pass may 7707replace a register with a constant permitted by the constraint in some 7708cases. Similarly for memory references. Because of this substitution, 7709you should not provide separate patterns for increment and decrement 7710instructions. Instead, they should be generated from the same pattern 7711that supports register-register add insns by examining the operands and 7712generating the appropriate machine instruction. 7713 7714@end ifset 7715@ifset INTERNALS 7716@node Jump Patterns 7717@section Defining Jump Instruction Patterns 7718@cindex jump instruction patterns 7719@cindex defining jump instruction patterns 7720 7721GCC does not assume anything about how the machine realizes jumps. 7722The machine description should define a single pattern, usually 7723a @code{define_expand}, which expands to all the required insns. 7724 7725Usually, this would be a comparison insn to set the condition code 7726and a separate branch insn testing the condition code and branching 7727or not according to its value. For many machines, however, 7728separating compares and branches is limiting, which is why the 7729more flexible approach with one @code{define_expand} is used in GCC. 7730The machine description becomes clearer for architectures that 7731have compare-and-branch instructions but no condition code. It also 7732works better when different sets of comparison operators are supported 7733by different kinds of conditional branches (e.g.@: integer vs.@: 7734floating-point), or by conditional branches with respect to conditional stores. 7735 7736Two separate insns are always used if the machine description represents 7737a condition code register using the legacy RTL expression @code{(cc0)}, 7738and on most machines that use a separate condition code register 7739(@pxref{Condition Code}). For machines that use @code{(cc0)}, in 7740fact, the set and use of the condition code must be separate and 7741adjacent@footnote{@code{note} insns can separate them, though.}, thus 7742allowing flags in @code{cc_status} to be used (@pxref{Condition Code}) and 7743so that the comparison and branch insns could be located from each other 7744by using the functions @code{prev_cc0_setter} and @code{next_cc0_user}. 7745 7746Even in this case having a single entry point for conditional branches 7747is advantageous, because it handles equally well the case where a single 7748comparison instruction records the results of both signed and unsigned 7749comparison of the given operands (with the branch insns coming in distinct 7750signed and unsigned flavors) as in the x86 or SPARC, and the case where 7751there are distinct signed and unsigned compare instructions and only 7752one set of conditional branch instructions as in the PowerPC. 7753 7754@end ifset 7755@ifset INTERNALS 7756@node Looping Patterns 7757@section Defining Looping Instruction Patterns 7758@cindex looping instruction patterns 7759@cindex defining looping instruction patterns 7760 7761Some machines have special jump instructions that can be utilized to 7762make loops more efficient. A common example is the 68000 @samp{dbra} 7763instruction which performs a decrement of a register and a branch if the 7764result was greater than zero. Other machines, in particular digital 7765signal processors (DSPs), have special block repeat instructions to 7766provide low-overhead loop support. For example, the TI TMS320C3x/C4x 7767DSPs have a block repeat instruction that loads special registers to 7768mark the top and end of a loop and to count the number of loop 7769iterations. This avoids the need for fetching and executing a 7770@samp{dbra}-like instruction and avoids pipeline stalls associated with 7771the jump. 7772 7773GCC has two special named patterns to support low overhead looping. 7774They are @samp{doloop_begin} and @samp{doloop_end}. These are emitted 7775by the loop optimizer for certain well-behaved loops with a finite 7776number of loop iterations using information collected during strength 7777reduction. 7778 7779The @samp{doloop_end} pattern describes the actual looping instruction 7780(or the implicit looping operation) and the @samp{doloop_begin} pattern 7781is an optional companion pattern that can be used for initialization 7782needed for some low-overhead looping instructions. 7783 7784Note that some machines require the actual looping instruction to be 7785emitted at the top of the loop (e.g., the TMS320C3x/C4x DSPs). Emitting 7786the true RTL for a looping instruction at the top of the loop can cause 7787problems with flow analysis. So instead, a dummy @code{doloop} insn is 7788emitted at the end of the loop. The machine dependent reorg pass checks 7789for the presence of this @code{doloop} insn and then searches back to 7790the top of the loop, where it inserts the true looping insn (provided 7791there are no instructions in the loop which would cause problems). Any 7792additional labels can be emitted at this point. In addition, if the 7793desired special iteration counter register was not allocated, this 7794machine dependent reorg pass could emit a traditional compare and jump 7795instruction pair. 7796 7797For the @samp{doloop_end} pattern, the loop optimizer allocates an 7798additional pseudo register as an iteration counter. This pseudo 7799register cannot be used within the loop (i.e., general induction 7800variables cannot be derived from it), however, in many cases the loop 7801induction variable may become redundant and removed by the flow pass. 7802 7803The @samp{doloop_end} pattern must have a specific structure to be 7804handled correctly by GCC. The example below is taken (slightly 7805simplified) from the PDP-11 target: 7806 7807@smallexample 7808@group 7809(define_expand "doloop_end" 7810 [(parallel [(set (pc) 7811 (if_then_else 7812 (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m") 7813 (const_int 1)) 7814 (label_ref (match_operand 1 "" "")) 7815 (pc))) 7816 (set (match_dup 0) 7817 (plus:HI (match_dup 0) 7818 (const_int -1)))])] 7819 "" 7820 "@{ 7821 if (GET_MODE (operands[0]) != HImode) 7822 FAIL; 7823 @}") 7824 7825(define_insn "doloop_end_insn" 7826 [(set (pc) 7827 (if_then_else 7828 (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m") 7829 (const_int 1)) 7830 (label_ref (match_operand 1 "" "")) 7831 (pc))) 7832 (set (match_dup 0) 7833 (plus:HI (match_dup 0) 7834 (const_int -1)))] 7835 "" 7836 7837 @{ 7838 if (which_alternative == 0) 7839 return "sob %0,%l1"; 7840 7841 /* emulate sob */ 7842 output_asm_insn ("dec %0", operands); 7843 return "bne %l1"; 7844 @}) 7845@end group 7846@end smallexample 7847 7848The first part of the pattern describes the branch condition. GCC 7849supports three cases for the way the target machine handles the loop 7850counter: 7851@itemize @bullet 7852@item Loop terminates when the loop register decrements to zero. This 7853is represented by a @code{ne} comparison of the register (its old value) 7854with constant 1 (as in the example above). 7855@item Loop terminates when the loop register decrements to @minus{}1. 7856This is represented by a @code{ne} comparison of the register with 7857constant zero. 7858@item Loop terminates when the loop register decrements to a negative 7859value. This is represented by a @code{ge} comparison of the register 7860with constant zero. For this case, GCC will attach a @code{REG_NONNEG} 7861note to the @code{doloop_end} insn if it can determine that the register 7862will be non-negative. 7863@end itemize 7864 7865Since the @code{doloop_end} insn is a jump insn that also has an output, 7866the reload pass does not handle the output operand. Therefore, the 7867constraint must allow for that operand to be in memory rather than a 7868register. In the example shown above, that is handled (in the 7869@code{doloop_end_insn} pattern) by using a loop instruction sequence 7870that can handle memory operands when the memory alternative appears. 7871 7872GCC does not check the mode of the loop register operand when generating 7873the @code{doloop_end} pattern. If the pattern is only valid for some 7874modes but not others, the pattern should be a @code{define_expand} 7875pattern that checks the operand mode in the preparation code, and issues 7876@code{FAIL} if an unsupported mode is found. The example above does 7877this, since the machine instruction to be used only exists for 7878@code{HImode}. 7879 7880If the @code{doloop_end} pattern is a @code{define_expand}, there must 7881also be a @code{define_insn} or @code{define_insn_and_split} matching 7882the generated pattern. Otherwise, the compiler will fail during loop 7883optimization. 7884 7885@end ifset 7886@ifset INTERNALS 7887@node Insn Canonicalizations 7888@section Canonicalization of Instructions 7889@cindex canonicalization of instructions 7890@cindex insn canonicalization 7891 7892There are often cases where multiple RTL expressions could represent an 7893operation performed by a single machine instruction. This situation is 7894most commonly encountered with logical, branch, and multiply-accumulate 7895instructions. In such cases, the compiler attempts to convert these 7896multiple RTL expressions into a single canonical form to reduce the 7897number of insn patterns required. 7898 7899In addition to algebraic simplifications, following canonicalizations 7900are performed: 7901 7902@itemize @bullet 7903@item 7904For commutative and comparison operators, a constant is always made the 7905second operand. If a machine only supports a constant as the second 7906operand, only patterns that match a constant in the second operand need 7907be supplied. 7908 7909@item 7910For associative operators, a sequence of operators will always chain 7911to the left; for instance, only the left operand of an integer @code{plus} 7912can itself be a @code{plus}. @code{and}, @code{ior}, @code{xor}, 7913@code{plus}, @code{mult}, @code{smin}, @code{smax}, @code{umin}, and 7914@code{umax} are associative when applied to integers, and sometimes to 7915floating-point. 7916 7917@item 7918@cindex @code{neg}, canonicalization of 7919@cindex @code{not}, canonicalization of 7920@cindex @code{mult}, canonicalization of 7921@cindex @code{plus}, canonicalization of 7922@cindex @code{minus}, canonicalization of 7923For these operators, if only one operand is a @code{neg}, @code{not}, 7924@code{mult}, @code{plus}, or @code{minus} expression, it will be the 7925first operand. 7926 7927@item 7928In combinations of @code{neg}, @code{mult}, @code{plus}, and 7929@code{minus}, the @code{neg} operations (if any) will be moved inside 7930the operations as far as possible. For instance, 7931@code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but 7932@code{(plus (mult (neg B) C) A)} is canonicalized as 7933@code{(minus A (mult B C))}. 7934 7935@cindex @code{compare}, canonicalization of 7936@item 7937For the @code{compare} operator, a constant is always the second operand 7938if the first argument is a condition code register or @code{(cc0)}. 7939 7940@item 7941For instructions that inherently set a condition code register, the 7942@code{compare} operator is always written as the first RTL expression of 7943the @code{parallel} instruction pattern. For example, 7944 7945@smallexample 7946(define_insn "" 7947 [(set (reg:CCZ FLAGS_REG) 7948 (compare:CCZ 7949 (plus:SI 7950 (match_operand:SI 1 "register_operand" "%r") 7951 (match_operand:SI 2 "register_operand" "r")) 7952 (const_int 0))) 7953 (set (match_operand:SI 0 "register_operand" "=r") 7954 (plus:SI (match_dup 1) (match_dup 2)))] 7955 "" 7956 "addl %0, %1, %2") 7957@end smallexample 7958 7959@item 7960An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or 7961@code{minus} is made the first operand under the same conditions as 7962above. 7963 7964@item 7965@code{(ltu (plus @var{a} @var{b}) @var{b})} is converted to 7966@code{(ltu (plus @var{a} @var{b}) @var{a})}. Likewise with @code{geu} instead 7967of @code{ltu}. 7968 7969@item 7970@code{(minus @var{x} (const_int @var{n}))} is converted to 7971@code{(plus @var{x} (const_int @var{-n}))}. 7972 7973@item 7974Within address computations (i.e., inside @code{mem}), a left shift is 7975converted into the appropriate multiplication by a power of two. 7976 7977@cindex @code{ior}, canonicalization of 7978@cindex @code{and}, canonicalization of 7979@cindex De Morgan's law 7980@item 7981De Morgan's Law is used to move bitwise negation inside a bitwise 7982logical-and or logical-or operation. If this results in only one 7983operand being a @code{not} expression, it will be the first one. 7984 7985A machine that has an instruction that performs a bitwise logical-and of one 7986operand with the bitwise negation of the other should specify the pattern 7987for that instruction as 7988 7989@smallexample 7990(define_insn "" 7991 [(set (match_operand:@var{m} 0 @dots{}) 7992 (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) 7993 (match_operand:@var{m} 2 @dots{})))] 7994 "@dots{}" 7995 "@dots{}") 7996@end smallexample 7997 7998@noindent 7999Similarly, a pattern for a ``NAND'' instruction should be written 8000 8001@smallexample 8002(define_insn "" 8003 [(set (match_operand:@var{m} 0 @dots{}) 8004 (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) 8005 (not:@var{m} (match_operand:@var{m} 2 @dots{}))))] 8006 "@dots{}" 8007 "@dots{}") 8008@end smallexample 8009 8010In both cases, it is not necessary to include patterns for the many 8011logically equivalent RTL expressions. 8012 8013@cindex @code{xor}, canonicalization of 8014@item 8015The only possible RTL expressions involving both bitwise exclusive-or 8016and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})} 8017and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}. 8018 8019@item 8020The sum of three items, one of which is a constant, will only appear in 8021the form 8022 8023@smallexample 8024(plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant}) 8025@end smallexample 8026 8027@cindex @code{zero_extract}, canonicalization of 8028@cindex @code{sign_extract}, canonicalization of 8029@item 8030Equality comparisons of a group of bits (usually a single bit) with zero 8031will be written using @code{zero_extract} rather than the equivalent 8032@code{and} or @code{sign_extract} operations. 8033 8034@cindex @code{mult}, canonicalization of 8035@item 8036@code{(sign_extend:@var{m1} (mult:@var{m2} (sign_extend:@var{m2} @var{x}) 8037(sign_extend:@var{m2} @var{y})))} is converted to @code{(mult:@var{m1} 8038(sign_extend:@var{m1} @var{x}) (sign_extend:@var{m1} @var{y}))}, and likewise 8039for @code{zero_extend}. 8040 8041@item 8042@code{(sign_extend:@var{m1} (mult:@var{m2} (ashiftrt:@var{m2} 8043@var{x} @var{s}) (sign_extend:@var{m2} @var{y})))} is converted 8044to @code{(mult:@var{m1} (sign_extend:@var{m1} (ashiftrt:@var{m2} 8045@var{x} @var{s})) (sign_extend:@var{m1} @var{y}))}, and likewise for 8046patterns using @code{zero_extend} and @code{lshiftrt}. If the second 8047operand of @code{mult} is also a shift, then that is extended also. 8048This transformation is only applied when it can be proven that the 8049original operation had sufficient precision to prevent overflow. 8050 8051@end itemize 8052 8053Further canonicalization rules are defined in the function 8054@code{commutative_operand_precedence} in @file{gcc/rtlanal.c}. 8055 8056@end ifset 8057@ifset INTERNALS 8058@node Expander Definitions 8059@section Defining RTL Sequences for Code Generation 8060@cindex expander definitions 8061@cindex code generation RTL sequences 8062@cindex defining RTL sequences for code generation 8063 8064On some target machines, some standard pattern names for RTL generation 8065cannot be handled with single insn, but a sequence of RTL insns can 8066represent them. For these target machines, you can write a 8067@code{define_expand} to specify how to generate the sequence of RTL@. 8068 8069@findex define_expand 8070A @code{define_expand} is an RTL expression that looks almost like a 8071@code{define_insn}; but, unlike the latter, a @code{define_expand} is used 8072only for RTL generation and it can produce more than one RTL insn. 8073 8074A @code{define_expand} RTX has four operands: 8075 8076@itemize @bullet 8077@item 8078The name. Each @code{define_expand} must have a name, since the only 8079use for it is to refer to it by name. 8080 8081@item 8082The RTL template. This is a vector of RTL expressions representing 8083a sequence of separate instructions. Unlike @code{define_insn}, there 8084is no implicit surrounding @code{PARALLEL}. 8085 8086@item 8087The condition, a string containing a C expression. This expression is 8088used to express how the availability of this pattern depends on 8089subclasses of target machine, selected by command-line options when GCC 8090is run. This is just like the condition of a @code{define_insn} that 8091has a standard name. Therefore, the condition (if present) may not 8092depend on the data in the insn being matched, but only the 8093target-machine-type flags. The compiler needs to test these conditions 8094during initialization in order to learn exactly which named instructions 8095are available in a particular run. 8096 8097@item 8098The preparation statements, a string containing zero or more C 8099statements which are to be executed before RTL code is generated from 8100the RTL template. 8101 8102Usually these statements prepare temporary registers for use as 8103internal operands in the RTL template, but they can also generate RTL 8104insns directly by calling routines such as @code{emit_insn}, etc. 8105Any such insns precede the ones that come from the RTL template. 8106 8107@item 8108Optionally, a vector containing the values of attributes. @xref{Insn 8109Attributes}. 8110@end itemize 8111 8112Every RTL insn emitted by a @code{define_expand} must match some 8113@code{define_insn} in the machine description. Otherwise, the compiler 8114will crash when trying to generate code for the insn or trying to optimize 8115it. 8116 8117The RTL template, in addition to controlling generation of RTL insns, 8118also describes the operands that need to be specified when this pattern 8119is used. In particular, it gives a predicate for each operand. 8120 8121A true operand, which needs to be specified in order to generate RTL from 8122the pattern, should be described with a @code{match_operand} in its first 8123occurrence in the RTL template. This enters information on the operand's 8124predicate into the tables that record such things. GCC uses the 8125information to preload the operand into a register if that is required for 8126valid RTL code. If the operand is referred to more than once, subsequent 8127references should use @code{match_dup}. 8128 8129The RTL template may also refer to internal ``operands'' which are 8130temporary registers or labels used only within the sequence made by the 8131@code{define_expand}. Internal operands are substituted into the RTL 8132template with @code{match_dup}, never with @code{match_operand}. The 8133values of the internal operands are not passed in as arguments by the 8134compiler when it requests use of this pattern. Instead, they are computed 8135within the pattern, in the preparation statements. These statements 8136compute the values and store them into the appropriate elements of 8137@code{operands} so that @code{match_dup} can find them. 8138 8139There are two special macros defined for use in the preparation statements: 8140@code{DONE} and @code{FAIL}. Use them with a following semicolon, 8141as a statement. 8142 8143@table @code 8144 8145@findex DONE 8146@item DONE 8147Use the @code{DONE} macro to end RTL generation for the pattern. The 8148only RTL insns resulting from the pattern on this occasion will be 8149those already emitted by explicit calls to @code{emit_insn} within the 8150preparation statements; the RTL template will not be generated. 8151 8152@findex FAIL 8153@item FAIL 8154Make the pattern fail on this occasion. When a pattern fails, it means 8155that the pattern was not truly available. The calling routines in the 8156compiler will try other strategies for code generation using other patterns. 8157 8158Failure is currently supported only for binary (addition, multiplication, 8159shifting, etc.) and bit-field (@code{extv}, @code{extzv}, and @code{insv}) 8160operations. 8161@end table 8162 8163If the preparation falls through (invokes neither @code{DONE} nor 8164@code{FAIL}), then the @code{define_expand} acts like a 8165@code{define_insn} in that the RTL template is used to generate the 8166insn. 8167 8168The RTL template is not used for matching, only for generating the 8169initial insn list. If the preparation statement always invokes 8170@code{DONE} or @code{FAIL}, the RTL template may be reduced to a simple 8171list of operands, such as this example: 8172 8173@smallexample 8174@group 8175(define_expand "addsi3" 8176 [(match_operand:SI 0 "register_operand" "") 8177 (match_operand:SI 1 "register_operand" "") 8178 (match_operand:SI 2 "register_operand" "")] 8179@end group 8180@group 8181 "" 8182 " 8183@{ 8184 handle_add (operands[0], operands[1], operands[2]); 8185 DONE; 8186@}") 8187@end group 8188@end smallexample 8189 8190Here is an example, the definition of left-shift for the SPUR chip: 8191 8192@smallexample 8193@group 8194(define_expand "ashlsi3" 8195 [(set (match_operand:SI 0 "register_operand" "") 8196 (ashift:SI 8197@end group 8198@group 8199 (match_operand:SI 1 "register_operand" "") 8200 (match_operand:SI 2 "nonmemory_operand" "")))] 8201 "" 8202 " 8203@end group 8204@end smallexample 8205 8206@smallexample 8207@group 8208@{ 8209 if (GET_CODE (operands[2]) != CONST_INT 8210 || (unsigned) INTVAL (operands[2]) > 3) 8211 FAIL; 8212@}") 8213@end group 8214@end smallexample 8215 8216@noindent 8217This example uses @code{define_expand} so that it can generate an RTL insn 8218for shifting when the shift-count is in the supported range of 0 to 3 but 8219fail in other cases where machine insns aren't available. When it fails, 8220the compiler tries another strategy using different patterns (such as, a 8221library call). 8222 8223If the compiler were able to handle nontrivial condition-strings in 8224patterns with names, then it would be possible to use a 8225@code{define_insn} in that case. Here is another case (zero-extension 8226on the 68000) which makes more use of the power of @code{define_expand}: 8227 8228@smallexample 8229(define_expand "zero_extendhisi2" 8230 [(set (match_operand:SI 0 "general_operand" "") 8231 (const_int 0)) 8232 (set (strict_low_part 8233 (subreg:HI 8234 (match_dup 0) 8235 0)) 8236 (match_operand:HI 1 "general_operand" ""))] 8237 "" 8238 "operands[1] = make_safe_from (operands[1], operands[0]);") 8239@end smallexample 8240 8241@noindent 8242@findex make_safe_from 8243Here two RTL insns are generated, one to clear the entire output operand 8244and the other to copy the input operand into its low half. This sequence 8245is incorrect if the input operand refers to [the old value of] the output 8246operand, so the preparation statement makes sure this isn't so. The 8247function @code{make_safe_from} copies the @code{operands[1]} into a 8248temporary register if it refers to @code{operands[0]}. It does this 8249by emitting another RTL insn. 8250 8251Finally, a third example shows the use of an internal operand. 8252Zero-extension on the SPUR chip is done by @code{and}-ing the result 8253against a halfword mask. But this mask cannot be represented by a 8254@code{const_int} because the constant value is too large to be legitimate 8255on this machine. So it must be copied into a register with 8256@code{force_reg} and then the register used in the @code{and}. 8257 8258@smallexample 8259(define_expand "zero_extendhisi2" 8260 [(set (match_operand:SI 0 "register_operand" "") 8261 (and:SI (subreg:SI 8262 (match_operand:HI 1 "register_operand" "") 8263 0) 8264 (match_dup 2)))] 8265 "" 8266 "operands[2] 8267 = force_reg (SImode, GEN_INT (65535)); ") 8268@end smallexample 8269 8270@emph{Note:} If the @code{define_expand} is used to serve a 8271standard binary or unary arithmetic operation or a bit-field operation, 8272then the last insn it generates must not be a @code{code_label}, 8273@code{barrier} or @code{note}. It must be an @code{insn}, 8274@code{jump_insn} or @code{call_insn}. If you don't need a real insn 8275at the end, emit an insn to copy the result of the operation into 8276itself. Such an insn will generate no code, but it can avoid problems 8277in the compiler. 8278 8279@end ifset 8280@ifset INTERNALS 8281@node Insn Splitting 8282@section Defining How to Split Instructions 8283@cindex insn splitting 8284@cindex instruction splitting 8285@cindex splitting instructions 8286 8287There are two cases where you should specify how to split a pattern 8288into multiple insns. On machines that have instructions requiring 8289delay slots (@pxref{Delay Slots}) or that have instructions whose 8290output is not available for multiple cycles (@pxref{Processor pipeline 8291description}), the compiler phases that optimize these cases need to 8292be able to move insns into one-instruction delay slots. However, some 8293insns may generate more than one machine instruction. These insns 8294cannot be placed into a delay slot. 8295 8296Often you can rewrite the single insn as a list of individual insns, 8297each corresponding to one machine instruction. The disadvantage of 8298doing so is that it will cause the compilation to be slower and require 8299more space. If the resulting insns are too complex, it may also 8300suppress some optimizations. The compiler splits the insn if there is a 8301reason to believe that it might improve instruction or delay slot 8302scheduling. 8303 8304The insn combiner phase also splits putative insns. If three insns are 8305merged into one insn with a complex expression that cannot be matched by 8306some @code{define_insn} pattern, the combiner phase attempts to split 8307the complex pattern into two insns that are recognized. Usually it can 8308break the complex pattern into two patterns by splitting out some 8309subexpression. However, in some other cases, such as performing an 8310addition of a large constant in two insns on a RISC machine, the way to 8311split the addition into two insns is machine-dependent. 8312 8313@findex define_split 8314The @code{define_split} definition tells the compiler how to split a 8315complex insn into several simpler insns. It looks like this: 8316 8317@smallexample 8318(define_split 8319 [@var{insn-pattern}] 8320 "@var{condition}" 8321 [@var{new-insn-pattern-1} 8322 @var{new-insn-pattern-2} 8323 @dots{}] 8324 "@var{preparation-statements}") 8325@end smallexample 8326 8327@var{insn-pattern} is a pattern that needs to be split and 8328@var{condition} is the final condition to be tested, as in a 8329@code{define_insn}. When an insn matching @var{insn-pattern} and 8330satisfying @var{condition} is found, it is replaced in the insn list 8331with the insns given by @var{new-insn-pattern-1}, 8332@var{new-insn-pattern-2}, etc. 8333 8334The @var{preparation-statements} are similar to those statements that 8335are specified for @code{define_expand} (@pxref{Expander Definitions}) 8336and are executed before the new RTL is generated to prepare for the 8337generated code or emit some insns whose pattern is not fixed. Unlike 8338those in @code{define_expand}, however, these statements must not 8339generate any new pseudo-registers. Once reload has completed, they also 8340must not allocate any space in the stack frame. 8341 8342There are two special macros defined for use in the preparation statements: 8343@code{DONE} and @code{FAIL}. Use them with a following semicolon, 8344as a statement. 8345 8346@table @code 8347 8348@findex DONE 8349@item DONE 8350Use the @code{DONE} macro to end RTL generation for the splitter. The 8351only RTL insns generated as replacement for the matched input insn will 8352be those already emitted by explicit calls to @code{emit_insn} within 8353the preparation statements; the replacement pattern is not used. 8354 8355@findex FAIL 8356@item FAIL 8357Make the @code{define_split} fail on this occasion. When a @code{define_split} 8358fails, it means that the splitter was not truly available for the inputs 8359it was given, and the input insn will not be split. 8360@end table 8361 8362If the preparation falls through (invokes neither @code{DONE} nor 8363@code{FAIL}), then the @code{define_split} uses the replacement 8364template. 8365 8366Patterns are matched against @var{insn-pattern} in two different 8367circumstances. If an insn needs to be split for delay slot scheduling 8368or insn scheduling, the insn is already known to be valid, which means 8369that it must have been matched by some @code{define_insn} and, if 8370@code{reload_completed} is nonzero, is known to satisfy the constraints 8371of that @code{define_insn}. In that case, the new insn patterns must 8372also be insns that are matched by some @code{define_insn} and, if 8373@code{reload_completed} is nonzero, must also satisfy the constraints 8374of those definitions. 8375 8376As an example of this usage of @code{define_split}, consider the following 8377example from @file{a29k.md}, which splits a @code{sign_extend} from 8378@code{HImode} to @code{SImode} into a pair of shift insns: 8379 8380@smallexample 8381(define_split 8382 [(set (match_operand:SI 0 "gen_reg_operand" "") 8383 (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))] 8384 "" 8385 [(set (match_dup 0) 8386 (ashift:SI (match_dup 1) 8387 (const_int 16))) 8388 (set (match_dup 0) 8389 (ashiftrt:SI (match_dup 0) 8390 (const_int 16)))] 8391 " 8392@{ operands[1] = gen_lowpart (SImode, operands[1]); @}") 8393@end smallexample 8394 8395When the combiner phase tries to split an insn pattern, it is always the 8396case that the pattern is @emph{not} matched by any @code{define_insn}. 8397The combiner pass first tries to split a single @code{set} expression 8398and then the same @code{set} expression inside a @code{parallel}, but 8399followed by a @code{clobber} of a pseudo-reg to use as a scratch 8400register. In these cases, the combiner expects exactly one or two new insn 8401patterns to be generated. It will verify that these patterns match some 8402@code{define_insn} definitions, so you need not do this test in the 8403@code{define_split} (of course, there is no point in writing a 8404@code{define_split} that will never produce insns that match). 8405 8406Here is an example of this use of @code{define_split}, taken from 8407@file{rs6000.md}: 8408 8409@smallexample 8410(define_split 8411 [(set (match_operand:SI 0 "gen_reg_operand" "") 8412 (plus:SI (match_operand:SI 1 "gen_reg_operand" "") 8413 (match_operand:SI 2 "non_add_cint_operand" "")))] 8414 "" 8415 [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3))) 8416 (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))] 8417" 8418@{ 8419 int low = INTVAL (operands[2]) & 0xffff; 8420 int high = (unsigned) INTVAL (operands[2]) >> 16; 8421 8422 if (low & 0x8000) 8423 high++, low |= 0xffff0000; 8424 8425 operands[3] = GEN_INT (high << 16); 8426 operands[4] = GEN_INT (low); 8427@}") 8428@end smallexample 8429 8430Here the predicate @code{non_add_cint_operand} matches any 8431@code{const_int} that is @emph{not} a valid operand of a single add 8432insn. The add with the smaller displacement is written so that it 8433can be substituted into the address of a subsequent operation. 8434 8435An example that uses a scratch register, from the same file, generates 8436an equality comparison of a register and a large constant: 8437 8438@smallexample 8439(define_split 8440 [(set (match_operand:CC 0 "cc_reg_operand" "") 8441 (compare:CC (match_operand:SI 1 "gen_reg_operand" "") 8442 (match_operand:SI 2 "non_short_cint_operand" ""))) 8443 (clobber (match_operand:SI 3 "gen_reg_operand" ""))] 8444 "find_single_use (operands[0], insn, 0) 8445 && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ 8446 || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)" 8447 [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4))) 8448 (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))] 8449 " 8450@{ 8451 /* @r{Get the constant we are comparing against, C, and see what it 8452 looks like sign-extended to 16 bits. Then see what constant 8453 could be XOR'ed with C to get the sign-extended value.} */ 8454 8455 int c = INTVAL (operands[2]); 8456 int sextc = (c << 16) >> 16; 8457 int xorv = c ^ sextc; 8458 8459 operands[4] = GEN_INT (xorv); 8460 operands[5] = GEN_INT (sextc); 8461@}") 8462@end smallexample 8463 8464To avoid confusion, don't write a single @code{define_split} that 8465accepts some insns that match some @code{define_insn} as well as some 8466insns that don't. Instead, write two separate @code{define_split} 8467definitions, one for the insns that are valid and one for the insns that 8468are not valid. 8469 8470The splitter is allowed to split jump instructions into sequence of 8471jumps or create new jumps in while splitting non-jump instructions. As 8472the control flow graph and branch prediction information needs to be updated, 8473several restriction apply. 8474 8475Splitting of jump instruction into sequence that over by another jump 8476instruction is always valid, as compiler expect identical behavior of new 8477jump. When new sequence contains multiple jump instructions or new labels, 8478more assistance is needed. Splitter is required to create only unconditional 8479jumps, or simple conditional jump instructions. Additionally it must attach a 8480@code{REG_BR_PROB} note to each conditional jump. A global variable 8481@code{split_branch_probability} holds the probability of the original branch in case 8482it was a simple conditional jump, @minus{}1 otherwise. To simplify 8483recomputing of edge frequencies, the new sequence is required to have only 8484forward jumps to the newly created labels. 8485 8486@findex define_insn_and_split 8487For the common case where the pattern of a define_split exactly matches the 8488pattern of a define_insn, use @code{define_insn_and_split}. It looks like 8489this: 8490 8491@smallexample 8492(define_insn_and_split 8493 [@var{insn-pattern}] 8494 "@var{condition}" 8495 "@var{output-template}" 8496 "@var{split-condition}" 8497 [@var{new-insn-pattern-1} 8498 @var{new-insn-pattern-2} 8499 @dots{}] 8500 "@var{preparation-statements}" 8501 [@var{insn-attributes}]) 8502 8503@end smallexample 8504 8505@var{insn-pattern}, @var{condition}, @var{output-template}, and 8506@var{insn-attributes} are used as in @code{define_insn}. The 8507@var{new-insn-pattern} vector and the @var{preparation-statements} are used as 8508in a @code{define_split}. The @var{split-condition} is also used as in 8509@code{define_split}, with the additional behavior that if the condition starts 8510with @samp{&&}, the condition used for the split will be the constructed as a 8511logical ``and'' of the split condition with the insn condition. For example, 8512from i386.md: 8513 8514@smallexample 8515(define_insn_and_split "zero_extendhisi2_and" 8516 [(set (match_operand:SI 0 "register_operand" "=r") 8517 (zero_extend:SI (match_operand:HI 1 "register_operand" "0"))) 8518 (clobber (reg:CC 17))] 8519 "TARGET_ZERO_EXTEND_WITH_AND && !optimize_size" 8520 "#" 8521 "&& reload_completed" 8522 [(parallel [(set (match_dup 0) 8523 (and:SI (match_dup 0) (const_int 65535))) 8524 (clobber (reg:CC 17))])] 8525 "" 8526 [(set_attr "type" "alu1")]) 8527 8528@end smallexample 8529 8530In this case, the actual split condition will be 8531@samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}. 8532 8533The @code{define_insn_and_split} construction provides exactly the same 8534functionality as two separate @code{define_insn} and @code{define_split} 8535patterns. It exists for compactness, and as a maintenance tool to prevent 8536having to ensure the two patterns' templates match. 8537 8538@findex define_insn_and_rewrite 8539It is sometimes useful to have a @code{define_insn_and_split} 8540that replaces specific operands of an instruction but leaves the 8541rest of the instruction pattern unchanged. You can do this directly 8542with a @code{define_insn_and_split}, but it requires a 8543@var{new-insn-pattern-1} that repeats most of the original @var{insn-pattern}. 8544There is also the complication that an implicit @code{parallel} in 8545@var{insn-pattern} must become an explicit @code{parallel} in 8546@var{new-insn-pattern-1}, which is easy to overlook. 8547A simpler alternative is to use @code{define_insn_and_rewrite}, which 8548is a form of @code{define_insn_and_split} that automatically generates 8549@var{new-insn-pattern-1} by replacing each @code{match_operand} 8550in @var{insn-pattern} with a corresponding @code{match_dup}, and each 8551@code{match_operator} in the pattern with a corresponding @code{match_op_dup}. 8552The arguments are otherwise identical to @code{define_insn_and_split}: 8553 8554@smallexample 8555(define_insn_and_rewrite 8556 [@var{insn-pattern}] 8557 "@var{condition}" 8558 "@var{output-template}" 8559 "@var{split-condition}" 8560 "@var{preparation-statements}" 8561 [@var{insn-attributes}]) 8562@end smallexample 8563 8564The @code{match_dup}s and @code{match_op_dup}s in the new 8565instruction pattern use any new operand values that the 8566@var{preparation-statements} store in the @code{operands} array, 8567as for a normal @code{define_insn_and_split}. @var{preparation-statements} 8568can also emit additional instructions before the new instruction. 8569They can even emit an entirely different sequence of instructions and 8570use @code{DONE} to avoid emitting a new form of the original 8571instruction. 8572 8573The split in a @code{define_insn_and_rewrite} is only intended 8574to apply to existing instructions that match @var{insn-pattern}. 8575@var{split-condition} must therefore start with @code{&&}, 8576so that the split condition applies on top of @var{condition}. 8577 8578Here is an example from the AArch64 SVE port, in which operand 1 is 8579known to be equivalent to an all-true constant and isn't used by the 8580output template: 8581 8582@smallexample 8583(define_insn_and_rewrite "*while_ult<GPI:mode><PRED_ALL:mode>_cc" 8584 [(set (reg:CC CC_REGNUM) 8585 (compare:CC 8586 (unspec:SI [(match_operand:PRED_ALL 1) 8587 (unspec:PRED_ALL 8588 [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ") 8589 (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")] 8590 UNSPEC_WHILE_LO)] 8591 UNSPEC_PTEST_PTRUE) 8592 (const_int 0))) 8593 (set (match_operand:PRED_ALL 0 "register_operand" "=Upa") 8594 (unspec:PRED_ALL [(match_dup 2) 8595 (match_dup 3)] 8596 UNSPEC_WHILE_LO))] 8597 "TARGET_SVE" 8598 "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3" 8599 ;; Force the compiler to drop the unused predicate operand, so that we 8600 ;; don't have an unnecessary PTRUE. 8601 "&& !CONSTANT_P (operands[1])" 8602 @{ 8603 operands[1] = CONSTM1_RTX (<MODE>mode); 8604 @} 8605) 8606@end smallexample 8607 8608The splitter in this case simply replaces operand 1 with the constant 8609value that it is known to have. The equivalent @code{define_insn_and_split} 8610would be: 8611 8612@smallexample 8613(define_insn_and_split "*while_ult<GPI:mode><PRED_ALL:mode>_cc" 8614 [(set (reg:CC CC_REGNUM) 8615 (compare:CC 8616 (unspec:SI [(match_operand:PRED_ALL 1) 8617 (unspec:PRED_ALL 8618 [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ") 8619 (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")] 8620 UNSPEC_WHILE_LO)] 8621 UNSPEC_PTEST_PTRUE) 8622 (const_int 0))) 8623 (set (match_operand:PRED_ALL 0 "register_operand" "=Upa") 8624 (unspec:PRED_ALL [(match_dup 2) 8625 (match_dup 3)] 8626 UNSPEC_WHILE_LO))] 8627 "TARGET_SVE" 8628 "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3" 8629 ;; Force the compiler to drop the unused predicate operand, so that we 8630 ;; don't have an unnecessary PTRUE. 8631 "&& !CONSTANT_P (operands[1])" 8632 [(parallel 8633 [(set (reg:CC CC_REGNUM) 8634 (compare:CC 8635 (unspec:SI [(match_dup 1) 8636 (unspec:PRED_ALL [(match_dup 2) 8637 (match_dup 3)] 8638 UNSPEC_WHILE_LO)] 8639 UNSPEC_PTEST_PTRUE) 8640 (const_int 0))) 8641 (set (match_dup 0) 8642 (unspec:PRED_ALL [(match_dup 2) 8643 (match_dup 3)] 8644 UNSPEC_WHILE_LO))])] 8645 @{ 8646 operands[1] = CONSTM1_RTX (<MODE>mode); 8647 @} 8648) 8649@end smallexample 8650 8651@end ifset 8652@ifset INTERNALS 8653@node Including Patterns 8654@section Including Patterns in Machine Descriptions. 8655@cindex insn includes 8656 8657@findex include 8658The @code{include} pattern tells the compiler tools where to 8659look for patterns that are in files other than in the file 8660@file{.md}. This is used only at build time and there is no preprocessing allowed. 8661 8662It looks like: 8663 8664@smallexample 8665 8666(include 8667 @var{pathname}) 8668@end smallexample 8669 8670For example: 8671 8672@smallexample 8673 8674(include "filestuff") 8675 8676@end smallexample 8677 8678Where @var{pathname} is a string that specifies the location of the file, 8679specifies the include file to be in @file{gcc/config/target/filestuff}. The 8680directory @file{gcc/config/target} is regarded as the default directory. 8681 8682 8683Machine descriptions may be split up into smaller more manageable subsections 8684and placed into subdirectories. 8685 8686By specifying: 8687 8688@smallexample 8689 8690(include "BOGUS/filestuff") 8691 8692@end smallexample 8693 8694the include file is specified to be in @file{gcc/config/@var{target}/BOGUS/filestuff}. 8695 8696Specifying an absolute path for the include file such as; 8697@smallexample 8698 8699(include "/u2/BOGUS/filestuff") 8700 8701@end smallexample 8702is permitted but is not encouraged. 8703 8704@subsection RTL Generation Tool Options for Directory Search 8705@cindex directory options .md 8706@cindex options, directory search 8707@cindex search options 8708 8709The @option{-I@var{dir}} option specifies directories to search for machine descriptions. 8710For example: 8711 8712@smallexample 8713 8714genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md 8715 8716@end smallexample 8717 8718 8719Add the directory @var{dir} to the head of the list of directories to be 8720searched for header files. This can be used to override a system machine definition 8721file, substituting your own version, since these directories are 8722searched before the default machine description file directories. If you use more than 8723one @option{-I} option, the directories are scanned in left-to-right 8724order; the standard default directory come after. 8725 8726 8727@end ifset 8728@ifset INTERNALS 8729@node Peephole Definitions 8730@section Machine-Specific Peephole Optimizers 8731@cindex peephole optimizer definitions 8732@cindex defining peephole optimizers 8733 8734In addition to instruction patterns the @file{md} file may contain 8735definitions of machine-specific peephole optimizations. 8736 8737The combiner does not notice certain peephole optimizations when the data 8738flow in the program does not suggest that it should try them. For example, 8739sometimes two consecutive insns related in purpose can be combined even 8740though the second one does not appear to use a register computed in the 8741first one. A machine-specific peephole optimizer can detect such 8742opportunities. 8743 8744There are two forms of peephole definitions that may be used. The 8745original @code{define_peephole} is run at assembly output time to 8746match insns and substitute assembly text. Use of @code{define_peephole} 8747is deprecated. 8748 8749A newer @code{define_peephole2} matches insns and substitutes new 8750insns. The @code{peephole2} pass is run after register allocation 8751but before scheduling, which may result in much better code for 8752targets that do scheduling. 8753 8754@menu 8755* define_peephole:: RTL to Text Peephole Optimizers 8756* define_peephole2:: RTL to RTL Peephole Optimizers 8757@end menu 8758 8759@end ifset 8760@ifset INTERNALS 8761@node define_peephole 8762@subsection RTL to Text Peephole Optimizers 8763@findex define_peephole 8764 8765@need 1000 8766A definition looks like this: 8767 8768@smallexample 8769(define_peephole 8770 [@var{insn-pattern-1} 8771 @var{insn-pattern-2} 8772 @dots{}] 8773 "@var{condition}" 8774 "@var{template}" 8775 "@var{optional-insn-attributes}") 8776@end smallexample 8777 8778@noindent 8779The last string operand may be omitted if you are not using any 8780machine-specific information in this machine description. If present, 8781it must obey the same rules as in a @code{define_insn}. 8782 8783In this skeleton, @var{insn-pattern-1} and so on are patterns to match 8784consecutive insns. The optimization applies to a sequence of insns when 8785@var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches 8786the next, and so on. 8787 8788Each of the insns matched by a peephole must also match a 8789@code{define_insn}. Peepholes are checked only at the last stage just 8790before code generation, and only optionally. Therefore, any insn which 8791would match a peephole but no @code{define_insn} will cause a crash in code 8792generation in an unoptimized compilation, or at various optimization 8793stages. 8794 8795The operands of the insns are matched with @code{match_operands}, 8796@code{match_operator}, and @code{match_dup}, as usual. What is not 8797usual is that the operand numbers apply to all the insn patterns in the 8798definition. So, you can check for identical operands in two insns by 8799using @code{match_operand} in one insn and @code{match_dup} in the 8800other. 8801 8802The operand constraints used in @code{match_operand} patterns do not have 8803any direct effect on the applicability of the peephole, but they will 8804be validated afterward, so make sure your constraints are general enough 8805to apply whenever the peephole matches. If the peephole matches 8806but the constraints are not satisfied, the compiler will crash. 8807 8808It is safe to omit constraints in all the operands of the peephole; or 8809you can write constraints which serve as a double-check on the criteria 8810previously tested. 8811 8812Once a sequence of insns matches the patterns, the @var{condition} is 8813checked. This is a C expression which makes the final decision whether to 8814perform the optimization (we do so if the expression is nonzero). If 8815@var{condition} is omitted (in other words, the string is empty) then the 8816optimization is applied to every sequence of insns that matches the 8817patterns. 8818 8819The defined peephole optimizations are applied after register allocation 8820is complete. Therefore, the peephole definition can check which 8821operands have ended up in which kinds of registers, just by looking at 8822the operands. 8823 8824@findex prev_active_insn 8825The way to refer to the operands in @var{condition} is to write 8826@code{operands[@var{i}]} for operand number @var{i} (as matched by 8827@code{(match_operand @var{i} @dots{})}). Use the variable @code{insn} 8828to refer to the last of the insns being matched; use 8829@code{prev_active_insn} to find the preceding insns. 8830 8831@findex dead_or_set_p 8832When optimizing computations with intermediate results, you can use 8833@var{condition} to match only when the intermediate results are not used 8834elsewhere. Use the C expression @code{dead_or_set_p (@var{insn}, 8835@var{op})}, where @var{insn} is the insn in which you expect the value 8836to be used for the last time (from the value of @code{insn}, together 8837with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate 8838value (from @code{operands[@var{i}]}). 8839 8840Applying the optimization means replacing the sequence of insns with one 8841new insn. The @var{template} controls ultimate output of assembler code 8842for this combined insn. It works exactly like the template of a 8843@code{define_insn}. Operand numbers in this template are the same ones 8844used in matching the original sequence of insns. 8845 8846The result of a defined peephole optimizer does not need to match any of 8847the insn patterns in the machine description; it does not even have an 8848opportunity to match them. The peephole optimizer definition itself serves 8849as the insn pattern to control how the insn is output. 8850 8851Defined peephole optimizers are run as assembler code is being output, 8852so the insns they produce are never combined or rearranged in any way. 8853 8854Here is an example, taken from the 68000 machine description: 8855 8856@smallexample 8857(define_peephole 8858 [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4))) 8859 (set (match_operand:DF 0 "register_operand" "=f") 8860 (match_operand:DF 1 "register_operand" "ad"))] 8861 "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])" 8862@{ 8863 rtx xoperands[2]; 8864 xoperands[1] = gen_rtx_REG (SImode, REGNO (operands[1]) + 1); 8865#ifdef MOTOROLA 8866 output_asm_insn ("move.l %1,(sp)", xoperands); 8867 output_asm_insn ("move.l %1,-(sp)", operands); 8868 return "fmove.d (sp)+,%0"; 8869#else 8870 output_asm_insn ("movel %1,sp@@", xoperands); 8871 output_asm_insn ("movel %1,sp@@-", operands); 8872 return "fmoved sp@@+,%0"; 8873#endif 8874@}) 8875@end smallexample 8876 8877@need 1000 8878The effect of this optimization is to change 8879 8880@smallexample 8881@group 8882jbsr _foobar 8883addql #4,sp 8884movel d1,sp@@- 8885movel d0,sp@@- 8886fmoved sp@@+,fp0 8887@end group 8888@end smallexample 8889 8890@noindent 8891into 8892 8893@smallexample 8894@group 8895jbsr _foobar 8896movel d1,sp@@ 8897movel d0,sp@@- 8898fmoved sp@@+,fp0 8899@end group 8900@end smallexample 8901 8902@ignore 8903@findex CC_REVERSED 8904If a peephole matches a sequence including one or more jump insns, you must 8905take account of the flags such as @code{CC_REVERSED} which specify that the 8906condition codes are represented in an unusual manner. The compiler 8907automatically alters any ordinary conditional jumps which occur in such 8908situations, but the compiler cannot alter jumps which have been replaced by 8909peephole optimizations. So it is up to you to alter the assembler code 8910that the peephole produces. Supply C code to write the assembler output, 8911and in this C code check the condition code status flags and change the 8912assembler code as appropriate. 8913@end ignore 8914 8915@var{insn-pattern-1} and so on look @emph{almost} like the second 8916operand of @code{define_insn}. There is one important difference: the 8917second operand of @code{define_insn} consists of one or more RTX's 8918enclosed in square brackets. Usually, there is only one: then the same 8919action can be written as an element of a @code{define_peephole}. But 8920when there are multiple actions in a @code{define_insn}, they are 8921implicitly enclosed in a @code{parallel}. Then you must explicitly 8922write the @code{parallel}, and the square brackets within it, in the 8923@code{define_peephole}. Thus, if an insn pattern looks like this, 8924 8925@smallexample 8926(define_insn "divmodsi4" 8927 [(set (match_operand:SI 0 "general_operand" "=d") 8928 (div:SI (match_operand:SI 1 "general_operand" "0") 8929 (match_operand:SI 2 "general_operand" "dmsK"))) 8930 (set (match_operand:SI 3 "general_operand" "=d") 8931 (mod:SI (match_dup 1) (match_dup 2)))] 8932 "TARGET_68020" 8933 "divsl%.l %2,%3:%0") 8934@end smallexample 8935 8936@noindent 8937then the way to mention this insn in a peephole is as follows: 8938 8939@smallexample 8940(define_peephole 8941 [@dots{} 8942 (parallel 8943 [(set (match_operand:SI 0 "general_operand" "=d") 8944 (div:SI (match_operand:SI 1 "general_operand" "0") 8945 (match_operand:SI 2 "general_operand" "dmsK"))) 8946 (set (match_operand:SI 3 "general_operand" "=d") 8947 (mod:SI (match_dup 1) (match_dup 2)))]) 8948 @dots{}] 8949 @dots{}) 8950@end smallexample 8951 8952@end ifset 8953@ifset INTERNALS 8954@node define_peephole2 8955@subsection RTL to RTL Peephole Optimizers 8956@findex define_peephole2 8957 8958The @code{define_peephole2} definition tells the compiler how to 8959substitute one sequence of instructions for another sequence, 8960what additional scratch registers may be needed and what their 8961lifetimes must be. 8962 8963@smallexample 8964(define_peephole2 8965 [@var{insn-pattern-1} 8966 @var{insn-pattern-2} 8967 @dots{}] 8968 "@var{condition}" 8969 [@var{new-insn-pattern-1} 8970 @var{new-insn-pattern-2} 8971 @dots{}] 8972 "@var{preparation-statements}") 8973@end smallexample 8974 8975The definition is almost identical to @code{define_split} 8976(@pxref{Insn Splitting}) except that the pattern to match is not a 8977single instruction, but a sequence of instructions. 8978 8979It is possible to request additional scratch registers for use in the 8980output template. If appropriate registers are not free, the pattern 8981will simply not match. 8982 8983@findex match_scratch 8984@findex match_dup 8985Scratch registers are requested with a @code{match_scratch} pattern at 8986the top level of the input pattern. The allocated register (initially) will 8987be dead at the point requested within the original sequence. If the scratch 8988is used at more than a single point, a @code{match_dup} pattern at the 8989top level of the input pattern marks the last position in the input sequence 8990at which the register must be available. 8991 8992Here is an example from the IA-32 machine description: 8993 8994@smallexample 8995(define_peephole2 8996 [(match_scratch:SI 2 "r") 8997 (parallel [(set (match_operand:SI 0 "register_operand" "") 8998 (match_operator:SI 3 "arith_or_logical_operator" 8999 [(match_dup 0) 9000 (match_operand:SI 1 "memory_operand" "")])) 9001 (clobber (reg:CC 17))])] 9002 "! optimize_size && ! TARGET_READ_MODIFY" 9003 [(set (match_dup 2) (match_dup 1)) 9004 (parallel [(set (match_dup 0) 9005 (match_op_dup 3 [(match_dup 0) (match_dup 2)])) 9006 (clobber (reg:CC 17))])] 9007 "") 9008@end smallexample 9009 9010@noindent 9011This pattern tries to split a load from its use in the hopes that we'll be 9012able to schedule around the memory load latency. It allocates a single 9013@code{SImode} register of class @code{GENERAL_REGS} (@code{"r"}) that needs 9014to be live only at the point just before the arithmetic. 9015 9016A real example requiring extended scratch lifetimes is harder to come by, 9017so here's a silly made-up example: 9018 9019@smallexample 9020(define_peephole2 9021 [(match_scratch:SI 4 "r") 9022 (set (match_operand:SI 0 "" "") (match_operand:SI 1 "" "")) 9023 (set (match_operand:SI 2 "" "") (match_dup 1)) 9024 (match_dup 4) 9025 (set (match_operand:SI 3 "" "") (match_dup 1))] 9026 "/* @r{determine 1 does not overlap 0 and 2} */" 9027 [(set (match_dup 4) (match_dup 1)) 9028 (set (match_dup 0) (match_dup 4)) 9029 (set (match_dup 2) (match_dup 4)) 9030 (set (match_dup 3) (match_dup 4))] 9031 "") 9032@end smallexample 9033 9034There are two special macros defined for use in the preparation statements: 9035@code{DONE} and @code{FAIL}. Use them with a following semicolon, 9036as a statement. 9037 9038@table @code 9039 9040@findex DONE 9041@item DONE 9042Use the @code{DONE} macro to end RTL generation for the peephole. The 9043only RTL insns generated as replacement for the matched input insn will 9044be those already emitted by explicit calls to @code{emit_insn} within 9045the preparation statements; the replacement pattern is not used. 9046 9047@findex FAIL 9048@item FAIL 9049Make the @code{define_peephole2} fail on this occasion. When a @code{define_peephole2} 9050fails, it means that the replacement was not truly available for the 9051particular inputs it was given. In that case, GCC may still apply a 9052later @code{define_peephole2} that also matches the given insn pattern. 9053(Note that this is different from @code{define_split}, where @code{FAIL} 9054prevents the input insn from being split at all.) 9055@end table 9056 9057If the preparation falls through (invokes neither @code{DONE} nor 9058@code{FAIL}), then the @code{define_peephole2} uses the replacement 9059template. 9060 9061@noindent 9062If we had not added the @code{(match_dup 4)} in the middle of the input 9063sequence, it might have been the case that the register we chose at the 9064beginning of the sequence is killed by the first or second @code{set}. 9065 9066@end ifset 9067@ifset INTERNALS 9068@node Insn Attributes 9069@section Instruction Attributes 9070@cindex insn attributes 9071@cindex instruction attributes 9072 9073In addition to describing the instruction supported by the target machine, 9074the @file{md} file also defines a group of @dfn{attributes} and a set of 9075values for each. Every generated insn is assigned a value for each attribute. 9076One possible attribute would be the effect that the insn has on the machine's 9077condition code. This attribute can then be used by @code{NOTICE_UPDATE_CC} 9078to track the condition codes. 9079 9080@menu 9081* Defining Attributes:: Specifying attributes and their values. 9082* Expressions:: Valid expressions for attribute values. 9083* Tagging Insns:: Assigning attribute values to insns. 9084* Attr Example:: An example of assigning attributes. 9085* Insn Lengths:: Computing the length of insns. 9086* Constant Attributes:: Defining attributes that are constant. 9087* Mnemonic Attribute:: Obtain the instruction mnemonic as attribute value. 9088* Delay Slots:: Defining delay slots required for a machine. 9089* Processor pipeline description:: Specifying information for insn scheduling. 9090@end menu 9091 9092@end ifset 9093@ifset INTERNALS 9094@node Defining Attributes 9095@subsection Defining Attributes and their Values 9096@cindex defining attributes and their values 9097@cindex attributes, defining 9098 9099@findex define_attr 9100The @code{define_attr} expression is used to define each attribute required 9101by the target machine. It looks like: 9102 9103@smallexample 9104(define_attr @var{name} @var{list-of-values} @var{default}) 9105@end smallexample 9106 9107@var{name} is a string specifying the name of the attribute being 9108defined. Some attributes are used in a special way by the rest of the 9109compiler. The @code{enabled} attribute can be used to conditionally 9110enable or disable insn alternatives (@pxref{Disable Insn 9111Alternatives}). The @code{predicable} attribute, together with a 9112suitable @code{define_cond_exec} (@pxref{Conditional Execution}), can 9113be used to automatically generate conditional variants of instruction 9114patterns. The @code{mnemonic} attribute can be used to check for the 9115instruction mnemonic (@pxref{Mnemonic Attribute}). The compiler 9116internally uses the names @code{ce_enabled} and @code{nonce_enabled}, 9117so they should not be used elsewhere as alternative names. 9118 9119@var{list-of-values} is either a string that specifies a comma-separated 9120list of values that can be assigned to the attribute, or a null string to 9121indicate that the attribute takes numeric values. 9122 9123@var{default} is an attribute expression that gives the value of this 9124attribute for insns that match patterns whose definition does not include 9125an explicit value for this attribute. @xref{Attr Example}, for more 9126information on the handling of defaults. @xref{Constant Attributes}, 9127for information on attributes that do not depend on any particular insn. 9128 9129@findex insn-attr.h 9130For each defined attribute, a number of definitions are written to the 9131@file{insn-attr.h} file. For cases where an explicit set of values is 9132specified for an attribute, the following are defined: 9133 9134@itemize @bullet 9135@item 9136A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}. 9137 9138@item 9139An enumerated class is defined for @samp{attr_@var{name}} with 9140elements of the form @samp{@var{upper-name}_@var{upper-value}} where 9141the attribute name and value are first converted to uppercase. 9142 9143@item 9144A function @samp{get_attr_@var{name}} is defined that is passed an insn and 9145returns the attribute value for that insn. 9146@end itemize 9147 9148For example, if the following is present in the @file{md} file: 9149 9150@smallexample 9151(define_attr "type" "branch,fp,load,store,arith" @dots{}) 9152@end smallexample 9153 9154@noindent 9155the following lines will be written to the file @file{insn-attr.h}. 9156 9157@smallexample 9158#define HAVE_ATTR_type 1 9159enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD, 9160 TYPE_STORE, TYPE_ARITH@}; 9161extern enum attr_type get_attr_type (); 9162@end smallexample 9163 9164If the attribute takes numeric values, no @code{enum} type will be 9165defined and the function to obtain the attribute's value will return 9166@code{int}. 9167 9168There are attributes which are tied to a specific meaning. These 9169attributes are not free to use for other purposes: 9170 9171@table @code 9172@item length 9173The @code{length} attribute is used to calculate the length of emitted 9174code chunks. This is especially important when verifying branch 9175distances. @xref{Insn Lengths}. 9176 9177@item enabled 9178The @code{enabled} attribute can be defined to prevent certain 9179alternatives of an insn definition from being used during code 9180generation. @xref{Disable Insn Alternatives}. 9181 9182@item mnemonic 9183The @code{mnemonic} attribute can be defined to implement instruction 9184specific checks in e.g.@: the pipeline description. 9185@xref{Mnemonic Attribute}. 9186@end table 9187 9188For each of these special attributes, the corresponding 9189@samp{HAVE_ATTR_@var{name}} @samp{#define} is also written when the 9190attribute is not defined; in that case, it is defined as @samp{0}. 9191 9192@findex define_enum_attr 9193@anchor{define_enum_attr} 9194Another way of defining an attribute is to use: 9195 9196@smallexample 9197(define_enum_attr "@var{attr}" "@var{enum}" @var{default}) 9198@end smallexample 9199 9200This works in just the same way as @code{define_attr}, except that 9201the list of values is taken from a separate enumeration called 9202@var{enum} (@pxref{define_enum}). This form allows you to use 9203the same list of values for several attributes without having to 9204repeat the list each time. For example: 9205 9206@smallexample 9207(define_enum "processor" [ 9208 model_a 9209 model_b 9210 @dots{} 9211]) 9212(define_enum_attr "arch" "processor" 9213 (const (symbol_ref "target_arch"))) 9214(define_enum_attr "tune" "processor" 9215 (const (symbol_ref "target_tune"))) 9216@end smallexample 9217 9218defines the same attributes as: 9219 9220@smallexample 9221(define_attr "arch" "model_a,model_b,@dots{}" 9222 (const (symbol_ref "target_arch"))) 9223(define_attr "tune" "model_a,model_b,@dots{}" 9224 (const (symbol_ref "target_tune"))) 9225@end smallexample 9226 9227but without duplicating the processor list. The second example defines two 9228separate C enums (@code{attr_arch} and @code{attr_tune}) whereas the first 9229defines a single C enum (@code{processor}). 9230@end ifset 9231@ifset INTERNALS 9232@node Expressions 9233@subsection Attribute Expressions 9234@cindex attribute expressions 9235 9236RTL expressions used to define attributes use the codes described above 9237plus a few specific to attribute definitions, to be discussed below. 9238Attribute value expressions must have one of the following forms: 9239 9240@table @code 9241@cindex @code{const_int} and attributes 9242@item (const_int @var{i}) 9243The integer @var{i} specifies the value of a numeric attribute. @var{i} 9244must be non-negative. 9245 9246The value of a numeric attribute can be specified either with a 9247@code{const_int}, or as an integer represented as a string in 9248@code{const_string}, @code{eq_attr} (see below), @code{attr}, 9249@code{symbol_ref}, simple arithmetic expressions, and @code{set_attr} 9250overrides on specific instructions (@pxref{Tagging Insns}). 9251 9252@cindex @code{const_string} and attributes 9253@item (const_string @var{value}) 9254The string @var{value} specifies a constant attribute value. 9255If @var{value} is specified as @samp{"*"}, it means that the default value of 9256the attribute is to be used for the insn containing this expression. 9257@samp{"*"} obviously cannot be used in the @var{default} expression 9258of a @code{define_attr}. 9259 9260If the attribute whose value is being specified is numeric, @var{value} 9261must be a string containing a non-negative integer (normally 9262@code{const_int} would be used in this case). Otherwise, it must 9263contain one of the valid values for the attribute. 9264 9265@cindex @code{if_then_else} and attributes 9266@item (if_then_else @var{test} @var{true-value} @var{false-value}) 9267@var{test} specifies an attribute test, whose format is defined below. 9268The value of this expression is @var{true-value} if @var{test} is true, 9269otherwise it is @var{false-value}. 9270 9271@cindex @code{cond} and attributes 9272@item (cond [@var{test1} @var{value1} @dots{}] @var{default}) 9273The first operand of this expression is a vector containing an even 9274number of expressions and consisting of pairs of @var{test} and @var{value} 9275expressions. The value of the @code{cond} expression is that of the 9276@var{value} corresponding to the first true @var{test} expression. If 9277none of the @var{test} expressions are true, the value of the @code{cond} 9278expression is that of the @var{default} expression. 9279@end table 9280 9281@var{test} expressions can have one of the following forms: 9282 9283@table @code 9284@cindex @code{const_int} and attribute tests 9285@item (const_int @var{i}) 9286This test is true if @var{i} is nonzero and false otherwise. 9287 9288@cindex @code{not} and attributes 9289@cindex @code{ior} and attributes 9290@cindex @code{and} and attributes 9291@item (not @var{test}) 9292@itemx (ior @var{test1} @var{test2}) 9293@itemx (and @var{test1} @var{test2}) 9294These tests are true if the indicated logical function is true. 9295 9296@cindex @code{match_operand} and attributes 9297@item (match_operand:@var{m} @var{n} @var{pred} @var{constraints}) 9298This test is true if operand @var{n} of the insn whose attribute value 9299is being determined has mode @var{m} (this part of the test is ignored 9300if @var{m} is @code{VOIDmode}) and the function specified by the string 9301@var{pred} returns a nonzero value when passed operand @var{n} and mode 9302@var{m} (this part of the test is ignored if @var{pred} is the null 9303string). 9304 9305The @var{constraints} operand is ignored and should be the null string. 9306 9307@cindex @code{match_test} and attributes 9308@item (match_test @var{c-expr}) 9309The test is true if C expression @var{c-expr} is true. In non-constant 9310attributes, @var{c-expr} has access to the following variables: 9311 9312@table @var 9313@item insn 9314The rtl instruction under test. 9315@item which_alternative 9316The @code{define_insn} alternative that @var{insn} matches. 9317@xref{Output Statement}. 9318@item operands 9319An array of @var{insn}'s rtl operands. 9320@end table 9321 9322@var{c-expr} behaves like the condition in a C @code{if} statement, 9323so there is no need to explicitly convert the expression into a boolean 93240 or 1 value. For example, the following two tests are equivalent: 9325 9326@smallexample 9327(match_test "x & 2") 9328(match_test "(x & 2) != 0") 9329@end smallexample 9330 9331@cindex @code{le} and attributes 9332@cindex @code{leu} and attributes 9333@cindex @code{lt} and attributes 9334@cindex @code{gt} and attributes 9335@cindex @code{gtu} and attributes 9336@cindex @code{ge} and attributes 9337@cindex @code{geu} and attributes 9338@cindex @code{ne} and attributes 9339@cindex @code{eq} and attributes 9340@cindex @code{plus} and attributes 9341@cindex @code{minus} and attributes 9342@cindex @code{mult} and attributes 9343@cindex @code{div} and attributes 9344@cindex @code{mod} and attributes 9345@cindex @code{abs} and attributes 9346@cindex @code{neg} and attributes 9347@cindex @code{ashift} and attributes 9348@cindex @code{lshiftrt} and attributes 9349@cindex @code{ashiftrt} and attributes 9350@item (le @var{arith1} @var{arith2}) 9351@itemx (leu @var{arith1} @var{arith2}) 9352@itemx (lt @var{arith1} @var{arith2}) 9353@itemx (ltu @var{arith1} @var{arith2}) 9354@itemx (gt @var{arith1} @var{arith2}) 9355@itemx (gtu @var{arith1} @var{arith2}) 9356@itemx (ge @var{arith1} @var{arith2}) 9357@itemx (geu @var{arith1} @var{arith2}) 9358@itemx (ne @var{arith1} @var{arith2}) 9359@itemx (eq @var{arith1} @var{arith2}) 9360These tests are true if the indicated comparison of the two arithmetic 9361expressions is true. Arithmetic expressions are formed with 9362@code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod}, 9363@code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not}, 9364@code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions. 9365 9366@findex get_attr 9367@code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn 9368Lengths},for additional forms). @code{symbol_ref} is a string 9369denoting a C expression that yields an @code{int} when evaluated by the 9370@samp{get_attr_@dots{}} routine. It should normally be a global 9371variable. 9372 9373@findex eq_attr 9374@item (eq_attr @var{name} @var{value}) 9375@var{name} is a string specifying the name of an attribute. 9376 9377@var{value} is a string that is either a valid value for attribute 9378@var{name}, a comma-separated list of values, or @samp{!} followed by a 9379value or list. If @var{value} does not begin with a @samp{!}, this 9380test is true if the value of the @var{name} attribute of the current 9381insn is in the list specified by @var{value}. If @var{value} begins 9382with a @samp{!}, this test is true if the attribute's value is 9383@emph{not} in the specified list. 9384 9385For example, 9386 9387@smallexample 9388(eq_attr "type" "load,store") 9389@end smallexample 9390 9391@noindent 9392is equivalent to 9393 9394@smallexample 9395(ior (eq_attr "type" "load") (eq_attr "type" "store")) 9396@end smallexample 9397 9398If @var{name} specifies an attribute of @samp{alternative}, it refers to the 9399value of the compiler variable @code{which_alternative} 9400(@pxref{Output Statement}) and the values must be small integers. For 9401example, 9402 9403@smallexample 9404(eq_attr "alternative" "2,3") 9405@end smallexample 9406 9407@noindent 9408is equivalent to 9409 9410@smallexample 9411(ior (eq (symbol_ref "which_alternative") (const_int 2)) 9412 (eq (symbol_ref "which_alternative") (const_int 3))) 9413@end smallexample 9414 9415Note that, for most attributes, an @code{eq_attr} test is simplified in cases 9416where the value of the attribute being tested is known for all insns matching 9417a particular pattern. This is by far the most common case. 9418 9419@findex attr_flag 9420@item (attr_flag @var{name}) 9421The value of an @code{attr_flag} expression is true if the flag 9422specified by @var{name} is true for the @code{insn} currently being 9423scheduled. 9424 9425@var{name} is a string specifying one of a fixed set of flags to test. 9426Test the flags @code{forward} and @code{backward} to determine the 9427direction of a conditional branch. 9428 9429This example describes a conditional branch delay slot which 9430can be nullified for forward branches that are taken (annul-true) or 9431for backward branches which are not taken (annul-false). 9432 9433@smallexample 9434(define_delay (eq_attr "type" "cbranch") 9435 [(eq_attr "in_branch_delay" "true") 9436 (and (eq_attr "in_branch_delay" "true") 9437 (attr_flag "forward")) 9438 (and (eq_attr "in_branch_delay" "true") 9439 (attr_flag "backward"))]) 9440@end smallexample 9441 9442The @code{forward} and @code{backward} flags are false if the current 9443@code{insn} being scheduled is not a conditional branch. 9444 9445@code{attr_flag} is only used during delay slot scheduling and has no 9446meaning to other passes of the compiler. 9447 9448@findex attr 9449@item (attr @var{name}) 9450The value of another attribute is returned. This is most useful 9451for numeric attributes, as @code{eq_attr} and @code{attr_flag} 9452produce more efficient code for non-numeric attributes. 9453@end table 9454 9455@end ifset 9456@ifset INTERNALS 9457@node Tagging Insns 9458@subsection Assigning Attribute Values to Insns 9459@cindex tagging insns 9460@cindex assigning attribute values to insns 9461 9462The value assigned to an attribute of an insn is primarily determined by 9463which pattern is matched by that insn (or which @code{define_peephole} 9464generated it). Every @code{define_insn} and @code{define_peephole} can 9465have an optional last argument to specify the values of attributes for 9466matching insns. The value of any attribute not specified in a particular 9467insn is set to the default value for that attribute, as specified in its 9468@code{define_attr}. Extensive use of default values for attributes 9469permits the specification of the values for only one or two attributes 9470in the definition of most insn patterns, as seen in the example in the 9471next section. 9472 9473The optional last argument of @code{define_insn} and 9474@code{define_peephole} is a vector of expressions, each of which defines 9475the value for a single attribute. The most general way of assigning an 9476attribute's value is to use a @code{set} expression whose first operand is an 9477@code{attr} expression giving the name of the attribute being set. The 9478second operand of the @code{set} is an attribute expression 9479(@pxref{Expressions}) giving the value of the attribute. 9480 9481When the attribute value depends on the @samp{alternative} attribute 9482(i.e., which is the applicable alternative in the constraint of the 9483insn), the @code{set_attr_alternative} expression can be used. It 9484allows the specification of a vector of attribute expressions, one for 9485each alternative. 9486 9487@findex set_attr 9488When the generality of arbitrary attribute expressions is not required, 9489the simpler @code{set_attr} expression can be used, which allows 9490specifying a string giving either a single attribute value or a list 9491of attribute values, one for each alternative. 9492 9493The form of each of the above specifications is shown below. In each case, 9494@var{name} is a string specifying the attribute to be set. 9495 9496@table @code 9497@item (set_attr @var{name} @var{value-string}) 9498@var{value-string} is either a string giving the desired attribute value, 9499or a string containing a comma-separated list giving the values for 9500succeeding alternatives. The number of elements must match the number 9501of alternatives in the constraint of the insn pattern. 9502 9503Note that it may be useful to specify @samp{*} for some alternative, in 9504which case the attribute will assume its default value for insns matching 9505that alternative. 9506 9507@findex set_attr_alternative 9508@item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}]) 9509Depending on the alternative of the insn, the value will be one of the 9510specified values. This is a shorthand for using a @code{cond} with 9511tests on the @samp{alternative} attribute. 9512 9513@findex attr 9514@item (set (attr @var{name}) @var{value}) 9515The first operand of this @code{set} must be the special RTL expression 9516@code{attr}, whose sole operand is a string giving the name of the 9517attribute being set. @var{value} is the value of the attribute. 9518@end table 9519 9520The following shows three different ways of representing the same 9521attribute value specification: 9522 9523@smallexample 9524(set_attr "type" "load,store,arith") 9525 9526(set_attr_alternative "type" 9527 [(const_string "load") (const_string "store") 9528 (const_string "arith")]) 9529 9530(set (attr "type") 9531 (cond [(eq_attr "alternative" "1") (const_string "load") 9532 (eq_attr "alternative" "2") (const_string "store")] 9533 (const_string "arith"))) 9534@end smallexample 9535 9536@need 1000 9537@findex define_asm_attributes 9538The @code{define_asm_attributes} expression provides a mechanism to 9539specify the attributes assigned to insns produced from an @code{asm} 9540statement. It has the form: 9541 9542@smallexample 9543(define_asm_attributes [@var{attr-sets}]) 9544@end smallexample 9545 9546@noindent 9547where @var{attr-sets} is specified the same as for both the 9548@code{define_insn} and the @code{define_peephole} expressions. 9549 9550These values will typically be the ``worst case'' attribute values. For 9551example, they might indicate that the condition code will be clobbered. 9552 9553A specification for a @code{length} attribute is handled specially. The 9554way to compute the length of an @code{asm} insn is to multiply the 9555length specified in the expression @code{define_asm_attributes} by the 9556number of machine instructions specified in the @code{asm} statement, 9557determined by counting the number of semicolons and newlines in the 9558string. Therefore, the value of the @code{length} attribute specified 9559in a @code{define_asm_attributes} should be the maximum possible length 9560of a single machine instruction. 9561 9562@end ifset 9563@ifset INTERNALS 9564@node Attr Example 9565@subsection Example of Attribute Specifications 9566@cindex attribute specifications example 9567@cindex attribute specifications 9568 9569The judicious use of defaulting is important in the efficient use of 9570insn attributes. Typically, insns are divided into @dfn{types} and an 9571attribute, customarily called @code{type}, is used to represent this 9572value. This attribute is normally used only to define the default value 9573for other attributes. An example will clarify this usage. 9574 9575Assume we have a RISC machine with a condition code and in which only 9576full-word operations are performed in registers. Let us assume that we 9577can divide all insns into loads, stores, (integer) arithmetic 9578operations, floating point operations, and branches. 9579 9580Here we will concern ourselves with determining the effect of an insn on 9581the condition code and will limit ourselves to the following possible 9582effects: The condition code can be set unpredictably (clobbered), not 9583be changed, be set to agree with the results of the operation, or only 9584changed if the item previously set into the condition code has been 9585modified. 9586 9587Here is part of a sample @file{md} file for such a machine: 9588 9589@smallexample 9590(define_attr "type" "load,store,arith,fp,branch" (const_string "arith")) 9591 9592(define_attr "cc" "clobber,unchanged,set,change0" 9593 (cond [(eq_attr "type" "load") 9594 (const_string "change0") 9595 (eq_attr "type" "store,branch") 9596 (const_string "unchanged") 9597 (eq_attr "type" "arith") 9598 (if_then_else (match_operand:SI 0 "" "") 9599 (const_string "set") 9600 (const_string "clobber"))] 9601 (const_string "clobber"))) 9602 9603(define_insn "" 9604 [(set (match_operand:SI 0 "general_operand" "=r,r,m") 9605 (match_operand:SI 1 "general_operand" "r,m,r"))] 9606 "" 9607 "@@ 9608 move %0,%1 9609 load %0,%1 9610 store %0,%1" 9611 [(set_attr "type" "arith,load,store")]) 9612@end smallexample 9613 9614Note that we assume in the above example that arithmetic operations 9615performed on quantities smaller than a machine word clobber the condition 9616code since they will set the condition code to a value corresponding to the 9617full-word result. 9618 9619@end ifset 9620@ifset INTERNALS 9621@node Insn Lengths 9622@subsection Computing the Length of an Insn 9623@cindex insn lengths, computing 9624@cindex computing the length of an insn 9625 9626For many machines, multiple types of branch instructions are provided, each 9627for different length branch displacements. In most cases, the assembler 9628will choose the correct instruction to use. However, when the assembler 9629cannot do so, GCC can when a special attribute, the @code{length} 9630attribute, is defined. This attribute must be defined to have numeric 9631values by specifying a null string in its @code{define_attr}. 9632 9633In the case of the @code{length} attribute, two additional forms of 9634arithmetic terms are allowed in test expressions: 9635 9636@table @code 9637@cindex @code{match_dup} and attributes 9638@item (match_dup @var{n}) 9639This refers to the address of operand @var{n} of the current insn, which 9640must be a @code{label_ref}. 9641 9642@cindex @code{pc} and attributes 9643@item (pc) 9644For non-branch instructions and backward branch instructions, this refers 9645to the address of the current insn. But for forward branch instructions, 9646this refers to the address of the next insn, because the length of the 9647current insn is to be computed. 9648@end table 9649 9650@cindex @code{addr_vec}, length of 9651@cindex @code{addr_diff_vec}, length of 9652For normal insns, the length will be determined by value of the 9653@code{length} attribute. In the case of @code{addr_vec} and 9654@code{addr_diff_vec} insn patterns, the length is computed as 9655the number of vectors multiplied by the size of each vector. 9656 9657Lengths are measured in addressable storage units (bytes). 9658 9659Note that it is possible to call functions via the @code{symbol_ref} 9660mechanism to compute the length of an insn. However, if you use this 9661mechanism you must provide dummy clauses to express the maximum length 9662without using the function call. You can an example of this in the 9663@code{pa} machine description for the @code{call_symref} pattern. 9664 9665The following macros can be used to refine the length computation: 9666 9667@table @code 9668@findex ADJUST_INSN_LENGTH 9669@item ADJUST_INSN_LENGTH (@var{insn}, @var{length}) 9670If defined, modifies the length assigned to instruction @var{insn} as a 9671function of the context in which it is used. @var{length} is an lvalue 9672that contains the initially computed length of the insn and should be 9673updated with the correct length of the insn. 9674 9675This macro will normally not be required. A case in which it is 9676required is the ROMP@. On this machine, the size of an @code{addr_vec} 9677insn must be increased by two to compensate for the fact that alignment 9678may be required. 9679@end table 9680 9681@findex get_attr_length 9682The routine that returns @code{get_attr_length} (the value of the 9683@code{length} attribute) can be used by the output routine to 9684determine the form of the branch instruction to be written, as the 9685example below illustrates. 9686 9687As an example of the specification of variable-length branches, consider 9688the IBM 360. If we adopt the convention that a register will be set to 9689the starting address of a function, we can jump to labels within 4k of 9690the start using a four-byte instruction. Otherwise, we need a six-byte 9691sequence to load the address from memory and then branch to it. 9692 9693On such a machine, a pattern for a branch instruction might be specified 9694as follows: 9695 9696@smallexample 9697(define_insn "jump" 9698 [(set (pc) 9699 (label_ref (match_operand 0 "" "")))] 9700 "" 9701@{ 9702 return (get_attr_length (insn) == 4 9703 ? "b %l0" : "l r15,=a(%l0); br r15"); 9704@} 9705 [(set (attr "length") 9706 (if_then_else (lt (match_dup 0) (const_int 4096)) 9707 (const_int 4) 9708 (const_int 6)))]) 9709@end smallexample 9710 9711@end ifset 9712@ifset INTERNALS 9713@node Constant Attributes 9714@subsection Constant Attributes 9715@cindex constant attributes 9716 9717A special form of @code{define_attr}, where the expression for the 9718default value is a @code{const} expression, indicates an attribute that 9719is constant for a given run of the compiler. Constant attributes may be 9720used to specify which variety of processor is used. For example, 9721 9722@smallexample 9723(define_attr "cpu" "m88100,m88110,m88000" 9724 (const 9725 (cond [(symbol_ref "TARGET_88100") (const_string "m88100") 9726 (symbol_ref "TARGET_88110") (const_string "m88110")] 9727 (const_string "m88000")))) 9728 9729(define_attr "memory" "fast,slow" 9730 (const 9731 (if_then_else (symbol_ref "TARGET_FAST_MEM") 9732 (const_string "fast") 9733 (const_string "slow")))) 9734@end smallexample 9735 9736The routine generated for constant attributes has no parameters as it 9737does not depend on any particular insn. RTL expressions used to define 9738the value of a constant attribute may use the @code{symbol_ref} form, 9739but may not use either the @code{match_operand} form or @code{eq_attr} 9740forms involving insn attributes. 9741 9742@end ifset 9743@ifset INTERNALS 9744@node Mnemonic Attribute 9745@subsection Mnemonic Attribute 9746@cindex mnemonic attribute 9747 9748The @code{mnemonic} attribute is a string type attribute holding the 9749instruction mnemonic for an insn alternative. The attribute values 9750will automatically be generated by the machine description parser if 9751there is an attribute definition in the md file: 9752 9753@smallexample 9754(define_attr "mnemonic" "unknown" (const_string "unknown")) 9755@end smallexample 9756 9757The default value can be freely chosen as long as it does not collide 9758with any of the instruction mnemonics. This value will be used 9759whenever the machine description parser is not able to determine the 9760mnemonic string. This might be the case for output templates 9761containing more than a single instruction as in 9762@code{"mvcle\t%0,%1,0\;jo\t.-4"}. 9763 9764The @code{mnemonic} attribute set is not generated automatically if the 9765instruction string is generated via C code. 9766 9767An existing @code{mnemonic} attribute set in an insn definition will not 9768be overriden by the md file parser. That way it is possible to 9769manually set the instruction mnemonics for the cases where the md file 9770parser fails to determine it automatically. 9771 9772The @code{mnemonic} attribute is useful for dealing with instruction 9773specific properties in the pipeline description without defining 9774additional insn attributes. 9775 9776@smallexample 9777(define_attr "ooo_expanded" "" 9778 (cond [(eq_attr "mnemonic" "dlr,dsgr,d,dsgf,stam,dsgfr,dlgr") 9779 (const_int 1)] 9780 (const_int 0))) 9781@end smallexample 9782 9783@end ifset 9784@ifset INTERNALS 9785@node Delay Slots 9786@subsection Delay Slot Scheduling 9787@cindex delay slots, defining 9788 9789The insn attribute mechanism can be used to specify the requirements for 9790delay slots, if any, on a target machine. An instruction is said to 9791require a @dfn{delay slot} if some instructions that are physically 9792after the instruction are executed as if they were located before it. 9793Classic examples are branch and call instructions, which often execute 9794the following instruction before the branch or call is performed. 9795 9796On some machines, conditional branch instructions can optionally 9797@dfn{annul} instructions in the delay slot. This means that the 9798instruction will not be executed for certain branch outcomes. Both 9799instructions that annul if the branch is true and instructions that 9800annul if the branch is false are supported. 9801 9802Delay slot scheduling differs from instruction scheduling in that 9803determining whether an instruction needs a delay slot is dependent only 9804on the type of instruction being generated, not on data flow between the 9805instructions. See the next section for a discussion of data-dependent 9806instruction scheduling. 9807 9808@findex define_delay 9809The requirement of an insn needing one or more delay slots is indicated 9810via the @code{define_delay} expression. It has the following form: 9811 9812@smallexample 9813(define_delay @var{test} 9814 [@var{delay-1} @var{annul-true-1} @var{annul-false-1} 9815 @var{delay-2} @var{annul-true-2} @var{annul-false-2} 9816 @dots{}]) 9817@end smallexample 9818 9819@var{test} is an attribute test that indicates whether this 9820@code{define_delay} applies to a particular insn. If so, the number of 9821required delay slots is determined by the length of the vector specified 9822as the second argument. An insn placed in delay slot @var{n} must 9823satisfy attribute test @var{delay-n}. @var{annul-true-n} is an 9824attribute test that specifies which insns may be annulled if the branch 9825is true. Similarly, @var{annul-false-n} specifies which insns in the 9826delay slot may be annulled if the branch is false. If annulling is not 9827supported for that delay slot, @code{(nil)} should be coded. 9828 9829For example, in the common case where branch and call insns require 9830a single delay slot, which may contain any insn other than a branch or 9831call, the following would be placed in the @file{md} file: 9832 9833@smallexample 9834(define_delay (eq_attr "type" "branch,call") 9835 [(eq_attr "type" "!branch,call") (nil) (nil)]) 9836@end smallexample 9837 9838Multiple @code{define_delay} expressions may be specified. In this 9839case, each such expression specifies different delay slot requirements 9840and there must be no insn for which tests in two @code{define_delay} 9841expressions are both true. 9842 9843For example, if we have a machine that requires one delay slot for branches 9844but two for calls, no delay slot can contain a branch or call insn, 9845and any valid insn in the delay slot for the branch can be annulled if the 9846branch is true, we might represent this as follows: 9847 9848@smallexample 9849(define_delay (eq_attr "type" "branch") 9850 [(eq_attr "type" "!branch,call") 9851 (eq_attr "type" "!branch,call") 9852 (nil)]) 9853 9854(define_delay (eq_attr "type" "call") 9855 [(eq_attr "type" "!branch,call") (nil) (nil) 9856 (eq_attr "type" "!branch,call") (nil) (nil)]) 9857@end smallexample 9858@c the above is *still* too long. --mew 4feb93 9859 9860@end ifset 9861@ifset INTERNALS 9862@node Processor pipeline description 9863@subsection Specifying processor pipeline description 9864@cindex processor pipeline description 9865@cindex processor functional units 9866@cindex instruction latency time 9867@cindex interlock delays 9868@cindex data dependence delays 9869@cindex reservation delays 9870@cindex pipeline hazard recognizer 9871@cindex automaton based pipeline description 9872@cindex regular expressions 9873@cindex deterministic finite state automaton 9874@cindex automaton based scheduler 9875@cindex RISC 9876@cindex VLIW 9877 9878To achieve better performance, most modern processors 9879(super-pipelined, superscalar @acronym{RISC}, and @acronym{VLIW} 9880processors) have many @dfn{functional units} on which several 9881instructions can be executed simultaneously. An instruction starts 9882execution if its issue conditions are satisfied. If not, the 9883instruction is stalled until its conditions are satisfied. Such 9884@dfn{interlock (pipeline) delay} causes interruption of the fetching 9885of successor instructions (or demands nop instructions, e.g.@: for some 9886MIPS processors). 9887 9888There are two major kinds of interlock delays in modern processors. 9889The first one is a data dependence delay determining @dfn{instruction 9890latency time}. The instruction execution is not started until all 9891source data have been evaluated by prior instructions (there are more 9892complex cases when the instruction execution starts even when the data 9893are not available but will be ready in given time after the 9894instruction execution start). Taking the data dependence delays into 9895account is simple. The data dependence (true, output, and 9896anti-dependence) delay between two instructions is given by a 9897constant. In most cases this approach is adequate. The second kind 9898of interlock delays is a reservation delay. The reservation delay 9899means that two instructions under execution will be in need of shared 9900processors resources, i.e.@: buses, internal registers, and/or 9901functional units, which are reserved for some time. Taking this kind 9902of delay into account is complex especially for modern @acronym{RISC} 9903processors. 9904 9905The task of exploiting more processor parallelism is solved by an 9906instruction scheduler. For a better solution to this problem, the 9907instruction scheduler has to have an adequate description of the 9908processor parallelism (or @dfn{pipeline description}). GCC 9909machine descriptions describe processor parallelism and functional 9910unit reservations for groups of instructions with the aid of 9911@dfn{regular expressions}. 9912 9913The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to 9914figure out the possibility of the instruction issue by the processor 9915on a given simulated processor cycle. The pipeline hazard recognizer is 9916automatically generated from the processor pipeline description. The 9917pipeline hazard recognizer generated from the machine description 9918is based on a deterministic finite state automaton (@acronym{DFA}): 9919the instruction issue is possible if there is a transition from one 9920automaton state to another one. This algorithm is very fast, and 9921furthermore, its speed is not dependent on processor 9922complexity@footnote{However, the size of the automaton depends on 9923processor complexity. To limit this effect, machine descriptions 9924can split orthogonal parts of the machine description among several 9925automata: but then, since each of these must be stepped independently, 9926this does cause a small decrease in the algorithm's performance.}. 9927 9928@cindex automaton based pipeline description 9929The rest of this section describes the directives that constitute 9930an automaton-based processor pipeline description. The order of 9931these constructions within the machine description file is not 9932important. 9933 9934@findex define_automaton 9935@cindex pipeline hazard recognizer 9936The following optional construction describes names of automata 9937generated and used for the pipeline hazards recognition. Sometimes 9938the generated finite state automaton used by the pipeline hazard 9939recognizer is large. If we use more than one automaton and bind functional 9940units to the automata, the total size of the automata is usually 9941less than the size of the single automaton. If there is no one such 9942construction, only one finite state automaton is generated. 9943 9944@smallexample 9945(define_automaton @var{automata-names}) 9946@end smallexample 9947 9948@var{automata-names} is a string giving names of the automata. The 9949names are separated by commas. All the automata should have unique names. 9950The automaton name is used in the constructions @code{define_cpu_unit} and 9951@code{define_query_cpu_unit}. 9952 9953@findex define_cpu_unit 9954@cindex processor functional units 9955Each processor functional unit used in the description of instruction 9956reservations should be described by the following construction. 9957 9958@smallexample 9959(define_cpu_unit @var{unit-names} [@var{automaton-name}]) 9960@end smallexample 9961 9962@var{unit-names} is a string giving the names of the functional units 9963separated by commas. Don't use name @samp{nothing}, it is reserved 9964for other goals. 9965 9966@var{automaton-name} is a string giving the name of the automaton with 9967which the unit is bound. The automaton should be described in 9968construction @code{define_automaton}. You should give 9969@dfn{automaton-name}, if there is a defined automaton. 9970 9971The assignment of units to automata are constrained by the uses of the 9972units in insn reservations. The most important constraint is: if a 9973unit reservation is present on a particular cycle of an alternative 9974for an insn reservation, then some unit from the same automaton must 9975be present on the same cycle for the other alternatives of the insn 9976reservation. The rest of the constraints are mentioned in the 9977description of the subsequent constructions. 9978 9979@findex define_query_cpu_unit 9980@cindex querying function unit reservations 9981The following construction describes CPU functional units analogously 9982to @code{define_cpu_unit}. The reservation of such units can be 9983queried for an automaton state. The instruction scheduler never 9984queries reservation of functional units for given automaton state. So 9985as a rule, you don't need this construction. This construction could 9986be used for future code generation goals (e.g.@: to generate 9987@acronym{VLIW} insn templates). 9988 9989@smallexample 9990(define_query_cpu_unit @var{unit-names} [@var{automaton-name}]) 9991@end smallexample 9992 9993@var{unit-names} is a string giving names of the functional units 9994separated by commas. 9995 9996@var{automaton-name} is a string giving the name of the automaton with 9997which the unit is bound. 9998 9999@findex define_insn_reservation 10000@cindex instruction latency time 10001@cindex regular expressions 10002@cindex data bypass 10003The following construction is the major one to describe pipeline 10004characteristics of an instruction. 10005 10006@smallexample 10007(define_insn_reservation @var{insn-name} @var{default_latency} 10008 @var{condition} @var{regexp}) 10009@end smallexample 10010 10011@var{default_latency} is a number giving latency time of the 10012instruction. There is an important difference between the old 10013description and the automaton based pipeline description. The latency 10014time is used for all dependencies when we use the old description. In 10015the automaton based pipeline description, the given latency time is only 10016used for true dependencies. The cost of anti-dependencies is always 10017zero and the cost of output dependencies is the difference between 10018latency times of the producing and consuming insns (if the difference 10019is negative, the cost is considered to be zero). You can always 10020change the default costs for any description by using the target hook 10021@code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}). 10022 10023@var{insn-name} is a string giving the internal name of the insn. The 10024internal names are used in constructions @code{define_bypass} and in 10025the automaton description file generated for debugging. The internal 10026name has nothing in common with the names in @code{define_insn}. It is a 10027good practice to use insn classes described in the processor manual. 10028 10029@var{condition} defines what RTL insns are described by this 10030construction. You should remember that you will be in trouble if 10031@var{condition} for two or more different 10032@code{define_insn_reservation} constructions is TRUE for an insn. In 10033this case what reservation will be used for the insn is not defined. 10034Such cases are not checked during generation of the pipeline hazards 10035recognizer because in general recognizing that two conditions may have 10036the same value is quite difficult (especially if the conditions 10037contain @code{symbol_ref}). It is also not checked during the 10038pipeline hazard recognizer work because it would slow down the 10039recognizer considerably. 10040 10041@var{regexp} is a string describing the reservation of the cpu's functional 10042units by the instruction. The reservations are described by a regular 10043expression according to the following syntax: 10044 10045@smallexample 10046 regexp = regexp "," oneof 10047 | oneof 10048 10049 oneof = oneof "|" allof 10050 | allof 10051 10052 allof = allof "+" repeat 10053 | repeat 10054 10055 repeat = element "*" number 10056 | element 10057 10058 element = cpu_function_unit_name 10059 | reservation_name 10060 | result_name 10061 | "nothing" 10062 | "(" regexp ")" 10063@end smallexample 10064 10065@itemize @bullet 10066@item 10067@samp{,} is used for describing the start of the next cycle in 10068the reservation. 10069 10070@item 10071@samp{|} is used for describing a reservation described by the first 10072regular expression @strong{or} a reservation described by the second 10073regular expression @strong{or} etc. 10074 10075@item 10076@samp{+} is used for describing a reservation described by the first 10077regular expression @strong{and} a reservation described by the 10078second regular expression @strong{and} etc. 10079 10080@item 10081@samp{*} is used for convenience and simply means a sequence in which 10082the regular expression are repeated @var{number} times with cycle 10083advancing (see @samp{,}). 10084 10085@item 10086@samp{cpu_function_unit_name} denotes reservation of the named 10087functional unit. 10088 10089@item 10090@samp{reservation_name} --- see description of construction 10091@samp{define_reservation}. 10092 10093@item 10094@samp{nothing} denotes no unit reservations. 10095@end itemize 10096 10097@findex define_reservation 10098Sometimes unit reservations for different insns contain common parts. 10099In such case, you can simplify the pipeline description by describing 10100the common part by the following construction 10101 10102@smallexample 10103(define_reservation @var{reservation-name} @var{regexp}) 10104@end smallexample 10105 10106@var{reservation-name} is a string giving name of @var{regexp}. 10107Functional unit names and reservation names are in the same name 10108space. So the reservation names should be different from the 10109functional unit names and cannot be the reserved name @samp{nothing}. 10110 10111@findex define_bypass 10112@cindex instruction latency time 10113@cindex data bypass 10114The following construction is used to describe exceptions in the 10115latency time for given instruction pair. This is so called bypasses. 10116 10117@smallexample 10118(define_bypass @var{number} @var{out_insn_names} @var{in_insn_names} 10119 [@var{guard}]) 10120@end smallexample 10121 10122@var{number} defines when the result generated by the instructions 10123given in string @var{out_insn_names} will be ready for the 10124instructions given in string @var{in_insn_names}. Each of these 10125strings is a comma-separated list of filename-style globs and 10126they refer to the names of @code{define_insn_reservation}s. 10127For example: 10128@smallexample 10129(define_bypass 1 "cpu1_load_*, cpu1_store_*" "cpu1_load_*") 10130@end smallexample 10131defines a bypass between instructions that start with 10132@samp{cpu1_load_} or @samp{cpu1_store_} and those that start with 10133@samp{cpu1_load_}. 10134 10135@var{guard} is an optional string giving the name of a C function which 10136defines an additional guard for the bypass. The function will get the 10137two insns as parameters. If the function returns zero the bypass will 10138be ignored for this case. The additional guard is necessary to 10139recognize complicated bypasses, e.g.@: when the consumer is only an address 10140of insn @samp{store} (not a stored value). 10141 10142If there are more one bypass with the same output and input insns, the 10143chosen bypass is the first bypass with a guard in description whose 10144guard function returns nonzero. If there is no such bypass, then 10145bypass without the guard function is chosen. 10146 10147@findex exclusion_set 10148@findex presence_set 10149@findex final_presence_set 10150@findex absence_set 10151@findex final_absence_set 10152@cindex VLIW 10153@cindex RISC 10154The following five constructions are usually used to describe 10155@acronym{VLIW} processors, or more precisely, to describe a placement 10156of small instructions into @acronym{VLIW} instruction slots. They 10157can be used for @acronym{RISC} processors, too. 10158 10159@smallexample 10160(exclusion_set @var{unit-names} @var{unit-names}) 10161(presence_set @var{unit-names} @var{patterns}) 10162(final_presence_set @var{unit-names} @var{patterns}) 10163(absence_set @var{unit-names} @var{patterns}) 10164(final_absence_set @var{unit-names} @var{patterns}) 10165@end smallexample 10166 10167@var{unit-names} is a string giving names of functional units 10168separated by commas. 10169 10170@var{patterns} is a string giving patterns of functional units 10171separated by comma. Currently pattern is one unit or units 10172separated by white-spaces. 10173 10174The first construction (@samp{exclusion_set}) means that each 10175functional unit in the first string cannot be reserved simultaneously 10176with a unit whose name is in the second string and vice versa. For 10177example, the construction is useful for describing processors 10178(e.g.@: some SPARC processors) with a fully pipelined floating point 10179functional unit which can execute simultaneously only single floating 10180point insns or only double floating point insns. 10181 10182The second construction (@samp{presence_set}) means that each 10183functional unit in the first string cannot be reserved unless at 10184least one of pattern of units whose names are in the second string is 10185reserved. This is an asymmetric relation. For example, it is useful 10186for description that @acronym{VLIW} @samp{slot1} is reserved after 10187@samp{slot0} reservation. We could describe it by the following 10188construction 10189 10190@smallexample 10191(presence_set "slot1" "slot0") 10192@end smallexample 10193 10194Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0} 10195reservation. In this case we could write 10196 10197@smallexample 10198(presence_set "slot1" "slot0 b0") 10199@end smallexample 10200 10201The third construction (@samp{final_presence_set}) is analogous to 10202@samp{presence_set}. The difference between them is when checking is 10203done. When an instruction is issued in given automaton state 10204reflecting all current and planned unit reservations, the automaton 10205state is changed. The first state is a source state, the second one 10206is a result state. Checking for @samp{presence_set} is done on the 10207source state reservation, checking for @samp{final_presence_set} is 10208done on the result reservation. This construction is useful to 10209describe a reservation which is actually two subsequent reservations. 10210For example, if we use 10211 10212@smallexample 10213(presence_set "slot1" "slot0") 10214@end smallexample 10215 10216the following insn will be never issued (because @samp{slot1} requires 10217@samp{slot0} which is absent in the source state). 10218 10219@smallexample 10220(define_reservation "insn_and_nop" "slot0 + slot1") 10221@end smallexample 10222 10223but it can be issued if we use analogous @samp{final_presence_set}. 10224 10225The forth construction (@samp{absence_set}) means that each functional 10226unit in the first string can be reserved only if each pattern of units 10227whose names are in the second string is not reserved. This is an 10228asymmetric relation (actually @samp{exclusion_set} is analogous to 10229this one but it is symmetric). For example it might be useful in a 10230@acronym{VLIW} description to say that @samp{slot0} cannot be reserved 10231after either @samp{slot1} or @samp{slot2} have been reserved. This 10232can be described as: 10233 10234@smallexample 10235(absence_set "slot0" "slot1, slot2") 10236@end smallexample 10237 10238Or @samp{slot2} cannot be reserved if @samp{slot0} and unit @samp{b0} 10239are reserved or @samp{slot1} and unit @samp{b1} are reserved. In 10240this case we could write 10241 10242@smallexample 10243(absence_set "slot2" "slot0 b0, slot1 b1") 10244@end smallexample 10245 10246All functional units mentioned in a set should belong to the same 10247automaton. 10248 10249The last construction (@samp{final_absence_set}) is analogous to 10250@samp{absence_set} but checking is done on the result (state) 10251reservation. See comments for @samp{final_presence_set}. 10252 10253@findex automata_option 10254@cindex deterministic finite state automaton 10255@cindex nondeterministic finite state automaton 10256@cindex finite state automaton minimization 10257You can control the generator of the pipeline hazard recognizer with 10258the following construction. 10259 10260@smallexample 10261(automata_option @var{options}) 10262@end smallexample 10263 10264@var{options} is a string giving options which affect the generated 10265code. Currently there are the following options: 10266 10267@itemize @bullet 10268@item 10269@dfn{no-minimization} makes no minimization of the automaton. This is 10270only worth to do when we are debugging the description and need to 10271look more accurately at reservations of states. 10272 10273@item 10274@dfn{time} means printing time statistics about the generation of 10275automata. 10276 10277@item 10278@dfn{stats} means printing statistics about the generated automata 10279such as the number of DFA states, NDFA states and arcs. 10280 10281@item 10282@dfn{v} means a generation of the file describing the result automata. 10283The file has suffix @samp{.dfa} and can be used for the description 10284verification and debugging. 10285 10286@item 10287@dfn{w} means a generation of warning instead of error for 10288non-critical errors. 10289 10290@item 10291@dfn{no-comb-vect} prevents the automaton generator from generating 10292two data structures and comparing them for space efficiency. Using 10293a comb vector to represent transitions may be better, but it can be 10294very expensive to construct. This option is useful if the build 10295process spends an unacceptably long time in genautomata. 10296 10297@item 10298@dfn{ndfa} makes nondeterministic finite state automata. This affects 10299the treatment of operator @samp{|} in the regular expressions. The 10300usual treatment of the operator is to try the first alternative and, 10301if the reservation is not possible, the second alternative. The 10302nondeterministic treatment means trying all alternatives, some of them 10303may be rejected by reservations in the subsequent insns. 10304 10305@item 10306@dfn{collapse-ndfa} modifies the behavior of the generator when 10307producing an automaton. An additional state transition to collapse a 10308nondeterministic @acronym{NDFA} state to a deterministic @acronym{DFA} 10309state is generated. It can be triggered by passing @code{const0_rtx} to 10310state_transition. In such an automaton, cycle advance transitions are 10311available only for these collapsed states. This option is useful for 10312ports that want to use the @code{ndfa} option, but also want to use 10313@code{define_query_cpu_unit} to assign units to insns issued in a cycle. 10314 10315@item 10316@dfn{progress} means output of a progress bar showing how many states 10317were generated so far for automaton being processed. This is useful 10318during debugging a @acronym{DFA} description. If you see too many 10319generated states, you could interrupt the generator of the pipeline 10320hazard recognizer and try to figure out a reason for generation of the 10321huge automaton. 10322@end itemize 10323 10324As an example, consider a superscalar @acronym{RISC} machine which can 10325issue three insns (two integer insns and one floating point insn) on 10326the cycle but can finish only two insns. To describe this, we define 10327the following functional units. 10328 10329@smallexample 10330(define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline") 10331(define_cpu_unit "port0, port1") 10332@end smallexample 10333 10334All simple integer insns can be executed in any integer pipeline and 10335their result is ready in two cycles. The simple integer insns are 10336issued into the first pipeline unless it is reserved, otherwise they 10337are issued into the second pipeline. Integer division and 10338multiplication insns can be executed only in the second integer 10339pipeline and their results are ready correspondingly in 9 and 4 10340cycles. The integer division is not pipelined, i.e.@: the subsequent 10341integer division insn cannot be issued until the current division 10342insn finished. Floating point insns are fully pipelined and their 10343results are ready in 3 cycles. Where the result of a floating point 10344insn is used by an integer insn, an additional delay of one cycle is 10345incurred. To describe all of this we could specify 10346 10347@smallexample 10348(define_cpu_unit "div") 10349 10350(define_insn_reservation "simple" 2 (eq_attr "type" "int") 10351 "(i0_pipeline | i1_pipeline), (port0 | port1)") 10352 10353(define_insn_reservation "mult" 4 (eq_attr "type" "mult") 10354 "i1_pipeline, nothing*2, (port0 | port1)") 10355 10356(define_insn_reservation "div" 9 (eq_attr "type" "div") 10357 "i1_pipeline, div*7, div + (port0 | port1)") 10358 10359(define_insn_reservation "float" 3 (eq_attr "type" "float") 10360 "f_pipeline, nothing, (port0 | port1)) 10361 10362(define_bypass 4 "float" "simple,mult,div") 10363@end smallexample 10364 10365To simplify the description we could describe the following reservation 10366 10367@smallexample 10368(define_reservation "finish" "port0|port1") 10369@end smallexample 10370 10371and use it in all @code{define_insn_reservation} as in the following 10372construction 10373 10374@smallexample 10375(define_insn_reservation "simple" 2 (eq_attr "type" "int") 10376 "(i0_pipeline | i1_pipeline), finish") 10377@end smallexample 10378 10379 10380@end ifset 10381@ifset INTERNALS 10382@node Conditional Execution 10383@section Conditional Execution 10384@cindex conditional execution 10385@cindex predication 10386 10387A number of architectures provide for some form of conditional 10388execution, or predication. The hallmark of this feature is the 10389ability to nullify most of the instructions in the instruction set. 10390When the instruction set is large and not entirely symmetric, it 10391can be quite tedious to describe these forms directly in the 10392@file{.md} file. An alternative is the @code{define_cond_exec} template. 10393 10394@findex define_cond_exec 10395@smallexample 10396(define_cond_exec 10397 [@var{predicate-pattern}] 10398 "@var{condition}" 10399 "@var{output-template}" 10400 "@var{optional-insn-attribues}") 10401@end smallexample 10402 10403@var{predicate-pattern} is the condition that must be true for the 10404insn to be executed at runtime and should match a relational operator. 10405One can use @code{match_operator} to match several relational operators 10406at once. Any @code{match_operand} operands must have no more than one 10407alternative. 10408 10409@var{condition} is a C expression that must be true for the generated 10410pattern to match. 10411 10412@findex current_insn_predicate 10413@var{output-template} is a string similar to the @code{define_insn} 10414output template (@pxref{Output Template}), except that the @samp{*} 10415and @samp{@@} special cases do not apply. This is only useful if the 10416assembly text for the predicate is a simple prefix to the main insn. 10417In order to handle the general case, there is a global variable 10418@code{current_insn_predicate} that will contain the entire predicate 10419if the current insn is predicated, and will otherwise be @code{NULL}. 10420 10421@var{optional-insn-attributes} is an optional vector of attributes that gets 10422appended to the insn attributes of the produced cond_exec rtx. It can 10423be used to add some distinguishing attribute to cond_exec rtxs produced 10424that way. An example usage would be to use this attribute in conjunction 10425with attributes on the main pattern to disable particular alternatives under 10426certain conditions. 10427 10428When @code{define_cond_exec} is used, an implicit reference to 10429the @code{predicable} instruction attribute is made. 10430@xref{Insn Attributes}. This attribute must be a boolean (i.e.@: have 10431exactly two elements in its @var{list-of-values}), with the possible 10432values being @code{no} and @code{yes}. The default and all uses in 10433the insns must be a simple constant, not a complex expressions. It 10434may, however, depend on the alternative, by using a comma-separated 10435list of values. If that is the case, the port should also define an 10436@code{enabled} attribute (@pxref{Disable Insn Alternatives}), which 10437should also allow only @code{no} and @code{yes} as its values. 10438 10439For each @code{define_insn} for which the @code{predicable} 10440attribute is true, a new @code{define_insn} pattern will be 10441generated that matches a predicated version of the instruction. 10442For example, 10443 10444@smallexample 10445(define_insn "addsi" 10446 [(set (match_operand:SI 0 "register_operand" "r") 10447 (plus:SI (match_operand:SI 1 "register_operand" "r") 10448 (match_operand:SI 2 "register_operand" "r")))] 10449 "@var{test1}" 10450 "add %2,%1,%0") 10451 10452(define_cond_exec 10453 [(ne (match_operand:CC 0 "register_operand" "c") 10454 (const_int 0))] 10455 "@var{test2}" 10456 "(%0)") 10457@end smallexample 10458 10459@noindent 10460generates a new pattern 10461 10462@smallexample 10463(define_insn "" 10464 [(cond_exec 10465 (ne (match_operand:CC 3 "register_operand" "c") (const_int 0)) 10466 (set (match_operand:SI 0 "register_operand" "r") 10467 (plus:SI (match_operand:SI 1 "register_operand" "r") 10468 (match_operand:SI 2 "register_operand" "r"))))] 10469 "(@var{test2}) && (@var{test1})" 10470 "(%3) add %2,%1,%0") 10471@end smallexample 10472 10473@end ifset 10474@ifset INTERNALS 10475@node Define Subst 10476@section RTL Templates Transformations 10477@cindex define_subst 10478 10479For some hardware architectures there are common cases when the RTL 10480templates for the instructions can be derived from the other RTL 10481templates using simple transformations. E.g., @file{i386.md} contains 10482an RTL template for the ordinary @code{sub} instruction--- 10483@code{*subsi_1}, and for the @code{sub} instruction with subsequent 10484zero-extension---@code{*subsi_1_zext}. Such cases can be easily 10485implemented by a single meta-template capable of generating a modified 10486case based on the initial one: 10487 10488@findex define_subst 10489@smallexample 10490(define_subst "@var{name}" 10491 [@var{input-template}] 10492 "@var{condition}" 10493 [@var{output-template}]) 10494@end smallexample 10495@var{input-template} is a pattern describing the source RTL template, 10496which will be transformed. 10497 10498@var{condition} is a C expression that is conjunct with the condition 10499from the input-template to generate a condition to be used in the 10500output-template. 10501 10502@var{output-template} is a pattern that will be used in the resulting 10503template. 10504 10505@code{define_subst} mechanism is tightly coupled with the notion of the 10506subst attribute (@pxref{Subst Iterators}). The use of 10507@code{define_subst} is triggered by a reference to a subst attribute in 10508the transforming RTL template. This reference initiates duplication of 10509the source RTL template and substitution of the attributes with their 10510values. The source RTL template is left unchanged, while the copy is 10511transformed by @code{define_subst}. This transformation can fail in the 10512case when the source RTL template is not matched against the 10513input-template of the @code{define_subst}. In such case the copy is 10514deleted. 10515 10516@code{define_subst} can be used only in @code{define_insn} and 10517@code{define_expand}, it cannot be used in other expressions (e.g.@: in 10518@code{define_insn_and_split}). 10519 10520@menu 10521* Define Subst Example:: Example of @code{define_subst} work. 10522* Define Subst Pattern Matching:: Process of template comparison. 10523* Define Subst Output Template:: Generation of output template. 10524@end menu 10525 10526@node Define Subst Example 10527@subsection @code{define_subst} Example 10528@cindex define_subst 10529 10530To illustrate how @code{define_subst} works, let us examine a simple 10531template transformation. 10532 10533Suppose there are two kinds of instructions: one that touches flags and 10534the other that does not. The instructions of the second type could be 10535generated with the following @code{define_subst}: 10536 10537@smallexample 10538(define_subst "add_clobber_subst" 10539 [(set (match_operand:SI 0 "" "") 10540 (match_operand:SI 1 "" ""))] 10541 "" 10542 [(set (match_dup 0) 10543 (match_dup 1)) 10544 (clobber (reg:CC FLAGS_REG))]) 10545@end smallexample 10546 10547This @code{define_subst} can be applied to any RTL pattern containing 10548@code{set} of mode SI and generates a copy with clobber when it is 10549applied. 10550 10551Assume there is an RTL template for a @code{max} instruction to be used 10552in @code{define_subst} mentioned above: 10553 10554@smallexample 10555(define_insn "maxsi" 10556 [(set (match_operand:SI 0 "register_operand" "=r") 10557 (max:SI 10558 (match_operand:SI 1 "register_operand" "r") 10559 (match_operand:SI 2 "register_operand" "r")))] 10560 "" 10561 "max\t@{%2, %1, %0|%0, %1, %2@}" 10562 [@dots{}]) 10563@end smallexample 10564 10565To mark the RTL template for @code{define_subst} application, 10566subst-attributes are used. They should be declared in advance: 10567 10568@smallexample 10569(define_subst_attr "add_clobber_name" "add_clobber_subst" "_noclobber" "_clobber") 10570@end smallexample 10571 10572Here @samp{add_clobber_name} is the attribute name, 10573@samp{add_clobber_subst} is the name of the corresponding 10574@code{define_subst}, the third argument (@samp{_noclobber}) is the 10575attribute value that would be substituted into the unchanged version of 10576the source RTL template, and the last argument (@samp{_clobber}) is the 10577value that would be substituted into the second, transformed, 10578version of the RTL template. 10579 10580Once the subst-attribute has been defined, it should be used in RTL 10581templates which need to be processed by the @code{define_subst}. So, 10582the original RTL template should be changed: 10583 10584@smallexample 10585(define_insn "maxsi<add_clobber_name>" 10586 [(set (match_operand:SI 0 "register_operand" "=r") 10587 (max:SI 10588 (match_operand:SI 1 "register_operand" "r") 10589 (match_operand:SI 2 "register_operand" "r")))] 10590 "" 10591 "max\t@{%2, %1, %0|%0, %1, %2@}" 10592 [@dots{}]) 10593@end smallexample 10594 10595The result of the @code{define_subst} usage would look like the following: 10596 10597@smallexample 10598(define_insn "maxsi_noclobber" 10599 [(set (match_operand:SI 0 "register_operand" "=r") 10600 (max:SI 10601 (match_operand:SI 1 "register_operand" "r") 10602 (match_operand:SI 2 "register_operand" "r")))] 10603 "" 10604 "max\t@{%2, %1, %0|%0, %1, %2@}" 10605 [@dots{}]) 10606(define_insn "maxsi_clobber" 10607 [(set (match_operand:SI 0 "register_operand" "=r") 10608 (max:SI 10609 (match_operand:SI 1 "register_operand" "r") 10610 (match_operand:SI 2 "register_operand" "r"))) 10611 (clobber (reg:CC FLAGS_REG))] 10612 "" 10613 "max\t@{%2, %1, %0|%0, %1, %2@}" 10614 [@dots{}]) 10615@end smallexample 10616 10617@node Define Subst Pattern Matching 10618@subsection Pattern Matching in @code{define_subst} 10619@cindex define_subst 10620 10621All expressions, allowed in @code{define_insn} or @code{define_expand}, 10622are allowed in the input-template of @code{define_subst}, except 10623@code{match_par_dup}, @code{match_scratch}, @code{match_parallel}. The 10624meanings of expressions in the input-template were changed: 10625 10626@code{match_operand} matches any expression (possibly, a subtree in 10627RTL-template), if modes of the @code{match_operand} and this expression 10628are the same, or mode of the @code{match_operand} is @code{VOIDmode}, or 10629this expression is @code{match_dup}, @code{match_op_dup}. If the 10630expression is @code{match_operand} too, and predicate of 10631@code{match_operand} from the input pattern is not empty, then the 10632predicates are compared. That can be used for more accurate filtering 10633of accepted RTL-templates. 10634 10635@code{match_operator} matches common operators (like @code{plus}, 10636@code{minus}), @code{unspec}, @code{unspec_volatile} operators and 10637@code{match_operator}s from the original pattern if the modes match and 10638@code{match_operator} from the input pattern has the same number of 10639operands as the operator from the original pattern. 10640 10641@node Define Subst Output Template 10642@subsection Generation of output template in @code{define_subst} 10643@cindex define_subst 10644 10645If all necessary checks for @code{define_subst} application pass, a new 10646RTL-pattern, based on the output-template, is created to replace the old 10647template. Like in input-patterns, meanings of some RTL expressions are 10648changed when they are used in output-patterns of a @code{define_subst}. 10649Thus, @code{match_dup} is used for copying the whole expression from the 10650original pattern, which matched corresponding @code{match_operand} from 10651the input pattern. 10652 10653@code{match_dup N} is used in the output template to be replaced with 10654the expression from the original pattern, which matched 10655@code{match_operand N} from the input pattern. As a consequence, 10656@code{match_dup} cannot be used to point to @code{match_operand}s from 10657the output pattern, it should always refer to a @code{match_operand} 10658from the input pattern. If a @code{match_dup N} occurs more than once 10659in the output template, its first occurrence is replaced with the 10660expression from the original pattern, and the subsequent expressions 10661are replaced with @code{match_dup N}, i.e., a reference to the first 10662expression. 10663 10664In the output template one can refer to the expressions from the 10665original pattern and create new ones. For instance, some operands could 10666be added by means of standard @code{match_operand}. 10667 10668After replacing @code{match_dup} with some RTL-subtree from the original 10669pattern, it could happen that several @code{match_operand}s in the 10670output pattern have the same indexes. It is unknown, how many and what 10671indexes would be used in the expression which would replace 10672@code{match_dup}, so such conflicts in indexes are inevitable. To 10673overcome this issue, @code{match_operands} and @code{match_operators}, 10674which were introduced into the output pattern, are renumerated when all 10675@code{match_dup}s are replaced. 10676 10677Number of alternatives in @code{match_operand}s introduced into the 10678output template @code{M} could differ from the number of alternatives in 10679the original pattern @code{N}, so in the resultant pattern there would 10680be @code{N*M} alternatives. Thus, constraints from the original pattern 10681would be duplicated @code{N} times, constraints from the output pattern 10682would be duplicated @code{M} times, producing all possible combinations. 10683@end ifset 10684 10685@ifset INTERNALS 10686@node Constant Definitions 10687@section Constant Definitions 10688@cindex constant definitions 10689@findex define_constants 10690 10691Using literal constants inside instruction patterns reduces legibility and 10692can be a maintenance problem. 10693 10694To overcome this problem, you may use the @code{define_constants} 10695expression. It contains a vector of name-value pairs. From that 10696point on, wherever any of the names appears in the MD file, it is as 10697if the corresponding value had been written instead. You may use 10698@code{define_constants} multiple times; each appearance adds more 10699constants to the table. It is an error to redefine a constant with 10700a different value. 10701 10702To come back to the a29k load multiple example, instead of 10703 10704@smallexample 10705(define_insn "" 10706 [(match_parallel 0 "load_multiple_operation" 10707 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 10708 (match_operand:SI 2 "memory_operand" "m")) 10709 (use (reg:SI 179)) 10710 (clobber (reg:SI 179))])] 10711 "" 10712 "loadm 0,0,%1,%2") 10713@end smallexample 10714 10715You could write: 10716 10717@smallexample 10718(define_constants [ 10719 (R_BP 177) 10720 (R_FC 178) 10721 (R_CR 179) 10722 (R_Q 180) 10723]) 10724 10725(define_insn "" 10726 [(match_parallel 0 "load_multiple_operation" 10727 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 10728 (match_operand:SI 2 "memory_operand" "m")) 10729 (use (reg:SI R_CR)) 10730 (clobber (reg:SI R_CR))])] 10731 "" 10732 "loadm 0,0,%1,%2") 10733@end smallexample 10734 10735The constants that are defined with a define_constant are also output 10736in the insn-codes.h header file as #defines. 10737 10738@cindex enumerations 10739@findex define_c_enum 10740You can also use the machine description file to define enumerations. 10741Like the constants defined by @code{define_constant}, these enumerations 10742are visible to both the machine description file and the main C code. 10743 10744The syntax is as follows: 10745 10746@smallexample 10747(define_c_enum "@var{name}" [ 10748 @var{value0} 10749 @var{value1} 10750 @dots{} 10751 @var{valuen} 10752]) 10753@end smallexample 10754 10755This definition causes the equivalent of the following C code to appear 10756in @file{insn-constants.h}: 10757 10758@smallexample 10759enum @var{name} @{ 10760 @var{value0} = 0, 10761 @var{value1} = 1, 10762 @dots{} 10763 @var{valuen} = @var{n} 10764@}; 10765#define NUM_@var{cname}_VALUES (@var{n} + 1) 10766@end smallexample 10767 10768where @var{cname} is the capitalized form of @var{name}. 10769It also makes each @var{valuei} available in the machine description 10770file, just as if it had been declared with: 10771 10772@smallexample 10773(define_constants [(@var{valuei} @var{i})]) 10774@end smallexample 10775 10776Each @var{valuei} is usually an upper-case identifier and usually 10777begins with @var{cname}. 10778 10779You can split the enumeration definition into as many statements as 10780you like. The above example is directly equivalent to: 10781 10782@smallexample 10783(define_c_enum "@var{name}" [@var{value0}]) 10784(define_c_enum "@var{name}" [@var{value1}]) 10785@dots{} 10786(define_c_enum "@var{name}" [@var{valuen}]) 10787@end smallexample 10788 10789Splitting the enumeration helps to improve the modularity of each 10790individual @code{.md} file. For example, if a port defines its 10791synchronization instructions in a separate @file{sync.md} file, 10792it is convenient to define all synchronization-specific enumeration 10793values in @file{sync.md} rather than in the main @file{.md} file. 10794 10795Some enumeration names have special significance to GCC: 10796 10797@table @code 10798@item unspecv 10799@findex unspec_volatile 10800If an enumeration called @code{unspecv} is defined, GCC will use it 10801when printing out @code{unspec_volatile} expressions. For example: 10802 10803@smallexample 10804(define_c_enum "unspecv" [ 10805 UNSPECV_BLOCKAGE 10806]) 10807@end smallexample 10808 10809causes GCC to print @samp{(unspec_volatile @dots{} 0)} as: 10810 10811@smallexample 10812(unspec_volatile ... UNSPECV_BLOCKAGE) 10813@end smallexample 10814 10815@item unspec 10816@findex unspec 10817If an enumeration called @code{unspec} is defined, GCC will use 10818it when printing out @code{unspec} expressions. GCC will also use 10819it when printing out @code{unspec_volatile} expressions unless an 10820@code{unspecv} enumeration is also defined. You can therefore 10821decide whether to keep separate enumerations for volatile and 10822non-volatile expressions or whether to use the same enumeration 10823for both. 10824@end table 10825 10826@findex define_enum 10827@anchor{define_enum} 10828Another way of defining an enumeration is to use @code{define_enum}: 10829 10830@smallexample 10831(define_enum "@var{name}" [ 10832 @var{value0} 10833 @var{value1} 10834 @dots{} 10835 @var{valuen} 10836]) 10837@end smallexample 10838 10839This directive implies: 10840 10841@smallexample 10842(define_c_enum "@var{name}" [ 10843 @var{cname}_@var{cvalue0} 10844 @var{cname}_@var{cvalue1} 10845 @dots{} 10846 @var{cname}_@var{cvaluen} 10847]) 10848@end smallexample 10849 10850@findex define_enum_attr 10851where @var{cvaluei} is the capitalized form of @var{valuei}. 10852However, unlike @code{define_c_enum}, the enumerations defined 10853by @code{define_enum} can be used in attribute specifications 10854(@pxref{define_enum_attr}). 10855@end ifset 10856@ifset INTERNALS 10857@node Iterators 10858@section Iterators 10859@cindex iterators in @file{.md} files 10860 10861Ports often need to define similar patterns for more than one machine 10862mode or for more than one rtx code. GCC provides some simple iterator 10863facilities to make this process easier. 10864 10865@menu 10866* Mode Iterators:: Generating variations of patterns for different modes. 10867* Code Iterators:: Doing the same for codes. 10868* Int Iterators:: Doing the same for integers. 10869* Subst Iterators:: Generating variations of patterns for define_subst. 10870* Parameterized Names:: Specifying iterator values in C++ code. 10871@end menu 10872 10873@node Mode Iterators 10874@subsection Mode Iterators 10875@cindex mode iterators in @file{.md} files 10876 10877Ports often need to define similar patterns for two or more different modes. 10878For example: 10879 10880@itemize @bullet 10881@item 10882If a processor has hardware support for both single and double 10883floating-point arithmetic, the @code{SFmode} patterns tend to be 10884very similar to the @code{DFmode} ones. 10885 10886@item 10887If a port uses @code{SImode} pointers in one configuration and 10888@code{DImode} pointers in another, it will usually have very similar 10889@code{SImode} and @code{DImode} patterns for manipulating pointers. 10890@end itemize 10891 10892Mode iterators allow several patterns to be instantiated from one 10893@file{.md} file template. They can be used with any type of 10894rtx-based construct, such as a @code{define_insn}, 10895@code{define_split}, or @code{define_peephole2}. 10896 10897@menu 10898* Defining Mode Iterators:: Defining a new mode iterator. 10899* Substitutions:: Combining mode iterators with substitutions 10900* Examples:: Examples 10901@end menu 10902 10903@node Defining Mode Iterators 10904@subsubsection Defining Mode Iterators 10905@findex define_mode_iterator 10906 10907The syntax for defining a mode iterator is: 10908 10909@smallexample 10910(define_mode_iterator @var{name} [(@var{mode1} "@var{cond1}") @dots{} (@var{moden} "@var{condn}")]) 10911@end smallexample 10912 10913This allows subsequent @file{.md} file constructs to use the mode suffix 10914@code{:@var{name}}. Every construct that does so will be expanded 10915@var{n} times, once with every use of @code{:@var{name}} replaced by 10916@code{:@var{mode1}}, once with every use replaced by @code{:@var{mode2}}, 10917and so on. In the expansion for a particular @var{modei}, every 10918C condition will also require that @var{condi} be true. 10919 10920For example: 10921 10922@smallexample 10923(define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")]) 10924@end smallexample 10925 10926defines a new mode suffix @code{:P}. Every construct that uses 10927@code{:P} will be expanded twice, once with every @code{:P} replaced 10928by @code{:SI} and once with every @code{:P} replaced by @code{:DI}. 10929The @code{:SI} version will only apply if @code{Pmode == SImode} and 10930the @code{:DI} version will only apply if @code{Pmode == DImode}. 10931 10932As with other @file{.md} conditions, an empty string is treated 10933as ``always true''. @code{(@var{mode} "")} can also be abbreviated 10934to @code{@var{mode}}. For example: 10935 10936@smallexample 10937(define_mode_iterator GPR [SI (DI "TARGET_64BIT")]) 10938@end smallexample 10939 10940means that the @code{:DI} expansion only applies if @code{TARGET_64BIT} 10941but that the @code{:SI} expansion has no such constraint. 10942 10943Iterators are applied in the order they are defined. This can be 10944significant if two iterators are used in a construct that requires 10945substitutions. @xref{Substitutions}. 10946 10947@node Substitutions 10948@subsubsection Substitution in Mode Iterators 10949@findex define_mode_attr 10950 10951If an @file{.md} file construct uses mode iterators, each version of the 10952construct will often need slightly different strings or modes. For 10953example: 10954 10955@itemize @bullet 10956@item 10957When a @code{define_expand} defines several @code{add@var{m}3} patterns 10958(@pxref{Standard Names}), each expander will need to use the 10959appropriate mode name for @var{m}. 10960 10961@item 10962When a @code{define_insn} defines several instruction patterns, 10963each instruction will often use a different assembler mnemonic. 10964 10965@item 10966When a @code{define_insn} requires operands with different modes, 10967using an iterator for one of the operand modes usually requires a specific 10968mode for the other operand(s). 10969@end itemize 10970 10971GCC supports such variations through a system of ``mode attributes''. 10972There are two standard attributes: @code{mode}, which is the name of 10973the mode in lower case, and @code{MODE}, which is the same thing in 10974upper case. You can define other attributes using: 10975 10976@smallexample 10977(define_mode_attr @var{name} [(@var{mode1} "@var{value1}") @dots{} (@var{moden} "@var{valuen}")]) 10978@end smallexample 10979 10980where @var{name} is the name of the attribute and @var{valuei} 10981is the value associated with @var{modei}. 10982 10983When GCC replaces some @var{:iterator} with @var{:mode}, it will scan 10984each string and mode in the pattern for sequences of the form 10985@code{<@var{iterator}:@var{attr}>}, where @var{attr} is the name of a 10986mode attribute. If the attribute is defined for @var{mode}, the whole 10987@code{<@dots{}>} sequence will be replaced by the appropriate attribute 10988value. 10989 10990For example, suppose an @file{.md} file has: 10991 10992@smallexample 10993(define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")]) 10994(define_mode_attr load [(SI "lw") (DI "ld")]) 10995@end smallexample 10996 10997If one of the patterns that uses @code{:P} contains the string 10998@code{"<P:load>\t%0,%1"}, the @code{SI} version of that pattern 10999will use @code{"lw\t%0,%1"} and the @code{DI} version will use 11000@code{"ld\t%0,%1"}. 11001 11002Here is an example of using an attribute for a mode: 11003 11004@smallexample 11005(define_mode_iterator LONG [SI DI]) 11006(define_mode_attr SHORT [(SI "HI") (DI "SI")]) 11007(define_insn @dots{} 11008 (sign_extend:LONG (match_operand:<LONG:SHORT> @dots{})) @dots{}) 11009@end smallexample 11010 11011The @code{@var{iterator}:} prefix may be omitted, in which case the 11012substitution will be attempted for every iterator expansion. 11013 11014@node Examples 11015@subsubsection Mode Iterator Examples 11016 11017Here is an example from the MIPS port. It defines the following 11018modes and attributes (among others): 11019 11020@smallexample 11021(define_mode_iterator GPR [SI (DI "TARGET_64BIT")]) 11022(define_mode_attr d [(SI "") (DI "d")]) 11023@end smallexample 11024 11025and uses the following template to define both @code{subsi3} 11026and @code{subdi3}: 11027 11028@smallexample 11029(define_insn "sub<mode>3" 11030 [(set (match_operand:GPR 0 "register_operand" "=d") 11031 (minus:GPR (match_operand:GPR 1 "register_operand" "d") 11032 (match_operand:GPR 2 "register_operand" "d")))] 11033 "" 11034 "<d>subu\t%0,%1,%2" 11035 [(set_attr "type" "arith") 11036 (set_attr "mode" "<MODE>")]) 11037@end smallexample 11038 11039This is exactly equivalent to: 11040 11041@smallexample 11042(define_insn "subsi3" 11043 [(set (match_operand:SI 0 "register_operand" "=d") 11044 (minus:SI (match_operand:SI 1 "register_operand" "d") 11045 (match_operand:SI 2 "register_operand" "d")))] 11046 "" 11047 "subu\t%0,%1,%2" 11048 [(set_attr "type" "arith") 11049 (set_attr "mode" "SI")]) 11050 11051(define_insn "subdi3" 11052 [(set (match_operand:DI 0 "register_operand" "=d") 11053 (minus:DI (match_operand:DI 1 "register_operand" "d") 11054 (match_operand:DI 2 "register_operand" "d")))] 11055 "" 11056 "dsubu\t%0,%1,%2" 11057 [(set_attr "type" "arith") 11058 (set_attr "mode" "DI")]) 11059@end smallexample 11060 11061@node Code Iterators 11062@subsection Code Iterators 11063@cindex code iterators in @file{.md} files 11064@findex define_code_iterator 11065@findex define_code_attr 11066 11067Code iterators operate in a similar way to mode iterators. @xref{Mode Iterators}. 11068 11069The construct: 11070 11071@smallexample 11072(define_code_iterator @var{name} [(@var{code1} "@var{cond1}") @dots{} (@var{coden} "@var{condn}")]) 11073@end smallexample 11074 11075defines a pseudo rtx code @var{name} that can be instantiated as 11076@var{codei} if condition @var{condi} is true. Each @var{codei} 11077must have the same rtx format. @xref{RTL Classes}. 11078 11079As with mode iterators, each pattern that uses @var{name} will be 11080expanded @var{n} times, once with all uses of @var{name} replaced by 11081@var{code1}, once with all uses replaced by @var{code2}, and so on. 11082@xref{Defining Mode Iterators}. 11083 11084It is possible to define attributes for codes as well as for modes. 11085There are two standard code attributes: @code{code}, the name of the 11086code in lower case, and @code{CODE}, the name of the code in upper case. 11087Other attributes are defined using: 11088 11089@smallexample 11090(define_code_attr @var{name} [(@var{code1} "@var{value1}") @dots{} (@var{coden} "@var{valuen}")]) 11091@end smallexample 11092 11093Instruction patterns can use code attributes as rtx codes, which can be 11094useful if two sets of codes act in tandem. For example, the following 11095@code{define_insn} defines two patterns, one calculating a signed absolute 11096difference and another calculating an unsigned absolute difference: 11097 11098@smallexample 11099(define_code_iterator any_max [smax umax]) 11100(define_code_attr paired_min [(smax "smin") (umax "umin")]) 11101(define_insn @dots{} 11102 [(set (match_operand:SI 0 @dots{}) 11103 (minus:SI (any_max:SI (match_operand:SI 1 @dots{}) 11104 (match_operand:SI 2 @dots{})) 11105 (<paired_min>:SI (match_dup 1) (match_dup 2))))] 11106 @dots{}) 11107@end smallexample 11108 11109The signed version of the instruction uses @code{smax} and @code{smin} 11110while the unsigned version uses @code{umax} and @code{umin}. There 11111are no versions that pair @code{smax} with @code{umin} or @code{umax} 11112with @code{smin}. 11113 11114Here's an example of code iterators in action, taken from the MIPS port: 11115 11116@smallexample 11117(define_code_iterator any_cond [unordered ordered unlt unge uneq ltgt unle ungt 11118 eq ne gt ge lt le gtu geu ltu leu]) 11119 11120(define_expand "b<code>" 11121 [(set (pc) 11122 (if_then_else (any_cond:CC (cc0) 11123 (const_int 0)) 11124 (label_ref (match_operand 0 "")) 11125 (pc)))] 11126 "" 11127@{ 11128 gen_conditional_branch (operands, <CODE>); 11129 DONE; 11130@}) 11131@end smallexample 11132 11133This is equivalent to: 11134 11135@smallexample 11136(define_expand "bunordered" 11137 [(set (pc) 11138 (if_then_else (unordered:CC (cc0) 11139 (const_int 0)) 11140 (label_ref (match_operand 0 "")) 11141 (pc)))] 11142 "" 11143@{ 11144 gen_conditional_branch (operands, UNORDERED); 11145 DONE; 11146@}) 11147 11148(define_expand "bordered" 11149 [(set (pc) 11150 (if_then_else (ordered:CC (cc0) 11151 (const_int 0)) 11152 (label_ref (match_operand 0 "")) 11153 (pc)))] 11154 "" 11155@{ 11156 gen_conditional_branch (operands, ORDERED); 11157 DONE; 11158@}) 11159 11160@dots{} 11161@end smallexample 11162 11163@node Int Iterators 11164@subsection Int Iterators 11165@cindex int iterators in @file{.md} files 11166@findex define_int_iterator 11167@findex define_int_attr 11168 11169Int iterators operate in a similar way to code iterators. @xref{Code Iterators}. 11170 11171The construct: 11172 11173@smallexample 11174(define_int_iterator @var{name} [(@var{int1} "@var{cond1}") @dots{} (@var{intn} "@var{condn}")]) 11175@end smallexample 11176 11177defines a pseudo integer constant @var{name} that can be instantiated as 11178@var{inti} if condition @var{condi} is true. Each @var{int} 11179must have the same rtx format. @xref{RTL Classes}. Int iterators can appear 11180in only those rtx fields that have 'i' as the specifier. This means that 11181each @var{int} has to be a constant defined using define_constant or 11182define_c_enum. 11183 11184As with mode and code iterators, each pattern that uses @var{name} will be 11185expanded @var{n} times, once with all uses of @var{name} replaced by 11186@var{int1}, once with all uses replaced by @var{int2}, and so on. 11187@xref{Defining Mode Iterators}. 11188 11189It is possible to define attributes for ints as well as for codes and modes. 11190Attributes are defined using: 11191 11192@smallexample 11193(define_int_attr @var{name} [(@var{int1} "@var{value1}") @dots{} (@var{intn} "@var{valuen}")]) 11194@end smallexample 11195 11196Here's an example of int iterators in action, taken from the ARM port: 11197 11198@smallexample 11199(define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG]) 11200 11201(define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")]) 11202 11203(define_insn "neon_vq<absneg><mode>" 11204 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 11205 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 11206 (match_operand:SI 2 "immediate_operand" "i")] 11207 QABSNEG))] 11208 "TARGET_NEON" 11209 "vq<absneg>.<V_s_elem>\t%<V_reg>0, %<V_reg>1" 11210 [(set_attr "type" "neon_vqneg_vqabs")] 11211) 11212 11213@end smallexample 11214 11215This is equivalent to: 11216 11217@smallexample 11218(define_insn "neon_vqabs<mode>" 11219 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 11220 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 11221 (match_operand:SI 2 "immediate_operand" "i")] 11222 UNSPEC_VQABS))] 11223 "TARGET_NEON" 11224 "vqabs.<V_s_elem>\t%<V_reg>0, %<V_reg>1" 11225 [(set_attr "type" "neon_vqneg_vqabs")] 11226) 11227 11228(define_insn "neon_vqneg<mode>" 11229 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 11230 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 11231 (match_operand:SI 2 "immediate_operand" "i")] 11232 UNSPEC_VQNEG))] 11233 "TARGET_NEON" 11234 "vqneg.<V_s_elem>\t%<V_reg>0, %<V_reg>1" 11235 [(set_attr "type" "neon_vqneg_vqabs")] 11236) 11237 11238@end smallexample 11239 11240@node Subst Iterators 11241@subsection Subst Iterators 11242@cindex subst iterators in @file{.md} files 11243@findex define_subst 11244@findex define_subst_attr 11245 11246Subst iterators are special type of iterators with the following 11247restrictions: they could not be declared explicitly, they always have 11248only two values, and they do not have explicit dedicated name. 11249Subst-iterators are triggered only when corresponding subst-attribute is 11250used in RTL-pattern. 11251 11252Subst iterators transform templates in the following way: the templates 11253are duplicated, the subst-attributes in these templates are replaced 11254with the corresponding values, and a new attribute is implicitly added 11255to the given @code{define_insn}/@code{define_expand}. The name of the 11256added attribute matches the name of @code{define_subst}. Such 11257attributes are declared implicitly, and it is not allowed to have a 11258@code{define_attr} named as a @code{define_subst}. 11259 11260Each subst iterator is linked to a @code{define_subst}. It is declared 11261implicitly by the first appearance of the corresponding 11262@code{define_subst_attr}, and it is not allowed to define it explicitly. 11263 11264Declarations of subst-attributes have the following syntax: 11265 11266@findex define_subst_attr 11267@smallexample 11268(define_subst_attr "@var{name}" 11269 "@var{subst-name}" 11270 "@var{no-subst-value}" 11271 "@var{subst-applied-value}") 11272@end smallexample 11273 11274@var{name} is a string with which the given subst-attribute could be 11275referred to. 11276 11277@var{subst-name} shows which @code{define_subst} should be applied to an 11278RTL-template if the given subst-attribute is present in the 11279RTL-template. 11280 11281@var{no-subst-value} is a value with which subst-attribute would be 11282replaced in the first copy of the original RTL-template. 11283 11284@var{subst-applied-value} is a value with which subst-attribute would be 11285replaced in the second copy of the original RTL-template. 11286 11287@node Parameterized Names 11288@subsection Parameterized Names 11289@cindex @samp{@@} in instruction pattern names 11290Ports sometimes need to apply iterators using C++ code, in order to 11291get the code or RTL pattern for a specific instruction. For example, 11292suppose we have the @samp{neon_vq<absneg><mode>} pattern given above: 11293 11294@smallexample 11295(define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG]) 11296 11297(define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")]) 11298 11299(define_insn "neon_vq<absneg><mode>" 11300 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 11301 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 11302 (match_operand:SI 2 "immediate_operand" "i")] 11303 QABSNEG))] 11304 @dots{} 11305) 11306@end smallexample 11307 11308A port might need to generate this pattern for a variable 11309@samp{QABSNEG} value and a variable @samp{VDQIW} mode. There are two 11310ways of doing this. The first is to build the rtx for the pattern 11311directly from C++ code; this is a valid technique and avoids any risk 11312of combinatorial explosion. The second is to prefix the instruction 11313name with the special character @samp{@@}, which tells GCC to generate 11314the four additional functions below. In each case, @var{name} is the 11315name of the instruction without the leading @samp{@@} character, 11316without the @samp{<@dots{}>} placeholders, and with any underscore 11317before a @samp{<@dots{}>} placeholder removed if keeping it would 11318lead to a double or trailing underscore. 11319 11320@table @samp 11321@item insn_code maybe_code_for_@var{name} (@var{i1}, @var{i2}, @dots{}) 11322See whether replacing the first @samp{<@dots{}>} placeholder with 11323iterator value @var{i1}, the second with iterator value @var{i2}, and 11324so on, gives a valid instruction. Return its code if so, otherwise 11325return @code{CODE_FOR_nothing}. 11326 11327@item insn_code code_for_@var{name} (@var{i1}, @var{i2}, @dots{}) 11328Same, but abort the compiler if the requested instruction does not exist. 11329 11330@item rtx maybe_gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{}) 11331Check for a valid instruction in the same way as 11332@code{maybe_code_for_@var{name}}. If the instruction exists, 11333generate an instance of it using the operand values given by @var{op0}, 11334@var{op1}, and so on, otherwise return null. 11335 11336@item rtx gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{}) 11337Same, but abort the compiler if the requested instruction does not exist, 11338or if the instruction generator invoked the @code{FAIL} macro. 11339@end table 11340 11341For example, changing the pattern above to: 11342 11343@smallexample 11344(define_insn "@@neon_vq<absneg><mode>" 11345 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 11346 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 11347 (match_operand:SI 2 "immediate_operand" "i")] 11348 QABSNEG))] 11349 @dots{} 11350) 11351@end smallexample 11352 11353would define the same patterns as before, but in addition would generate 11354the four functions below: 11355 11356@smallexample 11357insn_code maybe_code_for_neon_vq (int, machine_mode); 11358insn_code code_for_neon_vq (int, machine_mode); 11359rtx maybe_gen_neon_vq (int, machine_mode, rtx, rtx, rtx); 11360rtx gen_neon_vq (int, machine_mode, rtx, rtx, rtx); 11361@end smallexample 11362 11363Calling @samp{code_for_neon_vq (UNSPEC_VQABS, V8QImode)} 11364would then give @code{CODE_FOR_neon_vqabsv8qi}. 11365 11366It is possible to have multiple @samp{@@} patterns with the same 11367name and same types of iterator. For example: 11368 11369@smallexample 11370(define_insn "@@some_arithmetic_op<mode>" 11371 [(set (match_operand:INTEGER_MODES 0 "register_operand") @dots{})] 11372 @dots{} 11373) 11374 11375(define_insn "@@some_arithmetic_op<mode>" 11376 [(set (match_operand:FLOAT_MODES 0 "register_operand") @dots{})] 11377 @dots{} 11378) 11379@end smallexample 11380 11381would produce a single set of functions that handles both 11382@code{INTEGER_MODES} and @code{FLOAT_MODES}. 11383 11384It is also possible for these @samp{@@} patterns to have different 11385numbers of operands from each other. For example, patterns with 11386a binary rtl code might take three operands (one output and two inputs) 11387while patterns with a ternary rtl code might take four operands (one 11388output and three inputs). This combination would produce separate 11389@samp{maybe_gen_@var{name}} and @samp{gen_@var{name}} functions for 11390each operand count, but it would still produce a single 11391@samp{maybe_code_for_@var{name}} and a single @samp{code_for_@var{name}}. 11392 11393@end ifset 11394