1@c Copyright (C) 1988-2021 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 1637An 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_memory_constraint}. 4568@end deffn 4569 4570@deffn {MD Expression} define_relaxed_memory_constraint name docstring exp 4571The test expression in a @code{define_memory_constraint} can assume 4572that @code{TARGET_LEGITIMATE_ADDRESS_P} holds for the address inside 4573a @code{mem} rtx and so it does not need to test this condition itself. 4574In other words, a @code{define_memory_constraint} test of the form: 4575 4576@smallexample 4577(match_test "mem") 4578@end smallexample 4579 4580is enough to test whether an rtx is a @code{mem} @emph{and} whether 4581its address satisfies @code{TARGET_MEM_CONSTRAINT} (which is usually 4582@samp{'m'}). Thus the conditions imposed by a @code{define_memory_constraint} 4583always apply on top of the conditions imposed by @code{TARGET_MEM_CONSTRAINT}. 4584 4585However, it is sometimes useful to define memory constraints that allow 4586addresses beyond those accepted by @code{TARGET_LEGITIMATE_ADDRESS_P}. 4587@code{define_relaxed_memory_constraint} exists for this case. 4588The test expression in a @code{define_relaxed_memory_constraint} is 4589applied with no preconditions, so that the expression can determine 4590``from scratch'' exactly which addresses are valid and which are not. 4591 4592The syntax and semantics are otherwise identical to 4593@code{define_memory_constraint}. 4594@end deffn 4595 4596@deffn {MD Expression} define_address_constraint name docstring exp 4597Use this expression for constraints that match a subset of all address 4598operands: that is, @code{reload} can make the constraint match by 4599converting the operand to the form @samp{@w{(reg @var{X})}}, again 4600with @var{X} a base register. 4601 4602Constraints defined with @code{define_address_constraint} can only be 4603used with the @code{address_operand} predicate, or machine-specific 4604predicates that work the same way. They are treated analogously to 4605the generic @samp{p} constraint. 4606 4607The syntax and semantics are otherwise identical to 4608@code{define_constraint}. 4609@end deffn 4610 4611For historical reasons, names beginning with the letters @samp{G H} 4612are reserved for constraints that match only @code{const_double}s, and 4613names beginning with the letters @samp{I J K L M N O P} are reserved 4614for constraints that match only @code{const_int}s. This may change in 4615the future. For the time being, constraints with these names must be 4616written in a stylized form, so that @code{genpreds} can tell you did 4617it correctly: 4618 4619@smallexample 4620@group 4621(define_constraint "[@var{GHIJKLMNOP}]@dots{}" 4622 "@var{doc}@dots{}" 4623 (and (match_code "const_int") ; @r{@code{const_double} for G/H} 4624 @var{condition}@dots{})) ; @r{usually a @code{match_test}} 4625@end group 4626@end smallexample 4627@c the semicolons line up in the formatted manual 4628 4629It is fine to use names beginning with other letters for constraints 4630that match @code{const_double}s or @code{const_int}s. 4631 4632Each docstring in a constraint definition should be one or more complete 4633sentences, marked up in Texinfo format. @emph{They are currently unused.} 4634In the future they will be copied into the GCC manual, in @ref{Machine 4635Constraints}, replacing the hand-maintained tables currently found in 4636that section. Also, in the future the compiler may use this to give 4637more helpful diagnostics when poor choice of @code{asm} constraints 4638causes a reload failure. 4639 4640If you put the pseudo-Texinfo directive @samp{@@internal} at the 4641beginning of a docstring, then (in the future) it will appear only in 4642the internals manual's version of the machine-specific constraint tables. 4643Use this for constraints that should not appear in @code{asm} statements. 4644 4645@node C Constraint Interface 4646@subsection Testing constraints from C 4647@cindex testing constraints 4648@cindex constraints, testing 4649 4650It is occasionally useful to test a constraint from C code rather than 4651implicitly via the constraint string in a @code{match_operand}. The 4652generated file @file{tm_p.h} declares a few interfaces for working 4653with constraints. At present these are defined for all constraints 4654except @code{g} (which is equivalent to @code{general_operand}). 4655 4656Some valid constraint names are not valid C identifiers, so there is a 4657mangling scheme for referring to them from C@. Constraint names that 4658do not contain angle brackets or underscores are left unchanged. 4659Underscores are doubled, each @samp{<} is replaced with @samp{_l}, and 4660each @samp{>} with @samp{_g}. Here are some examples: 4661 4662@c the @c's prevent double blank lines in the printed manual. 4663@example 4664@multitable {Original} {Mangled} 4665@item @strong{Original} @tab @strong{Mangled} @c 4666@item @code{x} @tab @code{x} @c 4667@item @code{P42x} @tab @code{P42x} @c 4668@item @code{P4_x} @tab @code{P4__x} @c 4669@item @code{P4>x} @tab @code{P4_gx} @c 4670@item @code{P4>>} @tab @code{P4_g_g} @c 4671@item @code{P4_g>} @tab @code{P4__g_g} @c 4672@end multitable 4673@end example 4674 4675Throughout this section, the variable @var{c} is either a constraint 4676in the abstract sense, or a constant from @code{enum constraint_num}; 4677the variable @var{m} is a mangled constraint name (usually as part of 4678a larger identifier). 4679 4680@deftp Enum constraint_num 4681For each constraint except @code{g}, there is a corresponding 4682enumeration constant: @samp{CONSTRAINT_} plus the mangled name of the 4683constraint. Functions that take an @code{enum constraint_num} as an 4684argument expect one of these constants. 4685@end deftp 4686 4687@deftypefun {inline bool} satisfies_constraint_@var{m} (rtx @var{exp}) 4688For each non-register constraint @var{m} except @code{g}, there is 4689one of these functions; it returns @code{true} if @var{exp} satisfies the 4690constraint. These functions are only visible if @file{rtl.h} was included 4691before @file{tm_p.h}. 4692@end deftypefun 4693 4694@deftypefun bool constraint_satisfied_p (rtx @var{exp}, enum constraint_num @var{c}) 4695Like the @code{satisfies_constraint_@var{m}} functions, but the 4696constraint to test is given as an argument, @var{c}. If @var{c} 4697specifies a register constraint, this function will always return 4698@code{false}. 4699@end deftypefun 4700 4701@deftypefun {enum reg_class} reg_class_for_constraint (enum constraint_num @var{c}) 4702Returns the register class associated with @var{c}. If @var{c} is not 4703a register constraint, or those registers are not available for the 4704currently selected subtarget, returns @code{NO_REGS}. 4705@end deftypefun 4706 4707Here is an example use of @code{satisfies_constraint_@var{m}}. In 4708peephole optimizations (@pxref{Peephole Definitions}), operand 4709constraint strings are ignored, so if there are relevant constraints, 4710they must be tested in the C condition. In the example, the 4711optimization is applied if operand 2 does @emph{not} satisfy the 4712@samp{K} constraint. (This is a simplified version of a peephole 4713definition from the i386 machine description.) 4714 4715@smallexample 4716(define_peephole2 4717 [(match_scratch:SI 3 "r") 4718 (set (match_operand:SI 0 "register_operand" "") 4719 (mult:SI (match_operand:SI 1 "memory_operand" "") 4720 (match_operand:SI 2 "immediate_operand" "")))] 4721 4722 "!satisfies_constraint_K (operands[2])" 4723 4724 [(set (match_dup 3) (match_dup 1)) 4725 (set (match_dup 0) (mult:SI (match_dup 3) (match_dup 2)))] 4726 4727 "") 4728@end smallexample 4729 4730@node Standard Names 4731@section Standard Pattern Names For Generation 4732@cindex standard pattern names 4733@cindex pattern names 4734@cindex names, pattern 4735 4736Here is a table of the instruction names that are meaningful in the RTL 4737generation pass of the compiler. Giving one of these names to an 4738instruction pattern tells the RTL generation pass that it can use the 4739pattern to accomplish a certain task. 4740 4741@table @asis 4742@cindex @code{mov@var{m}} instruction pattern 4743@item @samp{mov@var{m}} 4744Here @var{m} stands for a two-letter machine mode name, in lowercase. 4745This instruction pattern moves data with that machine mode from operand 47461 to operand 0. For example, @samp{movsi} moves full-word data. 4747 4748If operand 0 is a @code{subreg} with mode @var{m} of a register whose 4749own mode is wider than @var{m}, the effect of this instruction is 4750to store the specified value in the part of the register that corresponds 4751to mode @var{m}. Bits outside of @var{m}, but which are within the 4752same target word as the @code{subreg} are undefined. Bits which are 4753outside the target word are left unchanged. 4754 4755This class of patterns is special in several ways. First of all, each 4756of these names up to and including full word size @emph{must} be defined, 4757because there is no other way to copy a datum from one place to another. 4758If there are patterns accepting operands in larger modes, 4759@samp{mov@var{m}} must be defined for integer modes of those sizes. 4760 4761Second, these patterns are not used solely in the RTL generation pass. 4762Even the reload pass can generate move insns to copy values from stack 4763slots into temporary registers. When it does so, one of the operands is 4764a hard register and the other is an operand that can need to be reloaded 4765into a register. 4766 4767@findex force_reg 4768Therefore, when given such a pair of operands, the pattern must generate 4769RTL which needs no reloading and needs no temporary registers---no 4770registers other than the operands. For example, if you support the 4771pattern with a @code{define_expand}, then in such a case the 4772@code{define_expand} mustn't call @code{force_reg} or any other such 4773function which might generate new pseudo registers. 4774 4775This requirement exists even for subword modes on a RISC machine where 4776fetching those modes from memory normally requires several insns and 4777some temporary registers. 4778 4779@findex change_address 4780During reload a memory reference with an invalid address may be passed 4781as an operand. Such an address will be replaced with a valid address 4782later in the reload pass. In this case, nothing may be done with the 4783address except to use it as it stands. If it is copied, it will not be 4784replaced with a valid address. No attempt should be made to make such 4785an address into a valid address and no routine (such as 4786@code{change_address}) that will do so may be called. Note that 4787@code{general_operand} will fail when applied to such an address. 4788 4789@findex reload_in_progress 4790The global variable @code{reload_in_progress} (which must be explicitly 4791declared if required) can be used to determine whether such special 4792handling is required. 4793 4794The variety of operands that have reloads depends on the rest of the 4795machine description, but typically on a RISC machine these can only be 4796pseudo registers that did not get hard registers, while on other 4797machines explicit memory references will get optional reloads. 4798 4799If a scratch register is required to move an object to or from memory, 4800it can be allocated using @code{gen_reg_rtx} prior to life analysis. 4801 4802If there are cases which need scratch registers during or after reload, 4803you must provide an appropriate secondary_reload target hook. 4804 4805@findex can_create_pseudo_p 4806The macro @code{can_create_pseudo_p} can be used to determine if it 4807is unsafe to create new pseudo registers. If this variable is nonzero, then 4808it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo. 4809 4810The constraints on a @samp{mov@var{m}} must permit moving any hard 4811register to any other hard register provided that 4812@code{TARGET_HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and 4813@code{TARGET_REGISTER_MOVE_COST} applied to their classes returns a value 4814of 2. 4815 4816It is obligatory to support floating point @samp{mov@var{m}} 4817instructions into and out of any registers that can hold fixed point 4818values, because unions and structures (which have modes @code{SImode} or 4819@code{DImode}) can be in those registers and they may have floating 4820point members. 4821 4822There may also be a need to support fixed point @samp{mov@var{m}} 4823instructions in and out of floating point registers. Unfortunately, I 4824have forgotten why this was so, and I don't know whether it is still 4825true. If @code{TARGET_HARD_REGNO_MODE_OK} rejects fixed point values in 4826floating point registers, then the constraints of the fixed point 4827@samp{mov@var{m}} instructions must be designed to avoid ever trying to 4828reload into a floating point register. 4829 4830@cindex @code{reload_in} instruction pattern 4831@cindex @code{reload_out} instruction pattern 4832@item @samp{reload_in@var{m}} 4833@itemx @samp{reload_out@var{m}} 4834These named patterns have been obsoleted by the target hook 4835@code{secondary_reload}. 4836 4837Like @samp{mov@var{m}}, but used when a scratch register is required to 4838move between operand 0 and operand 1. Operand 2 describes the scratch 4839register. See the discussion of the @code{SECONDARY_RELOAD_CLASS} 4840macro in @pxref{Register Classes}. 4841 4842There are special restrictions on the form of the @code{match_operand}s 4843used in these patterns. First, only the predicate for the reload 4844operand is examined, i.e., @code{reload_in} examines operand 1, but not 4845the predicates for operand 0 or 2. Second, there may be only one 4846alternative in the constraints. Third, only a single register class 4847letter may be used for the constraint; subsequent constraint letters 4848are ignored. As a special exception, an empty constraint string 4849matches the @code{ALL_REGS} register class. This may relieve ports 4850of the burden of defining an @code{ALL_REGS} constraint letter just 4851for these patterns. 4852 4853@cindex @code{movstrict@var{m}} instruction pattern 4854@item @samp{movstrict@var{m}} 4855Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg} 4856with mode @var{m} of a register whose natural mode is wider, 4857the @samp{movstrict@var{m}} instruction is guaranteed not to alter 4858any of the register except the part which belongs to mode @var{m}. 4859 4860@cindex @code{movmisalign@var{m}} instruction pattern 4861@item @samp{movmisalign@var{m}} 4862This variant of a move pattern is designed to load or store a value 4863from a memory address that is not naturally aligned for its mode. 4864For a store, the memory will be in operand 0; for a load, the memory 4865will be in operand 1. The other operand is guaranteed not to be a 4866memory, so that it's easy to tell whether this is a load or store. 4867 4868This pattern is used by the autovectorizer, and when expanding a 4869@code{MISALIGNED_INDIRECT_REF} expression. 4870 4871@cindex @code{load_multiple} instruction pattern 4872@item @samp{load_multiple} 4873Load several consecutive memory locations into consecutive registers. 4874Operand 0 is the first of the consecutive registers, operand 1 4875is the first memory location, and operand 2 is a constant: the 4876number of consecutive registers. 4877 4878Define this only if the target machine really has such an instruction; 4879do not define this if the most efficient way of loading consecutive 4880registers from memory is to do them one at a time. 4881 4882On some machines, there are restrictions as to which consecutive 4883registers can be stored into memory, such as particular starting or 4884ending register numbers or only a range of valid counts. For those 4885machines, use a @code{define_expand} (@pxref{Expander Definitions}) 4886and make the pattern fail if the restrictions are not met. 4887 4888Write the generated insn as a @code{parallel} with elements being a 4889@code{set} of one register from the appropriate memory location (you may 4890also need @code{use} or @code{clobber} elements). Use a 4891@code{match_parallel} (@pxref{RTL Template}) to recognize the insn. See 4892@file{rs6000.md} for examples of the use of this insn pattern. 4893 4894@cindex @samp{store_multiple} instruction pattern 4895@item @samp{store_multiple} 4896Similar to @samp{load_multiple}, but store several consecutive registers 4897into consecutive memory locations. Operand 0 is the first of the 4898consecutive memory locations, operand 1 is the first register, and 4899operand 2 is a constant: the number of consecutive registers. 4900 4901@cindex @code{vec_load_lanes@var{m}@var{n}} instruction pattern 4902@item @samp{vec_load_lanes@var{m}@var{n}} 4903Perform an interleaved load of several vectors from memory operand 1 4904into register operand 0. Both operands have mode @var{m}. The register 4905operand is viewed as holding consecutive vectors of mode @var{n}, 4906while the memory operand is a flat array that contains the same number 4907of elements. The operation is equivalent to: 4908 4909@smallexample 4910int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4911for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4912 for (i = 0; i < c; i++) 4913 operand0[i][j] = operand1[j * c + i]; 4914@end smallexample 4915 4916For example, @samp{vec_load_lanestiv4hi} loads 8 16-bit values 4917from memory into a register of mode @samp{TI}@. The register 4918contains two consecutive vectors of mode @samp{V4HI}@. 4919 4920This pattern can only be used if: 4921@smallexample 4922TARGET_ARRAY_MODE_SUPPORTED_P (@var{n}, @var{c}) 4923@end smallexample 4924is true. GCC assumes that, if a target supports this kind of 4925instruction for some mode @var{n}, it also supports unaligned 4926loads for vectors of mode @var{n}. 4927 4928This pattern is not allowed to @code{FAIL}. 4929 4930@cindex @code{vec_mask_load_lanes@var{m}@var{n}} instruction pattern 4931@item @samp{vec_mask_load_lanes@var{m}@var{n}} 4932Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional 4933mask operand (operand 2) that specifies which elements of the destination 4934vectors should be loaded. Other elements of the destination 4935vectors are set to zero. The operation is equivalent to: 4936 4937@smallexample 4938int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4939for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4940 if (operand2[j]) 4941 for (i = 0; i < c; i++) 4942 operand0[i][j] = operand1[j * c + i]; 4943 else 4944 for (i = 0; i < c; i++) 4945 operand0[i][j] = 0; 4946@end smallexample 4947 4948This pattern is not allowed to @code{FAIL}. 4949 4950@cindex @code{vec_store_lanes@var{m}@var{n}} instruction pattern 4951@item @samp{vec_store_lanes@var{m}@var{n}} 4952Equivalent to @samp{vec_load_lanes@var{m}@var{n}}, with the memory 4953and register operands reversed. That is, the instruction is 4954equivalent to: 4955 4956@smallexample 4957int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4958for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4959 for (i = 0; i < c; i++) 4960 operand0[j * c + i] = operand1[i][j]; 4961@end smallexample 4962 4963for a memory operand 0 and register operand 1. 4964 4965This pattern is not allowed to @code{FAIL}. 4966 4967@cindex @code{vec_mask_store_lanes@var{m}@var{n}} instruction pattern 4968@item @samp{vec_mask_store_lanes@var{m}@var{n}} 4969Like @samp{vec_store_lanes@var{m}@var{n}}, but takes an additional 4970mask operand (operand 2) that specifies which elements of the source 4971vectors should be stored. The operation is equivalent to: 4972 4973@smallexample 4974int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4975for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4976 if (operand2[j]) 4977 for (i = 0; i < c; i++) 4978 operand0[j * c + i] = operand1[i][j]; 4979@end smallexample 4980 4981This pattern is not allowed to @code{FAIL}. 4982 4983@cindex @code{gather_load@var{m}@var{n}} instruction pattern 4984@item @samp{gather_load@var{m}@var{n}} 4985Load several separate memory locations into a vector of mode @var{m}. 4986Operand 1 is a scalar base address and operand 2 is a vector of mode @var{n} 4987containing offsets from that base. Operand 0 is a destination vector with 4988the same number of elements as @var{n}. For each element index @var{i}: 4989 4990@itemize @bullet 4991@item 4992extend the offset element @var{i} to address width, using zero 4993extension if operand 3 is 1 and sign extension if operand 3 is zero; 4994@item 4995multiply the extended offset by operand 4; 4996@item 4997add the result to the base; and 4998@item 4999load the value at that address into element @var{i} of operand 0. 5000@end itemize 5001 5002The value of operand 3 does not matter if the offsets are already 5003address width. 5004 5005@cindex @code{mask_gather_load@var{m}@var{n}} instruction pattern 5006@item @samp{mask_gather_load@var{m}@var{n}} 5007Like @samp{gather_load@var{m}@var{n}}, but takes an extra mask operand as 5008operand 5. Bit @var{i} of the mask is set if element @var{i} 5009of the result should be loaded from memory and clear if element @var{i} 5010of the result should be set to zero. 5011 5012@cindex @code{scatter_store@var{m}@var{n}} instruction pattern 5013@item @samp{scatter_store@var{m}@var{n}} 5014Store a vector of mode @var{m} into several distinct memory locations. 5015Operand 0 is a scalar base address and operand 1 is a vector of mode 5016@var{n} containing offsets from that base. Operand 4 is the vector of 5017values that should be stored, which has the same number of elements as 5018@var{n}. For each element index @var{i}: 5019 5020@itemize @bullet 5021@item 5022extend the offset element @var{i} to address width, using zero 5023extension if operand 2 is 1 and sign extension if operand 2 is zero; 5024@item 5025multiply the extended offset by operand 3; 5026@item 5027add the result to the base; and 5028@item 5029store element @var{i} of operand 4 to that address. 5030@end itemize 5031 5032The value of operand 2 does not matter if the offsets are already 5033address width. 5034 5035@cindex @code{mask_scatter_store@var{m}@var{n}} instruction pattern 5036@item @samp{mask_scatter_store@var{m}@var{n}} 5037Like @samp{scatter_store@var{m}@var{n}}, but takes an extra mask operand as 5038operand 5. Bit @var{i} of the mask is set if element @var{i} 5039of the result should be stored to memory. 5040 5041@cindex @code{vec_set@var{m}} instruction pattern 5042@item @samp{vec_set@var{m}} 5043Set given field in the vector value. Operand 0 is the vector to modify, 5044operand 1 is new value of field and operand 2 specify the field index. 5045 5046@cindex @code{vec_extract@var{m}@var{n}} instruction pattern 5047@item @samp{vec_extract@var{m}@var{n}} 5048Extract given field from the vector value. Operand 1 is the vector, operand 2 5049specify field index and operand 0 place to store value into. The 5050@var{n} mode is the mode of the field or vector of fields that should be 5051extracted, should be either element mode of the vector mode @var{m}, or 5052a vector mode with the same element mode and smaller number of elements. 5053If @var{n} is a vector mode, the index is counted in units of that mode. 5054 5055@cindex @code{vec_init@var{m}@var{n}} instruction pattern 5056@item @samp{vec_init@var{m}@var{n}} 5057Initialize the vector to given values. Operand 0 is the vector to initialize 5058and operand 1 is parallel containing values for individual fields. The 5059@var{n} mode is the mode of the elements, should be either element mode of 5060the vector mode @var{m}, or a vector mode with the same element mode and 5061smaller number of elements. 5062 5063@cindex @code{vec_duplicate@var{m}} instruction pattern 5064@item @samp{vec_duplicate@var{m}} 5065Initialize vector output operand 0 so that each element has the value given 5066by scalar input operand 1. The vector has mode @var{m} and the scalar has 5067the mode appropriate for one element of @var{m}. 5068 5069This pattern only handles duplicates of non-constant inputs. Constant 5070vectors go through the @code{mov@var{m}} pattern instead. 5071 5072This pattern is not allowed to @code{FAIL}. 5073 5074@cindex @code{vec_series@var{m}} instruction pattern 5075@item @samp{vec_series@var{m}} 5076Initialize vector output operand 0 so that element @var{i} is equal to 5077operand 1 plus @var{i} times operand 2. In other words, create a linear 5078series whose base value is operand 1 and whose step is operand 2. 5079 5080The vector output has mode @var{m} and the scalar inputs have the mode 5081appropriate for one element of @var{m}. This pattern is not used for 5082floating-point vectors, in order to avoid having to specify the 5083rounding behavior for @var{i} > 1. 5084 5085This pattern is not allowed to @code{FAIL}. 5086 5087@cindex @code{while_ult@var{m}@var{n}} instruction pattern 5088@item @code{while_ult@var{m}@var{n}} 5089Set operand 0 to a mask that is true while incrementing operand 1 5090gives a value that is less than operand 2. Operand 0 has mode @var{n} 5091and operands 1 and 2 are scalar integers of mode @var{m}. 5092The operation is equivalent to: 5093 5094@smallexample 5095operand0[0] = operand1 < operand2; 5096for (i = 1; i < GET_MODE_NUNITS (@var{n}); i++) 5097 operand0[i] = operand0[i - 1] && (operand1 + i < operand2); 5098@end smallexample 5099 5100@cindex @code{check_raw_ptrs@var{m}} instruction pattern 5101@item @samp{check_raw_ptrs@var{m}} 5102Check whether, given two pointers @var{a} and @var{b} and a length @var{len}, 5103a write of @var{len} bytes at @var{a} followed by a read of @var{len} bytes 5104at @var{b} can be split into interleaved byte accesses 5105@samp{@var{a}[0], @var{b}[0], @var{a}[1], @var{b}[1], @dots{}} 5106without affecting the dependencies between the bytes. Set operand 0 5107to true if the split is possible and false otherwise. 5108 5109Operands 1, 2 and 3 provide the values of @var{a}, @var{b} and @var{len} 5110respectively. Operand 4 is a constant integer that provides the known 5111common alignment of @var{a} and @var{b}. All inputs have mode @var{m}. 5112 5113This split is possible if: 5114 5115@smallexample 5116@var{a} == @var{b} || @var{a} + @var{len} <= @var{b} || @var{b} + @var{len} <= @var{a} 5117@end smallexample 5118 5119You should only define this pattern if the target has a way of accelerating 5120the test without having to do the individual comparisons. 5121 5122@cindex @code{check_war_ptrs@var{m}} instruction pattern 5123@item @samp{check_war_ptrs@var{m}} 5124Like @samp{check_raw_ptrs@var{m}}, but with the read and write swapped round. 5125The split is possible in this case if: 5126 5127@smallexample 5128@var{b} <= @var{a} || @var{a} + @var{len} <= @var{b} 5129@end smallexample 5130 5131@cindex @code{vec_cmp@var{m}@var{n}} instruction pattern 5132@item @samp{vec_cmp@var{m}@var{n}} 5133Output a vector comparison. Operand 0 of mode @var{n} is the destination for 5134predicate in operand 1 which is a signed vector comparison with operands of 5135mode @var{m} in operands 2 and 3. Predicate is computed by element-wise 5136evaluation of the vector comparison with a truth value of all-ones and a false 5137value of all-zeros. 5138 5139@cindex @code{vec_cmpu@var{m}@var{n}} instruction pattern 5140@item @samp{vec_cmpu@var{m}@var{n}} 5141Similar to @code{vec_cmp@var{m}@var{n}} but perform unsigned vector comparison. 5142 5143@cindex @code{vec_cmpeq@var{m}@var{n}} instruction pattern 5144@item @samp{vec_cmpeq@var{m}@var{n}} 5145Similar to @code{vec_cmp@var{m}@var{n}} but perform equality or non-equality 5146vector comparison only. If @code{vec_cmp@var{m}@var{n}} 5147or @code{vec_cmpu@var{m}@var{n}} instruction pattern is supported, 5148it will be preferred over @code{vec_cmpeq@var{m}@var{n}}, so there is 5149no need to define this instruction pattern if the others are supported. 5150 5151@cindex @code{vcond@var{m}@var{n}} instruction pattern 5152@item @samp{vcond@var{m}@var{n}} 5153Output a conditional vector move. Operand 0 is the destination to 5154receive a combination of operand 1 and operand 2, which are of mode @var{m}, 5155dependent on the outcome of the predicate in operand 3 which is a signed 5156vector comparison with operands of mode @var{n} in operands 4 and 5. The 5157modes @var{m} and @var{n} should have the same size. Operand 0 5158will be set to the value @var{op1} & @var{msk} | @var{op2} & ~@var{msk} 5159where @var{msk} is computed by element-wise evaluation of the vector 5160comparison with a truth value of all-ones and a false value of all-zeros. 5161 5162@cindex @code{vcondu@var{m}@var{n}} instruction pattern 5163@item @samp{vcondu@var{m}@var{n}} 5164Similar to @code{vcond@var{m}@var{n}} but performs unsigned vector 5165comparison. 5166 5167@cindex @code{vcondeq@var{m}@var{n}} instruction pattern 5168@item @samp{vcondeq@var{m}@var{n}} 5169Similar to @code{vcond@var{m}@var{n}} but performs equality or 5170non-equality vector comparison only. If @code{vcond@var{m}@var{n}} 5171or @code{vcondu@var{m}@var{n}} instruction pattern is supported, 5172it will be preferred over @code{vcondeq@var{m}@var{n}}, so there is 5173no need to define this instruction pattern if the others are supported. 5174 5175@cindex @code{vcond_mask_@var{m}@var{n}} instruction pattern 5176@item @samp{vcond_mask_@var{m}@var{n}} 5177Similar to @code{vcond@var{m}@var{n}} but operand 3 holds a pre-computed 5178result of vector comparison. 5179 5180@cindex @code{maskload@var{m}@var{n}} instruction pattern 5181@item @samp{maskload@var{m}@var{n}} 5182Perform a masked load of vector from memory operand 1 of mode @var{m} 5183into register operand 0. Mask is provided in register operand 2 of 5184mode @var{n}. 5185 5186This pattern is not allowed to @code{FAIL}. 5187 5188@cindex @code{maskstore@var{m}@var{n}} instruction pattern 5189@item @samp{maskstore@var{m}@var{n}} 5190Perform a masked store of vector from register operand 1 of mode @var{m} 5191into memory operand 0. Mask is provided in register operand 2 of 5192mode @var{n}. 5193 5194This pattern is not allowed to @code{FAIL}. 5195 5196@cindex @code{len_load_@var{m}} instruction pattern 5197@item @samp{len_load_@var{m}} 5198Load the number of vector elements specified by operand 2 from memory 5199operand 1 into vector register operand 0, setting the other elements of 5200operand 0 to undefined values. Operands 0 and 1 have mode @var{m}, 5201which must be a vector mode. Operand 2 has whichever integer mode the 5202target prefers. If operand 2 exceeds the number of elements in mode 5203@var{m}, the behavior is undefined. If the target prefers the length 5204to be measured in bytes rather than elements, it should only implement 5205this pattern for vectors of @code{QI} elements. 5206 5207This pattern is not allowed to @code{FAIL}. 5208 5209@cindex @code{len_store_@var{m}} instruction pattern 5210@item @samp{len_store_@var{m}} 5211Store the number of vector elements specified by operand 2 from vector 5212register operand 1 into memory operand 0, leaving the other elements of 5213operand 0 unchanged. Operands 0 and 1 have mode @var{m}, which must be 5214a vector mode. Operand 2 has whichever integer mode the target prefers. 5215If operand 2 exceeds the number of elements in mode @var{m}, the behavior 5216is undefined. If the target prefers the length to be measured in bytes 5217rather than elements, it should only implement this pattern for vectors 5218of @code{QI} elements. 5219 5220This pattern is not allowed to @code{FAIL}. 5221 5222@cindex @code{vec_perm@var{m}} instruction pattern 5223@item @samp{vec_perm@var{m}} 5224Output a (variable) vector permutation. Operand 0 is the destination 5225to receive elements from operand 1 and operand 2, which are of mode 5226@var{m}. Operand 3 is the @dfn{selector}. It is an integral mode 5227vector of the same width and number of elements as mode @var{m}. 5228 5229The input elements are numbered from 0 in operand 1 through 5230@math{2*@var{N}-1} in operand 2. The elements of the selector must 5231be computed modulo @math{2*@var{N}}. Note that if 5232@code{rtx_equal_p(operand1, operand2)}, this can be implemented 5233with just operand 1 and selector elements modulo @var{N}. 5234 5235In order to make things easy for a number of targets, if there is no 5236@samp{vec_perm} pattern for mode @var{m}, but there is for mode @var{q} 5237where @var{q} is a vector of @code{QImode} of the same width as @var{m}, 5238the middle-end will lower the mode @var{m} @code{VEC_PERM_EXPR} to 5239mode @var{q}. 5240 5241See also @code{TARGET_VECTORIZER_VEC_PERM_CONST}, which performs 5242the analogous operation for constant selectors. 5243 5244@cindex @code{push@var{m}1} instruction pattern 5245@item @samp{push@var{m}1} 5246Output a push instruction. Operand 0 is value to push. Used only when 5247@code{PUSH_ROUNDING} is defined. For historical reason, this pattern may be 5248missing and in such case an @code{mov} expander is used instead, with a 5249@code{MEM} expression forming the push operation. The @code{mov} expander 5250method is deprecated. 5251 5252@cindex @code{add@var{m}3} instruction pattern 5253@item @samp{add@var{m}3} 5254Add operand 2 and operand 1, storing the result in operand 0. All operands 5255must have mode @var{m}. This can be used even on two-address machines, by 5256means of constraints requiring operands 1 and 0 to be the same location. 5257 5258@cindex @code{ssadd@var{m}3} instruction pattern 5259@cindex @code{usadd@var{m}3} instruction pattern 5260@cindex @code{sub@var{m}3} instruction pattern 5261@cindex @code{sssub@var{m}3} instruction pattern 5262@cindex @code{ussub@var{m}3} instruction pattern 5263@cindex @code{mul@var{m}3} instruction pattern 5264@cindex @code{ssmul@var{m}3} instruction pattern 5265@cindex @code{usmul@var{m}3} instruction pattern 5266@cindex @code{div@var{m}3} instruction pattern 5267@cindex @code{ssdiv@var{m}3} instruction pattern 5268@cindex @code{udiv@var{m}3} instruction pattern 5269@cindex @code{usdiv@var{m}3} instruction pattern 5270@cindex @code{mod@var{m}3} instruction pattern 5271@cindex @code{umod@var{m}3} instruction pattern 5272@cindex @code{umin@var{m}3} instruction pattern 5273@cindex @code{umax@var{m}3} instruction pattern 5274@cindex @code{and@var{m}3} instruction pattern 5275@cindex @code{ior@var{m}3} instruction pattern 5276@cindex @code{xor@var{m}3} instruction pattern 5277@item @samp{ssadd@var{m}3}, @samp{usadd@var{m}3} 5278@itemx @samp{sub@var{m}3}, @samp{sssub@var{m}3}, @samp{ussub@var{m}3} 5279@itemx @samp{mul@var{m}3}, @samp{ssmul@var{m}3}, @samp{usmul@var{m}3} 5280@itemx @samp{div@var{m}3}, @samp{ssdiv@var{m}3} 5281@itemx @samp{udiv@var{m}3}, @samp{usdiv@var{m}3} 5282@itemx @samp{mod@var{m}3}, @samp{umod@var{m}3} 5283@itemx @samp{umin@var{m}3}, @samp{umax@var{m}3} 5284@itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3} 5285Similar, for other arithmetic operations. 5286 5287@cindex @code{addv@var{m}4} instruction pattern 5288@item @samp{addv@var{m}4} 5289Like @code{add@var{m}3} but takes a @code{code_label} as operand 3 and 5290emits code to jump to it if signed overflow occurs during the addition. 5291This pattern is used to implement the built-in functions performing 5292signed integer addition with overflow checking. 5293 5294@cindex @code{subv@var{m}4} instruction pattern 5295@cindex @code{mulv@var{m}4} instruction pattern 5296@item @samp{subv@var{m}4}, @samp{mulv@var{m}4} 5297Similar, for other signed arithmetic operations. 5298 5299@cindex @code{uaddv@var{m}4} instruction pattern 5300@item @samp{uaddv@var{m}4} 5301Like @code{addv@var{m}4} but for unsigned addition. That is to 5302say, the operation is the same as signed addition but the jump 5303is taken only on unsigned overflow. 5304 5305@cindex @code{usubv@var{m}4} instruction pattern 5306@cindex @code{umulv@var{m}4} instruction pattern 5307@item @samp{usubv@var{m}4}, @samp{umulv@var{m}4} 5308Similar, for other unsigned arithmetic operations. 5309 5310@cindex @code{addptr@var{m}3} instruction pattern 5311@item @samp{addptr@var{m}3} 5312Like @code{add@var{m}3} but is guaranteed to only be used for address 5313calculations. The expanded code is not allowed to clobber the 5314condition code. It only needs to be defined if @code{add@var{m}3} 5315sets the condition code. If adds used for address calculations and 5316normal adds are not compatible it is required to expand a distinct 5317pattern (e.g.@: using an unspec). The pattern is used by LRA to emit 5318address calculations. @code{add@var{m}3} is used if 5319@code{addptr@var{m}3} is not defined. 5320 5321@cindex @code{fma@var{m}4} instruction pattern 5322@item @samp{fma@var{m}4} 5323Multiply operand 2 and operand 1, then add operand 3, storing the 5324result in operand 0 without doing an intermediate rounding step. All 5325operands must have mode @var{m}. This pattern is used to implement 5326the @code{fma}, @code{fmaf}, and @code{fmal} builtin functions from 5327the ISO C99 standard. 5328 5329@cindex @code{fms@var{m}4} instruction pattern 5330@item @samp{fms@var{m}4} 5331Like @code{fma@var{m}4}, except operand 3 subtracted from the 5332product instead of added to the product. This is represented 5333in the rtl as 5334 5335@smallexample 5336(fma:@var{m} @var{op1} @var{op2} (neg:@var{m} @var{op3})) 5337@end smallexample 5338 5339@cindex @code{fnma@var{m}4} instruction pattern 5340@item @samp{fnma@var{m}4} 5341Like @code{fma@var{m}4} except that the intermediate product 5342is negated before being added to operand 3. This is represented 5343in the rtl as 5344 5345@smallexample 5346(fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} @var{op3}) 5347@end smallexample 5348 5349@cindex @code{fnms@var{m}4} instruction pattern 5350@item @samp{fnms@var{m}4} 5351Like @code{fms@var{m}4} except that the intermediate product 5352is negated before subtracting operand 3. This is represented 5353in the rtl as 5354 5355@smallexample 5356(fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} (neg:@var{m} @var{op3})) 5357@end smallexample 5358 5359@cindex @code{min@var{m}3} instruction pattern 5360@cindex @code{max@var{m}3} instruction pattern 5361@item @samp{smin@var{m}3}, @samp{smax@var{m}3} 5362Signed minimum and maximum operations. When used with floating point, 5363if both operands are zeros, or if either operand is @code{NaN}, then 5364it is unspecified which of the two operands is returned as the result. 5365 5366@cindex @code{fmin@var{m}3} instruction pattern 5367@cindex @code{fmax@var{m}3} instruction pattern 5368@item @samp{fmin@var{m}3}, @samp{fmax@var{m}3} 5369IEEE-conformant minimum and maximum operations. If one operand is a quiet 5370@code{NaN}, then the other operand is returned. If both operands are quiet 5371@code{NaN}, then a quiet @code{NaN} is returned. In the case when gcc supports 5372signaling @code{NaN} (-fsignaling-nans) an invalid floating point exception is 5373raised and a quiet @code{NaN} is returned. 5374 5375All operands have mode @var{m}, which is a scalar or vector 5376floating-point mode. These patterns are not allowed to @code{FAIL}. 5377 5378@cindex @code{reduc_smin_scal_@var{m}} instruction pattern 5379@cindex @code{reduc_smax_scal_@var{m}} instruction pattern 5380@item @samp{reduc_smin_scal_@var{m}}, @samp{reduc_smax_scal_@var{m}} 5381Find the signed minimum/maximum of the elements of a vector. The vector is 5382operand 1, and operand 0 is the scalar result, with mode equal to the mode of 5383the elements of the input vector. 5384 5385@cindex @code{reduc_umin_scal_@var{m}} instruction pattern 5386@cindex @code{reduc_umax_scal_@var{m}} instruction pattern 5387@item @samp{reduc_umin_scal_@var{m}}, @samp{reduc_umax_scal_@var{m}} 5388Find the unsigned minimum/maximum of the elements of a vector. The vector is 5389operand 1, and operand 0 is the scalar result, with mode equal to the mode of 5390the elements of the input vector. 5391 5392@cindex @code{reduc_plus_scal_@var{m}} instruction pattern 5393@item @samp{reduc_plus_scal_@var{m}} 5394Compute the sum of the elements of a vector. The vector is operand 1, and 5395operand 0 is the scalar result, with mode equal to the mode of the elements of 5396the input vector. 5397 5398@cindex @code{reduc_and_scal_@var{m}} instruction pattern 5399@item @samp{reduc_and_scal_@var{m}} 5400@cindex @code{reduc_ior_scal_@var{m}} instruction pattern 5401@itemx @samp{reduc_ior_scal_@var{m}} 5402@cindex @code{reduc_xor_scal_@var{m}} instruction pattern 5403@itemx @samp{reduc_xor_scal_@var{m}} 5404Compute the bitwise @code{AND}/@code{IOR}/@code{XOR} reduction of the elements 5405of a vector of mode @var{m}. Operand 1 is the vector input and operand 0 5406is the scalar result. The mode of the scalar result is the same as one 5407element of @var{m}. 5408 5409@cindex @code{extract_last_@var{m}} instruction pattern 5410@item @code{extract_last_@var{m}} 5411Find the last set bit in mask operand 1 and extract the associated element 5412of vector operand 2. Store the result in scalar operand 0. Operand 2 5413has vector mode @var{m} while operand 0 has the mode appropriate for one 5414element of @var{m}. Operand 1 has the usual mask mode for vectors of mode 5415@var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}. 5416 5417@cindex @code{fold_extract_last_@var{m}} instruction pattern 5418@item @code{fold_extract_last_@var{m}} 5419If any bits of mask operand 2 are set, find the last set bit, extract 5420the associated element from vector operand 3, and store the result 5421in operand 0. Store operand 1 in operand 0 otherwise. Operand 3 5422has mode @var{m} and operands 0 and 1 have the mode appropriate for 5423one element of @var{m}. Operand 2 has the usual mask mode for vectors 5424of mode @var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}. 5425 5426@cindex @code{fold_left_plus_@var{m}} instruction pattern 5427@item @code{fold_left_plus_@var{m}} 5428Take scalar operand 1 and successively add each element from vector 5429operand 2. Store the result in scalar operand 0. The vector has 5430mode @var{m} and the scalars have the mode appropriate for one 5431element of @var{m}. The operation is strictly in-order: there is 5432no reassociation. 5433 5434@cindex @code{mask_fold_left_plus_@var{m}} instruction pattern 5435@item @code{mask_fold_left_plus_@var{m}} 5436Like @samp{fold_left_plus_@var{m}}, but takes an additional mask operand 5437(operand 3) that specifies which elements of the source vector should be added. 5438 5439@cindex @code{sdot_prod@var{m}} instruction pattern 5440@item @samp{sdot_prod@var{m}} 5441@cindex @code{udot_prod@var{m}} instruction pattern 5442@itemx @samp{udot_prod@var{m}} 5443Compute the sum of the products of two signed/unsigned elements. 5444Operand 1 and operand 2 are of the same mode. Their product, which is of a 5445wider mode, is computed and added to operand 3. Operand 3 is of a mode equal or 5446wider than the mode of the product. The result is placed in operand 0, which 5447is of the same mode as operand 3. 5448 5449@cindex @code{ssad@var{m}} instruction pattern 5450@item @samp{ssad@var{m}} 5451@cindex @code{usad@var{m}} instruction pattern 5452@item @samp{usad@var{m}} 5453Compute the sum of absolute differences of two signed/unsigned elements. 5454Operand 1 and operand 2 are of the same mode. Their absolute difference, which 5455is of a wider mode, is computed and added to operand 3. Operand 3 is of a mode 5456equal or wider than the mode of the absolute difference. The result is placed 5457in operand 0, which is of the same mode as operand 3. 5458 5459@cindex @code{widen_ssum@var{m3}} instruction pattern 5460@item @samp{widen_ssum@var{m3}} 5461@cindex @code{widen_usum@var{m3}} instruction pattern 5462@itemx @samp{widen_usum@var{m3}} 5463Operands 0 and 2 are of the same mode, which is wider than the mode of 5464operand 1. Add operand 1 to operand 2 and place the widened result in 5465operand 0. (This is used express accumulation of elements into an accumulator 5466of a wider mode.) 5467 5468@cindex @code{smulhs@var{m3}} instruction pattern 5469@item @samp{smulhs@var{m3}} 5470@cindex @code{umulhs@var{m3}} instruction pattern 5471@itemx @samp{umulhs@var{m3}} 5472Signed/unsigned multiply high with scale. This is equivalent to the C code: 5473@smallexample 5474narrow op0, op1, op2; 5475@dots{} 5476op0 = (narrow) (((wide) op1 * (wide) op2) >> (N / 2 - 1)); 5477@end smallexample 5478where the sign of @samp{narrow} determines whether this is a signed 5479or unsigned operation, and @var{N} is the size of @samp{wide} in bits. 5480 5481@cindex @code{smulhrs@var{m3}} instruction pattern 5482@item @samp{smulhrs@var{m3}} 5483@cindex @code{umulhrs@var{m3}} instruction pattern 5484@itemx @samp{umulhrs@var{m3}} 5485Signed/unsigned multiply high with round and scale. This is 5486equivalent to the C code: 5487@smallexample 5488narrow op0, op1, op2; 5489@dots{} 5490op0 = (narrow) (((((wide) op1 * (wide) op2) >> (N / 2 - 2)) + 1) >> 1); 5491@end smallexample 5492where the sign of @samp{narrow} determines whether this is a signed 5493or unsigned operation, and @var{N} is the size of @samp{wide} in bits. 5494 5495@cindex @code{sdiv_pow2@var{m3}} instruction pattern 5496@item @samp{sdiv_pow2@var{m3}} 5497@cindex @code{sdiv_pow2@var{m3}} instruction pattern 5498@itemx @samp{sdiv_pow2@var{m3}} 5499Signed division by power-of-2 immediate. Equivalent to: 5500@smallexample 5501signed op0, op1; 5502@dots{} 5503op0 = op1 / (1 << imm); 5504@end smallexample 5505 5506@cindex @code{vec_shl_insert_@var{m}} instruction pattern 5507@item @samp{vec_shl_insert_@var{m}} 5508Shift the elements in vector input operand 1 left one element (i.e.@: 5509away from element 0) and fill the vacated element 0 with the scalar 5510in operand 2. Store the result in vector output operand 0. Operands 55110 and 1 have mode @var{m} and operand 2 has the mode appropriate for 5512one element of @var{m}. 5513 5514@cindex @code{vec_shl_@var{m}} instruction pattern 5515@item @samp{vec_shl_@var{m}} 5516Whole vector left shift in bits, i.e.@: away from element 0. 5517Operand 1 is a vector to be shifted. 5518Operand 2 is an integer shift amount in bits. 5519Operand 0 is where the resulting shifted vector is stored. 5520The output and input vectors should have the same modes. 5521 5522@cindex @code{vec_shr_@var{m}} instruction pattern 5523@item @samp{vec_shr_@var{m}} 5524Whole vector right shift in bits, i.e.@: towards element 0. 5525Operand 1 is a vector to be shifted. 5526Operand 2 is an integer shift amount in bits. 5527Operand 0 is where the resulting shifted vector is stored. 5528The output and input vectors should have the same modes. 5529 5530@cindex @code{vec_pack_trunc_@var{m}} instruction pattern 5531@item @samp{vec_pack_trunc_@var{m}} 5532Narrow (demote) and merge the elements of two vectors. Operands 1 and 2 5533are vectors of the same mode having N integral or floating point elements 5534of size S@. Operand 0 is the resulting vector in which 2*N elements of 5535size S/2 are concatenated after narrowing them down using truncation. 5536 5537@cindex @code{vec_pack_sbool_trunc_@var{m}} instruction pattern 5538@item @samp{vec_pack_sbool_trunc_@var{m}} 5539Narrow and merge the elements of two vectors. Operands 1 and 2 are vectors 5540of the same type having N boolean elements. Operand 0 is the resulting 5541vector in which 2*N elements are concatenated. The last operand (operand 3) 5542is the number of elements in the output vector 2*N as a @code{CONST_INT}. 5543This instruction pattern is used when all the vector input and output 5544operands have the same scalar mode @var{m} and thus using 5545@code{vec_pack_trunc_@var{m}} would be ambiguous. 5546 5547@cindex @code{vec_pack_ssat_@var{m}} instruction pattern 5548@cindex @code{vec_pack_usat_@var{m}} instruction pattern 5549@item @samp{vec_pack_ssat_@var{m}}, @samp{vec_pack_usat_@var{m}} 5550Narrow (demote) and merge the elements of two vectors. Operands 1 and 2 5551are vectors of the same mode having N integral elements of size S. 5552Operand 0 is the resulting vector in which the elements of the two input 5553vectors are concatenated after narrowing them down using signed/unsigned 5554saturating arithmetic. 5555 5556@cindex @code{vec_pack_sfix_trunc_@var{m}} instruction pattern 5557@cindex @code{vec_pack_ufix_trunc_@var{m}} instruction pattern 5558@item @samp{vec_pack_sfix_trunc_@var{m}}, @samp{vec_pack_ufix_trunc_@var{m}} 5559Narrow, convert to signed/unsigned integral type and merge the elements 5560of two vectors. Operands 1 and 2 are vectors of the same mode having N 5561floating point elements of size S@. Operand 0 is the resulting vector 5562in which 2*N elements of size S/2 are concatenated. 5563 5564@cindex @code{vec_packs_float_@var{m}} instruction pattern 5565@cindex @code{vec_packu_float_@var{m}} instruction pattern 5566@item @samp{vec_packs_float_@var{m}}, @samp{vec_packu_float_@var{m}} 5567Narrow, convert to floating point type and merge the elements 5568of two vectors. Operands 1 and 2 are vectors of the same mode having N 5569signed/unsigned integral elements of size S@. Operand 0 is the resulting vector 5570in which 2*N elements of size S/2 are concatenated. 5571 5572@cindex @code{vec_unpacks_hi_@var{m}} instruction pattern 5573@cindex @code{vec_unpacks_lo_@var{m}} instruction pattern 5574@item @samp{vec_unpacks_hi_@var{m}}, @samp{vec_unpacks_lo_@var{m}} 5575Extract and widen (promote) the high/low part of a vector of signed 5576integral or floating point elements. The input vector (operand 1) has N 5577elements of size S@. Widen (promote) the high/low elements of the vector 5578using signed or floating point extension and place the resulting N/2 5579values of size 2*S in the output vector (operand 0). 5580 5581@cindex @code{vec_unpacku_hi_@var{m}} instruction pattern 5582@cindex @code{vec_unpacku_lo_@var{m}} instruction pattern 5583@item @samp{vec_unpacku_hi_@var{m}}, @samp{vec_unpacku_lo_@var{m}} 5584Extract and widen (promote) the high/low part of a vector of unsigned 5585integral elements. The input vector (operand 1) has N elements of size S. 5586Widen (promote) the high/low elements of the vector using zero extension and 5587place the resulting N/2 values of size 2*S in the output vector (operand 0). 5588 5589@cindex @code{vec_unpacks_sbool_hi_@var{m}} instruction pattern 5590@cindex @code{vec_unpacks_sbool_lo_@var{m}} instruction pattern 5591@item @samp{vec_unpacks_sbool_hi_@var{m}}, @samp{vec_unpacks_sbool_lo_@var{m}} 5592Extract the high/low part of a vector of boolean elements that have scalar 5593mode @var{m}. The input vector (operand 1) has N elements, the output 5594vector (operand 0) has N/2 elements. The last operand (operand 2) is the 5595number of elements of the input vector N as a @code{CONST_INT}. These 5596patterns are used if both the input and output vectors have the same scalar 5597mode @var{m} and thus using @code{vec_unpacks_hi_@var{m}} or 5598@code{vec_unpacks_lo_@var{m}} would be ambiguous. 5599 5600@cindex @code{vec_unpacks_float_hi_@var{m}} instruction pattern 5601@cindex @code{vec_unpacks_float_lo_@var{m}} instruction pattern 5602@cindex @code{vec_unpacku_float_hi_@var{m}} instruction pattern 5603@cindex @code{vec_unpacku_float_lo_@var{m}} instruction pattern 5604@item @samp{vec_unpacks_float_hi_@var{m}}, @samp{vec_unpacks_float_lo_@var{m}} 5605@itemx @samp{vec_unpacku_float_hi_@var{m}}, @samp{vec_unpacku_float_lo_@var{m}} 5606Extract, convert to floating point type and widen the high/low part of a 5607vector of signed/unsigned integral elements. The input vector (operand 1) 5608has N elements of size S@. Convert the high/low elements of the vector using 5609floating point conversion and place the resulting N/2 values of size 2*S in 5610the output vector (operand 0). 5611 5612@cindex @code{vec_unpack_sfix_trunc_hi_@var{m}} instruction pattern 5613@cindex @code{vec_unpack_sfix_trunc_lo_@var{m}} instruction pattern 5614@cindex @code{vec_unpack_ufix_trunc_hi_@var{m}} instruction pattern 5615@cindex @code{vec_unpack_ufix_trunc_lo_@var{m}} instruction pattern 5616@item @samp{vec_unpack_sfix_trunc_hi_@var{m}}, 5617@itemx @samp{vec_unpack_sfix_trunc_lo_@var{m}} 5618@itemx @samp{vec_unpack_ufix_trunc_hi_@var{m}} 5619@itemx @samp{vec_unpack_ufix_trunc_lo_@var{m}} 5620Extract, convert to signed/unsigned integer type and widen the high/low part of a 5621vector of floating point elements. The input vector (operand 1) 5622has N elements of size S@. Convert the high/low elements of the vector 5623to integers and place the resulting N/2 values of size 2*S in 5624the output vector (operand 0). 5625 5626@cindex @code{vec_widen_umult_hi_@var{m}} instruction pattern 5627@cindex @code{vec_widen_umult_lo_@var{m}} instruction pattern 5628@cindex @code{vec_widen_smult_hi_@var{m}} instruction pattern 5629@cindex @code{vec_widen_smult_lo_@var{m}} instruction pattern 5630@cindex @code{vec_widen_umult_even_@var{m}} instruction pattern 5631@cindex @code{vec_widen_umult_odd_@var{m}} instruction pattern 5632@cindex @code{vec_widen_smult_even_@var{m}} instruction pattern 5633@cindex @code{vec_widen_smult_odd_@var{m}} instruction pattern 5634@item @samp{vec_widen_umult_hi_@var{m}}, @samp{vec_widen_umult_lo_@var{m}} 5635@itemx @samp{vec_widen_smult_hi_@var{m}}, @samp{vec_widen_smult_lo_@var{m}} 5636@itemx @samp{vec_widen_umult_even_@var{m}}, @samp{vec_widen_umult_odd_@var{m}} 5637@itemx @samp{vec_widen_smult_even_@var{m}}, @samp{vec_widen_smult_odd_@var{m}} 5638Signed/Unsigned widening multiplication. The two inputs (operands 1 and 2) 5639are vectors with N signed/unsigned elements of size S@. Multiply the high/low 5640or even/odd elements of the two vectors, and put the N/2 products of size 2*S 5641in the output vector (operand 0). A target shouldn't implement even/odd pattern 5642pair if it is less efficient than lo/hi one. 5643 5644@cindex @code{vec_widen_ushiftl_hi_@var{m}} instruction pattern 5645@cindex @code{vec_widen_ushiftl_lo_@var{m}} instruction pattern 5646@cindex @code{vec_widen_sshiftl_hi_@var{m}} instruction pattern 5647@cindex @code{vec_widen_sshiftl_lo_@var{m}} instruction pattern 5648@item @samp{vec_widen_ushiftl_hi_@var{m}}, @samp{vec_widen_ushiftl_lo_@var{m}} 5649@itemx @samp{vec_widen_sshiftl_hi_@var{m}}, @samp{vec_widen_sshiftl_lo_@var{m}} 5650Signed/Unsigned widening shift left. The first input (operand 1) is a vector 5651with N signed/unsigned elements of size S@. Operand 2 is a constant. Shift 5652the high/low elements of operand 1, and put the N/2 results of size 2*S in the 5653output vector (operand 0). 5654 5655@cindex @code{vec_widen_saddl_hi_@var{m}} instruction pattern 5656@cindex @code{vec_widen_saddl_lo_@var{m}} instruction pattern 5657@cindex @code{vec_widen_uaddl_hi_@var{m}} instruction pattern 5658@cindex @code{vec_widen_uaddl_lo_@var{m}} instruction pattern 5659@item @samp{vec_widen_uaddl_hi_@var{m}}, @samp{vec_widen_uaddl_lo_@var{m}} 5660@itemx @samp{vec_widen_saddl_hi_@var{m}}, @samp{vec_widen_saddl_lo_@var{m}} 5661Signed/Unsigned widening add long. Operands 1 and 2 are vectors with N 5662signed/unsigned elements of size S@. Add the high/low elements of 1 and 2 5663together, widen the resulting elements and put the N/2 results of size 2*S in 5664the output vector (operand 0). 5665 5666@cindex @code{vec_widen_ssubl_hi_@var{m}} instruction pattern 5667@cindex @code{vec_widen_ssubl_lo_@var{m}} instruction pattern 5668@cindex @code{vec_widen_usubl_hi_@var{m}} instruction pattern 5669@cindex @code{vec_widen_usubl_lo_@var{m}} instruction pattern 5670@item @samp{vec_widen_usubl_hi_@var{m}}, @samp{vec_widen_usubl_lo_@var{m}} 5671@itemx @samp{vec_widen_ssubl_hi_@var{m}}, @samp{vec_widen_ssubl_lo_@var{m}} 5672Signed/Unsigned widening subtract long. Operands 1 and 2 are vectors with N 5673signed/unsigned elements of size S@. Subtract the high/low elements of 2 from 56741 and widen the resulting elements. Put the N/2 results of size 2*S in the 5675output vector (operand 0). 5676 5677@cindex @code{mulhisi3} instruction pattern 5678@item @samp{mulhisi3} 5679Multiply operands 1 and 2, which have mode @code{HImode}, and store 5680a @code{SImode} product in operand 0. 5681 5682@cindex @code{mulqihi3} instruction pattern 5683@cindex @code{mulsidi3} instruction pattern 5684@item @samp{mulqihi3}, @samp{mulsidi3} 5685Similar widening-multiplication instructions of other widths. 5686 5687@cindex @code{umulqihi3} instruction pattern 5688@cindex @code{umulhisi3} instruction pattern 5689@cindex @code{umulsidi3} instruction pattern 5690@item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3} 5691Similar widening-multiplication instructions that do unsigned 5692multiplication. 5693 5694@cindex @code{usmulqihi3} instruction pattern 5695@cindex @code{usmulhisi3} instruction pattern 5696@cindex @code{usmulsidi3} instruction pattern 5697@item @samp{usmulqihi3}, @samp{usmulhisi3}, @samp{usmulsidi3} 5698Similar widening-multiplication instructions that interpret the first 5699operand as unsigned and the second operand as signed, then do a signed 5700multiplication. 5701 5702@cindex @code{smul@var{m}3_highpart} instruction pattern 5703@item @samp{smul@var{m}3_highpart} 5704Perform a signed multiplication of operands 1 and 2, which have mode 5705@var{m}, and store the most significant half of the product in operand 0. 5706The least significant half of the product is discarded. 5707 5708@cindex @code{umul@var{m}3_highpart} instruction pattern 5709@item @samp{umul@var{m}3_highpart} 5710Similar, but the multiplication is unsigned. 5711 5712@cindex @code{madd@var{m}@var{n}4} instruction pattern 5713@item @samp{madd@var{m}@var{n}4} 5714Multiply operands 1 and 2, sign-extend them to mode @var{n}, add 5715operand 3, and store the result in operand 0. Operands 1 and 2 5716have mode @var{m} and operands 0 and 3 have mode @var{n}. 5717Both modes must be integer or fixed-point modes and @var{n} must be twice 5718the size of @var{m}. 5719 5720In other words, @code{madd@var{m}@var{n}4} is like 5721@code{mul@var{m}@var{n}3} except that it also adds operand 3. 5722 5723These instructions are not allowed to @code{FAIL}. 5724 5725@cindex @code{umadd@var{m}@var{n}4} instruction pattern 5726@item @samp{umadd@var{m}@var{n}4} 5727Like @code{madd@var{m}@var{n}4}, but zero-extend the multiplication 5728operands instead of sign-extending them. 5729 5730@cindex @code{ssmadd@var{m}@var{n}4} instruction pattern 5731@item @samp{ssmadd@var{m}@var{n}4} 5732Like @code{madd@var{m}@var{n}4}, but all involved operations must be 5733signed-saturating. 5734 5735@cindex @code{usmadd@var{m}@var{n}4} instruction pattern 5736@item @samp{usmadd@var{m}@var{n}4} 5737Like @code{umadd@var{m}@var{n}4}, but all involved operations must be 5738unsigned-saturating. 5739 5740@cindex @code{msub@var{m}@var{n}4} instruction pattern 5741@item @samp{msub@var{m}@var{n}4} 5742Multiply operands 1 and 2, sign-extend them to mode @var{n}, subtract the 5743result from operand 3, and store the result in operand 0. Operands 1 and 2 5744have mode @var{m} and operands 0 and 3 have mode @var{n}. 5745Both modes must be integer or fixed-point modes and @var{n} must be twice 5746the size of @var{m}. 5747 5748In other words, @code{msub@var{m}@var{n}4} is like 5749@code{mul@var{m}@var{n}3} except that it also subtracts the result 5750from operand 3. 5751 5752These instructions are not allowed to @code{FAIL}. 5753 5754@cindex @code{umsub@var{m}@var{n}4} instruction pattern 5755@item @samp{umsub@var{m}@var{n}4} 5756Like @code{msub@var{m}@var{n}4}, but zero-extend the multiplication 5757operands instead of sign-extending them. 5758 5759@cindex @code{ssmsub@var{m}@var{n}4} instruction pattern 5760@item @samp{ssmsub@var{m}@var{n}4} 5761Like @code{msub@var{m}@var{n}4}, but all involved operations must be 5762signed-saturating. 5763 5764@cindex @code{usmsub@var{m}@var{n}4} instruction pattern 5765@item @samp{usmsub@var{m}@var{n}4} 5766Like @code{umsub@var{m}@var{n}4}, but all involved operations must be 5767unsigned-saturating. 5768 5769@cindex @code{divmod@var{m}4} instruction pattern 5770@item @samp{divmod@var{m}4} 5771Signed division that produces both a quotient and a remainder. 5772Operand 1 is divided by operand 2 to produce a quotient stored 5773in operand 0 and a remainder stored in operand 3. 5774 5775For machines with an instruction that produces both a quotient and a 5776remainder, provide a pattern for @samp{divmod@var{m}4} but do not 5777provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}. This 5778allows optimization in the relatively common case when both the quotient 5779and remainder are computed. 5780 5781If an instruction that just produces a quotient or just a remainder 5782exists and is more efficient than the instruction that produces both, 5783write the output routine of @samp{divmod@var{m}4} to call 5784@code{find_reg_note} and look for a @code{REG_UNUSED} note on the 5785quotient or remainder and generate the appropriate instruction. 5786 5787@cindex @code{udivmod@var{m}4} instruction pattern 5788@item @samp{udivmod@var{m}4} 5789Similar, but does unsigned division. 5790 5791@anchor{shift patterns} 5792@cindex @code{ashl@var{m}3} instruction pattern 5793@cindex @code{ssashl@var{m}3} instruction pattern 5794@cindex @code{usashl@var{m}3} instruction pattern 5795@item @samp{ashl@var{m}3}, @samp{ssashl@var{m}3}, @samp{usashl@var{m}3} 5796Arithmetic-shift operand 1 left by a number of bits specified by operand 57972, and store the result in operand 0. Here @var{m} is the mode of 5798operand 0 and operand 1; operand 2's mode is specified by the 5799instruction pattern, and the compiler will convert the operand to that 5800mode before generating the instruction. The shift or rotate expander 5801or instruction pattern should explicitly specify the mode of the operand 2, 5802it should never be @code{VOIDmode}. The meaning of out-of-range shift 5803counts can optionally be specified by @code{TARGET_SHIFT_TRUNCATION_MASK}. 5804@xref{TARGET_SHIFT_TRUNCATION_MASK}. Operand 2 is always a scalar type. 5805 5806@cindex @code{ashr@var{m}3} instruction pattern 5807@cindex @code{lshr@var{m}3} instruction pattern 5808@cindex @code{rotl@var{m}3} instruction pattern 5809@cindex @code{rotr@var{m}3} instruction pattern 5810@item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3} 5811Other shift and rotate instructions, analogous to the 5812@code{ashl@var{m}3} instructions. Operand 2 is always a scalar type. 5813 5814@cindex @code{vashl@var{m}3} instruction pattern 5815@cindex @code{vashr@var{m}3} instruction pattern 5816@cindex @code{vlshr@var{m}3} instruction pattern 5817@cindex @code{vrotl@var{m}3} instruction pattern 5818@cindex @code{vrotr@var{m}3} instruction pattern 5819@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} 5820Vector shift and rotate instructions that take vectors as operand 2 5821instead of a scalar type. 5822 5823@cindex @code{avg@var{m}3_floor} instruction pattern 5824@cindex @code{uavg@var{m}3_floor} instruction pattern 5825@item @samp{avg@var{m}3_floor} 5826@itemx @samp{uavg@var{m}3_floor} 5827Signed and unsigned average instructions. These instructions add 5828operands 1 and 2 without truncation, divide the result by 2, 5829round towards -Inf, and store the result in operand 0. This is 5830equivalent to the C code: 5831@smallexample 5832narrow op0, op1, op2; 5833@dots{} 5834op0 = (narrow) (((wide) op1 + (wide) op2) >> 1); 5835@end smallexample 5836where the sign of @samp{narrow} determines whether this is a signed 5837or unsigned operation. 5838 5839@cindex @code{avg@var{m}3_ceil} instruction pattern 5840@cindex @code{uavg@var{m}3_ceil} instruction pattern 5841@item @samp{avg@var{m}3_ceil} 5842@itemx @samp{uavg@var{m}3_ceil} 5843Like @samp{avg@var{m}3_floor} and @samp{uavg@var{m}3_floor}, but round 5844towards +Inf. This is equivalent to the C code: 5845@smallexample 5846narrow op0, op1, op2; 5847@dots{} 5848op0 = (narrow) (((wide) op1 + (wide) op2 + 1) >> 1); 5849@end smallexample 5850 5851@cindex @code{bswap@var{m}2} instruction pattern 5852@item @samp{bswap@var{m}2} 5853Reverse the order of bytes of operand 1 and store the result in operand 0. 5854 5855@cindex @code{neg@var{m}2} instruction pattern 5856@cindex @code{ssneg@var{m}2} instruction pattern 5857@cindex @code{usneg@var{m}2} instruction pattern 5858@item @samp{neg@var{m}2}, @samp{ssneg@var{m}2}, @samp{usneg@var{m}2} 5859Negate operand 1 and store the result in operand 0. 5860 5861@cindex @code{negv@var{m}3} instruction pattern 5862@item @samp{negv@var{m}3} 5863Like @code{neg@var{m}2} but takes a @code{code_label} as operand 2 and 5864emits code to jump to it if signed overflow occurs during the negation. 5865 5866@cindex @code{abs@var{m}2} instruction pattern 5867@item @samp{abs@var{m}2} 5868Store the absolute value of operand 1 into operand 0. 5869 5870@cindex @code{sqrt@var{m}2} instruction pattern 5871@item @samp{sqrt@var{m}2} 5872Store the square root of operand 1 into operand 0. Both operands have 5873mode @var{m}, which is a scalar or vector floating-point mode. 5874 5875This pattern is not allowed to @code{FAIL}. 5876 5877@cindex @code{rsqrt@var{m}2} instruction pattern 5878@item @samp{rsqrt@var{m}2} 5879Store the reciprocal of the square root of operand 1 into operand 0. 5880Both operands have mode @var{m}, which is a scalar or vector 5881floating-point mode. 5882 5883On most architectures this pattern is only approximate, so either 5884its C condition or the @code{TARGET_OPTAB_SUPPORTED_P} hook should 5885check for the appropriate math flags. (Using the C condition is 5886more direct, but using @code{TARGET_OPTAB_SUPPORTED_P} can be useful 5887if a target-specific built-in also uses the @samp{rsqrt@var{m}2} 5888pattern.) 5889 5890This pattern is not allowed to @code{FAIL}. 5891 5892@cindex @code{fmod@var{m}3} instruction pattern 5893@item @samp{fmod@var{m}3} 5894Store the remainder of dividing operand 1 by operand 2 into 5895operand 0, rounded towards zero to an integer. All 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{remainder@var{m}3} instruction pattern 5901@item @samp{remainder@var{m}3} 5902Store the remainder of dividing operand 1 by operand 2 into 5903operand 0, rounded to the nearest integer. All operands have 5904mode @var{m}, which is a scalar or vector floating-point mode. 5905 5906This pattern is not allowed to @code{FAIL}. 5907 5908@cindex @code{scalb@var{m}3} instruction pattern 5909@item @samp{scalb@var{m}3} 5910Raise @code{FLT_RADIX} to the power of operand 2, multiply it by 5911operand 1, and store the result in operand 0. All operands have 5912mode @var{m}, which is a scalar or vector floating-point mode. 5913 5914This pattern is not allowed to @code{FAIL}. 5915 5916@cindex @code{ldexp@var{m}3} instruction pattern 5917@item @samp{ldexp@var{m}3} 5918Raise 2 to the power of operand 2, multiply it by operand 1, and store 5919the result in operand 0. Operands 0 and 1 have mode @var{m}, which is 5920a scalar or vector floating-point mode. Operand 2's mode has 5921the same number of elements as @var{m} and each element is wide 5922enough to store an @code{int}. The integers are signed. 5923 5924This pattern is not allowed to @code{FAIL}. 5925 5926@cindex @code{cos@var{m}2} instruction pattern 5927@item @samp{cos@var{m}2} 5928Store the cosine of operand 1 into operand 0. Both operands have 5929mode @var{m}, which is a scalar or vector floating-point mode. 5930 5931This pattern is not allowed to @code{FAIL}. 5932 5933@cindex @code{sin@var{m}2} instruction pattern 5934@item @samp{sin@var{m}2} 5935Store the sine of operand 1 into operand 0. Both operands have 5936mode @var{m}, which is a scalar or vector floating-point mode. 5937 5938This pattern is not allowed to @code{FAIL}. 5939 5940@cindex @code{sincos@var{m}3} instruction pattern 5941@item @samp{sincos@var{m}3} 5942Store the cosine of operand 2 into operand 0 and the sine of 5943operand 2 into operand 1. All operands have mode @var{m}, 5944which is a scalar or vector floating-point mode. 5945 5946Targets that can calculate the sine and cosine simultaneously can 5947implement this pattern as opposed to implementing individual 5948@code{sin@var{m}2} and @code{cos@var{m}2} patterns. The @code{sin} 5949and @code{cos} built-in functions will then be expanded to the 5950@code{sincos@var{m}3} pattern, with one of the output values 5951left unused. 5952 5953@cindex @code{tan@var{m}2} instruction pattern 5954@item @samp{tan@var{m}2} 5955Store the tangent of operand 1 into operand 0. Both operands have 5956mode @var{m}, which is a scalar or vector floating-point mode. 5957 5958This pattern is not allowed to @code{FAIL}. 5959 5960@cindex @code{asin@var{m}2} instruction pattern 5961@item @samp{asin@var{m}2} 5962Store the arc sine of operand 1 into operand 0. Both operands have 5963mode @var{m}, which is a scalar or vector floating-point mode. 5964 5965This pattern is not allowed to @code{FAIL}. 5966 5967@cindex @code{acos@var{m}2} instruction pattern 5968@item @samp{acos@var{m}2} 5969Store the arc cosine of operand 1 into operand 0. Both operands have 5970mode @var{m}, which is a scalar or vector floating-point mode. 5971 5972This pattern is not allowed to @code{FAIL}. 5973 5974@cindex @code{atan@var{m}2} instruction pattern 5975@item @samp{atan@var{m}2} 5976Store the arc tangent of operand 1 into operand 0. Both operands have 5977mode @var{m}, which is a scalar or vector floating-point mode. 5978 5979This pattern is not allowed to @code{FAIL}. 5980 5981@cindex @code{exp@var{m}2} instruction pattern 5982@item @samp{exp@var{m}2} 5983Raise e (the base of natural logarithms) to the power of operand 1 5984and store the result in operand 0. Both operands have mode @var{m}, 5985which is a scalar or vector floating-point mode. 5986 5987This pattern is not allowed to @code{FAIL}. 5988 5989@cindex @code{expm1@var{m}2} instruction pattern 5990@item @samp{expm1@var{m}2} 5991Raise e (the base of natural logarithms) to the power of operand 1, 5992subtract 1, and store the result in operand 0. Both operands have 5993mode @var{m}, which is a scalar or vector floating-point mode. 5994 5995For inputs close to zero, the pattern is expected to be more 5996accurate than a separate @code{exp@var{m}2} and @code{sub@var{m}3} 5997would be. 5998 5999This pattern is not allowed to @code{FAIL}. 6000 6001@cindex @code{exp10@var{m}2} instruction pattern 6002@item @samp{exp10@var{m}2} 6003Raise 10 to the power of operand 1 and store the result in operand 0. 6004Both operands have mode @var{m}, which is a scalar or vector 6005floating-point mode. 6006 6007This pattern is not allowed to @code{FAIL}. 6008 6009@cindex @code{exp2@var{m}2} instruction pattern 6010@item @samp{exp2@var{m}2} 6011Raise 2 to the power of operand 1 and store the result in operand 0. 6012Both operands have mode @var{m}, which is a scalar or vector 6013floating-point mode. 6014 6015This pattern is not allowed to @code{FAIL}. 6016 6017@cindex @code{log@var{m}2} instruction pattern 6018@item @samp{log@var{m}2} 6019Store the natural logarithm of operand 1 into operand 0. Both operands 6020have mode @var{m}, which is a scalar or vector floating-point mode. 6021 6022This pattern is not allowed to @code{FAIL}. 6023 6024@cindex @code{log1p@var{m}2} instruction pattern 6025@item @samp{log1p@var{m}2} 6026Add 1 to operand 1, compute the natural logarithm, and store 6027the result in operand 0. Both operands have mode @var{m}, which is 6028a scalar or vector floating-point mode. 6029 6030For inputs close to zero, the pattern is expected to be more 6031accurate than a separate @code{add@var{m}3} and @code{log@var{m}2} 6032would be. 6033 6034This pattern is not allowed to @code{FAIL}. 6035 6036@cindex @code{log10@var{m}2} instruction pattern 6037@item @samp{log10@var{m}2} 6038Store the base-10 logarithm of operand 1 into operand 0. Both operands 6039have mode @var{m}, which is a scalar or vector floating-point mode. 6040 6041This pattern is not allowed to @code{FAIL}. 6042 6043@cindex @code{log2@var{m}2} instruction pattern 6044@item @samp{log2@var{m}2} 6045Store the base-2 logarithm of operand 1 into operand 0. Both operands 6046have mode @var{m}, which is a scalar or vector floating-point mode. 6047 6048This pattern is not allowed to @code{FAIL}. 6049 6050@cindex @code{logb@var{m}2} instruction pattern 6051@item @samp{logb@var{m}2} 6052Store the base-@code{FLT_RADIX} logarithm of operand 1 into operand 0. 6053Both operands have mode @var{m}, which is a scalar or vector 6054floating-point mode. 6055 6056This pattern is not allowed to @code{FAIL}. 6057 6058@cindex @code{significand@var{m}2} instruction pattern 6059@item @samp{significand@var{m}2} 6060Store the significand of floating-point operand 1 in operand 0. 6061Both operands have mode @var{m}, which is a scalar or vector 6062floating-point mode. 6063 6064This pattern is not allowed to @code{FAIL}. 6065 6066@cindex @code{pow@var{m}3} instruction pattern 6067@item @samp{pow@var{m}3} 6068Store the value of operand 1 raised to the exponent operand 2 6069into operand 0. All operands have mode @var{m}, which is a scalar 6070or vector floating-point mode. 6071 6072This pattern is not allowed to @code{FAIL}. 6073 6074@cindex @code{atan2@var{m}3} instruction pattern 6075@item @samp{atan2@var{m}3} 6076Store the arc tangent (inverse tangent) of operand 1 divided by 6077operand 2 into operand 0, using the signs of both arguments to 6078determine the quadrant of the result. All operands have mode 6079@var{m}, which is a scalar or vector floating-point mode. 6080 6081This pattern is not allowed to @code{FAIL}. 6082 6083@cindex @code{floor@var{m}2} instruction pattern 6084@item @samp{floor@var{m}2} 6085Store the largest integral value not greater than operand 1 in operand 0. 6086Both operands have mode @var{m}, which is a scalar or vector 6087floating-point mode. If @option{-ffp-int-builtin-inexact} is in 6088effect, the ``inexact'' exception may be raised for noninteger 6089operands; otherwise, it may not. 6090 6091This pattern is not allowed to @code{FAIL}. 6092 6093@cindex @code{btrunc@var{m}2} instruction pattern 6094@item @samp{btrunc@var{m}2} 6095Round operand 1 to an integer, towards zero, and store the result in 6096operand 0. Both operands have mode @var{m}, which is a scalar or 6097vector floating-point mode. If @option{-ffp-int-builtin-inexact} is 6098in effect, the ``inexact'' exception may be raised for noninteger 6099operands; otherwise, it may not. 6100 6101This pattern is not allowed to @code{FAIL}. 6102 6103@cindex @code{round@var{m}2} instruction pattern 6104@item @samp{round@var{m}2} 6105Round operand 1 to the nearest integer, rounding away from zero in the 6106event of a tie, and store the result in operand 0. Both operands have 6107mode @var{m}, which is a scalar or vector floating-point mode. If 6108@option{-ffp-int-builtin-inexact} is in effect, the ``inexact'' 6109exception may be raised for noninteger operands; otherwise, it may 6110not. 6111 6112This pattern is not allowed to @code{FAIL}. 6113 6114@cindex @code{ceil@var{m}2} instruction pattern 6115@item @samp{ceil@var{m}2} 6116Store the smallest integral value not less than operand 1 in operand 0. 6117Both operands have mode @var{m}, which is a scalar or vector 6118floating-point mode. If @option{-ffp-int-builtin-inexact} is in 6119effect, the ``inexact'' exception may be raised for noninteger 6120operands; otherwise, it may not. 6121 6122This pattern is not allowed to @code{FAIL}. 6123 6124@cindex @code{nearbyint@var{m}2} instruction pattern 6125@item @samp{nearbyint@var{m}2} 6126Round operand 1 to an integer, using the current rounding mode, and 6127store the result in operand 0. Do not raise an inexact condition when 6128the result is different from the argument. Both operands have mode 6129@var{m}, which is a scalar or vector floating-point mode. 6130 6131This pattern is not allowed to @code{FAIL}. 6132 6133@cindex @code{rint@var{m}2} instruction pattern 6134@item @samp{rint@var{m}2} 6135Round operand 1 to an integer, using the current rounding mode, and 6136store the result in operand 0. Raise an inexact condition when 6137the result is different from the argument. Both operands have mode 6138@var{m}, which is a scalar or vector floating-point mode. 6139 6140This pattern is not allowed to @code{FAIL}. 6141 6142@cindex @code{lrint@var{m}@var{n}2} 6143@item @samp{lrint@var{m}@var{n}2} 6144Convert operand 1 (valid for floating point mode @var{m}) to fixed 6145point mode @var{n} as a signed number according to the current 6146rounding mode and store in operand 0 (which has mode @var{n}). 6147 6148@cindex @code{lround@var{m}@var{n}2} 6149@item @samp{lround@var{m}@var{n}2} 6150Convert operand 1 (valid for floating point mode @var{m}) to fixed 6151point mode @var{n} as a signed number rounding to nearest and away 6152from zero and store in operand 0 (which has mode @var{n}). 6153 6154@cindex @code{lfloor@var{m}@var{n}2} 6155@item @samp{lfloor@var{m}@var{n}2} 6156Convert operand 1 (valid for floating point mode @var{m}) to fixed 6157point mode @var{n} as a signed number rounding down and store in 6158operand 0 (which has mode @var{n}). 6159 6160@cindex @code{lceil@var{m}@var{n}2} 6161@item @samp{lceil@var{m}@var{n}2} 6162Convert operand 1 (valid for floating point mode @var{m}) to fixed 6163point mode @var{n} as a signed number rounding up and store in 6164operand 0 (which has mode @var{n}). 6165 6166@cindex @code{copysign@var{m}3} instruction pattern 6167@item @samp{copysign@var{m}3} 6168Store a value with the magnitude of operand 1 and the sign of operand 61692 into operand 0. All operands have mode @var{m}, which is a scalar or 6170vector floating-point mode. 6171 6172This pattern is not allowed to @code{FAIL}. 6173 6174@cindex @code{xorsign@var{m}3} instruction pattern 6175@item @samp{xorsign@var{m}3} 6176Equivalent to @samp{op0 = op1 * copysign (1.0, op2)}: store a value with 6177the magnitude of operand 1 and the sign of operand 2 into operand 0. 6178All operands have mode @var{m}, which is a scalar or vector 6179floating-point mode. 6180 6181This pattern is not allowed to @code{FAIL}. 6182 6183@cindex @code{cadd90@var{m}3} instruction pattern 6184@item @samp{cadd90@var{m}3} 6185Perform vector add and subtract on even/odd number pairs. The operation being 6186matched is semantically described as 6187 6188@smallexample 6189 for (int i = 0; i < N; i += 2) 6190 @{ 6191 c[i] = a[i] - b[i+1]; 6192 c[i+1] = a[i+1] + b[i]; 6193 @} 6194@end smallexample 6195 6196This operation is semantically equivalent to performing a vector addition of 6197complex numbers in operand 1 with operand 2 rotated by 90 degrees around 6198the argand plane and storing the result in operand 0. 6199 6200In GCC lane ordering the real part of the number must be in the even lanes with 6201the imaginary part in the odd lanes. 6202 6203The operation is only supported for vector modes @var{m}. 6204 6205This pattern is not allowed to @code{FAIL}. 6206 6207@cindex @code{cadd270@var{m}3} instruction pattern 6208@item @samp{cadd270@var{m}3} 6209Perform vector add and subtract on even/odd number pairs. The operation being 6210matched is semantically described as 6211 6212@smallexample 6213 for (int i = 0; i < N; i += 2) 6214 @{ 6215 c[i] = a[i] + b[i+1]; 6216 c[i+1] = a[i+1] - b[i]; 6217 @} 6218@end smallexample 6219 6220This operation is semantically equivalent to performing a vector addition of 6221complex numbers in operand 1 with operand 2 rotated by 270 degrees around 6222the argand plane and storing the result in operand 0. 6223 6224In GCC lane ordering the real part of the number must be in the even lanes with 6225the imaginary part in the odd lanes. 6226 6227The operation is only supported for vector modes @var{m}. 6228 6229This pattern is not allowed to @code{FAIL}. 6230 6231@cindex @code{cmla@var{m}4} instruction pattern 6232@item @samp{cmla@var{m}4} 6233Perform a vector multiply and accumulate that is semantically the same as 6234a multiply and accumulate of complex numbers. 6235 6236@smallexample 6237 complex TYPE c[N]; 6238 complex TYPE a[N]; 6239 complex TYPE b[N]; 6240 for (int i = 0; i < N; i += 1) 6241 @{ 6242 c[i] += a[i] * b[i]; 6243 @} 6244@end smallexample 6245 6246In GCC lane ordering the real part of the number must be in the even lanes with 6247the imaginary part in the odd lanes. 6248 6249The operation is only supported for vector modes @var{m}. 6250 6251This pattern is not allowed to @code{FAIL}. 6252 6253@cindex @code{cmla_conj@var{m}4} instruction pattern 6254@item @samp{cmla_conj@var{m}4} 6255Perform a vector multiply by conjugate and accumulate that is semantically 6256the same as a multiply and accumulate of complex numbers where the second 6257multiply arguments is conjugated. 6258 6259@smallexample 6260 complex TYPE c[N]; 6261 complex TYPE a[N]; 6262 complex TYPE b[N]; 6263 for (int i = 0; i < N; i += 1) 6264 @{ 6265 c[i] += a[i] * conj (b[i]); 6266 @} 6267@end smallexample 6268 6269In GCC lane ordering the real part of the number must be in the even lanes with 6270the imaginary part in the odd lanes. 6271 6272The operation is only supported for vector modes @var{m}. 6273 6274This pattern is not allowed to @code{FAIL}. 6275 6276@cindex @code{cmls@var{m}4} instruction pattern 6277@item @samp{cmls@var{m}4} 6278Perform a vector multiply and subtract that is semantically the same as 6279a multiply and subtract of complex numbers. 6280 6281@smallexample 6282 complex TYPE c[N]; 6283 complex TYPE a[N]; 6284 complex TYPE b[N]; 6285 for (int i = 0; i < N; i += 1) 6286 @{ 6287 c[i] -= a[i] * b[i]; 6288 @} 6289@end smallexample 6290 6291In GCC lane ordering the real part of the number must be in the even lanes with 6292the imaginary part in the odd lanes. 6293 6294The operation is only supported for vector modes @var{m}. 6295 6296This pattern is not allowed to @code{FAIL}. 6297 6298@cindex @code{cmls_conj@var{m}4} instruction pattern 6299@item @samp{cmls_conj@var{m}4} 6300Perform a vector multiply by conjugate and subtract that is semantically 6301the same as a multiply and subtract of complex numbers where the second 6302multiply arguments is conjugated. 6303 6304@smallexample 6305 complex TYPE c[N]; 6306 complex TYPE a[N]; 6307 complex TYPE b[N]; 6308 for (int i = 0; i < N; i += 1) 6309 @{ 6310 c[i] -= a[i] * conj (b[i]); 6311 @} 6312@end smallexample 6313 6314In GCC lane ordering the real part of the number must be in the even lanes with 6315the imaginary part in the odd lanes. 6316 6317The operation is only supported for vector modes @var{m}. 6318 6319This pattern is not allowed to @code{FAIL}. 6320 6321@cindex @code{cmul@var{m}4} instruction pattern 6322@item @samp{cmul@var{m}4} 6323Perform a vector multiply that is semantically the same as multiply of 6324complex numbers. 6325 6326@smallexample 6327 complex TYPE c[N]; 6328 complex TYPE a[N]; 6329 complex TYPE b[N]; 6330 for (int i = 0; i < N; i += 1) 6331 @{ 6332 c[i] = a[i] * b[i]; 6333 @} 6334@end smallexample 6335 6336In GCC lane ordering the real part of the number must be in the even lanes with 6337the imaginary part in the odd lanes. 6338 6339The operation is only supported for vector modes @var{m}. 6340 6341This pattern is not allowed to @code{FAIL}. 6342 6343@cindex @code{cmul_conj@var{m}4} instruction pattern 6344@item @samp{cmul_conj@var{m}4} 6345Perform a vector multiply by conjugate that is semantically the same as a 6346multiply of complex numbers where the second multiply arguments is conjugated. 6347 6348@smallexample 6349 complex TYPE c[N]; 6350 complex TYPE a[N]; 6351 complex TYPE b[N]; 6352 for (int i = 0; i < N; i += 1) 6353 @{ 6354 c[i] = a[i] * conj (b[i]); 6355 @} 6356@end smallexample 6357 6358In GCC lane ordering the real part of the number must be in the even lanes with 6359the imaginary part in the odd lanes. 6360 6361The operation is only supported for vector modes @var{m}. 6362 6363This pattern is not allowed to @code{FAIL}. 6364 6365@cindex @code{ffs@var{m}2} instruction pattern 6366@item @samp{ffs@var{m}2} 6367Store into operand 0 one plus the index of the least significant 1-bit 6368of operand 1. If operand 1 is zero, store zero. 6369 6370@var{m} is either a scalar or vector integer mode. When it is a scalar, 6371operand 1 has mode @var{m} but operand 0 can have whatever scalar 6372integer mode is suitable for the target. The compiler will insert 6373conversion instructions as necessary (typically to convert the result 6374to the same width as @code{int}). When @var{m} is a vector, both 6375operands must have mode @var{m}. 6376 6377This pattern is not allowed to @code{FAIL}. 6378 6379@cindex @code{clrsb@var{m}2} instruction pattern 6380@item @samp{clrsb@var{m}2} 6381Count leading redundant sign bits. 6382Store into operand 0 the number of redundant sign bits in operand 1, starting 6383at the most significant bit position. 6384A redundant sign bit is defined as any sign bit after the first. As such, 6385this count will be one less than the count of leading sign bits. 6386 6387@var{m} is either a scalar or vector integer mode. When it is a scalar, 6388operand 1 has mode @var{m} but operand 0 can have whatever scalar 6389integer mode is suitable for the target. The compiler will insert 6390conversion instructions as necessary (typically to convert the result 6391to the same width as @code{int}). When @var{m} is a vector, both 6392operands must have mode @var{m}. 6393 6394This pattern is not allowed to @code{FAIL}. 6395 6396@cindex @code{clz@var{m}2} instruction pattern 6397@item @samp{clz@var{m}2} 6398Store into operand 0 the number of leading 0-bits in operand 1, starting 6399at the most significant bit position. If operand 1 is 0, the 6400@code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if 6401the result is undefined or has a useful value. 6402 6403@var{m} is either a scalar or vector integer mode. When it is a scalar, 6404operand 1 has mode @var{m} but operand 0 can have whatever scalar 6405integer mode is suitable for the target. The compiler will insert 6406conversion instructions as necessary (typically to convert the result 6407to the same width as @code{int}). When @var{m} is a vector, both 6408operands must have mode @var{m}. 6409 6410This pattern is not allowed to @code{FAIL}. 6411 6412@cindex @code{ctz@var{m}2} instruction pattern 6413@item @samp{ctz@var{m}2} 6414Store into operand 0 the number of trailing 0-bits in operand 1, starting 6415at the least significant bit position. If operand 1 is 0, the 6416@code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if 6417the result is undefined or has a useful value. 6418 6419@var{m} is either a scalar or vector integer mode. When it is a scalar, 6420operand 1 has mode @var{m} but operand 0 can have whatever scalar 6421integer mode is suitable for the target. The compiler will insert 6422conversion instructions as necessary (typically to convert the result 6423to the same width as @code{int}). When @var{m} is a vector, both 6424operands must have mode @var{m}. 6425 6426This pattern is not allowed to @code{FAIL}. 6427 6428@cindex @code{popcount@var{m}2} instruction pattern 6429@item @samp{popcount@var{m}2} 6430Store into operand 0 the number of 1-bits in operand 1. 6431 6432@var{m} is either a scalar or vector integer mode. When it is a scalar, 6433operand 1 has mode @var{m} but operand 0 can have whatever scalar 6434integer mode is suitable for the target. The compiler will insert 6435conversion instructions as necessary (typically to convert the result 6436to the same width as @code{int}). When @var{m} is a vector, both 6437operands must have mode @var{m}. 6438 6439This pattern is not allowed to @code{FAIL}. 6440 6441@cindex @code{parity@var{m}2} instruction pattern 6442@item @samp{parity@var{m}2} 6443Store into operand 0 the parity of operand 1, i.e.@: the number of 1-bits 6444in operand 1 modulo 2. 6445 6446@var{m} is either a scalar or vector integer mode. When it is a scalar, 6447operand 1 has mode @var{m} but operand 0 can have whatever scalar 6448integer mode is suitable for the target. The compiler will insert 6449conversion instructions as necessary (typically to convert the result 6450to the same width as @code{int}). When @var{m} is a vector, both 6451operands must have mode @var{m}. 6452 6453This pattern is not allowed to @code{FAIL}. 6454 6455@cindex @code{one_cmpl@var{m}2} instruction pattern 6456@item @samp{one_cmpl@var{m}2} 6457Store the bitwise-complement of operand 1 into operand 0. 6458 6459@cindex @code{cpymem@var{m}} instruction pattern 6460@item @samp{cpymem@var{m}} 6461Block copy instruction. The destination and source blocks of memory 6462are the first two operands, and both are @code{mem:BLK}s with an 6463address in mode @code{Pmode}. 6464 6465The number of bytes to copy is the third operand, in mode @var{m}. 6466Usually, you specify @code{Pmode} for @var{m}. However, if you can 6467generate better code knowing the range of valid lengths is smaller than 6468those representable in a full Pmode pointer, you should provide 6469a pattern with a 6470mode corresponding to the range of values you can handle efficiently 6471(e.g., @code{QImode} for values in the range 0--127; note we avoid numbers 6472that appear negative) and also a pattern with @code{Pmode}. 6473 6474The fourth operand is the known shared alignment of the source and 6475destination, in the form of a @code{const_int} rtx. Thus, if the 6476compiler knows that both source and destination are word-aligned, 6477it may provide the value 4 for this operand. 6478 6479Optional operands 5 and 6 specify expected alignment and size of block 6480respectively. The expected alignment differs from alignment in operand 4 6481in a way that the blocks are not required to be aligned according to it in 6482all cases. This expected alignment is also in bytes, just like operand 4. 6483Expected size, when unknown, is set to @code{(const_int -1)}. 6484 6485Descriptions of multiple @code{cpymem@var{m}} patterns can only be 6486beneficial if the patterns for smaller modes have fewer restrictions 6487on their first, second and fourth operands. Note that the mode @var{m} 6488in @code{cpymem@var{m}} does not impose any restriction on the mode of 6489individually copied data units in the block. 6490 6491The @code{cpymem@var{m}} patterns need not give special consideration 6492to the possibility that the source and destination strings might 6493overlap. These patterns are used to do inline expansion of 6494@code{__builtin_memcpy}. 6495 6496@cindex @code{movmem@var{m}} instruction pattern 6497@item @samp{movmem@var{m}} 6498Block move instruction. The destination and source blocks of memory 6499are the first two operands, and both are @code{mem:BLK}s with an 6500address in mode @code{Pmode}. 6501 6502The number of bytes to copy is the third operand, in mode @var{m}. 6503Usually, you specify @code{Pmode} for @var{m}. However, if you can 6504generate better code knowing the range of valid lengths is smaller than 6505those representable in a full Pmode pointer, you should provide 6506a pattern with a 6507mode corresponding to the range of values you can handle efficiently 6508(e.g., @code{QImode} for values in the range 0--127; note we avoid numbers 6509that appear negative) and also a pattern with @code{Pmode}. 6510 6511The fourth operand is the known shared alignment of the source and 6512destination, in the form of a @code{const_int} rtx. Thus, if the 6513compiler knows that both source and destination are word-aligned, 6514it may provide the value 4 for this operand. 6515 6516Optional operands 5 and 6 specify expected alignment and size of block 6517respectively. The expected alignment differs from alignment in operand 4 6518in a way that the blocks are not required to be aligned according to it in 6519all cases. This expected alignment is also in bytes, just like operand 4. 6520Expected size, when unknown, is set to @code{(const_int -1)}. 6521 6522Descriptions of multiple @code{movmem@var{m}} patterns can only be 6523beneficial if the patterns for smaller modes have fewer restrictions 6524on their first, second and fourth operands. Note that the mode @var{m} 6525in @code{movmem@var{m}} does not impose any restriction on the mode of 6526individually copied data units in the block. 6527 6528The @code{movmem@var{m}} patterns must correctly handle the case where 6529the source and destination strings overlap. These patterns are used to 6530do inline expansion of @code{__builtin_memmove}. 6531 6532@cindex @code{movstr} instruction pattern 6533@item @samp{movstr} 6534String copy instruction, with @code{stpcpy} semantics. Operand 0 is 6535an output operand in mode @code{Pmode}. The addresses of the 6536destination and source strings are operands 1 and 2, and both are 6537@code{mem:BLK}s with addresses in mode @code{Pmode}. The execution of 6538the expansion of this pattern should store in operand 0 the address in 6539which the @code{NUL} terminator was stored in the destination string. 6540 6541This pattern has also several optional operands that are same as in 6542@code{setmem}. 6543 6544@cindex @code{setmem@var{m}} instruction pattern 6545@item @samp{setmem@var{m}} 6546Block set instruction. The destination string is the first operand, 6547given as a @code{mem:BLK} whose address is in mode @code{Pmode}. The 6548number of bytes to set is the second operand, in mode @var{m}. The value to 6549initialize the memory with is the third operand. Targets that only support the 6550clearing of memory should reject any value that is not the constant 0. See 6551@samp{cpymem@var{m}} for a discussion of the choice of mode. 6552 6553The fourth operand is the known alignment of the destination, in the form 6554of a @code{const_int} rtx. Thus, if the compiler knows that the 6555destination is word-aligned, it may provide the value 4 for this 6556operand. 6557 6558Optional operands 5 and 6 specify expected alignment and size of block 6559respectively. The expected alignment differs from alignment in operand 4 6560in a way that the blocks are not required to be aligned according to it in 6561all cases. This expected alignment is also in bytes, just like operand 4. 6562Expected size, when unknown, is set to @code{(const_int -1)}. 6563Operand 7 is the minimal size of the block and operand 8 is the 6564maximal size of the block (NULL if it cannot be represented as CONST_INT). 6565Operand 9 is the probable maximal size (i.e.@: we cannot rely on it for 6566correctness, but it can be used for choosing proper code sequence for a 6567given size). 6568 6569The use for multiple @code{setmem@var{m}} is as for @code{cpymem@var{m}}. 6570 6571@cindex @code{cmpstrn@var{m}} instruction pattern 6572@item @samp{cmpstrn@var{m}} 6573String compare instruction, with five operands. Operand 0 is the output; 6574it has mode @var{m}. The remaining four operands are like the operands 6575of @samp{cpymem@var{m}}. The two memory blocks specified are compared 6576byte by byte in lexicographic order starting at the beginning of each 6577string. The instruction is not allowed to prefetch more than one byte 6578at a time since either string may end in the first byte and reading past 6579that may access an invalid page or segment and cause a fault. The 6580comparison terminates early if the fetched bytes are different or if 6581they are equal to zero. The effect of the instruction is to store a 6582value in operand 0 whose sign indicates the result of the comparison. 6583 6584@cindex @code{cmpstr@var{m}} instruction pattern 6585@item @samp{cmpstr@var{m}} 6586String compare instruction, without known maximum length. Operand 0 is the 6587output; it has mode @var{m}. The second and third operand are the blocks of 6588memory to be compared; both are @code{mem:BLK} with an address in mode 6589@code{Pmode}. 6590 6591The fourth operand is the known shared alignment of the source and 6592destination, in the form of a @code{const_int} rtx. Thus, if the 6593compiler knows that both source and destination are word-aligned, 6594it may provide the value 4 for this operand. 6595 6596The two memory blocks specified are compared byte by byte in lexicographic 6597order starting at the beginning of each string. The instruction is not allowed 6598to prefetch more than one byte at a time since either string may end in the 6599first byte and reading past that may access an invalid page or segment and 6600cause a fault. The comparison will terminate when the fetched bytes 6601are different or if they are equal to zero. The effect of the 6602instruction is to store a value in operand 0 whose sign indicates the 6603result of the comparison. 6604 6605@cindex @code{cmpmem@var{m}} instruction pattern 6606@item @samp{cmpmem@var{m}} 6607Block compare instruction, with five operands like the operands 6608of @samp{cmpstr@var{m}}. The two memory blocks specified are compared 6609byte by byte in lexicographic order starting at the beginning of each 6610block. Unlike @samp{cmpstr@var{m}} the instruction can prefetch 6611any bytes in the two memory blocks. Also unlike @samp{cmpstr@var{m}} 6612the comparison will not stop if both bytes are zero. The effect of 6613the instruction is to store a value in operand 0 whose sign indicates 6614the result of the comparison. 6615 6616@cindex @code{strlen@var{m}} instruction pattern 6617@item @samp{strlen@var{m}} 6618Compute the length of a string, with three operands. 6619Operand 0 is the result (of mode @var{m}), operand 1 is 6620a @code{mem} referring to the first character of the string, 6621operand 2 is the character to search for (normally zero), 6622and operand 3 is a constant describing the known alignment 6623of the beginning of the string. 6624 6625@cindex @code{float@var{m}@var{n}2} instruction pattern 6626@item @samp{float@var{m}@var{n}2} 6627Convert signed integer operand 1 (valid for fixed point mode @var{m}) to 6628floating point mode @var{n} and store in operand 0 (which has mode 6629@var{n}). 6630 6631@cindex @code{floatuns@var{m}@var{n}2} instruction pattern 6632@item @samp{floatuns@var{m}@var{n}2} 6633Convert unsigned integer operand 1 (valid for fixed point mode @var{m}) 6634to floating point mode @var{n} and store in operand 0 (which has mode 6635@var{n}). 6636 6637@cindex @code{fix@var{m}@var{n}2} instruction pattern 6638@item @samp{fix@var{m}@var{n}2} 6639Convert operand 1 (valid for floating point mode @var{m}) to fixed 6640point mode @var{n} as a signed number and store in operand 0 (which 6641has mode @var{n}). This instruction's result is defined only when 6642the value of operand 1 is an integer. 6643 6644If the machine description defines this pattern, it also needs to 6645define the @code{ftrunc} pattern. 6646 6647@cindex @code{fixuns@var{m}@var{n}2} instruction pattern 6648@item @samp{fixuns@var{m}@var{n}2} 6649Convert operand 1 (valid for floating point mode @var{m}) to fixed 6650point mode @var{n} as an unsigned number and store in operand 0 (which 6651has mode @var{n}). This instruction's result is defined only when the 6652value of operand 1 is an integer. 6653 6654@cindex @code{ftrunc@var{m}2} instruction pattern 6655@item @samp{ftrunc@var{m}2} 6656Convert operand 1 (valid for floating point mode @var{m}) to an 6657integer value, still represented in floating point mode @var{m}, and 6658store it in operand 0 (valid for floating point mode @var{m}). 6659 6660@cindex @code{fix_trunc@var{m}@var{n}2} instruction pattern 6661@item @samp{fix_trunc@var{m}@var{n}2} 6662Like @samp{fix@var{m}@var{n}2} but works for any floating point value 6663of mode @var{m} by converting the value to an integer. 6664 6665@cindex @code{fixuns_trunc@var{m}@var{n}2} instruction pattern 6666@item @samp{fixuns_trunc@var{m}@var{n}2} 6667Like @samp{fixuns@var{m}@var{n}2} but works for any floating point 6668value of mode @var{m} by converting the value to an integer. 6669 6670@cindex @code{trunc@var{m}@var{n}2} instruction pattern 6671@item @samp{trunc@var{m}@var{n}2} 6672Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and 6673store in operand 0 (which has mode @var{n}). Both modes must be fixed 6674point or both floating point. 6675 6676@cindex @code{extend@var{m}@var{n}2} instruction pattern 6677@item @samp{extend@var{m}@var{n}2} 6678Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and 6679store in operand 0 (which has mode @var{n}). Both modes must be fixed 6680point or both floating point. 6681 6682@cindex @code{zero_extend@var{m}@var{n}2} instruction pattern 6683@item @samp{zero_extend@var{m}@var{n}2} 6684Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and 6685store in operand 0 (which has mode @var{n}). Both modes must be fixed 6686point. 6687 6688@cindex @code{fract@var{m}@var{n}2} instruction pattern 6689@item @samp{fract@var{m}@var{n}2} 6690Convert operand 1 of mode @var{m} to mode @var{n} and store in 6691operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} 6692could be fixed-point to fixed-point, signed integer to fixed-point, 6693fixed-point to signed integer, floating-point to fixed-point, 6694or fixed-point to floating-point. 6695When overflows or underflows happen, the results are undefined. 6696 6697@cindex @code{satfract@var{m}@var{n}2} instruction pattern 6698@item @samp{satfract@var{m}@var{n}2} 6699Convert operand 1 of mode @var{m} to mode @var{n} and store in 6700operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} 6701could be fixed-point to fixed-point, signed integer to fixed-point, 6702or floating-point to fixed-point. 6703When overflows or underflows happen, the instruction saturates the 6704results to the maximum or the minimum. 6705 6706@cindex @code{fractuns@var{m}@var{n}2} instruction pattern 6707@item @samp{fractuns@var{m}@var{n}2} 6708Convert operand 1 of mode @var{m} to mode @var{n} and store in 6709operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} 6710could be unsigned integer to fixed-point, or 6711fixed-point to unsigned integer. 6712When overflows or underflows happen, the results are undefined. 6713 6714@cindex @code{satfractuns@var{m}@var{n}2} instruction pattern 6715@item @samp{satfractuns@var{m}@var{n}2} 6716Convert unsigned integer operand 1 of mode @var{m} to fixed-point mode 6717@var{n} and store in operand 0 (which has mode @var{n}). 6718When overflows or underflows happen, the instruction saturates the 6719results to the maximum or the minimum. 6720 6721@cindex @code{extv@var{m}} instruction pattern 6722@item @samp{extv@var{m}} 6723Extract a bit-field from register operand 1, sign-extend it, and store 6724it in operand 0. Operand 2 specifies the width of the field in bits 6725and operand 3 the starting bit, which counts from the most significant 6726bit if @samp{BITS_BIG_ENDIAN} is true and from the least significant bit 6727otherwise. 6728 6729Operands 0 and 1 both have mode @var{m}. Operands 2 and 3 have a 6730target-specific mode. 6731 6732@cindex @code{extvmisalign@var{m}} instruction pattern 6733@item @samp{extvmisalign@var{m}} 6734Extract a bit-field from memory operand 1, sign extend it, and store 6735it in operand 0. Operand 2 specifies the width in bits and operand 3 6736the starting bit. The starting bit is always somewhere in the first byte of 6737operand 1; it counts from the most significant bit if @samp{BITS_BIG_ENDIAN} 6738is true and from the least significant bit otherwise. 6739 6740Operand 0 has mode @var{m} while operand 1 has @code{BLK} mode. 6741Operands 2 and 3 have a target-specific mode. 6742 6743The instruction must not read beyond the last byte of the bit-field. 6744 6745@cindex @code{extzv@var{m}} instruction pattern 6746@item @samp{extzv@var{m}} 6747Like @samp{extv@var{m}} except that the bit-field value is zero-extended. 6748 6749@cindex @code{extzvmisalign@var{m}} instruction pattern 6750@item @samp{extzvmisalign@var{m}} 6751Like @samp{extvmisalign@var{m}} except that the bit-field value is 6752zero-extended. 6753 6754@cindex @code{insv@var{m}} instruction pattern 6755@item @samp{insv@var{m}} 6756Insert operand 3 into a bit-field of register operand 0. Operand 1 6757specifies the width of the field in bits and operand 2 the starting bit, 6758which counts from the most significant bit if @samp{BITS_BIG_ENDIAN} 6759is true and from the least significant bit otherwise. 6760 6761Operands 0 and 3 both have mode @var{m}. Operands 1 and 2 have a 6762target-specific mode. 6763 6764@cindex @code{insvmisalign@var{m}} instruction pattern 6765@item @samp{insvmisalign@var{m}} 6766Insert operand 3 into a bit-field of memory operand 0. Operand 1 6767specifies the width of the field in bits and operand 2 the starting bit. 6768The starting bit is always somewhere in the first byte of operand 0; 6769it counts from the most significant bit if @samp{BITS_BIG_ENDIAN} 6770is true and from the least significant bit otherwise. 6771 6772Operand 3 has mode @var{m} while operand 0 has @code{BLK} mode. 6773Operands 1 and 2 have a target-specific mode. 6774 6775The instruction must not read or write beyond the last byte of the bit-field. 6776 6777@cindex @code{extv} instruction pattern 6778@item @samp{extv} 6779Extract a bit-field from operand 1 (a register or memory operand), where 6780operand 2 specifies the width in bits and operand 3 the starting bit, 6781and store it in operand 0. Operand 0 must have mode @code{word_mode}. 6782Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often 6783@code{word_mode} is allowed only for registers. Operands 2 and 3 must 6784be valid for @code{word_mode}. 6785 6786The RTL generation pass generates this instruction only with constants 6787for operands 2 and 3 and the constant is never zero for operand 2. 6788 6789The bit-field value is sign-extended to a full word integer 6790before it is stored in operand 0. 6791 6792This pattern is deprecated; please use @samp{extv@var{m}} and 6793@code{extvmisalign@var{m}} instead. 6794 6795@cindex @code{extzv} instruction pattern 6796@item @samp{extzv} 6797Like @samp{extv} except that the bit-field value is zero-extended. 6798 6799This pattern is deprecated; please use @samp{extzv@var{m}} and 6800@code{extzvmisalign@var{m}} instead. 6801 6802@cindex @code{insv} instruction pattern 6803@item @samp{insv} 6804Store operand 3 (which must be valid for @code{word_mode}) into a 6805bit-field in operand 0, where operand 1 specifies the width in bits and 6806operand 2 the starting bit. Operand 0 may have mode @code{byte_mode} or 6807@code{word_mode}; often @code{word_mode} is allowed only for registers. 6808Operands 1 and 2 must be valid for @code{word_mode}. 6809 6810The RTL generation pass generates this instruction only with constants 6811for operands 1 and 2 and the constant is never zero for operand 1. 6812 6813This pattern is deprecated; please use @samp{insv@var{m}} and 6814@code{insvmisalign@var{m}} instead. 6815 6816@cindex @code{mov@var{mode}cc} instruction pattern 6817@item @samp{mov@var{mode}cc} 6818Conditionally move operand 2 or operand 3 into operand 0 according to the 6819comparison in operand 1. If the comparison is true, operand 2 is moved 6820into operand 0, otherwise operand 3 is moved. 6821 6822The mode of the operands being compared need not be the same as the operands 6823being moved. Some machines, sparc64 for example, have instructions that 6824conditionally move an integer value based on the floating point condition 6825codes and vice versa. 6826 6827If the machine does not have conditional move instructions, do not 6828define these patterns. 6829 6830@cindex @code{add@var{mode}cc} instruction pattern 6831@item @samp{add@var{mode}cc} 6832Similar to @samp{mov@var{mode}cc} but for conditional addition. Conditionally 6833move operand 2 or (operands 2 + operand 3) into operand 0 according to the 6834comparison in operand 1. If the comparison is false, operand 2 is moved into 6835operand 0, otherwise (operand 2 + operand 3) is moved. 6836 6837@cindex @code{cond_add@var{mode}} instruction pattern 6838@cindex @code{cond_sub@var{mode}} instruction pattern 6839@cindex @code{cond_mul@var{mode}} instruction pattern 6840@cindex @code{cond_div@var{mode}} instruction pattern 6841@cindex @code{cond_udiv@var{mode}} instruction pattern 6842@cindex @code{cond_mod@var{mode}} instruction pattern 6843@cindex @code{cond_umod@var{mode}} instruction pattern 6844@cindex @code{cond_and@var{mode}} instruction pattern 6845@cindex @code{cond_ior@var{mode}} instruction pattern 6846@cindex @code{cond_xor@var{mode}} instruction pattern 6847@cindex @code{cond_smin@var{mode}} instruction pattern 6848@cindex @code{cond_smax@var{mode}} instruction pattern 6849@cindex @code{cond_umin@var{mode}} instruction pattern 6850@cindex @code{cond_umax@var{mode}} instruction pattern 6851@item @samp{cond_add@var{mode}} 6852@itemx @samp{cond_sub@var{mode}} 6853@itemx @samp{cond_mul@var{mode}} 6854@itemx @samp{cond_div@var{mode}} 6855@itemx @samp{cond_udiv@var{mode}} 6856@itemx @samp{cond_mod@var{mode}} 6857@itemx @samp{cond_umod@var{mode}} 6858@itemx @samp{cond_and@var{mode}} 6859@itemx @samp{cond_ior@var{mode}} 6860@itemx @samp{cond_xor@var{mode}} 6861@itemx @samp{cond_smin@var{mode}} 6862@itemx @samp{cond_smax@var{mode}} 6863@itemx @samp{cond_umin@var{mode}} 6864@itemx @samp{cond_umax@var{mode}} 6865When operand 1 is true, perform an operation on operands 2 and 3 and 6866store the result in operand 0, otherwise store operand 4 in operand 0. 6867The operation works elementwise if the operands are vectors. 6868 6869The scalar case is equivalent to: 6870 6871@smallexample 6872op0 = op1 ? op2 @var{op} op3 : op4; 6873@end smallexample 6874 6875while the vector case is equivalent to: 6876 6877@smallexample 6878for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++) 6879 op0[i] = op1[i] ? op2[i] @var{op} op3[i] : op4[i]; 6880@end smallexample 6881 6882where, for example, @var{op} is @code{+} for @samp{cond_add@var{mode}}. 6883 6884When defined for floating-point modes, the contents of @samp{op3[i]} 6885are not interpreted if @samp{op1[i]} is false, just like they would not 6886be in a normal C @samp{?:} condition. 6887 6888Operands 0, 2, 3 and 4 all have mode @var{m}. Operand 1 is a scalar 6889integer if @var{m} is scalar, otherwise it has the mode returned by 6890@code{TARGET_VECTORIZE_GET_MASK_MODE}. 6891 6892@cindex @code{cond_fma@var{mode}} instruction pattern 6893@cindex @code{cond_fms@var{mode}} instruction pattern 6894@cindex @code{cond_fnma@var{mode}} instruction pattern 6895@cindex @code{cond_fnms@var{mode}} instruction pattern 6896@item @samp{cond_fma@var{mode}} 6897@itemx @samp{cond_fms@var{mode}} 6898@itemx @samp{cond_fnma@var{mode}} 6899@itemx @samp{cond_fnms@var{mode}} 6900Like @samp{cond_add@var{m}}, except that the conditional operation 6901takes 3 operands rather than two. For example, the vector form of 6902@samp{cond_fma@var{mode}} is equivalent to: 6903 6904@smallexample 6905for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++) 6906 op0[i] = op1[i] ? fma (op2[i], op3[i], op4[i]) : op5[i]; 6907@end smallexample 6908 6909@cindex @code{neg@var{mode}cc} instruction pattern 6910@item @samp{neg@var{mode}cc} 6911Similar to @samp{mov@var{mode}cc} but for conditional negation. Conditionally 6912move the negation of operand 2 or the unchanged operand 3 into operand 0 6913according to the comparison in operand 1. If the comparison is true, the negation 6914of operand 2 is moved into operand 0, otherwise operand 3 is moved. 6915 6916@cindex @code{not@var{mode}cc} instruction pattern 6917@item @samp{not@var{mode}cc} 6918Similar to @samp{neg@var{mode}cc} but for conditional complement. 6919Conditionally move the bitwise complement of operand 2 or the unchanged 6920operand 3 into operand 0 according to the comparison in operand 1. 6921If the comparison is true, the complement of operand 2 is moved into 6922operand 0, otherwise operand 3 is moved. 6923 6924@cindex @code{cstore@var{mode}4} instruction pattern 6925@item @samp{cstore@var{mode}4} 6926Store zero or nonzero in operand 0 according to whether a comparison 6927is true. Operand 1 is a comparison operator. Operand 2 and operand 3 6928are the first and second operand of the comparison, respectively. 6929You specify the mode that operand 0 must have when you write the 6930@code{match_operand} expression. The compiler automatically sees which 6931mode you have used and supplies an operand of that mode. 6932 6933The value stored for a true condition must have 1 as its low bit, or 6934else must be negative. Otherwise the instruction is not suitable and 6935you should omit it from the machine description. You describe to the 6936compiler exactly which value is stored by defining the macro 6937@code{STORE_FLAG_VALUE} (@pxref{Misc}). If a description cannot be 6938found that can be used for all the possible comparison operators, you 6939should pick one and use a @code{define_expand} to map all results 6940onto the one you chose. 6941 6942These operations may @code{FAIL}, but should do so only in relatively 6943uncommon cases; if they would @code{FAIL} for common cases involving 6944integer comparisons, it is best to restrict the predicates to not 6945allow these operands. Likewise if a given comparison operator will 6946always fail, independent of the operands (for floating-point modes, the 6947@code{ordered_comparison_operator} predicate is often useful in this case). 6948 6949If this pattern is omitted, the compiler will generate a conditional 6950branch---for example, it may copy a constant one to the target and branching 6951around an assignment of zero to the target---or a libcall. If the predicate 6952for operand 1 only rejects some operators, it will also try reordering the 6953operands and/or inverting the result value (e.g.@: by an exclusive OR). 6954These possibilities could be cheaper or equivalent to the instructions 6955used for the @samp{cstore@var{mode}4} pattern followed by those required 6956to convert a positive result from @code{STORE_FLAG_VALUE} to 1; in this 6957case, you can and should make operand 1's predicate reject some operators 6958in the @samp{cstore@var{mode}4} pattern, or remove the pattern altogether 6959from the machine description. 6960 6961@cindex @code{cbranch@var{mode}4} instruction pattern 6962@item @samp{cbranch@var{mode}4} 6963Conditional branch instruction combined with a compare instruction. 6964Operand 0 is a comparison operator. Operand 1 and operand 2 are the 6965first and second operands of the comparison, respectively. Operand 3 6966is the @code{code_label} to jump to. 6967 6968@cindex @code{jump} instruction pattern 6969@item @samp{jump} 6970A jump inside a function; an unconditional branch. Operand 0 is the 6971@code{code_label} to jump to. This pattern name is mandatory on all 6972machines. 6973 6974@cindex @code{call} instruction pattern 6975@item @samp{call} 6976Subroutine call instruction returning no value. Operand 0 is the 6977function to call; operand 1 is the number of bytes of arguments pushed 6978as a @code{const_int}; operand 2 is the number of registers used as 6979operands. 6980 6981On most machines, operand 2 is not actually stored into the RTL 6982pattern. It is supplied for the sake of some RISC machines which need 6983to put this information into the assembler code; they can put it in 6984the RTL instead of operand 1. 6985 6986Operand 0 should be a @code{mem} RTX whose address is the address of the 6987function. Note, however, that this address can be a @code{symbol_ref} 6988expression even if it would not be a legitimate memory address on the 6989target machine. If it is also not a valid argument for a call 6990instruction, the pattern for this operation should be a 6991@code{define_expand} (@pxref{Expander Definitions}) that places the 6992address into a register and uses that register in the call instruction. 6993 6994@cindex @code{call_value} instruction pattern 6995@item @samp{call_value} 6996Subroutine call instruction returning a value. Operand 0 is the hard 6997register in which the value is returned. There are three more 6998operands, the same as the three operands of the @samp{call} 6999instruction (but with numbers increased by one). 7000 7001Subroutines that return @code{BLKmode} objects use the @samp{call} 7002insn. 7003 7004@cindex @code{call_pop} instruction pattern 7005@cindex @code{call_value_pop} instruction pattern 7006@item @samp{call_pop}, @samp{call_value_pop} 7007Similar to @samp{call} and @samp{call_value}, except used if defined and 7008if @code{RETURN_POPS_ARGS} is nonzero. They should emit a @code{parallel} 7009that contains both the function call and a @code{set} to indicate the 7010adjustment made to the frame pointer. 7011 7012For machines where @code{RETURN_POPS_ARGS} can be nonzero, the use of these 7013patterns increases the number of functions for which the frame pointer 7014can be eliminated, if desired. 7015 7016@cindex @code{untyped_call} instruction pattern 7017@item @samp{untyped_call} 7018Subroutine call instruction returning a value of any type. Operand 0 is 7019the function to call; operand 1 is a memory location where the result of 7020calling the function is to be stored; operand 2 is a @code{parallel} 7021expression where each element is a @code{set} expression that indicates 7022the saving of a function return value into the result block. 7023 7024This instruction pattern should be defined to support 7025@code{__builtin_apply} on machines where special instructions are needed 7026to call a subroutine with arbitrary arguments or to save the value 7027returned. This instruction pattern is required on machines that have 7028multiple registers that can hold a return value 7029(i.e.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register). 7030 7031@cindex @code{return} instruction pattern 7032@item @samp{return} 7033Subroutine return instruction. This instruction pattern name should be 7034defined only if a single instruction can do all the work of returning 7035from a function. 7036 7037Like the @samp{mov@var{m}} patterns, this pattern is also used after the 7038RTL generation phase. In this case it is to support machines where 7039multiple instructions are usually needed to return from a function, but 7040some class of functions only requires one instruction to implement a 7041return. Normally, the applicable functions are those which do not need 7042to save any registers or allocate stack space. 7043 7044It is valid for this pattern to expand to an instruction using 7045@code{simple_return} if no epilogue is required. 7046 7047@cindex @code{simple_return} instruction pattern 7048@item @samp{simple_return} 7049Subroutine return instruction. This instruction pattern name should be 7050defined only if a single instruction can do all the work of returning 7051from a function on a path where no epilogue is required. This pattern 7052is very similar to the @code{return} instruction pattern, but it is emitted 7053only by the shrink-wrapping optimization on paths where the function 7054prologue has not been executed, and a function return should occur without 7055any of the effects of the epilogue. Additional uses may be introduced on 7056paths where both the prologue and the epilogue have executed. 7057 7058@findex reload_completed 7059@findex leaf_function_p 7060For such machines, the condition specified in this pattern should only 7061be true when @code{reload_completed} is nonzero and the function's 7062epilogue would only be a single instruction. For machines with register 7063windows, the routine @code{leaf_function_p} may be used to determine if 7064a register window push is required. 7065 7066Machines that have conditional return instructions should define patterns 7067such as 7068 7069@smallexample 7070(define_insn "" 7071 [(set (pc) 7072 (if_then_else (match_operator 7073 0 "comparison_operator" 7074 [(cc0) (const_int 0)]) 7075 (return) 7076 (pc)))] 7077 "@var{condition}" 7078 "@dots{}") 7079@end smallexample 7080 7081where @var{condition} would normally be the same condition specified on the 7082named @samp{return} pattern. 7083 7084@cindex @code{untyped_return} instruction pattern 7085@item @samp{untyped_return} 7086Untyped subroutine return instruction. This instruction pattern should 7087be defined to support @code{__builtin_return} on machines where special 7088instructions are needed to return a value of any type. 7089 7090Operand 0 is a memory location where the result of calling a function 7091with @code{__builtin_apply} is stored; operand 1 is a @code{parallel} 7092expression where each element is a @code{set} expression that indicates 7093the restoring of a function return value from the result block. 7094 7095@cindex @code{nop} instruction pattern 7096@item @samp{nop} 7097No-op instruction. This instruction pattern name should always be defined 7098to output a no-op in assembler code. @code{(const_int 0)} will do as an 7099RTL pattern. 7100 7101@cindex @code{indirect_jump} instruction pattern 7102@item @samp{indirect_jump} 7103An instruction to jump to an address which is operand zero. 7104This pattern name is mandatory on all machines. 7105 7106@cindex @code{casesi} instruction pattern 7107@item @samp{casesi} 7108Instruction to jump through a dispatch table, including bounds checking. 7109This instruction takes five operands: 7110 7111@enumerate 7112@item 7113The index to dispatch on, which has mode @code{SImode}. 7114 7115@item 7116The lower bound for indices in the table, an integer constant. 7117 7118@item 7119The total range of indices in the table---the largest index 7120minus the smallest one (both inclusive). 7121 7122@item 7123A label that precedes the table itself. 7124 7125@item 7126A label to jump to if the index has a value outside the bounds. 7127@end enumerate 7128 7129The table is an @code{addr_vec} or @code{addr_diff_vec} inside of a 7130@code{jump_table_data}. The number of elements in the table is one plus the 7131difference between the upper bound and the lower bound. 7132 7133@cindex @code{tablejump} instruction pattern 7134@item @samp{tablejump} 7135Instruction to jump to a variable address. This is a low-level 7136capability which can be used to implement a dispatch table when there 7137is no @samp{casesi} pattern. 7138 7139This pattern requires two operands: the address or offset, and a label 7140which should immediately precede the jump table. If the macro 7141@code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first 7142operand is an offset which counts from the address of the table; otherwise, 7143it is an absolute address to jump to. In either case, the first operand has 7144mode @code{Pmode}. 7145 7146The @samp{tablejump} insn is always the last insn before the jump 7147table it uses. Its assembler code normally has no need to use the 7148second operand, but you should incorporate it in the RTL pattern so 7149that the jump optimizer will not delete the table as unreachable code. 7150 7151 7152@cindex @code{doloop_end} instruction pattern 7153@item @samp{doloop_end} 7154Conditional branch instruction that decrements a register and 7155jumps if the register is nonzero. Operand 0 is the register to 7156decrement and test; operand 1 is the label to jump to if the 7157register is nonzero. 7158@xref{Looping Patterns}. 7159 7160This optional instruction pattern should be defined for machines with 7161low-overhead looping instructions as the loop optimizer will try to 7162modify suitable loops to utilize it. The target hook 7163@code{TARGET_CAN_USE_DOLOOP_P} controls the conditions under which 7164low-overhead loops can be used. 7165 7166@cindex @code{doloop_begin} instruction pattern 7167@item @samp{doloop_begin} 7168Companion instruction to @code{doloop_end} required for machines that 7169need to perform some initialization, such as loading a special counter 7170register. Operand 1 is the associated @code{doloop_end} pattern and 7171operand 0 is the register that it decrements. 7172 7173If initialization insns do not always need to be emitted, use a 7174@code{define_expand} (@pxref{Expander Definitions}) and make it fail. 7175 7176@cindex @code{canonicalize_funcptr_for_compare} instruction pattern 7177@item @samp{canonicalize_funcptr_for_compare} 7178Canonicalize the function pointer in operand 1 and store the result 7179into operand 0. 7180 7181Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1 7182may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc 7183and also has mode @code{Pmode}. 7184 7185Canonicalization of a function pointer usually involves computing 7186the address of the function which would be called if the function 7187pointer were used in an indirect call. 7188 7189Only define this pattern if function pointers on the target machine 7190can have different values but still call the same function when 7191used in an indirect call. 7192 7193@cindex @code{save_stack_block} instruction pattern 7194@cindex @code{save_stack_function} instruction pattern 7195@cindex @code{save_stack_nonlocal} instruction pattern 7196@cindex @code{restore_stack_block} instruction pattern 7197@cindex @code{restore_stack_function} instruction pattern 7198@cindex @code{restore_stack_nonlocal} instruction pattern 7199@item @samp{save_stack_block} 7200@itemx @samp{save_stack_function} 7201@itemx @samp{save_stack_nonlocal} 7202@itemx @samp{restore_stack_block} 7203@itemx @samp{restore_stack_function} 7204@itemx @samp{restore_stack_nonlocal} 7205Most machines save and restore the stack pointer by copying it to or 7206from an object of mode @code{Pmode}. Do not define these patterns on 7207such machines. 7208 7209Some machines require special handling for stack pointer saves and 7210restores. On those machines, define the patterns corresponding to the 7211non-standard cases by using a @code{define_expand} (@pxref{Expander 7212Definitions}) that produces the required insns. The three types of 7213saves and restores are: 7214 7215@enumerate 7216@item 7217@samp{save_stack_block} saves the stack pointer at the start of a block 7218that allocates a variable-sized object, and @samp{restore_stack_block} 7219restores the stack pointer when the block is exited. 7220 7221@item 7222@samp{save_stack_function} and @samp{restore_stack_function} do a 7223similar job for the outermost block of a function and are used when the 7224function allocates variable-sized objects or calls @code{alloca}. Only 7225the epilogue uses the restored stack pointer, allowing a simpler save or 7226restore sequence on some machines. 7227 7228@item 7229@samp{save_stack_nonlocal} is used in functions that contain labels 7230branched to by nested functions. It saves the stack pointer in such a 7231way that the inner function can use @samp{restore_stack_nonlocal} to 7232restore the stack pointer. The compiler generates code to restore the 7233frame and argument pointer registers, but some machines require saving 7234and restoring additional data such as register window information or 7235stack backchains. Place insns in these patterns to save and restore any 7236such required data. 7237@end enumerate 7238 7239When saving the stack pointer, operand 0 is the save area and operand 1 7240is the stack pointer. The mode used to allocate the save area defaults 7241to @code{Pmode} but you can override that choice by defining the 7242@code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}). You must 7243specify an integral mode, or @code{VOIDmode} if no save area is needed 7244for a particular type of save (either because no save is needed or 7245because a machine-specific save area can be used). Operand 0 is the 7246stack pointer and operand 1 is the save area for restore operations. If 7247@samp{save_stack_block} is defined, operand 0 must not be 7248@code{VOIDmode} since these saves can be arbitrarily nested. 7249 7250A save area is a @code{mem} that is at a constant offset from 7251@code{virtual_stack_vars_rtx} when the stack pointer is saved for use by 7252nonlocal gotos and a @code{reg} in the other two cases. 7253 7254@cindex @code{allocate_stack} instruction pattern 7255@item @samp{allocate_stack} 7256Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from 7257the stack pointer to create space for dynamically allocated data. 7258 7259Store the resultant pointer to this space into operand 0. If you 7260are allocating space from the main stack, do this by emitting a 7261move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0. 7262If you are allocating the space elsewhere, generate code to copy the 7263location of the space to operand 0. In the latter case, you must 7264ensure this space gets freed when the corresponding space on the main 7265stack is free. 7266 7267Do not define this pattern if all that must be done is the subtraction. 7268Some machines require other operations such as stack probes or 7269maintaining the back chain. Define this pattern to emit those 7270operations in addition to updating the stack pointer. 7271 7272@cindex @code{check_stack} instruction pattern 7273@item @samp{check_stack} 7274If stack checking (@pxref{Stack Checking}) cannot be done on your system by 7275probing the stack, define this pattern to perform the needed check and signal 7276an error if the stack has overflowed. The single operand is the address in 7277the stack farthest from the current stack pointer that you need to validate. 7278Normally, on platforms where this pattern is needed, you would obtain the 7279stack limit from a global or thread-specific variable or register. 7280 7281@cindex @code{probe_stack_address} instruction pattern 7282@item @samp{probe_stack_address} 7283If stack checking (@pxref{Stack Checking}) can be done on your system by 7284probing the stack but without the need to actually access it, define this 7285pattern and signal an error if the stack has overflowed. The single operand 7286is the memory address in the stack that needs to be probed. 7287 7288@cindex @code{probe_stack} instruction pattern 7289@item @samp{probe_stack} 7290If stack checking (@pxref{Stack Checking}) can be done on your system by 7291probing the stack but doing it with a ``store zero'' instruction is not valid 7292or optimal, define this pattern to do the probing differently and signal an 7293error if the stack has overflowed. The single operand is the memory reference 7294in the stack that needs to be probed. 7295 7296@cindex @code{nonlocal_goto} instruction pattern 7297@item @samp{nonlocal_goto} 7298Emit code to generate a non-local goto, e.g., a jump from one function 7299to a label in an outer function. This pattern has four arguments, 7300each representing a value to be used in the jump. The first 7301argument is to be loaded into the frame pointer, the second is 7302the address to branch to (code to dispatch to the actual label), 7303the third is the address of a location where the stack is saved, 7304and the last is the address of the label, to be placed in the 7305location for the incoming static chain. 7306 7307On most machines you need not define this pattern, since GCC will 7308already generate the correct code, which is to load the frame pointer 7309and static chain, restore the stack (using the 7310@samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly 7311to the dispatcher. You need only define this pattern if this code will 7312not work on your machine. 7313 7314@cindex @code{nonlocal_goto_receiver} instruction pattern 7315@item @samp{nonlocal_goto_receiver} 7316This pattern, if defined, contains code needed at the target of a 7317nonlocal goto after the code already generated by GCC@. You will not 7318normally need to define this pattern. A typical reason why you might 7319need this pattern is if some value, such as a pointer to a global table, 7320must be restored when the frame pointer is restored. Note that a nonlocal 7321goto only occurs within a unit-of-translation, so a global table pointer 7322that is shared by all functions of a given module need not be restored. 7323There are no arguments. 7324 7325@cindex @code{exception_receiver} instruction pattern 7326@item @samp{exception_receiver} 7327This pattern, if defined, contains code needed at the site of an 7328exception handler that isn't needed at the site of a nonlocal goto. You 7329will not normally need to define this pattern. A typical reason why you 7330might need this pattern is if some value, such as a pointer to a global 7331table, must be restored after control flow is branched to the handler of 7332an exception. There are no arguments. 7333 7334@cindex @code{builtin_setjmp_setup} instruction pattern 7335@item @samp{builtin_setjmp_setup} 7336This pattern, if defined, contains additional code needed to initialize 7337the @code{jmp_buf}. You will not normally need to define this pattern. 7338A typical reason why you might need this pattern is if some value, such 7339as a pointer to a global table, must be restored. Though it is 7340preferred that the pointer value be recalculated if possible (given the 7341address of a label for instance). The single argument is a pointer to 7342the @code{jmp_buf}. Note that the buffer is five words long and that 7343the first three are normally used by the generic mechanism. 7344 7345@cindex @code{builtin_setjmp_receiver} instruction pattern 7346@item @samp{builtin_setjmp_receiver} 7347This pattern, if defined, contains code needed at the site of a 7348built-in setjmp that isn't needed at the site of a nonlocal goto. You 7349will not normally need to define this pattern. A typical reason why you 7350might need this pattern is if some value, such as a pointer to a global 7351table, must be restored. It takes one argument, which is the label 7352to which builtin_longjmp transferred control; this pattern may be emitted 7353at a small offset from that label. 7354 7355@cindex @code{builtin_longjmp} instruction pattern 7356@item @samp{builtin_longjmp} 7357This pattern, if defined, performs the entire action of the longjmp. 7358You will not normally need to define this pattern unless you also define 7359@code{builtin_setjmp_setup}. The single argument is a pointer to the 7360@code{jmp_buf}. 7361 7362@cindex @code{eh_return} instruction pattern 7363@item @samp{eh_return} 7364This pattern, if defined, affects the way @code{__builtin_eh_return}, 7365and thence the call frame exception handling library routines, are 7366built. It is intended to handle non-trivial actions needed along 7367the abnormal return path. 7368 7369The address of the exception handler to which the function should return 7370is passed as operand to this pattern. It will normally need to copied by 7371the pattern to some special register or memory location. 7372If the pattern needs to determine the location of the target call 7373frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX}, 7374if defined; it will have already been assigned. 7375 7376If this pattern is not defined, the default action will be to simply 7377copy the return address to @code{EH_RETURN_HANDLER_RTX}. Either 7378that macro or this pattern needs to be defined if call frame exception 7379handling is to be used. 7380 7381@cindex @code{prologue} instruction pattern 7382@anchor{prologue instruction pattern} 7383@item @samp{prologue} 7384This pattern, if defined, emits RTL for entry to a function. The function 7385entry is responsible for setting up the stack frame, initializing the frame 7386pointer register, saving callee saved registers, etc. 7387 7388Using a prologue pattern is generally preferred over defining 7389@code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue. 7390 7391The @code{prologue} pattern is particularly useful for targets which perform 7392instruction scheduling. 7393 7394@cindex @code{window_save} instruction pattern 7395@anchor{window_save instruction pattern} 7396@item @samp{window_save} 7397This pattern, if defined, emits RTL for a register window save. It should 7398be defined if the target machine has register windows but the window events 7399are decoupled from calls to subroutines. The canonical example is the SPARC 7400architecture. 7401 7402@cindex @code{epilogue} instruction pattern 7403@anchor{epilogue instruction pattern} 7404@item @samp{epilogue} 7405This pattern emits RTL for exit from a function. The function 7406exit is responsible for deallocating the stack frame, restoring callee saved 7407registers and emitting the return instruction. 7408 7409Using an epilogue pattern is generally preferred over defining 7410@code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue. 7411 7412The @code{epilogue} pattern is particularly useful for targets which perform 7413instruction scheduling or which have delay slots for their return instruction. 7414 7415@cindex @code{sibcall_epilogue} instruction pattern 7416@item @samp{sibcall_epilogue} 7417This pattern, if defined, emits RTL for exit from a function without the final 7418branch back to the calling function. This pattern will be emitted before any 7419sibling call (aka tail call) sites. 7420 7421The @code{sibcall_epilogue} pattern must not clobber any arguments used for 7422parameter passing or any stack slots for arguments passed to the current 7423function. 7424 7425@cindex @code{trap} instruction pattern 7426@item @samp{trap} 7427This pattern, if defined, signals an error, typically by causing some 7428kind of signal to be raised. 7429 7430@cindex @code{ctrap@var{MM}4} instruction pattern 7431@item @samp{ctrap@var{MM}4} 7432Conditional trap instruction. Operand 0 is a piece of RTL which 7433performs a comparison, and operands 1 and 2 are the arms of the 7434comparison. Operand 3 is the trap code, an integer. 7435 7436A typical @code{ctrap} pattern looks like 7437 7438@smallexample 7439(define_insn "ctrapsi4" 7440 [(trap_if (match_operator 0 "trap_operator" 7441 [(match_operand 1 "register_operand") 7442 (match_operand 2 "immediate_operand")]) 7443 (match_operand 3 "const_int_operand" "i"))] 7444 "" 7445 "@dots{}") 7446@end smallexample 7447 7448@cindex @code{prefetch} instruction pattern 7449@item @samp{prefetch} 7450This pattern, if defined, emits code for a non-faulting data prefetch 7451instruction. Operand 0 is the address of the memory to prefetch. Operand 1 7452is a constant 1 if the prefetch is preparing for a write to the memory 7453address, or a constant 0 otherwise. Operand 2 is the expected degree of 7454temporal locality of the data and is a value between 0 and 3, inclusive; 0 7455means that the data has no temporal locality, so it need not be left in the 7456cache after the access; 3 means that the data has a high degree of temporal 7457locality and should be left in all levels of cache possible; 1 and 2 mean, 7458respectively, a low or moderate degree of temporal locality. 7459 7460Targets that do not support write prefetches or locality hints can ignore 7461the values of operands 1 and 2. 7462 7463@cindex @code{blockage} instruction pattern 7464@item @samp{blockage} 7465This pattern defines a pseudo insn that prevents the instruction 7466scheduler and other passes from moving instructions and using register 7467equivalences across the boundary defined by the blockage insn. 7468This needs to be an UNSPEC_VOLATILE pattern or a volatile ASM. 7469 7470@cindex @code{memory_blockage} instruction pattern 7471@item @samp{memory_blockage} 7472This pattern, if defined, represents a compiler memory barrier, and will be 7473placed at points across which RTL passes may not propagate memory accesses. 7474This instruction needs to read and write volatile BLKmode memory. It does 7475not need to generate any machine instruction. If this pattern is not defined, 7476the compiler falls back to emitting an instruction corresponding 7477to @code{asm volatile ("" ::: "memory")}. 7478 7479@cindex @code{memory_barrier} instruction pattern 7480@item @samp{memory_barrier} 7481If the target memory model is not fully synchronous, then this pattern 7482should be defined to an instruction that orders both loads and stores 7483before the instruction with respect to loads and stores after the instruction. 7484This pattern has no operands. 7485 7486@cindex @code{speculation_barrier} instruction pattern 7487@item @samp{speculation_barrier} 7488If the target can support speculative execution, then this pattern should 7489be defined to an instruction that will block subsequent execution until 7490any prior speculation conditions has been resolved. The pattern must also 7491ensure that the compiler cannot move memory operations past the barrier, 7492so it needs to be an UNSPEC_VOLATILE pattern. The pattern has no 7493operands. 7494 7495If this pattern is not defined then the default expansion of 7496@code{__builtin_speculation_safe_value} will emit a warning. You can 7497suppress this warning by defining this pattern with a final condition 7498of @code{0} (zero), which tells the compiler that a speculation 7499barrier is not needed for this target. 7500 7501@cindex @code{sync_compare_and_swap@var{mode}} instruction pattern 7502@item @samp{sync_compare_and_swap@var{mode}} 7503This pattern, if defined, emits code for an atomic compare-and-swap 7504operation. Operand 1 is the memory on which the atomic operation is 7505performed. Operand 2 is the ``old'' value to be compared against the 7506current contents of the memory location. Operand 3 is the ``new'' value 7507to store in the memory if the compare succeeds. Operand 0 is the result 7508of the operation; it should contain the contents of the memory 7509before the operation. If the compare succeeds, this should obviously be 7510a copy of operand 2. 7511 7512This pattern must show that both operand 0 and operand 1 are modified. 7513 7514This pattern must issue any memory barrier instructions such that all 7515memory operations before the atomic operation occur before the atomic 7516operation and all memory operations after the atomic operation occur 7517after the atomic operation. 7518 7519For targets where the success or failure of the compare-and-swap 7520operation is available via the status flags, it is possible to 7521avoid a separate compare operation and issue the subsequent 7522branch or store-flag operation immediately after the compare-and-swap. 7523To this end, GCC will look for a @code{MODE_CC} set in the 7524output of @code{sync_compare_and_swap@var{mode}}; if the machine 7525description includes such a set, the target should also define special 7526@code{cbranchcc4} and/or @code{cstorecc4} instructions. GCC will then 7527be able to take the destination of the @code{MODE_CC} set and pass it 7528to the @code{cbranchcc4} or @code{cstorecc4} pattern as the first 7529operand of the comparison (the second will be @code{(const_int 0)}). 7530 7531For targets where the operating system may provide support for this 7532operation via library calls, the @code{sync_compare_and_swap_optab} 7533may be initialized to a function with the same interface as the 7534@code{__sync_val_compare_and_swap_@var{n}} built-in. If the entire 7535set of @var{__sync} builtins are supported via library calls, the 7536target can initialize all of the optabs at once with 7537@code{init_sync_libfuncs}. 7538For the purposes of C++11 @code{std::atomic::is_lock_free}, it is 7539assumed that these library calls do @emph{not} use any kind of 7540interruptable locking. 7541 7542@cindex @code{sync_add@var{mode}} instruction pattern 7543@cindex @code{sync_sub@var{mode}} instruction pattern 7544@cindex @code{sync_ior@var{mode}} instruction pattern 7545@cindex @code{sync_and@var{mode}} instruction pattern 7546@cindex @code{sync_xor@var{mode}} instruction pattern 7547@cindex @code{sync_nand@var{mode}} instruction pattern 7548@item @samp{sync_add@var{mode}}, @samp{sync_sub@var{mode}} 7549@itemx @samp{sync_ior@var{mode}}, @samp{sync_and@var{mode}} 7550@itemx @samp{sync_xor@var{mode}}, @samp{sync_nand@var{mode}} 7551These patterns emit code for an atomic operation on memory. 7552Operand 0 is the memory on which the atomic operation is performed. 7553Operand 1 is the second operand to the binary operator. 7554 7555This pattern must issue any memory barrier instructions such that all 7556memory operations before the atomic operation occur before the atomic 7557operation and all memory operations after the atomic operation occur 7558after the atomic operation. 7559 7560If these patterns are not defined, the operation will be constructed 7561from a compare-and-swap operation, if defined. 7562 7563@cindex @code{sync_old_add@var{mode}} instruction pattern 7564@cindex @code{sync_old_sub@var{mode}} instruction pattern 7565@cindex @code{sync_old_ior@var{mode}} instruction pattern 7566@cindex @code{sync_old_and@var{mode}} instruction pattern 7567@cindex @code{sync_old_xor@var{mode}} instruction pattern 7568@cindex @code{sync_old_nand@var{mode}} instruction pattern 7569@item @samp{sync_old_add@var{mode}}, @samp{sync_old_sub@var{mode}} 7570@itemx @samp{sync_old_ior@var{mode}}, @samp{sync_old_and@var{mode}} 7571@itemx @samp{sync_old_xor@var{mode}}, @samp{sync_old_nand@var{mode}} 7572These patterns emit code for an atomic operation on memory, 7573and return the value that the memory contained before the operation. 7574Operand 0 is the result value, operand 1 is the memory on which the 7575atomic operation is performed, and operand 2 is the second operand 7576to the binary operator. 7577 7578This pattern must issue any memory barrier instructions such that all 7579memory operations before the atomic operation occur before the atomic 7580operation and all memory operations after the atomic operation occur 7581after the atomic operation. 7582 7583If these patterns are not defined, the operation will be constructed 7584from a compare-and-swap operation, if defined. 7585 7586@cindex @code{sync_new_add@var{mode}} instruction pattern 7587@cindex @code{sync_new_sub@var{mode}} instruction pattern 7588@cindex @code{sync_new_ior@var{mode}} instruction pattern 7589@cindex @code{sync_new_and@var{mode}} instruction pattern 7590@cindex @code{sync_new_xor@var{mode}} instruction pattern 7591@cindex @code{sync_new_nand@var{mode}} instruction pattern 7592@item @samp{sync_new_add@var{mode}}, @samp{sync_new_sub@var{mode}} 7593@itemx @samp{sync_new_ior@var{mode}}, @samp{sync_new_and@var{mode}} 7594@itemx @samp{sync_new_xor@var{mode}}, @samp{sync_new_nand@var{mode}} 7595These patterns are like their @code{sync_old_@var{op}} counterparts, 7596except that they return the value that exists in the memory location 7597after the operation, rather than before the operation. 7598 7599@cindex @code{sync_lock_test_and_set@var{mode}} instruction pattern 7600@item @samp{sync_lock_test_and_set@var{mode}} 7601This pattern takes two forms, based on the capabilities of the target. 7602In either case, operand 0 is the result of the operand, operand 1 is 7603the memory on which the atomic operation is performed, and operand 2 7604is the value to set in the lock. 7605 7606In the ideal case, this operation is an atomic exchange operation, in 7607which the previous value in memory operand is copied into the result 7608operand, and the value operand is stored in the memory operand. 7609 7610For less capable targets, any value operand that is not the constant 1 7611should be rejected with @code{FAIL}. In this case the target may use 7612an atomic test-and-set bit operation. The result operand should contain 76131 if the bit was previously set and 0 if the bit was previously clear. 7614The true contents of the memory operand are implementation defined. 7615 7616This pattern must issue any memory barrier instructions such that the 7617pattern as a whole acts as an acquire barrier, that is all memory 7618operations after the pattern do not occur until the lock is acquired. 7619 7620If this pattern is not defined, the operation will be constructed from 7621a compare-and-swap operation, if defined. 7622 7623@cindex @code{sync_lock_release@var{mode}} instruction pattern 7624@item @samp{sync_lock_release@var{mode}} 7625This pattern, if defined, releases a lock set by 7626@code{sync_lock_test_and_set@var{mode}}. Operand 0 is the memory 7627that contains the lock; operand 1 is the value to store in the lock. 7628 7629If the target doesn't implement full semantics for 7630@code{sync_lock_test_and_set@var{mode}}, any value operand which is not 7631the constant 0 should be rejected with @code{FAIL}, and the true contents 7632of the memory operand are implementation defined. 7633 7634This pattern must issue any memory barrier instructions such that the 7635pattern as a whole acts as a release barrier, that is the lock is 7636released only after all previous memory operations have completed. 7637 7638If this pattern is not defined, then a @code{memory_barrier} pattern 7639will be emitted, followed by a store of the value to the memory operand. 7640 7641@cindex @code{atomic_compare_and_swap@var{mode}} instruction pattern 7642@item @samp{atomic_compare_and_swap@var{mode}} 7643This pattern, if defined, emits code for an atomic compare-and-swap 7644operation with memory model semantics. Operand 2 is the memory on which 7645the atomic operation is performed. Operand 0 is an output operand which 7646is set to true or false based on whether the operation succeeded. Operand 76471 is an output operand which is set to the contents of the memory before 7648the operation was attempted. Operand 3 is the value that is expected to 7649be in memory. Operand 4 is the value to put in memory if the expected 7650value is found there. Operand 5 is set to 1 if this compare and swap is to 7651be treated as a weak operation. Operand 6 is the memory model to be used 7652if the operation is a success. Operand 7 is the memory model to be used 7653if the operation fails. 7654 7655If memory referred to in operand 2 contains the value in operand 3, then 7656operand 4 is stored in memory pointed to by operand 2 and fencing based on 7657the memory model in operand 6 is issued. 7658 7659If memory referred to in operand 2 does not contain the value in operand 3, 7660then fencing based on the memory model in operand 7 is issued. 7661 7662If a target does not support weak compare-and-swap operations, or the port 7663elects not to implement weak operations, the argument in operand 5 can be 7664ignored. Note a strong implementation must be provided. 7665 7666If this pattern is not provided, the @code{__atomic_compare_exchange} 7667built-in functions will utilize the legacy @code{sync_compare_and_swap} 7668pattern with an @code{__ATOMIC_SEQ_CST} memory model. 7669 7670@cindex @code{atomic_load@var{mode}} instruction pattern 7671@item @samp{atomic_load@var{mode}} 7672This pattern implements an atomic load operation with memory model 7673semantics. Operand 1 is the memory address being loaded from. Operand 0 7674is the result of the load. Operand 2 is the memory model to be used for 7675the load operation. 7676 7677If not present, the @code{__atomic_load} built-in function will either 7678resort to a normal load with memory barriers, or a compare-and-swap 7679operation if a normal load would not be atomic. 7680 7681@cindex @code{atomic_store@var{mode}} instruction pattern 7682@item @samp{atomic_store@var{mode}} 7683This pattern implements an atomic store operation with memory model 7684semantics. Operand 0 is the memory address being stored to. Operand 1 7685is the value to be written. Operand 2 is the memory model to be used for 7686the operation. 7687 7688If not present, the @code{__atomic_store} built-in function will attempt to 7689perform a normal store and surround it with any required memory fences. If 7690the store would not be atomic, then an @code{__atomic_exchange} is 7691attempted with the result being ignored. 7692 7693@cindex @code{atomic_exchange@var{mode}} instruction pattern 7694@item @samp{atomic_exchange@var{mode}} 7695This pattern implements an atomic exchange operation with memory model 7696semantics. Operand 1 is the memory location the operation is performed on. 7697Operand 0 is an output operand which is set to the original value contained 7698in the memory pointed to by operand 1. Operand 2 is the value to be 7699stored. Operand 3 is the memory model to be used. 7700 7701If this pattern is not present, the built-in function 7702@code{__atomic_exchange} will attempt to preform the operation with a 7703compare and swap loop. 7704 7705@cindex @code{atomic_add@var{mode}} instruction pattern 7706@cindex @code{atomic_sub@var{mode}} instruction pattern 7707@cindex @code{atomic_or@var{mode}} instruction pattern 7708@cindex @code{atomic_and@var{mode}} instruction pattern 7709@cindex @code{atomic_xor@var{mode}} instruction pattern 7710@cindex @code{atomic_nand@var{mode}} instruction pattern 7711@item @samp{atomic_add@var{mode}}, @samp{atomic_sub@var{mode}} 7712@itemx @samp{atomic_or@var{mode}}, @samp{atomic_and@var{mode}} 7713@itemx @samp{atomic_xor@var{mode}}, @samp{atomic_nand@var{mode}} 7714These patterns emit code for an atomic operation on memory with memory 7715model semantics. Operand 0 is the memory on which the atomic operation is 7716performed. Operand 1 is the second operand to the binary operator. 7717Operand 2 is the memory model to be used by the operation. 7718 7719If these patterns are not defined, attempts will be made to use legacy 7720@code{sync} patterns, or equivalent patterns which return a result. If 7721none of these are available a compare-and-swap loop will be used. 7722 7723@cindex @code{atomic_fetch_add@var{mode}} instruction pattern 7724@cindex @code{atomic_fetch_sub@var{mode}} instruction pattern 7725@cindex @code{atomic_fetch_or@var{mode}} instruction pattern 7726@cindex @code{atomic_fetch_and@var{mode}} instruction pattern 7727@cindex @code{atomic_fetch_xor@var{mode}} instruction pattern 7728@cindex @code{atomic_fetch_nand@var{mode}} instruction pattern 7729@item @samp{atomic_fetch_add@var{mode}}, @samp{atomic_fetch_sub@var{mode}} 7730@itemx @samp{atomic_fetch_or@var{mode}}, @samp{atomic_fetch_and@var{mode}} 7731@itemx @samp{atomic_fetch_xor@var{mode}}, @samp{atomic_fetch_nand@var{mode}} 7732These patterns emit code for an atomic operation on memory with memory 7733model semantics, and return the original value. Operand 0 is an output 7734operand which contains the value of the memory location before the 7735operation was performed. Operand 1 is the memory on which the atomic 7736operation is performed. Operand 2 is the second operand to the binary 7737operator. Operand 3 is the memory model to be used by the operation. 7738 7739If these patterns are not defined, attempts will be made to use legacy 7740@code{sync} patterns. If none of these are available a compare-and-swap 7741loop will be used. 7742 7743@cindex @code{atomic_add_fetch@var{mode}} instruction pattern 7744@cindex @code{atomic_sub_fetch@var{mode}} instruction pattern 7745@cindex @code{atomic_or_fetch@var{mode}} instruction pattern 7746@cindex @code{atomic_and_fetch@var{mode}} instruction pattern 7747@cindex @code{atomic_xor_fetch@var{mode}} instruction pattern 7748@cindex @code{atomic_nand_fetch@var{mode}} instruction pattern 7749@item @samp{atomic_add_fetch@var{mode}}, @samp{atomic_sub_fetch@var{mode}} 7750@itemx @samp{atomic_or_fetch@var{mode}}, @samp{atomic_and_fetch@var{mode}} 7751@itemx @samp{atomic_xor_fetch@var{mode}}, @samp{atomic_nand_fetch@var{mode}} 7752These patterns emit code for an atomic operation on memory with memory 7753model semantics and return the result after the operation is performed. 7754Operand 0 is an output operand which contains the value after the 7755operation. Operand 1 is the memory on which the atomic operation is 7756performed. Operand 2 is the second operand to the binary operator. 7757Operand 3 is the memory model to be used by the operation. 7758 7759If these patterns are not defined, attempts will be made to use legacy 7760@code{sync} patterns, or equivalent patterns which return the result before 7761the operation followed by the arithmetic operation required to produce the 7762result. If none of these are available a compare-and-swap loop will be 7763used. 7764 7765@cindex @code{atomic_test_and_set} instruction pattern 7766@item @samp{atomic_test_and_set} 7767This pattern emits code for @code{__builtin_atomic_test_and_set}. 7768Operand 0 is an output operand which is set to true if the previous 7769previous contents of the byte was "set", and false otherwise. Operand 1 7770is the @code{QImode} memory to be modified. Operand 2 is the memory 7771model to be used. 7772 7773The specific value that defines "set" is implementation defined, and 7774is normally based on what is performed by the native atomic test and set 7775instruction. 7776 7777@cindex @code{atomic_bit_test_and_set@var{mode}} instruction pattern 7778@cindex @code{atomic_bit_test_and_complement@var{mode}} instruction pattern 7779@cindex @code{atomic_bit_test_and_reset@var{mode}} instruction pattern 7780@item @samp{atomic_bit_test_and_set@var{mode}} 7781@itemx @samp{atomic_bit_test_and_complement@var{mode}} 7782@itemx @samp{atomic_bit_test_and_reset@var{mode}} 7783These patterns emit code for an atomic bitwise operation on memory with memory 7784model semantics, and return the original value of the specified bit. 7785Operand 0 is an output operand which contains the value of the specified bit 7786from the memory location before the operation was performed. Operand 1 is the 7787memory on which the atomic operation is performed. Operand 2 is the bit within 7788the operand, starting with least significant bit. Operand 3 is the memory model 7789to be used by the operation. Operand 4 is a flag - it is @code{const1_rtx} 7790if operand 0 should contain the original value of the specified bit in the 7791least significant bit of the operand, and @code{const0_rtx} if the bit should 7792be in its original position in the operand. 7793@code{atomic_bit_test_and_set@var{mode}} atomically sets the specified bit after 7794remembering its original value, @code{atomic_bit_test_and_complement@var{mode}} 7795inverts the specified bit and @code{atomic_bit_test_and_reset@var{mode}} clears 7796the specified bit. 7797 7798If these patterns are not defined, attempts will be made to use 7799@code{atomic_fetch_or@var{mode}}, @code{atomic_fetch_xor@var{mode}} or 7800@code{atomic_fetch_and@var{mode}} instruction patterns, or their @code{sync} 7801counterparts. If none of these are available a compare-and-swap 7802loop will be used. 7803 7804@cindex @code{mem_thread_fence} instruction pattern 7805@item @samp{mem_thread_fence} 7806This pattern emits code required to implement a thread fence with 7807memory model semantics. Operand 0 is the memory model to be used. 7808 7809For the @code{__ATOMIC_RELAXED} model no instructions need to be issued 7810and this expansion is not invoked. 7811 7812The compiler always emits a compiler memory barrier regardless of what 7813expanding this pattern produced. 7814 7815If this pattern is not defined, the compiler falls back to expanding the 7816@code{memory_barrier} pattern, then to emitting @code{__sync_synchronize} 7817library call, and finally to just placing a compiler memory barrier. 7818 7819@cindex @code{get_thread_pointer@var{mode}} instruction pattern 7820@cindex @code{set_thread_pointer@var{mode}} instruction pattern 7821@item @samp{get_thread_pointer@var{mode}} 7822@itemx @samp{set_thread_pointer@var{mode}} 7823These patterns emit code that reads/sets the TLS thread pointer. Currently, 7824these are only needed if the target needs to support the 7825@code{__builtin_thread_pointer} and @code{__builtin_set_thread_pointer} 7826builtins. 7827 7828The get/set patterns have a single output/input operand respectively, 7829with @var{mode} intended to be @code{Pmode}. 7830 7831@cindex @code{stack_protect_combined_set} instruction pattern 7832@item @samp{stack_protect_combined_set} 7833This pattern, if defined, moves a @code{ptr_mode} value from an address 7834whose declaration RTX is given in operand 1 to the memory in operand 0 7835without leaving the value in a register afterward. If several 7836instructions are needed by the target to perform the operation (eg. to 7837load the address from a GOT entry then load the @code{ptr_mode} value 7838and finally store it), it is the backend's responsibility to ensure no 7839intermediate result gets spilled. This is to avoid leaking the value 7840some place that an attacker might use to rewrite the stack guard slot 7841after having clobbered it. 7842 7843If this pattern is not defined, then the address declaration is 7844expanded first in the standard way and a @code{stack_protect_set} 7845pattern is then generated to move the value from that address to the 7846address in operand 0. 7847 7848@cindex @code{stack_protect_set} instruction pattern 7849@item @samp{stack_protect_set} 7850This pattern, if defined, moves a @code{ptr_mode} value from the valid 7851memory location in operand 1 to the memory in operand 0 without leaving 7852the value in a register afterward. This is to avoid leaking the value 7853some place that an attacker might use to rewrite the stack guard slot 7854after having clobbered it. 7855 7856Note: on targets where the addressing modes do not allow to load 7857directly from stack guard address, the address is expanded in a standard 7858way first which could cause some spills. 7859 7860If this pattern is not defined, then a plain move pattern is generated. 7861 7862@cindex @code{stack_protect_combined_test} instruction pattern 7863@item @samp{stack_protect_combined_test} 7864This pattern, if defined, compares a @code{ptr_mode} value from an 7865address whose declaration RTX is given in operand 1 with the memory in 7866operand 0 without leaving the value in a register afterward and 7867branches to operand 2 if the values were equal. If several 7868instructions are needed by the target to perform the operation (eg. to 7869load the address from a GOT entry then load the @code{ptr_mode} value 7870and finally store it), it is the backend's responsibility to ensure no 7871intermediate result gets spilled. This is to avoid leaking the value 7872some place that an attacker might use to rewrite the stack guard slot 7873after having clobbered it. 7874 7875If this pattern is not defined, then the address declaration is 7876expanded first in the standard way and a @code{stack_protect_test} 7877pattern is then generated to compare the value from that address to the 7878value at the memory in operand 0. 7879 7880@cindex @code{stack_protect_test} instruction pattern 7881@item @samp{stack_protect_test} 7882This pattern, if defined, compares a @code{ptr_mode} value from the 7883valid memory location in operand 1 with the memory in operand 0 without 7884leaving the value in a register afterward and branches to operand 2 if 7885the values were equal. 7886 7887If this pattern is not defined, then a plain compare pattern and 7888conditional branch pattern is used. 7889 7890@cindex @code{clear_cache} instruction pattern 7891@item @samp{clear_cache} 7892This pattern, if defined, flushes the instruction cache for a region of 7893memory. The region is bounded to by the Pmode pointers in operand 0 7894inclusive and operand 1 exclusive. 7895 7896If this pattern is not defined, a call to the library function 7897@code{__clear_cache} is used. 7898 7899@end table 7900 7901@end ifset 7902@c Each of the following nodes are wrapped in separate 7903@c "@ifset INTERNALS" to work around memory limits for the default 7904@c configuration in older tetex distributions. Known to not work: 7905@c tetex-1.0.7, known to work: tetex-2.0.2. 7906@ifset INTERNALS 7907@node Pattern Ordering 7908@section When the Order of Patterns Matters 7909@cindex Pattern Ordering 7910@cindex Ordering of Patterns 7911 7912Sometimes an insn can match more than one instruction pattern. Then the 7913pattern that appears first in the machine description is the one used. 7914Therefore, more specific patterns (patterns that will match fewer things) 7915and faster instructions (those that will produce better code when they 7916do match) should usually go first in the description. 7917 7918In some cases the effect of ordering the patterns can be used to hide 7919a pattern when it is not valid. For example, the 68000 has an 7920instruction for converting a fullword to floating point and another 7921for converting a byte to floating point. An instruction converting 7922an integer to floating point could match either one. We put the 7923pattern to convert the fullword first to make sure that one will 7924be used rather than the other. (Otherwise a large integer might 7925be generated as a single-byte immediate quantity, which would not work.) 7926Instead of using this pattern ordering it would be possible to make the 7927pattern for convert-a-byte smart enough to deal properly with any 7928constant value. 7929 7930@end ifset 7931@ifset INTERNALS 7932@node Dependent Patterns 7933@section Interdependence of Patterns 7934@cindex Dependent Patterns 7935@cindex Interdependence of Patterns 7936 7937In some cases machines support instructions identical except for the 7938machine mode of one or more operands. For example, there may be 7939``sign-extend halfword'' and ``sign-extend byte'' instructions whose 7940patterns are 7941 7942@smallexample 7943(set (match_operand:SI 0 @dots{}) 7944 (extend:SI (match_operand:HI 1 @dots{}))) 7945 7946(set (match_operand:SI 0 @dots{}) 7947 (extend:SI (match_operand:QI 1 @dots{}))) 7948@end smallexample 7949 7950@noindent 7951Constant integers do not specify a machine mode, so an instruction to 7952extend a constant value could match either pattern. The pattern it 7953actually will match is the one that appears first in the file. For correct 7954results, this must be the one for the widest possible mode (@code{HImode}, 7955here). If the pattern matches the @code{QImode} instruction, the results 7956will be incorrect if the constant value does not actually fit that mode. 7957 7958Such instructions to extend constants are rarely generated because they are 7959optimized away, but they do occasionally happen in nonoptimized 7960compilations. 7961 7962If a constraint in a pattern allows a constant, the reload pass may 7963replace a register with a constant permitted by the constraint in some 7964cases. Similarly for memory references. Because of this substitution, 7965you should not provide separate patterns for increment and decrement 7966instructions. Instead, they should be generated from the same pattern 7967that supports register-register add insns by examining the operands and 7968generating the appropriate machine instruction. 7969 7970@end ifset 7971@ifset INTERNALS 7972@node Jump Patterns 7973@section Defining Jump Instruction Patterns 7974@cindex jump instruction patterns 7975@cindex defining jump instruction patterns 7976 7977GCC does not assume anything about how the machine realizes jumps. 7978The machine description should define a single pattern, usually 7979a @code{define_expand}, which expands to all the required insns. 7980 7981Usually, this would be a comparison insn to set the condition code 7982and a separate branch insn testing the condition code and branching 7983or not according to its value. For many machines, however, 7984separating compares and branches is limiting, which is why the 7985more flexible approach with one @code{define_expand} is used in GCC. 7986The machine description becomes clearer for architectures that 7987have compare-and-branch instructions but no condition code. It also 7988works better when different sets of comparison operators are supported 7989by different kinds of conditional branches (e.g.@: integer vs.@: 7990floating-point), or by conditional branches with respect to conditional stores. 7991 7992Two separate insns are always used if the machine description represents 7993a condition code register using the legacy RTL expression @code{(cc0)}, 7994and on most machines that use a separate condition code register 7995(@pxref{Condition Code}). For machines that use @code{(cc0)}, in 7996fact, the set and use of the condition code must be separate and 7997adjacent@footnote{@code{note} insns can separate them, though.}, thus 7998allowing flags in @code{cc_status} to be used (@pxref{Condition Code}) and 7999so that the comparison and branch insns could be located from each other 8000by using the functions @code{prev_cc0_setter} and @code{next_cc0_user}. 8001 8002Even in this case having a single entry point for conditional branches 8003is advantageous, because it handles equally well the case where a single 8004comparison instruction records the results of both signed and unsigned 8005comparison of the given operands (with the branch insns coming in distinct 8006signed and unsigned flavors) as in the x86 or SPARC, and the case where 8007there are distinct signed and unsigned compare instructions and only 8008one set of conditional branch instructions as in the PowerPC. 8009 8010@end ifset 8011@ifset INTERNALS 8012@node Looping Patterns 8013@section Defining Looping Instruction Patterns 8014@cindex looping instruction patterns 8015@cindex defining looping instruction patterns 8016 8017Some machines have special jump instructions that can be utilized to 8018make loops more efficient. A common example is the 68000 @samp{dbra} 8019instruction which performs a decrement of a register and a branch if the 8020result was greater than zero. Other machines, in particular digital 8021signal processors (DSPs), have special block repeat instructions to 8022provide low-overhead loop support. For example, the TI TMS320C3x/C4x 8023DSPs have a block repeat instruction that loads special registers to 8024mark the top and end of a loop and to count the number of loop 8025iterations. This avoids the need for fetching and executing a 8026@samp{dbra}-like instruction and avoids pipeline stalls associated with 8027the jump. 8028 8029GCC has two special named patterns to support low overhead looping. 8030They are @samp{doloop_begin} and @samp{doloop_end}. These are emitted 8031by the loop optimizer for certain well-behaved loops with a finite 8032number of loop iterations using information collected during strength 8033reduction. 8034 8035The @samp{doloop_end} pattern describes the actual looping instruction 8036(or the implicit looping operation) and the @samp{doloop_begin} pattern 8037is an optional companion pattern that can be used for initialization 8038needed for some low-overhead looping instructions. 8039 8040Note that some machines require the actual looping instruction to be 8041emitted at the top of the loop (e.g., the TMS320C3x/C4x DSPs). Emitting 8042the true RTL for a looping instruction at the top of the loop can cause 8043problems with flow analysis. So instead, a dummy @code{doloop} insn is 8044emitted at the end of the loop. The machine dependent reorg pass checks 8045for the presence of this @code{doloop} insn and then searches back to 8046the top of the loop, where it inserts the true looping insn (provided 8047there are no instructions in the loop which would cause problems). Any 8048additional labels can be emitted at this point. In addition, if the 8049desired special iteration counter register was not allocated, this 8050machine dependent reorg pass could emit a traditional compare and jump 8051instruction pair. 8052 8053For the @samp{doloop_end} pattern, the loop optimizer allocates an 8054additional pseudo register as an iteration counter. This pseudo 8055register cannot be used within the loop (i.e., general induction 8056variables cannot be derived from it), however, in many cases the loop 8057induction variable may become redundant and removed by the flow pass. 8058 8059The @samp{doloop_end} pattern must have a specific structure to be 8060handled correctly by GCC. The example below is taken (slightly 8061simplified) from the PDP-11 target: 8062 8063@smallexample 8064@group 8065(define_expand "doloop_end" 8066 [(parallel [(set (pc) 8067 (if_then_else 8068 (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m") 8069 (const_int 1)) 8070 (label_ref (match_operand 1 "" "")) 8071 (pc))) 8072 (set (match_dup 0) 8073 (plus:HI (match_dup 0) 8074 (const_int -1)))])] 8075 "" 8076 "@{ 8077 if (GET_MODE (operands[0]) != HImode) 8078 FAIL; 8079 @}") 8080 8081(define_insn "doloop_end_insn" 8082 [(set (pc) 8083 (if_then_else 8084 (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m") 8085 (const_int 1)) 8086 (label_ref (match_operand 1 "" "")) 8087 (pc))) 8088 (set (match_dup 0) 8089 (plus:HI (match_dup 0) 8090 (const_int -1)))] 8091 "" 8092 8093 @{ 8094 if (which_alternative == 0) 8095 return "sob %0,%l1"; 8096 8097 /* emulate sob */ 8098 output_asm_insn ("dec %0", operands); 8099 return "bne %l1"; 8100 @}) 8101@end group 8102@end smallexample 8103 8104The first part of the pattern describes the branch condition. GCC 8105supports three cases for the way the target machine handles the loop 8106counter: 8107@itemize @bullet 8108@item Loop terminates when the loop register decrements to zero. This 8109is represented by a @code{ne} comparison of the register (its old value) 8110with constant 1 (as in the example above). 8111@item Loop terminates when the loop register decrements to @minus{}1. 8112This is represented by a @code{ne} comparison of the register with 8113constant zero. 8114@item Loop terminates when the loop register decrements to a negative 8115value. This is represented by a @code{ge} comparison of the register 8116with constant zero. For this case, GCC will attach a @code{REG_NONNEG} 8117note to the @code{doloop_end} insn if it can determine that the register 8118will be non-negative. 8119@end itemize 8120 8121Since the @code{doloop_end} insn is a jump insn that also has an output, 8122the reload pass does not handle the output operand. Therefore, the 8123constraint must allow for that operand to be in memory rather than a 8124register. In the example shown above, that is handled (in the 8125@code{doloop_end_insn} pattern) by using a loop instruction sequence 8126that can handle memory operands when the memory alternative appears. 8127 8128GCC does not check the mode of the loop register operand when generating 8129the @code{doloop_end} pattern. If the pattern is only valid for some 8130modes but not others, the pattern should be a @code{define_expand} 8131pattern that checks the operand mode in the preparation code, and issues 8132@code{FAIL} if an unsupported mode is found. The example above does 8133this, since the machine instruction to be used only exists for 8134@code{HImode}. 8135 8136If the @code{doloop_end} pattern is a @code{define_expand}, there must 8137also be a @code{define_insn} or @code{define_insn_and_split} matching 8138the generated pattern. Otherwise, the compiler will fail during loop 8139optimization. 8140 8141@end ifset 8142@ifset INTERNALS 8143@node Insn Canonicalizations 8144@section Canonicalization of Instructions 8145@cindex canonicalization of instructions 8146@cindex insn canonicalization 8147 8148There are often cases where multiple RTL expressions could represent an 8149operation performed by a single machine instruction. This situation is 8150most commonly encountered with logical, branch, and multiply-accumulate 8151instructions. In such cases, the compiler attempts to convert these 8152multiple RTL expressions into a single canonical form to reduce the 8153number of insn patterns required. 8154 8155In addition to algebraic simplifications, following canonicalizations 8156are performed: 8157 8158@itemize @bullet 8159@item 8160For commutative and comparison operators, a constant is always made the 8161second operand. If a machine only supports a constant as the second 8162operand, only patterns that match a constant in the second operand need 8163be supplied. 8164 8165@item 8166For associative operators, a sequence of operators will always chain 8167to the left; for instance, only the left operand of an integer @code{plus} 8168can itself be a @code{plus}. @code{and}, @code{ior}, @code{xor}, 8169@code{plus}, @code{mult}, @code{smin}, @code{smax}, @code{umin}, and 8170@code{umax} are associative when applied to integers, and sometimes to 8171floating-point. 8172 8173@item 8174@cindex @code{neg}, canonicalization of 8175@cindex @code{not}, canonicalization of 8176@cindex @code{mult}, canonicalization of 8177@cindex @code{plus}, canonicalization of 8178@cindex @code{minus}, canonicalization of 8179For these operators, if only one operand is a @code{neg}, @code{not}, 8180@code{mult}, @code{plus}, or @code{minus} expression, it will be the 8181first operand. 8182 8183@item 8184In combinations of @code{neg}, @code{mult}, @code{plus}, and 8185@code{minus}, the @code{neg} operations (if any) will be moved inside 8186the operations as far as possible. For instance, 8187@code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but 8188@code{(plus (mult (neg B) C) A)} is canonicalized as 8189@code{(minus A (mult B C))}. 8190 8191@cindex @code{compare}, canonicalization of 8192@item 8193For the @code{compare} operator, a constant is always the second operand 8194if the first argument is a condition code register or @code{(cc0)}. 8195 8196@item 8197For instructions that inherently set a condition code register, the 8198@code{compare} operator is always written as the first RTL expression of 8199the @code{parallel} instruction pattern. For example, 8200 8201@smallexample 8202(define_insn "" 8203 [(set (reg:CCZ FLAGS_REG) 8204 (compare:CCZ 8205 (plus:SI 8206 (match_operand:SI 1 "register_operand" "%r") 8207 (match_operand:SI 2 "register_operand" "r")) 8208 (const_int 0))) 8209 (set (match_operand:SI 0 "register_operand" "=r") 8210 (plus:SI (match_dup 1) (match_dup 2)))] 8211 "" 8212 "addl %0, %1, %2") 8213@end smallexample 8214 8215@item 8216An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or 8217@code{minus} is made the first operand under the same conditions as 8218above. 8219 8220@item 8221@code{(ltu (plus @var{a} @var{b}) @var{b})} is converted to 8222@code{(ltu (plus @var{a} @var{b}) @var{a})}. Likewise with @code{geu} instead 8223of @code{ltu}. 8224 8225@item 8226@code{(minus @var{x} (const_int @var{n}))} is converted to 8227@code{(plus @var{x} (const_int @var{-n}))}. 8228 8229@item 8230Within address computations (i.e., inside @code{mem}), a left shift is 8231converted into the appropriate multiplication by a power of two. 8232 8233@cindex @code{ior}, canonicalization of 8234@cindex @code{and}, canonicalization of 8235@cindex De Morgan's law 8236@item 8237De Morgan's Law is used to move bitwise negation inside a bitwise 8238logical-and or logical-or operation. If this results in only one 8239operand being a @code{not} expression, it will be the first one. 8240 8241A machine that has an instruction that performs a bitwise logical-and of one 8242operand with the bitwise negation of the other should specify the pattern 8243for that instruction as 8244 8245@smallexample 8246(define_insn "" 8247 [(set (match_operand:@var{m} 0 @dots{}) 8248 (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) 8249 (match_operand:@var{m} 2 @dots{})))] 8250 "@dots{}" 8251 "@dots{}") 8252@end smallexample 8253 8254@noindent 8255Similarly, a pattern for a ``NAND'' instruction should be written 8256 8257@smallexample 8258(define_insn "" 8259 [(set (match_operand:@var{m} 0 @dots{}) 8260 (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) 8261 (not:@var{m} (match_operand:@var{m} 2 @dots{}))))] 8262 "@dots{}" 8263 "@dots{}") 8264@end smallexample 8265 8266In both cases, it is not necessary to include patterns for the many 8267logically equivalent RTL expressions. 8268 8269@cindex @code{xor}, canonicalization of 8270@item 8271The only possible RTL expressions involving both bitwise exclusive-or 8272and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})} 8273and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}. 8274 8275@item 8276The sum of three items, one of which is a constant, will only appear in 8277the form 8278 8279@smallexample 8280(plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant}) 8281@end smallexample 8282 8283@cindex @code{zero_extract}, canonicalization of 8284@cindex @code{sign_extract}, canonicalization of 8285@item 8286Equality comparisons of a group of bits (usually a single bit) with zero 8287will be written using @code{zero_extract} rather than the equivalent 8288@code{and} or @code{sign_extract} operations. 8289 8290@cindex @code{mult}, canonicalization of 8291@item 8292@code{(sign_extend:@var{m1} (mult:@var{m2} (sign_extend:@var{m2} @var{x}) 8293(sign_extend:@var{m2} @var{y})))} is converted to @code{(mult:@var{m1} 8294(sign_extend:@var{m1} @var{x}) (sign_extend:@var{m1} @var{y}))}, and likewise 8295for @code{zero_extend}. 8296 8297@item 8298@code{(sign_extend:@var{m1} (mult:@var{m2} (ashiftrt:@var{m2} 8299@var{x} @var{s}) (sign_extend:@var{m2} @var{y})))} is converted 8300to @code{(mult:@var{m1} (sign_extend:@var{m1} (ashiftrt:@var{m2} 8301@var{x} @var{s})) (sign_extend:@var{m1} @var{y}))}, and likewise for 8302patterns using @code{zero_extend} and @code{lshiftrt}. If the second 8303operand of @code{mult} is also a shift, then that is extended also. 8304This transformation is only applied when it can be proven that the 8305original operation had sufficient precision to prevent overflow. 8306 8307@end itemize 8308 8309Further canonicalization rules are defined in the function 8310@code{commutative_operand_precedence} in @file{gcc/rtlanal.c}. 8311 8312@end ifset 8313@ifset INTERNALS 8314@node Expander Definitions 8315@section Defining RTL Sequences for Code Generation 8316@cindex expander definitions 8317@cindex code generation RTL sequences 8318@cindex defining RTL sequences for code generation 8319 8320On some target machines, some standard pattern names for RTL generation 8321cannot be handled with single insn, but a sequence of RTL insns can 8322represent them. For these target machines, you can write a 8323@code{define_expand} to specify how to generate the sequence of RTL@. 8324 8325@findex define_expand 8326A @code{define_expand} is an RTL expression that looks almost like a 8327@code{define_insn}; but, unlike the latter, a @code{define_expand} is used 8328only for RTL generation and it can produce more than one RTL insn. 8329 8330A @code{define_expand} RTX has four operands: 8331 8332@itemize @bullet 8333@item 8334The name. Each @code{define_expand} must have a name, since the only 8335use for it is to refer to it by name. 8336 8337@item 8338The RTL template. This is a vector of RTL expressions representing 8339a sequence of separate instructions. Unlike @code{define_insn}, there 8340is no implicit surrounding @code{PARALLEL}. 8341 8342@item 8343The condition, a string containing a C expression. This expression is 8344used to express how the availability of this pattern depends on 8345subclasses of target machine, selected by command-line options when GCC 8346is run. This is just like the condition of a @code{define_insn} that 8347has a standard name. Therefore, the condition (if present) may not 8348depend on the data in the insn being matched, but only the 8349target-machine-type flags. The compiler needs to test these conditions 8350during initialization in order to learn exactly which named instructions 8351are available in a particular run. 8352 8353@item 8354The preparation statements, a string containing zero or more C 8355statements which are to be executed before RTL code is generated from 8356the RTL template. 8357 8358Usually these statements prepare temporary registers for use as 8359internal operands in the RTL template, but they can also generate RTL 8360insns directly by calling routines such as @code{emit_insn}, etc. 8361Any such insns precede the ones that come from the RTL template. 8362 8363@item 8364Optionally, a vector containing the values of attributes. @xref{Insn 8365Attributes}. 8366@end itemize 8367 8368Every RTL insn emitted by a @code{define_expand} must match some 8369@code{define_insn} in the machine description. Otherwise, the compiler 8370will crash when trying to generate code for the insn or trying to optimize 8371it. 8372 8373The RTL template, in addition to controlling generation of RTL insns, 8374also describes the operands that need to be specified when this pattern 8375is used. In particular, it gives a predicate for each operand. 8376 8377A true operand, which needs to be specified in order to generate RTL from 8378the pattern, should be described with a @code{match_operand} in its first 8379occurrence in the RTL template. This enters information on the operand's 8380predicate into the tables that record such things. GCC uses the 8381information to preload the operand into a register if that is required for 8382valid RTL code. If the operand is referred to more than once, subsequent 8383references should use @code{match_dup}. 8384 8385The RTL template may also refer to internal ``operands'' which are 8386temporary registers or labels used only within the sequence made by the 8387@code{define_expand}. Internal operands are substituted into the RTL 8388template with @code{match_dup}, never with @code{match_operand}. The 8389values of the internal operands are not passed in as arguments by the 8390compiler when it requests use of this pattern. Instead, they are computed 8391within the pattern, in the preparation statements. These statements 8392compute the values and store them into the appropriate elements of 8393@code{operands} so that @code{match_dup} can find them. 8394 8395There are two special macros defined for use in the preparation statements: 8396@code{DONE} and @code{FAIL}. Use them with a following semicolon, 8397as a statement. 8398 8399@table @code 8400 8401@findex DONE 8402@item DONE 8403Use the @code{DONE} macro to end RTL generation for the pattern. The 8404only RTL insns resulting from the pattern on this occasion will be 8405those already emitted by explicit calls to @code{emit_insn} within the 8406preparation statements; the RTL template will not be generated. 8407 8408@findex FAIL 8409@item FAIL 8410Make the pattern fail on this occasion. When a pattern fails, it means 8411that the pattern was not truly available. The calling routines in the 8412compiler will try other strategies for code generation using other patterns. 8413 8414Failure is currently supported only for binary (addition, multiplication, 8415shifting, etc.) and bit-field (@code{extv}, @code{extzv}, and @code{insv}) 8416operations. 8417@end table 8418 8419If the preparation falls through (invokes neither @code{DONE} nor 8420@code{FAIL}), then the @code{define_expand} acts like a 8421@code{define_insn} in that the RTL template is used to generate the 8422insn. 8423 8424The RTL template is not used for matching, only for generating the 8425initial insn list. If the preparation statement always invokes 8426@code{DONE} or @code{FAIL}, the RTL template may be reduced to a simple 8427list of operands, such as this example: 8428 8429@smallexample 8430@group 8431(define_expand "addsi3" 8432 [(match_operand:SI 0 "register_operand" "") 8433 (match_operand:SI 1 "register_operand" "") 8434 (match_operand:SI 2 "register_operand" "")] 8435@end group 8436@group 8437 "" 8438 " 8439@{ 8440 handle_add (operands[0], operands[1], operands[2]); 8441 DONE; 8442@}") 8443@end group 8444@end smallexample 8445 8446Here is an example, the definition of left-shift for the SPUR chip: 8447 8448@smallexample 8449@group 8450(define_expand "ashlsi3" 8451 [(set (match_operand:SI 0 "register_operand" "") 8452 (ashift:SI 8453@end group 8454@group 8455 (match_operand:SI 1 "register_operand" "") 8456 (match_operand:SI 2 "nonmemory_operand" "")))] 8457 "" 8458 " 8459@end group 8460@end smallexample 8461 8462@smallexample 8463@group 8464@{ 8465 if (GET_CODE (operands[2]) != CONST_INT 8466 || (unsigned) INTVAL (operands[2]) > 3) 8467 FAIL; 8468@}") 8469@end group 8470@end smallexample 8471 8472@noindent 8473This example uses @code{define_expand} so that it can generate an RTL insn 8474for shifting when the shift-count is in the supported range of 0 to 3 but 8475fail in other cases where machine insns aren't available. When it fails, 8476the compiler tries another strategy using different patterns (such as, a 8477library call). 8478 8479If the compiler were able to handle nontrivial condition-strings in 8480patterns with names, then it would be possible to use a 8481@code{define_insn} in that case. Here is another case (zero-extension 8482on the 68000) which makes more use of the power of @code{define_expand}: 8483 8484@smallexample 8485(define_expand "zero_extendhisi2" 8486 [(set (match_operand:SI 0 "general_operand" "") 8487 (const_int 0)) 8488 (set (strict_low_part 8489 (subreg:HI 8490 (match_dup 0) 8491 0)) 8492 (match_operand:HI 1 "general_operand" ""))] 8493 "" 8494 "operands[1] = make_safe_from (operands[1], operands[0]);") 8495@end smallexample 8496 8497@noindent 8498@findex make_safe_from 8499Here two RTL insns are generated, one to clear the entire output operand 8500and the other to copy the input operand into its low half. This sequence 8501is incorrect if the input operand refers to [the old value of] the output 8502operand, so the preparation statement makes sure this isn't so. The 8503function @code{make_safe_from} copies the @code{operands[1]} into a 8504temporary register if it refers to @code{operands[0]}. It does this 8505by emitting another RTL insn. 8506 8507Finally, a third example shows the use of an internal operand. 8508Zero-extension on the SPUR chip is done by @code{and}-ing the result 8509against a halfword mask. But this mask cannot be represented by a 8510@code{const_int} because the constant value is too large to be legitimate 8511on this machine. So it must be copied into a register with 8512@code{force_reg} and then the register used in the @code{and}. 8513 8514@smallexample 8515(define_expand "zero_extendhisi2" 8516 [(set (match_operand:SI 0 "register_operand" "") 8517 (and:SI (subreg:SI 8518 (match_operand:HI 1 "register_operand" "") 8519 0) 8520 (match_dup 2)))] 8521 "" 8522 "operands[2] 8523 = force_reg (SImode, GEN_INT (65535)); ") 8524@end smallexample 8525 8526@emph{Note:} If the @code{define_expand} is used to serve a 8527standard binary or unary arithmetic operation or a bit-field operation, 8528then the last insn it generates must not be a @code{code_label}, 8529@code{barrier} or @code{note}. It must be an @code{insn}, 8530@code{jump_insn} or @code{call_insn}. If you don't need a real insn 8531at the end, emit an insn to copy the result of the operation into 8532itself. Such an insn will generate no code, but it can avoid problems 8533in the compiler. 8534 8535@end ifset 8536@ifset INTERNALS 8537@node Insn Splitting 8538@section Defining How to Split Instructions 8539@cindex insn splitting 8540@cindex instruction splitting 8541@cindex splitting instructions 8542 8543There are two cases where you should specify how to split a pattern 8544into multiple insns. On machines that have instructions requiring 8545delay slots (@pxref{Delay Slots}) or that have instructions whose 8546output is not available for multiple cycles (@pxref{Processor pipeline 8547description}), the compiler phases that optimize these cases need to 8548be able to move insns into one-instruction delay slots. However, some 8549insns may generate more than one machine instruction. These insns 8550cannot be placed into a delay slot. 8551 8552Often you can rewrite the single insn as a list of individual insns, 8553each corresponding to one machine instruction. The disadvantage of 8554doing so is that it will cause the compilation to be slower and require 8555more space. If the resulting insns are too complex, it may also 8556suppress some optimizations. The compiler splits the insn if there is a 8557reason to believe that it might improve instruction or delay slot 8558scheduling. 8559 8560The insn combiner phase also splits putative insns. If three insns are 8561merged into one insn with a complex expression that cannot be matched by 8562some @code{define_insn} pattern, the combiner phase attempts to split 8563the complex pattern into two insns that are recognized. Usually it can 8564break the complex pattern into two patterns by splitting out some 8565subexpression. However, in some other cases, such as performing an 8566addition of a large constant in two insns on a RISC machine, the way to 8567split the addition into two insns is machine-dependent. 8568 8569@findex define_split 8570The @code{define_split} definition tells the compiler how to split a 8571complex insn into several simpler insns. It looks like this: 8572 8573@smallexample 8574(define_split 8575 [@var{insn-pattern}] 8576 "@var{condition}" 8577 [@var{new-insn-pattern-1} 8578 @var{new-insn-pattern-2} 8579 @dots{}] 8580 "@var{preparation-statements}") 8581@end smallexample 8582 8583@var{insn-pattern} is a pattern that needs to be split and 8584@var{condition} is the final condition to be tested, as in a 8585@code{define_insn}. When an insn matching @var{insn-pattern} and 8586satisfying @var{condition} is found, it is replaced in the insn list 8587with the insns given by @var{new-insn-pattern-1}, 8588@var{new-insn-pattern-2}, etc. 8589 8590The @var{preparation-statements} are similar to those statements that 8591are specified for @code{define_expand} (@pxref{Expander Definitions}) 8592and are executed before the new RTL is generated to prepare for the 8593generated code or emit some insns whose pattern is not fixed. Unlike 8594those in @code{define_expand}, however, these statements must not 8595generate any new pseudo-registers. Once reload has completed, they also 8596must not allocate any space in the stack frame. 8597 8598There are two special macros defined for use in the preparation statements: 8599@code{DONE} and @code{FAIL}. Use them with a following semicolon, 8600as a statement. 8601 8602@table @code 8603 8604@findex DONE 8605@item DONE 8606Use the @code{DONE} macro to end RTL generation for the splitter. The 8607only RTL insns generated as replacement for the matched input insn will 8608be those already emitted by explicit calls to @code{emit_insn} within 8609the preparation statements; the replacement pattern is not used. 8610 8611@findex FAIL 8612@item FAIL 8613Make the @code{define_split} fail on this occasion. When a @code{define_split} 8614fails, it means that the splitter was not truly available for the inputs 8615it was given, and the input insn will not be split. 8616@end table 8617 8618If the preparation falls through (invokes neither @code{DONE} nor 8619@code{FAIL}), then the @code{define_split} uses the replacement 8620template. 8621 8622Patterns are matched against @var{insn-pattern} in two different 8623circumstances. If an insn needs to be split for delay slot scheduling 8624or insn scheduling, the insn is already known to be valid, which means 8625that it must have been matched by some @code{define_insn} and, if 8626@code{reload_completed} is nonzero, is known to satisfy the constraints 8627of that @code{define_insn}. In that case, the new insn patterns must 8628also be insns that are matched by some @code{define_insn} and, if 8629@code{reload_completed} is nonzero, must also satisfy the constraints 8630of those definitions. 8631 8632As an example of this usage of @code{define_split}, consider the following 8633example from @file{a29k.md}, which splits a @code{sign_extend} from 8634@code{HImode} to @code{SImode} into a pair of shift insns: 8635 8636@smallexample 8637(define_split 8638 [(set (match_operand:SI 0 "gen_reg_operand" "") 8639 (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))] 8640 "" 8641 [(set (match_dup 0) 8642 (ashift:SI (match_dup 1) 8643 (const_int 16))) 8644 (set (match_dup 0) 8645 (ashiftrt:SI (match_dup 0) 8646 (const_int 16)))] 8647 " 8648@{ operands[1] = gen_lowpart (SImode, operands[1]); @}") 8649@end smallexample 8650 8651When the combiner phase tries to split an insn pattern, it is always the 8652case that the pattern is @emph{not} matched by any @code{define_insn}. 8653The combiner pass first tries to split a single @code{set} expression 8654and then the same @code{set} expression inside a @code{parallel}, but 8655followed by a @code{clobber} of a pseudo-reg to use as a scratch 8656register. In these cases, the combiner expects exactly one or two new insn 8657patterns to be generated. It will verify that these patterns match some 8658@code{define_insn} definitions, so you need not do this test in the 8659@code{define_split} (of course, there is no point in writing a 8660@code{define_split} that will never produce insns that match). 8661 8662Here is an example of this use of @code{define_split}, taken from 8663@file{rs6000.md}: 8664 8665@smallexample 8666(define_split 8667 [(set (match_operand:SI 0 "gen_reg_operand" "") 8668 (plus:SI (match_operand:SI 1 "gen_reg_operand" "") 8669 (match_operand:SI 2 "non_add_cint_operand" "")))] 8670 "" 8671 [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3))) 8672 (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))] 8673" 8674@{ 8675 int low = INTVAL (operands[2]) & 0xffff; 8676 int high = (unsigned) INTVAL (operands[2]) >> 16; 8677 8678 if (low & 0x8000) 8679 high++, low |= 0xffff0000; 8680 8681 operands[3] = GEN_INT (high << 16); 8682 operands[4] = GEN_INT (low); 8683@}") 8684@end smallexample 8685 8686Here the predicate @code{non_add_cint_operand} matches any 8687@code{const_int} that is @emph{not} a valid operand of a single add 8688insn. The add with the smaller displacement is written so that it 8689can be substituted into the address of a subsequent operation. 8690 8691An example that uses a scratch register, from the same file, generates 8692an equality comparison of a register and a large constant: 8693 8694@smallexample 8695(define_split 8696 [(set (match_operand:CC 0 "cc_reg_operand" "") 8697 (compare:CC (match_operand:SI 1 "gen_reg_operand" "") 8698 (match_operand:SI 2 "non_short_cint_operand" ""))) 8699 (clobber (match_operand:SI 3 "gen_reg_operand" ""))] 8700 "find_single_use (operands[0], insn, 0) 8701 && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ 8702 || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)" 8703 [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4))) 8704 (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))] 8705 " 8706@{ 8707 /* @r{Get the constant we are comparing against, C, and see what it 8708 looks like sign-extended to 16 bits. Then see what constant 8709 could be XOR'ed with C to get the sign-extended value.} */ 8710 8711 int c = INTVAL (operands[2]); 8712 int sextc = (c << 16) >> 16; 8713 int xorv = c ^ sextc; 8714 8715 operands[4] = GEN_INT (xorv); 8716 operands[5] = GEN_INT (sextc); 8717@}") 8718@end smallexample 8719 8720To avoid confusion, don't write a single @code{define_split} that 8721accepts some insns that match some @code{define_insn} as well as some 8722insns that don't. Instead, write two separate @code{define_split} 8723definitions, one for the insns that are valid and one for the insns that 8724are not valid. 8725 8726The splitter is allowed to split jump instructions into sequence of 8727jumps or create new jumps in while splitting non-jump instructions. As 8728the control flow graph and branch prediction information needs to be updated, 8729several restriction apply. 8730 8731Splitting of jump instruction into sequence that over by another jump 8732instruction is always valid, as compiler expect identical behavior of new 8733jump. When new sequence contains multiple jump instructions or new labels, 8734more assistance is needed. Splitter is required to create only unconditional 8735jumps, or simple conditional jump instructions. Additionally it must attach a 8736@code{REG_BR_PROB} note to each conditional jump. A global variable 8737@code{split_branch_probability} holds the probability of the original branch in case 8738it was a simple conditional jump, @minus{}1 otherwise. To simplify 8739recomputing of edge frequencies, the new sequence is required to have only 8740forward jumps to the newly created labels. 8741 8742@findex define_insn_and_split 8743For the common case where the pattern of a define_split exactly matches the 8744pattern of a define_insn, use @code{define_insn_and_split}. It looks like 8745this: 8746 8747@smallexample 8748(define_insn_and_split 8749 [@var{insn-pattern}] 8750 "@var{condition}" 8751 "@var{output-template}" 8752 "@var{split-condition}" 8753 [@var{new-insn-pattern-1} 8754 @var{new-insn-pattern-2} 8755 @dots{}] 8756 "@var{preparation-statements}" 8757 [@var{insn-attributes}]) 8758 8759@end smallexample 8760 8761@var{insn-pattern}, @var{condition}, @var{output-template}, and 8762@var{insn-attributes} are used as in @code{define_insn}. The 8763@var{new-insn-pattern} vector and the @var{preparation-statements} are used as 8764in a @code{define_split}. The @var{split-condition} is also used as in 8765@code{define_split}, with the additional behavior that if the condition starts 8766with @samp{&&}, the condition used for the split will be the constructed as a 8767logical ``and'' of the split condition with the insn condition. For example, 8768from i386.md: 8769 8770@smallexample 8771(define_insn_and_split "zero_extendhisi2_and" 8772 [(set (match_operand:SI 0 "register_operand" "=r") 8773 (zero_extend:SI (match_operand:HI 1 "register_operand" "0"))) 8774 (clobber (reg:CC 17))] 8775 "TARGET_ZERO_EXTEND_WITH_AND && !optimize_size" 8776 "#" 8777 "&& reload_completed" 8778 [(parallel [(set (match_dup 0) 8779 (and:SI (match_dup 0) (const_int 65535))) 8780 (clobber (reg:CC 17))])] 8781 "" 8782 [(set_attr "type" "alu1")]) 8783 8784@end smallexample 8785 8786In this case, the actual split condition will be 8787@samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}. 8788 8789The @code{define_insn_and_split} construction provides exactly the same 8790functionality as two separate @code{define_insn} and @code{define_split} 8791patterns. It exists for compactness, and as a maintenance tool to prevent 8792having to ensure the two patterns' templates match. 8793 8794@findex define_insn_and_rewrite 8795It is sometimes useful to have a @code{define_insn_and_split} 8796that replaces specific operands of an instruction but leaves the 8797rest of the instruction pattern unchanged. You can do this directly 8798with a @code{define_insn_and_split}, but it requires a 8799@var{new-insn-pattern-1} that repeats most of the original @var{insn-pattern}. 8800There is also the complication that an implicit @code{parallel} in 8801@var{insn-pattern} must become an explicit @code{parallel} in 8802@var{new-insn-pattern-1}, which is easy to overlook. 8803A simpler alternative is to use @code{define_insn_and_rewrite}, which 8804is a form of @code{define_insn_and_split} that automatically generates 8805@var{new-insn-pattern-1} by replacing each @code{match_operand} 8806in @var{insn-pattern} with a corresponding @code{match_dup}, and each 8807@code{match_operator} in the pattern with a corresponding @code{match_op_dup}. 8808The arguments are otherwise identical to @code{define_insn_and_split}: 8809 8810@smallexample 8811(define_insn_and_rewrite 8812 [@var{insn-pattern}] 8813 "@var{condition}" 8814 "@var{output-template}" 8815 "@var{split-condition}" 8816 "@var{preparation-statements}" 8817 [@var{insn-attributes}]) 8818@end smallexample 8819 8820The @code{match_dup}s and @code{match_op_dup}s in the new 8821instruction pattern use any new operand values that the 8822@var{preparation-statements} store in the @code{operands} array, 8823as for a normal @code{define_insn_and_split}. @var{preparation-statements} 8824can also emit additional instructions before the new instruction. 8825They can even emit an entirely different sequence of instructions and 8826use @code{DONE} to avoid emitting a new form of the original 8827instruction. 8828 8829The split in a @code{define_insn_and_rewrite} is only intended 8830to apply to existing instructions that match @var{insn-pattern}. 8831@var{split-condition} must therefore start with @code{&&}, 8832so that the split condition applies on top of @var{condition}. 8833 8834Here is an example from the AArch64 SVE port, in which operand 1 is 8835known to be equivalent to an all-true constant and isn't used by the 8836output template: 8837 8838@smallexample 8839(define_insn_and_rewrite "*while_ult<GPI:mode><PRED_ALL:mode>_cc" 8840 [(set (reg:CC CC_REGNUM) 8841 (compare:CC 8842 (unspec:SI [(match_operand:PRED_ALL 1) 8843 (unspec:PRED_ALL 8844 [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ") 8845 (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")] 8846 UNSPEC_WHILE_LO)] 8847 UNSPEC_PTEST_PTRUE) 8848 (const_int 0))) 8849 (set (match_operand:PRED_ALL 0 "register_operand" "=Upa") 8850 (unspec:PRED_ALL [(match_dup 2) 8851 (match_dup 3)] 8852 UNSPEC_WHILE_LO))] 8853 "TARGET_SVE" 8854 "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3" 8855 ;; Force the compiler to drop the unused predicate operand, so that we 8856 ;; don't have an unnecessary PTRUE. 8857 "&& !CONSTANT_P (operands[1])" 8858 @{ 8859 operands[1] = CONSTM1_RTX (<MODE>mode); 8860 @} 8861) 8862@end smallexample 8863 8864The splitter in this case simply replaces operand 1 with the constant 8865value that it is known to have. The equivalent @code{define_insn_and_split} 8866would be: 8867 8868@smallexample 8869(define_insn_and_split "*while_ult<GPI:mode><PRED_ALL:mode>_cc" 8870 [(set (reg:CC CC_REGNUM) 8871 (compare:CC 8872 (unspec:SI [(match_operand:PRED_ALL 1) 8873 (unspec:PRED_ALL 8874 [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ") 8875 (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")] 8876 UNSPEC_WHILE_LO)] 8877 UNSPEC_PTEST_PTRUE) 8878 (const_int 0))) 8879 (set (match_operand:PRED_ALL 0 "register_operand" "=Upa") 8880 (unspec:PRED_ALL [(match_dup 2) 8881 (match_dup 3)] 8882 UNSPEC_WHILE_LO))] 8883 "TARGET_SVE" 8884 "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3" 8885 ;; Force the compiler to drop the unused predicate operand, so that we 8886 ;; don't have an unnecessary PTRUE. 8887 "&& !CONSTANT_P (operands[1])" 8888 [(parallel 8889 [(set (reg:CC CC_REGNUM) 8890 (compare:CC 8891 (unspec:SI [(match_dup 1) 8892 (unspec:PRED_ALL [(match_dup 2) 8893 (match_dup 3)] 8894 UNSPEC_WHILE_LO)] 8895 UNSPEC_PTEST_PTRUE) 8896 (const_int 0))) 8897 (set (match_dup 0) 8898 (unspec:PRED_ALL [(match_dup 2) 8899 (match_dup 3)] 8900 UNSPEC_WHILE_LO))])] 8901 @{ 8902 operands[1] = CONSTM1_RTX (<MODE>mode); 8903 @} 8904) 8905@end smallexample 8906 8907@end ifset 8908@ifset INTERNALS 8909@node Including Patterns 8910@section Including Patterns in Machine Descriptions. 8911@cindex insn includes 8912 8913@findex include 8914The @code{include} pattern tells the compiler tools where to 8915look for patterns that are in files other than in the file 8916@file{.md}. This is used only at build time and there is no preprocessing allowed. 8917 8918It looks like: 8919 8920@smallexample 8921 8922(include 8923 @var{pathname}) 8924@end smallexample 8925 8926For example: 8927 8928@smallexample 8929 8930(include "filestuff") 8931 8932@end smallexample 8933 8934Where @var{pathname} is a string that specifies the location of the file, 8935specifies the include file to be in @file{gcc/config/target/filestuff}. The 8936directory @file{gcc/config/target} is regarded as the default directory. 8937 8938 8939Machine descriptions may be split up into smaller more manageable subsections 8940and placed into subdirectories. 8941 8942By specifying: 8943 8944@smallexample 8945 8946(include "BOGUS/filestuff") 8947 8948@end smallexample 8949 8950the include file is specified to be in @file{gcc/config/@var{target}/BOGUS/filestuff}. 8951 8952Specifying an absolute path for the include file such as; 8953@smallexample 8954 8955(include "/u2/BOGUS/filestuff") 8956 8957@end smallexample 8958is permitted but is not encouraged. 8959 8960@subsection RTL Generation Tool Options for Directory Search 8961@cindex directory options .md 8962@cindex options, directory search 8963@cindex search options 8964 8965The @option{-I@var{dir}} option specifies directories to search for machine descriptions. 8966For example: 8967 8968@smallexample 8969 8970genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md 8971 8972@end smallexample 8973 8974 8975Add the directory @var{dir} to the head of the list of directories to be 8976searched for header files. This can be used to override a system machine definition 8977file, substituting your own version, since these directories are 8978searched before the default machine description file directories. If you use more than 8979one @option{-I} option, the directories are scanned in left-to-right 8980order; the standard default directory come after. 8981 8982 8983@end ifset 8984@ifset INTERNALS 8985@node Peephole Definitions 8986@section Machine-Specific Peephole Optimizers 8987@cindex peephole optimizer definitions 8988@cindex defining peephole optimizers 8989 8990In addition to instruction patterns the @file{md} file may contain 8991definitions of machine-specific peephole optimizations. 8992 8993The combiner does not notice certain peephole optimizations when the data 8994flow in the program does not suggest that it should try them. For example, 8995sometimes two consecutive insns related in purpose can be combined even 8996though the second one does not appear to use a register computed in the 8997first one. A machine-specific peephole optimizer can detect such 8998opportunities. 8999 9000There are two forms of peephole definitions that may be used. The 9001original @code{define_peephole} is run at assembly output time to 9002match insns and substitute assembly text. Use of @code{define_peephole} 9003is deprecated. 9004 9005A newer @code{define_peephole2} matches insns and substitutes new 9006insns. The @code{peephole2} pass is run after register allocation 9007but before scheduling, which may result in much better code for 9008targets that do scheduling. 9009 9010@menu 9011* define_peephole:: RTL to Text Peephole Optimizers 9012* define_peephole2:: RTL to RTL Peephole Optimizers 9013@end menu 9014 9015@end ifset 9016@ifset INTERNALS 9017@node define_peephole 9018@subsection RTL to Text Peephole Optimizers 9019@findex define_peephole 9020 9021@need 1000 9022A definition looks like this: 9023 9024@smallexample 9025(define_peephole 9026 [@var{insn-pattern-1} 9027 @var{insn-pattern-2} 9028 @dots{}] 9029 "@var{condition}" 9030 "@var{template}" 9031 "@var{optional-insn-attributes}") 9032@end smallexample 9033 9034@noindent 9035The last string operand may be omitted if you are not using any 9036machine-specific information in this machine description. If present, 9037it must obey the same rules as in a @code{define_insn}. 9038 9039In this skeleton, @var{insn-pattern-1} and so on are patterns to match 9040consecutive insns. The optimization applies to a sequence of insns when 9041@var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches 9042the next, and so on. 9043 9044Each of the insns matched by a peephole must also match a 9045@code{define_insn}. Peepholes are checked only at the last stage just 9046before code generation, and only optionally. Therefore, any insn which 9047would match a peephole but no @code{define_insn} will cause a crash in code 9048generation in an unoptimized compilation, or at various optimization 9049stages. 9050 9051The operands of the insns are matched with @code{match_operands}, 9052@code{match_operator}, and @code{match_dup}, as usual. What is not 9053usual is that the operand numbers apply to all the insn patterns in the 9054definition. So, you can check for identical operands in two insns by 9055using @code{match_operand} in one insn and @code{match_dup} in the 9056other. 9057 9058The operand constraints used in @code{match_operand} patterns do not have 9059any direct effect on the applicability of the peephole, but they will 9060be validated afterward, so make sure your constraints are general enough 9061to apply whenever the peephole matches. If the peephole matches 9062but the constraints are not satisfied, the compiler will crash. 9063 9064It is safe to omit constraints in all the operands of the peephole; or 9065you can write constraints which serve as a double-check on the criteria 9066previously tested. 9067 9068Once a sequence of insns matches the patterns, the @var{condition} is 9069checked. This is a C expression which makes the final decision whether to 9070perform the optimization (we do so if the expression is nonzero). If 9071@var{condition} is omitted (in other words, the string is empty) then the 9072optimization is applied to every sequence of insns that matches the 9073patterns. 9074 9075The defined peephole optimizations are applied after register allocation 9076is complete. Therefore, the peephole definition can check which 9077operands have ended up in which kinds of registers, just by looking at 9078the operands. 9079 9080@findex prev_active_insn 9081The way to refer to the operands in @var{condition} is to write 9082@code{operands[@var{i}]} for operand number @var{i} (as matched by 9083@code{(match_operand @var{i} @dots{})}). Use the variable @code{insn} 9084to refer to the last of the insns being matched; use 9085@code{prev_active_insn} to find the preceding insns. 9086 9087@findex dead_or_set_p 9088When optimizing computations with intermediate results, you can use 9089@var{condition} to match only when the intermediate results are not used 9090elsewhere. Use the C expression @code{dead_or_set_p (@var{insn}, 9091@var{op})}, where @var{insn} is the insn in which you expect the value 9092to be used for the last time (from the value of @code{insn}, together 9093with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate 9094value (from @code{operands[@var{i}]}). 9095 9096Applying the optimization means replacing the sequence of insns with one 9097new insn. The @var{template} controls ultimate output of assembler code 9098for this combined insn. It works exactly like the template of a 9099@code{define_insn}. Operand numbers in this template are the same ones 9100used in matching the original sequence of insns. 9101 9102The result of a defined peephole optimizer does not need to match any of 9103the insn patterns in the machine description; it does not even have an 9104opportunity to match them. The peephole optimizer definition itself serves 9105as the insn pattern to control how the insn is output. 9106 9107Defined peephole optimizers are run as assembler code is being output, 9108so the insns they produce are never combined or rearranged in any way. 9109 9110Here is an example, taken from the 68000 machine description: 9111 9112@smallexample 9113(define_peephole 9114 [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4))) 9115 (set (match_operand:DF 0 "register_operand" "=f") 9116 (match_operand:DF 1 "register_operand" "ad"))] 9117 "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])" 9118@{ 9119 rtx xoperands[2]; 9120 xoperands[1] = gen_rtx_REG (SImode, REGNO (operands[1]) + 1); 9121#ifdef MOTOROLA 9122 output_asm_insn ("move.l %1,(sp)", xoperands); 9123 output_asm_insn ("move.l %1,-(sp)", operands); 9124 return "fmove.d (sp)+,%0"; 9125#else 9126 output_asm_insn ("movel %1,sp@@", xoperands); 9127 output_asm_insn ("movel %1,sp@@-", operands); 9128 return "fmoved sp@@+,%0"; 9129#endif 9130@}) 9131@end smallexample 9132 9133@need 1000 9134The effect of this optimization is to change 9135 9136@smallexample 9137@group 9138jbsr _foobar 9139addql #4,sp 9140movel d1,sp@@- 9141movel d0,sp@@- 9142fmoved sp@@+,fp0 9143@end group 9144@end smallexample 9145 9146@noindent 9147into 9148 9149@smallexample 9150@group 9151jbsr _foobar 9152movel d1,sp@@ 9153movel d0,sp@@- 9154fmoved sp@@+,fp0 9155@end group 9156@end smallexample 9157 9158@ignore 9159@findex CC_REVERSED 9160If a peephole matches a sequence including one or more jump insns, you must 9161take account of the flags such as @code{CC_REVERSED} which specify that the 9162condition codes are represented in an unusual manner. The compiler 9163automatically alters any ordinary conditional jumps which occur in such 9164situations, but the compiler cannot alter jumps which have been replaced by 9165peephole optimizations. So it is up to you to alter the assembler code 9166that the peephole produces. Supply C code to write the assembler output, 9167and in this C code check the condition code status flags and change the 9168assembler code as appropriate. 9169@end ignore 9170 9171@var{insn-pattern-1} and so on look @emph{almost} like the second 9172operand of @code{define_insn}. There is one important difference: the 9173second operand of @code{define_insn} consists of one or more RTX's 9174enclosed in square brackets. Usually, there is only one: then the same 9175action can be written as an element of a @code{define_peephole}. But 9176when there are multiple actions in a @code{define_insn}, they are 9177implicitly enclosed in a @code{parallel}. Then you must explicitly 9178write the @code{parallel}, and the square brackets within it, in the 9179@code{define_peephole}. Thus, if an insn pattern looks like this, 9180 9181@smallexample 9182(define_insn "divmodsi4" 9183 [(set (match_operand:SI 0 "general_operand" "=d") 9184 (div:SI (match_operand:SI 1 "general_operand" "0") 9185 (match_operand:SI 2 "general_operand" "dmsK"))) 9186 (set (match_operand:SI 3 "general_operand" "=d") 9187 (mod:SI (match_dup 1) (match_dup 2)))] 9188 "TARGET_68020" 9189 "divsl%.l %2,%3:%0") 9190@end smallexample 9191 9192@noindent 9193then the way to mention this insn in a peephole is as follows: 9194 9195@smallexample 9196(define_peephole 9197 [@dots{} 9198 (parallel 9199 [(set (match_operand:SI 0 "general_operand" "=d") 9200 (div:SI (match_operand:SI 1 "general_operand" "0") 9201 (match_operand:SI 2 "general_operand" "dmsK"))) 9202 (set (match_operand:SI 3 "general_operand" "=d") 9203 (mod:SI (match_dup 1) (match_dup 2)))]) 9204 @dots{}] 9205 @dots{}) 9206@end smallexample 9207 9208@end ifset 9209@ifset INTERNALS 9210@node define_peephole2 9211@subsection RTL to RTL Peephole Optimizers 9212@findex define_peephole2 9213 9214The @code{define_peephole2} definition tells the compiler how to 9215substitute one sequence of instructions for another sequence, 9216what additional scratch registers may be needed and what their 9217lifetimes must be. 9218 9219@smallexample 9220(define_peephole2 9221 [@var{insn-pattern-1} 9222 @var{insn-pattern-2} 9223 @dots{}] 9224 "@var{condition}" 9225 [@var{new-insn-pattern-1} 9226 @var{new-insn-pattern-2} 9227 @dots{}] 9228 "@var{preparation-statements}") 9229@end smallexample 9230 9231The definition is almost identical to @code{define_split} 9232(@pxref{Insn Splitting}) except that the pattern to match is not a 9233single instruction, but a sequence of instructions. 9234 9235It is possible to request additional scratch registers for use in the 9236output template. If appropriate registers are not free, the pattern 9237will simply not match. 9238 9239@findex match_scratch 9240@findex match_dup 9241Scratch registers are requested with a @code{match_scratch} pattern at 9242the top level of the input pattern. The allocated register (initially) will 9243be dead at the point requested within the original sequence. If the scratch 9244is used at more than a single point, a @code{match_dup} pattern at the 9245top level of the input pattern marks the last position in the input sequence 9246at which the register must be available. 9247 9248Here is an example from the IA-32 machine description: 9249 9250@smallexample 9251(define_peephole2 9252 [(match_scratch:SI 2 "r") 9253 (parallel [(set (match_operand:SI 0 "register_operand" "") 9254 (match_operator:SI 3 "arith_or_logical_operator" 9255 [(match_dup 0) 9256 (match_operand:SI 1 "memory_operand" "")])) 9257 (clobber (reg:CC 17))])] 9258 "! optimize_size && ! TARGET_READ_MODIFY" 9259 [(set (match_dup 2) (match_dup 1)) 9260 (parallel [(set (match_dup 0) 9261 (match_op_dup 3 [(match_dup 0) (match_dup 2)])) 9262 (clobber (reg:CC 17))])] 9263 "") 9264@end smallexample 9265 9266@noindent 9267This pattern tries to split a load from its use in the hopes that we'll be 9268able to schedule around the memory load latency. It allocates a single 9269@code{SImode} register of class @code{GENERAL_REGS} (@code{"r"}) that needs 9270to be live only at the point just before the arithmetic. 9271 9272A real example requiring extended scratch lifetimes is harder to come by, 9273so here's a silly made-up example: 9274 9275@smallexample 9276(define_peephole2 9277 [(match_scratch:SI 4 "r") 9278 (set (match_operand:SI 0 "" "") (match_operand:SI 1 "" "")) 9279 (set (match_operand:SI 2 "" "") (match_dup 1)) 9280 (match_dup 4) 9281 (set (match_operand:SI 3 "" "") (match_dup 1))] 9282 "/* @r{determine 1 does not overlap 0 and 2} */" 9283 [(set (match_dup 4) (match_dup 1)) 9284 (set (match_dup 0) (match_dup 4)) 9285 (set (match_dup 2) (match_dup 4)) 9286 (set (match_dup 3) (match_dup 4))] 9287 "") 9288@end smallexample 9289 9290There are two special macros defined for use in the preparation statements: 9291@code{DONE} and @code{FAIL}. Use them with a following semicolon, 9292as a statement. 9293 9294@table @code 9295 9296@findex DONE 9297@item DONE 9298Use the @code{DONE} macro to end RTL generation for the peephole. The 9299only RTL insns generated as replacement for the matched input insn will 9300be those already emitted by explicit calls to @code{emit_insn} within 9301the preparation statements; the replacement pattern is not used. 9302 9303@findex FAIL 9304@item FAIL 9305Make the @code{define_peephole2} fail on this occasion. When a @code{define_peephole2} 9306fails, it means that the replacement was not truly available for the 9307particular inputs it was given. In that case, GCC may still apply a 9308later @code{define_peephole2} that also matches the given insn pattern. 9309(Note that this is different from @code{define_split}, where @code{FAIL} 9310prevents the input insn from being split at all.) 9311@end table 9312 9313If the preparation falls through (invokes neither @code{DONE} nor 9314@code{FAIL}), then the @code{define_peephole2} uses the replacement 9315template. 9316 9317@noindent 9318If we had not added the @code{(match_dup 4)} in the middle of the input 9319sequence, it might have been the case that the register we chose at the 9320beginning of the sequence is killed by the first or second @code{set}. 9321 9322@end ifset 9323@ifset INTERNALS 9324@node Insn Attributes 9325@section Instruction Attributes 9326@cindex insn attributes 9327@cindex instruction attributes 9328 9329In addition to describing the instruction supported by the target machine, 9330the @file{md} file also defines a group of @dfn{attributes} and a set of 9331values for each. Every generated insn is assigned a value for each attribute. 9332One possible attribute would be the effect that the insn has on the machine's 9333condition code. This attribute can then be used by @code{NOTICE_UPDATE_CC} 9334to track the condition codes. 9335 9336@menu 9337* Defining Attributes:: Specifying attributes and their values. 9338* Expressions:: Valid expressions for attribute values. 9339* Tagging Insns:: Assigning attribute values to insns. 9340* Attr Example:: An example of assigning attributes. 9341* Insn Lengths:: Computing the length of insns. 9342* Constant Attributes:: Defining attributes that are constant. 9343* Mnemonic Attribute:: Obtain the instruction mnemonic as attribute value. 9344* Delay Slots:: Defining delay slots required for a machine. 9345* Processor pipeline description:: Specifying information for insn scheduling. 9346@end menu 9347 9348@end ifset 9349@ifset INTERNALS 9350@node Defining Attributes 9351@subsection Defining Attributes and their Values 9352@cindex defining attributes and their values 9353@cindex attributes, defining 9354 9355@findex define_attr 9356The @code{define_attr} expression is used to define each attribute required 9357by the target machine. It looks like: 9358 9359@smallexample 9360(define_attr @var{name} @var{list-of-values} @var{default}) 9361@end smallexample 9362 9363@var{name} is a string specifying the name of the attribute being 9364defined. Some attributes are used in a special way by the rest of the 9365compiler. The @code{enabled} attribute can be used to conditionally 9366enable or disable insn alternatives (@pxref{Disable Insn 9367Alternatives}). The @code{predicable} attribute, together with a 9368suitable @code{define_cond_exec} (@pxref{Conditional Execution}), can 9369be used to automatically generate conditional variants of instruction 9370patterns. The @code{mnemonic} attribute can be used to check for the 9371instruction mnemonic (@pxref{Mnemonic Attribute}). The compiler 9372internally uses the names @code{ce_enabled} and @code{nonce_enabled}, 9373so they should not be used elsewhere as alternative names. 9374 9375@var{list-of-values} is either a string that specifies a comma-separated 9376list of values that can be assigned to the attribute, or a null string to 9377indicate that the attribute takes numeric values. 9378 9379@var{default} is an attribute expression that gives the value of this 9380attribute for insns that match patterns whose definition does not include 9381an explicit value for this attribute. @xref{Attr Example}, for more 9382information on the handling of defaults. @xref{Constant Attributes}, 9383for information on attributes that do not depend on any particular insn. 9384 9385@findex insn-attr.h 9386For each defined attribute, a number of definitions are written to the 9387@file{insn-attr.h} file. For cases where an explicit set of values is 9388specified for an attribute, the following are defined: 9389 9390@itemize @bullet 9391@item 9392A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}. 9393 9394@item 9395An enumerated class is defined for @samp{attr_@var{name}} with 9396elements of the form @samp{@var{upper-name}_@var{upper-value}} where 9397the attribute name and value are first converted to uppercase. 9398 9399@item 9400A function @samp{get_attr_@var{name}} is defined that is passed an insn and 9401returns the attribute value for that insn. 9402@end itemize 9403 9404For example, if the following is present in the @file{md} file: 9405 9406@smallexample 9407(define_attr "type" "branch,fp,load,store,arith" @dots{}) 9408@end smallexample 9409 9410@noindent 9411the following lines will be written to the file @file{insn-attr.h}. 9412 9413@smallexample 9414#define HAVE_ATTR_type 1 9415enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD, 9416 TYPE_STORE, TYPE_ARITH@}; 9417extern enum attr_type get_attr_type (); 9418@end smallexample 9419 9420If the attribute takes numeric values, no @code{enum} type will be 9421defined and the function to obtain the attribute's value will return 9422@code{int}. 9423 9424There are attributes which are tied to a specific meaning. These 9425attributes are not free to use for other purposes: 9426 9427@table @code 9428@item length 9429The @code{length} attribute is used to calculate the length of emitted 9430code chunks. This is especially important when verifying branch 9431distances. @xref{Insn Lengths}. 9432 9433@item enabled 9434The @code{enabled} attribute can be defined to prevent certain 9435alternatives of an insn definition from being used during code 9436generation. @xref{Disable Insn Alternatives}. 9437 9438@item mnemonic 9439The @code{mnemonic} attribute can be defined to implement instruction 9440specific checks in e.g.@: the pipeline description. 9441@xref{Mnemonic Attribute}. 9442@end table 9443 9444For each of these special attributes, the corresponding 9445@samp{HAVE_ATTR_@var{name}} @samp{#define} is also written when the 9446attribute is not defined; in that case, it is defined as @samp{0}. 9447 9448@findex define_enum_attr 9449@anchor{define_enum_attr} 9450Another way of defining an attribute is to use: 9451 9452@smallexample 9453(define_enum_attr "@var{attr}" "@var{enum}" @var{default}) 9454@end smallexample 9455 9456This works in just the same way as @code{define_attr}, except that 9457the list of values is taken from a separate enumeration called 9458@var{enum} (@pxref{define_enum}). This form allows you to use 9459the same list of values for several attributes without having to 9460repeat the list each time. For example: 9461 9462@smallexample 9463(define_enum "processor" [ 9464 model_a 9465 model_b 9466 @dots{} 9467]) 9468(define_enum_attr "arch" "processor" 9469 (const (symbol_ref "target_arch"))) 9470(define_enum_attr "tune" "processor" 9471 (const (symbol_ref "target_tune"))) 9472@end smallexample 9473 9474defines the same attributes as: 9475 9476@smallexample 9477(define_attr "arch" "model_a,model_b,@dots{}" 9478 (const (symbol_ref "target_arch"))) 9479(define_attr "tune" "model_a,model_b,@dots{}" 9480 (const (symbol_ref "target_tune"))) 9481@end smallexample 9482 9483but without duplicating the processor list. The second example defines two 9484separate C enums (@code{attr_arch} and @code{attr_tune}) whereas the first 9485defines a single C enum (@code{processor}). 9486@end ifset 9487@ifset INTERNALS 9488@node Expressions 9489@subsection Attribute Expressions 9490@cindex attribute expressions 9491 9492RTL expressions used to define attributes use the codes described above 9493plus a few specific to attribute definitions, to be discussed below. 9494Attribute value expressions must have one of the following forms: 9495 9496@table @code 9497@cindex @code{const_int} and attributes 9498@item (const_int @var{i}) 9499The integer @var{i} specifies the value of a numeric attribute. @var{i} 9500must be non-negative. 9501 9502The value of a numeric attribute can be specified either with a 9503@code{const_int}, or as an integer represented as a string in 9504@code{const_string}, @code{eq_attr} (see below), @code{attr}, 9505@code{symbol_ref}, simple arithmetic expressions, and @code{set_attr} 9506overrides on specific instructions (@pxref{Tagging Insns}). 9507 9508@cindex @code{const_string} and attributes 9509@item (const_string @var{value}) 9510The string @var{value} specifies a constant attribute value. 9511If @var{value} is specified as @samp{"*"}, it means that the default value of 9512the attribute is to be used for the insn containing this expression. 9513@samp{"*"} obviously cannot be used in the @var{default} expression 9514of a @code{define_attr}. 9515 9516If the attribute whose value is being specified is numeric, @var{value} 9517must be a string containing a non-negative integer (normally 9518@code{const_int} would be used in this case). Otherwise, it must 9519contain one of the valid values for the attribute. 9520 9521@cindex @code{if_then_else} and attributes 9522@item (if_then_else @var{test} @var{true-value} @var{false-value}) 9523@var{test} specifies an attribute test, whose format is defined below. 9524The value of this expression is @var{true-value} if @var{test} is true, 9525otherwise it is @var{false-value}. 9526 9527@cindex @code{cond} and attributes 9528@item (cond [@var{test1} @var{value1} @dots{}] @var{default}) 9529The first operand of this expression is a vector containing an even 9530number of expressions and consisting of pairs of @var{test} and @var{value} 9531expressions. The value of the @code{cond} expression is that of the 9532@var{value} corresponding to the first true @var{test} expression. If 9533none of the @var{test} expressions are true, the value of the @code{cond} 9534expression is that of the @var{default} expression. 9535@end table 9536 9537@var{test} expressions can have one of the following forms: 9538 9539@table @code 9540@cindex @code{const_int} and attribute tests 9541@item (const_int @var{i}) 9542This test is true if @var{i} is nonzero and false otherwise. 9543 9544@cindex @code{not} and attributes 9545@cindex @code{ior} and attributes 9546@cindex @code{and} and attributes 9547@item (not @var{test}) 9548@itemx (ior @var{test1} @var{test2}) 9549@itemx (and @var{test1} @var{test2}) 9550These tests are true if the indicated logical function is true. 9551 9552@cindex @code{match_operand} and attributes 9553@item (match_operand:@var{m} @var{n} @var{pred} @var{constraints}) 9554This test is true if operand @var{n} of the insn whose attribute value 9555is being determined has mode @var{m} (this part of the test is ignored 9556if @var{m} is @code{VOIDmode}) and the function specified by the string 9557@var{pred} returns a nonzero value when passed operand @var{n} and mode 9558@var{m} (this part of the test is ignored if @var{pred} is the null 9559string). 9560 9561The @var{constraints} operand is ignored and should be the null string. 9562 9563@cindex @code{match_test} and attributes 9564@item (match_test @var{c-expr}) 9565The test is true if C expression @var{c-expr} is true. In non-constant 9566attributes, @var{c-expr} has access to the following variables: 9567 9568@table @var 9569@item insn 9570The rtl instruction under test. 9571@item which_alternative 9572The @code{define_insn} alternative that @var{insn} matches. 9573@xref{Output Statement}. 9574@item operands 9575An array of @var{insn}'s rtl operands. 9576@end table 9577 9578@var{c-expr} behaves like the condition in a C @code{if} statement, 9579so there is no need to explicitly convert the expression into a boolean 95800 or 1 value. For example, the following two tests are equivalent: 9581 9582@smallexample 9583(match_test "x & 2") 9584(match_test "(x & 2) != 0") 9585@end smallexample 9586 9587@cindex @code{le} and attributes 9588@cindex @code{leu} and attributes 9589@cindex @code{lt} and attributes 9590@cindex @code{gt} and attributes 9591@cindex @code{gtu} and attributes 9592@cindex @code{ge} and attributes 9593@cindex @code{geu} and attributes 9594@cindex @code{ne} and attributes 9595@cindex @code{eq} and attributes 9596@cindex @code{plus} and attributes 9597@cindex @code{minus} and attributes 9598@cindex @code{mult} and attributes 9599@cindex @code{div} and attributes 9600@cindex @code{mod} and attributes 9601@cindex @code{abs} and attributes 9602@cindex @code{neg} and attributes 9603@cindex @code{ashift} and attributes 9604@cindex @code{lshiftrt} and attributes 9605@cindex @code{ashiftrt} and attributes 9606@item (le @var{arith1} @var{arith2}) 9607@itemx (leu @var{arith1} @var{arith2}) 9608@itemx (lt @var{arith1} @var{arith2}) 9609@itemx (ltu @var{arith1} @var{arith2}) 9610@itemx (gt @var{arith1} @var{arith2}) 9611@itemx (gtu @var{arith1} @var{arith2}) 9612@itemx (ge @var{arith1} @var{arith2}) 9613@itemx (geu @var{arith1} @var{arith2}) 9614@itemx (ne @var{arith1} @var{arith2}) 9615@itemx (eq @var{arith1} @var{arith2}) 9616These tests are true if the indicated comparison of the two arithmetic 9617expressions is true. Arithmetic expressions are formed with 9618@code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod}, 9619@code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not}, 9620@code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions. 9621 9622@findex get_attr 9623@code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn 9624Lengths},for additional forms). @code{symbol_ref} is a string 9625denoting a C expression that yields an @code{int} when evaluated by the 9626@samp{get_attr_@dots{}} routine. It should normally be a global 9627variable. 9628 9629@findex eq_attr 9630@item (eq_attr @var{name} @var{value}) 9631@var{name} is a string specifying the name of an attribute. 9632 9633@var{value} is a string that is either a valid value for attribute 9634@var{name}, a comma-separated list of values, or @samp{!} followed by a 9635value or list. If @var{value} does not begin with a @samp{!}, this 9636test is true if the value of the @var{name} attribute of the current 9637insn is in the list specified by @var{value}. If @var{value} begins 9638with a @samp{!}, this test is true if the attribute's value is 9639@emph{not} in the specified list. 9640 9641For example, 9642 9643@smallexample 9644(eq_attr "type" "load,store") 9645@end smallexample 9646 9647@noindent 9648is equivalent to 9649 9650@smallexample 9651(ior (eq_attr "type" "load") (eq_attr "type" "store")) 9652@end smallexample 9653 9654If @var{name} specifies an attribute of @samp{alternative}, it refers to the 9655value of the compiler variable @code{which_alternative} 9656(@pxref{Output Statement}) and the values must be small integers. For 9657example, 9658 9659@smallexample 9660(eq_attr "alternative" "2,3") 9661@end smallexample 9662 9663@noindent 9664is equivalent to 9665 9666@smallexample 9667(ior (eq (symbol_ref "which_alternative") (const_int 2)) 9668 (eq (symbol_ref "which_alternative") (const_int 3))) 9669@end smallexample 9670 9671Note that, for most attributes, an @code{eq_attr} test is simplified in cases 9672where the value of the attribute being tested is known for all insns matching 9673a particular pattern. This is by far the most common case. 9674 9675@findex attr_flag 9676@item (attr_flag @var{name}) 9677The value of an @code{attr_flag} expression is true if the flag 9678specified by @var{name} is true for the @code{insn} currently being 9679scheduled. 9680 9681@var{name} is a string specifying one of a fixed set of flags to test. 9682Test the flags @code{forward} and @code{backward} to determine the 9683direction of a conditional branch. 9684 9685This example describes a conditional branch delay slot which 9686can be nullified for forward branches that are taken (annul-true) or 9687for backward branches which are not taken (annul-false). 9688 9689@smallexample 9690(define_delay (eq_attr "type" "cbranch") 9691 [(eq_attr "in_branch_delay" "true") 9692 (and (eq_attr "in_branch_delay" "true") 9693 (attr_flag "forward")) 9694 (and (eq_attr "in_branch_delay" "true") 9695 (attr_flag "backward"))]) 9696@end smallexample 9697 9698The @code{forward} and @code{backward} flags are false if the current 9699@code{insn} being scheduled is not a conditional branch. 9700 9701@code{attr_flag} is only used during delay slot scheduling and has no 9702meaning to other passes of the compiler. 9703 9704@findex attr 9705@item (attr @var{name}) 9706The value of another attribute is returned. This is most useful 9707for numeric attributes, as @code{eq_attr} and @code{attr_flag} 9708produce more efficient code for non-numeric attributes. 9709@end table 9710 9711@end ifset 9712@ifset INTERNALS 9713@node Tagging Insns 9714@subsection Assigning Attribute Values to Insns 9715@cindex tagging insns 9716@cindex assigning attribute values to insns 9717 9718The value assigned to an attribute of an insn is primarily determined by 9719which pattern is matched by that insn (or which @code{define_peephole} 9720generated it). Every @code{define_insn} and @code{define_peephole} can 9721have an optional last argument to specify the values of attributes for 9722matching insns. The value of any attribute not specified in a particular 9723insn is set to the default value for that attribute, as specified in its 9724@code{define_attr}. Extensive use of default values for attributes 9725permits the specification of the values for only one or two attributes 9726in the definition of most insn patterns, as seen in the example in the 9727next section. 9728 9729The optional last argument of @code{define_insn} and 9730@code{define_peephole} is a vector of expressions, each of which defines 9731the value for a single attribute. The most general way of assigning an 9732attribute's value is to use a @code{set} expression whose first operand is an 9733@code{attr} expression giving the name of the attribute being set. The 9734second operand of the @code{set} is an attribute expression 9735(@pxref{Expressions}) giving the value of the attribute. 9736 9737When the attribute value depends on the @samp{alternative} attribute 9738(i.e., which is the applicable alternative in the constraint of the 9739insn), the @code{set_attr_alternative} expression can be used. It 9740allows the specification of a vector of attribute expressions, one for 9741each alternative. 9742 9743@findex set_attr 9744When the generality of arbitrary attribute expressions is not required, 9745the simpler @code{set_attr} expression can be used, which allows 9746specifying a string giving either a single attribute value or a list 9747of attribute values, one for each alternative. 9748 9749The form of each of the above specifications is shown below. In each case, 9750@var{name} is a string specifying the attribute to be set. 9751 9752@table @code 9753@item (set_attr @var{name} @var{value-string}) 9754@var{value-string} is either a string giving the desired attribute value, 9755or a string containing a comma-separated list giving the values for 9756succeeding alternatives. The number of elements must match the number 9757of alternatives in the constraint of the insn pattern. 9758 9759Note that it may be useful to specify @samp{*} for some alternative, in 9760which case the attribute will assume its default value for insns matching 9761that alternative. 9762 9763@findex set_attr_alternative 9764@item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}]) 9765Depending on the alternative of the insn, the value will be one of the 9766specified values. This is a shorthand for using a @code{cond} with 9767tests on the @samp{alternative} attribute. 9768 9769@findex attr 9770@item (set (attr @var{name}) @var{value}) 9771The first operand of this @code{set} must be the special RTL expression 9772@code{attr}, whose sole operand is a string giving the name of the 9773attribute being set. @var{value} is the value of the attribute. 9774@end table 9775 9776The following shows three different ways of representing the same 9777attribute value specification: 9778 9779@smallexample 9780(set_attr "type" "load,store,arith") 9781 9782(set_attr_alternative "type" 9783 [(const_string "load") (const_string "store") 9784 (const_string "arith")]) 9785 9786(set (attr "type") 9787 (cond [(eq_attr "alternative" "1") (const_string "load") 9788 (eq_attr "alternative" "2") (const_string "store")] 9789 (const_string "arith"))) 9790@end smallexample 9791 9792@need 1000 9793@findex define_asm_attributes 9794The @code{define_asm_attributes} expression provides a mechanism to 9795specify the attributes assigned to insns produced from an @code{asm} 9796statement. It has the form: 9797 9798@smallexample 9799(define_asm_attributes [@var{attr-sets}]) 9800@end smallexample 9801 9802@noindent 9803where @var{attr-sets} is specified the same as for both the 9804@code{define_insn} and the @code{define_peephole} expressions. 9805 9806These values will typically be the ``worst case'' attribute values. For 9807example, they might indicate that the condition code will be clobbered. 9808 9809A specification for a @code{length} attribute is handled specially. The 9810way to compute the length of an @code{asm} insn is to multiply the 9811length specified in the expression @code{define_asm_attributes} by the 9812number of machine instructions specified in the @code{asm} statement, 9813determined by counting the number of semicolons and newlines in the 9814string. Therefore, the value of the @code{length} attribute specified 9815in a @code{define_asm_attributes} should be the maximum possible length 9816of a single machine instruction. 9817 9818@end ifset 9819@ifset INTERNALS 9820@node Attr Example 9821@subsection Example of Attribute Specifications 9822@cindex attribute specifications example 9823@cindex attribute specifications 9824 9825The judicious use of defaulting is important in the efficient use of 9826insn attributes. Typically, insns are divided into @dfn{types} and an 9827attribute, customarily called @code{type}, is used to represent this 9828value. This attribute is normally used only to define the default value 9829for other attributes. An example will clarify this usage. 9830 9831Assume we have a RISC machine with a condition code and in which only 9832full-word operations are performed in registers. Let us assume that we 9833can divide all insns into loads, stores, (integer) arithmetic 9834operations, floating point operations, and branches. 9835 9836Here we will concern ourselves with determining the effect of an insn on 9837the condition code and will limit ourselves to the following possible 9838effects: The condition code can be set unpredictably (clobbered), not 9839be changed, be set to agree with the results of the operation, or only 9840changed if the item previously set into the condition code has been 9841modified. 9842 9843Here is part of a sample @file{md} file for such a machine: 9844 9845@smallexample 9846(define_attr "type" "load,store,arith,fp,branch" (const_string "arith")) 9847 9848(define_attr "cc" "clobber,unchanged,set,change0" 9849 (cond [(eq_attr "type" "load") 9850 (const_string "change0") 9851 (eq_attr "type" "store,branch") 9852 (const_string "unchanged") 9853 (eq_attr "type" "arith") 9854 (if_then_else (match_operand:SI 0 "" "") 9855 (const_string "set") 9856 (const_string "clobber"))] 9857 (const_string "clobber"))) 9858 9859(define_insn "" 9860 [(set (match_operand:SI 0 "general_operand" "=r,r,m") 9861 (match_operand:SI 1 "general_operand" "r,m,r"))] 9862 "" 9863 "@@ 9864 move %0,%1 9865 load %0,%1 9866 store %0,%1" 9867 [(set_attr "type" "arith,load,store")]) 9868@end smallexample 9869 9870Note that we assume in the above example that arithmetic operations 9871performed on quantities smaller than a machine word clobber the condition 9872code since they will set the condition code to a value corresponding to the 9873full-word result. 9874 9875@end ifset 9876@ifset INTERNALS 9877@node Insn Lengths 9878@subsection Computing the Length of an Insn 9879@cindex insn lengths, computing 9880@cindex computing the length of an insn 9881 9882For many machines, multiple types of branch instructions are provided, each 9883for different length branch displacements. In most cases, the assembler 9884will choose the correct instruction to use. However, when the assembler 9885cannot do so, GCC can when a special attribute, the @code{length} 9886attribute, is defined. This attribute must be defined to have numeric 9887values by specifying a null string in its @code{define_attr}. 9888 9889In the case of the @code{length} attribute, two additional forms of 9890arithmetic terms are allowed in test expressions: 9891 9892@table @code 9893@cindex @code{match_dup} and attributes 9894@item (match_dup @var{n}) 9895This refers to the address of operand @var{n} of the current insn, which 9896must be a @code{label_ref}. 9897 9898@cindex @code{pc} and attributes 9899@item (pc) 9900For non-branch instructions and backward branch instructions, this refers 9901to the address of the current insn. But for forward branch instructions, 9902this refers to the address of the next insn, because the length of the 9903current insn is to be computed. 9904@end table 9905 9906@cindex @code{addr_vec}, length of 9907@cindex @code{addr_diff_vec}, length of 9908For normal insns, the length will be determined by value of the 9909@code{length} attribute. In the case of @code{addr_vec} and 9910@code{addr_diff_vec} insn patterns, the length is computed as 9911the number of vectors multiplied by the size of each vector. 9912 9913Lengths are measured in addressable storage units (bytes). 9914 9915Note that it is possible to call functions via the @code{symbol_ref} 9916mechanism to compute the length of an insn. However, if you use this 9917mechanism you must provide dummy clauses to express the maximum length 9918without using the function call. You can an example of this in the 9919@code{pa} machine description for the @code{call_symref} pattern. 9920 9921The following macros can be used to refine the length computation: 9922 9923@table @code 9924@findex ADJUST_INSN_LENGTH 9925@item ADJUST_INSN_LENGTH (@var{insn}, @var{length}) 9926If defined, modifies the length assigned to instruction @var{insn} as a 9927function of the context in which it is used. @var{length} is an lvalue 9928that contains the initially computed length of the insn and should be 9929updated with the correct length of the insn. 9930 9931This macro will normally not be required. A case in which it is 9932required is the ROMP@. On this machine, the size of an @code{addr_vec} 9933insn must be increased by two to compensate for the fact that alignment 9934may be required. 9935@end table 9936 9937@findex get_attr_length 9938The routine that returns @code{get_attr_length} (the value of the 9939@code{length} attribute) can be used by the output routine to 9940determine the form of the branch instruction to be written, as the 9941example below illustrates. 9942 9943As an example of the specification of variable-length branches, consider 9944the IBM 360. If we adopt the convention that a register will be set to 9945the starting address of a function, we can jump to labels within 4k of 9946the start using a four-byte instruction. Otherwise, we need a six-byte 9947sequence to load the address from memory and then branch to it. 9948 9949On such a machine, a pattern for a branch instruction might be specified 9950as follows: 9951 9952@smallexample 9953(define_insn "jump" 9954 [(set (pc) 9955 (label_ref (match_operand 0 "" "")))] 9956 "" 9957@{ 9958 return (get_attr_length (insn) == 4 9959 ? "b %l0" : "l r15,=a(%l0); br r15"); 9960@} 9961 [(set (attr "length") 9962 (if_then_else (lt (match_dup 0) (const_int 4096)) 9963 (const_int 4) 9964 (const_int 6)))]) 9965@end smallexample 9966 9967@end ifset 9968@ifset INTERNALS 9969@node Constant Attributes 9970@subsection Constant Attributes 9971@cindex constant attributes 9972 9973A special form of @code{define_attr}, where the expression for the 9974default value is a @code{const} expression, indicates an attribute that 9975is constant for a given run of the compiler. Constant attributes may be 9976used to specify which variety of processor is used. For example, 9977 9978@smallexample 9979(define_attr "cpu" "m88100,m88110,m88000" 9980 (const 9981 (cond [(symbol_ref "TARGET_88100") (const_string "m88100") 9982 (symbol_ref "TARGET_88110") (const_string "m88110")] 9983 (const_string "m88000")))) 9984 9985(define_attr "memory" "fast,slow" 9986 (const 9987 (if_then_else (symbol_ref "TARGET_FAST_MEM") 9988 (const_string "fast") 9989 (const_string "slow")))) 9990@end smallexample 9991 9992The routine generated for constant attributes has no parameters as it 9993does not depend on any particular insn. RTL expressions used to define 9994the value of a constant attribute may use the @code{symbol_ref} form, 9995but may not use either the @code{match_operand} form or @code{eq_attr} 9996forms involving insn attributes. 9997 9998@end ifset 9999@ifset INTERNALS 10000@node Mnemonic Attribute 10001@subsection Mnemonic Attribute 10002@cindex mnemonic attribute 10003 10004The @code{mnemonic} attribute is a string type attribute holding the 10005instruction mnemonic for an insn alternative. The attribute values 10006will automatically be generated by the machine description parser if 10007there is an attribute definition in the md file: 10008 10009@smallexample 10010(define_attr "mnemonic" "unknown" (const_string "unknown")) 10011@end smallexample 10012 10013The default value can be freely chosen as long as it does not collide 10014with any of the instruction mnemonics. This value will be used 10015whenever the machine description parser is not able to determine the 10016mnemonic string. This might be the case for output templates 10017containing more than a single instruction as in 10018@code{"mvcle\t%0,%1,0\;jo\t.-4"}. 10019 10020The @code{mnemonic} attribute set is not generated automatically if the 10021instruction string is generated via C code. 10022 10023An existing @code{mnemonic} attribute set in an insn definition will not 10024be overriden by the md file parser. That way it is possible to 10025manually set the instruction mnemonics for the cases where the md file 10026parser fails to determine it automatically. 10027 10028The @code{mnemonic} attribute is useful for dealing with instruction 10029specific properties in the pipeline description without defining 10030additional insn attributes. 10031 10032@smallexample 10033(define_attr "ooo_expanded" "" 10034 (cond [(eq_attr "mnemonic" "dlr,dsgr,d,dsgf,stam,dsgfr,dlgr") 10035 (const_int 1)] 10036 (const_int 0))) 10037@end smallexample 10038 10039@end ifset 10040@ifset INTERNALS 10041@node Delay Slots 10042@subsection Delay Slot Scheduling 10043@cindex delay slots, defining 10044 10045The insn attribute mechanism can be used to specify the requirements for 10046delay slots, if any, on a target machine. An instruction is said to 10047require a @dfn{delay slot} if some instructions that are physically 10048after the instruction are executed as if they were located before it. 10049Classic examples are branch and call instructions, which often execute 10050the following instruction before the branch or call is performed. 10051 10052On some machines, conditional branch instructions can optionally 10053@dfn{annul} instructions in the delay slot. This means that the 10054instruction will not be executed for certain branch outcomes. Both 10055instructions that annul if the branch is true and instructions that 10056annul if the branch is false are supported. 10057 10058Delay slot scheduling differs from instruction scheduling in that 10059determining whether an instruction needs a delay slot is dependent only 10060on the type of instruction being generated, not on data flow between the 10061instructions. See the next section for a discussion of data-dependent 10062instruction scheduling. 10063 10064@findex define_delay 10065The requirement of an insn needing one or more delay slots is indicated 10066via the @code{define_delay} expression. It has the following form: 10067 10068@smallexample 10069(define_delay @var{test} 10070 [@var{delay-1} @var{annul-true-1} @var{annul-false-1} 10071 @var{delay-2} @var{annul-true-2} @var{annul-false-2} 10072 @dots{}]) 10073@end smallexample 10074 10075@var{test} is an attribute test that indicates whether this 10076@code{define_delay} applies to a particular insn. If so, the number of 10077required delay slots is determined by the length of the vector specified 10078as the second argument. An insn placed in delay slot @var{n} must 10079satisfy attribute test @var{delay-n}. @var{annul-true-n} is an 10080attribute test that specifies which insns may be annulled if the branch 10081is true. Similarly, @var{annul-false-n} specifies which insns in the 10082delay slot may be annulled if the branch is false. If annulling is not 10083supported for that delay slot, @code{(nil)} should be coded. 10084 10085For example, in the common case where branch and call insns require 10086a single delay slot, which may contain any insn other than a branch or 10087call, the following would be placed in the @file{md} file: 10088 10089@smallexample 10090(define_delay (eq_attr "type" "branch,call") 10091 [(eq_attr "type" "!branch,call") (nil) (nil)]) 10092@end smallexample 10093 10094Multiple @code{define_delay} expressions may be specified. In this 10095case, each such expression specifies different delay slot requirements 10096and there must be no insn for which tests in two @code{define_delay} 10097expressions are both true. 10098 10099For example, if we have a machine that requires one delay slot for branches 10100but two for calls, no delay slot can contain a branch or call insn, 10101and any valid insn in the delay slot for the branch can be annulled if the 10102branch is true, we might represent this as follows: 10103 10104@smallexample 10105(define_delay (eq_attr "type" "branch") 10106 [(eq_attr "type" "!branch,call") 10107 (eq_attr "type" "!branch,call") 10108 (nil)]) 10109 10110(define_delay (eq_attr "type" "call") 10111 [(eq_attr "type" "!branch,call") (nil) (nil) 10112 (eq_attr "type" "!branch,call") (nil) (nil)]) 10113@end smallexample 10114@c the above is *still* too long. --mew 4feb93 10115 10116@end ifset 10117@ifset INTERNALS 10118@node Processor pipeline description 10119@subsection Specifying processor pipeline description 10120@cindex processor pipeline description 10121@cindex processor functional units 10122@cindex instruction latency time 10123@cindex interlock delays 10124@cindex data dependence delays 10125@cindex reservation delays 10126@cindex pipeline hazard recognizer 10127@cindex automaton based pipeline description 10128@cindex regular expressions 10129@cindex deterministic finite state automaton 10130@cindex automaton based scheduler 10131@cindex RISC 10132@cindex VLIW 10133 10134To achieve better performance, most modern processors 10135(super-pipelined, superscalar @acronym{RISC}, and @acronym{VLIW} 10136processors) have many @dfn{functional units} on which several 10137instructions can be executed simultaneously. An instruction starts 10138execution if its issue conditions are satisfied. If not, the 10139instruction is stalled until its conditions are satisfied. Such 10140@dfn{interlock (pipeline) delay} causes interruption of the fetching 10141of successor instructions (or demands nop instructions, e.g.@: for some 10142MIPS processors). 10143 10144There are two major kinds of interlock delays in modern processors. 10145The first one is a data dependence delay determining @dfn{instruction 10146latency time}. The instruction execution is not started until all 10147source data have been evaluated by prior instructions (there are more 10148complex cases when the instruction execution starts even when the data 10149are not available but will be ready in given time after the 10150instruction execution start). Taking the data dependence delays into 10151account is simple. The data dependence (true, output, and 10152anti-dependence) delay between two instructions is given by a 10153constant. In most cases this approach is adequate. The second kind 10154of interlock delays is a reservation delay. The reservation delay 10155means that two instructions under execution will be in need of shared 10156processors resources, i.e.@: buses, internal registers, and/or 10157functional units, which are reserved for some time. Taking this kind 10158of delay into account is complex especially for modern @acronym{RISC} 10159processors. 10160 10161The task of exploiting more processor parallelism is solved by an 10162instruction scheduler. For a better solution to this problem, the 10163instruction scheduler has to have an adequate description of the 10164processor parallelism (or @dfn{pipeline description}). GCC 10165machine descriptions describe processor parallelism and functional 10166unit reservations for groups of instructions with the aid of 10167@dfn{regular expressions}. 10168 10169The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to 10170figure out the possibility of the instruction issue by the processor 10171on a given simulated processor cycle. The pipeline hazard recognizer is 10172automatically generated from the processor pipeline description. The 10173pipeline hazard recognizer generated from the machine description 10174is based on a deterministic finite state automaton (@acronym{DFA}): 10175the instruction issue is possible if there is a transition from one 10176automaton state to another one. This algorithm is very fast, and 10177furthermore, its speed is not dependent on processor 10178complexity@footnote{However, the size of the automaton depends on 10179processor complexity. To limit this effect, machine descriptions 10180can split orthogonal parts of the machine description among several 10181automata: but then, since each of these must be stepped independently, 10182this does cause a small decrease in the algorithm's performance.}. 10183 10184@cindex automaton based pipeline description 10185The rest of this section describes the directives that constitute 10186an automaton-based processor pipeline description. The order of 10187these constructions within the machine description file is not 10188important. 10189 10190@findex define_automaton 10191@cindex pipeline hazard recognizer 10192The following optional construction describes names of automata 10193generated and used for the pipeline hazards recognition. Sometimes 10194the generated finite state automaton used by the pipeline hazard 10195recognizer is large. If we use more than one automaton and bind functional 10196units to the automata, the total size of the automata is usually 10197less than the size of the single automaton. If there is no one such 10198construction, only one finite state automaton is generated. 10199 10200@smallexample 10201(define_automaton @var{automata-names}) 10202@end smallexample 10203 10204@var{automata-names} is a string giving names of the automata. The 10205names are separated by commas. All the automata should have unique names. 10206The automaton name is used in the constructions @code{define_cpu_unit} and 10207@code{define_query_cpu_unit}. 10208 10209@findex define_cpu_unit 10210@cindex processor functional units 10211Each processor functional unit used in the description of instruction 10212reservations should be described by the following construction. 10213 10214@smallexample 10215(define_cpu_unit @var{unit-names} [@var{automaton-name}]) 10216@end smallexample 10217 10218@var{unit-names} is a string giving the names of the functional units 10219separated by commas. Don't use name @samp{nothing}, it is reserved 10220for other goals. 10221 10222@var{automaton-name} is a string giving the name of the automaton with 10223which the unit is bound. The automaton should be described in 10224construction @code{define_automaton}. You should give 10225@dfn{automaton-name}, if there is a defined automaton. 10226 10227The assignment of units to automata are constrained by the uses of the 10228units in insn reservations. The most important constraint is: if a 10229unit reservation is present on a particular cycle of an alternative 10230for an insn reservation, then some unit from the same automaton must 10231be present on the same cycle for the other alternatives of the insn 10232reservation. The rest of the constraints are mentioned in the 10233description of the subsequent constructions. 10234 10235@findex define_query_cpu_unit 10236@cindex querying function unit reservations 10237The following construction describes CPU functional units analogously 10238to @code{define_cpu_unit}. The reservation of such units can be 10239queried for an automaton state. The instruction scheduler never 10240queries reservation of functional units for given automaton state. So 10241as a rule, you don't need this construction. This construction could 10242be used for future code generation goals (e.g.@: to generate 10243@acronym{VLIW} insn templates). 10244 10245@smallexample 10246(define_query_cpu_unit @var{unit-names} [@var{automaton-name}]) 10247@end smallexample 10248 10249@var{unit-names} is a string giving names of the functional units 10250separated by commas. 10251 10252@var{automaton-name} is a string giving the name of the automaton with 10253which the unit is bound. 10254 10255@findex define_insn_reservation 10256@cindex instruction latency time 10257@cindex regular expressions 10258@cindex data bypass 10259The following construction is the major one to describe pipeline 10260characteristics of an instruction. 10261 10262@smallexample 10263(define_insn_reservation @var{insn-name} @var{default_latency} 10264 @var{condition} @var{regexp}) 10265@end smallexample 10266 10267@var{default_latency} is a number giving latency time of the 10268instruction. There is an important difference between the old 10269description and the automaton based pipeline description. The latency 10270time is used for all dependencies when we use the old description. In 10271the automaton based pipeline description, the given latency time is only 10272used for true dependencies. The cost of anti-dependencies is always 10273zero and the cost of output dependencies is the difference between 10274latency times of the producing and consuming insns (if the difference 10275is negative, the cost is considered to be zero). You can always 10276change the default costs for any description by using the target hook 10277@code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}). 10278 10279@var{insn-name} is a string giving the internal name of the insn. The 10280internal names are used in constructions @code{define_bypass} and in 10281the automaton description file generated for debugging. The internal 10282name has nothing in common with the names in @code{define_insn}. It is a 10283good practice to use insn classes described in the processor manual. 10284 10285@var{condition} defines what RTL insns are described by this 10286construction. You should remember that you will be in trouble if 10287@var{condition} for two or more different 10288@code{define_insn_reservation} constructions is TRUE for an insn. In 10289this case what reservation will be used for the insn is not defined. 10290Such cases are not checked during generation of the pipeline hazards 10291recognizer because in general recognizing that two conditions may have 10292the same value is quite difficult (especially if the conditions 10293contain @code{symbol_ref}). It is also not checked during the 10294pipeline hazard recognizer work because it would slow down the 10295recognizer considerably. 10296 10297@var{regexp} is a string describing the reservation of the cpu's functional 10298units by the instruction. The reservations are described by a regular 10299expression according to the following syntax: 10300 10301@smallexample 10302 regexp = regexp "," oneof 10303 | oneof 10304 10305 oneof = oneof "|" allof 10306 | allof 10307 10308 allof = allof "+" repeat 10309 | repeat 10310 10311 repeat = element "*" number 10312 | element 10313 10314 element = cpu_function_unit_name 10315 | reservation_name 10316 | result_name 10317 | "nothing" 10318 | "(" regexp ")" 10319@end smallexample 10320 10321@itemize @bullet 10322@item 10323@samp{,} is used for describing the start of the next cycle in 10324the reservation. 10325 10326@item 10327@samp{|} is used for describing a reservation described by the first 10328regular expression @strong{or} a reservation described by the second 10329regular expression @strong{or} etc. 10330 10331@item 10332@samp{+} is used for describing a reservation described by the first 10333regular expression @strong{and} a reservation described by the 10334second regular expression @strong{and} etc. 10335 10336@item 10337@samp{*} is used for convenience and simply means a sequence in which 10338the regular expression are repeated @var{number} times with cycle 10339advancing (see @samp{,}). 10340 10341@item 10342@samp{cpu_function_unit_name} denotes reservation of the named 10343functional unit. 10344 10345@item 10346@samp{reservation_name} --- see description of construction 10347@samp{define_reservation}. 10348 10349@item 10350@samp{nothing} denotes no unit reservations. 10351@end itemize 10352 10353@findex define_reservation 10354Sometimes unit reservations for different insns contain common parts. 10355In such case, you can simplify the pipeline description by describing 10356the common part by the following construction 10357 10358@smallexample 10359(define_reservation @var{reservation-name} @var{regexp}) 10360@end smallexample 10361 10362@var{reservation-name} is a string giving name of @var{regexp}. 10363Functional unit names and reservation names are in the same name 10364space. So the reservation names should be different from the 10365functional unit names and cannot be the reserved name @samp{nothing}. 10366 10367@findex define_bypass 10368@cindex instruction latency time 10369@cindex data bypass 10370The following construction is used to describe exceptions in the 10371latency time for given instruction pair. This is so called bypasses. 10372 10373@smallexample 10374(define_bypass @var{number} @var{out_insn_names} @var{in_insn_names} 10375 [@var{guard}]) 10376@end smallexample 10377 10378@var{number} defines when the result generated by the instructions 10379given in string @var{out_insn_names} will be ready for the 10380instructions given in string @var{in_insn_names}. Each of these 10381strings is a comma-separated list of filename-style globs and 10382they refer to the names of @code{define_insn_reservation}s. 10383For example: 10384@smallexample 10385(define_bypass 1 "cpu1_load_*, cpu1_store_*" "cpu1_load_*") 10386@end smallexample 10387defines a bypass between instructions that start with 10388@samp{cpu1_load_} or @samp{cpu1_store_} and those that start with 10389@samp{cpu1_load_}. 10390 10391@var{guard} is an optional string giving the name of a C function which 10392defines an additional guard for the bypass. The function will get the 10393two insns as parameters. If the function returns zero the bypass will 10394be ignored for this case. The additional guard is necessary to 10395recognize complicated bypasses, e.g.@: when the consumer is only an address 10396of insn @samp{store} (not a stored value). 10397 10398If there are more one bypass with the same output and input insns, the 10399chosen bypass is the first bypass with a guard in description whose 10400guard function returns nonzero. If there is no such bypass, then 10401bypass without the guard function is chosen. 10402 10403@findex exclusion_set 10404@findex presence_set 10405@findex final_presence_set 10406@findex absence_set 10407@findex final_absence_set 10408@cindex VLIW 10409@cindex RISC 10410The following five constructions are usually used to describe 10411@acronym{VLIW} processors, or more precisely, to describe a placement 10412of small instructions into @acronym{VLIW} instruction slots. They 10413can be used for @acronym{RISC} processors, too. 10414 10415@smallexample 10416(exclusion_set @var{unit-names} @var{unit-names}) 10417(presence_set @var{unit-names} @var{patterns}) 10418(final_presence_set @var{unit-names} @var{patterns}) 10419(absence_set @var{unit-names} @var{patterns}) 10420(final_absence_set @var{unit-names} @var{patterns}) 10421@end smallexample 10422 10423@var{unit-names} is a string giving names of functional units 10424separated by commas. 10425 10426@var{patterns} is a string giving patterns of functional units 10427separated by comma. Currently pattern is one unit or units 10428separated by white-spaces. 10429 10430The first construction (@samp{exclusion_set}) means that each 10431functional unit in the first string cannot be reserved simultaneously 10432with a unit whose name is in the second string and vice versa. For 10433example, the construction is useful for describing processors 10434(e.g.@: some SPARC processors) with a fully pipelined floating point 10435functional unit which can execute simultaneously only single floating 10436point insns or only double floating point insns. 10437 10438The second construction (@samp{presence_set}) means that each 10439functional unit in the first string cannot be reserved unless at 10440least one of pattern of units whose names are in the second string is 10441reserved. This is an asymmetric relation. For example, it is useful 10442for description that @acronym{VLIW} @samp{slot1} is reserved after 10443@samp{slot0} reservation. We could describe it by the following 10444construction 10445 10446@smallexample 10447(presence_set "slot1" "slot0") 10448@end smallexample 10449 10450Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0} 10451reservation. In this case we could write 10452 10453@smallexample 10454(presence_set "slot1" "slot0 b0") 10455@end smallexample 10456 10457The third construction (@samp{final_presence_set}) is analogous to 10458@samp{presence_set}. The difference between them is when checking is 10459done. When an instruction is issued in given automaton state 10460reflecting all current and planned unit reservations, the automaton 10461state is changed. The first state is a source state, the second one 10462is a result state. Checking for @samp{presence_set} is done on the 10463source state reservation, checking for @samp{final_presence_set} is 10464done on the result reservation. This construction is useful to 10465describe a reservation which is actually two subsequent reservations. 10466For example, if we use 10467 10468@smallexample 10469(presence_set "slot1" "slot0") 10470@end smallexample 10471 10472the following insn will be never issued (because @samp{slot1} requires 10473@samp{slot0} which is absent in the source state). 10474 10475@smallexample 10476(define_reservation "insn_and_nop" "slot0 + slot1") 10477@end smallexample 10478 10479but it can be issued if we use analogous @samp{final_presence_set}. 10480 10481The forth construction (@samp{absence_set}) means that each functional 10482unit in the first string can be reserved only if each pattern of units 10483whose names are in the second string is not reserved. This is an 10484asymmetric relation (actually @samp{exclusion_set} is analogous to 10485this one but it is symmetric). For example it might be useful in a 10486@acronym{VLIW} description to say that @samp{slot0} cannot be reserved 10487after either @samp{slot1} or @samp{slot2} have been reserved. This 10488can be described as: 10489 10490@smallexample 10491(absence_set "slot0" "slot1, slot2") 10492@end smallexample 10493 10494Or @samp{slot2} cannot be reserved if @samp{slot0} and unit @samp{b0} 10495are reserved or @samp{slot1} and unit @samp{b1} are reserved. In 10496this case we could write 10497 10498@smallexample 10499(absence_set "slot2" "slot0 b0, slot1 b1") 10500@end smallexample 10501 10502All functional units mentioned in a set should belong to the same 10503automaton. 10504 10505The last construction (@samp{final_absence_set}) is analogous to 10506@samp{absence_set} but checking is done on the result (state) 10507reservation. See comments for @samp{final_presence_set}. 10508 10509@findex automata_option 10510@cindex deterministic finite state automaton 10511@cindex nondeterministic finite state automaton 10512@cindex finite state automaton minimization 10513You can control the generator of the pipeline hazard recognizer with 10514the following construction. 10515 10516@smallexample 10517(automata_option @var{options}) 10518@end smallexample 10519 10520@var{options} is a string giving options which affect the generated 10521code. Currently there are the following options: 10522 10523@itemize @bullet 10524@item 10525@dfn{no-minimization} makes no minimization of the automaton. This is 10526only worth to do when we are debugging the description and need to 10527look more accurately at reservations of states. 10528 10529@item 10530@dfn{time} means printing time statistics about the generation of 10531automata. 10532 10533@item 10534@dfn{stats} means printing statistics about the generated automata 10535such as the number of DFA states, NDFA states and arcs. 10536 10537@item 10538@dfn{v} means a generation of the file describing the result automata. 10539The file has suffix @samp{.dfa} and can be used for the description 10540verification and debugging. 10541 10542@item 10543@dfn{w} means a generation of warning instead of error for 10544non-critical errors. 10545 10546@item 10547@dfn{no-comb-vect} prevents the automaton generator from generating 10548two data structures and comparing them for space efficiency. Using 10549a comb vector to represent transitions may be better, but it can be 10550very expensive to construct. This option is useful if the build 10551process spends an unacceptably long time in genautomata. 10552 10553@item 10554@dfn{ndfa} makes nondeterministic finite state automata. This affects 10555the treatment of operator @samp{|} in the regular expressions. The 10556usual treatment of the operator is to try the first alternative and, 10557if the reservation is not possible, the second alternative. The 10558nondeterministic treatment means trying all alternatives, some of them 10559may be rejected by reservations in the subsequent insns. 10560 10561@item 10562@dfn{collapse-ndfa} modifies the behavior of the generator when 10563producing an automaton. An additional state transition to collapse a 10564nondeterministic @acronym{NDFA} state to a deterministic @acronym{DFA} 10565state is generated. It can be triggered by passing @code{const0_rtx} to 10566state_transition. In such an automaton, cycle advance transitions are 10567available only for these collapsed states. This option is useful for 10568ports that want to use the @code{ndfa} option, but also want to use 10569@code{define_query_cpu_unit} to assign units to insns issued in a cycle. 10570 10571@item 10572@dfn{progress} means output of a progress bar showing how many states 10573were generated so far for automaton being processed. This is useful 10574during debugging a @acronym{DFA} description. If you see too many 10575generated states, you could interrupt the generator of the pipeline 10576hazard recognizer and try to figure out a reason for generation of the 10577huge automaton. 10578@end itemize 10579 10580As an example, consider a superscalar @acronym{RISC} machine which can 10581issue three insns (two integer insns and one floating point insn) on 10582the cycle but can finish only two insns. To describe this, we define 10583the following functional units. 10584 10585@smallexample 10586(define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline") 10587(define_cpu_unit "port0, port1") 10588@end smallexample 10589 10590All simple integer insns can be executed in any integer pipeline and 10591their result is ready in two cycles. The simple integer insns are 10592issued into the first pipeline unless it is reserved, otherwise they 10593are issued into the second pipeline. Integer division and 10594multiplication insns can be executed only in the second integer 10595pipeline and their results are ready correspondingly in 9 and 4 10596cycles. The integer division is not pipelined, i.e.@: the subsequent 10597integer division insn cannot be issued until the current division 10598insn finished. Floating point insns are fully pipelined and their 10599results are ready in 3 cycles. Where the result of a floating point 10600insn is used by an integer insn, an additional delay of one cycle is 10601incurred. To describe all of this we could specify 10602 10603@smallexample 10604(define_cpu_unit "div") 10605 10606(define_insn_reservation "simple" 2 (eq_attr "type" "int") 10607 "(i0_pipeline | i1_pipeline), (port0 | port1)") 10608 10609(define_insn_reservation "mult" 4 (eq_attr "type" "mult") 10610 "i1_pipeline, nothing*2, (port0 | port1)") 10611 10612(define_insn_reservation "div" 9 (eq_attr "type" "div") 10613 "i1_pipeline, div*7, div + (port0 | port1)") 10614 10615(define_insn_reservation "float" 3 (eq_attr "type" "float") 10616 "f_pipeline, nothing, (port0 | port1)) 10617 10618(define_bypass 4 "float" "simple,mult,div") 10619@end smallexample 10620 10621To simplify the description we could describe the following reservation 10622 10623@smallexample 10624(define_reservation "finish" "port0|port1") 10625@end smallexample 10626 10627and use it in all @code{define_insn_reservation} as in the following 10628construction 10629 10630@smallexample 10631(define_insn_reservation "simple" 2 (eq_attr "type" "int") 10632 "(i0_pipeline | i1_pipeline), finish") 10633@end smallexample 10634 10635 10636@end ifset 10637@ifset INTERNALS 10638@node Conditional Execution 10639@section Conditional Execution 10640@cindex conditional execution 10641@cindex predication 10642 10643A number of architectures provide for some form of conditional 10644execution, or predication. The hallmark of this feature is the 10645ability to nullify most of the instructions in the instruction set. 10646When the instruction set is large and not entirely symmetric, it 10647can be quite tedious to describe these forms directly in the 10648@file{.md} file. An alternative is the @code{define_cond_exec} template. 10649 10650@findex define_cond_exec 10651@smallexample 10652(define_cond_exec 10653 [@var{predicate-pattern}] 10654 "@var{condition}" 10655 "@var{output-template}" 10656 "@var{optional-insn-attribues}") 10657@end smallexample 10658 10659@var{predicate-pattern} is the condition that must be true for the 10660insn to be executed at runtime and should match a relational operator. 10661One can use @code{match_operator} to match several relational operators 10662at once. Any @code{match_operand} operands must have no more than one 10663alternative. 10664 10665@var{condition} is a C expression that must be true for the generated 10666pattern to match. 10667 10668@findex current_insn_predicate 10669@var{output-template} is a string similar to the @code{define_insn} 10670output template (@pxref{Output Template}), except that the @samp{*} 10671and @samp{@@} special cases do not apply. This is only useful if the 10672assembly text for the predicate is a simple prefix to the main insn. 10673In order to handle the general case, there is a global variable 10674@code{current_insn_predicate} that will contain the entire predicate 10675if the current insn is predicated, and will otherwise be @code{NULL}. 10676 10677@var{optional-insn-attributes} is an optional vector of attributes that gets 10678appended to the insn attributes of the produced cond_exec rtx. It can 10679be used to add some distinguishing attribute to cond_exec rtxs produced 10680that way. An example usage would be to use this attribute in conjunction 10681with attributes on the main pattern to disable particular alternatives under 10682certain conditions. 10683 10684When @code{define_cond_exec} is used, an implicit reference to 10685the @code{predicable} instruction attribute is made. 10686@xref{Insn Attributes}. This attribute must be a boolean (i.e.@: have 10687exactly two elements in its @var{list-of-values}), with the possible 10688values being @code{no} and @code{yes}. The default and all uses in 10689the insns must be a simple constant, not a complex expressions. It 10690may, however, depend on the alternative, by using a comma-separated 10691list of values. If that is the case, the port should also define an 10692@code{enabled} attribute (@pxref{Disable Insn Alternatives}), which 10693should also allow only @code{no} and @code{yes} as its values. 10694 10695For each @code{define_insn} for which the @code{predicable} 10696attribute is true, a new @code{define_insn} pattern will be 10697generated that matches a predicated version of the instruction. 10698For example, 10699 10700@smallexample 10701(define_insn "addsi" 10702 [(set (match_operand:SI 0 "register_operand" "r") 10703 (plus:SI (match_operand:SI 1 "register_operand" "r") 10704 (match_operand:SI 2 "register_operand" "r")))] 10705 "@var{test1}" 10706 "add %2,%1,%0") 10707 10708(define_cond_exec 10709 [(ne (match_operand:CC 0 "register_operand" "c") 10710 (const_int 0))] 10711 "@var{test2}" 10712 "(%0)") 10713@end smallexample 10714 10715@noindent 10716generates a new pattern 10717 10718@smallexample 10719(define_insn "" 10720 [(cond_exec 10721 (ne (match_operand:CC 3 "register_operand" "c") (const_int 0)) 10722 (set (match_operand:SI 0 "register_operand" "r") 10723 (plus:SI (match_operand:SI 1 "register_operand" "r") 10724 (match_operand:SI 2 "register_operand" "r"))))] 10725 "(@var{test2}) && (@var{test1})" 10726 "(%3) add %2,%1,%0") 10727@end smallexample 10728 10729@end ifset 10730@ifset INTERNALS 10731@node Define Subst 10732@section RTL Templates Transformations 10733@cindex define_subst 10734 10735For some hardware architectures there are common cases when the RTL 10736templates for the instructions can be derived from the other RTL 10737templates using simple transformations. E.g., @file{i386.md} contains 10738an RTL template for the ordinary @code{sub} instruction--- 10739@code{*subsi_1}, and for the @code{sub} instruction with subsequent 10740zero-extension---@code{*subsi_1_zext}. Such cases can be easily 10741implemented by a single meta-template capable of generating a modified 10742case based on the initial one: 10743 10744@findex define_subst 10745@smallexample 10746(define_subst "@var{name}" 10747 [@var{input-template}] 10748 "@var{condition}" 10749 [@var{output-template}]) 10750@end smallexample 10751@var{input-template} is a pattern describing the source RTL template, 10752which will be transformed. 10753 10754@var{condition} is a C expression that is conjunct with the condition 10755from the input-template to generate a condition to be used in the 10756output-template. 10757 10758@var{output-template} is a pattern that will be used in the resulting 10759template. 10760 10761@code{define_subst} mechanism is tightly coupled with the notion of the 10762subst attribute (@pxref{Subst Iterators}). The use of 10763@code{define_subst} is triggered by a reference to a subst attribute in 10764the transforming RTL template. This reference initiates duplication of 10765the source RTL template and substitution of the attributes with their 10766values. The source RTL template is left unchanged, while the copy is 10767transformed by @code{define_subst}. This transformation can fail in the 10768case when the source RTL template is not matched against the 10769input-template of the @code{define_subst}. In such case the copy is 10770deleted. 10771 10772@code{define_subst} can be used only in @code{define_insn} and 10773@code{define_expand}, it cannot be used in other expressions (e.g.@: in 10774@code{define_insn_and_split}). 10775 10776@menu 10777* Define Subst Example:: Example of @code{define_subst} work. 10778* Define Subst Pattern Matching:: Process of template comparison. 10779* Define Subst Output Template:: Generation of output template. 10780@end menu 10781 10782@node Define Subst Example 10783@subsection @code{define_subst} Example 10784@cindex define_subst 10785 10786To illustrate how @code{define_subst} works, let us examine a simple 10787template transformation. 10788 10789Suppose there are two kinds of instructions: one that touches flags and 10790the other that does not. The instructions of the second type could be 10791generated with the following @code{define_subst}: 10792 10793@smallexample 10794(define_subst "add_clobber_subst" 10795 [(set (match_operand:SI 0 "" "") 10796 (match_operand:SI 1 "" ""))] 10797 "" 10798 [(set (match_dup 0) 10799 (match_dup 1)) 10800 (clobber (reg:CC FLAGS_REG))]) 10801@end smallexample 10802 10803This @code{define_subst} can be applied to any RTL pattern containing 10804@code{set} of mode SI and generates a copy with clobber when it is 10805applied. 10806 10807Assume there is an RTL template for a @code{max} instruction to be used 10808in @code{define_subst} mentioned above: 10809 10810@smallexample 10811(define_insn "maxsi" 10812 [(set (match_operand:SI 0 "register_operand" "=r") 10813 (max:SI 10814 (match_operand:SI 1 "register_operand" "r") 10815 (match_operand:SI 2 "register_operand" "r")))] 10816 "" 10817 "max\t@{%2, %1, %0|%0, %1, %2@}" 10818 [@dots{}]) 10819@end smallexample 10820 10821To mark the RTL template for @code{define_subst} application, 10822subst-attributes are used. They should be declared in advance: 10823 10824@smallexample 10825(define_subst_attr "add_clobber_name" "add_clobber_subst" "_noclobber" "_clobber") 10826@end smallexample 10827 10828Here @samp{add_clobber_name} is the attribute name, 10829@samp{add_clobber_subst} is the name of the corresponding 10830@code{define_subst}, the third argument (@samp{_noclobber}) is the 10831attribute value that would be substituted into the unchanged version of 10832the source RTL template, and the last argument (@samp{_clobber}) is the 10833value that would be substituted into the second, transformed, 10834version of the RTL template. 10835 10836Once the subst-attribute has been defined, it should be used in RTL 10837templates which need to be processed by the @code{define_subst}. So, 10838the original RTL template should be changed: 10839 10840@smallexample 10841(define_insn "maxsi<add_clobber_name>" 10842 [(set (match_operand:SI 0 "register_operand" "=r") 10843 (max:SI 10844 (match_operand:SI 1 "register_operand" "r") 10845 (match_operand:SI 2 "register_operand" "r")))] 10846 "" 10847 "max\t@{%2, %1, %0|%0, %1, %2@}" 10848 [@dots{}]) 10849@end smallexample 10850 10851The result of the @code{define_subst} usage would look like the following: 10852 10853@smallexample 10854(define_insn "maxsi_noclobber" 10855 [(set (match_operand:SI 0 "register_operand" "=r") 10856 (max:SI 10857 (match_operand:SI 1 "register_operand" "r") 10858 (match_operand:SI 2 "register_operand" "r")))] 10859 "" 10860 "max\t@{%2, %1, %0|%0, %1, %2@}" 10861 [@dots{}]) 10862(define_insn "maxsi_clobber" 10863 [(set (match_operand:SI 0 "register_operand" "=r") 10864 (max:SI 10865 (match_operand:SI 1 "register_operand" "r") 10866 (match_operand:SI 2 "register_operand" "r"))) 10867 (clobber (reg:CC FLAGS_REG))] 10868 "" 10869 "max\t@{%2, %1, %0|%0, %1, %2@}" 10870 [@dots{}]) 10871@end smallexample 10872 10873@node Define Subst Pattern Matching 10874@subsection Pattern Matching in @code{define_subst} 10875@cindex define_subst 10876 10877All expressions, allowed in @code{define_insn} or @code{define_expand}, 10878are allowed in the input-template of @code{define_subst}, except 10879@code{match_par_dup}, @code{match_scratch}, @code{match_parallel}. The 10880meanings of expressions in the input-template were changed: 10881 10882@code{match_operand} matches any expression (possibly, a subtree in 10883RTL-template), if modes of the @code{match_operand} and this expression 10884are the same, or mode of the @code{match_operand} is @code{VOIDmode}, or 10885this expression is @code{match_dup}, @code{match_op_dup}. If the 10886expression is @code{match_operand} too, and predicate of 10887@code{match_operand} from the input pattern is not empty, then the 10888predicates are compared. That can be used for more accurate filtering 10889of accepted RTL-templates. 10890 10891@code{match_operator} matches common operators (like @code{plus}, 10892@code{minus}), @code{unspec}, @code{unspec_volatile} operators and 10893@code{match_operator}s from the original pattern if the modes match and 10894@code{match_operator} from the input pattern has the same number of 10895operands as the operator from the original pattern. 10896 10897@node Define Subst Output Template 10898@subsection Generation of output template in @code{define_subst} 10899@cindex define_subst 10900 10901If all necessary checks for @code{define_subst} application pass, a new 10902RTL-pattern, based on the output-template, is created to replace the old 10903template. Like in input-patterns, meanings of some RTL expressions are 10904changed when they are used in output-patterns of a @code{define_subst}. 10905Thus, @code{match_dup} is used for copying the whole expression from the 10906original pattern, which matched corresponding @code{match_operand} from 10907the input pattern. 10908 10909@code{match_dup N} is used in the output template to be replaced with 10910the expression from the original pattern, which matched 10911@code{match_operand N} from the input pattern. As a consequence, 10912@code{match_dup} cannot be used to point to @code{match_operand}s from 10913the output pattern, it should always refer to a @code{match_operand} 10914from the input pattern. If a @code{match_dup N} occurs more than once 10915in the output template, its first occurrence is replaced with the 10916expression from the original pattern, and the subsequent expressions 10917are replaced with @code{match_dup N}, i.e., a reference to the first 10918expression. 10919 10920In the output template one can refer to the expressions from the 10921original pattern and create new ones. For instance, some operands could 10922be added by means of standard @code{match_operand}. 10923 10924After replacing @code{match_dup} with some RTL-subtree from the original 10925pattern, it could happen that several @code{match_operand}s in the 10926output pattern have the same indexes. It is unknown, how many and what 10927indexes would be used in the expression which would replace 10928@code{match_dup}, so such conflicts in indexes are inevitable. To 10929overcome this issue, @code{match_operands} and @code{match_operators}, 10930which were introduced into the output pattern, are renumerated when all 10931@code{match_dup}s are replaced. 10932 10933Number of alternatives in @code{match_operand}s introduced into the 10934output template @code{M} could differ from the number of alternatives in 10935the original pattern @code{N}, so in the resultant pattern there would 10936be @code{N*M} alternatives. Thus, constraints from the original pattern 10937would be duplicated @code{N} times, constraints from the output pattern 10938would be duplicated @code{M} times, producing all possible combinations. 10939@end ifset 10940 10941@ifset INTERNALS 10942@node Constant Definitions 10943@section Constant Definitions 10944@cindex constant definitions 10945@findex define_constants 10946 10947Using literal constants inside instruction patterns reduces legibility and 10948can be a maintenance problem. 10949 10950To overcome this problem, you may use the @code{define_constants} 10951expression. It contains a vector of name-value pairs. From that 10952point on, wherever any of the names appears in the MD file, it is as 10953if the corresponding value had been written instead. You may use 10954@code{define_constants} multiple times; each appearance adds more 10955constants to the table. It is an error to redefine a constant with 10956a different value. 10957 10958To come back to the a29k load multiple example, instead of 10959 10960@smallexample 10961(define_insn "" 10962 [(match_parallel 0 "load_multiple_operation" 10963 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 10964 (match_operand:SI 2 "memory_operand" "m")) 10965 (use (reg:SI 179)) 10966 (clobber (reg:SI 179))])] 10967 "" 10968 "loadm 0,0,%1,%2") 10969@end smallexample 10970 10971You could write: 10972 10973@smallexample 10974(define_constants [ 10975 (R_BP 177) 10976 (R_FC 178) 10977 (R_CR 179) 10978 (R_Q 180) 10979]) 10980 10981(define_insn "" 10982 [(match_parallel 0 "load_multiple_operation" 10983 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 10984 (match_operand:SI 2 "memory_operand" "m")) 10985 (use (reg:SI R_CR)) 10986 (clobber (reg:SI R_CR))])] 10987 "" 10988 "loadm 0,0,%1,%2") 10989@end smallexample 10990 10991The constants that are defined with a define_constant are also output 10992in the insn-codes.h header file as #defines. 10993 10994@cindex enumerations 10995@findex define_c_enum 10996You can also use the machine description file to define enumerations. 10997Like the constants defined by @code{define_constant}, these enumerations 10998are visible to both the machine description file and the main C code. 10999 11000The syntax is as follows: 11001 11002@smallexample 11003(define_c_enum "@var{name}" [ 11004 @var{value0} 11005 @var{value1} 11006 @dots{} 11007 @var{valuen} 11008]) 11009@end smallexample 11010 11011This definition causes the equivalent of the following C code to appear 11012in @file{insn-constants.h}: 11013 11014@smallexample 11015enum @var{name} @{ 11016 @var{value0} = 0, 11017 @var{value1} = 1, 11018 @dots{} 11019 @var{valuen} = @var{n} 11020@}; 11021#define NUM_@var{cname}_VALUES (@var{n} + 1) 11022@end smallexample 11023 11024where @var{cname} is the capitalized form of @var{name}. 11025It also makes each @var{valuei} available in the machine description 11026file, just as if it had been declared with: 11027 11028@smallexample 11029(define_constants [(@var{valuei} @var{i})]) 11030@end smallexample 11031 11032Each @var{valuei} is usually an upper-case identifier and usually 11033begins with @var{cname}. 11034 11035You can split the enumeration definition into as many statements as 11036you like. The above example is directly equivalent to: 11037 11038@smallexample 11039(define_c_enum "@var{name}" [@var{value0}]) 11040(define_c_enum "@var{name}" [@var{value1}]) 11041@dots{} 11042(define_c_enum "@var{name}" [@var{valuen}]) 11043@end smallexample 11044 11045Splitting the enumeration helps to improve the modularity of each 11046individual @code{.md} file. For example, if a port defines its 11047synchronization instructions in a separate @file{sync.md} file, 11048it is convenient to define all synchronization-specific enumeration 11049values in @file{sync.md} rather than in the main @file{.md} file. 11050 11051Some enumeration names have special significance to GCC: 11052 11053@table @code 11054@item unspecv 11055@findex unspec_volatile 11056If an enumeration called @code{unspecv} is defined, GCC will use it 11057when printing out @code{unspec_volatile} expressions. For example: 11058 11059@smallexample 11060(define_c_enum "unspecv" [ 11061 UNSPECV_BLOCKAGE 11062]) 11063@end smallexample 11064 11065causes GCC to print @samp{(unspec_volatile @dots{} 0)} as: 11066 11067@smallexample 11068(unspec_volatile ... UNSPECV_BLOCKAGE) 11069@end smallexample 11070 11071@item unspec 11072@findex unspec 11073If an enumeration called @code{unspec} is defined, GCC will use 11074it when printing out @code{unspec} expressions. GCC will also use 11075it when printing out @code{unspec_volatile} expressions unless an 11076@code{unspecv} enumeration is also defined. You can therefore 11077decide whether to keep separate enumerations for volatile and 11078non-volatile expressions or whether to use the same enumeration 11079for both. 11080@end table 11081 11082@findex define_enum 11083@anchor{define_enum} 11084Another way of defining an enumeration is to use @code{define_enum}: 11085 11086@smallexample 11087(define_enum "@var{name}" [ 11088 @var{value0} 11089 @var{value1} 11090 @dots{} 11091 @var{valuen} 11092]) 11093@end smallexample 11094 11095This directive implies: 11096 11097@smallexample 11098(define_c_enum "@var{name}" [ 11099 @var{cname}_@var{cvalue0} 11100 @var{cname}_@var{cvalue1} 11101 @dots{} 11102 @var{cname}_@var{cvaluen} 11103]) 11104@end smallexample 11105 11106@findex define_enum_attr 11107where @var{cvaluei} is the capitalized form of @var{valuei}. 11108However, unlike @code{define_c_enum}, the enumerations defined 11109by @code{define_enum} can be used in attribute specifications 11110(@pxref{define_enum_attr}). 11111@end ifset 11112@ifset INTERNALS 11113@node Iterators 11114@section Iterators 11115@cindex iterators in @file{.md} files 11116 11117Ports often need to define similar patterns for more than one machine 11118mode or for more than one rtx code. GCC provides some simple iterator 11119facilities to make this process easier. 11120 11121@menu 11122* Mode Iterators:: Generating variations of patterns for different modes. 11123* Code Iterators:: Doing the same for codes. 11124* Int Iterators:: Doing the same for integers. 11125* Subst Iterators:: Generating variations of patterns for define_subst. 11126* Parameterized Names:: Specifying iterator values in C++ code. 11127@end menu 11128 11129@node Mode Iterators 11130@subsection Mode Iterators 11131@cindex mode iterators in @file{.md} files 11132 11133Ports often need to define similar patterns for two or more different modes. 11134For example: 11135 11136@itemize @bullet 11137@item 11138If a processor has hardware support for both single and double 11139floating-point arithmetic, the @code{SFmode} patterns tend to be 11140very similar to the @code{DFmode} ones. 11141 11142@item 11143If a port uses @code{SImode} pointers in one configuration and 11144@code{DImode} pointers in another, it will usually have very similar 11145@code{SImode} and @code{DImode} patterns for manipulating pointers. 11146@end itemize 11147 11148Mode iterators allow several patterns to be instantiated from one 11149@file{.md} file template. They can be used with any type of 11150rtx-based construct, such as a @code{define_insn}, 11151@code{define_split}, or @code{define_peephole2}. 11152 11153@menu 11154* Defining Mode Iterators:: Defining a new mode iterator. 11155* Substitutions:: Combining mode iterators with substitutions 11156* Examples:: Examples 11157@end menu 11158 11159@node Defining Mode Iterators 11160@subsubsection Defining Mode Iterators 11161@findex define_mode_iterator 11162 11163The syntax for defining a mode iterator is: 11164 11165@smallexample 11166(define_mode_iterator @var{name} [(@var{mode1} "@var{cond1}") @dots{} (@var{moden} "@var{condn}")]) 11167@end smallexample 11168 11169This allows subsequent @file{.md} file constructs to use the mode suffix 11170@code{:@var{name}}. Every construct that does so will be expanded 11171@var{n} times, once with every use of @code{:@var{name}} replaced by 11172@code{:@var{mode1}}, once with every use replaced by @code{:@var{mode2}}, 11173and so on. In the expansion for a particular @var{modei}, every 11174C condition will also require that @var{condi} be true. 11175 11176For example: 11177 11178@smallexample 11179(define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")]) 11180@end smallexample 11181 11182defines a new mode suffix @code{:P}. Every construct that uses 11183@code{:P} will be expanded twice, once with every @code{:P} replaced 11184by @code{:SI} and once with every @code{:P} replaced by @code{:DI}. 11185The @code{:SI} version will only apply if @code{Pmode == SImode} and 11186the @code{:DI} version will only apply if @code{Pmode == DImode}. 11187 11188As with other @file{.md} conditions, an empty string is treated 11189as ``always true''. @code{(@var{mode} "")} can also be abbreviated 11190to @code{@var{mode}}. For example: 11191 11192@smallexample 11193(define_mode_iterator GPR [SI (DI "TARGET_64BIT")]) 11194@end smallexample 11195 11196means that the @code{:DI} expansion only applies if @code{TARGET_64BIT} 11197but that the @code{:SI} expansion has no such constraint. 11198 11199Iterators are applied in the order they are defined. This can be 11200significant if two iterators are used in a construct that requires 11201substitutions. @xref{Substitutions}. 11202 11203@node Substitutions 11204@subsubsection Substitution in Mode Iterators 11205@findex define_mode_attr 11206 11207If an @file{.md} file construct uses mode iterators, each version of the 11208construct will often need slightly different strings or modes. For 11209example: 11210 11211@itemize @bullet 11212@item 11213When a @code{define_expand} defines several @code{add@var{m}3} patterns 11214(@pxref{Standard Names}), each expander will need to use the 11215appropriate mode name for @var{m}. 11216 11217@item 11218When a @code{define_insn} defines several instruction patterns, 11219each instruction will often use a different assembler mnemonic. 11220 11221@item 11222When a @code{define_insn} requires operands with different modes, 11223using an iterator for one of the operand modes usually requires a specific 11224mode for the other operand(s). 11225@end itemize 11226 11227GCC supports such variations through a system of ``mode attributes''. 11228There are two standard attributes: @code{mode}, which is the name of 11229the mode in lower case, and @code{MODE}, which is the same thing in 11230upper case. You can define other attributes using: 11231 11232@smallexample 11233(define_mode_attr @var{name} [(@var{mode1} "@var{value1}") @dots{} (@var{moden} "@var{valuen}")]) 11234@end smallexample 11235 11236where @var{name} is the name of the attribute and @var{valuei} 11237is the value associated with @var{modei}. 11238 11239When GCC replaces some @var{:iterator} with @var{:mode}, it will scan 11240each string and mode in the pattern for sequences of the form 11241@code{<@var{iterator}:@var{attr}>}, where @var{attr} is the name of a 11242mode attribute. If the attribute is defined for @var{mode}, the whole 11243@code{<@dots{}>} sequence will be replaced by the appropriate attribute 11244value. 11245 11246For example, suppose an @file{.md} file has: 11247 11248@smallexample 11249(define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")]) 11250(define_mode_attr load [(SI "lw") (DI "ld")]) 11251@end smallexample 11252 11253If one of the patterns that uses @code{:P} contains the string 11254@code{"<P:load>\t%0,%1"}, the @code{SI} version of that pattern 11255will use @code{"lw\t%0,%1"} and the @code{DI} version will use 11256@code{"ld\t%0,%1"}. 11257 11258Here is an example of using an attribute for a mode: 11259 11260@smallexample 11261(define_mode_iterator LONG [SI DI]) 11262(define_mode_attr SHORT [(SI "HI") (DI "SI")]) 11263(define_insn @dots{} 11264 (sign_extend:LONG (match_operand:<LONG:SHORT> @dots{})) @dots{}) 11265@end smallexample 11266 11267The @code{@var{iterator}:} prefix may be omitted, in which case the 11268substitution will be attempted for every iterator expansion. 11269 11270@node Examples 11271@subsubsection Mode Iterator Examples 11272 11273Here is an example from the MIPS port. It defines the following 11274modes and attributes (among others): 11275 11276@smallexample 11277(define_mode_iterator GPR [SI (DI "TARGET_64BIT")]) 11278(define_mode_attr d [(SI "") (DI "d")]) 11279@end smallexample 11280 11281and uses the following template to define both @code{subsi3} 11282and @code{subdi3}: 11283 11284@smallexample 11285(define_insn "sub<mode>3" 11286 [(set (match_operand:GPR 0 "register_operand" "=d") 11287 (minus:GPR (match_operand:GPR 1 "register_operand" "d") 11288 (match_operand:GPR 2 "register_operand" "d")))] 11289 "" 11290 "<d>subu\t%0,%1,%2" 11291 [(set_attr "type" "arith") 11292 (set_attr "mode" "<MODE>")]) 11293@end smallexample 11294 11295This is exactly equivalent to: 11296 11297@smallexample 11298(define_insn "subsi3" 11299 [(set (match_operand:SI 0 "register_operand" "=d") 11300 (minus:SI (match_operand:SI 1 "register_operand" "d") 11301 (match_operand:SI 2 "register_operand" "d")))] 11302 "" 11303 "subu\t%0,%1,%2" 11304 [(set_attr "type" "arith") 11305 (set_attr "mode" "SI")]) 11306 11307(define_insn "subdi3" 11308 [(set (match_operand:DI 0 "register_operand" "=d") 11309 (minus:DI (match_operand:DI 1 "register_operand" "d") 11310 (match_operand:DI 2 "register_operand" "d")))] 11311 "" 11312 "dsubu\t%0,%1,%2" 11313 [(set_attr "type" "arith") 11314 (set_attr "mode" "DI")]) 11315@end smallexample 11316 11317@node Code Iterators 11318@subsection Code Iterators 11319@cindex code iterators in @file{.md} files 11320@findex define_code_iterator 11321@findex define_code_attr 11322 11323Code iterators operate in a similar way to mode iterators. @xref{Mode Iterators}. 11324 11325The construct: 11326 11327@smallexample 11328(define_code_iterator @var{name} [(@var{code1} "@var{cond1}") @dots{} (@var{coden} "@var{condn}")]) 11329@end smallexample 11330 11331defines a pseudo rtx code @var{name} that can be instantiated as 11332@var{codei} if condition @var{condi} is true. Each @var{codei} 11333must have the same rtx format. @xref{RTL Classes}. 11334 11335As with mode iterators, each pattern that uses @var{name} will be 11336expanded @var{n} times, once with all uses of @var{name} replaced by 11337@var{code1}, once with all uses replaced by @var{code2}, and so on. 11338@xref{Defining Mode Iterators}. 11339 11340It is possible to define attributes for codes as well as for modes. 11341There are two standard code attributes: @code{code}, the name of the 11342code in lower case, and @code{CODE}, the name of the code in upper case. 11343Other attributes are defined using: 11344 11345@smallexample 11346(define_code_attr @var{name} [(@var{code1} "@var{value1}") @dots{} (@var{coden} "@var{valuen}")]) 11347@end smallexample 11348 11349Instruction patterns can use code attributes as rtx codes, which can be 11350useful if two sets of codes act in tandem. For example, the following 11351@code{define_insn} defines two patterns, one calculating a signed absolute 11352difference and another calculating an unsigned absolute difference: 11353 11354@smallexample 11355(define_code_iterator any_max [smax umax]) 11356(define_code_attr paired_min [(smax "smin") (umax "umin")]) 11357(define_insn @dots{} 11358 [(set (match_operand:SI 0 @dots{}) 11359 (minus:SI (any_max:SI (match_operand:SI 1 @dots{}) 11360 (match_operand:SI 2 @dots{})) 11361 (<paired_min>:SI (match_dup 1) (match_dup 2))))] 11362 @dots{}) 11363@end smallexample 11364 11365The signed version of the instruction uses @code{smax} and @code{smin} 11366while the unsigned version uses @code{umax} and @code{umin}. There 11367are no versions that pair @code{smax} with @code{umin} or @code{umax} 11368with @code{smin}. 11369 11370Here's an example of code iterators in action, taken from the MIPS port: 11371 11372@smallexample 11373(define_code_iterator any_cond [unordered ordered unlt unge uneq ltgt unle ungt 11374 eq ne gt ge lt le gtu geu ltu leu]) 11375 11376(define_expand "b<code>" 11377 [(set (pc) 11378 (if_then_else (any_cond:CC (cc0) 11379 (const_int 0)) 11380 (label_ref (match_operand 0 "")) 11381 (pc)))] 11382 "" 11383@{ 11384 gen_conditional_branch (operands, <CODE>); 11385 DONE; 11386@}) 11387@end smallexample 11388 11389This is equivalent to: 11390 11391@smallexample 11392(define_expand "bunordered" 11393 [(set (pc) 11394 (if_then_else (unordered:CC (cc0) 11395 (const_int 0)) 11396 (label_ref (match_operand 0 "")) 11397 (pc)))] 11398 "" 11399@{ 11400 gen_conditional_branch (operands, UNORDERED); 11401 DONE; 11402@}) 11403 11404(define_expand "bordered" 11405 [(set (pc) 11406 (if_then_else (ordered:CC (cc0) 11407 (const_int 0)) 11408 (label_ref (match_operand 0 "")) 11409 (pc)))] 11410 "" 11411@{ 11412 gen_conditional_branch (operands, ORDERED); 11413 DONE; 11414@}) 11415 11416@dots{} 11417@end smallexample 11418 11419@node Int Iterators 11420@subsection Int Iterators 11421@cindex int iterators in @file{.md} files 11422@findex define_int_iterator 11423@findex define_int_attr 11424 11425Int iterators operate in a similar way to code iterators. @xref{Code Iterators}. 11426 11427The construct: 11428 11429@smallexample 11430(define_int_iterator @var{name} [(@var{int1} "@var{cond1}") @dots{} (@var{intn} "@var{condn}")]) 11431@end smallexample 11432 11433defines a pseudo integer constant @var{name} that can be instantiated as 11434@var{inti} if condition @var{condi} is true. Each @var{int} must have the 11435same rtx format. @xref{RTL Classes}. Int iterators can appear in only 11436those rtx fields that have 'i', 'n', 'w', or 'p' as the specifier. This 11437means that each @var{int} has to be a constant defined using define_constant 11438or define_c_enum. 11439 11440As with mode and code iterators, each pattern that uses @var{name} will be 11441expanded @var{n} times, once with all uses of @var{name} replaced by 11442@var{int1}, once with all uses replaced by @var{int2}, and so on. 11443@xref{Defining Mode Iterators}. 11444 11445It is possible to define attributes for ints as well as for codes and modes. 11446Attributes are defined using: 11447 11448@smallexample 11449(define_int_attr @var{name} [(@var{int1} "@var{value1}") @dots{} (@var{intn} "@var{valuen}")]) 11450@end smallexample 11451 11452Here's an example of int iterators in action, taken from the ARM port: 11453 11454@smallexample 11455(define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG]) 11456 11457(define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")]) 11458 11459(define_insn "neon_vq<absneg><mode>" 11460 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 11461 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 11462 (match_operand:SI 2 "immediate_operand" "i")] 11463 QABSNEG))] 11464 "TARGET_NEON" 11465 "vq<absneg>.<V_s_elem>\t%<V_reg>0, %<V_reg>1" 11466 [(set_attr "type" "neon_vqneg_vqabs")] 11467) 11468 11469@end smallexample 11470 11471This is equivalent to: 11472 11473@smallexample 11474(define_insn "neon_vqabs<mode>" 11475 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 11476 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 11477 (match_operand:SI 2 "immediate_operand" "i")] 11478 UNSPEC_VQABS))] 11479 "TARGET_NEON" 11480 "vqabs.<V_s_elem>\t%<V_reg>0, %<V_reg>1" 11481 [(set_attr "type" "neon_vqneg_vqabs")] 11482) 11483 11484(define_insn "neon_vqneg<mode>" 11485 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 11486 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 11487 (match_operand:SI 2 "immediate_operand" "i")] 11488 UNSPEC_VQNEG))] 11489 "TARGET_NEON" 11490 "vqneg.<V_s_elem>\t%<V_reg>0, %<V_reg>1" 11491 [(set_attr "type" "neon_vqneg_vqabs")] 11492) 11493 11494@end smallexample 11495 11496@node Subst Iterators 11497@subsection Subst Iterators 11498@cindex subst iterators in @file{.md} files 11499@findex define_subst 11500@findex define_subst_attr 11501 11502Subst iterators are special type of iterators with the following 11503restrictions: they could not be declared explicitly, they always have 11504only two values, and they do not have explicit dedicated name. 11505Subst-iterators are triggered only when corresponding subst-attribute is 11506used in RTL-pattern. 11507 11508Subst iterators transform templates in the following way: the templates 11509are duplicated, the subst-attributes in these templates are replaced 11510with the corresponding values, and a new attribute is implicitly added 11511to the given @code{define_insn}/@code{define_expand}. The name of the 11512added attribute matches the name of @code{define_subst}. Such 11513attributes are declared implicitly, and it is not allowed to have a 11514@code{define_attr} named as a @code{define_subst}. 11515 11516Each subst iterator is linked to a @code{define_subst}. It is declared 11517implicitly by the first appearance of the corresponding 11518@code{define_subst_attr}, and it is not allowed to define it explicitly. 11519 11520Declarations of subst-attributes have the following syntax: 11521 11522@findex define_subst_attr 11523@smallexample 11524(define_subst_attr "@var{name}" 11525 "@var{subst-name}" 11526 "@var{no-subst-value}" 11527 "@var{subst-applied-value}") 11528@end smallexample 11529 11530@var{name} is a string with which the given subst-attribute could be 11531referred to. 11532 11533@var{subst-name} shows which @code{define_subst} should be applied to an 11534RTL-template if the given subst-attribute is present in the 11535RTL-template. 11536 11537@var{no-subst-value} is a value with which subst-attribute would be 11538replaced in the first copy of the original RTL-template. 11539 11540@var{subst-applied-value} is a value with which subst-attribute would be 11541replaced in the second copy of the original RTL-template. 11542 11543@node Parameterized Names 11544@subsection Parameterized Names 11545@cindex @samp{@@} in instruction pattern names 11546Ports sometimes need to apply iterators using C++ code, in order to 11547get the code or RTL pattern for a specific instruction. For example, 11548suppose we have the @samp{neon_vq<absneg><mode>} pattern given above: 11549 11550@smallexample 11551(define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG]) 11552 11553(define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")]) 11554 11555(define_insn "neon_vq<absneg><mode>" 11556 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 11557 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 11558 (match_operand:SI 2 "immediate_operand" "i")] 11559 QABSNEG))] 11560 @dots{} 11561) 11562@end smallexample 11563 11564A port might need to generate this pattern for a variable 11565@samp{QABSNEG} value and a variable @samp{VDQIW} mode. There are two 11566ways of doing this. The first is to build the rtx for the pattern 11567directly from C++ code; this is a valid technique and avoids any risk 11568of combinatorial explosion. The second is to prefix the instruction 11569name with the special character @samp{@@}, which tells GCC to generate 11570the four additional functions below. In each case, @var{name} is the 11571name of the instruction without the leading @samp{@@} character, 11572without the @samp{<@dots{}>} placeholders, and with any underscore 11573before a @samp{<@dots{}>} placeholder removed if keeping it would 11574lead to a double or trailing underscore. 11575 11576@table @samp 11577@item insn_code maybe_code_for_@var{name} (@var{i1}, @var{i2}, @dots{}) 11578See whether replacing the first @samp{<@dots{}>} placeholder with 11579iterator value @var{i1}, the second with iterator value @var{i2}, and 11580so on, gives a valid instruction. Return its code if so, otherwise 11581return @code{CODE_FOR_nothing}. 11582 11583@item insn_code code_for_@var{name} (@var{i1}, @var{i2}, @dots{}) 11584Same, but abort the compiler if the requested instruction does not exist. 11585 11586@item rtx maybe_gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{}) 11587Check for a valid instruction in the same way as 11588@code{maybe_code_for_@var{name}}. If the instruction exists, 11589generate an instance of it using the operand values given by @var{op0}, 11590@var{op1}, and so on, otherwise return null. 11591 11592@item rtx gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{}) 11593Same, but abort the compiler if the requested instruction does not exist, 11594or if the instruction generator invoked the @code{FAIL} macro. 11595@end table 11596 11597For example, changing the pattern above to: 11598 11599@smallexample 11600(define_insn "@@neon_vq<absneg><mode>" 11601 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 11602 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 11603 (match_operand:SI 2 "immediate_operand" "i")] 11604 QABSNEG))] 11605 @dots{} 11606) 11607@end smallexample 11608 11609would define the same patterns as before, but in addition would generate 11610the four functions below: 11611 11612@smallexample 11613insn_code maybe_code_for_neon_vq (int, machine_mode); 11614insn_code code_for_neon_vq (int, machine_mode); 11615rtx maybe_gen_neon_vq (int, machine_mode, rtx, rtx, rtx); 11616rtx gen_neon_vq (int, machine_mode, rtx, rtx, rtx); 11617@end smallexample 11618 11619Calling @samp{code_for_neon_vq (UNSPEC_VQABS, V8QImode)} 11620would then give @code{CODE_FOR_neon_vqabsv8qi}. 11621 11622It is possible to have multiple @samp{@@} patterns with the same 11623name and same types of iterator. For example: 11624 11625@smallexample 11626(define_insn "@@some_arithmetic_op<mode>" 11627 [(set (match_operand:INTEGER_MODES 0 "register_operand") @dots{})] 11628 @dots{} 11629) 11630 11631(define_insn "@@some_arithmetic_op<mode>" 11632 [(set (match_operand:FLOAT_MODES 0 "register_operand") @dots{})] 11633 @dots{} 11634) 11635@end smallexample 11636 11637would produce a single set of functions that handles both 11638@code{INTEGER_MODES} and @code{FLOAT_MODES}. 11639 11640It is also possible for these @samp{@@} patterns to have different 11641numbers of operands from each other. For example, patterns with 11642a binary rtl code might take three operands (one output and two inputs) 11643while patterns with a ternary rtl code might take four operands (one 11644output and three inputs). This combination would produce separate 11645@samp{maybe_gen_@var{name}} and @samp{gen_@var{name}} functions for 11646each operand count, but it would still produce a single 11647@samp{maybe_code_for_@var{name}} and a single @samp{code_for_@var{name}}. 11648 11649@end ifset 11650