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 2262@item Q 2263A memory address which uses a base register with a short offset 2264or with a index register with its scale. 2265 2266@item W 2267A memory address which uses a base register with a index register 2268with its scale. 2269@end table 2270 2271@ifset INTERNALS 2272The C-SKY back end supports a large set of additional constraints 2273that are only useful for instruction selection or splitting rather 2274than inline asm, such as constraints representing constant integer 2275ranges accepted by particular instruction encodings. 2276Refer to the source code for details. 2277@end ifset 2278 2279@item Epiphany---@file{config/epiphany/constraints.md} 2280@table @code 2281@item U16 2282An unsigned 16-bit constant. 2283 2284@item K 2285An unsigned 5-bit constant. 2286 2287@item L 2288A signed 11-bit constant. 2289 2290@item Cm1 2291A signed 11-bit constant added to @minus{}1. 2292Can only match when the @option{-m1reg-@var{reg}} option is active. 2293 2294@item Cl1 2295Left-shift of @minus{}1, i.e., a bit mask with a block of leading ones, the rest 2296being a block of trailing zeroes. 2297Can only match when the @option{-m1reg-@var{reg}} option is active. 2298 2299@item Cr1 2300Right-shift of @minus{}1, i.e., a bit mask with a trailing block of ones, the 2301rest being zeroes. Or to put it another way, one less than a power of two. 2302Can only match when the @option{-m1reg-@var{reg}} option is active. 2303 2304@item Cal 2305Constant for arithmetic/logical operations. 2306This is like @code{i}, except that for position independent code, 2307no symbols / expressions needing relocations are allowed. 2308 2309@item Csy 2310Symbolic constant for call/jump instruction. 2311 2312@item Rcs 2313The register class usable in short insns. This is a register class 2314constraint, and can thus drive register allocation. 2315This constraint won't match unless @option{-mprefer-short-insn-regs} is 2316in effect. 2317 2318@item Rsc 2319The the register class of registers that can be used to hold a 2320sibcall call address. I.e., a caller-saved register. 2321 2322@item Rct 2323Core control register class. 2324 2325@item Rgs 2326The register group usable in short insns. 2327This constraint does not use a register class, so that it only 2328passively matches suitable registers, and doesn't drive register allocation. 2329 2330@ifset INTERNALS 2331@item Car 2332Constant suitable for the addsi3_r pattern. This is a valid offset 2333For byte, halfword, or word addressing. 2334@end ifset 2335 2336@item Rra 2337Matches the return address if it can be replaced with the link register. 2338 2339@item Rcc 2340Matches the integer condition code register. 2341 2342@item Sra 2343Matches the return address if it is in a stack slot. 2344 2345@item Cfm 2346Matches control register values to switch fp mode, which are encapsulated in 2347@code{UNSPEC_FP_MODE}. 2348@end table 2349 2350@item FRV---@file{config/frv/frv.h} 2351@table @code 2352@item a 2353Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}). 2354 2355@item b 2356Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}). 2357 2358@item c 2359Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and 2360@code{icc0} to @code{icc3}). 2361 2362@item d 2363Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}). 2364 2365@item e 2366Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}). 2367Odd registers are excluded not in the class but through the use of a machine 2368mode larger than 4 bytes. 2369 2370@item f 2371Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}). 2372 2373@item h 2374Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}). 2375Odd registers are excluded not in the class but through the use of a machine 2376mode larger than 4 bytes. 2377 2378@item l 2379Register in the class @code{LR_REG} (the @code{lr} register). 2380 2381@item q 2382Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}). 2383Register numbers not divisible by 4 are excluded not in the class but through 2384the use of a machine mode larger than 8 bytes. 2385 2386@item t 2387Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}). 2388 2389@item u 2390Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}). 2391 2392@item v 2393Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}). 2394 2395@item w 2396Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}). 2397 2398@item x 2399Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}). 2400Register numbers not divisible by 4 are excluded not in the class but through 2401the use of a machine mode larger than 8 bytes. 2402 2403@item z 2404Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}). 2405 2406@item A 2407Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}). 2408 2409@item B 2410Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}). 2411 2412@item C 2413Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}). 2414 2415@item G 2416Floating point constant zero 2417 2418@item I 24196-bit signed integer constant 2420 2421@item J 242210-bit signed integer constant 2423 2424@item L 242516-bit signed integer constant 2426 2427@item M 242816-bit unsigned integer constant 2429 2430@item N 243112-bit signed integer constant that is negative---i.e.@: in the 2432range of @minus{}2048 to @minus{}1 2433 2434@item O 2435Constant zero 2436 2437@item P 243812-bit signed integer constant that is greater than zero---i.e.@: in the 2439range of 1 to 2047. 2440 2441@end table 2442 2443@item FT32---@file{config/ft32/constraints.md} 2444@table @code 2445@item A 2446An absolute address 2447 2448@item B 2449An offset address 2450 2451@item W 2452A register indirect memory operand 2453 2454@item e 2455An offset address. 2456 2457@item f 2458An offset address. 2459 2460@item O 2461The constant zero or one 2462 2463@item I 2464A 16-bit signed constant (@minus{}32768 @dots{} 32767) 2465 2466@item w 2467A bitfield mask suitable for bext or bins 2468 2469@item x 2470An inverted bitfield mask suitable for bext or bins 2471 2472@item L 2473A 16-bit unsigned constant, multiple of 4 (0 @dots{} 65532) 2474 2475@item S 2476A 20-bit signed constant (@minus{}524288 @dots{} 524287) 2477 2478@item b 2479A constant for a bitfield width (1 @dots{} 16) 2480 2481@item KA 2482A 10-bit signed constant (@minus{}512 @dots{} 511) 2483 2484@end table 2485 2486@item Hewlett-Packard PA-RISC---@file{config/pa/pa.h} 2487@table @code 2488@item a 2489General register 1 2490 2491@item f 2492Floating point register 2493 2494@item q 2495Shift amount register 2496 2497@item x 2498Floating point register (deprecated) 2499 2500@item y 2501Upper floating point register (32-bit), floating point register (64-bit) 2502 2503@item Z 2504Any register 2505 2506@item I 2507Signed 11-bit integer constant 2508 2509@item J 2510Signed 14-bit integer constant 2511 2512@item K 2513Integer constant that can be deposited with a @code{zdepi} instruction 2514 2515@item L 2516Signed 5-bit integer constant 2517 2518@item M 2519Integer constant 0 2520 2521@item N 2522Integer constant that can be loaded with a @code{ldil} instruction 2523 2524@item O 2525Integer constant whose value plus one is a power of 2 2526 2527@item P 2528Integer constant that can be used for @code{and} operations in @code{depi} 2529and @code{extru} instructions 2530 2531@item S 2532Integer constant 31 2533 2534@item U 2535Integer constant 63 2536 2537@item G 2538Floating-point constant 0.0 2539 2540@item A 2541A @code{lo_sum} data-linkage-table memory operand 2542 2543@item Q 2544A memory operand that can be used as the destination operand of an 2545integer store instruction 2546 2547@item R 2548A scaled or unscaled indexed memory operand 2549 2550@item T 2551A memory operand for floating-point loads and stores 2552 2553@item W 2554A register indirect memory operand 2555@end table 2556 2557@item Intel IA-64---@file{config/ia64/ia64.h} 2558@table @code 2559@item a 2560General register @code{r0} to @code{r3} for @code{addl} instruction 2561 2562@item b 2563Branch register 2564 2565@item c 2566Predicate register (@samp{c} as in ``conditional'') 2567 2568@item d 2569Application register residing in M-unit 2570 2571@item e 2572Application register residing in I-unit 2573 2574@item f 2575Floating-point register 2576 2577@item m 2578Memory operand. If used together with @samp{<} or @samp{>}, 2579the operand can have postincrement and postdecrement which 2580require printing with @samp{%Pn} on IA-64. 2581 2582@item G 2583Floating-point constant 0.0 or 1.0 2584 2585@item I 258614-bit signed integer constant 2587 2588@item J 258922-bit signed integer constant 2590 2591@item K 25928-bit signed integer constant for logical instructions 2593 2594@item L 25958-bit adjusted signed integer constant for compare pseudo-ops 2596 2597@item M 25986-bit unsigned integer constant for shift counts 2599 2600@item N 26019-bit signed integer constant for load and store postincrements 2602 2603@item O 2604The constant zero 2605 2606@item P 26070 or @minus{}1 for @code{dep} instruction 2608 2609@item Q 2610Non-volatile memory for floating-point loads and stores 2611 2612@item R 2613Integer constant in the range 1 to 4 for @code{shladd} instruction 2614 2615@item S 2616Memory operand except postincrement and postdecrement. This is 2617now roughly the same as @samp{m} when not used together with @samp{<} 2618or @samp{>}. 2619@end table 2620 2621@item M32C---@file{config/m32c/m32c.c} 2622@table @code 2623@item Rsp 2624@itemx Rfb 2625@itemx Rsb 2626@samp{$sp}, @samp{$fb}, @samp{$sb}. 2627 2628@item Rcr 2629Any control register, when they're 16 bits wide (nothing if control 2630registers are 24 bits wide) 2631 2632@item Rcl 2633Any control register, when they're 24 bits wide. 2634 2635@item R0w 2636@itemx R1w 2637@itemx R2w 2638@itemx R3w 2639$r0, $r1, $r2, $r3. 2640 2641@item R02 2642$r0 or $r2, or $r2r0 for 32 bit values. 2643 2644@item R13 2645$r1 or $r3, or $r3r1 for 32 bit values. 2646 2647@item Rdi 2648A register that can hold a 64 bit value. 2649 2650@item Rhl 2651$r0 or $r1 (registers with addressable high/low bytes) 2652 2653@item R23 2654$r2 or $r3 2655 2656@item Raa 2657Address registers 2658 2659@item Raw 2660Address registers when they're 16 bits wide. 2661 2662@item Ral 2663Address registers when they're 24 bits wide. 2664 2665@item Rqi 2666Registers that can hold QI values. 2667 2668@item Rad 2669Registers that can be used with displacements ($a0, $a1, $sb). 2670 2671@item Rsi 2672Registers that can hold 32 bit values. 2673 2674@item Rhi 2675Registers that can hold 16 bit values. 2676 2677@item Rhc 2678Registers chat can hold 16 bit values, including all control 2679registers. 2680 2681@item Rra 2682$r0 through R1, plus $a0 and $a1. 2683 2684@item Rfl 2685The flags register. 2686 2687@item Rmm 2688The memory-based pseudo-registers $mem0 through $mem15. 2689 2690@item Rpi 2691Registers that can hold pointers (16 bit registers for r8c, m16c; 24 2692bit registers for m32cm, m32c). 2693 2694@item Rpa 2695Matches multiple registers in a PARALLEL to form a larger register. 2696Used to match function return values. 2697 2698@item Is3 2699@minus{}8 @dots{} 7 2700 2701@item IS1 2702@minus{}128 @dots{} 127 2703 2704@item IS2 2705@minus{}32768 @dots{} 32767 2706 2707@item IU2 27080 @dots{} 65535 2709 2710@item In4 2711@minus{}8 @dots{} @minus{}1 or 1 @dots{} 8 2712 2713@item In5 2714@minus{}16 @dots{} @minus{}1 or 1 @dots{} 16 2715 2716@item In6 2717@minus{}32 @dots{} @minus{}1 or 1 @dots{} 32 2718 2719@item IM2 2720@minus{}65536 @dots{} @minus{}1 2721 2722@item Ilb 2723An 8 bit value with exactly one bit set. 2724 2725@item Ilw 2726A 16 bit value with exactly one bit set. 2727 2728@item Sd 2729The common src/dest memory addressing modes. 2730 2731@item Sa 2732Memory addressed using $a0 or $a1. 2733 2734@item Si 2735Memory addressed with immediate addresses. 2736 2737@item Ss 2738Memory addressed using the stack pointer ($sp). 2739 2740@item Sf 2741Memory addressed using the frame base register ($fb). 2742 2743@item Ss 2744Memory addressed using the small base register ($sb). 2745 2746@item S1 2747$r1h 2748@end table 2749 2750@item MicroBlaze---@file{config/microblaze/constraints.md} 2751@table @code 2752@item d 2753A general register (@code{r0} to @code{r31}). 2754 2755@item z 2756A status register (@code{rmsr}, @code{$fcc1} to @code{$fcc7}). 2757 2758@end table 2759 2760@item MIPS---@file{config/mips/constraints.md} 2761@table @code 2762@item d 2763A general-purpose register. This is equivalent to @code{r} unless 2764generating MIPS16 code, in which case the MIPS16 register set is used. 2765 2766@item f 2767A floating-point register (if available). 2768 2769@item h 2770Formerly the @code{hi} register. This constraint is no longer supported. 2771 2772@item l 2773The @code{lo} register. Use this register to store values that are 2774no bigger than a word. 2775 2776@item x 2777The concatenated @code{hi} and @code{lo} registers. Use this register 2778to store doubleword values. 2779 2780@item c 2781A register suitable for use in an indirect jump. This will always be 2782@code{$25} for @option{-mabicalls}. 2783 2784@item v 2785Register @code{$3}. Do not use this constraint in new code; 2786it is retained only for compatibility with glibc. 2787 2788@item y 2789Equivalent to @code{r}; retained for backwards compatibility. 2790 2791@item z 2792A floating-point condition code register. 2793 2794@item I 2795A signed 16-bit constant (for arithmetic instructions). 2796 2797@item J 2798Integer zero. 2799 2800@item K 2801An unsigned 16-bit constant (for logic instructions). 2802 2803@item L 2804A signed 32-bit constant in which the lower 16 bits are zero. 2805Such constants can be loaded using @code{lui}. 2806 2807@item M 2808A constant that cannot be loaded using @code{lui}, @code{addiu} 2809or @code{ori}. 2810 2811@item N 2812A constant in the range @minus{}65535 to @minus{}1 (inclusive). 2813 2814@item O 2815A signed 15-bit constant. 2816 2817@item P 2818A constant in the range 1 to 65535 (inclusive). 2819 2820@item G 2821Floating-point zero. 2822 2823@item R 2824An address that can be used in a non-macro load or store. 2825 2826@item ZC 2827A memory operand whose address is formed by a base register and offset 2828that is suitable for use in instructions with the same addressing mode 2829as @code{ll} and @code{sc}. 2830 2831@item ZD 2832An address suitable for a @code{prefetch} instruction, or for any other 2833instruction with the same addressing mode as @code{prefetch}. 2834@end table 2835 2836@item Motorola 680x0---@file{config/m68k/constraints.md} 2837@table @code 2838@item a 2839Address register 2840 2841@item d 2842Data register 2843 2844@item f 284568881 floating-point register, if available 2846 2847@item I 2848Integer in the range 1 to 8 2849 2850@item J 285116-bit signed number 2852 2853@item K 2854Signed number whose magnitude is greater than 0x80 2855 2856@item L 2857Integer in the range @minus{}8 to @minus{}1 2858 2859@item M 2860Signed number whose magnitude is greater than 0x100 2861 2862@item N 2863Range 24 to 31, rotatert:SI 8 to 1 expressed as rotate 2864 2865@item O 286616 (for rotate using swap) 2867 2868@item P 2869Range 8 to 15, rotatert:HI 8 to 1 expressed as rotate 2870 2871@item R 2872Numbers that mov3q can handle 2873 2874@item G 2875Floating point constant that is not a 68881 constant 2876 2877@item S 2878Operands that satisfy 'm' when -mpcrel is in effect 2879 2880@item T 2881Operands that satisfy 's' when -mpcrel is not in effect 2882 2883@item Q 2884Address register indirect addressing mode 2885 2886@item U 2887Register offset addressing 2888 2889@item W 2890const_call_operand 2891 2892@item Cs 2893symbol_ref or const 2894 2895@item Ci 2896const_int 2897 2898@item C0 2899const_int 0 2900 2901@item Cj 2902Range of signed numbers that don't fit in 16 bits 2903 2904@item Cmvq 2905Integers valid for mvq 2906 2907@item Capsw 2908Integers valid for a moveq followed by a swap 2909 2910@item Cmvz 2911Integers valid for mvz 2912 2913@item Cmvs 2914Integers valid for mvs 2915 2916@item Ap 2917push_operand 2918 2919@item Ac 2920Non-register operands allowed in clr 2921 2922@end table 2923 2924@item Moxie---@file{config/moxie/constraints.md} 2925@table @code 2926@item A 2927An absolute address 2928 2929@item B 2930An offset address 2931 2932@item W 2933A register indirect memory operand 2934 2935@item I 2936A constant in the range of 0 to 255. 2937 2938@item N 2939A constant in the range of 0 to @minus{}255. 2940 2941@end table 2942 2943@item MSP430--@file{config/msp430/constraints.md} 2944@table @code 2945 2946@item R12 2947Register R12. 2948 2949@item R13 2950Register R13. 2951 2952@item K 2953Integer constant 1. 2954 2955@item L 2956Integer constant -1^20..1^19. 2957 2958@item M 2959Integer constant 1-4. 2960 2961@item Ya 2962Memory references which do not require an extended MOVX instruction. 2963 2964@item Yl 2965Memory reference, labels only. 2966 2967@item Ys 2968Memory reference, stack only. 2969 2970@end table 2971 2972@item NDS32---@file{config/nds32/constraints.md} 2973@table @code 2974@item w 2975LOW register class $r0 to $r7 constraint for V3/V3M ISA. 2976@item l 2977LOW register class $r0 to $r7. 2978@item d 2979MIDDLE register class $r0 to $r11, $r16 to $r19. 2980@item h 2981HIGH register class $r12 to $r14, $r20 to $r31. 2982@item t 2983Temporary assist register $ta (i.e.@: $r15). 2984@item k 2985Stack register $sp. 2986@item Iu03 2987Unsigned immediate 3-bit value. 2988@item In03 2989Negative immediate 3-bit value in the range of @minus{}7--0. 2990@item Iu04 2991Unsigned immediate 4-bit value. 2992@item Is05 2993Signed immediate 5-bit value. 2994@item Iu05 2995Unsigned immediate 5-bit value. 2996@item In05 2997Negative immediate 5-bit value in the range of @minus{}31--0. 2998@item Ip05 2999Unsigned immediate 5-bit value for movpi45 instruction with range 16--47. 3000@item Iu06 3001Unsigned immediate 6-bit value constraint for addri36.sp instruction. 3002@item Iu08 3003Unsigned immediate 8-bit value. 3004@item Iu09 3005Unsigned immediate 9-bit value. 3006@item Is10 3007Signed immediate 10-bit value. 3008@item Is11 3009Signed immediate 11-bit value. 3010@item Is15 3011Signed immediate 15-bit value. 3012@item Iu15 3013Unsigned immediate 15-bit value. 3014@item Ic15 3015A constant which is not in the range of imm15u but ok for bclr instruction. 3016@item Ie15 3017A constant which is not in the range of imm15u but ok for bset instruction. 3018@item It15 3019A constant which is not in the range of imm15u but ok for btgl instruction. 3020@item Ii15 3021A constant whose compliment value is in the range of imm15u 3022and ok for bitci instruction. 3023@item Is16 3024Signed immediate 16-bit value. 3025@item Is17 3026Signed immediate 17-bit value. 3027@item Is19 3028Signed immediate 19-bit value. 3029@item Is20 3030Signed immediate 20-bit value. 3031@item Ihig 3032The immediate value that can be simply set high 20-bit. 3033@item Izeb 3034The immediate value 0xff. 3035@item Izeh 3036The immediate value 0xffff. 3037@item Ixls 3038The immediate value 0x01. 3039@item Ix11 3040The immediate value 0x7ff. 3041@item Ibms 3042The immediate value with power of 2. 3043@item Ifex 3044The immediate value with power of 2 minus 1. 3045@item U33 3046Memory constraint for 333 format. 3047@item U45 3048Memory constraint for 45 format. 3049@item U37 3050Memory constraint for 37 format. 3051@end table 3052 3053@item Nios II family---@file{config/nios2/constraints.md} 3054@table @code 3055 3056@item I 3057Integer that is valid as an immediate operand in an 3058instruction taking a signed 16-bit number. Range 3059@minus{}32768 to 32767. 3060 3061@item J 3062Integer that is valid as an immediate operand in an 3063instruction taking an unsigned 16-bit number. Range 30640 to 65535. 3065 3066@item K 3067Integer that is valid as an immediate operand in an 3068instruction taking only the upper 16-bits of a 306932-bit number. Range 32-bit numbers with the lower 307016-bits being 0. 3071 3072@item L 3073Integer that is valid as an immediate operand for a 3074shift instruction. Range 0 to 31. 3075 3076@item M 3077Integer that is valid as an immediate operand for 3078only the value 0. Can be used in conjunction with 3079the format modifier @code{z} to use @code{r0} 3080instead of @code{0} in the assembly output. 3081 3082@item N 3083Integer that is valid as an immediate operand for 3084a custom instruction opcode. Range 0 to 255. 3085 3086@item P 3087An immediate operand for R2 andchi/andci instructions. 3088 3089@item S 3090Matches immediates which are addresses in the small 3091data section and therefore can be added to @code{gp} 3092as a 16-bit immediate to re-create their 32-bit value. 3093 3094@item U 3095Matches constants suitable as an operand for the rdprs and 3096cache instructions. 3097 3098@item v 3099A memory operand suitable for Nios II R2 load/store 3100exclusive instructions. 3101 3102@item w 3103A memory operand suitable for load/store IO and cache 3104instructions. 3105 3106@ifset INTERNALS 3107@item T 3108A @code{const} wrapped @code{UNSPEC} expression, 3109representing a supported PIC or TLS relocation. 3110@end ifset 3111 3112@end table 3113 3114@item OpenRISC---@file{config/or1k/constraints.md} 3115@table @code 3116@item I 3117Integer that is valid as an immediate operand in an 3118instruction taking a signed 16-bit number. Range 3119@minus{}32768 to 32767. 3120 3121@item K 3122Integer that is valid as an immediate operand in an 3123instruction taking an unsigned 16-bit number. Range 31240 to 65535. 3125 3126@item M 3127Signed 16-bit constant shifted left 16 bits. (Used with @code{l.movhi}) 3128 3129@item O 3130Zero 3131 3132@ifset INTERNALS 3133@item c 3134Register usable for sibcalls. 3135@end ifset 3136 3137@end table 3138 3139@item PDP-11---@file{config/pdp11/constraints.md} 3140@table @code 3141@item a 3142Floating point registers AC0 through AC3. These can be loaded from/to 3143memory with a single instruction. 3144 3145@item d 3146Odd numbered general registers (R1, R3, R5). These are used for 314716-bit multiply operations. 3148 3149@item D 3150A memory reference that is encoded within the opcode, but not 3151auto-increment or auto-decrement. 3152 3153@item f 3154Any of the floating point registers (AC0 through AC5). 3155 3156@item G 3157Floating point constant 0. 3158 3159@item h 3160Floating point registers AC4 and AC5. These cannot be loaded from/to 3161memory with a single instruction. 3162 3163@item I 3164An integer constant that fits in 16 bits. 3165 3166@item J 3167An integer constant whose low order 16 bits are zero. 3168 3169@item K 3170An integer constant that does not meet the constraints for codes 3171@samp{I} or @samp{J}. 3172 3173@item L 3174The integer constant 1. 3175 3176@item M 3177The integer constant @minus{}1. 3178 3179@item N 3180The integer constant 0. 3181 3182@item O 3183Integer constants 0 through 3; shifts by these 3184amounts are handled as multiple single-bit shifts rather than a single 3185variable-length shift. 3186 3187@item Q 3188A memory reference which requires an additional word (address or 3189offset) after the opcode. 3190 3191@item R 3192A memory reference that is encoded within the opcode. 3193 3194@end table 3195 3196@item PowerPC and IBM RS6000---@file{config/rs6000/constraints.md} 3197@table @code 3198@item r 3199A general purpose register (GPR), @code{r0}@dots{}@code{r31}. 3200 3201@item b 3202A base register. Like @code{r}, but @code{r0} is not allowed, so 3203@code{r1}@dots{}@code{r31}. 3204 3205@item f 3206A floating point register (FPR), @code{f0}@dots{}@code{f31}. 3207 3208@item d 3209A floating point register. This is the same as @code{f} nowadays; 3210historically @code{f} was for single-precision and @code{d} was for 3211double-precision floating point. 3212 3213@item v 3214An Altivec vector register (VR), @code{v0}@dots{}@code{v31}. 3215 3216@item wa 3217A VSX register (VSR), @code{vs0}@dots{}@code{vs63}. This is either an 3218FPR (@code{vs0}@dots{}@code{vs31} are @code{f0}@dots{}@code{f31}) or a VR 3219(@code{vs32}@dots{}@code{vs63} are @code{v0}@dots{}@code{v31}). 3220 3221When using @code{wa}, you should use the @code{%x} output modifier, so that 3222the correct register number is printed. For example: 3223 3224@smallexample 3225asm ("xvadddp %x0,%x1,%x2" 3226 : "=wa" (v1) 3227 : "wa" (v2), "wa" (v3)); 3228@end smallexample 3229 3230You should not use @code{%x} for @code{v} operands: 3231 3232@smallexample 3233asm ("xsaddqp %0,%1,%2" 3234 : "=v" (v1) 3235 : "v" (v2), "v" (v3)); 3236@end smallexample 3237 3238@ifset INTERNALS 3239@item h 3240A special register (@code{vrsave}, @code{ctr}, or @code{lr}). 3241@end ifset 3242 3243@item c 3244The count register, @code{ctr}. 3245 3246@item l 3247The link register, @code{lr}. 3248 3249@item x 3250Condition register field 0, @code{cr0}. 3251 3252@item y 3253Any condition register field, @code{cr0}@dots{}@code{cr7}. 3254 3255@ifset INTERNALS 3256@item z 3257The carry bit, @code{XER[CA]}. 3258 3259@item we 3260Like @code{wa}, if @option{-mpower9-vector} and @option{-m64} are used; 3261otherwise, @code{NO_REGS}. 3262 3263@item wn 3264No register (@code{NO_REGS}). 3265 3266@item wr 3267Like @code{r}, if @option{-mpowerpc64} is used; otherwise, @code{NO_REGS}. 3268 3269@item wx 3270Like @code{d}, if @option{-mpowerpc-gfxopt} is used; otherwise, @code{NO_REGS}. 3271 3272@item wA 3273Like @code{b}, if @option{-mpowerpc64} is used; otherwise, @code{NO_REGS}. 3274 3275@item wB 3276Signed 5-bit constant integer that can be loaded into an Altivec register. 3277 3278@item wD 3279Int constant that is the element number of the 64-bit scalar in a vector. 3280 3281@item wE 3282Vector constant that can be loaded with the XXSPLTIB instruction. 3283 3284@item wF 3285Memory operand suitable for power8 GPR load fusion. 3286 3287@item wL 3288Int constant that is the element number mfvsrld accesses in a vector. 3289 3290@item wM 3291Match vector constant with all 1's if the XXLORC instruction is available. 3292 3293@item wO 3294Memory operand suitable for the ISA 3.0 vector d-form instructions. 3295 3296@item wQ 3297Memory operand suitable for the load/store quad instructions. 3298 3299@item wS 3300Vector constant that can be loaded with XXSPLTIB & sign extension. 3301 3302@item wY 3303A memory operand for a DS-form instruction. 3304 3305@item wZ 3306An indexed or indirect memory operand, ignoring the bottom 4 bits. 3307@end ifset 3308 3309@item I 3310A signed 16-bit constant. 3311 3312@item J 3313An unsigned 16-bit constant shifted left 16 bits (use @code{L} instead 3314for @code{SImode} constants). 3315 3316@item K 3317An unsigned 16-bit constant. 3318 3319@item L 3320A signed 16-bit constant shifted left 16 bits. 3321 3322@ifset INTERNALS 3323@item M 3324An integer constant greater than 31. 3325 3326@item N 3327An exact power of 2. 3328 3329@item O 3330The integer constant zero. 3331 3332@item P 3333A constant whose negation is a signed 16-bit constant. 3334@end ifset 3335 3336@item eI 3337A signed 34-bit integer constant if prefixed instructions are supported. 3338 3339@ifset INTERNALS 3340@item G 3341A floating point constant that can be loaded into a register with one 3342instruction per word. 3343 3344@item H 3345A floating point constant that can be loaded into a register using 3346three instructions. 3347@end ifset 3348 3349@item m 3350A memory operand. 3351Normally, @code{m} does not allow addresses that update the base register. 3352If the @code{<} or @code{>} constraint is also used, they are allowed and 3353therefore on PowerPC targets in that case it is only safe 3354to use @code{m<>} in an @code{asm} statement if that @code{asm} statement 3355accesses the operand exactly once. The @code{asm} statement must also 3356use @code{%U@var{<opno>}} as a placeholder for the ``update'' flag in the 3357corresponding load or store instruction. For example: 3358 3359@smallexample 3360asm ("st%U0 %1,%0" : "=m<>" (mem) : "r" (val)); 3361@end smallexample 3362 3363is correct but: 3364 3365@smallexample 3366asm ("st %1,%0" : "=m<>" (mem) : "r" (val)); 3367@end smallexample 3368 3369is not. 3370 3371@ifset INTERNALS 3372@item es 3373A ``stable'' memory operand; that is, one which does not include any 3374automodification of the base register. This used to be useful when 3375@code{m} allowed automodification of the base register, but as those 3376are now only allowed when @code{<} or @code{>} is used, @code{es} is 3377basically the same as @code{m} without @code{<} and @code{>}. 3378@end ifset 3379 3380@item Q 3381A memory operand addressed by just a base register. 3382 3383@ifset INTERNALS 3384@item Y 3385A memory operand for a DQ-form instruction. 3386@end ifset 3387 3388@item Z 3389A memory operand accessed with indexed or indirect addressing. 3390 3391@ifset INTERNALS 3392@item R 3393An AIX TOC entry. 3394@end ifset 3395 3396@item a 3397An indexed or indirect address. 3398 3399@ifset INTERNALS 3400@item U 3401A V.4 small data reference. 3402 3403@item W 3404A vector constant that does not require memory. 3405 3406@item j 3407The zero vector constant. 3408@end ifset 3409 3410@end table 3411 3412@item PRU---@file{config/pru/constraints.md} 3413@table @code 3414@item I 3415An unsigned 8-bit integer constant. 3416 3417@item J 3418An unsigned 16-bit integer constant. 3419 3420@item L 3421An unsigned 5-bit integer constant (for shift counts). 3422 3423@item T 3424A text segment (program memory) constant label. 3425 3426@item Z 3427Integer constant zero. 3428 3429@end table 3430 3431@item RL78---@file{config/rl78/constraints.md} 3432@table @code 3433 3434@item Int3 3435An integer constant in the range 1 @dots{} 7. 3436@item Int8 3437An integer constant in the range 0 @dots{} 255. 3438@item J 3439An integer constant in the range @minus{}255 @dots{} 0 3440@item K 3441The integer constant 1. 3442@item L 3443The integer constant -1. 3444@item M 3445The integer constant 0. 3446@item N 3447The integer constant 2. 3448@item O 3449The integer constant -2. 3450@item P 3451An integer constant in the range 1 @dots{} 15. 3452@item Qbi 3453The built-in compare types--eq, ne, gtu, ltu, geu, and leu. 3454@item Qsc 3455The synthetic compare types--gt, lt, ge, and le. 3456@item Wab 3457A memory reference with an absolute address. 3458@item Wbc 3459A memory reference using @code{BC} as a base register, with an optional offset. 3460@item Wca 3461A memory reference using @code{AX}, @code{BC}, @code{DE}, or @code{HL} for the address, for calls. 3462@item Wcv 3463A memory reference using any 16-bit register pair for the address, for calls. 3464@item Wd2 3465A memory reference using @code{DE} as a base register, with an optional offset. 3466@item Wde 3467A memory reference using @code{DE} as a base register, without any offset. 3468@item Wfr 3469Any memory reference to an address in the far address space. 3470@item Wh1 3471A memory reference using @code{HL} as a base register, with an optional one-byte offset. 3472@item Whb 3473A memory reference using @code{HL} as a base register, with @code{B} or @code{C} as the index register. 3474@item Whl 3475A memory reference using @code{HL} as a base register, without any offset. 3476@item Ws1 3477A memory reference using @code{SP} as a base register, with an optional one-byte offset. 3478@item Y 3479Any memory reference to an address in the near address space. 3480@item A 3481The @code{AX} register. 3482@item B 3483The @code{BC} register. 3484@item D 3485The @code{DE} register. 3486@item R 3487@code{A} through @code{L} registers. 3488@item S 3489The @code{SP} register. 3490@item T 3491The @code{HL} register. 3492@item Z08W 3493The 16-bit @code{R8} register. 3494@item Z10W 3495The 16-bit @code{R10} register. 3496@item Zint 3497The registers reserved for interrupts (@code{R24} to @code{R31}). 3498@item a 3499The @code{A} register. 3500@item b 3501The @code{B} register. 3502@item c 3503The @code{C} register. 3504@item d 3505The @code{D} register. 3506@item e 3507The @code{E} register. 3508@item h 3509The @code{H} register. 3510@item l 3511The @code{L} register. 3512@item v 3513The virtual registers. 3514@item w 3515The @code{PSW} register. 3516@item x 3517The @code{X} register. 3518 3519@end table 3520 3521@item RISC-V---@file{config/riscv/constraints.md} 3522@table @code 3523 3524@item f 3525A floating-point register (if available). 3526 3527@item I 3528An I-type 12-bit signed immediate. 3529 3530@item J 3531Integer zero. 3532 3533@item K 3534A 5-bit unsigned immediate for CSR access instructions. 3535 3536@item A 3537An address that is held in a general-purpose register. 3538 3539@item S 3540A constraint that matches an absolute symbolic address. 3541 3542@end table 3543 3544@item RX---@file{config/rx/constraints.md} 3545@table @code 3546@item Q 3547An address which does not involve register indirect addressing or 3548pre/post increment/decrement addressing. 3549 3550@item Symbol 3551A symbol reference. 3552 3553@item Int08 3554A constant in the range @minus{}256 to 255, inclusive. 3555 3556@item Sint08 3557A constant in the range @minus{}128 to 127, inclusive. 3558 3559@item Sint16 3560A constant in the range @minus{}32768 to 32767, inclusive. 3561 3562@item Sint24 3563A constant in the range @minus{}8388608 to 8388607, inclusive. 3564 3565@item Uint04 3566A constant in the range 0 to 15, inclusive. 3567 3568@end table 3569 3570@item S/390 and zSeries---@file{config/s390/s390.h} 3571@table @code 3572@item a 3573Address register (general purpose register except r0) 3574 3575@item c 3576Condition code register 3577 3578@item d 3579Data register (arbitrary general purpose register) 3580 3581@item f 3582Floating-point register 3583 3584@item I 3585Unsigned 8-bit constant (0--255) 3586 3587@item J 3588Unsigned 12-bit constant (0--4095) 3589 3590@item K 3591Signed 16-bit constant (@minus{}32768--32767) 3592 3593@item L 3594Value appropriate as displacement. 3595@table @code 3596@item (0..4095) 3597for short displacement 3598@item (@minus{}524288..524287) 3599for long displacement 3600@end table 3601 3602@item M 3603Constant integer with a value of 0x7fffffff. 3604 3605@item N 3606Multiple letter constraint followed by 4 parameter letters. 3607@table @code 3608@item 0..9: 3609number of the part counting from most to least significant 3610@item H,Q: 3611mode of the part 3612@item D,S,H: 3613mode of the containing operand 3614@item 0,F: 3615value of the other parts (F---all bits set) 3616@end table 3617The constraint matches if the specified part of a constant 3618has a value different from its other parts. 3619 3620@item Q 3621Memory reference without index register and with short displacement. 3622 3623@item R 3624Memory reference with index register and short displacement. 3625 3626@item S 3627Memory reference without index register but with long displacement. 3628 3629@item T 3630Memory reference with index register and long displacement. 3631 3632@item U 3633Pointer with short displacement. 3634 3635@item W 3636Pointer with long displacement. 3637 3638@item Y 3639Shift count operand. 3640 3641@end table 3642 3643@need 1000 3644@item SPARC---@file{config/sparc/sparc.h} 3645@table @code 3646@item f 3647Floating-point register on the SPARC-V8 architecture and 3648lower floating-point register on the SPARC-V9 architecture. 3649 3650@item e 3651Floating-point register. It is equivalent to @samp{f} on the 3652SPARC-V8 architecture and contains both lower and upper 3653floating-point registers on the SPARC-V9 architecture. 3654 3655@item c 3656Floating-point condition code register. 3657 3658@item d 3659Lower floating-point register. It is only valid on the SPARC-V9 3660architecture when the Visual Instruction Set is available. 3661 3662@item b 3663Floating-point register. It is only valid on the SPARC-V9 architecture 3664when the Visual Instruction Set is available. 3665 3666@item h 366764-bit global or out register for the SPARC-V8+ architecture. 3668 3669@item C 3670The constant all-ones, for floating-point. 3671 3672@item A 3673Signed 5-bit constant 3674 3675@item D 3676A vector constant 3677 3678@item I 3679Signed 13-bit constant 3680 3681@item J 3682Zero 3683 3684@item K 368532-bit constant with the low 12 bits clear (a constant that can be 3686loaded with the @code{sethi} instruction) 3687 3688@item L 3689A constant in the range supported by @code{movcc} instructions (11-bit 3690signed immediate) 3691 3692@item M 3693A constant in the range supported by @code{movrcc} instructions (10-bit 3694signed immediate) 3695 3696@item N 3697Same as @samp{K}, except that it verifies that bits that are not in the 3698lower 32-bit range are all zero. Must be used instead of @samp{K} for 3699modes wider than @code{SImode} 3700 3701@item O 3702The constant 4096 3703 3704@item G 3705Floating-point zero 3706 3707@item H 3708Signed 13-bit constant, sign-extended to 32 or 64 bits 3709 3710@item P 3711The constant -1 3712 3713@item Q 3714Floating-point constant whose integral representation can 3715be moved into an integer register using a single sethi 3716instruction 3717 3718@item R 3719Floating-point constant whose integral representation can 3720be moved into an integer register using a single mov 3721instruction 3722 3723@item S 3724Floating-point constant whose integral representation can 3725be moved into an integer register using a high/lo_sum 3726instruction sequence 3727 3728@item T 3729Memory address aligned to an 8-byte boundary 3730 3731@item U 3732Even register 3733 3734@item W 3735Memory address for @samp{e} constraint registers 3736 3737@item w 3738Memory address with only a base register 3739 3740@item Y 3741Vector zero 3742 3743@end table 3744 3745@item TI C6X family---@file{config/c6x/constraints.md} 3746@table @code 3747@item a 3748Register file A (A0--A31). 3749 3750@item b 3751Register file B (B0--B31). 3752 3753@item A 3754Predicate registers in register file A (A0--A2 on C64X and 3755higher, A1 and A2 otherwise). 3756 3757@item B 3758Predicate registers in register file B (B0--B2). 3759 3760@item C 3761A call-used register in register file B (B0--B9, B16--B31). 3762 3763@item Da 3764Register file A, excluding predicate registers (A3--A31, 3765plus A0 if not C64X or higher). 3766 3767@item Db 3768Register file B, excluding predicate registers (B3--B31). 3769 3770@item Iu4 3771Integer constant in the range 0 @dots{} 15. 3772 3773@item Iu5 3774Integer constant in the range 0 @dots{} 31. 3775 3776@item In5 3777Integer constant in the range @minus{}31 @dots{} 0. 3778 3779@item Is5 3780Integer constant in the range @minus{}16 @dots{} 15. 3781 3782@item I5x 3783Integer constant that can be the operand of an ADDA or a SUBA insn. 3784 3785@item IuB 3786Integer constant in the range 0 @dots{} 65535. 3787 3788@item IsB 3789Integer constant in the range @minus{}32768 @dots{} 32767. 3790 3791@item IsC 3792Integer constant in the range @math{-2^{20}} @dots{} @math{2^{20} - 1}. 3793 3794@item Jc 3795Integer constant that is a valid mask for the clr instruction. 3796 3797@item Js 3798Integer constant that is a valid mask for the set instruction. 3799 3800@item Q 3801Memory location with A base register. 3802 3803@item R 3804Memory location with B base register. 3805 3806@ifset INTERNALS 3807@item S0 3808On C64x+ targets, a GP-relative small data reference. 3809 3810@item S1 3811Any kind of @code{SYMBOL_REF}, for use in a call address. 3812 3813@item Si 3814Any kind of immediate operand, unless it matches the S0 constraint. 3815 3816@item T 3817Memory location with B base register, but not using a long offset. 3818 3819@item W 3820A memory operand with an address that cannot be used in an unaligned access. 3821 3822@end ifset 3823@item Z 3824Register B14 (aka DP). 3825 3826@end table 3827 3828@item TILE-Gx---@file{config/tilegx/constraints.md} 3829@table @code 3830@item R00 3831@itemx R01 3832@itemx R02 3833@itemx R03 3834@itemx R04 3835@itemx R05 3836@itemx R06 3837@itemx R07 3838@itemx R08 3839@itemx R09 3840@itemx R10 3841Each of these represents a register constraint for an individual 3842register, from r0 to r10. 3843 3844@item I 3845Signed 8-bit integer constant. 3846 3847@item J 3848Signed 16-bit integer constant. 3849 3850@item K 3851Unsigned 16-bit integer constant. 3852 3853@item L 3854Integer constant that fits in one signed byte when incremented by one 3855(@minus{}129 @dots{} 126). 3856 3857@item m 3858Memory operand. If used together with @samp{<} or @samp{>}, the 3859operand can have postincrement which requires printing with @samp{%In} 3860and @samp{%in} on TILE-Gx. For example: 3861 3862@smallexample 3863asm ("st_add %I0,%1,%i0" : "=m<>" (*mem) : "r" (val)); 3864@end smallexample 3865 3866@item M 3867A bit mask suitable for the BFINS instruction. 3868 3869@item N 3870Integer constant that is a byte tiled out eight times. 3871 3872@item O 3873The integer zero constant. 3874 3875@item P 3876Integer constant that is a sign-extended byte tiled out as four shorts. 3877 3878@item Q 3879Integer constant that fits in one signed byte when incremented 3880(@minus{}129 @dots{} 126), but excluding -1. 3881 3882@item S 3883Integer constant that has all 1 bits consecutive and starting at bit 0. 3884 3885@item T 3886A 16-bit fragment of a got, tls, or pc-relative reference. 3887 3888@item U 3889Memory operand except postincrement. This is roughly the same as 3890@samp{m} when not used together with @samp{<} or @samp{>}. 3891 3892@item W 3893An 8-element vector constant with identical elements. 3894 3895@item Y 3896A 4-element vector constant with identical elements. 3897 3898@item Z0 3899The integer constant 0xffffffff. 3900 3901@item Z1 3902The integer constant 0xffffffff00000000. 3903 3904@end table 3905 3906@item TILEPro---@file{config/tilepro/constraints.md} 3907@table @code 3908@item R00 3909@itemx R01 3910@itemx R02 3911@itemx R03 3912@itemx R04 3913@itemx R05 3914@itemx R06 3915@itemx R07 3916@itemx R08 3917@itemx R09 3918@itemx R10 3919Each of these represents a register constraint for an individual 3920register, from r0 to r10. 3921 3922@item I 3923Signed 8-bit integer constant. 3924 3925@item J 3926Signed 16-bit integer constant. 3927 3928@item K 3929Nonzero integer constant with low 16 bits zero. 3930 3931@item L 3932Integer constant that fits in one signed byte when incremented by one 3933(@minus{}129 @dots{} 126). 3934 3935@item m 3936Memory operand. If used together with @samp{<} or @samp{>}, the 3937operand can have postincrement which requires printing with @samp{%In} 3938and @samp{%in} on TILEPro. For example: 3939 3940@smallexample 3941asm ("swadd %I0,%1,%i0" : "=m<>" (mem) : "r" (val)); 3942@end smallexample 3943 3944@item M 3945A bit mask suitable for the MM instruction. 3946 3947@item N 3948Integer constant that is a byte tiled out four times. 3949 3950@item O 3951The integer zero constant. 3952 3953@item P 3954Integer constant that is a sign-extended byte tiled out as two shorts. 3955 3956@item Q 3957Integer constant that fits in one signed byte when incremented 3958(@minus{}129 @dots{} 126), but excluding -1. 3959 3960@item T 3961A symbolic operand, or a 16-bit fragment of a got, tls, or pc-relative 3962reference. 3963 3964@item U 3965Memory operand except postincrement. This is roughly the same as 3966@samp{m} when not used together with @samp{<} or @samp{>}. 3967 3968@item W 3969A 4-element vector constant with identical elements. 3970 3971@item Y 3972A 2-element vector constant with identical elements. 3973 3974@end table 3975 3976@item Visium---@file{config/visium/constraints.md} 3977@table @code 3978@item b 3979EAM register @code{mdb} 3980 3981@item c 3982EAM register @code{mdc} 3983 3984@item f 3985Floating point register 3986 3987@ifset INTERNALS 3988@item k 3989Register for sibcall optimization 3990@end ifset 3991 3992@item l 3993General register, but not @code{r29}, @code{r30} and @code{r31} 3994 3995@item t 3996Register @code{r1} 3997 3998@item u 3999Register @code{r2} 4000 4001@item v 4002Register @code{r3} 4003 4004@item G 4005Floating-point constant 0.0 4006 4007@item J 4008Integer constant in the range 0 .. 65535 (16-bit immediate) 4009 4010@item K 4011Integer constant in the range 1 .. 31 (5-bit immediate) 4012 4013@item L 4014Integer constant in the range @minus{}65535 .. @minus{}1 (16-bit negative immediate) 4015 4016@item M 4017Integer constant @minus{}1 4018 4019@item O 4020Integer constant 0 4021 4022@item P 4023Integer constant 32 4024@end table 4025 4026@item x86 family---@file{config/i386/constraints.md} 4027@table @code 4028@item R 4029Legacy register---the eight integer registers available on all 4030i386 processors (@code{a}, @code{b}, @code{c}, @code{d}, 4031@code{si}, @code{di}, @code{bp}, @code{sp}). 4032 4033@item q 4034Any register accessible as @code{@var{r}l}. In 32-bit mode, @code{a}, 4035@code{b}, @code{c}, and @code{d}; in 64-bit mode, any integer register. 4036 4037@item Q 4038Any register accessible as @code{@var{r}h}: @code{a}, @code{b}, 4039@code{c}, and @code{d}. 4040 4041@ifset INTERNALS 4042@item l 4043Any register that can be used as the index in a base+index memory 4044access: that is, any general register except the stack pointer. 4045@end ifset 4046 4047@item a 4048The @code{a} register. 4049 4050@item b 4051The @code{b} register. 4052 4053@item c 4054The @code{c} register. 4055 4056@item d 4057The @code{d} register. 4058 4059@item S 4060The @code{si} register. 4061 4062@item D 4063The @code{di} register. 4064 4065@item A 4066The @code{a} and @code{d} registers. This class is used for instructions 4067that return double word results in the @code{ax:dx} register pair. Single 4068word values will be allocated either in @code{ax} or @code{dx}. 4069For example on i386 the following implements @code{rdtsc}: 4070 4071@smallexample 4072unsigned long long rdtsc (void) 4073@{ 4074 unsigned long long tick; 4075 __asm__ __volatile__("rdtsc":"=A"(tick)); 4076 return tick; 4077@} 4078@end smallexample 4079 4080This is not correct on x86-64 as it would allocate tick in either @code{ax} 4081or @code{dx}. You have to use the following variant instead: 4082 4083@smallexample 4084unsigned long long rdtsc (void) 4085@{ 4086 unsigned int tickl, tickh; 4087 __asm__ __volatile__("rdtsc":"=a"(tickl),"=d"(tickh)); 4088 return ((unsigned long long)tickh << 32)|tickl; 4089@} 4090@end smallexample 4091 4092@item U 4093The call-clobbered integer registers. 4094 4095@item f 4096Any 80387 floating-point (stack) register. 4097 4098@item t 4099Top of 80387 floating-point stack (@code{%st(0)}). 4100 4101@item u 4102Second from top of 80387 floating-point stack (@code{%st(1)}). 4103 4104@ifset INTERNALS 4105@item Yk 4106Any mask register that can be used as a predicate, i.e.@: @code{k1-k7}. 4107 4108@item k 4109Any mask register. 4110@end ifset 4111 4112@item y 4113Any MMX register. 4114 4115@item x 4116Any SSE register. 4117 4118@item v 4119Any EVEX encodable SSE register (@code{%xmm0-%xmm31}). 4120 4121@ifset INTERNALS 4122@item w 4123Any bound register. 4124@end ifset 4125 4126@item Yz 4127First SSE register (@code{%xmm0}). 4128 4129@ifset INTERNALS 4130@item Yi 4131Any SSE register, when SSE2 and inter-unit moves are enabled. 4132 4133@item Yj 4134Any SSE register, when SSE2 and inter-unit moves from vector registers are enabled. 4135 4136@item Ym 4137Any MMX register, when inter-unit moves are enabled. 4138 4139@item Yn 4140Any MMX register, when inter-unit moves from vector registers are enabled. 4141 4142@item Yp 4143Any integer register when @code{TARGET_PARTIAL_REG_STALL} is disabled. 4144 4145@item Ya 4146Any integer register when zero extensions with @code{AND} are disabled. 4147 4148@item Yb 4149Any register that can be used as the GOT base when calling@* 4150@code{___tls_get_addr}: that is, any general register except @code{a} 4151and @code{sp} registers, for @option{-fno-plt} if linker supports it. 4152Otherwise, @code{b} register. 4153 4154@item Yf 4155Any x87 register when 80387 floating-point arithmetic is enabled. 4156 4157@item Yr 4158Lower SSE register when avoiding REX prefix and all SSE registers otherwise. 4159 4160@item Yv 4161For AVX512VL, any EVEX-encodable SSE register (@code{%xmm0-%xmm31}), 4162otherwise any SSE register. 4163 4164@item Yh 4165Any EVEX-encodable SSE register, that has number factor of four. 4166 4167@item Bf 4168Flags register operand. 4169 4170@item Bg 4171GOT memory operand. 4172 4173@item Bm 4174Vector memory operand. 4175 4176@item Bc 4177Constant memory operand. 4178 4179@item Bn 4180Memory operand without REX prefix. 4181 4182@item Bs 4183Sibcall memory operand. 4184 4185@item Bw 4186Call memory operand. 4187 4188@item Bz 4189Constant call address operand. 4190 4191@item BC 4192SSE constant -1 operand. 4193@end ifset 4194 4195@item I 4196Integer constant in the range 0 @dots{} 31, for 32-bit shifts. 4197 4198@item J 4199Integer constant in the range 0 @dots{} 63, for 64-bit shifts. 4200 4201@item K 4202Signed 8-bit integer constant. 4203 4204@item L 4205@code{0xFF} or @code{0xFFFF}, for andsi as a zero-extending move. 4206 4207@item M 42080, 1, 2, or 3 (shifts for the @code{lea} instruction). 4209 4210@item N 4211Unsigned 8-bit integer constant (for @code{in} and @code{out} 4212instructions). 4213 4214@ifset INTERNALS 4215@item O 4216Integer constant in the range 0 @dots{} 127, for 128-bit shifts. 4217@end ifset 4218 4219@item G 4220Standard 80387 floating point constant. 4221 4222@item C 4223SSE constant zero operand. 4224 4225@item e 422632-bit signed integer constant, or a symbolic reference known 4227to fit that range (for immediate operands in sign-extending x86-64 4228instructions). 4229 4230@item We 423132-bit signed integer constant, or a symbolic reference known 4232to fit that range (for sign-extending conversion operations that 4233require non-@code{VOIDmode} immediate operands). 4234 4235@item Wz 423632-bit unsigned integer constant, or a symbolic reference known 4237to fit that range (for zero-extending conversion operations that 4238require non-@code{VOIDmode} immediate operands). 4239 4240@item Wd 4241128-bit integer constant where both the high and low 64-bit word 4242satisfy the @code{e} constraint. 4243 4244@item Z 424532-bit unsigned integer constant, or a symbolic reference known 4246to fit that range (for immediate operands in zero-extending x86-64 4247instructions). 4248 4249@item Tv 4250VSIB address operand. 4251 4252@item Ts 4253Address operand without segment register. 4254 4255@end table 4256 4257@item Xstormy16---@file{config/stormy16/stormy16.h} 4258@table @code 4259@item a 4260Register r0. 4261 4262@item b 4263Register r1. 4264 4265@item c 4266Register r2. 4267 4268@item d 4269Register r8. 4270 4271@item e 4272Registers r0 through r7. 4273 4274@item t 4275Registers r0 and r1. 4276 4277@item y 4278The carry register. 4279 4280@item z 4281Registers r8 and r9. 4282 4283@item I 4284A constant between 0 and 3 inclusive. 4285 4286@item J 4287A constant that has exactly one bit set. 4288 4289@item K 4290A constant that has exactly one bit clear. 4291 4292@item L 4293A constant between 0 and 255 inclusive. 4294 4295@item M 4296A constant between @minus{}255 and 0 inclusive. 4297 4298@item N 4299A constant between @minus{}3 and 0 inclusive. 4300 4301@item O 4302A constant between 1 and 4 inclusive. 4303 4304@item P 4305A constant between @minus{}4 and @minus{}1 inclusive. 4306 4307@item Q 4308A memory reference that is a stack push. 4309 4310@item R 4311A memory reference that is a stack pop. 4312 4313@item S 4314A memory reference that refers to a constant address of known value. 4315 4316@item T 4317The register indicated by Rx (not implemented yet). 4318 4319@item U 4320A constant that is not between 2 and 15 inclusive. 4321 4322@item Z 4323The constant 0. 4324 4325@end table 4326 4327@item Xtensa---@file{config/xtensa/constraints.md} 4328@table @code 4329@item a 4330General-purpose 32-bit register 4331 4332@item b 4333One-bit boolean register 4334 4335@item A 4336MAC16 40-bit accumulator register 4337 4338@item I 4339Signed 12-bit integer constant, for use in MOVI instructions 4340 4341@item J 4342Signed 8-bit integer constant, for use in ADDI instructions 4343 4344@item K 4345Integer constant valid for BccI instructions 4346 4347@item L 4348Unsigned constant valid for BccUI instructions 4349 4350@end table 4351 4352@end table 4353 4354@ifset INTERNALS 4355@node Disable Insn Alternatives 4356@subsection Disable insn alternatives using the @code{enabled} attribute 4357@cindex enabled 4358 4359There are three insn attributes that may be used to selectively disable 4360instruction alternatives: 4361 4362@table @code 4363@item enabled 4364Says whether an alternative is available on the current subtarget. 4365 4366@item preferred_for_size 4367Says whether an enabled alternative should be used in code that is 4368optimized for size. 4369 4370@item preferred_for_speed 4371Says whether an enabled alternative should be used in code that is 4372optimized for speed. 4373@end table 4374 4375All these attributes should use @code{(const_int 1)} to allow an alternative 4376or @code{(const_int 0)} to disallow it. The attributes must be a static 4377property of the subtarget; they cannot for example depend on the 4378current operands, on the current optimization level, on the location 4379of the insn within the body of a loop, on whether register allocation 4380has finished, or on the current compiler pass. 4381 4382The @code{enabled} attribute is a correctness property. It tells GCC to act 4383as though the disabled alternatives were never defined in the first place. 4384This is useful when adding new instructions to an existing pattern in 4385cases where the new instructions are only available for certain cpu 4386architecture levels (typically mapped to the @code{-march=} command-line 4387option). 4388 4389In contrast, the @code{preferred_for_size} and @code{preferred_for_speed} 4390attributes are strong optimization hints rather than correctness properties. 4391@code{preferred_for_size} tells GCC which alternatives to consider when 4392adding or modifying an instruction that GCC wants to optimize for size. 4393@code{preferred_for_speed} does the same thing for speed. Note that things 4394like code motion can lead to cases where code optimized for size uses 4395alternatives that are not preferred for size, and similarly for speed. 4396 4397Although @code{define_insn}s can in principle specify the @code{enabled} 4398attribute directly, it is often clearer to have subsiduary attributes 4399for each architectural feature of interest. The @code{define_insn}s 4400can then use these subsiduary attributes to say which alternatives 4401require which features. The example below does this for @code{cpu_facility}. 4402 4403E.g. the following two patterns could easily be merged using the @code{enabled} 4404attribute: 4405 4406@smallexample 4407 4408(define_insn "*movdi_old" 4409 [(set (match_operand:DI 0 "register_operand" "=d") 4410 (match_operand:DI 1 "register_operand" " d"))] 4411 "!TARGET_NEW" 4412 "lgr %0,%1") 4413 4414(define_insn "*movdi_new" 4415 [(set (match_operand:DI 0 "register_operand" "=d,f,d") 4416 (match_operand:DI 1 "register_operand" " d,d,f"))] 4417 "TARGET_NEW" 4418 "@@ 4419 lgr %0,%1 4420 ldgr %0,%1 4421 lgdr %0,%1") 4422 4423@end smallexample 4424 4425to: 4426 4427@smallexample 4428 4429(define_insn "*movdi_combined" 4430 [(set (match_operand:DI 0 "register_operand" "=d,f,d") 4431 (match_operand:DI 1 "register_operand" " d,d,f"))] 4432 "" 4433 "@@ 4434 lgr %0,%1 4435 ldgr %0,%1 4436 lgdr %0,%1" 4437 [(set_attr "cpu_facility" "*,new,new")]) 4438 4439@end smallexample 4440 4441with the @code{enabled} attribute defined like this: 4442 4443@smallexample 4444 4445(define_attr "cpu_facility" "standard,new" (const_string "standard")) 4446 4447(define_attr "enabled" "" 4448 (cond [(eq_attr "cpu_facility" "standard") (const_int 1) 4449 (and (eq_attr "cpu_facility" "new") 4450 (ne (symbol_ref "TARGET_NEW") (const_int 0))) 4451 (const_int 1)] 4452 (const_int 0))) 4453 4454@end smallexample 4455 4456@end ifset 4457 4458@ifset INTERNALS 4459@node Define Constraints 4460@subsection Defining Machine-Specific Constraints 4461@cindex defining constraints 4462@cindex constraints, defining 4463 4464Machine-specific constraints fall into two categories: register and 4465non-register constraints. Within the latter category, constraints 4466which allow subsets of all possible memory or address operands should 4467be specially marked, to give @code{reload} more information. 4468 4469Machine-specific constraints can be given names of arbitrary length, 4470but they must be entirely composed of letters, digits, underscores 4471(@samp{_}), and angle brackets (@samp{< >}). Like C identifiers, they 4472must begin with a letter or underscore. 4473 4474In order to avoid ambiguity in operand constraint strings, no 4475constraint can have a name that begins with any other constraint's 4476name. For example, if @code{x} is defined as a constraint name, 4477@code{xy} may not be, and vice versa. As a consequence of this rule, 4478no constraint may begin with one of the generic constraint letters: 4479@samp{E F V X g i m n o p r s}. 4480 4481Register constraints correspond directly to register classes. 4482@xref{Register Classes}. There is thus not much flexibility in their 4483definitions. 4484 4485@deffn {MD Expression} define_register_constraint name regclass docstring 4486All three arguments are string constants. 4487@var{name} is the name of the constraint, as it will appear in 4488@code{match_operand} expressions. If @var{name} is a multi-letter 4489constraint its length shall be the same for all constraints starting 4490with the same letter. @var{regclass} can be either the 4491name of the corresponding register class (@pxref{Register Classes}), 4492or a C expression which evaluates to the appropriate register class. 4493If it is an expression, it must have no side effects, and it cannot 4494look at the operand. The usual use of expressions is to map some 4495register constraints to @code{NO_REGS} when the register class 4496is not available on a given subarchitecture. 4497 4498@var{docstring} is a sentence documenting the meaning of the 4499constraint. Docstrings are explained further below. 4500@end deffn 4501 4502Non-register constraints are more like predicates: the constraint 4503definition gives a boolean expression which indicates whether the 4504constraint matches. 4505 4506@deffn {MD Expression} define_constraint name docstring exp 4507The @var{name} and @var{docstring} arguments are the same as for 4508@code{define_register_constraint}, but note that the docstring comes 4509immediately after the name for these expressions. @var{exp} is an RTL 4510expression, obeying the same rules as the RTL expressions in predicate 4511definitions. @xref{Defining Predicates}, for details. If it 4512evaluates true, the constraint matches; if it evaluates false, it 4513doesn't. Constraint expressions should indicate which RTL codes they 4514might match, just like predicate expressions. 4515 4516@code{match_test} C expressions have access to the 4517following variables: 4518 4519@table @var 4520@item op 4521The RTL object defining the operand. 4522@item mode 4523The machine mode of @var{op}. 4524@item ival 4525@samp{INTVAL (@var{op})}, if @var{op} is a @code{const_int}. 4526@item hval 4527@samp{CONST_DOUBLE_HIGH (@var{op})}, if @var{op} is an integer 4528@code{const_double}. 4529@item lval 4530@samp{CONST_DOUBLE_LOW (@var{op})}, if @var{op} is an integer 4531@code{const_double}. 4532@item rval 4533@samp{CONST_DOUBLE_REAL_VALUE (@var{op})}, if @var{op} is a floating-point 4534@code{const_double}. 4535@end table 4536 4537The @var{*val} variables should only be used once another piece of the 4538expression has verified that @var{op} is the appropriate kind of RTL 4539object. 4540@end deffn 4541 4542Most non-register constraints should be defined with 4543@code{define_constraint}. The remaining two definition expressions 4544are only appropriate for constraints that should be handled specially 4545by @code{reload} if they fail to match. 4546 4547@deffn {MD Expression} define_memory_constraint name docstring exp 4548Use this expression for constraints that match a subset of all memory 4549operands: that is, @code{reload} can make them match by converting the 4550operand to the form @samp{@w{(mem (reg @var{X}))}}, where @var{X} is a 4551base register (from the register class specified by 4552@code{BASE_REG_CLASS}, @pxref{Register Classes}). 4553 4554For example, on the S/390, some instructions do not accept arbitrary 4555memory references, but only those that do not make use of an index 4556register. The constraint letter @samp{Q} is defined to represent a 4557memory address of this type. If @samp{Q} is defined with 4558@code{define_memory_constraint}, a @samp{Q} constraint can handle any 4559memory operand, because @code{reload} knows it can simply copy the 4560memory address into a base register if required. This is analogous to 4561the way an @samp{o} constraint can handle any memory operand. 4562 4563The syntax and semantics are otherwise identical to 4564@code{define_constraint}. 4565@end deffn 4566 4567@deffn {MD Expression} define_special_memory_constraint name docstring exp 4568Use this expression for constraints that match a subset of all memory 4569operands: that is, @code{reload} cannot make them match by reloading 4570the address as it is described for @code{define_memory_constraint} or 4571such address reload is undesirable with the performance point of view. 4572 4573For example, @code{define_special_memory_constraint} can be useful if 4574specifically aligned memory is necessary or desirable for some insn 4575operand. 4576 4577The syntax and semantics are otherwise identical to 4578@code{define_memory_constraint}. 4579@end deffn 4580 4581@deffn {MD Expression} define_relaxed_memory_constraint name docstring exp 4582The test expression in a @code{define_memory_constraint} can assume 4583that @code{TARGET_LEGITIMATE_ADDRESS_P} holds for the address inside 4584a @code{mem} rtx and so it does not need to test this condition itself. 4585In other words, a @code{define_memory_constraint} test of the form: 4586 4587@smallexample 4588(match_test "mem") 4589@end smallexample 4590 4591is enough to test whether an rtx is a @code{mem} @emph{and} whether 4592its address satisfies @code{TARGET_MEM_CONSTRAINT} (which is usually 4593@samp{'m'}). Thus the conditions imposed by a @code{define_memory_constraint} 4594always apply on top of the conditions imposed by @code{TARGET_MEM_CONSTRAINT}. 4595 4596However, it is sometimes useful to define memory constraints that allow 4597addresses beyond those accepted by @code{TARGET_LEGITIMATE_ADDRESS_P}. 4598@code{define_relaxed_memory_constraint} exists for this case. 4599The test expression in a @code{define_relaxed_memory_constraint} is 4600applied with no preconditions, so that the expression can determine 4601``from scratch'' exactly which addresses are valid and which are not. 4602 4603The syntax and semantics are otherwise identical to 4604@code{define_memory_constraint}. 4605@end deffn 4606 4607@deffn {MD Expression} define_address_constraint name docstring exp 4608Use this expression for constraints that match a subset of all address 4609operands: that is, @code{reload} can make the constraint match by 4610converting the operand to the form @samp{@w{(reg @var{X})}}, again 4611with @var{X} a base register. 4612 4613Constraints defined with @code{define_address_constraint} can only be 4614used with the @code{address_operand} predicate, or machine-specific 4615predicates that work the same way. They are treated analogously to 4616the generic @samp{p} constraint. 4617 4618The syntax and semantics are otherwise identical to 4619@code{define_constraint}. 4620@end deffn 4621 4622For historical reasons, names beginning with the letters @samp{G H} 4623are reserved for constraints that match only @code{const_double}s, and 4624names beginning with the letters @samp{I J K L M N O P} are reserved 4625for constraints that match only @code{const_int}s. This may change in 4626the future. For the time being, constraints with these names must be 4627written in a stylized form, so that @code{genpreds} can tell you did 4628it correctly: 4629 4630@smallexample 4631@group 4632(define_constraint "[@var{GHIJKLMNOP}]@dots{}" 4633 "@var{doc}@dots{}" 4634 (and (match_code "const_int") ; @r{@code{const_double} for G/H} 4635 @var{condition}@dots{})) ; @r{usually a @code{match_test}} 4636@end group 4637@end smallexample 4638@c the semicolons line up in the formatted manual 4639 4640It is fine to use names beginning with other letters for constraints 4641that match @code{const_double}s or @code{const_int}s. 4642 4643Each docstring in a constraint definition should be one or more complete 4644sentences, marked up in Texinfo format. @emph{They are currently unused.} 4645In the future they will be copied into the GCC manual, in @ref{Machine 4646Constraints}, replacing the hand-maintained tables currently found in 4647that section. Also, in the future the compiler may use this to give 4648more helpful diagnostics when poor choice of @code{asm} constraints 4649causes a reload failure. 4650 4651If you put the pseudo-Texinfo directive @samp{@@internal} at the 4652beginning of a docstring, then (in the future) it will appear only in 4653the internals manual's version of the machine-specific constraint tables. 4654Use this for constraints that should not appear in @code{asm} statements. 4655 4656@node C Constraint Interface 4657@subsection Testing constraints from C 4658@cindex testing constraints 4659@cindex constraints, testing 4660 4661It is occasionally useful to test a constraint from C code rather than 4662implicitly via the constraint string in a @code{match_operand}. The 4663generated file @file{tm_p.h} declares a few interfaces for working 4664with constraints. At present these are defined for all constraints 4665except @code{g} (which is equivalent to @code{general_operand}). 4666 4667Some valid constraint names are not valid C identifiers, so there is a 4668mangling scheme for referring to them from C@. Constraint names that 4669do not contain angle brackets or underscores are left unchanged. 4670Underscores are doubled, each @samp{<} is replaced with @samp{_l}, and 4671each @samp{>} with @samp{_g}. Here are some examples: 4672 4673@c the @c's prevent double blank lines in the printed manual. 4674@example 4675@multitable {Original} {Mangled} 4676@item @strong{Original} @tab @strong{Mangled} @c 4677@item @code{x} @tab @code{x} @c 4678@item @code{P42x} @tab @code{P42x} @c 4679@item @code{P4_x} @tab @code{P4__x} @c 4680@item @code{P4>x} @tab @code{P4_gx} @c 4681@item @code{P4>>} @tab @code{P4_g_g} @c 4682@item @code{P4_g>} @tab @code{P4__g_g} @c 4683@end multitable 4684@end example 4685 4686Throughout this section, the variable @var{c} is either a constraint 4687in the abstract sense, or a constant from @code{enum constraint_num}; 4688the variable @var{m} is a mangled constraint name (usually as part of 4689a larger identifier). 4690 4691@deftp Enum constraint_num 4692For each constraint except @code{g}, there is a corresponding 4693enumeration constant: @samp{CONSTRAINT_} plus the mangled name of the 4694constraint. Functions that take an @code{enum constraint_num} as an 4695argument expect one of these constants. 4696@end deftp 4697 4698@deftypefun {inline bool} satisfies_constraint_@var{m} (rtx @var{exp}) 4699For each non-register constraint @var{m} except @code{g}, there is 4700one of these functions; it returns @code{true} if @var{exp} satisfies the 4701constraint. These functions are only visible if @file{rtl.h} was included 4702before @file{tm_p.h}. 4703@end deftypefun 4704 4705@deftypefun bool constraint_satisfied_p (rtx @var{exp}, enum constraint_num @var{c}) 4706Like the @code{satisfies_constraint_@var{m}} functions, but the 4707constraint to test is given as an argument, @var{c}. If @var{c} 4708specifies a register constraint, this function will always return 4709@code{false}. 4710@end deftypefun 4711 4712@deftypefun {enum reg_class} reg_class_for_constraint (enum constraint_num @var{c}) 4713Returns the register class associated with @var{c}. If @var{c} is not 4714a register constraint, or those registers are not available for the 4715currently selected subtarget, returns @code{NO_REGS}. 4716@end deftypefun 4717 4718Here is an example use of @code{satisfies_constraint_@var{m}}. In 4719peephole optimizations (@pxref{Peephole Definitions}), operand 4720constraint strings are ignored, so if there are relevant constraints, 4721they must be tested in the C condition. In the example, the 4722optimization is applied if operand 2 does @emph{not} satisfy the 4723@samp{K} constraint. (This is a simplified version of a peephole 4724definition from the i386 machine description.) 4725 4726@smallexample 4727(define_peephole2 4728 [(match_scratch:SI 3 "r") 4729 (set (match_operand:SI 0 "register_operand" "") 4730 (mult:SI (match_operand:SI 1 "memory_operand" "") 4731 (match_operand:SI 2 "immediate_operand" "")))] 4732 4733 "!satisfies_constraint_K (operands[2])" 4734 4735 [(set (match_dup 3) (match_dup 1)) 4736 (set (match_dup 0) (mult:SI (match_dup 3) (match_dup 2)))] 4737 4738 "") 4739@end smallexample 4740 4741@node Standard Names 4742@section Standard Pattern Names For Generation 4743@cindex standard pattern names 4744@cindex pattern names 4745@cindex names, pattern 4746 4747Here is a table of the instruction names that are meaningful in the RTL 4748generation pass of the compiler. Giving one of these names to an 4749instruction pattern tells the RTL generation pass that it can use the 4750pattern to accomplish a certain task. 4751 4752@table @asis 4753@cindex @code{mov@var{m}} instruction pattern 4754@item @samp{mov@var{m}} 4755Here @var{m} stands for a two-letter machine mode name, in lowercase. 4756This instruction pattern moves data with that machine mode from operand 47571 to operand 0. For example, @samp{movsi} moves full-word data. 4758 4759If operand 0 is a @code{subreg} with mode @var{m} of a register whose 4760own mode is wider than @var{m}, the effect of this instruction is 4761to store the specified value in the part of the register that corresponds 4762to mode @var{m}. Bits outside of @var{m}, but which are within the 4763same target word as the @code{subreg} are undefined. Bits which are 4764outside the target word are left unchanged. 4765 4766This class of patterns is special in several ways. First of all, each 4767of these names up to and including full word size @emph{must} be defined, 4768because there is no other way to copy a datum from one place to another. 4769If there are patterns accepting operands in larger modes, 4770@samp{mov@var{m}} must be defined for integer modes of those sizes. 4771 4772Second, these patterns are not used solely in the RTL generation pass. 4773Even the reload pass can generate move insns to copy values from stack 4774slots into temporary registers. When it does so, one of the operands is 4775a hard register and the other is an operand that can need to be reloaded 4776into a register. 4777 4778@findex force_reg 4779Therefore, when given such a pair of operands, the pattern must generate 4780RTL which needs no reloading and needs no temporary registers---no 4781registers other than the operands. For example, if you support the 4782pattern with a @code{define_expand}, then in such a case the 4783@code{define_expand} mustn't call @code{force_reg} or any other such 4784function which might generate new pseudo registers. 4785 4786This requirement exists even for subword modes on a RISC machine where 4787fetching those modes from memory normally requires several insns and 4788some temporary registers. 4789 4790@findex change_address 4791During reload a memory reference with an invalid address may be passed 4792as an operand. Such an address will be replaced with a valid address 4793later in the reload pass. In this case, nothing may be done with the 4794address except to use it as it stands. If it is copied, it will not be 4795replaced with a valid address. No attempt should be made to make such 4796an address into a valid address and no routine (such as 4797@code{change_address}) that will do so may be called. Note that 4798@code{general_operand} will fail when applied to such an address. 4799 4800@findex reload_in_progress 4801The global variable @code{reload_in_progress} (which must be explicitly 4802declared if required) can be used to determine whether such special 4803handling is required. 4804 4805The variety of operands that have reloads depends on the rest of the 4806machine description, but typically on a RISC machine these can only be 4807pseudo registers that did not get hard registers, while on other 4808machines explicit memory references will get optional reloads. 4809 4810If a scratch register is required to move an object to or from memory, 4811it can be allocated using @code{gen_reg_rtx} prior to life analysis. 4812 4813If there are cases which need scratch registers during or after reload, 4814you must provide an appropriate secondary_reload target hook. 4815 4816@findex can_create_pseudo_p 4817The macro @code{can_create_pseudo_p} can be used to determine if it 4818is unsafe to create new pseudo registers. If this variable is nonzero, then 4819it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo. 4820 4821The constraints on a @samp{mov@var{m}} must permit moving any hard 4822register to any other hard register provided that 4823@code{TARGET_HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and 4824@code{TARGET_REGISTER_MOVE_COST} applied to their classes returns a value 4825of 2. 4826 4827It is obligatory to support floating point @samp{mov@var{m}} 4828instructions into and out of any registers that can hold fixed point 4829values, because unions and structures (which have modes @code{SImode} or 4830@code{DImode}) can be in those registers and they may have floating 4831point members. 4832 4833There may also be a need to support fixed point @samp{mov@var{m}} 4834instructions in and out of floating point registers. Unfortunately, I 4835have forgotten why this was so, and I don't know whether it is still 4836true. If @code{TARGET_HARD_REGNO_MODE_OK} rejects fixed point values in 4837floating point registers, then the constraints of the fixed point 4838@samp{mov@var{m}} instructions must be designed to avoid ever trying to 4839reload into a floating point register. 4840 4841@cindex @code{reload_in} instruction pattern 4842@cindex @code{reload_out} instruction pattern 4843@item @samp{reload_in@var{m}} 4844@itemx @samp{reload_out@var{m}} 4845These named patterns have been obsoleted by the target hook 4846@code{secondary_reload}. 4847 4848Like @samp{mov@var{m}}, but used when a scratch register is required to 4849move between operand 0 and operand 1. Operand 2 describes the scratch 4850register. See the discussion of the @code{SECONDARY_RELOAD_CLASS} 4851macro in @pxref{Register Classes}. 4852 4853There are special restrictions on the form of the @code{match_operand}s 4854used in these patterns. First, only the predicate for the reload 4855operand is examined, i.e., @code{reload_in} examines operand 1, but not 4856the predicates for operand 0 or 2. Second, there may be only one 4857alternative in the constraints. Third, only a single register class 4858letter may be used for the constraint; subsequent constraint letters 4859are ignored. As a special exception, an empty constraint string 4860matches the @code{ALL_REGS} register class. This may relieve ports 4861of the burden of defining an @code{ALL_REGS} constraint letter just 4862for these patterns. 4863 4864@cindex @code{movstrict@var{m}} instruction pattern 4865@item @samp{movstrict@var{m}} 4866Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg} 4867with mode @var{m} of a register whose natural mode is wider, 4868the @samp{movstrict@var{m}} instruction is guaranteed not to alter 4869any of the register except the part which belongs to mode @var{m}. 4870 4871@cindex @code{movmisalign@var{m}} instruction pattern 4872@item @samp{movmisalign@var{m}} 4873This variant of a move pattern is designed to load or store a value 4874from a memory address that is not naturally aligned for its mode. 4875For a store, the memory will be in operand 0; for a load, the memory 4876will be in operand 1. The other operand is guaranteed not to be a 4877memory, so that it's easy to tell whether this is a load or store. 4878 4879This pattern is used by the autovectorizer, and when expanding a 4880@code{MISALIGNED_INDIRECT_REF} expression. 4881 4882@cindex @code{load_multiple} instruction pattern 4883@item @samp{load_multiple} 4884Load several consecutive memory locations into consecutive registers. 4885Operand 0 is the first of the consecutive registers, operand 1 4886is the first memory location, and operand 2 is a constant: the 4887number of consecutive registers. 4888 4889Define this only if the target machine really has such an instruction; 4890do not define this if the most efficient way of loading consecutive 4891registers from memory is to do them one at a time. 4892 4893On some machines, there are restrictions as to which consecutive 4894registers can be stored into memory, such as particular starting or 4895ending register numbers or only a range of valid counts. For those 4896machines, use a @code{define_expand} (@pxref{Expander Definitions}) 4897and make the pattern fail if the restrictions are not met. 4898 4899Write the generated insn as a @code{parallel} with elements being a 4900@code{set} of one register from the appropriate memory location (you may 4901also need @code{use} or @code{clobber} elements). Use a 4902@code{match_parallel} (@pxref{RTL Template}) to recognize the insn. See 4903@file{rs6000.md} for examples of the use of this insn pattern. 4904 4905@cindex @samp{store_multiple} instruction pattern 4906@item @samp{store_multiple} 4907Similar to @samp{load_multiple}, but store several consecutive registers 4908into consecutive memory locations. Operand 0 is the first of the 4909consecutive memory locations, operand 1 is the first register, and 4910operand 2 is a constant: the number of consecutive registers. 4911 4912@cindex @code{vec_load_lanes@var{m}@var{n}} instruction pattern 4913@item @samp{vec_load_lanes@var{m}@var{n}} 4914Perform an interleaved load of several vectors from memory operand 1 4915into register operand 0. Both operands have mode @var{m}. The register 4916operand is viewed as holding consecutive vectors of mode @var{n}, 4917while the memory operand is a flat array that contains the same number 4918of elements. The operation is equivalent to: 4919 4920@smallexample 4921int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4922for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4923 for (i = 0; i < c; i++) 4924 operand0[i][j] = operand1[j * c + i]; 4925@end smallexample 4926 4927For example, @samp{vec_load_lanestiv4hi} loads 8 16-bit values 4928from memory into a register of mode @samp{TI}@. The register 4929contains two consecutive vectors of mode @samp{V4HI}@. 4930 4931This pattern can only be used if: 4932@smallexample 4933TARGET_ARRAY_MODE_SUPPORTED_P (@var{n}, @var{c}) 4934@end smallexample 4935is true. GCC assumes that, if a target supports this kind of 4936instruction for some mode @var{n}, it also supports unaligned 4937loads for vectors of mode @var{n}. 4938 4939This pattern is not allowed to @code{FAIL}. 4940 4941@cindex @code{vec_mask_load_lanes@var{m}@var{n}} instruction pattern 4942@item @samp{vec_mask_load_lanes@var{m}@var{n}} 4943Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional 4944mask operand (operand 2) that specifies which elements of the destination 4945vectors should be loaded. Other elements of the destination 4946vectors are set to zero. The operation is equivalent to: 4947 4948@smallexample 4949int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4950for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4951 if (operand2[j]) 4952 for (i = 0; i < c; i++) 4953 operand0[i][j] = operand1[j * c + i]; 4954 else 4955 for (i = 0; i < c; i++) 4956 operand0[i][j] = 0; 4957@end smallexample 4958 4959This pattern is not allowed to @code{FAIL}. 4960 4961@cindex @code{vec_store_lanes@var{m}@var{n}} instruction pattern 4962@item @samp{vec_store_lanes@var{m}@var{n}} 4963Equivalent to @samp{vec_load_lanes@var{m}@var{n}}, with the memory 4964and register operands reversed. That is, the instruction is 4965equivalent to: 4966 4967@smallexample 4968int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4969for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4970 for (i = 0; i < c; i++) 4971 operand0[j * c + i] = operand1[i][j]; 4972@end smallexample 4973 4974for a memory operand 0 and register operand 1. 4975 4976This pattern is not allowed to @code{FAIL}. 4977 4978@cindex @code{vec_mask_store_lanes@var{m}@var{n}} instruction pattern 4979@item @samp{vec_mask_store_lanes@var{m}@var{n}} 4980Like @samp{vec_store_lanes@var{m}@var{n}}, but takes an additional 4981mask operand (operand 2) that specifies which elements of the source 4982vectors should be stored. The operation is equivalent to: 4983 4984@smallexample 4985int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4986for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4987 if (operand2[j]) 4988 for (i = 0; i < c; i++) 4989 operand0[j * c + i] = operand1[i][j]; 4990@end smallexample 4991 4992This pattern is not allowed to @code{FAIL}. 4993 4994@cindex @code{gather_load@var{m}@var{n}} instruction pattern 4995@item @samp{gather_load@var{m}@var{n}} 4996Load several separate memory locations into a vector of mode @var{m}. 4997Operand 1 is a scalar base address and operand 2 is a vector of mode @var{n} 4998containing offsets from that base. Operand 0 is a destination vector with 4999the same number of elements as @var{n}. For each element index @var{i}: 5000 5001@itemize @bullet 5002@item 5003extend the offset element @var{i} to address width, using zero 5004extension if operand 3 is 1 and sign extension if operand 3 is zero; 5005@item 5006multiply the extended offset by operand 4; 5007@item 5008add the result to the base; and 5009@item 5010load the value at that address into element @var{i} of operand 0. 5011@end itemize 5012 5013The value of operand 3 does not matter if the offsets are already 5014address width. 5015 5016@cindex @code{mask_gather_load@var{m}@var{n}} instruction pattern 5017@item @samp{mask_gather_load@var{m}@var{n}} 5018Like @samp{gather_load@var{m}@var{n}}, but takes an extra mask operand as 5019operand 5. Bit @var{i} of the mask is set if element @var{i} 5020of the result should be loaded from memory and clear if element @var{i} 5021of the result should be set to zero. 5022 5023@cindex @code{scatter_store@var{m}@var{n}} instruction pattern 5024@item @samp{scatter_store@var{m}@var{n}} 5025Store a vector of mode @var{m} into several distinct memory locations. 5026Operand 0 is a scalar base address and operand 1 is a vector of mode 5027@var{n} containing offsets from that base. Operand 4 is the vector of 5028values that should be stored, which has the same number of elements as 5029@var{n}. For each element index @var{i}: 5030 5031@itemize @bullet 5032@item 5033extend the offset element @var{i} to address width, using zero 5034extension if operand 2 is 1 and sign extension if operand 2 is zero; 5035@item 5036multiply the extended offset by operand 3; 5037@item 5038add the result to the base; and 5039@item 5040store element @var{i} of operand 4 to that address. 5041@end itemize 5042 5043The value of operand 2 does not matter if the offsets are already 5044address width. 5045 5046@cindex @code{mask_scatter_store@var{m}@var{n}} instruction pattern 5047@item @samp{mask_scatter_store@var{m}@var{n}} 5048Like @samp{scatter_store@var{m}@var{n}}, but takes an extra mask operand as 5049operand 5. Bit @var{i} of the mask is set if element @var{i} 5050of the result should be stored to memory. 5051 5052@cindex @code{vec_set@var{m}} instruction pattern 5053@item @samp{vec_set@var{m}} 5054Set given field in the vector value. Operand 0 is the vector to modify, 5055operand 1 is new value of field and operand 2 specify the field index. 5056 5057@cindex @code{vec_extract@var{m}@var{n}} instruction pattern 5058@item @samp{vec_extract@var{m}@var{n}} 5059Extract given field from the vector value. Operand 1 is the vector, operand 2 5060specify field index and operand 0 place to store value into. The 5061@var{n} mode is the mode of the field or vector of fields that should be 5062extracted, should be either element mode of the vector mode @var{m}, or 5063a vector mode with the same element mode and smaller number of elements. 5064If @var{n} is a vector mode, the index is counted in units of that mode. 5065 5066@cindex @code{vec_init@var{m}@var{n}} instruction pattern 5067@item @samp{vec_init@var{m}@var{n}} 5068Initialize the vector to given values. Operand 0 is the vector to initialize 5069and operand 1 is parallel containing values for individual fields. The 5070@var{n} mode is the mode of the elements, should be either element mode of 5071the vector mode @var{m}, or a vector mode with the same element mode and 5072smaller number of elements. 5073 5074@cindex @code{vec_duplicate@var{m}} instruction pattern 5075@item @samp{vec_duplicate@var{m}} 5076Initialize vector output operand 0 so that each element has the value given 5077by scalar input operand 1. The vector has mode @var{m} and the scalar has 5078the mode appropriate for one element of @var{m}. 5079 5080This pattern only handles duplicates of non-constant inputs. Constant 5081vectors go through the @code{mov@var{m}} pattern instead. 5082 5083This pattern is not allowed to @code{FAIL}. 5084 5085@cindex @code{vec_series@var{m}} instruction pattern 5086@item @samp{vec_series@var{m}} 5087Initialize vector output operand 0 so that element @var{i} is equal to 5088operand 1 plus @var{i} times operand 2. In other words, create a linear 5089series whose base value is operand 1 and whose step is operand 2. 5090 5091The vector output has mode @var{m} and the scalar inputs have the mode 5092appropriate for one element of @var{m}. This pattern is not used for 5093floating-point vectors, in order to avoid having to specify the 5094rounding behavior for @var{i} > 1. 5095 5096This pattern is not allowed to @code{FAIL}. 5097 5098@cindex @code{while_ult@var{m}@var{n}} instruction pattern 5099@item @code{while_ult@var{m}@var{n}} 5100Set operand 0 to a mask that is true while incrementing operand 1 5101gives a value that is less than operand 2. Operand 0 has mode @var{n} 5102and operands 1 and 2 are scalar integers of mode @var{m}. 5103The operation is equivalent to: 5104 5105@smallexample 5106operand0[0] = operand1 < operand2; 5107for (i = 1; i < GET_MODE_NUNITS (@var{n}); i++) 5108 operand0[i] = operand0[i - 1] && (operand1 + i < operand2); 5109@end smallexample 5110 5111@cindex @code{check_raw_ptrs@var{m}} instruction pattern 5112@item @samp{check_raw_ptrs@var{m}} 5113Check whether, given two pointers @var{a} and @var{b} and a length @var{len}, 5114a write of @var{len} bytes at @var{a} followed by a read of @var{len} bytes 5115at @var{b} can be split into interleaved byte accesses 5116@samp{@var{a}[0], @var{b}[0], @var{a}[1], @var{b}[1], @dots{}} 5117without affecting the dependencies between the bytes. Set operand 0 5118to true if the split is possible and false otherwise. 5119 5120Operands 1, 2 and 3 provide the values of @var{a}, @var{b} and @var{len} 5121respectively. Operand 4 is a constant integer that provides the known 5122common alignment of @var{a} and @var{b}. All inputs have mode @var{m}. 5123 5124This split is possible if: 5125 5126@smallexample 5127@var{a} == @var{b} || @var{a} + @var{len} <= @var{b} || @var{b} + @var{len} <= @var{a} 5128@end smallexample 5129 5130You should only define this pattern if the target has a way of accelerating 5131the test without having to do the individual comparisons. 5132 5133@cindex @code{check_war_ptrs@var{m}} instruction pattern 5134@item @samp{check_war_ptrs@var{m}} 5135Like @samp{check_raw_ptrs@var{m}}, but with the read and write swapped round. 5136The split is possible in this case if: 5137 5138@smallexample 5139@var{b} <= @var{a} || @var{a} + @var{len} <= @var{b} 5140@end smallexample 5141 5142@cindex @code{vec_cmp@var{m}@var{n}} instruction pattern 5143@item @samp{vec_cmp@var{m}@var{n}} 5144Output a vector comparison. Operand 0 of mode @var{n} is the destination for 5145predicate in operand 1 which is a signed vector comparison with operands of 5146mode @var{m} in operands 2 and 3. Predicate is computed by element-wise 5147evaluation of the vector comparison with a truth value of all-ones and a false 5148value of all-zeros. 5149 5150@cindex @code{vec_cmpu@var{m}@var{n}} instruction pattern 5151@item @samp{vec_cmpu@var{m}@var{n}} 5152Similar to @code{vec_cmp@var{m}@var{n}} but perform unsigned vector comparison. 5153 5154@cindex @code{vec_cmpeq@var{m}@var{n}} instruction pattern 5155@item @samp{vec_cmpeq@var{m}@var{n}} 5156Similar to @code{vec_cmp@var{m}@var{n}} but perform equality or non-equality 5157vector comparison only. If @code{vec_cmp@var{m}@var{n}} 5158or @code{vec_cmpu@var{m}@var{n}} instruction pattern is supported, 5159it will be preferred over @code{vec_cmpeq@var{m}@var{n}}, so there is 5160no need to define this instruction pattern if the others are supported. 5161 5162@cindex @code{vcond@var{m}@var{n}} instruction pattern 5163@item @samp{vcond@var{m}@var{n}} 5164Output a conditional vector move. Operand 0 is the destination to 5165receive a combination of operand 1 and operand 2, which are of mode @var{m}, 5166dependent on the outcome of the predicate in operand 3 which is a signed 5167vector comparison with operands of mode @var{n} in operands 4 and 5. The 5168modes @var{m} and @var{n} should have the same size. Operand 0 5169will be set to the value @var{op1} & @var{msk} | @var{op2} & ~@var{msk} 5170where @var{msk} is computed by element-wise evaluation of the vector 5171comparison with a truth value of all-ones and a false value of all-zeros. 5172 5173@cindex @code{vcondu@var{m}@var{n}} instruction pattern 5174@item @samp{vcondu@var{m}@var{n}} 5175Similar to @code{vcond@var{m}@var{n}} but performs unsigned vector 5176comparison. 5177 5178@cindex @code{vcondeq@var{m}@var{n}} instruction pattern 5179@item @samp{vcondeq@var{m}@var{n}} 5180Similar to @code{vcond@var{m}@var{n}} but performs equality or 5181non-equality vector comparison only. If @code{vcond@var{m}@var{n}} 5182or @code{vcondu@var{m}@var{n}} instruction pattern is supported, 5183it will be preferred over @code{vcondeq@var{m}@var{n}}, so there is 5184no need to define this instruction pattern if the others are supported. 5185 5186@cindex @code{vcond_mask_@var{m}@var{n}} instruction pattern 5187@item @samp{vcond_mask_@var{m}@var{n}} 5188Similar to @code{vcond@var{m}@var{n}} but operand 3 holds a pre-computed 5189result of vector comparison. 5190 5191@cindex @code{maskload@var{m}@var{n}} instruction pattern 5192@item @samp{maskload@var{m}@var{n}} 5193Perform a masked load of vector from memory operand 1 of mode @var{m} 5194into register operand 0. Mask is provided in register operand 2 of 5195mode @var{n}. 5196 5197This pattern is not allowed to @code{FAIL}. 5198 5199@cindex @code{maskstore@var{m}@var{n}} instruction pattern 5200@item @samp{maskstore@var{m}@var{n}} 5201Perform a masked store of vector from register operand 1 of mode @var{m} 5202into memory operand 0. Mask is provided in register operand 2 of 5203mode @var{n}. 5204 5205This pattern is not allowed to @code{FAIL}. 5206 5207@cindex @code{len_load_@var{m}} instruction pattern 5208@item @samp{len_load_@var{m}} 5209Load the number of vector elements specified by operand 2 from memory 5210operand 1 into vector register operand 0, setting the other elements of 5211operand 0 to undefined values. Operands 0 and 1 have mode @var{m}, 5212which must be a vector mode. Operand 2 has whichever integer mode the 5213target prefers. If operand 2 exceeds the number of elements in mode 5214@var{m}, the behavior is undefined. If the target prefers the length 5215to be measured in bytes rather than elements, it should only implement 5216this pattern for vectors of @code{QI} elements. 5217 5218This pattern is not allowed to @code{FAIL}. 5219 5220@cindex @code{len_store_@var{m}} instruction pattern 5221@item @samp{len_store_@var{m}} 5222Store the number of vector elements specified by operand 2 from vector 5223register operand 1 into memory operand 0, leaving the other elements of 5224operand 0 unchanged. Operands 0 and 1 have mode @var{m}, which must be 5225a vector mode. Operand 2 has whichever integer mode the target prefers. 5226If operand 2 exceeds the number of elements in mode @var{m}, the behavior 5227is undefined. If the target prefers the length to be measured in bytes 5228rather than elements, it should only implement this pattern for vectors 5229of @code{QI} elements. 5230 5231This pattern is not allowed to @code{FAIL}. 5232 5233@cindex @code{vec_perm@var{m}} instruction pattern 5234@item @samp{vec_perm@var{m}} 5235Output a (variable) vector permutation. Operand 0 is the destination 5236to receive elements from operand 1 and operand 2, which are of mode 5237@var{m}. Operand 3 is the @dfn{selector}. It is an integral mode 5238vector of the same width and number of elements as mode @var{m}. 5239 5240The input elements are numbered from 0 in operand 1 through 5241@math{2*@var{N}-1} in operand 2. The elements of the selector must 5242be computed modulo @math{2*@var{N}}. Note that if 5243@code{rtx_equal_p(operand1, operand2)}, this can be implemented 5244with just operand 1 and selector elements modulo @var{N}. 5245 5246In order to make things easy for a number of targets, if there is no 5247@samp{vec_perm} pattern for mode @var{m}, but there is for mode @var{q} 5248where @var{q} is a vector of @code{QImode} of the same width as @var{m}, 5249the middle-end will lower the mode @var{m} @code{VEC_PERM_EXPR} to 5250mode @var{q}. 5251 5252See also @code{TARGET_VECTORIZER_VEC_PERM_CONST}, which performs 5253the analogous operation for constant selectors. 5254 5255@cindex @code{push@var{m}1} instruction pattern 5256@item @samp{push@var{m}1} 5257Output a push instruction. Operand 0 is value to push. Used only when 5258@code{PUSH_ROUNDING} is defined. For historical reason, this pattern may be 5259missing and in such case an @code{mov} expander is used instead, with a 5260@code{MEM} expression forming the push operation. The @code{mov} expander 5261method is deprecated. 5262 5263@cindex @code{add@var{m}3} instruction pattern 5264@item @samp{add@var{m}3} 5265Add operand 2 and operand 1, storing the result in operand 0. All operands 5266must have mode @var{m}. This can be used even on two-address machines, by 5267means of constraints requiring operands 1 and 0 to be the same location. 5268 5269@cindex @code{ssadd@var{m}3} instruction pattern 5270@cindex @code{usadd@var{m}3} instruction pattern 5271@cindex @code{sub@var{m}3} instruction pattern 5272@cindex @code{sssub@var{m}3} instruction pattern 5273@cindex @code{ussub@var{m}3} instruction pattern 5274@cindex @code{mul@var{m}3} instruction pattern 5275@cindex @code{ssmul@var{m}3} instruction pattern 5276@cindex @code{usmul@var{m}3} instruction pattern 5277@cindex @code{div@var{m}3} instruction pattern 5278@cindex @code{ssdiv@var{m}3} instruction pattern 5279@cindex @code{udiv@var{m}3} instruction pattern 5280@cindex @code{usdiv@var{m}3} instruction pattern 5281@cindex @code{mod@var{m}3} instruction pattern 5282@cindex @code{umod@var{m}3} instruction pattern 5283@cindex @code{umin@var{m}3} instruction pattern 5284@cindex @code{umax@var{m}3} instruction pattern 5285@cindex @code{and@var{m}3} instruction pattern 5286@cindex @code{ior@var{m}3} instruction pattern 5287@cindex @code{xor@var{m}3} instruction pattern 5288@item @samp{ssadd@var{m}3}, @samp{usadd@var{m}3} 5289@itemx @samp{sub@var{m}3}, @samp{sssub@var{m}3}, @samp{ussub@var{m}3} 5290@itemx @samp{mul@var{m}3}, @samp{ssmul@var{m}3}, @samp{usmul@var{m}3} 5291@itemx @samp{div@var{m}3}, @samp{ssdiv@var{m}3} 5292@itemx @samp{udiv@var{m}3}, @samp{usdiv@var{m}3} 5293@itemx @samp{mod@var{m}3}, @samp{umod@var{m}3} 5294@itemx @samp{umin@var{m}3}, @samp{umax@var{m}3} 5295@itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3} 5296Similar, for other arithmetic operations. 5297 5298@cindex @code{addv@var{m}4} instruction pattern 5299@item @samp{addv@var{m}4} 5300Like @code{add@var{m}3} but takes a @code{code_label} as operand 3 and 5301emits code to jump to it if signed overflow occurs during the addition. 5302This pattern is used to implement the built-in functions performing 5303signed integer addition with overflow checking. 5304 5305@cindex @code{subv@var{m}4} instruction pattern 5306@cindex @code{mulv@var{m}4} instruction pattern 5307@item @samp{subv@var{m}4}, @samp{mulv@var{m}4} 5308Similar, for other signed arithmetic operations. 5309 5310@cindex @code{uaddv@var{m}4} instruction pattern 5311@item @samp{uaddv@var{m}4} 5312Like @code{addv@var{m}4} but for unsigned addition. That is to 5313say, the operation is the same as signed addition but the jump 5314is taken only on unsigned overflow. 5315 5316@cindex @code{usubv@var{m}4} instruction pattern 5317@cindex @code{umulv@var{m}4} instruction pattern 5318@item @samp{usubv@var{m}4}, @samp{umulv@var{m}4} 5319Similar, for other unsigned arithmetic operations. 5320 5321@cindex @code{addptr@var{m}3} instruction pattern 5322@item @samp{addptr@var{m}3} 5323Like @code{add@var{m}3} but is guaranteed to only be used for address 5324calculations. The expanded code is not allowed to clobber the 5325condition code. It only needs to be defined if @code{add@var{m}3} 5326sets the condition code. If adds used for address calculations and 5327normal adds are not compatible it is required to expand a distinct 5328pattern (e.g.@: using an unspec). The pattern is used by LRA to emit 5329address calculations. @code{add@var{m}3} is used if 5330@code{addptr@var{m}3} is not defined. 5331 5332@cindex @code{fma@var{m}4} instruction pattern 5333@item @samp{fma@var{m}4} 5334Multiply operand 2 and operand 1, then add operand 3, storing the 5335result in operand 0 without doing an intermediate rounding step. All 5336operands must have mode @var{m}. This pattern is used to implement 5337the @code{fma}, @code{fmaf}, and @code{fmal} builtin functions from 5338the ISO C99 standard. 5339 5340@cindex @code{fms@var{m}4} instruction pattern 5341@item @samp{fms@var{m}4} 5342Like @code{fma@var{m}4}, except operand 3 subtracted from the 5343product instead of added to the product. This is represented 5344in the rtl as 5345 5346@smallexample 5347(fma:@var{m} @var{op1} @var{op2} (neg:@var{m} @var{op3})) 5348@end smallexample 5349 5350@cindex @code{fnma@var{m}4} instruction pattern 5351@item @samp{fnma@var{m}4} 5352Like @code{fma@var{m}4} except that the intermediate product 5353is negated before being added to operand 3. This is represented 5354in the rtl as 5355 5356@smallexample 5357(fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} @var{op3}) 5358@end smallexample 5359 5360@cindex @code{fnms@var{m}4} instruction pattern 5361@item @samp{fnms@var{m}4} 5362Like @code{fms@var{m}4} except that the intermediate product 5363is negated before subtracting operand 3. This is represented 5364in the rtl as 5365 5366@smallexample 5367(fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} (neg:@var{m} @var{op3})) 5368@end smallexample 5369 5370@cindex @code{min@var{m}3} instruction pattern 5371@cindex @code{max@var{m}3} instruction pattern 5372@item @samp{smin@var{m}3}, @samp{smax@var{m}3} 5373Signed minimum and maximum operations. When used with floating point, 5374if both operands are zeros, or if either operand is @code{NaN}, then 5375it is unspecified which of the two operands is returned as the result. 5376 5377@cindex @code{fmin@var{m}3} instruction pattern 5378@cindex @code{fmax@var{m}3} instruction pattern 5379@item @samp{fmin@var{m}3}, @samp{fmax@var{m}3} 5380IEEE-conformant minimum and maximum operations. If one operand is a quiet 5381@code{NaN}, then the other operand is returned. If both operands are quiet 5382@code{NaN}, then a quiet @code{NaN} is returned. In the case when gcc supports 5383signaling @code{NaN} (-fsignaling-nans) an invalid floating point exception is 5384raised and a quiet @code{NaN} is returned. 5385 5386All operands have mode @var{m}, which is a scalar or vector 5387floating-point mode. These patterns are not allowed to @code{FAIL}. 5388 5389@cindex @code{reduc_smin_scal_@var{m}} instruction pattern 5390@cindex @code{reduc_smax_scal_@var{m}} instruction pattern 5391@item @samp{reduc_smin_scal_@var{m}}, @samp{reduc_smax_scal_@var{m}} 5392Find the signed minimum/maximum of the elements of a vector. The vector is 5393operand 1, and operand 0 is the scalar result, with mode equal to the mode of 5394the elements of the input vector. 5395 5396@cindex @code{reduc_umin_scal_@var{m}} instruction pattern 5397@cindex @code{reduc_umax_scal_@var{m}} instruction pattern 5398@item @samp{reduc_umin_scal_@var{m}}, @samp{reduc_umax_scal_@var{m}} 5399Find the unsigned minimum/maximum of the elements of a vector. The vector is 5400operand 1, and operand 0 is the scalar result, with mode equal to the mode of 5401the elements of the input vector. 5402 5403@cindex @code{reduc_fmin_scal_@var{m}} instruction pattern 5404@cindex @code{reduc_fmax_scal_@var{m}} instruction pattern 5405@item @samp{reduc_fmin_scal_@var{m}}, @samp{reduc_fmax_scal_@var{m}} 5406Find the floating-point minimum/maximum of the elements of a vector, 5407using the same rules as @code{fmin@var{m}3} and @code{fmax@var{m}3}. 5408Operand 1 is a vector of mode @var{m} and operand 0 is the scalar 5409result, which has mode @code{GET_MODE_INNER (@var{m})}. 5410 5411@cindex @code{reduc_plus_scal_@var{m}} instruction pattern 5412@item @samp{reduc_plus_scal_@var{m}} 5413Compute the sum of the elements of a vector. The vector is operand 1, and 5414operand 0 is the scalar result, with mode equal to the mode of the elements of 5415the input vector. 5416 5417@cindex @code{reduc_and_scal_@var{m}} instruction pattern 5418@item @samp{reduc_and_scal_@var{m}} 5419@cindex @code{reduc_ior_scal_@var{m}} instruction pattern 5420@itemx @samp{reduc_ior_scal_@var{m}} 5421@cindex @code{reduc_xor_scal_@var{m}} instruction pattern 5422@itemx @samp{reduc_xor_scal_@var{m}} 5423Compute the bitwise @code{AND}/@code{IOR}/@code{XOR} reduction of the elements 5424of a vector of mode @var{m}. Operand 1 is the vector input and operand 0 5425is the scalar result. The mode of the scalar result is the same as one 5426element of @var{m}. 5427 5428@cindex @code{extract_last_@var{m}} instruction pattern 5429@item @code{extract_last_@var{m}} 5430Find the last set bit in mask operand 1 and extract the associated element 5431of vector operand 2. Store the result in scalar operand 0. Operand 2 5432has vector mode @var{m} while operand 0 has the mode appropriate for one 5433element of @var{m}. Operand 1 has the usual mask mode for vectors of mode 5434@var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}. 5435 5436@cindex @code{fold_extract_last_@var{m}} instruction pattern 5437@item @code{fold_extract_last_@var{m}} 5438If any bits of mask operand 2 are set, find the last set bit, extract 5439the associated element from vector operand 3, and store the result 5440in operand 0. Store operand 1 in operand 0 otherwise. Operand 3 5441has mode @var{m} and operands 0 and 1 have the mode appropriate for 5442one element of @var{m}. Operand 2 has the usual mask mode for vectors 5443of mode @var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}. 5444 5445@cindex @code{fold_left_plus_@var{m}} instruction pattern 5446@item @code{fold_left_plus_@var{m}} 5447Take scalar operand 1 and successively add each element from vector 5448operand 2. Store the result in scalar operand 0. The vector has 5449mode @var{m} and the scalars have the mode appropriate for one 5450element of @var{m}. The operation is strictly in-order: there is 5451no reassociation. 5452 5453@cindex @code{mask_fold_left_plus_@var{m}} instruction pattern 5454@item @code{mask_fold_left_plus_@var{m}} 5455Like @samp{fold_left_plus_@var{m}}, but takes an additional mask operand 5456(operand 3) that specifies which elements of the source vector should be added. 5457 5458@cindex @code{sdot_prod@var{m}} instruction pattern 5459@item @samp{sdot_prod@var{m}} 5460 5461Compute the sum of the products of two signed elements. 5462Operand 1 and operand 2 are of the same mode. Their 5463product, which is of a wider mode, is computed and added to operand 3. 5464Operand 3 is of a mode equal or wider than the mode of the product. The 5465result is placed in operand 0, which is of the same mode as operand 3. 5466 5467Semantically the expressions perform the multiplication in the following signs 5468 5469@smallexample 5470sdot<signed op0, signed op1, signed op2, signed op3> == 5471 op0 = sign-ext (op1) * sign-ext (op2) + op3 5472@dots{} 5473@end smallexample 5474 5475@cindex @code{udot_prod@var{m}} instruction pattern 5476@item @samp{udot_prod@var{m}} 5477 5478Compute the sum of the products of two unsigned elements. 5479Operand 1 and operand 2 are of the same mode. Their 5480product, which is of a wider mode, is computed and added to operand 3. 5481Operand 3 is of a mode equal or wider than the mode of the product. The 5482result is placed in operand 0, which is of the same mode as operand 3. 5483 5484Semantically the expressions perform the multiplication in the following signs 5485 5486@smallexample 5487udot<unsigned op0, unsigned op1, unsigned op2, unsigned op3> == 5488 op0 = zero-ext (op1) * zero-ext (op2) + op3 5489@dots{} 5490@end smallexample 5491 5492@cindex @code{usdot_prod@var{m}} instruction pattern 5493@item @samp{usdot_prod@var{m}} 5494Compute the sum of the products of elements of different signs. 5495Operand 1 must be unsigned and operand 2 signed. Their 5496product, which is of a wider mode, is computed and added to operand 3. 5497Operand 3 is of a mode equal or wider than the mode of the product. The 5498result is placed in operand 0, which is of the same mode as operand 3. 5499 5500Semantically the expressions perform the multiplication in the following signs 5501 5502@smallexample 5503usdot<signed op0, unsigned op1, signed op2, signed op3> == 5504 op0 = ((signed-conv) zero-ext (op1)) * sign-ext (op2) + op3 5505@dots{} 5506@end smallexample 5507 5508@cindex @code{ssad@var{m}} instruction pattern 5509@item @samp{ssad@var{m}} 5510@cindex @code{usad@var{m}} instruction pattern 5511@item @samp{usad@var{m}} 5512Compute the sum of absolute differences of two signed/unsigned elements. 5513Operand 1 and operand 2 are of the same mode. Their absolute difference, which 5514is of a wider mode, is computed and added to operand 3. Operand 3 is of a mode 5515equal or wider than the mode of the absolute difference. The result is placed 5516in operand 0, which is of the same mode as operand 3. 5517 5518@cindex @code{widen_ssum@var{m3}} instruction pattern 5519@item @samp{widen_ssum@var{m3}} 5520@cindex @code{widen_usum@var{m3}} instruction pattern 5521@itemx @samp{widen_usum@var{m3}} 5522Operands 0 and 2 are of the same mode, which is wider than the mode of 5523operand 1. Add operand 1 to operand 2 and place the widened result in 5524operand 0. (This is used express accumulation of elements into an accumulator 5525of a wider mode.) 5526 5527@cindex @code{smulhs@var{m3}} instruction pattern 5528@item @samp{smulhs@var{m3}} 5529@cindex @code{umulhs@var{m3}} instruction pattern 5530@itemx @samp{umulhs@var{m3}} 5531Signed/unsigned multiply high with scale. This is equivalent to the C code: 5532@smallexample 5533narrow op0, op1, op2; 5534@dots{} 5535op0 = (narrow) (((wide) op1 * (wide) op2) >> (N / 2 - 1)); 5536@end smallexample 5537where the sign of @samp{narrow} determines whether this is a signed 5538or unsigned operation, and @var{N} is the size of @samp{wide} in bits. 5539 5540@cindex @code{smulhrs@var{m3}} instruction pattern 5541@item @samp{smulhrs@var{m3}} 5542@cindex @code{umulhrs@var{m3}} instruction pattern 5543@itemx @samp{umulhrs@var{m3}} 5544Signed/unsigned multiply high with round and scale. This is 5545equivalent to the C code: 5546@smallexample 5547narrow op0, op1, op2; 5548@dots{} 5549op0 = (narrow) (((((wide) op1 * (wide) op2) >> (N / 2 - 2)) + 1) >> 1); 5550@end smallexample 5551where the sign of @samp{narrow} determines whether this is a signed 5552or unsigned operation, and @var{N} is the size of @samp{wide} in bits. 5553 5554@cindex @code{sdiv_pow2@var{m3}} instruction pattern 5555@item @samp{sdiv_pow2@var{m3}} 5556@cindex @code{sdiv_pow2@var{m3}} instruction pattern 5557@itemx @samp{sdiv_pow2@var{m3}} 5558Signed division by power-of-2 immediate. Equivalent to: 5559@smallexample 5560signed op0, op1; 5561@dots{} 5562op0 = op1 / (1 << imm); 5563@end smallexample 5564 5565@cindex @code{vec_shl_insert_@var{m}} instruction pattern 5566@item @samp{vec_shl_insert_@var{m}} 5567Shift the elements in vector input operand 1 left one element (i.e.@: 5568away from element 0) and fill the vacated element 0 with the scalar 5569in operand 2. Store the result in vector output operand 0. Operands 55700 and 1 have mode @var{m} and operand 2 has the mode appropriate for 5571one element of @var{m}. 5572 5573@cindex @code{vec_shl_@var{m}} instruction pattern 5574@item @samp{vec_shl_@var{m}} 5575Whole vector left shift in bits, i.e.@: away from element 0. 5576Operand 1 is a vector to be shifted. 5577Operand 2 is an integer shift amount in bits. 5578Operand 0 is where the resulting shifted vector is stored. 5579The output and input vectors should have the same modes. 5580 5581@cindex @code{vec_shr_@var{m}} instruction pattern 5582@item @samp{vec_shr_@var{m}} 5583Whole vector right shift in bits, i.e.@: towards element 0. 5584Operand 1 is a vector to be shifted. 5585Operand 2 is an integer shift amount in bits. 5586Operand 0 is where the resulting shifted vector is stored. 5587The output and input vectors should have the same modes. 5588 5589@cindex @code{vec_pack_trunc_@var{m}} instruction pattern 5590@item @samp{vec_pack_trunc_@var{m}} 5591Narrow (demote) and merge the elements of two vectors. Operands 1 and 2 5592are vectors of the same mode having N integral or floating point elements 5593of size S@. Operand 0 is the resulting vector in which 2*N elements of 5594size S/2 are concatenated after narrowing them down using truncation. 5595 5596@cindex @code{vec_pack_sbool_trunc_@var{m}} instruction pattern 5597@item @samp{vec_pack_sbool_trunc_@var{m}} 5598Narrow and merge the elements of two vectors. Operands 1 and 2 are vectors 5599of the same type having N boolean elements. Operand 0 is the resulting 5600vector in which 2*N elements are concatenated. The last operand (operand 3) 5601is the number of elements in the output vector 2*N as a @code{CONST_INT}. 5602This instruction pattern is used when all the vector input and output 5603operands have the same scalar mode @var{m} and thus using 5604@code{vec_pack_trunc_@var{m}} would be ambiguous. 5605 5606@cindex @code{vec_pack_ssat_@var{m}} instruction pattern 5607@cindex @code{vec_pack_usat_@var{m}} instruction pattern 5608@item @samp{vec_pack_ssat_@var{m}}, @samp{vec_pack_usat_@var{m}} 5609Narrow (demote) and merge the elements of two vectors. Operands 1 and 2 5610are vectors of the same mode having N integral elements of size S. 5611Operand 0 is the resulting vector in which the elements of the two input 5612vectors are concatenated after narrowing them down using signed/unsigned 5613saturating arithmetic. 5614 5615@cindex @code{vec_pack_sfix_trunc_@var{m}} instruction pattern 5616@cindex @code{vec_pack_ufix_trunc_@var{m}} instruction pattern 5617@item @samp{vec_pack_sfix_trunc_@var{m}}, @samp{vec_pack_ufix_trunc_@var{m}} 5618Narrow, convert to signed/unsigned integral type and merge the elements 5619of two vectors. Operands 1 and 2 are vectors of the same mode having N 5620floating point elements of size S@. Operand 0 is the resulting vector 5621in which 2*N elements of size S/2 are concatenated. 5622 5623@cindex @code{vec_packs_float_@var{m}} instruction pattern 5624@cindex @code{vec_packu_float_@var{m}} instruction pattern 5625@item @samp{vec_packs_float_@var{m}}, @samp{vec_packu_float_@var{m}} 5626Narrow, convert to floating point type and merge the elements 5627of two vectors. Operands 1 and 2 are vectors of the same mode having N 5628signed/unsigned integral elements of size S@. Operand 0 is the resulting vector 5629in which 2*N elements of size S/2 are concatenated. 5630 5631@cindex @code{vec_unpacks_hi_@var{m}} instruction pattern 5632@cindex @code{vec_unpacks_lo_@var{m}} instruction pattern 5633@item @samp{vec_unpacks_hi_@var{m}}, @samp{vec_unpacks_lo_@var{m}} 5634Extract and widen (promote) the high/low part of a vector of signed 5635integral or floating point elements. The input vector (operand 1) has N 5636elements of size S@. Widen (promote) the high/low elements of the vector 5637using signed or floating point extension and place the resulting N/2 5638values of size 2*S in the output vector (operand 0). 5639 5640@cindex @code{vec_unpacku_hi_@var{m}} instruction pattern 5641@cindex @code{vec_unpacku_lo_@var{m}} instruction pattern 5642@item @samp{vec_unpacku_hi_@var{m}}, @samp{vec_unpacku_lo_@var{m}} 5643Extract and widen (promote) the high/low part of a vector of unsigned 5644integral elements. The input vector (operand 1) has N elements of size S. 5645Widen (promote) the high/low elements of the vector using zero extension and 5646place the resulting N/2 values of size 2*S in the output vector (operand 0). 5647 5648@cindex @code{vec_unpacks_sbool_hi_@var{m}} instruction pattern 5649@cindex @code{vec_unpacks_sbool_lo_@var{m}} instruction pattern 5650@item @samp{vec_unpacks_sbool_hi_@var{m}}, @samp{vec_unpacks_sbool_lo_@var{m}} 5651Extract the high/low part of a vector of boolean elements that have scalar 5652mode @var{m}. The input vector (operand 1) has N elements, the output 5653vector (operand 0) has N/2 elements. The last operand (operand 2) is the 5654number of elements of the input vector N as a @code{CONST_INT}. These 5655patterns are used if both the input and output vectors have the same scalar 5656mode @var{m} and thus using @code{vec_unpacks_hi_@var{m}} or 5657@code{vec_unpacks_lo_@var{m}} would be ambiguous. 5658 5659@cindex @code{vec_unpacks_float_hi_@var{m}} instruction pattern 5660@cindex @code{vec_unpacks_float_lo_@var{m}} instruction pattern 5661@cindex @code{vec_unpacku_float_hi_@var{m}} instruction pattern 5662@cindex @code{vec_unpacku_float_lo_@var{m}} instruction pattern 5663@item @samp{vec_unpacks_float_hi_@var{m}}, @samp{vec_unpacks_float_lo_@var{m}} 5664@itemx @samp{vec_unpacku_float_hi_@var{m}}, @samp{vec_unpacku_float_lo_@var{m}} 5665Extract, convert to floating point type and widen the high/low part of a 5666vector of signed/unsigned integral elements. The input vector (operand 1) 5667has N elements of size S@. Convert the high/low elements of the vector using 5668floating point conversion and place the resulting N/2 values of size 2*S in 5669the output vector (operand 0). 5670 5671@cindex @code{vec_unpack_sfix_trunc_hi_@var{m}} instruction pattern 5672@cindex @code{vec_unpack_sfix_trunc_lo_@var{m}} instruction pattern 5673@cindex @code{vec_unpack_ufix_trunc_hi_@var{m}} instruction pattern 5674@cindex @code{vec_unpack_ufix_trunc_lo_@var{m}} instruction pattern 5675@item @samp{vec_unpack_sfix_trunc_hi_@var{m}}, 5676@itemx @samp{vec_unpack_sfix_trunc_lo_@var{m}} 5677@itemx @samp{vec_unpack_ufix_trunc_hi_@var{m}} 5678@itemx @samp{vec_unpack_ufix_trunc_lo_@var{m}} 5679Extract, convert to signed/unsigned integer type and widen the high/low part of a 5680vector of floating point elements. The input vector (operand 1) 5681has N elements of size S@. Convert the high/low elements of the vector 5682to integers and place the resulting N/2 values of size 2*S in 5683the output vector (operand 0). 5684 5685@cindex @code{vec_widen_umult_hi_@var{m}} instruction pattern 5686@cindex @code{vec_widen_umult_lo_@var{m}} instruction pattern 5687@cindex @code{vec_widen_smult_hi_@var{m}} instruction pattern 5688@cindex @code{vec_widen_smult_lo_@var{m}} instruction pattern 5689@cindex @code{vec_widen_umult_even_@var{m}} instruction pattern 5690@cindex @code{vec_widen_umult_odd_@var{m}} instruction pattern 5691@cindex @code{vec_widen_smult_even_@var{m}} instruction pattern 5692@cindex @code{vec_widen_smult_odd_@var{m}} instruction pattern 5693@item @samp{vec_widen_umult_hi_@var{m}}, @samp{vec_widen_umult_lo_@var{m}} 5694@itemx @samp{vec_widen_smult_hi_@var{m}}, @samp{vec_widen_smult_lo_@var{m}} 5695@itemx @samp{vec_widen_umult_even_@var{m}}, @samp{vec_widen_umult_odd_@var{m}} 5696@itemx @samp{vec_widen_smult_even_@var{m}}, @samp{vec_widen_smult_odd_@var{m}} 5697Signed/Unsigned widening multiplication. The two inputs (operands 1 and 2) 5698are vectors with N signed/unsigned elements of size S@. Multiply the high/low 5699or even/odd elements of the two vectors, and put the N/2 products of size 2*S 5700in the output vector (operand 0). A target shouldn't implement even/odd pattern 5701pair if it is less efficient than lo/hi one. 5702 5703@cindex @code{vec_widen_ushiftl_hi_@var{m}} instruction pattern 5704@cindex @code{vec_widen_ushiftl_lo_@var{m}} instruction pattern 5705@cindex @code{vec_widen_sshiftl_hi_@var{m}} instruction pattern 5706@cindex @code{vec_widen_sshiftl_lo_@var{m}} instruction pattern 5707@item @samp{vec_widen_ushiftl_hi_@var{m}}, @samp{vec_widen_ushiftl_lo_@var{m}} 5708@itemx @samp{vec_widen_sshiftl_hi_@var{m}}, @samp{vec_widen_sshiftl_lo_@var{m}} 5709Signed/Unsigned widening shift left. The first input (operand 1) is a vector 5710with N signed/unsigned elements of size S@. Operand 2 is a constant. Shift 5711the high/low elements of operand 1, and put the N/2 results of size 2*S in the 5712output vector (operand 0). 5713 5714@cindex @code{vec_widen_saddl_hi_@var{m}} instruction pattern 5715@cindex @code{vec_widen_saddl_lo_@var{m}} instruction pattern 5716@cindex @code{vec_widen_uaddl_hi_@var{m}} instruction pattern 5717@cindex @code{vec_widen_uaddl_lo_@var{m}} instruction pattern 5718@item @samp{vec_widen_uaddl_hi_@var{m}}, @samp{vec_widen_uaddl_lo_@var{m}} 5719@itemx @samp{vec_widen_saddl_hi_@var{m}}, @samp{vec_widen_saddl_lo_@var{m}} 5720Signed/Unsigned widening add long. Operands 1 and 2 are vectors with N 5721signed/unsigned elements of size S@. Add the high/low elements of 1 and 2 5722together, widen the resulting elements and put the N/2 results of size 2*S in 5723the output vector (operand 0). 5724 5725@cindex @code{vec_widen_ssubl_hi_@var{m}} instruction pattern 5726@cindex @code{vec_widen_ssubl_lo_@var{m}} instruction pattern 5727@cindex @code{vec_widen_usubl_hi_@var{m}} instruction pattern 5728@cindex @code{vec_widen_usubl_lo_@var{m}} instruction pattern 5729@item @samp{vec_widen_usubl_hi_@var{m}}, @samp{vec_widen_usubl_lo_@var{m}} 5730@itemx @samp{vec_widen_ssubl_hi_@var{m}}, @samp{vec_widen_ssubl_lo_@var{m}} 5731Signed/Unsigned widening subtract long. Operands 1 and 2 are vectors with N 5732signed/unsigned elements of size S@. Subtract the high/low elements of 2 from 57331 and widen the resulting elements. Put the N/2 results of size 2*S in the 5734output vector (operand 0). 5735 5736@cindex @code{vec_addsub@var{m}3} instruction pattern 5737@item @samp{vec_addsub@var{m}3} 5738Alternating subtract, add with even lanes doing subtract and odd 5739lanes doing addition. Operands 1 and 2 and the outout operand are vectors 5740with mode @var{m}. 5741 5742@cindex @code{vec_fmaddsub@var{m}4} instruction pattern 5743@item @samp{vec_fmaddsub@var{m}4} 5744Alternating multiply subtract, add with even lanes doing subtract and odd 5745lanes doing addition of the third operand to the multiplication result 5746of the first two operands. Operands 1, 2 and 3 and the outout operand are vectors 5747with mode @var{m}. 5748 5749@cindex @code{vec_fmsubadd@var{m}4} instruction pattern 5750@item @samp{vec_fmsubadd@var{m}4} 5751Alternating multiply add, subtract with even lanes doing addition and odd 5752lanes doing subtraction of the third operand to the multiplication result 5753of the first two operands. Operands 1, 2 and 3 and the outout operand are vectors 5754with mode @var{m}. 5755 5756These instructions are not allowed to @code{FAIL}. 5757 5758@cindex @code{mulhisi3} instruction pattern 5759@item @samp{mulhisi3} 5760Multiply operands 1 and 2, which have mode @code{HImode}, and store 5761a @code{SImode} product in operand 0. 5762 5763@cindex @code{mulqihi3} instruction pattern 5764@cindex @code{mulsidi3} instruction pattern 5765@item @samp{mulqihi3}, @samp{mulsidi3} 5766Similar widening-multiplication instructions of other widths. 5767 5768@cindex @code{umulqihi3} instruction pattern 5769@cindex @code{umulhisi3} instruction pattern 5770@cindex @code{umulsidi3} instruction pattern 5771@item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3} 5772Similar widening-multiplication instructions that do unsigned 5773multiplication. 5774 5775@cindex @code{usmulqihi3} instruction pattern 5776@cindex @code{usmulhisi3} instruction pattern 5777@cindex @code{usmulsidi3} instruction pattern 5778@item @samp{usmulqihi3}, @samp{usmulhisi3}, @samp{usmulsidi3} 5779Similar widening-multiplication instructions that interpret the first 5780operand as unsigned and the second operand as signed, then do a signed 5781multiplication. 5782 5783@cindex @code{smul@var{m}3_highpart} instruction pattern 5784@item @samp{smul@var{m}3_highpart} 5785Perform a signed multiplication of operands 1 and 2, which have mode 5786@var{m}, and store the most significant half of the product in operand 0. 5787The least significant half of the product is discarded. This may be 5788represented in RTL using a @code{smul_highpart} RTX expression. 5789 5790@cindex @code{umul@var{m}3_highpart} instruction pattern 5791@item @samp{umul@var{m}3_highpart} 5792Similar, but the multiplication is unsigned. This may be represented 5793in RTL using an @code{umul_highpart} RTX expression. 5794 5795@cindex @code{madd@var{m}@var{n}4} instruction pattern 5796@item @samp{madd@var{m}@var{n}4} 5797Multiply operands 1 and 2, sign-extend them to mode @var{n}, add 5798operand 3, and store the result in operand 0. Operands 1 and 2 5799have mode @var{m} and operands 0 and 3 have mode @var{n}. 5800Both modes must be integer or fixed-point modes and @var{n} must be twice 5801the size of @var{m}. 5802 5803In other words, @code{madd@var{m}@var{n}4} is like 5804@code{mul@var{m}@var{n}3} except that it also adds operand 3. 5805 5806These instructions are not allowed to @code{FAIL}. 5807 5808@cindex @code{umadd@var{m}@var{n}4} instruction pattern 5809@item @samp{umadd@var{m}@var{n}4} 5810Like @code{madd@var{m}@var{n}4}, but zero-extend the multiplication 5811operands instead of sign-extending them. 5812 5813@cindex @code{ssmadd@var{m}@var{n}4} instruction pattern 5814@item @samp{ssmadd@var{m}@var{n}4} 5815Like @code{madd@var{m}@var{n}4}, but all involved operations must be 5816signed-saturating. 5817 5818@cindex @code{usmadd@var{m}@var{n}4} instruction pattern 5819@item @samp{usmadd@var{m}@var{n}4} 5820Like @code{umadd@var{m}@var{n}4}, but all involved operations must be 5821unsigned-saturating. 5822 5823@cindex @code{msub@var{m}@var{n}4} instruction pattern 5824@item @samp{msub@var{m}@var{n}4} 5825Multiply operands 1 and 2, sign-extend them to mode @var{n}, subtract the 5826result from operand 3, and store the result in operand 0. Operands 1 and 2 5827have mode @var{m} and operands 0 and 3 have mode @var{n}. 5828Both modes must be integer or fixed-point modes and @var{n} must be twice 5829the size of @var{m}. 5830 5831In other words, @code{msub@var{m}@var{n}4} is like 5832@code{mul@var{m}@var{n}3} except that it also subtracts the result 5833from operand 3. 5834 5835These instructions are not allowed to @code{FAIL}. 5836 5837@cindex @code{umsub@var{m}@var{n}4} instruction pattern 5838@item @samp{umsub@var{m}@var{n}4} 5839Like @code{msub@var{m}@var{n}4}, but zero-extend the multiplication 5840operands instead of sign-extending them. 5841 5842@cindex @code{ssmsub@var{m}@var{n}4} instruction pattern 5843@item @samp{ssmsub@var{m}@var{n}4} 5844Like @code{msub@var{m}@var{n}4}, but all involved operations must be 5845signed-saturating. 5846 5847@cindex @code{usmsub@var{m}@var{n}4} instruction pattern 5848@item @samp{usmsub@var{m}@var{n}4} 5849Like @code{umsub@var{m}@var{n}4}, but all involved operations must be 5850unsigned-saturating. 5851 5852@cindex @code{divmod@var{m}4} instruction pattern 5853@item @samp{divmod@var{m}4} 5854Signed division that produces both a quotient and a remainder. 5855Operand 1 is divided by operand 2 to produce a quotient stored 5856in operand 0 and a remainder stored in operand 3. 5857 5858For machines with an instruction that produces both a quotient and a 5859remainder, provide a pattern for @samp{divmod@var{m}4} but do not 5860provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}. This 5861allows optimization in the relatively common case when both the quotient 5862and remainder are computed. 5863 5864If an instruction that just produces a quotient or just a remainder 5865exists and is more efficient than the instruction that produces both, 5866write the output routine of @samp{divmod@var{m}4} to call 5867@code{find_reg_note} and look for a @code{REG_UNUSED} note on the 5868quotient or remainder and generate the appropriate instruction. 5869 5870@cindex @code{udivmod@var{m}4} instruction pattern 5871@item @samp{udivmod@var{m}4} 5872Similar, but does unsigned division. 5873 5874@anchor{shift patterns} 5875@cindex @code{ashl@var{m}3} instruction pattern 5876@cindex @code{ssashl@var{m}3} instruction pattern 5877@cindex @code{usashl@var{m}3} instruction pattern 5878@item @samp{ashl@var{m}3}, @samp{ssashl@var{m}3}, @samp{usashl@var{m}3} 5879Arithmetic-shift operand 1 left by a number of bits specified by operand 58802, and store the result in operand 0. Here @var{m} is the mode of 5881operand 0 and operand 1; operand 2's mode is specified by the 5882instruction pattern, and the compiler will convert the operand to that 5883mode before generating the instruction. The shift or rotate expander 5884or instruction pattern should explicitly specify the mode of the operand 2, 5885it should never be @code{VOIDmode}. The meaning of out-of-range shift 5886counts can optionally be specified by @code{TARGET_SHIFT_TRUNCATION_MASK}. 5887@xref{TARGET_SHIFT_TRUNCATION_MASK}. Operand 2 is always a scalar type. 5888 5889@cindex @code{ashr@var{m}3} instruction pattern 5890@cindex @code{lshr@var{m}3} instruction pattern 5891@cindex @code{rotl@var{m}3} instruction pattern 5892@cindex @code{rotr@var{m}3} instruction pattern 5893@item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3} 5894Other shift and rotate instructions, analogous to the 5895@code{ashl@var{m}3} instructions. Operand 2 is always a scalar type. 5896 5897@cindex @code{vashl@var{m}3} instruction pattern 5898@cindex @code{vashr@var{m}3} instruction pattern 5899@cindex @code{vlshr@var{m}3} instruction pattern 5900@cindex @code{vrotl@var{m}3} instruction pattern 5901@cindex @code{vrotr@var{m}3} instruction pattern 5902@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} 5903Vector shift and rotate instructions that take vectors as operand 2 5904instead of a scalar type. 5905 5906@cindex @code{avg@var{m}3_floor} instruction pattern 5907@cindex @code{uavg@var{m}3_floor} instruction pattern 5908@item @samp{avg@var{m}3_floor} 5909@itemx @samp{uavg@var{m}3_floor} 5910Signed and unsigned average instructions. These instructions add 5911operands 1 and 2 without truncation, divide the result by 2, 5912round towards -Inf, and store the result in operand 0. This is 5913equivalent to the C code: 5914@smallexample 5915narrow op0, op1, op2; 5916@dots{} 5917op0 = (narrow) (((wide) op1 + (wide) op2) >> 1); 5918@end smallexample 5919where the sign of @samp{narrow} determines whether this is a signed 5920or unsigned operation. 5921 5922@cindex @code{avg@var{m}3_ceil} instruction pattern 5923@cindex @code{uavg@var{m}3_ceil} instruction pattern 5924@item @samp{avg@var{m}3_ceil} 5925@itemx @samp{uavg@var{m}3_ceil} 5926Like @samp{avg@var{m}3_floor} and @samp{uavg@var{m}3_floor}, but round 5927towards +Inf. This is equivalent to the C code: 5928@smallexample 5929narrow op0, op1, op2; 5930@dots{} 5931op0 = (narrow) (((wide) op1 + (wide) op2 + 1) >> 1); 5932@end smallexample 5933 5934@cindex @code{bswap@var{m}2} instruction pattern 5935@item @samp{bswap@var{m}2} 5936Reverse the order of bytes of operand 1 and store the result in operand 0. 5937 5938@cindex @code{neg@var{m}2} instruction pattern 5939@cindex @code{ssneg@var{m}2} instruction pattern 5940@cindex @code{usneg@var{m}2} instruction pattern 5941@item @samp{neg@var{m}2}, @samp{ssneg@var{m}2}, @samp{usneg@var{m}2} 5942Negate operand 1 and store the result in operand 0. 5943 5944@cindex @code{negv@var{m}3} instruction pattern 5945@item @samp{negv@var{m}3} 5946Like @code{neg@var{m}2} but takes a @code{code_label} as operand 2 and 5947emits code to jump to it if signed overflow occurs during the negation. 5948 5949@cindex @code{abs@var{m}2} instruction pattern 5950@item @samp{abs@var{m}2} 5951Store the absolute value of operand 1 into operand 0. 5952 5953@cindex @code{sqrt@var{m}2} instruction pattern 5954@item @samp{sqrt@var{m}2} 5955Store the square root 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{rsqrt@var{m}2} instruction pattern 5961@item @samp{rsqrt@var{m}2} 5962Store the reciprocal of the square root of operand 1 into operand 0. 5963Both operands have mode @var{m}, which is a scalar or vector 5964floating-point mode. 5965 5966On most architectures this pattern is only approximate, so either 5967its C condition or the @code{TARGET_OPTAB_SUPPORTED_P} hook should 5968check for the appropriate math flags. (Using the C condition is 5969more direct, but using @code{TARGET_OPTAB_SUPPORTED_P} can be useful 5970if a target-specific built-in also uses the @samp{rsqrt@var{m}2} 5971pattern.) 5972 5973This pattern is not allowed to @code{FAIL}. 5974 5975@cindex @code{fmod@var{m}3} instruction pattern 5976@item @samp{fmod@var{m}3} 5977Store the remainder of dividing operand 1 by operand 2 into 5978operand 0, rounded towards zero to an integer. All operands have 5979mode @var{m}, which is a scalar or vector floating-point mode. 5980 5981This pattern is not allowed to @code{FAIL}. 5982 5983@cindex @code{remainder@var{m}3} instruction pattern 5984@item @samp{remainder@var{m}3} 5985Store the remainder of dividing operand 1 by operand 2 into 5986operand 0, rounded to the nearest integer. All operands have 5987mode @var{m}, which is a scalar or vector floating-point mode. 5988 5989This pattern is not allowed to @code{FAIL}. 5990 5991@cindex @code{scalb@var{m}3} instruction pattern 5992@item @samp{scalb@var{m}3} 5993Raise @code{FLT_RADIX} to the power of operand 2, multiply it by 5994operand 1, and store the result in operand 0. All operands have 5995mode @var{m}, which is a scalar or vector floating-point mode. 5996 5997This pattern is not allowed to @code{FAIL}. 5998 5999@cindex @code{ldexp@var{m}3} instruction pattern 6000@item @samp{ldexp@var{m}3} 6001Raise 2 to the power of operand 2, multiply it by operand 1, and store 6002the result in operand 0. Operands 0 and 1 have mode @var{m}, which is 6003a scalar or vector floating-point mode. Operand 2's mode has 6004the same number of elements as @var{m} and each element is wide 6005enough to store an @code{int}. The integers are signed. 6006 6007This pattern is not allowed to @code{FAIL}. 6008 6009@cindex @code{cos@var{m}2} instruction pattern 6010@item @samp{cos@var{m}2} 6011Store the cosine of operand 1 into operand 0. Both operands have 6012mode @var{m}, which is a scalar or vector floating-point mode. 6013 6014This pattern is not allowed to @code{FAIL}. 6015 6016@cindex @code{sin@var{m}2} instruction pattern 6017@item @samp{sin@var{m}2} 6018Store the sine of operand 1 into operand 0. Both operands have 6019mode @var{m}, which is a scalar or vector floating-point mode. 6020 6021This pattern is not allowed to @code{FAIL}. 6022 6023@cindex @code{sincos@var{m}3} instruction pattern 6024@item @samp{sincos@var{m}3} 6025Store the cosine of operand 2 into operand 0 and the sine of 6026operand 2 into operand 1. All operands have mode @var{m}, 6027which is a scalar or vector floating-point mode. 6028 6029Targets that can calculate the sine and cosine simultaneously can 6030implement this pattern as opposed to implementing individual 6031@code{sin@var{m}2} and @code{cos@var{m}2} patterns. The @code{sin} 6032and @code{cos} built-in functions will then be expanded to the 6033@code{sincos@var{m}3} pattern, with one of the output values 6034left unused. 6035 6036@cindex @code{tan@var{m}2} instruction pattern 6037@item @samp{tan@var{m}2} 6038Store the tangent of operand 1 into operand 0. Both operands have 6039mode @var{m}, which is a scalar or vector floating-point mode. 6040 6041This pattern is not allowed to @code{FAIL}. 6042 6043@cindex @code{asin@var{m}2} instruction pattern 6044@item @samp{asin@var{m}2} 6045Store the arc sine of operand 1 into operand 0. Both operands have 6046mode @var{m}, which is a scalar or vector floating-point mode. 6047 6048This pattern is not allowed to @code{FAIL}. 6049 6050@cindex @code{acos@var{m}2} instruction pattern 6051@item @samp{acos@var{m}2} 6052Store the arc cosine of operand 1 into operand 0. Both operands have 6053mode @var{m}, which is a scalar or vector floating-point mode. 6054 6055This pattern is not allowed to @code{FAIL}. 6056 6057@cindex @code{atan@var{m}2} instruction pattern 6058@item @samp{atan@var{m}2} 6059Store the arc tangent of operand 1 into operand 0. Both operands have 6060mode @var{m}, which is a scalar or vector floating-point mode. 6061 6062This pattern is not allowed to @code{FAIL}. 6063 6064@cindex @code{exp@var{m}2} instruction pattern 6065@item @samp{exp@var{m}2} 6066Raise e (the base of natural logarithms) to the power of operand 1 6067and store the result in operand 0. Both operands have mode @var{m}, 6068which is a scalar or vector floating-point mode. 6069 6070This pattern is not allowed to @code{FAIL}. 6071 6072@cindex @code{expm1@var{m}2} instruction pattern 6073@item @samp{expm1@var{m}2} 6074Raise e (the base of natural logarithms) to the power of operand 1, 6075subtract 1, and store the result in operand 0. Both operands have 6076mode @var{m}, which is a scalar or vector floating-point mode. 6077 6078For inputs close to zero, the pattern is expected to be more 6079accurate than a separate @code{exp@var{m}2} and @code{sub@var{m}3} 6080would be. 6081 6082This pattern is not allowed to @code{FAIL}. 6083 6084@cindex @code{exp10@var{m}2} instruction pattern 6085@item @samp{exp10@var{m}2} 6086Raise 10 to the power of operand 1 and store the result in operand 0. 6087Both operands have mode @var{m}, which is a scalar or vector 6088floating-point mode. 6089 6090This pattern is not allowed to @code{FAIL}. 6091 6092@cindex @code{exp2@var{m}2} instruction pattern 6093@item @samp{exp2@var{m}2} 6094Raise 2 to the power of operand 1 and store the result in operand 0. 6095Both operands have mode @var{m}, which is a scalar or vector 6096floating-point mode. 6097 6098This pattern is not allowed to @code{FAIL}. 6099 6100@cindex @code{log@var{m}2} instruction pattern 6101@item @samp{log@var{m}2} 6102Store the natural logarithm of operand 1 into operand 0. Both operands 6103have mode @var{m}, which is a scalar or vector floating-point mode. 6104 6105This pattern is not allowed to @code{FAIL}. 6106 6107@cindex @code{log1p@var{m}2} instruction pattern 6108@item @samp{log1p@var{m}2} 6109Add 1 to operand 1, compute the natural logarithm, and store 6110the result in operand 0. Both operands have mode @var{m}, which is 6111a scalar or vector floating-point mode. 6112 6113For inputs close to zero, the pattern is expected to be more 6114accurate than a separate @code{add@var{m}3} and @code{log@var{m}2} 6115would be. 6116 6117This pattern is not allowed to @code{FAIL}. 6118 6119@cindex @code{log10@var{m}2} instruction pattern 6120@item @samp{log10@var{m}2} 6121Store the base-10 logarithm of operand 1 into operand 0. Both operands 6122have mode @var{m}, which is a scalar or vector floating-point mode. 6123 6124This pattern is not allowed to @code{FAIL}. 6125 6126@cindex @code{log2@var{m}2} instruction pattern 6127@item @samp{log2@var{m}2} 6128Store the base-2 logarithm of operand 1 into operand 0. Both operands 6129have mode @var{m}, which is a scalar or vector floating-point mode. 6130 6131This pattern is not allowed to @code{FAIL}. 6132 6133@cindex @code{logb@var{m}2} instruction pattern 6134@item @samp{logb@var{m}2} 6135Store the base-@code{FLT_RADIX} logarithm of operand 1 into operand 0. 6136Both operands have mode @var{m}, which is a scalar or vector 6137floating-point mode. 6138 6139This pattern is not allowed to @code{FAIL}. 6140 6141@cindex @code{significand@var{m}2} instruction pattern 6142@item @samp{significand@var{m}2} 6143Store the significand of floating-point operand 1 in operand 0. 6144Both operands have mode @var{m}, which is a scalar or vector 6145floating-point mode. 6146 6147This pattern is not allowed to @code{FAIL}. 6148 6149@cindex @code{pow@var{m}3} instruction pattern 6150@item @samp{pow@var{m}3} 6151Store the value of operand 1 raised to the exponent operand 2 6152into operand 0. All operands have mode @var{m}, which is a scalar 6153or vector floating-point mode. 6154 6155This pattern is not allowed to @code{FAIL}. 6156 6157@cindex @code{atan2@var{m}3} instruction pattern 6158@item @samp{atan2@var{m}3} 6159Store the arc tangent (inverse tangent) of operand 1 divided by 6160operand 2 into operand 0, using the signs of both arguments to 6161determine the quadrant of the result. All operands have mode 6162@var{m}, which is a scalar or vector floating-point mode. 6163 6164This pattern is not allowed to @code{FAIL}. 6165 6166@cindex @code{floor@var{m}2} instruction pattern 6167@item @samp{floor@var{m}2} 6168Store the largest integral value not greater than operand 1 in operand 0. 6169Both operands have mode @var{m}, which is a scalar or vector 6170floating-point mode. If @option{-ffp-int-builtin-inexact} is in 6171effect, the ``inexact'' exception may be raised for noninteger 6172operands; otherwise, it may not. 6173 6174This pattern is not allowed to @code{FAIL}. 6175 6176@cindex @code{btrunc@var{m}2} instruction pattern 6177@item @samp{btrunc@var{m}2} 6178Round operand 1 to an integer, towards zero, and store the result in 6179operand 0. Both operands have mode @var{m}, which is a scalar or 6180vector floating-point mode. If @option{-ffp-int-builtin-inexact} is 6181in effect, the ``inexact'' exception may be raised for noninteger 6182operands; otherwise, it may not. 6183 6184This pattern is not allowed to @code{FAIL}. 6185 6186@cindex @code{round@var{m}2} instruction pattern 6187@item @samp{round@var{m}2} 6188Round operand 1 to the nearest integer, rounding away from zero in the 6189event of a tie, and store the result in operand 0. Both operands have 6190mode @var{m}, which is a scalar or vector floating-point mode. If 6191@option{-ffp-int-builtin-inexact} is in effect, the ``inexact'' 6192exception may be raised for noninteger operands; otherwise, it may 6193not. 6194 6195This pattern is not allowed to @code{FAIL}. 6196 6197@cindex @code{ceil@var{m}2} instruction pattern 6198@item @samp{ceil@var{m}2} 6199Store the smallest integral value not less than operand 1 in operand 0. 6200Both operands have mode @var{m}, which is a scalar or vector 6201floating-point mode. If @option{-ffp-int-builtin-inexact} is in 6202effect, the ``inexact'' exception may be raised for noninteger 6203operands; otherwise, it may not. 6204 6205This pattern is not allowed to @code{FAIL}. 6206 6207@cindex @code{nearbyint@var{m}2} instruction pattern 6208@item @samp{nearbyint@var{m}2} 6209Round operand 1 to an integer, using the current rounding mode, and 6210store the result in operand 0. Do not raise an inexact condition when 6211the result is different from the argument. Both operands have mode 6212@var{m}, which is a scalar or vector floating-point mode. 6213 6214This pattern is not allowed to @code{FAIL}. 6215 6216@cindex @code{rint@var{m}2} instruction pattern 6217@item @samp{rint@var{m}2} 6218Round operand 1 to an integer, using the current rounding mode, and 6219store the result in operand 0. Raise an inexact condition when 6220the result is different from the argument. Both operands have mode 6221@var{m}, which is a scalar or vector floating-point mode. 6222 6223This pattern is not allowed to @code{FAIL}. 6224 6225@cindex @code{lrint@var{m}@var{n}2} 6226@item @samp{lrint@var{m}@var{n}2} 6227Convert operand 1 (valid for floating point mode @var{m}) to fixed 6228point mode @var{n} as a signed number according to the current 6229rounding mode and store in operand 0 (which has mode @var{n}). 6230 6231@cindex @code{lround@var{m}@var{n}2} 6232@item @samp{lround@var{m}@var{n}2} 6233Convert operand 1 (valid for floating point mode @var{m}) to fixed 6234point mode @var{n} as a signed number rounding to nearest and away 6235from zero and store in operand 0 (which has mode @var{n}). 6236 6237@cindex @code{lfloor@var{m}@var{n}2} 6238@item @samp{lfloor@var{m}@var{n}2} 6239Convert operand 1 (valid for floating point mode @var{m}) to fixed 6240point mode @var{n} as a signed number rounding down and store in 6241operand 0 (which has mode @var{n}). 6242 6243@cindex @code{lceil@var{m}@var{n}2} 6244@item @samp{lceil@var{m}@var{n}2} 6245Convert operand 1 (valid for floating point mode @var{m}) to fixed 6246point mode @var{n} as a signed number rounding up and store in 6247operand 0 (which has mode @var{n}). 6248 6249@cindex @code{copysign@var{m}3} instruction pattern 6250@item @samp{copysign@var{m}3} 6251Store a value with the magnitude of operand 1 and the sign of operand 62522 into operand 0. All operands have mode @var{m}, which is a scalar or 6253vector floating-point mode. 6254 6255This pattern is not allowed to @code{FAIL}. 6256 6257@cindex @code{xorsign@var{m}3} instruction pattern 6258@item @samp{xorsign@var{m}3} 6259Equivalent to @samp{op0 = op1 * copysign (1.0, op2)}: store a value with 6260the magnitude of operand 1 and the sign of operand 2 into operand 0. 6261All operands have mode @var{m}, which is a scalar or vector 6262floating-point mode. 6263 6264This pattern is not allowed to @code{FAIL}. 6265 6266@cindex @code{cadd90@var{m}3} instruction pattern 6267@item @samp{cadd90@var{m}3} 6268Perform vector add and subtract on even/odd number pairs. The operation being 6269matched is semantically described as 6270 6271@smallexample 6272 for (int i = 0; i < N; i += 2) 6273 @{ 6274 c[i] = a[i] - b[i+1]; 6275 c[i+1] = a[i+1] + b[i]; 6276 @} 6277@end smallexample 6278 6279This operation is semantically equivalent to performing a vector addition of 6280complex numbers in operand 1 with operand 2 rotated by 90 degrees around 6281the argand plane and storing the result in operand 0. 6282 6283In GCC lane ordering the real part of the number must be in the even lanes with 6284the imaginary part in the odd lanes. 6285 6286The operation is only supported for vector modes @var{m}. 6287 6288This pattern is not allowed to @code{FAIL}. 6289 6290@cindex @code{cadd270@var{m}3} instruction pattern 6291@item @samp{cadd270@var{m}3} 6292Perform vector add and subtract on even/odd number pairs. The operation being 6293matched is semantically described as 6294 6295@smallexample 6296 for (int i = 0; i < N; i += 2) 6297 @{ 6298 c[i] = a[i] + b[i+1]; 6299 c[i+1] = a[i+1] - b[i]; 6300 @} 6301@end smallexample 6302 6303This operation is semantically equivalent to performing a vector addition of 6304complex numbers in operand 1 with operand 2 rotated by 270 degrees around 6305the argand plane and storing the result in operand 0. 6306 6307In GCC lane ordering the real part of the number must be in the even lanes with 6308the imaginary part in the odd lanes. 6309 6310The operation is only supported for vector modes @var{m}. 6311 6312This pattern is not allowed to @code{FAIL}. 6313 6314@cindex @code{cmla@var{m}4} instruction pattern 6315@item @samp{cmla@var{m}4} 6316Perform a vector multiply and accumulate that is semantically the same as 6317a multiply and accumulate of complex numbers. 6318 6319@smallexample 6320 complex TYPE c[N]; 6321 complex TYPE a[N]; 6322 complex TYPE b[N]; 6323 for (int i = 0; i < N; i += 1) 6324 @{ 6325 c[i] += a[i] * b[i]; 6326 @} 6327@end smallexample 6328 6329In GCC lane ordering the real part of the number must be in the even lanes with 6330the imaginary part in the odd lanes. 6331 6332The operation is only supported for vector modes @var{m}. 6333 6334This pattern is not allowed to @code{FAIL}. 6335 6336@cindex @code{cmla_conj@var{m}4} instruction pattern 6337@item @samp{cmla_conj@var{m}4} 6338Perform a vector multiply by conjugate and accumulate that is semantically 6339the same as a multiply and accumulate of complex numbers where the second 6340multiply arguments is conjugated. 6341 6342@smallexample 6343 complex TYPE c[N]; 6344 complex TYPE a[N]; 6345 complex TYPE b[N]; 6346 for (int i = 0; i < N; i += 1) 6347 @{ 6348 c[i] += a[i] * conj (b[i]); 6349 @} 6350@end smallexample 6351 6352In GCC lane ordering the real part of the number must be in the even lanes with 6353the imaginary part in the odd lanes. 6354 6355The operation is only supported for vector modes @var{m}. 6356 6357This pattern is not allowed to @code{FAIL}. 6358 6359@cindex @code{cmls@var{m}4} instruction pattern 6360@item @samp{cmls@var{m}4} 6361Perform a vector multiply and subtract that is semantically the same as 6362a multiply and subtract of complex numbers. 6363 6364@smallexample 6365 complex TYPE c[N]; 6366 complex TYPE a[N]; 6367 complex TYPE b[N]; 6368 for (int i = 0; i < N; i += 1) 6369 @{ 6370 c[i] -= a[i] * b[i]; 6371 @} 6372@end smallexample 6373 6374In GCC lane ordering the real part of the number must be in the even lanes with 6375the imaginary part in the odd lanes. 6376 6377The operation is only supported for vector modes @var{m}. 6378 6379This pattern is not allowed to @code{FAIL}. 6380 6381@cindex @code{cmls_conj@var{m}4} instruction pattern 6382@item @samp{cmls_conj@var{m}4} 6383Perform a vector multiply by conjugate and subtract that is semantically 6384the same as a multiply and subtract of complex numbers where the second 6385multiply arguments is conjugated. 6386 6387@smallexample 6388 complex TYPE c[N]; 6389 complex TYPE a[N]; 6390 complex TYPE b[N]; 6391 for (int i = 0; i < N; i += 1) 6392 @{ 6393 c[i] -= a[i] * conj (b[i]); 6394 @} 6395@end smallexample 6396 6397In GCC lane ordering the real part of the number must be in the even lanes with 6398the imaginary part in the odd lanes. 6399 6400The operation is only supported for vector modes @var{m}. 6401 6402This pattern is not allowed to @code{FAIL}. 6403 6404@cindex @code{cmul@var{m}4} instruction pattern 6405@item @samp{cmul@var{m}4} 6406Perform a vector multiply that is semantically the same as multiply of 6407complex numbers. 6408 6409@smallexample 6410 complex TYPE c[N]; 6411 complex TYPE a[N]; 6412 complex TYPE b[N]; 6413 for (int i = 0; i < N; i += 1) 6414 @{ 6415 c[i] = a[i] * b[i]; 6416 @} 6417@end smallexample 6418 6419In GCC lane ordering the real part of the number must be in the even lanes with 6420the imaginary part in the odd lanes. 6421 6422The operation is only supported for vector modes @var{m}. 6423 6424This pattern is not allowed to @code{FAIL}. 6425 6426@cindex @code{cmul_conj@var{m}4} instruction pattern 6427@item @samp{cmul_conj@var{m}4} 6428Perform a vector multiply by conjugate that is semantically the same as a 6429multiply of complex numbers where the second multiply arguments is conjugated. 6430 6431@smallexample 6432 complex TYPE c[N]; 6433 complex TYPE a[N]; 6434 complex TYPE b[N]; 6435 for (int i = 0; i < N; i += 1) 6436 @{ 6437 c[i] = a[i] * conj (b[i]); 6438 @} 6439@end smallexample 6440 6441In GCC lane ordering the real part of the number must be in the even lanes with 6442the imaginary part in the odd lanes. 6443 6444The operation is only supported for vector modes @var{m}. 6445 6446This pattern is not allowed to @code{FAIL}. 6447 6448@cindex @code{ffs@var{m}2} instruction pattern 6449@item @samp{ffs@var{m}2} 6450Store into operand 0 one plus the index of the least significant 1-bit 6451of operand 1. If operand 1 is zero, store zero. 6452 6453@var{m} is either a scalar or vector integer mode. When it is a scalar, 6454operand 1 has mode @var{m} but operand 0 can have whatever scalar 6455integer mode is suitable for the target. The compiler will insert 6456conversion instructions as necessary (typically to convert the result 6457to the same width as @code{int}). When @var{m} is a vector, both 6458operands must have mode @var{m}. 6459 6460This pattern is not allowed to @code{FAIL}. 6461 6462@cindex @code{clrsb@var{m}2} instruction pattern 6463@item @samp{clrsb@var{m}2} 6464Count leading redundant sign bits. 6465Store into operand 0 the number of redundant sign bits in operand 1, starting 6466at the most significant bit position. 6467A redundant sign bit is defined as any sign bit after the first. As such, 6468this count will be one less than the count of leading sign bits. 6469 6470@var{m} is either a scalar or vector integer mode. When it is a scalar, 6471operand 1 has mode @var{m} but operand 0 can have whatever scalar 6472integer mode is suitable for the target. The compiler will insert 6473conversion instructions as necessary (typically to convert the result 6474to the same width as @code{int}). When @var{m} is a vector, both 6475operands must have mode @var{m}. 6476 6477This pattern is not allowed to @code{FAIL}. 6478 6479@cindex @code{clz@var{m}2} instruction pattern 6480@item @samp{clz@var{m}2} 6481Store into operand 0 the number of leading 0-bits in operand 1, starting 6482at the most significant bit position. If operand 1 is 0, the 6483@code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if 6484the result is undefined or has a useful value. 6485 6486@var{m} is either a scalar or vector integer mode. When it is a scalar, 6487operand 1 has mode @var{m} but operand 0 can have whatever scalar 6488integer mode is suitable for the target. The compiler will insert 6489conversion instructions as necessary (typically to convert the result 6490to the same width as @code{int}). When @var{m} is a vector, both 6491operands must have mode @var{m}. 6492 6493This pattern is not allowed to @code{FAIL}. 6494 6495@cindex @code{ctz@var{m}2} instruction pattern 6496@item @samp{ctz@var{m}2} 6497Store into operand 0 the number of trailing 0-bits in operand 1, starting 6498at the least significant bit position. If operand 1 is 0, the 6499@code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if 6500the result is undefined or has a useful value. 6501 6502@var{m} is either a scalar or vector integer mode. When it is a scalar, 6503operand 1 has mode @var{m} but operand 0 can have whatever scalar 6504integer mode is suitable for the target. The compiler will insert 6505conversion instructions as necessary (typically to convert the result 6506to the same width as @code{int}). When @var{m} is a vector, both 6507operands must have mode @var{m}. 6508 6509This pattern is not allowed to @code{FAIL}. 6510 6511@cindex @code{popcount@var{m}2} instruction pattern 6512@item @samp{popcount@var{m}2} 6513Store into operand 0 the number of 1-bits in operand 1. 6514 6515@var{m} is either a scalar or vector integer mode. When it is a scalar, 6516operand 1 has mode @var{m} but operand 0 can have whatever scalar 6517integer mode is suitable for the target. The compiler will insert 6518conversion instructions as necessary (typically to convert the result 6519to the same width as @code{int}). When @var{m} is a vector, both 6520operands must have mode @var{m}. 6521 6522This pattern is not allowed to @code{FAIL}. 6523 6524@cindex @code{parity@var{m}2} instruction pattern 6525@item @samp{parity@var{m}2} 6526Store into operand 0 the parity of operand 1, i.e.@: the number of 1-bits 6527in operand 1 modulo 2. 6528 6529@var{m} is either a scalar or vector integer mode. When it is a scalar, 6530operand 1 has mode @var{m} but operand 0 can have whatever scalar 6531integer mode is suitable for the target. The compiler will insert 6532conversion instructions as necessary (typically to convert the result 6533to the same width as @code{int}). When @var{m} is a vector, both 6534operands must have mode @var{m}. 6535 6536This pattern is not allowed to @code{FAIL}. 6537 6538@cindex @code{one_cmpl@var{m}2} instruction pattern 6539@item @samp{one_cmpl@var{m}2} 6540Store the bitwise-complement of operand 1 into operand 0. 6541 6542@cindex @code{cpymem@var{m}} instruction pattern 6543@item @samp{cpymem@var{m}} 6544Block copy instruction. The destination and source blocks of memory 6545are the first two operands, and both are @code{mem:BLK}s with an 6546address in mode @code{Pmode}. 6547 6548The number of bytes to copy is the third operand, in mode @var{m}. 6549Usually, you specify @code{Pmode} for @var{m}. However, if you can 6550generate better code knowing the range of valid lengths is smaller than 6551those representable in a full Pmode pointer, you should provide 6552a pattern with a 6553mode corresponding to the range of values you can handle efficiently 6554(e.g., @code{QImode} for values in the range 0--127; note we avoid numbers 6555that appear negative) and also a pattern with @code{Pmode}. 6556 6557The fourth operand is the known shared alignment of the source and 6558destination, in the form of a @code{const_int} rtx. Thus, if the 6559compiler knows that both source and destination are word-aligned, 6560it may provide the value 4 for this operand. 6561 6562Optional operands 5 and 6 specify expected alignment and size of block 6563respectively. The expected alignment differs from alignment in operand 4 6564in a way that the blocks are not required to be aligned according to it in 6565all cases. This expected alignment is also in bytes, just like operand 4. 6566Expected size, when unknown, is set to @code{(const_int -1)}. 6567 6568Descriptions of multiple @code{cpymem@var{m}} patterns can only be 6569beneficial if the patterns for smaller modes have fewer restrictions 6570on their first, second and fourth operands. Note that the mode @var{m} 6571in @code{cpymem@var{m}} does not impose any restriction on the mode of 6572individually copied data units in the block. 6573 6574The @code{cpymem@var{m}} patterns need not give special consideration 6575to the possibility that the source and destination strings might 6576overlap. These patterns are used to do inline expansion of 6577@code{__builtin_memcpy}. 6578 6579@cindex @code{movmem@var{m}} instruction pattern 6580@item @samp{movmem@var{m}} 6581Block move instruction. The destination and source blocks of memory 6582are the first two operands, and both are @code{mem:BLK}s with an 6583address in mode @code{Pmode}. 6584 6585The number of bytes to copy is the third operand, in mode @var{m}. 6586Usually, you specify @code{Pmode} for @var{m}. However, if you can 6587generate better code knowing the range of valid lengths is smaller than 6588those representable in a full Pmode pointer, you should provide 6589a pattern with a 6590mode corresponding to the range of values you can handle efficiently 6591(e.g., @code{QImode} for values in the range 0--127; note we avoid numbers 6592that appear negative) and also a pattern with @code{Pmode}. 6593 6594The fourth operand is the known shared alignment of the source and 6595destination, in the form of a @code{const_int} rtx. Thus, if the 6596compiler knows that both source and destination are word-aligned, 6597it may provide the value 4 for this operand. 6598 6599Optional operands 5 and 6 specify expected alignment and size of block 6600respectively. The expected alignment differs from alignment in operand 4 6601in a way that the blocks are not required to be aligned according to it in 6602all cases. This expected alignment is also in bytes, just like operand 4. 6603Expected size, when unknown, is set to @code{(const_int -1)}. 6604 6605Descriptions of multiple @code{movmem@var{m}} patterns can only be 6606beneficial if the patterns for smaller modes have fewer restrictions 6607on their first, second and fourth operands. Note that the mode @var{m} 6608in @code{movmem@var{m}} does not impose any restriction on the mode of 6609individually copied data units in the block. 6610 6611The @code{movmem@var{m}} patterns must correctly handle the case where 6612the source and destination strings overlap. These patterns are used to 6613do inline expansion of @code{__builtin_memmove}. 6614 6615@cindex @code{movstr} instruction pattern 6616@item @samp{movstr} 6617String copy instruction, with @code{stpcpy} semantics. Operand 0 is 6618an output operand in mode @code{Pmode}. The addresses of the 6619destination and source strings are operands 1 and 2, and both are 6620@code{mem:BLK}s with addresses in mode @code{Pmode}. The execution of 6621the expansion of this pattern should store in operand 0 the address in 6622which the @code{NUL} terminator was stored in the destination string. 6623 6624This pattern has also several optional operands that are same as in 6625@code{setmem}. 6626 6627@cindex @code{setmem@var{m}} instruction pattern 6628@item @samp{setmem@var{m}} 6629Block set instruction. The destination string is the first operand, 6630given as a @code{mem:BLK} whose address is in mode @code{Pmode}. The 6631number of bytes to set is the second operand, in mode @var{m}. The value to 6632initialize the memory with is the third operand. Targets that only support the 6633clearing of memory should reject any value that is not the constant 0. See 6634@samp{cpymem@var{m}} for a discussion of the choice of mode. 6635 6636The fourth operand is the known alignment of the destination, in the form 6637of a @code{const_int} rtx. Thus, if the compiler knows that the 6638destination is word-aligned, it may provide the value 4 for this 6639operand. 6640 6641Optional operands 5 and 6 specify expected alignment and size of block 6642respectively. The expected alignment differs from alignment in operand 4 6643in a way that the blocks are not required to be aligned according to it in 6644all cases. This expected alignment is also in bytes, just like operand 4. 6645Expected size, when unknown, is set to @code{(const_int -1)}. 6646Operand 7 is the minimal size of the block and operand 8 is the 6647maximal size of the block (NULL if it cannot be represented as CONST_INT). 6648Operand 9 is the probable maximal size (i.e.@: we cannot rely on it for 6649correctness, but it can be used for choosing proper code sequence for a 6650given size). 6651 6652The use for multiple @code{setmem@var{m}} is as for @code{cpymem@var{m}}. 6653 6654@cindex @code{cmpstrn@var{m}} instruction pattern 6655@item @samp{cmpstrn@var{m}} 6656String compare instruction, with five operands. Operand 0 is the output; 6657it has mode @var{m}. The remaining four operands are like the operands 6658of @samp{cpymem@var{m}}. The two memory blocks specified are compared 6659byte by byte in lexicographic order starting at the beginning of each 6660string. The instruction is not allowed to prefetch more than one byte 6661at a time since either string may end in the first byte and reading past 6662that may access an invalid page or segment and cause a fault. The 6663comparison terminates early if the fetched bytes are different or if 6664they are equal to zero. The effect of the instruction is to store a 6665value in operand 0 whose sign indicates the result of the comparison. 6666 6667@cindex @code{cmpstr@var{m}} instruction pattern 6668@item @samp{cmpstr@var{m}} 6669String compare instruction, without known maximum length. Operand 0 is the 6670output; it has mode @var{m}. The second and third operand are the blocks of 6671memory to be compared; both are @code{mem:BLK} with an address in mode 6672@code{Pmode}. 6673 6674The fourth operand is the known shared alignment of the source and 6675destination, in the form of a @code{const_int} rtx. Thus, if the 6676compiler knows that both source and destination are word-aligned, 6677it may provide the value 4 for this operand. 6678 6679The two memory blocks specified are compared byte by byte in lexicographic 6680order starting at the beginning of each string. The instruction is not allowed 6681to prefetch more than one byte at a time since either string may end in the 6682first byte and reading past that may access an invalid page or segment and 6683cause a fault. The comparison will terminate when the fetched bytes 6684are different or if they are equal to zero. The effect of the 6685instruction is to store a value in operand 0 whose sign indicates the 6686result of the comparison. 6687 6688@cindex @code{cmpmem@var{m}} instruction pattern 6689@item @samp{cmpmem@var{m}} 6690Block compare instruction, with five operands like the operands 6691of @samp{cmpstr@var{m}}. The two memory blocks specified are compared 6692byte by byte in lexicographic order starting at the beginning of each 6693block. Unlike @samp{cmpstr@var{m}} the instruction can prefetch 6694any bytes in the two memory blocks. Also unlike @samp{cmpstr@var{m}} 6695the comparison will not stop if both bytes are zero. The effect of 6696the instruction is to store a value in operand 0 whose sign indicates 6697the result of the comparison. 6698 6699@cindex @code{strlen@var{m}} instruction pattern 6700@item @samp{strlen@var{m}} 6701Compute the length of a string, with three operands. 6702Operand 0 is the result (of mode @var{m}), operand 1 is 6703a @code{mem} referring to the first character of the string, 6704operand 2 is the character to search for (normally zero), 6705and operand 3 is a constant describing the known alignment 6706of the beginning of the string. 6707 6708@cindex @code{rawmemchr@var{m}} instruction pattern 6709@item @samp{rawmemchr@var{m}} 6710Scan memory referred to by operand 1 for the first occurrence of operand 2. 6711Operand 1 is a @code{mem} and operand 2 a @code{const_int} of mode @var{m}. 6712Operand 0 is the result, i.e., a pointer to the first occurrence of operand 2 6713in the memory block given by operand 1. 6714 6715@cindex @code{float@var{m}@var{n}2} instruction pattern 6716@item @samp{float@var{m}@var{n}2} 6717Convert signed integer operand 1 (valid for fixed point mode @var{m}) to 6718floating point mode @var{n} and store in operand 0 (which has mode 6719@var{n}). 6720 6721@cindex @code{floatuns@var{m}@var{n}2} instruction pattern 6722@item @samp{floatuns@var{m}@var{n}2} 6723Convert unsigned integer operand 1 (valid for fixed point mode @var{m}) 6724to floating point mode @var{n} and store in operand 0 (which has mode 6725@var{n}). 6726 6727@cindex @code{fix@var{m}@var{n}2} instruction pattern 6728@item @samp{fix@var{m}@var{n}2} 6729Convert operand 1 (valid for floating point mode @var{m}) to fixed 6730point mode @var{n} as a signed number and store in operand 0 (which 6731has mode @var{n}). This instruction's result is defined only when 6732the value of operand 1 is an integer. 6733 6734If the machine description defines this pattern, it also needs to 6735define the @code{ftrunc} pattern. 6736 6737@cindex @code{fixuns@var{m}@var{n}2} instruction pattern 6738@item @samp{fixuns@var{m}@var{n}2} 6739Convert operand 1 (valid for floating point mode @var{m}) to fixed 6740point mode @var{n} as an unsigned number and store in operand 0 (which 6741has mode @var{n}). This instruction's result is defined only when the 6742value of operand 1 is an integer. 6743 6744@cindex @code{ftrunc@var{m}2} instruction pattern 6745@item @samp{ftrunc@var{m}2} 6746Convert operand 1 (valid for floating point mode @var{m}) to an 6747integer value, still represented in floating point mode @var{m}, and 6748store it in operand 0 (valid for floating point mode @var{m}). 6749 6750@cindex @code{fix_trunc@var{m}@var{n}2} instruction pattern 6751@item @samp{fix_trunc@var{m}@var{n}2} 6752Like @samp{fix@var{m}@var{n}2} but works for any floating point value 6753of mode @var{m} by converting the value to an integer. 6754 6755@cindex @code{fixuns_trunc@var{m}@var{n}2} instruction pattern 6756@item @samp{fixuns_trunc@var{m}@var{n}2} 6757Like @samp{fixuns@var{m}@var{n}2} but works for any floating point 6758value of mode @var{m} by converting the value to an integer. 6759 6760@cindex @code{trunc@var{m}@var{n}2} instruction pattern 6761@item @samp{trunc@var{m}@var{n}2} 6762Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and 6763store in operand 0 (which has mode @var{n}). Both modes must be fixed 6764point or both floating point. 6765 6766@cindex @code{extend@var{m}@var{n}2} instruction pattern 6767@item @samp{extend@var{m}@var{n}2} 6768Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and 6769store in operand 0 (which has mode @var{n}). Both modes must be fixed 6770point or both floating point. 6771 6772@cindex @code{zero_extend@var{m}@var{n}2} instruction pattern 6773@item @samp{zero_extend@var{m}@var{n}2} 6774Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and 6775store in operand 0 (which has mode @var{n}). Both modes must be fixed 6776point. 6777 6778@cindex @code{fract@var{m}@var{n}2} instruction pattern 6779@item @samp{fract@var{m}@var{n}2} 6780Convert operand 1 of mode @var{m} to mode @var{n} and store in 6781operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} 6782could be fixed-point to fixed-point, signed integer to fixed-point, 6783fixed-point to signed integer, floating-point to fixed-point, 6784or fixed-point to floating-point. 6785When overflows or underflows happen, the results are undefined. 6786 6787@cindex @code{satfract@var{m}@var{n}2} instruction pattern 6788@item @samp{satfract@var{m}@var{n}2} 6789Convert operand 1 of mode @var{m} to mode @var{n} and store in 6790operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} 6791could be fixed-point to fixed-point, signed integer to fixed-point, 6792or floating-point to fixed-point. 6793When overflows or underflows happen, the instruction saturates the 6794results to the maximum or the minimum. 6795 6796@cindex @code{fractuns@var{m}@var{n}2} instruction pattern 6797@item @samp{fractuns@var{m}@var{n}2} 6798Convert operand 1 of mode @var{m} to mode @var{n} and store in 6799operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} 6800could be unsigned integer to fixed-point, or 6801fixed-point to unsigned integer. 6802When overflows or underflows happen, the results are undefined. 6803 6804@cindex @code{satfractuns@var{m}@var{n}2} instruction pattern 6805@item @samp{satfractuns@var{m}@var{n}2} 6806Convert unsigned integer operand 1 of mode @var{m} to fixed-point mode 6807@var{n} and store in operand 0 (which has mode @var{n}). 6808When overflows or underflows happen, the instruction saturates the 6809results to the maximum or the minimum. 6810 6811@cindex @code{extv@var{m}} instruction pattern 6812@item @samp{extv@var{m}} 6813Extract a bit-field from register operand 1, sign-extend it, and store 6814it in operand 0. Operand 2 specifies the width of the field in bits 6815and operand 3 the starting bit, which counts from the most significant 6816bit if @samp{BITS_BIG_ENDIAN} is true and from the least significant bit 6817otherwise. 6818 6819Operands 0 and 1 both have mode @var{m}. Operands 2 and 3 have a 6820target-specific mode. 6821 6822@cindex @code{extvmisalign@var{m}} instruction pattern 6823@item @samp{extvmisalign@var{m}} 6824Extract a bit-field from memory operand 1, sign extend it, and store 6825it in operand 0. Operand 2 specifies the width in bits and operand 3 6826the starting bit. The starting bit is always somewhere in the first byte of 6827operand 1; it counts from the most significant bit if @samp{BITS_BIG_ENDIAN} 6828is true and from the least significant bit otherwise. 6829 6830Operand 0 has mode @var{m} while operand 1 has @code{BLK} mode. 6831Operands 2 and 3 have a target-specific mode. 6832 6833The instruction must not read beyond the last byte of the bit-field. 6834 6835@cindex @code{extzv@var{m}} instruction pattern 6836@item @samp{extzv@var{m}} 6837Like @samp{extv@var{m}} except that the bit-field value is zero-extended. 6838 6839@cindex @code{extzvmisalign@var{m}} instruction pattern 6840@item @samp{extzvmisalign@var{m}} 6841Like @samp{extvmisalign@var{m}} except that the bit-field value is 6842zero-extended. 6843 6844@cindex @code{insv@var{m}} instruction pattern 6845@item @samp{insv@var{m}} 6846Insert operand 3 into a bit-field of register operand 0. Operand 1 6847specifies the width of the field in bits and operand 2 the starting bit, 6848which counts from the most significant bit if @samp{BITS_BIG_ENDIAN} 6849is true and from the least significant bit otherwise. 6850 6851Operands 0 and 3 both have mode @var{m}. Operands 1 and 2 have a 6852target-specific mode. 6853 6854@cindex @code{insvmisalign@var{m}} instruction pattern 6855@item @samp{insvmisalign@var{m}} 6856Insert operand 3 into a bit-field of memory operand 0. Operand 1 6857specifies the width of the field in bits and operand 2 the starting bit. 6858The starting bit is always somewhere in the first byte of operand 0; 6859it counts from the most significant bit if @samp{BITS_BIG_ENDIAN} 6860is true and from the least significant bit otherwise. 6861 6862Operand 3 has mode @var{m} while operand 0 has @code{BLK} mode. 6863Operands 1 and 2 have a target-specific mode. 6864 6865The instruction must not read or write beyond the last byte of the bit-field. 6866 6867@cindex @code{extv} instruction pattern 6868@item @samp{extv} 6869Extract a bit-field from operand 1 (a register or memory operand), where 6870operand 2 specifies the width in bits and operand 3 the starting bit, 6871and store it in operand 0. Operand 0 must have mode @code{word_mode}. 6872Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often 6873@code{word_mode} is allowed only for registers. Operands 2 and 3 must 6874be valid for @code{word_mode}. 6875 6876The RTL generation pass generates this instruction only with constants 6877for operands 2 and 3 and the constant is never zero for operand 2. 6878 6879The bit-field value is sign-extended to a full word integer 6880before it is stored in operand 0. 6881 6882This pattern is deprecated; please use @samp{extv@var{m}} and 6883@code{extvmisalign@var{m}} instead. 6884 6885@cindex @code{extzv} instruction pattern 6886@item @samp{extzv} 6887Like @samp{extv} except that the bit-field value is zero-extended. 6888 6889This pattern is deprecated; please use @samp{extzv@var{m}} and 6890@code{extzvmisalign@var{m}} instead. 6891 6892@cindex @code{insv} instruction pattern 6893@item @samp{insv} 6894Store operand 3 (which must be valid for @code{word_mode}) into a 6895bit-field in operand 0, where operand 1 specifies the width in bits and 6896operand 2 the starting bit. Operand 0 may have mode @code{byte_mode} or 6897@code{word_mode}; often @code{word_mode} is allowed only for registers. 6898Operands 1 and 2 must be valid for @code{word_mode}. 6899 6900The RTL generation pass generates this instruction only with constants 6901for operands 1 and 2 and the constant is never zero for operand 1. 6902 6903This pattern is deprecated; please use @samp{insv@var{m}} and 6904@code{insvmisalign@var{m}} instead. 6905 6906@cindex @code{mov@var{mode}cc} instruction pattern 6907@item @samp{mov@var{mode}cc} 6908Conditionally move operand 2 or operand 3 into operand 0 according to the 6909comparison in operand 1. If the comparison is true, operand 2 is moved 6910into operand 0, otherwise operand 3 is moved. 6911 6912The mode of the operands being compared need not be the same as the operands 6913being moved. Some machines, sparc64 for example, have instructions that 6914conditionally move an integer value based on the floating point condition 6915codes and vice versa. 6916 6917If the machine does not have conditional move instructions, do not 6918define these patterns. 6919 6920@cindex @code{add@var{mode}cc} instruction pattern 6921@item @samp{add@var{mode}cc} 6922Similar to @samp{mov@var{mode}cc} but for conditional addition. Conditionally 6923move operand 2 or (operands 2 + operand 3) into operand 0 according to the 6924comparison in operand 1. If the comparison is false, operand 2 is moved into 6925operand 0, otherwise (operand 2 + operand 3) is moved. 6926 6927@cindex @code{cond_add@var{mode}} instruction pattern 6928@cindex @code{cond_sub@var{mode}} instruction pattern 6929@cindex @code{cond_mul@var{mode}} instruction pattern 6930@cindex @code{cond_div@var{mode}} instruction pattern 6931@cindex @code{cond_udiv@var{mode}} instruction pattern 6932@cindex @code{cond_mod@var{mode}} instruction pattern 6933@cindex @code{cond_umod@var{mode}} instruction pattern 6934@cindex @code{cond_and@var{mode}} instruction pattern 6935@cindex @code{cond_ior@var{mode}} instruction pattern 6936@cindex @code{cond_xor@var{mode}} instruction pattern 6937@cindex @code{cond_smin@var{mode}} instruction pattern 6938@cindex @code{cond_smax@var{mode}} instruction pattern 6939@cindex @code{cond_umin@var{mode}} instruction pattern 6940@cindex @code{cond_umax@var{mode}} instruction pattern 6941@cindex @code{cond_fmin@var{mode}} instruction pattern 6942@cindex @code{cond_fmax@var{mode}} instruction pattern 6943@cindex @code{cond_ashl@var{mode}} instruction pattern 6944@cindex @code{cond_ashr@var{mode}} instruction pattern 6945@cindex @code{cond_lshr@var{mode}} instruction pattern 6946@item @samp{cond_add@var{mode}} 6947@itemx @samp{cond_sub@var{mode}} 6948@itemx @samp{cond_mul@var{mode}} 6949@itemx @samp{cond_div@var{mode}} 6950@itemx @samp{cond_udiv@var{mode}} 6951@itemx @samp{cond_mod@var{mode}} 6952@itemx @samp{cond_umod@var{mode}} 6953@itemx @samp{cond_and@var{mode}} 6954@itemx @samp{cond_ior@var{mode}} 6955@itemx @samp{cond_xor@var{mode}} 6956@itemx @samp{cond_smin@var{mode}} 6957@itemx @samp{cond_smax@var{mode}} 6958@itemx @samp{cond_umin@var{mode}} 6959@itemx @samp{cond_umax@var{mode}} 6960@itemx @samp{cond_fmin@var{mode}} 6961@itemx @samp{cond_fmax@var{mode}} 6962@itemx @samp{cond_ashl@var{mode}} 6963@itemx @samp{cond_ashr@var{mode}} 6964@itemx @samp{cond_lshr@var{mode}} 6965When operand 1 is true, perform an operation on operands 2 and 3 and 6966store the result in operand 0, otherwise store operand 4 in operand 0. 6967The operation works elementwise if the operands are vectors. 6968 6969The scalar case is equivalent to: 6970 6971@smallexample 6972op0 = op1 ? op2 @var{op} op3 : op4; 6973@end smallexample 6974 6975while the vector case is equivalent to: 6976 6977@smallexample 6978for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++) 6979 op0[i] = op1[i] ? op2[i] @var{op} op3[i] : op4[i]; 6980@end smallexample 6981 6982where, for example, @var{op} is @code{+} for @samp{cond_add@var{mode}}. 6983 6984When defined for floating-point modes, the contents of @samp{op3[i]} 6985are not interpreted if @samp{op1[i]} is false, just like they would not 6986be in a normal C @samp{?:} condition. 6987 6988Operands 0, 2, 3 and 4 all have mode @var{m}. Operand 1 is a scalar 6989integer if @var{m} is scalar, otherwise it has the mode returned by 6990@code{TARGET_VECTORIZE_GET_MASK_MODE}. 6991 6992@samp{cond_@var{op}@var{mode}} generally corresponds to a conditional 6993form of @samp{@var{op}@var{mode}3}. As an exception, the vector forms 6994of shifts correspond to patterns like @code{vashl@var{mode}3} rather 6995than patterns like @code{ashl@var{mode}3}. 6996 6997@cindex @code{cond_fma@var{mode}} instruction pattern 6998@cindex @code{cond_fms@var{mode}} instruction pattern 6999@cindex @code{cond_fnma@var{mode}} instruction pattern 7000@cindex @code{cond_fnms@var{mode}} instruction pattern 7001@item @samp{cond_fma@var{mode}} 7002@itemx @samp{cond_fms@var{mode}} 7003@itemx @samp{cond_fnma@var{mode}} 7004@itemx @samp{cond_fnms@var{mode}} 7005Like @samp{cond_add@var{m}}, except that the conditional operation 7006takes 3 operands rather than two. For example, the vector form of 7007@samp{cond_fma@var{mode}} is equivalent to: 7008 7009@smallexample 7010for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++) 7011 op0[i] = op1[i] ? fma (op2[i], op3[i], op4[i]) : op5[i]; 7012@end smallexample 7013 7014@cindex @code{neg@var{mode}cc} instruction pattern 7015@item @samp{neg@var{mode}cc} 7016Similar to @samp{mov@var{mode}cc} but for conditional negation. Conditionally 7017move the negation of operand 2 or the unchanged operand 3 into operand 0 7018according to the comparison in operand 1. If the comparison is true, the negation 7019of operand 2 is moved into operand 0, otherwise operand 3 is moved. 7020 7021@cindex @code{not@var{mode}cc} instruction pattern 7022@item @samp{not@var{mode}cc} 7023Similar to @samp{neg@var{mode}cc} but for conditional complement. 7024Conditionally move the bitwise complement of operand 2 or the unchanged 7025operand 3 into operand 0 according to the comparison in operand 1. 7026If the comparison is true, the complement of operand 2 is moved into 7027operand 0, otherwise operand 3 is moved. 7028 7029@cindex @code{cstore@var{mode}4} instruction pattern 7030@item @samp{cstore@var{mode}4} 7031Store zero or nonzero in operand 0 according to whether a comparison 7032is true. Operand 1 is a comparison operator. Operand 2 and operand 3 7033are the first and second operand of the comparison, respectively. 7034You specify the mode that operand 0 must have when you write the 7035@code{match_operand} expression. The compiler automatically sees which 7036mode you have used and supplies an operand of that mode. 7037 7038The value stored for a true condition must have 1 as its low bit, or 7039else must be negative. Otherwise the instruction is not suitable and 7040you should omit it from the machine description. You describe to the 7041compiler exactly which value is stored by defining the macro 7042@code{STORE_FLAG_VALUE} (@pxref{Misc}). If a description cannot be 7043found that can be used for all the possible comparison operators, you 7044should pick one and use a @code{define_expand} to map all results 7045onto the one you chose. 7046 7047These operations may @code{FAIL}, but should do so only in relatively 7048uncommon cases; if they would @code{FAIL} for common cases involving 7049integer comparisons, it is best to restrict the predicates to not 7050allow these operands. Likewise if a given comparison operator will 7051always fail, independent of the operands (for floating-point modes, the 7052@code{ordered_comparison_operator} predicate is often useful in this case). 7053 7054If this pattern is omitted, the compiler will generate a conditional 7055branch---for example, it may copy a constant one to the target and branching 7056around an assignment of zero to the target---or a libcall. If the predicate 7057for operand 1 only rejects some operators, it will also try reordering the 7058operands and/or inverting the result value (e.g.@: by an exclusive OR). 7059These possibilities could be cheaper or equivalent to the instructions 7060used for the @samp{cstore@var{mode}4} pattern followed by those required 7061to convert a positive result from @code{STORE_FLAG_VALUE} to 1; in this 7062case, you can and should make operand 1's predicate reject some operators 7063in the @samp{cstore@var{mode}4} pattern, or remove the pattern altogether 7064from the machine description. 7065 7066@cindex @code{cbranch@var{mode}4} instruction pattern 7067@item @samp{cbranch@var{mode}4} 7068Conditional branch instruction combined with a compare instruction. 7069Operand 0 is a comparison operator. Operand 1 and operand 2 are the 7070first and second operands of the comparison, respectively. Operand 3 7071is the @code{code_label} to jump to. 7072 7073@cindex @code{jump} instruction pattern 7074@item @samp{jump} 7075A jump inside a function; an unconditional branch. Operand 0 is the 7076@code{code_label} to jump to. This pattern name is mandatory on all 7077machines. 7078 7079@cindex @code{call} instruction pattern 7080@item @samp{call} 7081Subroutine call instruction returning no value. Operand 0 is the 7082function to call; operand 1 is the number of bytes of arguments pushed 7083as a @code{const_int}. Operand 2 is the result of calling the target 7084hook @code{TARGET_FUNCTION_ARG} with the second argument @code{arg} 7085yielding true for @code{arg.end_marker_p ()}, in a call after all 7086parameters have been passed to that hook. By default this is the first 7087register beyond those used for arguments in the call, or @code{NULL} if 7088all the argument-registers are used in the call. 7089 7090On most machines, operand 2 is not actually stored into the RTL 7091pattern. It is supplied for the sake of some RISC machines which need 7092to put this information into the assembler code; they can put it in 7093the RTL instead of operand 1. 7094 7095Operand 0 should be a @code{mem} RTX whose address is the address of the 7096function. Note, however, that this address can be a @code{symbol_ref} 7097expression even if it would not be a legitimate memory address on the 7098target machine. If it is also not a valid argument for a call 7099instruction, the pattern for this operation should be a 7100@code{define_expand} (@pxref{Expander Definitions}) that places the 7101address into a register and uses that register in the call instruction. 7102 7103@cindex @code{call_value} instruction pattern 7104@item @samp{call_value} 7105Subroutine call instruction returning a value. Operand 0 is the hard 7106register in which the value is returned. There are three more 7107operands, the same as the three operands of the @samp{call} 7108instruction (but with numbers increased by one). 7109 7110Subroutines that return @code{BLKmode} objects use the @samp{call} 7111insn. 7112 7113@cindex @code{call_pop} instruction pattern 7114@cindex @code{call_value_pop} instruction pattern 7115@item @samp{call_pop}, @samp{call_value_pop} 7116Similar to @samp{call} and @samp{call_value}, except used if defined and 7117if @code{RETURN_POPS_ARGS} is nonzero. They should emit a @code{parallel} 7118that contains both the function call and a @code{set} to indicate the 7119adjustment made to the frame pointer. 7120 7121For machines where @code{RETURN_POPS_ARGS} can be nonzero, the use of these 7122patterns increases the number of functions for which the frame pointer 7123can be eliminated, if desired. 7124 7125@cindex @code{untyped_call} instruction pattern 7126@item @samp{untyped_call} 7127Subroutine call instruction returning a value of any type. Operand 0 is 7128the function to call; operand 1 is a memory location where the result of 7129calling the function is to be stored; operand 2 is a @code{parallel} 7130expression where each element is a @code{set} expression that indicates 7131the saving of a function return value into the result block. 7132 7133This instruction pattern should be defined to support 7134@code{__builtin_apply} on machines where special instructions are needed 7135to call a subroutine with arbitrary arguments or to save the value 7136returned. This instruction pattern is required on machines that have 7137multiple registers that can hold a return value 7138(i.e.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register). 7139 7140@cindex @code{return} instruction pattern 7141@item @samp{return} 7142Subroutine return instruction. This instruction pattern name should be 7143defined only if a single instruction can do all the work of returning 7144from a function. 7145 7146Like the @samp{mov@var{m}} patterns, this pattern is also used after the 7147RTL generation phase. In this case it is to support machines where 7148multiple instructions are usually needed to return from a function, but 7149some class of functions only requires one instruction to implement a 7150return. Normally, the applicable functions are those which do not need 7151to save any registers or allocate stack space. 7152 7153It is valid for this pattern to expand to an instruction using 7154@code{simple_return} if no epilogue is required. 7155 7156@cindex @code{simple_return} instruction pattern 7157@item @samp{simple_return} 7158Subroutine return instruction. This instruction pattern name should be 7159defined only if a single instruction can do all the work of returning 7160from a function on a path where no epilogue is required. This pattern 7161is very similar to the @code{return} instruction pattern, but it is emitted 7162only by the shrink-wrapping optimization on paths where the function 7163prologue has not been executed, and a function return should occur without 7164any of the effects of the epilogue. Additional uses may be introduced on 7165paths where both the prologue and the epilogue have executed. 7166 7167@findex reload_completed 7168@findex leaf_function_p 7169For such machines, the condition specified in this pattern should only 7170be true when @code{reload_completed} is nonzero and the function's 7171epilogue would only be a single instruction. For machines with register 7172windows, the routine @code{leaf_function_p} may be used to determine if 7173a register window push is required. 7174 7175Machines that have conditional return instructions should define patterns 7176such as 7177 7178@smallexample 7179(define_insn "" 7180 [(set (pc) 7181 (if_then_else (match_operator 7182 0 "comparison_operator" 7183 [(reg:CC CC_REG) (const_int 0)]) 7184 (return) 7185 (pc)))] 7186 "@var{condition}" 7187 "@dots{}") 7188@end smallexample 7189 7190where @var{condition} would normally be the same condition specified on the 7191named @samp{return} pattern. 7192 7193@cindex @code{untyped_return} instruction pattern 7194@item @samp{untyped_return} 7195Untyped subroutine return instruction. This instruction pattern should 7196be defined to support @code{__builtin_return} on machines where special 7197instructions are needed to return a value of any type. 7198 7199Operand 0 is a memory location where the result of calling a function 7200with @code{__builtin_apply} is stored; operand 1 is a @code{parallel} 7201expression where each element is a @code{set} expression that indicates 7202the restoring of a function return value from the result block. 7203 7204@cindex @code{nop} instruction pattern 7205@item @samp{nop} 7206No-op instruction. This instruction pattern name should always be defined 7207to output a no-op in assembler code. @code{(const_int 0)} will do as an 7208RTL pattern. 7209 7210@cindex @code{indirect_jump} instruction pattern 7211@item @samp{indirect_jump} 7212An instruction to jump to an address which is operand zero. 7213This pattern name is mandatory on all machines. 7214 7215@cindex @code{casesi} instruction pattern 7216@item @samp{casesi} 7217Instruction to jump through a dispatch table, including bounds checking. 7218This instruction takes five operands: 7219 7220@enumerate 7221@item 7222The index to dispatch on, which has mode @code{SImode}. 7223 7224@item 7225The lower bound for indices in the table, an integer constant. 7226 7227@item 7228The total range of indices in the table---the largest index 7229minus the smallest one (both inclusive). 7230 7231@item 7232A label that precedes the table itself. 7233 7234@item 7235A label to jump to if the index has a value outside the bounds. 7236@end enumerate 7237 7238The table is an @code{addr_vec} or @code{addr_diff_vec} inside of a 7239@code{jump_table_data}. The number of elements in the table is one plus the 7240difference between the upper bound and the lower bound. 7241 7242@cindex @code{tablejump} instruction pattern 7243@item @samp{tablejump} 7244Instruction to jump to a variable address. This is a low-level 7245capability which can be used to implement a dispatch table when there 7246is no @samp{casesi} pattern. 7247 7248This pattern requires two operands: the address or offset, and a label 7249which should immediately precede the jump table. If the macro 7250@code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first 7251operand is an offset which counts from the address of the table; otherwise, 7252it is an absolute address to jump to. In either case, the first operand has 7253mode @code{Pmode}. 7254 7255The @samp{tablejump} insn is always the last insn before the jump 7256table it uses. Its assembler code normally has no need to use the 7257second operand, but you should incorporate it in the RTL pattern so 7258that the jump optimizer will not delete the table as unreachable code. 7259 7260 7261@cindex @code{doloop_end} instruction pattern 7262@item @samp{doloop_end} 7263Conditional branch instruction that decrements a register and 7264jumps if the register is nonzero. Operand 0 is the register to 7265decrement and test; operand 1 is the label to jump to if the 7266register is nonzero. 7267@xref{Looping Patterns}. 7268 7269This optional instruction pattern should be defined for machines with 7270low-overhead looping instructions as the loop optimizer will try to 7271modify suitable loops to utilize it. The target hook 7272@code{TARGET_CAN_USE_DOLOOP_P} controls the conditions under which 7273low-overhead loops can be used. 7274 7275@cindex @code{doloop_begin} instruction pattern 7276@item @samp{doloop_begin} 7277Companion instruction to @code{doloop_end} required for machines that 7278need to perform some initialization, such as loading a special counter 7279register. Operand 1 is the associated @code{doloop_end} pattern and 7280operand 0 is the register that it decrements. 7281 7282If initialization insns do not always need to be emitted, use a 7283@code{define_expand} (@pxref{Expander Definitions}) and make it fail. 7284 7285@cindex @code{canonicalize_funcptr_for_compare} instruction pattern 7286@item @samp{canonicalize_funcptr_for_compare} 7287Canonicalize the function pointer in operand 1 and store the result 7288into operand 0. 7289 7290Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1 7291may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc 7292and also has mode @code{Pmode}. 7293 7294Canonicalization of a function pointer usually involves computing 7295the address of the function which would be called if the function 7296pointer were used in an indirect call. 7297 7298Only define this pattern if function pointers on the target machine 7299can have different values but still call the same function when 7300used in an indirect call. 7301 7302@cindex @code{save_stack_block} instruction pattern 7303@cindex @code{save_stack_function} instruction pattern 7304@cindex @code{save_stack_nonlocal} instruction pattern 7305@cindex @code{restore_stack_block} instruction pattern 7306@cindex @code{restore_stack_function} instruction pattern 7307@cindex @code{restore_stack_nonlocal} instruction pattern 7308@item @samp{save_stack_block} 7309@itemx @samp{save_stack_function} 7310@itemx @samp{save_stack_nonlocal} 7311@itemx @samp{restore_stack_block} 7312@itemx @samp{restore_stack_function} 7313@itemx @samp{restore_stack_nonlocal} 7314Most machines save and restore the stack pointer by copying it to or 7315from an object of mode @code{Pmode}. Do not define these patterns on 7316such machines. 7317 7318Some machines require special handling for stack pointer saves and 7319restores. On those machines, define the patterns corresponding to the 7320non-standard cases by using a @code{define_expand} (@pxref{Expander 7321Definitions}) that produces the required insns. The three types of 7322saves and restores are: 7323 7324@enumerate 7325@item 7326@samp{save_stack_block} saves the stack pointer at the start of a block 7327that allocates a variable-sized object, and @samp{restore_stack_block} 7328restores the stack pointer when the block is exited. 7329 7330@item 7331@samp{save_stack_function} and @samp{restore_stack_function} do a 7332similar job for the outermost block of a function and are used when the 7333function allocates variable-sized objects or calls @code{alloca}. Only 7334the epilogue uses the restored stack pointer, allowing a simpler save or 7335restore sequence on some machines. 7336 7337@item 7338@samp{save_stack_nonlocal} is used in functions that contain labels 7339branched to by nested functions. It saves the stack pointer in such a 7340way that the inner function can use @samp{restore_stack_nonlocal} to 7341restore the stack pointer. The compiler generates code to restore the 7342frame and argument pointer registers, but some machines require saving 7343and restoring additional data such as register window information or 7344stack backchains. Place insns in these patterns to save and restore any 7345such required data. 7346@end enumerate 7347 7348When saving the stack pointer, operand 0 is the save area and operand 1 7349is the stack pointer. The mode used to allocate the save area defaults 7350to @code{Pmode} but you can override that choice by defining the 7351@code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}). You must 7352specify an integral mode, or @code{VOIDmode} if no save area is needed 7353for a particular type of save (either because no save is needed or 7354because a machine-specific save area can be used). Operand 0 is the 7355stack pointer and operand 1 is the save area for restore operations. If 7356@samp{save_stack_block} is defined, operand 0 must not be 7357@code{VOIDmode} since these saves can be arbitrarily nested. 7358 7359A save area is a @code{mem} that is at a constant offset from 7360@code{virtual_stack_vars_rtx} when the stack pointer is saved for use by 7361nonlocal gotos and a @code{reg} in the other two cases. 7362 7363@cindex @code{allocate_stack} instruction pattern 7364@item @samp{allocate_stack} 7365Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from 7366the stack pointer to create space for dynamically allocated data. 7367 7368Store the resultant pointer to this space into operand 0. If you 7369are allocating space from the main stack, do this by emitting a 7370move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0. 7371If you are allocating the space elsewhere, generate code to copy the 7372location of the space to operand 0. In the latter case, you must 7373ensure this space gets freed when the corresponding space on the main 7374stack is free. 7375 7376Do not define this pattern if all that must be done is the subtraction. 7377Some machines require other operations such as stack probes or 7378maintaining the back chain. Define this pattern to emit those 7379operations in addition to updating the stack pointer. 7380 7381@cindex @code{check_stack} instruction pattern 7382@item @samp{check_stack} 7383If stack checking (@pxref{Stack Checking}) cannot be done on your system by 7384probing the stack, define this pattern to perform the needed check and signal 7385an error if the stack has overflowed. The single operand is the address in 7386the stack farthest from the current stack pointer that you need to validate. 7387Normally, on platforms where this pattern is needed, you would obtain the 7388stack limit from a global or thread-specific variable or register. 7389 7390@cindex @code{probe_stack_address} instruction pattern 7391@item @samp{probe_stack_address} 7392If stack checking (@pxref{Stack Checking}) can be done on your system by 7393probing the stack but without the need to actually access it, define this 7394pattern and signal an error if the stack has overflowed. The single operand 7395is the memory address in the stack that needs to be probed. 7396 7397@cindex @code{probe_stack} instruction pattern 7398@item @samp{probe_stack} 7399If stack checking (@pxref{Stack Checking}) can be done on your system by 7400probing the stack but doing it with a ``store zero'' instruction is not valid 7401or optimal, define this pattern to do the probing differently and signal an 7402error if the stack has overflowed. The single operand is the memory reference 7403in the stack that needs to be probed. 7404 7405@cindex @code{nonlocal_goto} instruction pattern 7406@item @samp{nonlocal_goto} 7407Emit code to generate a non-local goto, e.g., a jump from one function 7408to a label in an outer function. This pattern has four arguments, 7409each representing a value to be used in the jump. The first 7410argument is to be loaded into the frame pointer, the second is 7411the address to branch to (code to dispatch to the actual label), 7412the third is the address of a location where the stack is saved, 7413and the last is the address of the label, to be placed in the 7414location for the incoming static chain. 7415 7416On most machines you need not define this pattern, since GCC will 7417already generate the correct code, which is to load the frame pointer 7418and static chain, restore the stack (using the 7419@samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly 7420to the dispatcher. You need only define this pattern if this code will 7421not work on your machine. 7422 7423@cindex @code{nonlocal_goto_receiver} instruction pattern 7424@item @samp{nonlocal_goto_receiver} 7425This pattern, if defined, contains code needed at the target of a 7426nonlocal goto after the code already generated by GCC@. You will not 7427normally need to define this pattern. A typical reason why you might 7428need this pattern is if some value, such as a pointer to a global table, 7429must be restored when the frame pointer is restored. Note that a nonlocal 7430goto only occurs within a unit-of-translation, so a global table pointer 7431that is shared by all functions of a given module need not be restored. 7432There are no arguments. 7433 7434@cindex @code{exception_receiver} instruction pattern 7435@item @samp{exception_receiver} 7436This pattern, if defined, contains code needed at the site of an 7437exception handler that isn't needed at the site of a nonlocal goto. You 7438will not normally need to define this pattern. A typical reason why you 7439might need this pattern is if some value, such as a pointer to a global 7440table, must be restored after control flow is branched to the handler of 7441an exception. There are no arguments. 7442 7443@cindex @code{builtin_setjmp_setup} instruction pattern 7444@item @samp{builtin_setjmp_setup} 7445This pattern, if defined, contains additional code needed to initialize 7446the @code{jmp_buf}. You will not normally need to define this pattern. 7447A typical reason why you might need this pattern is if some value, such 7448as a pointer to a global table, must be restored. Though it is 7449preferred that the pointer value be recalculated if possible (given the 7450address of a label for instance). The single argument is a pointer to 7451the @code{jmp_buf}. Note that the buffer is five words long and that 7452the first three are normally used by the generic mechanism. 7453 7454@cindex @code{builtin_setjmp_receiver} instruction pattern 7455@item @samp{builtin_setjmp_receiver} 7456This pattern, if defined, contains code needed at the site of a 7457built-in setjmp that isn't needed at the site of a nonlocal goto. You 7458will not normally need to define this pattern. A typical reason why you 7459might need this pattern is if some value, such as a pointer to a global 7460table, must be restored. It takes one argument, which is the label 7461to which builtin_longjmp transferred control; this pattern may be emitted 7462at a small offset from that label. 7463 7464@cindex @code{builtin_longjmp} instruction pattern 7465@item @samp{builtin_longjmp} 7466This pattern, if defined, performs the entire action of the longjmp. 7467You will not normally need to define this pattern unless you also define 7468@code{builtin_setjmp_setup}. The single argument is a pointer to the 7469@code{jmp_buf}. 7470 7471@cindex @code{eh_return} instruction pattern 7472@item @samp{eh_return} 7473This pattern, if defined, affects the way @code{__builtin_eh_return}, 7474and thence the call frame exception handling library routines, are 7475built. It is intended to handle non-trivial actions needed along 7476the abnormal return path. 7477 7478The address of the exception handler to which the function should return 7479is passed as operand to this pattern. It will normally need to copied by 7480the pattern to some special register or memory location. 7481If the pattern needs to determine the location of the target call 7482frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX}, 7483if defined; it will have already been assigned. 7484 7485If this pattern is not defined, the default action will be to simply 7486copy the return address to @code{EH_RETURN_HANDLER_RTX}. Either 7487that macro or this pattern needs to be defined if call frame exception 7488handling is to be used. 7489 7490@cindex @code{prologue} instruction pattern 7491@anchor{prologue instruction pattern} 7492@item @samp{prologue} 7493This pattern, if defined, emits RTL for entry to a function. The function 7494entry is responsible for setting up the stack frame, initializing the frame 7495pointer register, saving callee saved registers, etc. 7496 7497Using a prologue pattern is generally preferred over defining 7498@code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue. 7499 7500The @code{prologue} pattern is particularly useful for targets which perform 7501instruction scheduling. 7502 7503@cindex @code{window_save} instruction pattern 7504@anchor{window_save instruction pattern} 7505@item @samp{window_save} 7506This pattern, if defined, emits RTL for a register window save. It should 7507be defined if the target machine has register windows but the window events 7508are decoupled from calls to subroutines. The canonical example is the SPARC 7509architecture. 7510 7511@cindex @code{epilogue} instruction pattern 7512@anchor{epilogue instruction pattern} 7513@item @samp{epilogue} 7514This pattern emits RTL for exit from a function. The function 7515exit is responsible for deallocating the stack frame, restoring callee saved 7516registers and emitting the return instruction. 7517 7518Using an epilogue pattern is generally preferred over defining 7519@code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue. 7520 7521The @code{epilogue} pattern is particularly useful for targets which perform 7522instruction scheduling or which have delay slots for their return instruction. 7523 7524@cindex @code{sibcall_epilogue} instruction pattern 7525@item @samp{sibcall_epilogue} 7526This pattern, if defined, emits RTL for exit from a function without the final 7527branch back to the calling function. This pattern will be emitted before any 7528sibling call (aka tail call) sites. 7529 7530The @code{sibcall_epilogue} pattern must not clobber any arguments used for 7531parameter passing or any stack slots for arguments passed to the current 7532function. 7533 7534@cindex @code{trap} instruction pattern 7535@item @samp{trap} 7536This pattern, if defined, signals an error, typically by causing some 7537kind of signal to be raised. 7538 7539@cindex @code{ctrap@var{MM}4} instruction pattern 7540@item @samp{ctrap@var{MM}4} 7541Conditional trap instruction. Operand 0 is a piece of RTL which 7542performs a comparison, and operands 1 and 2 are the arms of the 7543comparison. Operand 3 is the trap code, an integer. 7544 7545A typical @code{ctrap} pattern looks like 7546 7547@smallexample 7548(define_insn "ctrapsi4" 7549 [(trap_if (match_operator 0 "trap_operator" 7550 [(match_operand 1 "register_operand") 7551 (match_operand 2 "immediate_operand")]) 7552 (match_operand 3 "const_int_operand" "i"))] 7553 "" 7554 "@dots{}") 7555@end smallexample 7556 7557@cindex @code{prefetch} instruction pattern 7558@item @samp{prefetch} 7559This pattern, if defined, emits code for a non-faulting data prefetch 7560instruction. Operand 0 is the address of the memory to prefetch. Operand 1 7561is a constant 1 if the prefetch is preparing for a write to the memory 7562address, or a constant 0 otherwise. Operand 2 is the expected degree of 7563temporal locality of the data and is a value between 0 and 3, inclusive; 0 7564means that the data has no temporal locality, so it need not be left in the 7565cache after the access; 3 means that the data has a high degree of temporal 7566locality and should be left in all levels of cache possible; 1 and 2 mean, 7567respectively, a low or moderate degree of temporal locality. 7568 7569Targets that do not support write prefetches or locality hints can ignore 7570the values of operands 1 and 2. 7571 7572@cindex @code{blockage} instruction pattern 7573@item @samp{blockage} 7574This pattern defines a pseudo insn that prevents the instruction 7575scheduler and other passes from moving instructions and using register 7576equivalences across the boundary defined by the blockage insn. 7577This needs to be an UNSPEC_VOLATILE pattern or a volatile ASM. 7578 7579@cindex @code{memory_blockage} instruction pattern 7580@item @samp{memory_blockage} 7581This pattern, if defined, represents a compiler memory barrier, and will be 7582placed at points across which RTL passes may not propagate memory accesses. 7583This instruction needs to read and write volatile BLKmode memory. It does 7584not need to generate any machine instruction. If this pattern is not defined, 7585the compiler falls back to emitting an instruction corresponding 7586to @code{asm volatile ("" ::: "memory")}. 7587 7588@cindex @code{memory_barrier} instruction pattern 7589@item @samp{memory_barrier} 7590If the target memory model is not fully synchronous, then this pattern 7591should be defined to an instruction that orders both loads and stores 7592before the instruction with respect to loads and stores after the instruction. 7593This pattern has no operands. 7594 7595@cindex @code{speculation_barrier} instruction pattern 7596@item @samp{speculation_barrier} 7597If the target can support speculative execution, then this pattern should 7598be defined to an instruction that will block subsequent execution until 7599any prior speculation conditions has been resolved. The pattern must also 7600ensure that the compiler cannot move memory operations past the barrier, 7601so it needs to be an UNSPEC_VOLATILE pattern. The pattern has no 7602operands. 7603 7604If this pattern is not defined then the default expansion of 7605@code{__builtin_speculation_safe_value} will emit a warning. You can 7606suppress this warning by defining this pattern with a final condition 7607of @code{0} (zero), which tells the compiler that a speculation 7608barrier is not needed for this target. 7609 7610@cindex @code{sync_compare_and_swap@var{mode}} instruction pattern 7611@item @samp{sync_compare_and_swap@var{mode}} 7612This pattern, if defined, emits code for an atomic compare-and-swap 7613operation. Operand 1 is the memory on which the atomic operation is 7614performed. Operand 2 is the ``old'' value to be compared against the 7615current contents of the memory location. Operand 3 is the ``new'' value 7616to store in the memory if the compare succeeds. Operand 0 is the result 7617of the operation; it should contain the contents of the memory 7618before the operation. If the compare succeeds, this should obviously be 7619a copy of operand 2. 7620 7621This pattern must show that both operand 0 and operand 1 are modified. 7622 7623This pattern must issue any memory barrier instructions such that all 7624memory operations before the atomic operation occur before the atomic 7625operation and all memory operations after the atomic operation occur 7626after the atomic operation. 7627 7628For targets where the success or failure of the compare-and-swap 7629operation is available via the status flags, it is possible to 7630avoid a separate compare operation and issue the subsequent 7631branch or store-flag operation immediately after the compare-and-swap. 7632To this end, GCC will look for a @code{MODE_CC} set in the 7633output of @code{sync_compare_and_swap@var{mode}}; if the machine 7634description includes such a set, the target should also define special 7635@code{cbranchcc4} and/or @code{cstorecc4} instructions. GCC will then 7636be able to take the destination of the @code{MODE_CC} set and pass it 7637to the @code{cbranchcc4} or @code{cstorecc4} pattern as the first 7638operand of the comparison (the second will be @code{(const_int 0)}). 7639 7640For targets where the operating system may provide support for this 7641operation via library calls, the @code{sync_compare_and_swap_optab} 7642may be initialized to a function with the same interface as the 7643@code{__sync_val_compare_and_swap_@var{n}} built-in. If the entire 7644set of @var{__sync} builtins are supported via library calls, the 7645target can initialize all of the optabs at once with 7646@code{init_sync_libfuncs}. 7647For the purposes of C++11 @code{std::atomic::is_lock_free}, it is 7648assumed that these library calls do @emph{not} use any kind of 7649interruptable locking. 7650 7651@cindex @code{sync_add@var{mode}} instruction pattern 7652@cindex @code{sync_sub@var{mode}} instruction pattern 7653@cindex @code{sync_ior@var{mode}} instruction pattern 7654@cindex @code{sync_and@var{mode}} instruction pattern 7655@cindex @code{sync_xor@var{mode}} instruction pattern 7656@cindex @code{sync_nand@var{mode}} instruction pattern 7657@item @samp{sync_add@var{mode}}, @samp{sync_sub@var{mode}} 7658@itemx @samp{sync_ior@var{mode}}, @samp{sync_and@var{mode}} 7659@itemx @samp{sync_xor@var{mode}}, @samp{sync_nand@var{mode}} 7660These patterns emit code for an atomic operation on memory. 7661Operand 0 is the memory on which the atomic operation is performed. 7662Operand 1 is the second operand to the binary operator. 7663 7664This pattern must issue any memory barrier instructions such that all 7665memory operations before the atomic operation occur before the atomic 7666operation and all memory operations after the atomic operation occur 7667after the atomic operation. 7668 7669If these patterns are not defined, the operation will be constructed 7670from a compare-and-swap operation, if defined. 7671 7672@cindex @code{sync_old_add@var{mode}} instruction pattern 7673@cindex @code{sync_old_sub@var{mode}} instruction pattern 7674@cindex @code{sync_old_ior@var{mode}} instruction pattern 7675@cindex @code{sync_old_and@var{mode}} instruction pattern 7676@cindex @code{sync_old_xor@var{mode}} instruction pattern 7677@cindex @code{sync_old_nand@var{mode}} instruction pattern 7678@item @samp{sync_old_add@var{mode}}, @samp{sync_old_sub@var{mode}} 7679@itemx @samp{sync_old_ior@var{mode}}, @samp{sync_old_and@var{mode}} 7680@itemx @samp{sync_old_xor@var{mode}}, @samp{sync_old_nand@var{mode}} 7681These patterns emit code for an atomic operation on memory, 7682and return the value that the memory contained before the operation. 7683Operand 0 is the result value, operand 1 is the memory on which the 7684atomic operation is performed, and operand 2 is the second operand 7685to the binary operator. 7686 7687This pattern must issue any memory barrier instructions such that all 7688memory operations before the atomic operation occur before the atomic 7689operation and all memory operations after the atomic operation occur 7690after the atomic operation. 7691 7692If these patterns are not defined, the operation will be constructed 7693from a compare-and-swap operation, if defined. 7694 7695@cindex @code{sync_new_add@var{mode}} instruction pattern 7696@cindex @code{sync_new_sub@var{mode}} instruction pattern 7697@cindex @code{sync_new_ior@var{mode}} instruction pattern 7698@cindex @code{sync_new_and@var{mode}} instruction pattern 7699@cindex @code{sync_new_xor@var{mode}} instruction pattern 7700@cindex @code{sync_new_nand@var{mode}} instruction pattern 7701@item @samp{sync_new_add@var{mode}}, @samp{sync_new_sub@var{mode}} 7702@itemx @samp{sync_new_ior@var{mode}}, @samp{sync_new_and@var{mode}} 7703@itemx @samp{sync_new_xor@var{mode}}, @samp{sync_new_nand@var{mode}} 7704These patterns are like their @code{sync_old_@var{op}} counterparts, 7705except that they return the value that exists in the memory location 7706after the operation, rather than before the operation. 7707 7708@cindex @code{sync_lock_test_and_set@var{mode}} instruction pattern 7709@item @samp{sync_lock_test_and_set@var{mode}} 7710This pattern takes two forms, based on the capabilities of the target. 7711In either case, operand 0 is the result of the operand, operand 1 is 7712the memory on which the atomic operation is performed, and operand 2 7713is the value to set in the lock. 7714 7715In the ideal case, this operation is an atomic exchange operation, in 7716which the previous value in memory operand is copied into the result 7717operand, and the value operand is stored in the memory operand. 7718 7719For less capable targets, any value operand that is not the constant 1 7720should be rejected with @code{FAIL}. In this case the target may use 7721an atomic test-and-set bit operation. The result operand should contain 77221 if the bit was previously set and 0 if the bit was previously clear. 7723The true contents of the memory operand are implementation defined. 7724 7725This pattern must issue any memory barrier instructions such that the 7726pattern as a whole acts as an acquire barrier, that is all memory 7727operations after the pattern do not occur until the lock is acquired. 7728 7729If this pattern is not defined, the operation will be constructed from 7730a compare-and-swap operation, if defined. 7731 7732@cindex @code{sync_lock_release@var{mode}} instruction pattern 7733@item @samp{sync_lock_release@var{mode}} 7734This pattern, if defined, releases a lock set by 7735@code{sync_lock_test_and_set@var{mode}}. Operand 0 is the memory 7736that contains the lock; operand 1 is the value to store in the lock. 7737 7738If the target doesn't implement full semantics for 7739@code{sync_lock_test_and_set@var{mode}}, any value operand which is not 7740the constant 0 should be rejected with @code{FAIL}, and the true contents 7741of the memory operand are implementation defined. 7742 7743This pattern must issue any memory barrier instructions such that the 7744pattern as a whole acts as a release barrier, that is the lock is 7745released only after all previous memory operations have completed. 7746 7747If this pattern is not defined, then a @code{memory_barrier} pattern 7748will be emitted, followed by a store of the value to the memory operand. 7749 7750@cindex @code{atomic_compare_and_swap@var{mode}} instruction pattern 7751@item @samp{atomic_compare_and_swap@var{mode}} 7752This pattern, if defined, emits code for an atomic compare-and-swap 7753operation with memory model semantics. Operand 2 is the memory on which 7754the atomic operation is performed. Operand 0 is an output operand which 7755is set to true or false based on whether the operation succeeded. Operand 77561 is an output operand which is set to the contents of the memory before 7757the operation was attempted. Operand 3 is the value that is expected to 7758be in memory. Operand 4 is the value to put in memory if the expected 7759value is found there. Operand 5 is set to 1 if this compare and swap is to 7760be treated as a weak operation. Operand 6 is the memory model to be used 7761if the operation is a success. Operand 7 is the memory model to be used 7762if the operation fails. 7763 7764If memory referred to in operand 2 contains the value in operand 3, then 7765operand 4 is stored in memory pointed to by operand 2 and fencing based on 7766the memory model in operand 6 is issued. 7767 7768If memory referred to in operand 2 does not contain the value in operand 3, 7769then fencing based on the memory model in operand 7 is issued. 7770 7771If a target does not support weak compare-and-swap operations, or the port 7772elects not to implement weak operations, the argument in operand 5 can be 7773ignored. Note a strong implementation must be provided. 7774 7775If this pattern is not provided, the @code{__atomic_compare_exchange} 7776built-in functions will utilize the legacy @code{sync_compare_and_swap} 7777pattern with an @code{__ATOMIC_SEQ_CST} memory model. 7778 7779@cindex @code{atomic_load@var{mode}} instruction pattern 7780@item @samp{atomic_load@var{mode}} 7781This pattern implements an atomic load operation with memory model 7782semantics. Operand 1 is the memory address being loaded from. Operand 0 7783is the result of the load. Operand 2 is the memory model to be used for 7784the load operation. 7785 7786If not present, the @code{__atomic_load} built-in function will either 7787resort to a normal load with memory barriers, or a compare-and-swap 7788operation if a normal load would not be atomic. 7789 7790@cindex @code{atomic_store@var{mode}} instruction pattern 7791@item @samp{atomic_store@var{mode}} 7792This pattern implements an atomic store operation with memory model 7793semantics. Operand 0 is the memory address being stored to. Operand 1 7794is the value to be written. Operand 2 is the memory model to be used for 7795the operation. 7796 7797If not present, the @code{__atomic_store} built-in function will attempt to 7798perform a normal store and surround it with any required memory fences. If 7799the store would not be atomic, then an @code{__atomic_exchange} is 7800attempted with the result being ignored. 7801 7802@cindex @code{atomic_exchange@var{mode}} instruction pattern 7803@item @samp{atomic_exchange@var{mode}} 7804This pattern implements an atomic exchange operation with memory model 7805semantics. Operand 1 is the memory location the operation is performed on. 7806Operand 0 is an output operand which is set to the original value contained 7807in the memory pointed to by operand 1. Operand 2 is the value to be 7808stored. Operand 3 is the memory model to be used. 7809 7810If this pattern is not present, the built-in function 7811@code{__atomic_exchange} will attempt to preform the operation with a 7812compare and swap loop. 7813 7814@cindex @code{atomic_add@var{mode}} instruction pattern 7815@cindex @code{atomic_sub@var{mode}} instruction pattern 7816@cindex @code{atomic_or@var{mode}} instruction pattern 7817@cindex @code{atomic_and@var{mode}} instruction pattern 7818@cindex @code{atomic_xor@var{mode}} instruction pattern 7819@cindex @code{atomic_nand@var{mode}} instruction pattern 7820@item @samp{atomic_add@var{mode}}, @samp{atomic_sub@var{mode}} 7821@itemx @samp{atomic_or@var{mode}}, @samp{atomic_and@var{mode}} 7822@itemx @samp{atomic_xor@var{mode}}, @samp{atomic_nand@var{mode}} 7823These patterns emit code for an atomic operation on memory with memory 7824model semantics. Operand 0 is the memory on which the atomic operation is 7825performed. Operand 1 is the second operand to the binary operator. 7826Operand 2 is the memory model to be used by the operation. 7827 7828If these patterns are not defined, attempts will be made to use legacy 7829@code{sync} patterns, or equivalent patterns which return a result. If 7830none of these are available a compare-and-swap loop will be used. 7831 7832@cindex @code{atomic_fetch_add@var{mode}} instruction pattern 7833@cindex @code{atomic_fetch_sub@var{mode}} instruction pattern 7834@cindex @code{atomic_fetch_or@var{mode}} instruction pattern 7835@cindex @code{atomic_fetch_and@var{mode}} instruction pattern 7836@cindex @code{atomic_fetch_xor@var{mode}} instruction pattern 7837@cindex @code{atomic_fetch_nand@var{mode}} instruction pattern 7838@item @samp{atomic_fetch_add@var{mode}}, @samp{atomic_fetch_sub@var{mode}} 7839@itemx @samp{atomic_fetch_or@var{mode}}, @samp{atomic_fetch_and@var{mode}} 7840@itemx @samp{atomic_fetch_xor@var{mode}}, @samp{atomic_fetch_nand@var{mode}} 7841These patterns emit code for an atomic operation on memory with memory 7842model semantics, and return the original value. Operand 0 is an output 7843operand which contains the value of the memory location before the 7844operation was performed. Operand 1 is the memory on which the atomic 7845operation is performed. Operand 2 is the second operand to the binary 7846operator. Operand 3 is the memory model to be used by the operation. 7847 7848If these patterns are not defined, attempts will be made to use legacy 7849@code{sync} patterns. If none of these are available a compare-and-swap 7850loop will be used. 7851 7852@cindex @code{atomic_add_fetch@var{mode}} instruction pattern 7853@cindex @code{atomic_sub_fetch@var{mode}} instruction pattern 7854@cindex @code{atomic_or_fetch@var{mode}} instruction pattern 7855@cindex @code{atomic_and_fetch@var{mode}} instruction pattern 7856@cindex @code{atomic_xor_fetch@var{mode}} instruction pattern 7857@cindex @code{atomic_nand_fetch@var{mode}} instruction pattern 7858@item @samp{atomic_add_fetch@var{mode}}, @samp{atomic_sub_fetch@var{mode}} 7859@itemx @samp{atomic_or_fetch@var{mode}}, @samp{atomic_and_fetch@var{mode}} 7860@itemx @samp{atomic_xor_fetch@var{mode}}, @samp{atomic_nand_fetch@var{mode}} 7861These patterns emit code for an atomic operation on memory with memory 7862model semantics and return the result after the operation is performed. 7863Operand 0 is an output operand which contains the value after the 7864operation. Operand 1 is the memory on which the atomic operation is 7865performed. Operand 2 is the second operand to the binary operator. 7866Operand 3 is the memory model to be used by the operation. 7867 7868If these patterns are not defined, attempts will be made to use legacy 7869@code{sync} patterns, or equivalent patterns which return the result before 7870the operation followed by the arithmetic operation required to produce the 7871result. If none of these are available a compare-and-swap loop will be 7872used. 7873 7874@cindex @code{atomic_test_and_set} instruction pattern 7875@item @samp{atomic_test_and_set} 7876This pattern emits code for @code{__builtin_atomic_test_and_set}. 7877Operand 0 is an output operand which is set to true if the previous 7878previous contents of the byte was "set", and false otherwise. Operand 1 7879is the @code{QImode} memory to be modified. Operand 2 is the memory 7880model to be used. 7881 7882The specific value that defines "set" is implementation defined, and 7883is normally based on what is performed by the native atomic test and set 7884instruction. 7885 7886@cindex @code{atomic_bit_test_and_set@var{mode}} instruction pattern 7887@cindex @code{atomic_bit_test_and_complement@var{mode}} instruction pattern 7888@cindex @code{atomic_bit_test_and_reset@var{mode}} instruction pattern 7889@item @samp{atomic_bit_test_and_set@var{mode}} 7890@itemx @samp{atomic_bit_test_and_complement@var{mode}} 7891@itemx @samp{atomic_bit_test_and_reset@var{mode}} 7892These patterns emit code for an atomic bitwise operation on memory with memory 7893model semantics, and return the original value of the specified bit. 7894Operand 0 is an output operand which contains the value of the specified bit 7895from the memory location before the operation was performed. Operand 1 is the 7896memory on which the atomic operation is performed. Operand 2 is the bit within 7897the operand, starting with least significant bit. Operand 3 is the memory model 7898to be used by the operation. Operand 4 is a flag - it is @code{const1_rtx} 7899if operand 0 should contain the original value of the specified bit in the 7900least significant bit of the operand, and @code{const0_rtx} if the bit should 7901be in its original position in the operand. 7902@code{atomic_bit_test_and_set@var{mode}} atomically sets the specified bit after 7903remembering its original value, @code{atomic_bit_test_and_complement@var{mode}} 7904inverts the specified bit and @code{atomic_bit_test_and_reset@var{mode}} clears 7905the specified bit. 7906 7907If these patterns are not defined, attempts will be made to use 7908@code{atomic_fetch_or@var{mode}}, @code{atomic_fetch_xor@var{mode}} or 7909@code{atomic_fetch_and@var{mode}} instruction patterns, or their @code{sync} 7910counterparts. If none of these are available a compare-and-swap 7911loop will be used. 7912 7913@cindex @code{mem_thread_fence} instruction pattern 7914@item @samp{mem_thread_fence} 7915This pattern emits code required to implement a thread fence with 7916memory model semantics. Operand 0 is the memory model to be used. 7917 7918For the @code{__ATOMIC_RELAXED} model no instructions need to be issued 7919and this expansion is not invoked. 7920 7921The compiler always emits a compiler memory barrier regardless of what 7922expanding this pattern produced. 7923 7924If this pattern is not defined, the compiler falls back to expanding the 7925@code{memory_barrier} pattern, then to emitting @code{__sync_synchronize} 7926library call, and finally to just placing a compiler memory barrier. 7927 7928@cindex @code{get_thread_pointer@var{mode}} instruction pattern 7929@cindex @code{set_thread_pointer@var{mode}} instruction pattern 7930@item @samp{get_thread_pointer@var{mode}} 7931@itemx @samp{set_thread_pointer@var{mode}} 7932These patterns emit code that reads/sets the TLS thread pointer. Currently, 7933these are only needed if the target needs to support the 7934@code{__builtin_thread_pointer} and @code{__builtin_set_thread_pointer} 7935builtins. 7936 7937The get/set patterns have a single output/input operand respectively, 7938with @var{mode} intended to be @code{Pmode}. 7939 7940@cindex @code{stack_protect_combined_set} instruction pattern 7941@item @samp{stack_protect_combined_set} 7942This pattern, if defined, moves a @code{ptr_mode} value from an address 7943whose declaration RTX is given in operand 1 to the memory in operand 0 7944without leaving the value in a register afterward. If several 7945instructions are needed by the target to perform the operation (eg. to 7946load the address from a GOT entry then load the @code{ptr_mode} value 7947and finally store it), it is the backend's responsibility to ensure no 7948intermediate result gets spilled. This is to avoid leaking the value 7949some place that an attacker might use to rewrite the stack guard slot 7950after having clobbered it. 7951 7952If this pattern is not defined, then the address declaration is 7953expanded first in the standard way and a @code{stack_protect_set} 7954pattern is then generated to move the value from that address to the 7955address in operand 0. 7956 7957@cindex @code{stack_protect_set} instruction pattern 7958@item @samp{stack_protect_set} 7959This pattern, if defined, moves a @code{ptr_mode} value from the valid 7960memory location in operand 1 to the memory in operand 0 without leaving 7961the value in a register afterward. This is to avoid leaking the value 7962some place that an attacker might use to rewrite the stack guard slot 7963after having clobbered it. 7964 7965Note: on targets where the addressing modes do not allow to load 7966directly from stack guard address, the address is expanded in a standard 7967way first which could cause some spills. 7968 7969If this pattern is not defined, then a plain move pattern is generated. 7970 7971@cindex @code{stack_protect_combined_test} instruction pattern 7972@item @samp{stack_protect_combined_test} 7973This pattern, if defined, compares a @code{ptr_mode} value from an 7974address whose declaration RTX is given in operand 1 with the memory in 7975operand 0 without leaving the value in a register afterward and 7976branches to operand 2 if the values were equal. If several 7977instructions are needed by the target to perform the operation (eg. to 7978load the address from a GOT entry then load the @code{ptr_mode} value 7979and finally store it), it is the backend's responsibility to ensure no 7980intermediate result gets spilled. This is to avoid leaking the value 7981some place that an attacker might use to rewrite the stack guard slot 7982after having clobbered it. 7983 7984If this pattern is not defined, then the address declaration is 7985expanded first in the standard way and a @code{stack_protect_test} 7986pattern is then generated to compare the value from that address to the 7987value at the memory in operand 0. 7988 7989@cindex @code{stack_protect_test} instruction pattern 7990@item @samp{stack_protect_test} 7991This pattern, if defined, compares a @code{ptr_mode} value from the 7992valid memory location in operand 1 with the memory in operand 0 without 7993leaving the value in a register afterward and branches to operand 2 if 7994the values were equal. 7995 7996If this pattern is not defined, then a plain compare pattern and 7997conditional branch pattern is used. 7998 7999@cindex @code{clear_cache} instruction pattern 8000@item @samp{clear_cache} 8001This pattern, if defined, flushes the instruction cache for a region of 8002memory. The region is bounded to by the Pmode pointers in operand 0 8003inclusive and operand 1 exclusive. 8004 8005If this pattern is not defined, a call to the library function 8006@code{__clear_cache} is used. 8007 8008@end table 8009 8010@end ifset 8011@c Each of the following nodes are wrapped in separate 8012@c "@ifset INTERNALS" to work around memory limits for the default 8013@c configuration in older tetex distributions. Known to not work: 8014@c tetex-1.0.7, known to work: tetex-2.0.2. 8015@ifset INTERNALS 8016@node Pattern Ordering 8017@section When the Order of Patterns Matters 8018@cindex Pattern Ordering 8019@cindex Ordering of Patterns 8020 8021Sometimes an insn can match more than one instruction pattern. Then the 8022pattern that appears first in the machine description is the one used. 8023Therefore, more specific patterns (patterns that will match fewer things) 8024and faster instructions (those that will produce better code when they 8025do match) should usually go first in the description. 8026 8027In some cases the effect of ordering the patterns can be used to hide 8028a pattern when it is not valid. For example, the 68000 has an 8029instruction for converting a fullword to floating point and another 8030for converting a byte to floating point. An instruction converting 8031an integer to floating point could match either one. We put the 8032pattern to convert the fullword first to make sure that one will 8033be used rather than the other. (Otherwise a large integer might 8034be generated as a single-byte immediate quantity, which would not work.) 8035Instead of using this pattern ordering it would be possible to make the 8036pattern for convert-a-byte smart enough to deal properly with any 8037constant value. 8038 8039@end ifset 8040@ifset INTERNALS 8041@node Dependent Patterns 8042@section Interdependence of Patterns 8043@cindex Dependent Patterns 8044@cindex Interdependence of Patterns 8045 8046In some cases machines support instructions identical except for the 8047machine mode of one or more operands. For example, there may be 8048``sign-extend halfword'' and ``sign-extend byte'' instructions whose 8049patterns are 8050 8051@smallexample 8052(set (match_operand:SI 0 @dots{}) 8053 (extend:SI (match_operand:HI 1 @dots{}))) 8054 8055(set (match_operand:SI 0 @dots{}) 8056 (extend:SI (match_operand:QI 1 @dots{}))) 8057@end smallexample 8058 8059@noindent 8060Constant integers do not specify a machine mode, so an instruction to 8061extend a constant value could match either pattern. The pattern it 8062actually will match is the one that appears first in the file. For correct 8063results, this must be the one for the widest possible mode (@code{HImode}, 8064here). If the pattern matches the @code{QImode} instruction, the results 8065will be incorrect if the constant value does not actually fit that mode. 8066 8067Such instructions to extend constants are rarely generated because they are 8068optimized away, but they do occasionally happen in nonoptimized 8069compilations. 8070 8071If a constraint in a pattern allows a constant, the reload pass may 8072replace a register with a constant permitted by the constraint in some 8073cases. Similarly for memory references. Because of this substitution, 8074you should not provide separate patterns for increment and decrement 8075instructions. Instead, they should be generated from the same pattern 8076that supports register-register add insns by examining the operands and 8077generating the appropriate machine instruction. 8078 8079@end ifset 8080@ifset INTERNALS 8081@node Jump Patterns 8082@section Defining Jump Instruction Patterns 8083@cindex jump instruction patterns 8084@cindex defining jump instruction patterns 8085 8086GCC does not assume anything about how the machine realizes jumps. 8087The machine description should define a single pattern, usually 8088a @code{define_expand}, which expands to all the required insns. 8089 8090Usually, this would be a comparison insn to set the condition code 8091and a separate branch insn testing the condition code and branching 8092or not according to its value. For many machines, however, 8093separating compares and branches is limiting, which is why the 8094more flexible approach with one @code{define_expand} is used in GCC. 8095The machine description becomes clearer for architectures that 8096have compare-and-branch instructions but no condition code. It also 8097works better when different sets of comparison operators are supported 8098by different kinds of conditional branches (e.g.@: integer vs.@: 8099floating-point), or by conditional branches with respect to conditional stores. 8100 8101Two separate insns are always used on most machines that use a separate 8102condition code register (@pxref{Condition Code}). 8103 8104Even in this case having a single entry point for conditional branches 8105is advantageous, because it handles equally well the case where a single 8106comparison instruction records the results of both signed and unsigned 8107comparison of the given operands (with the branch insns coming in distinct 8108signed and unsigned flavors) as in the x86 or SPARC, and the case where 8109there are distinct signed and unsigned compare instructions and only 8110one set of conditional branch instructions as in the PowerPC. 8111 8112@end ifset 8113@ifset INTERNALS 8114@node Looping Patterns 8115@section Defining Looping Instruction Patterns 8116@cindex looping instruction patterns 8117@cindex defining looping instruction patterns 8118 8119Some machines have special jump instructions that can be utilized to 8120make loops more efficient. A common example is the 68000 @samp{dbra} 8121instruction which performs a decrement of a register and a branch if the 8122result was greater than zero. Other machines, in particular digital 8123signal processors (DSPs), have special block repeat instructions to 8124provide low-overhead loop support. For example, the TI TMS320C3x/C4x 8125DSPs have a block repeat instruction that loads special registers to 8126mark the top and end of a loop and to count the number of loop 8127iterations. This avoids the need for fetching and executing a 8128@samp{dbra}-like instruction and avoids pipeline stalls associated with 8129the jump. 8130 8131GCC has two special named patterns to support low overhead looping. 8132They are @samp{doloop_begin} and @samp{doloop_end}. These are emitted 8133by the loop optimizer for certain well-behaved loops with a finite 8134number of loop iterations using information collected during strength 8135reduction. 8136 8137The @samp{doloop_end} pattern describes the actual looping instruction 8138(or the implicit looping operation) and the @samp{doloop_begin} pattern 8139is an optional companion pattern that can be used for initialization 8140needed for some low-overhead looping instructions. 8141 8142Note that some machines require the actual looping instruction to be 8143emitted at the top of the loop (e.g., the TMS320C3x/C4x DSPs). Emitting 8144the true RTL for a looping instruction at the top of the loop can cause 8145problems with flow analysis. So instead, a dummy @code{doloop} insn is 8146emitted at the end of the loop. The machine dependent reorg pass checks 8147for the presence of this @code{doloop} insn and then searches back to 8148the top of the loop, where it inserts the true looping insn (provided 8149there are no instructions in the loop which would cause problems). Any 8150additional labels can be emitted at this point. In addition, if the 8151desired special iteration counter register was not allocated, this 8152machine dependent reorg pass could emit a traditional compare and jump 8153instruction pair. 8154 8155For the @samp{doloop_end} pattern, the loop optimizer allocates an 8156additional pseudo register as an iteration counter. This pseudo 8157register cannot be used within the loop (i.e., general induction 8158variables cannot be derived from it), however, in many cases the loop 8159induction variable may become redundant and removed by the flow pass. 8160 8161The @samp{doloop_end} pattern must have a specific structure to be 8162handled correctly by GCC. The example below is taken (slightly 8163simplified) from the PDP-11 target: 8164 8165@smallexample 8166@group 8167(define_expand "doloop_end" 8168 [(parallel [(set (pc) 8169 (if_then_else 8170 (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m") 8171 (const_int 1)) 8172 (label_ref (match_operand 1 "" "")) 8173 (pc))) 8174 (set (match_dup 0) 8175 (plus:HI (match_dup 0) 8176 (const_int -1)))])] 8177 "" 8178 "@{ 8179 if (GET_MODE (operands[0]) != HImode) 8180 FAIL; 8181 @}") 8182 8183(define_insn "doloop_end_insn" 8184 [(set (pc) 8185 (if_then_else 8186 (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m") 8187 (const_int 1)) 8188 (label_ref (match_operand 1 "" "")) 8189 (pc))) 8190 (set (match_dup 0) 8191 (plus:HI (match_dup 0) 8192 (const_int -1)))] 8193 "" 8194 8195 @{ 8196 if (which_alternative == 0) 8197 return "sob %0,%l1"; 8198 8199 /* emulate sob */ 8200 output_asm_insn ("dec %0", operands); 8201 return "bne %l1"; 8202 @}) 8203@end group 8204@end smallexample 8205 8206The first part of the pattern describes the branch condition. GCC 8207supports three cases for the way the target machine handles the loop 8208counter: 8209@itemize @bullet 8210@item Loop terminates when the loop register decrements to zero. This 8211is represented by a @code{ne} comparison of the register (its old value) 8212with constant 1 (as in the example above). 8213@item Loop terminates when the loop register decrements to @minus{}1. 8214This is represented by a @code{ne} comparison of the register with 8215constant zero. 8216@item Loop terminates when the loop register decrements to a negative 8217value. This is represented by a @code{ge} comparison of the register 8218with constant zero. For this case, GCC will attach a @code{REG_NONNEG} 8219note to the @code{doloop_end} insn if it can determine that the register 8220will be non-negative. 8221@end itemize 8222 8223Since the @code{doloop_end} insn is a jump insn that also has an output, 8224the reload pass does not handle the output operand. Therefore, the 8225constraint must allow for that operand to be in memory rather than a 8226register. In the example shown above, that is handled (in the 8227@code{doloop_end_insn} pattern) by using a loop instruction sequence 8228that can handle memory operands when the memory alternative appears. 8229 8230GCC does not check the mode of the loop register operand when generating 8231the @code{doloop_end} pattern. If the pattern is only valid for some 8232modes but not others, the pattern should be a @code{define_expand} 8233pattern that checks the operand mode in the preparation code, and issues 8234@code{FAIL} if an unsupported mode is found. The example above does 8235this, since the machine instruction to be used only exists for 8236@code{HImode}. 8237 8238If the @code{doloop_end} pattern is a @code{define_expand}, there must 8239also be a @code{define_insn} or @code{define_insn_and_split} matching 8240the generated pattern. Otherwise, the compiler will fail during loop 8241optimization. 8242 8243@end ifset 8244@ifset INTERNALS 8245@node Insn Canonicalizations 8246@section Canonicalization of Instructions 8247@cindex canonicalization of instructions 8248@cindex insn canonicalization 8249 8250There are often cases where multiple RTL expressions could represent an 8251operation performed by a single machine instruction. This situation is 8252most commonly encountered with logical, branch, and multiply-accumulate 8253instructions. In such cases, the compiler attempts to convert these 8254multiple RTL expressions into a single canonical form to reduce the 8255number of insn patterns required. 8256 8257In addition to algebraic simplifications, following canonicalizations 8258are performed: 8259 8260@itemize @bullet 8261@item 8262For commutative and comparison operators, a constant is always made the 8263second operand. If a machine only supports a constant as the second 8264operand, only patterns that match a constant in the second operand need 8265be supplied. 8266 8267@item 8268For associative operators, a sequence of operators will always chain 8269to the left; for instance, only the left operand of an integer @code{plus} 8270can itself be a @code{plus}. @code{and}, @code{ior}, @code{xor}, 8271@code{plus}, @code{mult}, @code{smin}, @code{smax}, @code{umin}, and 8272@code{umax} are associative when applied to integers, and sometimes to 8273floating-point. 8274 8275@item 8276@cindex @code{neg}, canonicalization of 8277@cindex @code{not}, canonicalization of 8278@cindex @code{mult}, canonicalization of 8279@cindex @code{plus}, canonicalization of 8280@cindex @code{minus}, canonicalization of 8281For these operators, if only one operand is a @code{neg}, @code{not}, 8282@code{mult}, @code{plus}, or @code{minus} expression, it will be the 8283first operand. 8284 8285@item 8286In combinations of @code{neg}, @code{mult}, @code{plus}, and 8287@code{minus}, the @code{neg} operations (if any) will be moved inside 8288the operations as far as possible. For instance, 8289@code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but 8290@code{(plus (mult (neg B) C) A)} is canonicalized as 8291@code{(minus A (mult B C))}. 8292 8293@cindex @code{compare}, canonicalization of 8294@item 8295For the @code{compare} operator, a constant is always the second operand 8296if the first argument is a condition code register. 8297 8298@item 8299For instructions that inherently set a condition code register, the 8300@code{compare} operator is always written as the first RTL expression of 8301the @code{parallel} instruction pattern. For example, 8302 8303@smallexample 8304(define_insn "" 8305 [(set (reg:CCZ FLAGS_REG) 8306 (compare:CCZ 8307 (plus:SI 8308 (match_operand:SI 1 "register_operand" "%r") 8309 (match_operand:SI 2 "register_operand" "r")) 8310 (const_int 0))) 8311 (set (match_operand:SI 0 "register_operand" "=r") 8312 (plus:SI (match_dup 1) (match_dup 2)))] 8313 "" 8314 "addl %0, %1, %2") 8315@end smallexample 8316 8317@item 8318An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or 8319@code{minus} is made the first operand under the same conditions as 8320above. 8321 8322@item 8323@code{(ltu (plus @var{a} @var{b}) @var{b})} is converted to 8324@code{(ltu (plus @var{a} @var{b}) @var{a})}. Likewise with @code{geu} instead 8325of @code{ltu}. 8326 8327@item 8328@code{(minus @var{x} (const_int @var{n}))} is converted to 8329@code{(plus @var{x} (const_int @var{-n}))}. 8330 8331@item 8332Within address computations (i.e., inside @code{mem}), a left shift is 8333converted into the appropriate multiplication by a power of two. 8334 8335@cindex @code{ior}, canonicalization of 8336@cindex @code{and}, canonicalization of 8337@cindex De Morgan's law 8338@item 8339De Morgan's Law is used to move bitwise negation inside a bitwise 8340logical-and or logical-or operation. If this results in only one 8341operand being a @code{not} expression, it will be the first one. 8342 8343A machine that has an instruction that performs a bitwise logical-and of one 8344operand with the bitwise negation of the other should specify the pattern 8345for that instruction as 8346 8347@smallexample 8348(define_insn "" 8349 [(set (match_operand:@var{m} 0 @dots{}) 8350 (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) 8351 (match_operand:@var{m} 2 @dots{})))] 8352 "@dots{}" 8353 "@dots{}") 8354@end smallexample 8355 8356@noindent 8357Similarly, a pattern for a ``NAND'' instruction should be written 8358 8359@smallexample 8360(define_insn "" 8361 [(set (match_operand:@var{m} 0 @dots{}) 8362 (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) 8363 (not:@var{m} (match_operand:@var{m} 2 @dots{}))))] 8364 "@dots{}" 8365 "@dots{}") 8366@end smallexample 8367 8368In both cases, it is not necessary to include patterns for the many 8369logically equivalent RTL expressions. 8370 8371@cindex @code{xor}, canonicalization of 8372@item 8373The only possible RTL expressions involving both bitwise exclusive-or 8374and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})} 8375and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}. 8376 8377@item 8378The sum of three items, one of which is a constant, will only appear in 8379the form 8380 8381@smallexample 8382(plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant}) 8383@end smallexample 8384 8385@cindex @code{zero_extract}, canonicalization of 8386@cindex @code{sign_extract}, canonicalization of 8387@item 8388Equality comparisons of a group of bits (usually a single bit) with zero 8389will be written using @code{zero_extract} rather than the equivalent 8390@code{and} or @code{sign_extract} operations. 8391 8392@cindex @code{mult}, canonicalization of 8393@item 8394@code{(sign_extend:@var{m1} (mult:@var{m2} (sign_extend:@var{m2} @var{x}) 8395(sign_extend:@var{m2} @var{y})))} is converted to @code{(mult:@var{m1} 8396(sign_extend:@var{m1} @var{x}) (sign_extend:@var{m1} @var{y}))}, and likewise 8397for @code{zero_extend}. 8398 8399@item 8400@code{(sign_extend:@var{m1} (mult:@var{m2} (ashiftrt:@var{m2} 8401@var{x} @var{s}) (sign_extend:@var{m2} @var{y})))} is converted 8402to @code{(mult:@var{m1} (sign_extend:@var{m1} (ashiftrt:@var{m2} 8403@var{x} @var{s})) (sign_extend:@var{m1} @var{y}))}, and likewise for 8404patterns using @code{zero_extend} and @code{lshiftrt}. If the second 8405operand of @code{mult} is also a shift, then that is extended also. 8406This transformation is only applied when it can be proven that the 8407original operation had sufficient precision to prevent overflow. 8408 8409@end itemize 8410 8411Further canonicalization rules are defined in the function 8412@code{commutative_operand_precedence} in @file{gcc/rtlanal.c}. 8413 8414@end ifset 8415@ifset INTERNALS 8416@node Expander Definitions 8417@section Defining RTL Sequences for Code Generation 8418@cindex expander definitions 8419@cindex code generation RTL sequences 8420@cindex defining RTL sequences for code generation 8421 8422On some target machines, some standard pattern names for RTL generation 8423cannot be handled with single insn, but a sequence of RTL insns can 8424represent them. For these target machines, you can write a 8425@code{define_expand} to specify how to generate the sequence of RTL@. 8426 8427@findex define_expand 8428A @code{define_expand} is an RTL expression that looks almost like a 8429@code{define_insn}; but, unlike the latter, a @code{define_expand} is used 8430only for RTL generation and it can produce more than one RTL insn. 8431 8432A @code{define_expand} RTX has four operands: 8433 8434@itemize @bullet 8435@item 8436The name. Each @code{define_expand} must have a name, since the only 8437use for it is to refer to it by name. 8438 8439@item 8440The RTL template. This is a vector of RTL expressions representing 8441a sequence of separate instructions. Unlike @code{define_insn}, there 8442is no implicit surrounding @code{PARALLEL}. 8443 8444@item 8445The condition, a string containing a C expression. This expression is 8446used to express how the availability of this pattern depends on 8447subclasses of target machine, selected by command-line options when GCC 8448is run. This is just like the condition of a @code{define_insn} that 8449has a standard name. Therefore, the condition (if present) may not 8450depend on the data in the insn being matched, but only the 8451target-machine-type flags. The compiler needs to test these conditions 8452during initialization in order to learn exactly which named instructions 8453are available in a particular run. 8454 8455@item 8456The preparation statements, a string containing zero or more C 8457statements which are to be executed before RTL code is generated from 8458the RTL template. 8459 8460Usually these statements prepare temporary registers for use as 8461internal operands in the RTL template, but they can also generate RTL 8462insns directly by calling routines such as @code{emit_insn}, etc. 8463Any such insns precede the ones that come from the RTL template. 8464 8465@item 8466Optionally, a vector containing the values of attributes. @xref{Insn 8467Attributes}. 8468@end itemize 8469 8470Every RTL insn emitted by a @code{define_expand} must match some 8471@code{define_insn} in the machine description. Otherwise, the compiler 8472will crash when trying to generate code for the insn or trying to optimize 8473it. 8474 8475The RTL template, in addition to controlling generation of RTL insns, 8476also describes the operands that need to be specified when this pattern 8477is used. In particular, it gives a predicate for each operand. 8478 8479A true operand, which needs to be specified in order to generate RTL from 8480the pattern, should be described with a @code{match_operand} in its first 8481occurrence in the RTL template. This enters information on the operand's 8482predicate into the tables that record such things. GCC uses the 8483information to preload the operand into a register if that is required for 8484valid RTL code. If the operand is referred to more than once, subsequent 8485references should use @code{match_dup}. 8486 8487The RTL template may also refer to internal ``operands'' which are 8488temporary registers or labels used only within the sequence made by the 8489@code{define_expand}. Internal operands are substituted into the RTL 8490template with @code{match_dup}, never with @code{match_operand}. The 8491values of the internal operands are not passed in as arguments by the 8492compiler when it requests use of this pattern. Instead, they are computed 8493within the pattern, in the preparation statements. These statements 8494compute the values and store them into the appropriate elements of 8495@code{operands} so that @code{match_dup} can find them. 8496 8497There are two special macros defined for use in the preparation statements: 8498@code{DONE} and @code{FAIL}. Use them with a following semicolon, 8499as a statement. 8500 8501@table @code 8502 8503@findex DONE 8504@item DONE 8505Use the @code{DONE} macro to end RTL generation for the pattern. The 8506only RTL insns resulting from the pattern on this occasion will be 8507those already emitted by explicit calls to @code{emit_insn} within the 8508preparation statements; the RTL template will not be generated. 8509 8510@findex FAIL 8511@item FAIL 8512Make the pattern fail on this occasion. When a pattern fails, it means 8513that the pattern was not truly available. The calling routines in the 8514compiler will try other strategies for code generation using other patterns. 8515 8516Failure is currently supported only for binary (addition, multiplication, 8517shifting, etc.) and bit-field (@code{extv}, @code{extzv}, and @code{insv}) 8518operations. 8519@end table 8520 8521If the preparation falls through (invokes neither @code{DONE} nor 8522@code{FAIL}), then the @code{define_expand} acts like a 8523@code{define_insn} in that the RTL template is used to generate the 8524insn. 8525 8526The RTL template is not used for matching, only for generating the 8527initial insn list. If the preparation statement always invokes 8528@code{DONE} or @code{FAIL}, the RTL template may be reduced to a simple 8529list of operands, such as this example: 8530 8531@smallexample 8532@group 8533(define_expand "addsi3" 8534 [(match_operand:SI 0 "register_operand" "") 8535 (match_operand:SI 1 "register_operand" "") 8536 (match_operand:SI 2 "register_operand" "")] 8537 "" 8538 " 8539@{ 8540 handle_add (operands[0], operands[1], operands[2]); 8541 DONE; 8542@}") 8543@end group 8544@end smallexample 8545 8546Here is an example, the definition of left-shift for the SPUR chip: 8547 8548@smallexample 8549@group 8550(define_expand "ashlsi3" 8551 [(set (match_operand:SI 0 "register_operand" "") 8552 (ashift:SI 8553 (match_operand:SI 1 "register_operand" "") 8554 (match_operand:SI 2 "nonmemory_operand" "")))] 8555 "" 8556 " 8557@{ 8558 if (GET_CODE (operands[2]) != CONST_INT 8559 || (unsigned) INTVAL (operands[2]) > 3) 8560 FAIL; 8561@}") 8562@end group 8563@end smallexample 8564 8565@noindent 8566This example uses @code{define_expand} so that it can generate an RTL insn 8567for shifting when the shift-count is in the supported range of 0 to 3 but 8568fail in other cases where machine insns aren't available. When it fails, 8569the compiler tries another strategy using different patterns (such as, a 8570library call). 8571 8572If the compiler were able to handle nontrivial condition-strings in 8573patterns with names, then it would be possible to use a 8574@code{define_insn} in that case. Here is another case (zero-extension 8575on the 68000) which makes more use of the power of @code{define_expand}: 8576 8577@smallexample 8578(define_expand "zero_extendhisi2" 8579 [(set (match_operand:SI 0 "general_operand" "") 8580 (const_int 0)) 8581 (set (strict_low_part 8582 (subreg:HI 8583 (match_dup 0) 8584 0)) 8585 (match_operand:HI 1 "general_operand" ""))] 8586 "" 8587 "operands[1] = make_safe_from (operands[1], operands[0]);") 8588@end smallexample 8589 8590@noindent 8591@findex make_safe_from 8592Here two RTL insns are generated, one to clear the entire output operand 8593and the other to copy the input operand into its low half. This sequence 8594is incorrect if the input operand refers to [the old value of] the output 8595operand, so the preparation statement makes sure this isn't so. The 8596function @code{make_safe_from} copies the @code{operands[1]} into a 8597temporary register if it refers to @code{operands[0]}. It does this 8598by emitting another RTL insn. 8599 8600Finally, a third example shows the use of an internal operand. 8601Zero-extension on the SPUR chip is done by @code{and}-ing the result 8602against a halfword mask. But this mask cannot be represented by a 8603@code{const_int} because the constant value is too large to be legitimate 8604on this machine. So it must be copied into a register with 8605@code{force_reg} and then the register used in the @code{and}. 8606 8607@smallexample 8608(define_expand "zero_extendhisi2" 8609 [(set (match_operand:SI 0 "register_operand" "") 8610 (and:SI (subreg:SI 8611 (match_operand:HI 1 "register_operand" "") 8612 0) 8613 (match_dup 2)))] 8614 "" 8615 "operands[2] 8616 = force_reg (SImode, GEN_INT (65535)); ") 8617@end smallexample 8618 8619@emph{Note:} If the @code{define_expand} is used to serve a 8620standard binary or unary arithmetic operation or a bit-field operation, 8621then the last insn it generates must not be a @code{code_label}, 8622@code{barrier} or @code{note}. It must be an @code{insn}, 8623@code{jump_insn} or @code{call_insn}. If you don't need a real insn 8624at the end, emit an insn to copy the result of the operation into 8625itself. Such an insn will generate no code, but it can avoid problems 8626in the compiler. 8627 8628@end ifset 8629@ifset INTERNALS 8630@node Insn Splitting 8631@section Defining How to Split Instructions 8632@cindex insn splitting 8633@cindex instruction splitting 8634@cindex splitting instructions 8635 8636There are two cases where you should specify how to split a pattern 8637into multiple insns. On machines that have instructions requiring 8638delay slots (@pxref{Delay Slots}) or that have instructions whose 8639output is not available for multiple cycles (@pxref{Processor pipeline 8640description}), the compiler phases that optimize these cases need to 8641be able to move insns into one-instruction delay slots. However, some 8642insns may generate more than one machine instruction. These insns 8643cannot be placed into a delay slot. 8644 8645Often you can rewrite the single insn as a list of individual insns, 8646each corresponding to one machine instruction. The disadvantage of 8647doing so is that it will cause the compilation to be slower and require 8648more space. If the resulting insns are too complex, it may also 8649suppress some optimizations. The compiler splits the insn if there is a 8650reason to believe that it might improve instruction or delay slot 8651scheduling. 8652 8653The insn combiner phase also splits putative insns. If three insns are 8654merged into one insn with a complex expression that cannot be matched by 8655some @code{define_insn} pattern, the combiner phase attempts to split 8656the complex pattern into two insns that are recognized. Usually it can 8657break the complex pattern into two patterns by splitting out some 8658subexpression. However, in some other cases, such as performing an 8659addition of a large constant in two insns on a RISC machine, the way to 8660split the addition into two insns is machine-dependent. 8661 8662@findex define_split 8663The @code{define_split} definition tells the compiler how to split a 8664complex insn into several simpler insns. It looks like this: 8665 8666@smallexample 8667(define_split 8668 [@var{insn-pattern}] 8669 "@var{condition}" 8670 [@var{new-insn-pattern-1} 8671 @var{new-insn-pattern-2} 8672 @dots{}] 8673 "@var{preparation-statements}") 8674@end smallexample 8675 8676@var{insn-pattern} is a pattern that needs to be split and 8677@var{condition} is the final condition to be tested, as in a 8678@code{define_insn}. When an insn matching @var{insn-pattern} and 8679satisfying @var{condition} is found, it is replaced in the insn list 8680with the insns given by @var{new-insn-pattern-1}, 8681@var{new-insn-pattern-2}, etc. 8682 8683The @var{preparation-statements} are similar to those statements that 8684are specified for @code{define_expand} (@pxref{Expander Definitions}) 8685and are executed before the new RTL is generated to prepare for the 8686generated code or emit some insns whose pattern is not fixed. Unlike 8687those in @code{define_expand}, however, these statements must not 8688generate any new pseudo-registers. Once reload has completed, they also 8689must not allocate any space in the stack frame. 8690 8691There are two special macros defined for use in the preparation statements: 8692@code{DONE} and @code{FAIL}. Use them with a following semicolon, 8693as a statement. 8694 8695@table @code 8696 8697@findex DONE 8698@item DONE 8699Use the @code{DONE} macro to end RTL generation for the splitter. The 8700only RTL insns generated as replacement for the matched input insn will 8701be those already emitted by explicit calls to @code{emit_insn} within 8702the preparation statements; the replacement pattern is not used. 8703 8704@findex FAIL 8705@item FAIL 8706Make the @code{define_split} fail on this occasion. When a @code{define_split} 8707fails, it means that the splitter was not truly available for the inputs 8708it was given, and the input insn will not be split. 8709@end table 8710 8711If the preparation falls through (invokes neither @code{DONE} nor 8712@code{FAIL}), then the @code{define_split} uses the replacement 8713template. 8714 8715Patterns are matched against @var{insn-pattern} in two different 8716circumstances. If an insn needs to be split for delay slot scheduling 8717or insn scheduling, the insn is already known to be valid, which means 8718that it must have been matched by some @code{define_insn} and, if 8719@code{reload_completed} is nonzero, is known to satisfy the constraints 8720of that @code{define_insn}. In that case, the new insn patterns must 8721also be insns that are matched by some @code{define_insn} and, if 8722@code{reload_completed} is nonzero, must also satisfy the constraints 8723of those definitions. 8724 8725As an example of this usage of @code{define_split}, consider the following 8726example from @file{a29k.md}, which splits a @code{sign_extend} from 8727@code{HImode} to @code{SImode} into a pair of shift insns: 8728 8729@smallexample 8730(define_split 8731 [(set (match_operand:SI 0 "gen_reg_operand" "") 8732 (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))] 8733 "" 8734 [(set (match_dup 0) 8735 (ashift:SI (match_dup 1) 8736 (const_int 16))) 8737 (set (match_dup 0) 8738 (ashiftrt:SI (match_dup 0) 8739 (const_int 16)))] 8740 " 8741@{ operands[1] = gen_lowpart (SImode, operands[1]); @}") 8742@end smallexample 8743 8744When the combiner phase tries to split an insn pattern, it is always the 8745case that the pattern is @emph{not} matched by any @code{define_insn}. 8746The combiner pass first tries to split a single @code{set} expression 8747and then the same @code{set} expression inside a @code{parallel}, but 8748followed by a @code{clobber} of a pseudo-reg to use as a scratch 8749register. In these cases, the combiner expects exactly one or two new insn 8750patterns to be generated. It will verify that these patterns match some 8751@code{define_insn} definitions, so you need not do this test in the 8752@code{define_split} (of course, there is no point in writing a 8753@code{define_split} that will never produce insns that match). 8754 8755Here is an example of this use of @code{define_split}, taken from 8756@file{rs6000.md}: 8757 8758@smallexample 8759(define_split 8760 [(set (match_operand:SI 0 "gen_reg_operand" "") 8761 (plus:SI (match_operand:SI 1 "gen_reg_operand" "") 8762 (match_operand:SI 2 "non_add_cint_operand" "")))] 8763 "" 8764 [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3))) 8765 (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))] 8766" 8767@{ 8768 int low = INTVAL (operands[2]) & 0xffff; 8769 int high = (unsigned) INTVAL (operands[2]) >> 16; 8770 8771 if (low & 0x8000) 8772 high++, low |= 0xffff0000; 8773 8774 operands[3] = GEN_INT (high << 16); 8775 operands[4] = GEN_INT (low); 8776@}") 8777@end smallexample 8778 8779Here the predicate @code{non_add_cint_operand} matches any 8780@code{const_int} that is @emph{not} a valid operand of a single add 8781insn. The add with the smaller displacement is written so that it 8782can be substituted into the address of a subsequent operation. 8783 8784An example that uses a scratch register, from the same file, generates 8785an equality comparison of a register and a large constant: 8786 8787@smallexample 8788(define_split 8789 [(set (match_operand:CC 0 "cc_reg_operand" "") 8790 (compare:CC (match_operand:SI 1 "gen_reg_operand" "") 8791 (match_operand:SI 2 "non_short_cint_operand" ""))) 8792 (clobber (match_operand:SI 3 "gen_reg_operand" ""))] 8793 "find_single_use (operands[0], insn, 0) 8794 && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ 8795 || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)" 8796 [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4))) 8797 (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))] 8798 " 8799@{ 8800 /* @r{Get the constant we are comparing against, C, and see what it 8801 looks like sign-extended to 16 bits. Then see what constant 8802 could be XOR'ed with C to get the sign-extended value.} */ 8803 8804 int c = INTVAL (operands[2]); 8805 int sextc = (c << 16) >> 16; 8806 int xorv = c ^ sextc; 8807 8808 operands[4] = GEN_INT (xorv); 8809 operands[5] = GEN_INT (sextc); 8810@}") 8811@end smallexample 8812 8813To avoid confusion, don't write a single @code{define_split} that 8814accepts some insns that match some @code{define_insn} as well as some 8815insns that don't. Instead, write two separate @code{define_split} 8816definitions, one for the insns that are valid and one for the insns that 8817are not valid. 8818 8819The splitter is allowed to split jump instructions into sequence of 8820jumps or create new jumps in while splitting non-jump instructions. As 8821the control flow graph and branch prediction information needs to be updated, 8822several restriction apply. 8823 8824Splitting of jump instruction into sequence that over by another jump 8825instruction is always valid, as compiler expect identical behavior of new 8826jump. When new sequence contains multiple jump instructions or new labels, 8827more assistance is needed. Splitter is required to create only unconditional 8828jumps, or simple conditional jump instructions. Additionally it must attach a 8829@code{REG_BR_PROB} note to each conditional jump. A global variable 8830@code{split_branch_probability} holds the probability of the original branch in case 8831it was a simple conditional jump, @minus{}1 otherwise. To simplify 8832recomputing of edge frequencies, the new sequence is required to have only 8833forward jumps to the newly created labels. 8834 8835@findex define_insn_and_split 8836For the common case where the pattern of a define_split exactly matches the 8837pattern of a define_insn, use @code{define_insn_and_split}. It looks like 8838this: 8839 8840@smallexample 8841(define_insn_and_split 8842 [@var{insn-pattern}] 8843 "@var{condition}" 8844 "@var{output-template}" 8845 "@var{split-condition}" 8846 [@var{new-insn-pattern-1} 8847 @var{new-insn-pattern-2} 8848 @dots{}] 8849 "@var{preparation-statements}" 8850 [@var{insn-attributes}]) 8851 8852@end smallexample 8853 8854@var{insn-pattern}, @var{condition}, @var{output-template}, and 8855@var{insn-attributes} are used as in @code{define_insn}. The 8856@var{new-insn-pattern} vector and the @var{preparation-statements} are used as 8857in a @code{define_split}. The @var{split-condition} is also used as in 8858@code{define_split}, with the additional behavior that if the condition starts 8859with @samp{&&}, the condition used for the split will be the constructed as a 8860logical ``and'' of the split condition with the insn condition. For example, 8861from i386.md: 8862 8863@smallexample 8864(define_insn_and_split "zero_extendhisi2_and" 8865 [(set (match_operand:SI 0 "register_operand" "=r") 8866 (zero_extend:SI (match_operand:HI 1 "register_operand" "0"))) 8867 (clobber (reg:CC 17))] 8868 "TARGET_ZERO_EXTEND_WITH_AND && !optimize_size" 8869 "#" 8870 "&& reload_completed" 8871 [(parallel [(set (match_dup 0) 8872 (and:SI (match_dup 0) (const_int 65535))) 8873 (clobber (reg:CC 17))])] 8874 "" 8875 [(set_attr "type" "alu1")]) 8876 8877@end smallexample 8878 8879In this case, the actual split condition will be 8880@samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}. 8881 8882The @code{define_insn_and_split} construction provides exactly the same 8883functionality as two separate @code{define_insn} and @code{define_split} 8884patterns. It exists for compactness, and as a maintenance tool to prevent 8885having to ensure the two patterns' templates match. 8886 8887@findex define_insn_and_rewrite 8888It is sometimes useful to have a @code{define_insn_and_split} 8889that replaces specific operands of an instruction but leaves the 8890rest of the instruction pattern unchanged. You can do this directly 8891with a @code{define_insn_and_split}, but it requires a 8892@var{new-insn-pattern-1} that repeats most of the original @var{insn-pattern}. 8893There is also the complication that an implicit @code{parallel} in 8894@var{insn-pattern} must become an explicit @code{parallel} in 8895@var{new-insn-pattern-1}, which is easy to overlook. 8896A simpler alternative is to use @code{define_insn_and_rewrite}, which 8897is a form of @code{define_insn_and_split} that automatically generates 8898@var{new-insn-pattern-1} by replacing each @code{match_operand} 8899in @var{insn-pattern} with a corresponding @code{match_dup}, and each 8900@code{match_operator} in the pattern with a corresponding @code{match_op_dup}. 8901The arguments are otherwise identical to @code{define_insn_and_split}: 8902 8903@smallexample 8904(define_insn_and_rewrite 8905 [@var{insn-pattern}] 8906 "@var{condition}" 8907 "@var{output-template}" 8908 "@var{split-condition}" 8909 "@var{preparation-statements}" 8910 [@var{insn-attributes}]) 8911@end smallexample 8912 8913The @code{match_dup}s and @code{match_op_dup}s in the new 8914instruction pattern use any new operand values that the 8915@var{preparation-statements} store in the @code{operands} array, 8916as for a normal @code{define_insn_and_split}. @var{preparation-statements} 8917can also emit additional instructions before the new instruction. 8918They can even emit an entirely different sequence of instructions and 8919use @code{DONE} to avoid emitting a new form of the original 8920instruction. 8921 8922The split in a @code{define_insn_and_rewrite} is only intended 8923to apply to existing instructions that match @var{insn-pattern}. 8924@var{split-condition} must therefore start with @code{&&}, 8925so that the split condition applies on top of @var{condition}. 8926 8927Here is an example from the AArch64 SVE port, in which operand 1 is 8928known to be equivalent to an all-true constant and isn't used by the 8929output template: 8930 8931@smallexample 8932(define_insn_and_rewrite "*while_ult<GPI:mode><PRED_ALL:mode>_cc" 8933 [(set (reg:CC CC_REGNUM) 8934 (compare:CC 8935 (unspec:SI [(match_operand:PRED_ALL 1) 8936 (unspec:PRED_ALL 8937 [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ") 8938 (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")] 8939 UNSPEC_WHILE_LO)] 8940 UNSPEC_PTEST_PTRUE) 8941 (const_int 0))) 8942 (set (match_operand:PRED_ALL 0 "register_operand" "=Upa") 8943 (unspec:PRED_ALL [(match_dup 2) 8944 (match_dup 3)] 8945 UNSPEC_WHILE_LO))] 8946 "TARGET_SVE" 8947 "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3" 8948 ;; Force the compiler to drop the unused predicate operand, so that we 8949 ;; don't have an unnecessary PTRUE. 8950 "&& !CONSTANT_P (operands[1])" 8951 @{ 8952 operands[1] = CONSTM1_RTX (<MODE>mode); 8953 @} 8954) 8955@end smallexample 8956 8957The splitter in this case simply replaces operand 1 with the constant 8958value that it is known to have. The equivalent @code{define_insn_and_split} 8959would be: 8960 8961@smallexample 8962(define_insn_and_split "*while_ult<GPI:mode><PRED_ALL:mode>_cc" 8963 [(set (reg:CC CC_REGNUM) 8964 (compare:CC 8965 (unspec:SI [(match_operand:PRED_ALL 1) 8966 (unspec:PRED_ALL 8967 [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ") 8968 (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")] 8969 UNSPEC_WHILE_LO)] 8970 UNSPEC_PTEST_PTRUE) 8971 (const_int 0))) 8972 (set (match_operand:PRED_ALL 0 "register_operand" "=Upa") 8973 (unspec:PRED_ALL [(match_dup 2) 8974 (match_dup 3)] 8975 UNSPEC_WHILE_LO))] 8976 "TARGET_SVE" 8977 "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3" 8978 ;; Force the compiler to drop the unused predicate operand, so that we 8979 ;; don't have an unnecessary PTRUE. 8980 "&& !CONSTANT_P (operands[1])" 8981 [(parallel 8982 [(set (reg:CC CC_REGNUM) 8983 (compare:CC 8984 (unspec:SI [(match_dup 1) 8985 (unspec:PRED_ALL [(match_dup 2) 8986 (match_dup 3)] 8987 UNSPEC_WHILE_LO)] 8988 UNSPEC_PTEST_PTRUE) 8989 (const_int 0))) 8990 (set (match_dup 0) 8991 (unspec:PRED_ALL [(match_dup 2) 8992 (match_dup 3)] 8993 UNSPEC_WHILE_LO))])] 8994 @{ 8995 operands[1] = CONSTM1_RTX (<MODE>mode); 8996 @} 8997) 8998@end smallexample 8999 9000@end ifset 9001@ifset INTERNALS 9002@node Including Patterns 9003@section Including Patterns in Machine Descriptions. 9004@cindex insn includes 9005 9006@findex include 9007The @code{include} pattern tells the compiler tools where to 9008look for patterns that are in files other than in the file 9009@file{.md}. This is used only at build time and there is no preprocessing allowed. 9010 9011It looks like: 9012 9013@smallexample 9014 9015(include 9016 @var{pathname}) 9017@end smallexample 9018 9019For example: 9020 9021@smallexample 9022 9023(include "filestuff") 9024 9025@end smallexample 9026 9027Where @var{pathname} is a string that specifies the location of the file, 9028specifies the include file to be in @file{gcc/config/target/filestuff}. The 9029directory @file{gcc/config/target} is regarded as the default directory. 9030 9031 9032Machine descriptions may be split up into smaller more manageable subsections 9033and placed into subdirectories. 9034 9035By specifying: 9036 9037@smallexample 9038 9039(include "BOGUS/filestuff") 9040 9041@end smallexample 9042 9043the include file is specified to be in @file{gcc/config/@var{target}/BOGUS/filestuff}. 9044 9045Specifying an absolute path for the include file such as; 9046@smallexample 9047 9048(include "/u2/BOGUS/filestuff") 9049 9050@end smallexample 9051is permitted but is not encouraged. 9052 9053@subsection RTL Generation Tool Options for Directory Search 9054@cindex directory options .md 9055@cindex options, directory search 9056@cindex search options 9057 9058The @option{-I@var{dir}} option specifies directories to search for machine descriptions. 9059For example: 9060 9061@smallexample 9062 9063genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md 9064 9065@end smallexample 9066 9067 9068Add the directory @var{dir} to the head of the list of directories to be 9069searched for header files. This can be used to override a system machine definition 9070file, substituting your own version, since these directories are 9071searched before the default machine description file directories. If you use more than 9072one @option{-I} option, the directories are scanned in left-to-right 9073order; the standard default directory come after. 9074 9075 9076@end ifset 9077@ifset INTERNALS 9078@node Peephole Definitions 9079@section Machine-Specific Peephole Optimizers 9080@cindex peephole optimizer definitions 9081@cindex defining peephole optimizers 9082 9083In addition to instruction patterns the @file{md} file may contain 9084definitions of machine-specific peephole optimizations. 9085 9086The combiner does not notice certain peephole optimizations when the data 9087flow in the program does not suggest that it should try them. For example, 9088sometimes two consecutive insns related in purpose can be combined even 9089though the second one does not appear to use a register computed in the 9090first one. A machine-specific peephole optimizer can detect such 9091opportunities. 9092 9093There are two forms of peephole definitions that may be used. The 9094original @code{define_peephole} is run at assembly output time to 9095match insns and substitute assembly text. Use of @code{define_peephole} 9096is deprecated. 9097 9098A newer @code{define_peephole2} matches insns and substitutes new 9099insns. The @code{peephole2} pass is run after register allocation 9100but before scheduling, which may result in much better code for 9101targets that do scheduling. 9102 9103@menu 9104* define_peephole:: RTL to Text Peephole Optimizers 9105* define_peephole2:: RTL to RTL Peephole Optimizers 9106@end menu 9107 9108@end ifset 9109@ifset INTERNALS 9110@node define_peephole 9111@subsection RTL to Text Peephole Optimizers 9112@findex define_peephole 9113 9114@need 1000 9115A definition looks like this: 9116 9117@smallexample 9118(define_peephole 9119 [@var{insn-pattern-1} 9120 @var{insn-pattern-2} 9121 @dots{}] 9122 "@var{condition}" 9123 "@var{template}" 9124 "@var{optional-insn-attributes}") 9125@end smallexample 9126 9127@noindent 9128The last string operand may be omitted if you are not using any 9129machine-specific information in this machine description. If present, 9130it must obey the same rules as in a @code{define_insn}. 9131 9132In this skeleton, @var{insn-pattern-1} and so on are patterns to match 9133consecutive insns. The optimization applies to a sequence of insns when 9134@var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches 9135the next, and so on. 9136 9137Each of the insns matched by a peephole must also match a 9138@code{define_insn}. Peepholes are checked only at the last stage just 9139before code generation, and only optionally. Therefore, any insn which 9140would match a peephole but no @code{define_insn} will cause a crash in code 9141generation in an unoptimized compilation, or at various optimization 9142stages. 9143 9144The operands of the insns are matched with @code{match_operands}, 9145@code{match_operator}, and @code{match_dup}, as usual. What is not 9146usual is that the operand numbers apply to all the insn patterns in the 9147definition. So, you can check for identical operands in two insns by 9148using @code{match_operand} in one insn and @code{match_dup} in the 9149other. 9150 9151The operand constraints used in @code{match_operand} patterns do not have 9152any direct effect on the applicability of the peephole, but they will 9153be validated afterward, so make sure your constraints are general enough 9154to apply whenever the peephole matches. If the peephole matches 9155but the constraints are not satisfied, the compiler will crash. 9156 9157It is safe to omit constraints in all the operands of the peephole; or 9158you can write constraints which serve as a double-check on the criteria 9159previously tested. 9160 9161Once a sequence of insns matches the patterns, the @var{condition} is 9162checked. This is a C expression which makes the final decision whether to 9163perform the optimization (we do so if the expression is nonzero). If 9164@var{condition} is omitted (in other words, the string is empty) then the 9165optimization is applied to every sequence of insns that matches the 9166patterns. 9167 9168The defined peephole optimizations are applied after register allocation 9169is complete. Therefore, the peephole definition can check which 9170operands have ended up in which kinds of registers, just by looking at 9171the operands. 9172 9173@findex prev_active_insn 9174The way to refer to the operands in @var{condition} is to write 9175@code{operands[@var{i}]} for operand number @var{i} (as matched by 9176@code{(match_operand @var{i} @dots{})}). Use the variable @code{insn} 9177to refer to the last of the insns being matched; use 9178@code{prev_active_insn} to find the preceding insns. 9179 9180@findex dead_or_set_p 9181When optimizing computations with intermediate results, you can use 9182@var{condition} to match only when the intermediate results are not used 9183elsewhere. Use the C expression @code{dead_or_set_p (@var{insn}, 9184@var{op})}, where @var{insn} is the insn in which you expect the value 9185to be used for the last time (from the value of @code{insn}, together 9186with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate 9187value (from @code{operands[@var{i}]}). 9188 9189Applying the optimization means replacing the sequence of insns with one 9190new insn. The @var{template} controls ultimate output of assembler code 9191for this combined insn. It works exactly like the template of a 9192@code{define_insn}. Operand numbers in this template are the same ones 9193used in matching the original sequence of insns. 9194 9195The result of a defined peephole optimizer does not need to match any of 9196the insn patterns in the machine description; it does not even have an 9197opportunity to match them. The peephole optimizer definition itself serves 9198as the insn pattern to control how the insn is output. 9199 9200Defined peephole optimizers are run as assembler code is being output, 9201so the insns they produce are never combined or rearranged in any way. 9202 9203Here is an example, taken from the 68000 machine description: 9204 9205@smallexample 9206(define_peephole 9207 [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4))) 9208 (set (match_operand:DF 0 "register_operand" "=f") 9209 (match_operand:DF 1 "register_operand" "ad"))] 9210 "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])" 9211@{ 9212 rtx xoperands[2]; 9213 xoperands[1] = gen_rtx_REG (SImode, REGNO (operands[1]) + 1); 9214#ifdef MOTOROLA 9215 output_asm_insn ("move.l %1,(sp)", xoperands); 9216 output_asm_insn ("move.l %1,-(sp)", operands); 9217 return "fmove.d (sp)+,%0"; 9218#else 9219 output_asm_insn ("movel %1,sp@@", xoperands); 9220 output_asm_insn ("movel %1,sp@@-", operands); 9221 return "fmoved sp@@+,%0"; 9222#endif 9223@}) 9224@end smallexample 9225 9226@need 1000 9227The effect of this optimization is to change 9228 9229@smallexample 9230@group 9231jbsr _foobar 9232addql #4,sp 9233movel d1,sp@@- 9234movel d0,sp@@- 9235fmoved sp@@+,fp0 9236@end group 9237@end smallexample 9238 9239@noindent 9240into 9241 9242@smallexample 9243@group 9244jbsr _foobar 9245movel d1,sp@@ 9246movel d0,sp@@- 9247fmoved sp@@+,fp0 9248@end group 9249@end smallexample 9250 9251@ignore 9252@findex CC_REVERSED 9253If a peephole matches a sequence including one or more jump insns, you must 9254take account of the flags such as @code{CC_REVERSED} which specify that the 9255condition codes are represented in an unusual manner. The compiler 9256automatically alters any ordinary conditional jumps which occur in such 9257situations, but the compiler cannot alter jumps which have been replaced by 9258peephole optimizations. So it is up to you to alter the assembler code 9259that the peephole produces. Supply C code to write the assembler output, 9260and in this C code check the condition code status flags and change the 9261assembler code as appropriate. 9262@end ignore 9263 9264@var{insn-pattern-1} and so on look @emph{almost} like the second 9265operand of @code{define_insn}. There is one important difference: the 9266second operand of @code{define_insn} consists of one or more RTX's 9267enclosed in square brackets. Usually, there is only one: then the same 9268action can be written as an element of a @code{define_peephole}. But 9269when there are multiple actions in a @code{define_insn}, they are 9270implicitly enclosed in a @code{parallel}. Then you must explicitly 9271write the @code{parallel}, and the square brackets within it, in the 9272@code{define_peephole}. Thus, if an insn pattern looks like this, 9273 9274@smallexample 9275(define_insn "divmodsi4" 9276 [(set (match_operand:SI 0 "general_operand" "=d") 9277 (div:SI (match_operand:SI 1 "general_operand" "0") 9278 (match_operand:SI 2 "general_operand" "dmsK"))) 9279 (set (match_operand:SI 3 "general_operand" "=d") 9280 (mod:SI (match_dup 1) (match_dup 2)))] 9281 "TARGET_68020" 9282 "divsl%.l %2,%3:%0") 9283@end smallexample 9284 9285@noindent 9286then the way to mention this insn in a peephole is as follows: 9287 9288@smallexample 9289(define_peephole 9290 [@dots{} 9291 (parallel 9292 [(set (match_operand:SI 0 "general_operand" "=d") 9293 (div:SI (match_operand:SI 1 "general_operand" "0") 9294 (match_operand:SI 2 "general_operand" "dmsK"))) 9295 (set (match_operand:SI 3 "general_operand" "=d") 9296 (mod:SI (match_dup 1) (match_dup 2)))]) 9297 @dots{}] 9298 @dots{}) 9299@end smallexample 9300 9301@end ifset 9302@ifset INTERNALS 9303@node define_peephole2 9304@subsection RTL to RTL Peephole Optimizers 9305@findex define_peephole2 9306 9307The @code{define_peephole2} definition tells the compiler how to 9308substitute one sequence of instructions for another sequence, 9309what additional scratch registers may be needed and what their 9310lifetimes must be. 9311 9312@smallexample 9313(define_peephole2 9314 [@var{insn-pattern-1} 9315 @var{insn-pattern-2} 9316 @dots{}] 9317 "@var{condition}" 9318 [@var{new-insn-pattern-1} 9319 @var{new-insn-pattern-2} 9320 @dots{}] 9321 "@var{preparation-statements}") 9322@end smallexample 9323 9324The definition is almost identical to @code{define_split} 9325(@pxref{Insn Splitting}) except that the pattern to match is not a 9326single instruction, but a sequence of instructions. 9327 9328It is possible to request additional scratch registers for use in the 9329output template. If appropriate registers are not free, the pattern 9330will simply not match. 9331 9332@findex match_scratch 9333@findex match_dup 9334Scratch registers are requested with a @code{match_scratch} pattern at 9335the top level of the input pattern. The allocated register (initially) will 9336be dead at the point requested within the original sequence. If the scratch 9337is used at more than a single point, a @code{match_dup} pattern at the 9338top level of the input pattern marks the last position in the input sequence 9339at which the register must be available. 9340 9341Here is an example from the IA-32 machine description: 9342 9343@smallexample 9344(define_peephole2 9345 [(match_scratch:SI 2 "r") 9346 (parallel [(set (match_operand:SI 0 "register_operand" "") 9347 (match_operator:SI 3 "arith_or_logical_operator" 9348 [(match_dup 0) 9349 (match_operand:SI 1 "memory_operand" "")])) 9350 (clobber (reg:CC 17))])] 9351 "! optimize_size && ! TARGET_READ_MODIFY" 9352 [(set (match_dup 2) (match_dup 1)) 9353 (parallel [(set (match_dup 0) 9354 (match_op_dup 3 [(match_dup 0) (match_dup 2)])) 9355 (clobber (reg:CC 17))])] 9356 "") 9357@end smallexample 9358 9359@noindent 9360This pattern tries to split a load from its use in the hopes that we'll be 9361able to schedule around the memory load latency. It allocates a single 9362@code{SImode} register of class @code{GENERAL_REGS} (@code{"r"}) that needs 9363to be live only at the point just before the arithmetic. 9364 9365A real example requiring extended scratch lifetimes is harder to come by, 9366so here's a silly made-up example: 9367 9368@smallexample 9369(define_peephole2 9370 [(match_scratch:SI 4 "r") 9371 (set (match_operand:SI 0 "" "") (match_operand:SI 1 "" "")) 9372 (set (match_operand:SI 2 "" "") (match_dup 1)) 9373 (match_dup 4) 9374 (set (match_operand:SI 3 "" "") (match_dup 1))] 9375 "/* @r{determine 1 does not overlap 0 and 2} */" 9376 [(set (match_dup 4) (match_dup 1)) 9377 (set (match_dup 0) (match_dup 4)) 9378 (set (match_dup 2) (match_dup 4)) 9379 (set (match_dup 3) (match_dup 4))] 9380 "") 9381@end smallexample 9382 9383There are two special macros defined for use in the preparation statements: 9384@code{DONE} and @code{FAIL}. Use them with a following semicolon, 9385as a statement. 9386 9387@table @code 9388 9389@findex DONE 9390@item DONE 9391Use the @code{DONE} macro to end RTL generation for the peephole. The 9392only RTL insns generated as replacement for the matched input insn will 9393be those already emitted by explicit calls to @code{emit_insn} within 9394the preparation statements; the replacement pattern is not used. 9395 9396@findex FAIL 9397@item FAIL 9398Make the @code{define_peephole2} fail on this occasion. When a @code{define_peephole2} 9399fails, it means that the replacement was not truly available for the 9400particular inputs it was given. In that case, GCC may still apply a 9401later @code{define_peephole2} that also matches the given insn pattern. 9402(Note that this is different from @code{define_split}, where @code{FAIL} 9403prevents the input insn from being split at all.) 9404@end table 9405 9406If the preparation falls through (invokes neither @code{DONE} nor 9407@code{FAIL}), then the @code{define_peephole2} uses the replacement 9408template. 9409 9410@noindent 9411If we had not added the @code{(match_dup 4)} in the middle of the input 9412sequence, it might have been the case that the register we chose at the 9413beginning of the sequence is killed by the first or second @code{set}. 9414 9415@end ifset 9416@ifset INTERNALS 9417@node Insn Attributes 9418@section Instruction Attributes 9419@cindex insn attributes 9420@cindex instruction attributes 9421 9422In addition to describing the instruction supported by the target machine, 9423the @file{md} file also defines a group of @dfn{attributes} and a set of 9424values for each. Every generated insn is assigned a value for each attribute. 9425One possible attribute would be the effect that the insn has on the machine's 9426condition code. 9427 9428@menu 9429* Defining Attributes:: Specifying attributes and their values. 9430* Expressions:: Valid expressions for attribute values. 9431* Tagging Insns:: Assigning attribute values to insns. 9432* Attr Example:: An example of assigning attributes. 9433* Insn Lengths:: Computing the length of insns. 9434* Constant Attributes:: Defining attributes that are constant. 9435* Mnemonic Attribute:: Obtain the instruction mnemonic as attribute value. 9436* Delay Slots:: Defining delay slots required for a machine. 9437* Processor pipeline description:: Specifying information for insn scheduling. 9438@end menu 9439 9440@end ifset 9441@ifset INTERNALS 9442@node Defining Attributes 9443@subsection Defining Attributes and their Values 9444@cindex defining attributes and their values 9445@cindex attributes, defining 9446 9447@findex define_attr 9448The @code{define_attr} expression is used to define each attribute required 9449by the target machine. It looks like: 9450 9451@smallexample 9452(define_attr @var{name} @var{list-of-values} @var{default}) 9453@end smallexample 9454 9455@var{name} is a string specifying the name of the attribute being 9456defined. Some attributes are used in a special way by the rest of the 9457compiler. The @code{enabled} attribute can be used to conditionally 9458enable or disable insn alternatives (@pxref{Disable Insn 9459Alternatives}). The @code{predicable} attribute, together with a 9460suitable @code{define_cond_exec} (@pxref{Conditional Execution}), can 9461be used to automatically generate conditional variants of instruction 9462patterns. The @code{mnemonic} attribute can be used to check for the 9463instruction mnemonic (@pxref{Mnemonic Attribute}). The compiler 9464internally uses the names @code{ce_enabled} and @code{nonce_enabled}, 9465so they should not be used elsewhere as alternative names. 9466 9467@var{list-of-values} is either a string that specifies a comma-separated 9468list of values that can be assigned to the attribute, or a null string to 9469indicate that the attribute takes numeric values. 9470 9471@var{default} is an attribute expression that gives the value of this 9472attribute for insns that match patterns whose definition does not include 9473an explicit value for this attribute. @xref{Attr Example}, for more 9474information on the handling of defaults. @xref{Constant Attributes}, 9475for information on attributes that do not depend on any particular insn. 9476 9477@findex insn-attr.h 9478For each defined attribute, a number of definitions are written to the 9479@file{insn-attr.h} file. For cases where an explicit set of values is 9480specified for an attribute, the following are defined: 9481 9482@itemize @bullet 9483@item 9484A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}. 9485 9486@item 9487An enumerated class is defined for @samp{attr_@var{name}} with 9488elements of the form @samp{@var{upper-name}_@var{upper-value}} where 9489the attribute name and value are first converted to uppercase. 9490 9491@item 9492A function @samp{get_attr_@var{name}} is defined that is passed an insn and 9493returns the attribute value for that insn. 9494@end itemize 9495 9496For example, if the following is present in the @file{md} file: 9497 9498@smallexample 9499(define_attr "type" "branch,fp,load,store,arith" @dots{}) 9500@end smallexample 9501 9502@noindent 9503the following lines will be written to the file @file{insn-attr.h}. 9504 9505@smallexample 9506#define HAVE_ATTR_type 1 9507enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD, 9508 TYPE_STORE, TYPE_ARITH@}; 9509extern enum attr_type get_attr_type (); 9510@end smallexample 9511 9512If the attribute takes numeric values, no @code{enum} type will be 9513defined and the function to obtain the attribute's value will return 9514@code{int}. 9515 9516There are attributes which are tied to a specific meaning. These 9517attributes are not free to use for other purposes: 9518 9519@table @code 9520@item length 9521The @code{length} attribute is used to calculate the length of emitted 9522code chunks. This is especially important when verifying branch 9523distances. @xref{Insn Lengths}. 9524 9525@item enabled 9526The @code{enabled} attribute can be defined to prevent certain 9527alternatives of an insn definition from being used during code 9528generation. @xref{Disable Insn Alternatives}. 9529 9530@item mnemonic 9531The @code{mnemonic} attribute can be defined to implement instruction 9532specific checks in e.g.@: the pipeline description. 9533@xref{Mnemonic Attribute}. 9534@end table 9535 9536For each of these special attributes, the corresponding 9537@samp{HAVE_ATTR_@var{name}} @samp{#define} is also written when the 9538attribute is not defined; in that case, it is defined as @samp{0}. 9539 9540@findex define_enum_attr 9541@anchor{define_enum_attr} 9542Another way of defining an attribute is to use: 9543 9544@smallexample 9545(define_enum_attr "@var{attr}" "@var{enum}" @var{default}) 9546@end smallexample 9547 9548This works in just the same way as @code{define_attr}, except that 9549the list of values is taken from a separate enumeration called 9550@var{enum} (@pxref{define_enum}). This form allows you to use 9551the same list of values for several attributes without having to 9552repeat the list each time. For example: 9553 9554@smallexample 9555(define_enum "processor" [ 9556 model_a 9557 model_b 9558 @dots{} 9559]) 9560(define_enum_attr "arch" "processor" 9561 (const (symbol_ref "target_arch"))) 9562(define_enum_attr "tune" "processor" 9563 (const (symbol_ref "target_tune"))) 9564@end smallexample 9565 9566defines the same attributes as: 9567 9568@smallexample 9569(define_attr "arch" "model_a,model_b,@dots{}" 9570 (const (symbol_ref "target_arch"))) 9571(define_attr "tune" "model_a,model_b,@dots{}" 9572 (const (symbol_ref "target_tune"))) 9573@end smallexample 9574 9575but without duplicating the processor list. The second example defines two 9576separate C enums (@code{attr_arch} and @code{attr_tune}) whereas the first 9577defines a single C enum (@code{processor}). 9578@end ifset 9579@ifset INTERNALS 9580@node Expressions 9581@subsection Attribute Expressions 9582@cindex attribute expressions 9583 9584RTL expressions used to define attributes use the codes described above 9585plus a few specific to attribute definitions, to be discussed below. 9586Attribute value expressions must have one of the following forms: 9587 9588@table @code 9589@cindex @code{const_int} and attributes 9590@item (const_int @var{i}) 9591The integer @var{i} specifies the value of a numeric attribute. @var{i} 9592must be non-negative. 9593 9594The value of a numeric attribute can be specified either with a 9595@code{const_int}, or as an integer represented as a string in 9596@code{const_string}, @code{eq_attr} (see below), @code{attr}, 9597@code{symbol_ref}, simple arithmetic expressions, and @code{set_attr} 9598overrides on specific instructions (@pxref{Tagging Insns}). 9599 9600@cindex @code{const_string} and attributes 9601@item (const_string @var{value}) 9602The string @var{value} specifies a constant attribute value. 9603If @var{value} is specified as @samp{"*"}, it means that the default value of 9604the attribute is to be used for the insn containing this expression. 9605@samp{"*"} obviously cannot be used in the @var{default} expression 9606of a @code{define_attr}. 9607 9608If the attribute whose value is being specified is numeric, @var{value} 9609must be a string containing a non-negative integer (normally 9610@code{const_int} would be used in this case). Otherwise, it must 9611contain one of the valid values for the attribute. 9612 9613@cindex @code{if_then_else} and attributes 9614@item (if_then_else @var{test} @var{true-value} @var{false-value}) 9615@var{test} specifies an attribute test, whose format is defined below. 9616The value of this expression is @var{true-value} if @var{test} is true, 9617otherwise it is @var{false-value}. 9618 9619@cindex @code{cond} and attributes 9620@item (cond [@var{test1} @var{value1} @dots{}] @var{default}) 9621The first operand of this expression is a vector containing an even 9622number of expressions and consisting of pairs of @var{test} and @var{value} 9623expressions. The value of the @code{cond} expression is that of the 9624@var{value} corresponding to the first true @var{test} expression. If 9625none of the @var{test} expressions are true, the value of the @code{cond} 9626expression is that of the @var{default} expression. 9627@end table 9628 9629@var{test} expressions can have one of the following forms: 9630 9631@table @code 9632@cindex @code{const_int} and attribute tests 9633@item (const_int @var{i}) 9634This test is true if @var{i} is nonzero and false otherwise. 9635 9636@cindex @code{not} and attributes 9637@cindex @code{ior} and attributes 9638@cindex @code{and} and attributes 9639@item (not @var{test}) 9640@itemx (ior @var{test1} @var{test2}) 9641@itemx (and @var{test1} @var{test2}) 9642These tests are true if the indicated logical function is true. 9643 9644@cindex @code{match_operand} and attributes 9645@item (match_operand:@var{m} @var{n} @var{pred} @var{constraints}) 9646This test is true if operand @var{n} of the insn whose attribute value 9647is being determined has mode @var{m} (this part of the test is ignored 9648if @var{m} is @code{VOIDmode}) and the function specified by the string 9649@var{pred} returns a nonzero value when passed operand @var{n} and mode 9650@var{m} (this part of the test is ignored if @var{pred} is the null 9651string). 9652 9653The @var{constraints} operand is ignored and should be the null string. 9654 9655@cindex @code{match_test} and attributes 9656@item (match_test @var{c-expr}) 9657The test is true if C expression @var{c-expr} is true. In non-constant 9658attributes, @var{c-expr} has access to the following variables: 9659 9660@table @var 9661@item insn 9662The rtl instruction under test. 9663@item which_alternative 9664The @code{define_insn} alternative that @var{insn} matches. 9665@xref{Output Statement}. 9666@item operands 9667An array of @var{insn}'s rtl operands. 9668@end table 9669 9670@var{c-expr} behaves like the condition in a C @code{if} statement, 9671so there is no need to explicitly convert the expression into a boolean 96720 or 1 value. For example, the following two tests are equivalent: 9673 9674@smallexample 9675(match_test "x & 2") 9676(match_test "(x & 2) != 0") 9677@end smallexample 9678 9679@cindex @code{le} and attributes 9680@cindex @code{leu} and attributes 9681@cindex @code{lt} and attributes 9682@cindex @code{gt} and attributes 9683@cindex @code{gtu} and attributes 9684@cindex @code{ge} and attributes 9685@cindex @code{geu} and attributes 9686@cindex @code{ne} and attributes 9687@cindex @code{eq} and attributes 9688@cindex @code{plus} and attributes 9689@cindex @code{minus} and attributes 9690@cindex @code{mult} and attributes 9691@cindex @code{div} and attributes 9692@cindex @code{mod} and attributes 9693@cindex @code{abs} and attributes 9694@cindex @code{neg} and attributes 9695@cindex @code{ashift} and attributes 9696@cindex @code{lshiftrt} and attributes 9697@cindex @code{ashiftrt} and attributes 9698@item (le @var{arith1} @var{arith2}) 9699@itemx (leu @var{arith1} @var{arith2}) 9700@itemx (lt @var{arith1} @var{arith2}) 9701@itemx (ltu @var{arith1} @var{arith2}) 9702@itemx (gt @var{arith1} @var{arith2}) 9703@itemx (gtu @var{arith1} @var{arith2}) 9704@itemx (ge @var{arith1} @var{arith2}) 9705@itemx (geu @var{arith1} @var{arith2}) 9706@itemx (ne @var{arith1} @var{arith2}) 9707@itemx (eq @var{arith1} @var{arith2}) 9708These tests are true if the indicated comparison of the two arithmetic 9709expressions is true. Arithmetic expressions are formed with 9710@code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod}, 9711@code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not}, 9712@code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions. 9713 9714@findex get_attr 9715@code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn 9716Lengths},for additional forms). @code{symbol_ref} is a string 9717denoting a C expression that yields an @code{int} when evaluated by the 9718@samp{get_attr_@dots{}} routine. It should normally be a global 9719variable. 9720 9721@findex eq_attr 9722@item (eq_attr @var{name} @var{value}) 9723@var{name} is a string specifying the name of an attribute. 9724 9725@var{value} is a string that is either a valid value for attribute 9726@var{name}, a comma-separated list of values, or @samp{!} followed by a 9727value or list. If @var{value} does not begin with a @samp{!}, this 9728test is true if the value of the @var{name} attribute of the current 9729insn is in the list specified by @var{value}. If @var{value} begins 9730with a @samp{!}, this test is true if the attribute's value is 9731@emph{not} in the specified list. 9732 9733For example, 9734 9735@smallexample 9736(eq_attr "type" "load,store") 9737@end smallexample 9738 9739@noindent 9740is equivalent to 9741 9742@smallexample 9743(ior (eq_attr "type" "load") (eq_attr "type" "store")) 9744@end smallexample 9745 9746If @var{name} specifies an attribute of @samp{alternative}, it refers to the 9747value of the compiler variable @code{which_alternative} 9748(@pxref{Output Statement}) and the values must be small integers. For 9749example, 9750 9751@smallexample 9752(eq_attr "alternative" "2,3") 9753@end smallexample 9754 9755@noindent 9756is equivalent to 9757 9758@smallexample 9759(ior (eq (symbol_ref "which_alternative") (const_int 2)) 9760 (eq (symbol_ref "which_alternative") (const_int 3))) 9761@end smallexample 9762 9763Note that, for most attributes, an @code{eq_attr} test is simplified in cases 9764where the value of the attribute being tested is known for all insns matching 9765a particular pattern. This is by far the most common case. 9766 9767@findex attr_flag 9768@item (attr_flag @var{name}) 9769The value of an @code{attr_flag} expression is true if the flag 9770specified by @var{name} is true for the @code{insn} currently being 9771scheduled. 9772 9773@var{name} is a string specifying one of a fixed set of flags to test. 9774Test the flags @code{forward} and @code{backward} to determine the 9775direction of a conditional branch. 9776 9777This example describes a conditional branch delay slot which 9778can be nullified for forward branches that are taken (annul-true) or 9779for backward branches which are not taken (annul-false). 9780 9781@smallexample 9782(define_delay (eq_attr "type" "cbranch") 9783 [(eq_attr "in_branch_delay" "true") 9784 (and (eq_attr "in_branch_delay" "true") 9785 (attr_flag "forward")) 9786 (and (eq_attr "in_branch_delay" "true") 9787 (attr_flag "backward"))]) 9788@end smallexample 9789 9790The @code{forward} and @code{backward} flags are false if the current 9791@code{insn} being scheduled is not a conditional branch. 9792 9793@code{attr_flag} is only used during delay slot scheduling and has no 9794meaning to other passes of the compiler. 9795 9796@findex attr 9797@item (attr @var{name}) 9798The value of another attribute is returned. This is most useful 9799for numeric attributes, as @code{eq_attr} and @code{attr_flag} 9800produce more efficient code for non-numeric attributes. 9801@end table 9802 9803@end ifset 9804@ifset INTERNALS 9805@node Tagging Insns 9806@subsection Assigning Attribute Values to Insns 9807@cindex tagging insns 9808@cindex assigning attribute values to insns 9809 9810The value assigned to an attribute of an insn is primarily determined by 9811which pattern is matched by that insn (or which @code{define_peephole} 9812generated it). Every @code{define_insn} and @code{define_peephole} can 9813have an optional last argument to specify the values of attributes for 9814matching insns. The value of any attribute not specified in a particular 9815insn is set to the default value for that attribute, as specified in its 9816@code{define_attr}. Extensive use of default values for attributes 9817permits the specification of the values for only one or two attributes 9818in the definition of most insn patterns, as seen in the example in the 9819next section. 9820 9821The optional last argument of @code{define_insn} and 9822@code{define_peephole} is a vector of expressions, each of which defines 9823the value for a single attribute. The most general way of assigning an 9824attribute's value is to use a @code{set} expression whose first operand is an 9825@code{attr} expression giving the name of the attribute being set. The 9826second operand of the @code{set} is an attribute expression 9827(@pxref{Expressions}) giving the value of the attribute. 9828 9829When the attribute value depends on the @samp{alternative} attribute 9830(i.e., which is the applicable alternative in the constraint of the 9831insn), the @code{set_attr_alternative} expression can be used. It 9832allows the specification of a vector of attribute expressions, one for 9833each alternative. 9834 9835@findex set_attr 9836When the generality of arbitrary attribute expressions is not required, 9837the simpler @code{set_attr} expression can be used, which allows 9838specifying a string giving either a single attribute value or a list 9839of attribute values, one for each alternative. 9840 9841The form of each of the above specifications is shown below. In each case, 9842@var{name} is a string specifying the attribute to be set. 9843 9844@table @code 9845@item (set_attr @var{name} @var{value-string}) 9846@var{value-string} is either a string giving the desired attribute value, 9847or a string containing a comma-separated list giving the values for 9848succeeding alternatives. The number of elements must match the number 9849of alternatives in the constraint of the insn pattern. 9850 9851Note that it may be useful to specify @samp{*} for some alternative, in 9852which case the attribute will assume its default value for insns matching 9853that alternative. 9854 9855@findex set_attr_alternative 9856@item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}]) 9857Depending on the alternative of the insn, the value will be one of the 9858specified values. This is a shorthand for using a @code{cond} with 9859tests on the @samp{alternative} attribute. 9860 9861@findex attr 9862@item (set (attr @var{name}) @var{value}) 9863The first operand of this @code{set} must be the special RTL expression 9864@code{attr}, whose sole operand is a string giving the name of the 9865attribute being set. @var{value} is the value of the attribute. 9866@end table 9867 9868The following shows three different ways of representing the same 9869attribute value specification: 9870 9871@smallexample 9872(set_attr "type" "load,store,arith") 9873 9874(set_attr_alternative "type" 9875 [(const_string "load") (const_string "store") 9876 (const_string "arith")]) 9877 9878(set (attr "type") 9879 (cond [(eq_attr "alternative" "1") (const_string "load") 9880 (eq_attr "alternative" "2") (const_string "store")] 9881 (const_string "arith"))) 9882@end smallexample 9883 9884@need 1000 9885@findex define_asm_attributes 9886The @code{define_asm_attributes} expression provides a mechanism to 9887specify the attributes assigned to insns produced from an @code{asm} 9888statement. It has the form: 9889 9890@smallexample 9891(define_asm_attributes [@var{attr-sets}]) 9892@end smallexample 9893 9894@noindent 9895where @var{attr-sets} is specified the same as for both the 9896@code{define_insn} and the @code{define_peephole} expressions. 9897 9898These values will typically be the ``worst case'' attribute values. For 9899example, they might indicate that the condition code will be clobbered. 9900 9901A specification for a @code{length} attribute is handled specially. The 9902way to compute the length of an @code{asm} insn is to multiply the 9903length specified in the expression @code{define_asm_attributes} by the 9904number of machine instructions specified in the @code{asm} statement, 9905determined by counting the number of semicolons and newlines in the 9906string. Therefore, the value of the @code{length} attribute specified 9907in a @code{define_asm_attributes} should be the maximum possible length 9908of a single machine instruction. 9909 9910@end ifset 9911@ifset INTERNALS 9912@node Attr Example 9913@subsection Example of Attribute Specifications 9914@cindex attribute specifications example 9915@cindex attribute specifications 9916 9917The judicious use of defaulting is important in the efficient use of 9918insn attributes. Typically, insns are divided into @dfn{types} and an 9919attribute, customarily called @code{type}, is used to represent this 9920value. This attribute is normally used only to define the default value 9921for other attributes. An example will clarify this usage. 9922 9923Assume we have a RISC machine with a condition code and in which only 9924full-word operations are performed in registers. Let us assume that we 9925can divide all insns into loads, stores, (integer) arithmetic 9926operations, floating point operations, and branches. 9927 9928Here we will concern ourselves with determining the effect of an insn on 9929the condition code and will limit ourselves to the following possible 9930effects: The condition code can be set unpredictably (clobbered), not 9931be changed, be set to agree with the results of the operation, or only 9932changed if the item previously set into the condition code has been 9933modified. 9934 9935Here is part of a sample @file{md} file for such a machine: 9936 9937@smallexample 9938(define_attr "type" "load,store,arith,fp,branch" (const_string "arith")) 9939 9940(define_attr "cc" "clobber,unchanged,set,change0" 9941 (cond [(eq_attr "type" "load") 9942 (const_string "change0") 9943 (eq_attr "type" "store,branch") 9944 (const_string "unchanged") 9945 (eq_attr "type" "arith") 9946 (if_then_else (match_operand:SI 0 "" "") 9947 (const_string "set") 9948 (const_string "clobber"))] 9949 (const_string "clobber"))) 9950 9951(define_insn "" 9952 [(set (match_operand:SI 0 "general_operand" "=r,r,m") 9953 (match_operand:SI 1 "general_operand" "r,m,r"))] 9954 "" 9955 "@@ 9956 move %0,%1 9957 load %0,%1 9958 store %0,%1" 9959 [(set_attr "type" "arith,load,store")]) 9960@end smallexample 9961 9962Note that we assume in the above example that arithmetic operations 9963performed on quantities smaller than a machine word clobber the condition 9964code since they will set the condition code to a value corresponding to the 9965full-word result. 9966 9967@end ifset 9968@ifset INTERNALS 9969@node Insn Lengths 9970@subsection Computing the Length of an Insn 9971@cindex insn lengths, computing 9972@cindex computing the length of an insn 9973 9974For many machines, multiple types of branch instructions are provided, each 9975for different length branch displacements. In most cases, the assembler 9976will choose the correct instruction to use. However, when the assembler 9977cannot do so, GCC can when a special attribute, the @code{length} 9978attribute, is defined. This attribute must be defined to have numeric 9979values by specifying a null string in its @code{define_attr}. 9980 9981In the case of the @code{length} attribute, two additional forms of 9982arithmetic terms are allowed in test expressions: 9983 9984@table @code 9985@cindex @code{match_dup} and attributes 9986@item (match_dup @var{n}) 9987This refers to the address of operand @var{n} of the current insn, which 9988must be a @code{label_ref}. 9989 9990@cindex @code{pc} and attributes 9991@item (pc) 9992For non-branch instructions and backward branch instructions, this refers 9993to the address of the current insn. But for forward branch instructions, 9994this refers to the address of the next insn, because the length of the 9995current insn is to be computed. 9996@end table 9997 9998@cindex @code{addr_vec}, length of 9999@cindex @code{addr_diff_vec}, length of 10000For normal insns, the length will be determined by value of the 10001@code{length} attribute. In the case of @code{addr_vec} and 10002@code{addr_diff_vec} insn patterns, the length is computed as 10003the number of vectors multiplied by the size of each vector. 10004 10005Lengths are measured in addressable storage units (bytes). 10006 10007Note that it is possible to call functions via the @code{symbol_ref} 10008mechanism to compute the length of an insn. However, if you use this 10009mechanism you must provide dummy clauses to express the maximum length 10010without using the function call. You can see an example of this in the 10011@code{pa} machine description for the @code{call_symref} pattern. 10012 10013The following macros can be used to refine the length computation: 10014 10015@table @code 10016@findex ADJUST_INSN_LENGTH 10017@item ADJUST_INSN_LENGTH (@var{insn}, @var{length}) 10018If defined, modifies the length assigned to instruction @var{insn} as a 10019function of the context in which it is used. @var{length} is an lvalue 10020that contains the initially computed length of the insn and should be 10021updated with the correct length of the insn. 10022 10023This macro will normally not be required. A case in which it is 10024required is the ROMP@. On this machine, the size of an @code{addr_vec} 10025insn must be increased by two to compensate for the fact that alignment 10026may be required. 10027@end table 10028 10029@findex get_attr_length 10030The routine that returns @code{get_attr_length} (the value of the 10031@code{length} attribute) can be used by the output routine to 10032determine the form of the branch instruction to be written, as the 10033example below illustrates. 10034 10035As an example of the specification of variable-length branches, consider 10036the IBM 360. If we adopt the convention that a register will be set to 10037the starting address of a function, we can jump to labels within 4k of 10038the start using a four-byte instruction. Otherwise, we need a six-byte 10039sequence to load the address from memory and then branch to it. 10040 10041On such a machine, a pattern for a branch instruction might be specified 10042as follows: 10043 10044@smallexample 10045(define_insn "jump" 10046 [(set (pc) 10047 (label_ref (match_operand 0 "" "")))] 10048 "" 10049@{ 10050 return (get_attr_length (insn) == 4 10051 ? "b %l0" : "l r15,=a(%l0); br r15"); 10052@} 10053 [(set (attr "length") 10054 (if_then_else (lt (match_dup 0) (const_int 4096)) 10055 (const_int 4) 10056 (const_int 6)))]) 10057@end smallexample 10058 10059@end ifset 10060@ifset INTERNALS 10061@node Constant Attributes 10062@subsection Constant Attributes 10063@cindex constant attributes 10064 10065A special form of @code{define_attr}, where the expression for the 10066default value is a @code{const} expression, indicates an attribute that 10067is constant for a given run of the compiler. Constant attributes may be 10068used to specify which variety of processor is used. For example, 10069 10070@smallexample 10071(define_attr "cpu" "m88100,m88110,m88000" 10072 (const 10073 (cond [(symbol_ref "TARGET_88100") (const_string "m88100") 10074 (symbol_ref "TARGET_88110") (const_string "m88110")] 10075 (const_string "m88000")))) 10076 10077(define_attr "memory" "fast,slow" 10078 (const 10079 (if_then_else (symbol_ref "TARGET_FAST_MEM") 10080 (const_string "fast") 10081 (const_string "slow")))) 10082@end smallexample 10083 10084The routine generated for constant attributes has no parameters as it 10085does not depend on any particular insn. RTL expressions used to define 10086the value of a constant attribute may use the @code{symbol_ref} form, 10087but may not use either the @code{match_operand} form or @code{eq_attr} 10088forms involving insn attributes. 10089 10090@end ifset 10091@ifset INTERNALS 10092@node Mnemonic Attribute 10093@subsection Mnemonic Attribute 10094@cindex mnemonic attribute 10095 10096The @code{mnemonic} attribute is a string type attribute holding the 10097instruction mnemonic for an insn alternative. The attribute values 10098will automatically be generated by the machine description parser if 10099there is an attribute definition in the md file: 10100 10101@smallexample 10102(define_attr "mnemonic" "unknown" (const_string "unknown")) 10103@end smallexample 10104 10105The default value can be freely chosen as long as it does not collide 10106with any of the instruction mnemonics. This value will be used 10107whenever the machine description parser is not able to determine the 10108mnemonic string. This might be the case for output templates 10109containing more than a single instruction as in 10110@code{"mvcle\t%0,%1,0\;jo\t.-4"}. 10111 10112The @code{mnemonic} attribute set is not generated automatically if the 10113instruction string is generated via C code. 10114 10115An existing @code{mnemonic} attribute set in an insn definition will not 10116be overriden by the md file parser. That way it is possible to 10117manually set the instruction mnemonics for the cases where the md file 10118parser fails to determine it automatically. 10119 10120The @code{mnemonic} attribute is useful for dealing with instruction 10121specific properties in the pipeline description without defining 10122additional insn attributes. 10123 10124@smallexample 10125(define_attr "ooo_expanded" "" 10126 (cond [(eq_attr "mnemonic" "dlr,dsgr,d,dsgf,stam,dsgfr,dlgr") 10127 (const_int 1)] 10128 (const_int 0))) 10129@end smallexample 10130 10131@end ifset 10132@ifset INTERNALS 10133@node Delay Slots 10134@subsection Delay Slot Scheduling 10135@cindex delay slots, defining 10136 10137The insn attribute mechanism can be used to specify the requirements for 10138delay slots, if any, on a target machine. An instruction is said to 10139require a @dfn{delay slot} if some instructions that are physically 10140after the instruction are executed as if they were located before it. 10141Classic examples are branch and call instructions, which often execute 10142the following instruction before the branch or call is performed. 10143 10144On some machines, conditional branch instructions can optionally 10145@dfn{annul} instructions in the delay slot. This means that the 10146instruction will not be executed for certain branch outcomes. Both 10147instructions that annul if the branch is true and instructions that 10148annul if the branch is false are supported. 10149 10150Delay slot scheduling differs from instruction scheduling in that 10151determining whether an instruction needs a delay slot is dependent only 10152on the type of instruction being generated, not on data flow between the 10153instructions. See the next section for a discussion of data-dependent 10154instruction scheduling. 10155 10156@findex define_delay 10157The requirement of an insn needing one or more delay slots is indicated 10158via the @code{define_delay} expression. It has the following form: 10159 10160@smallexample 10161(define_delay @var{test} 10162 [@var{delay-1} @var{annul-true-1} @var{annul-false-1} 10163 @var{delay-2} @var{annul-true-2} @var{annul-false-2} 10164 @dots{}]) 10165@end smallexample 10166 10167@var{test} is an attribute test that indicates whether this 10168@code{define_delay} applies to a particular insn. If so, the number of 10169required delay slots is determined by the length of the vector specified 10170as the second argument. An insn placed in delay slot @var{n} must 10171satisfy attribute test @var{delay-n}. @var{annul-true-n} is an 10172attribute test that specifies which insns may be annulled if the branch 10173is true. Similarly, @var{annul-false-n} specifies which insns in the 10174delay slot may be annulled if the branch is false. If annulling is not 10175supported for that delay slot, @code{(nil)} should be coded. 10176 10177For example, in the common case where branch and call insns require 10178a single delay slot, which may contain any insn other than a branch or 10179call, the following would be placed in the @file{md} file: 10180 10181@smallexample 10182(define_delay (eq_attr "type" "branch,call") 10183 [(eq_attr "type" "!branch,call") (nil) (nil)]) 10184@end smallexample 10185 10186Multiple @code{define_delay} expressions may be specified. In this 10187case, each such expression specifies different delay slot requirements 10188and there must be no insn for which tests in two @code{define_delay} 10189expressions are both true. 10190 10191For example, if we have a machine that requires one delay slot for branches 10192but two for calls, no delay slot can contain a branch or call insn, 10193and any valid insn in the delay slot for the branch can be annulled if the 10194branch is true, we might represent this as follows: 10195 10196@smallexample 10197(define_delay (eq_attr "type" "branch") 10198 [(eq_attr "type" "!branch,call") 10199 (eq_attr "type" "!branch,call") 10200 (nil)]) 10201 10202(define_delay (eq_attr "type" "call") 10203 [(eq_attr "type" "!branch,call") (nil) (nil) 10204 (eq_attr "type" "!branch,call") (nil) (nil)]) 10205@end smallexample 10206@c the above is *still* too long. --mew 4feb93 10207 10208@end ifset 10209@ifset INTERNALS 10210@node Processor pipeline description 10211@subsection Specifying processor pipeline description 10212@cindex processor pipeline description 10213@cindex processor functional units 10214@cindex instruction latency time 10215@cindex interlock delays 10216@cindex data dependence delays 10217@cindex reservation delays 10218@cindex pipeline hazard recognizer 10219@cindex automaton based pipeline description 10220@cindex regular expressions 10221@cindex deterministic finite state automaton 10222@cindex automaton based scheduler 10223@cindex RISC 10224@cindex VLIW 10225 10226To achieve better performance, most modern processors 10227(super-pipelined, superscalar @acronym{RISC}, and @acronym{VLIW} 10228processors) have many @dfn{functional units} on which several 10229instructions can be executed simultaneously. An instruction starts 10230execution if its issue conditions are satisfied. If not, the 10231instruction is stalled until its conditions are satisfied. Such 10232@dfn{interlock (pipeline) delay} causes interruption of the fetching 10233of successor instructions (or demands nop instructions, e.g.@: for some 10234MIPS processors). 10235 10236There are two major kinds of interlock delays in modern processors. 10237The first one is a data dependence delay determining @dfn{instruction 10238latency time}. The instruction execution is not started until all 10239source data have been evaluated by prior instructions (there are more 10240complex cases when the instruction execution starts even when the data 10241are not available but will be ready in given time after the 10242instruction execution start). Taking the data dependence delays into 10243account is simple. The data dependence (true, output, and 10244anti-dependence) delay between two instructions is given by a 10245constant. In most cases this approach is adequate. The second kind 10246of interlock delays is a reservation delay. The reservation delay 10247means that two instructions under execution will be in need of shared 10248processors resources, i.e.@: buses, internal registers, and/or 10249functional units, which are reserved for some time. Taking this kind 10250of delay into account is complex especially for modern @acronym{RISC} 10251processors. 10252 10253The task of exploiting more processor parallelism is solved by an 10254instruction scheduler. For a better solution to this problem, the 10255instruction scheduler has to have an adequate description of the 10256processor parallelism (or @dfn{pipeline description}). GCC 10257machine descriptions describe processor parallelism and functional 10258unit reservations for groups of instructions with the aid of 10259@dfn{regular expressions}. 10260 10261The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to 10262figure out the possibility of the instruction issue by the processor 10263on a given simulated processor cycle. The pipeline hazard recognizer is 10264automatically generated from the processor pipeline description. The 10265pipeline hazard recognizer generated from the machine description 10266is based on a deterministic finite state automaton (@acronym{DFA}): 10267the instruction issue is possible if there is a transition from one 10268automaton state to another one. This algorithm is very fast, and 10269furthermore, its speed is not dependent on processor 10270complexity@footnote{However, the size of the automaton depends on 10271processor complexity. To limit this effect, machine descriptions 10272can split orthogonal parts of the machine description among several 10273automata: but then, since each of these must be stepped independently, 10274this does cause a small decrease in the algorithm's performance.}. 10275 10276@cindex automaton based pipeline description 10277The rest of this section describes the directives that constitute 10278an automaton-based processor pipeline description. The order of 10279these constructions within the machine description file is not 10280important. 10281 10282@findex define_automaton 10283@cindex pipeline hazard recognizer 10284The following optional construction describes names of automata 10285generated and used for the pipeline hazards recognition. Sometimes 10286the generated finite state automaton used by the pipeline hazard 10287recognizer is large. If we use more than one automaton and bind functional 10288units to the automata, the total size of the automata is usually 10289less than the size of the single automaton. If there is no one such 10290construction, only one finite state automaton is generated. 10291 10292@smallexample 10293(define_automaton @var{automata-names}) 10294@end smallexample 10295 10296@var{automata-names} is a string giving names of the automata. The 10297names are separated by commas. All the automata should have unique names. 10298The automaton name is used in the constructions @code{define_cpu_unit} and 10299@code{define_query_cpu_unit}. 10300 10301@findex define_cpu_unit 10302@cindex processor functional units 10303Each processor functional unit used in the description of instruction 10304reservations should be described by the following construction. 10305 10306@smallexample 10307(define_cpu_unit @var{unit-names} [@var{automaton-name}]) 10308@end smallexample 10309 10310@var{unit-names} is a string giving the names of the functional units 10311separated by commas. Don't use name @samp{nothing}, it is reserved 10312for other goals. 10313 10314@var{automaton-name} is a string giving the name of the automaton with 10315which the unit is bound. The automaton should be described in 10316construction @code{define_automaton}. You should give 10317@dfn{automaton-name}, if there is a defined automaton. 10318 10319The assignment of units to automata are constrained by the uses of the 10320units in insn reservations. The most important constraint is: if a 10321unit reservation is present on a particular cycle of an alternative 10322for an insn reservation, then some unit from the same automaton must 10323be present on the same cycle for the other alternatives of the insn 10324reservation. The rest of the constraints are mentioned in the 10325description of the subsequent constructions. 10326 10327@findex define_query_cpu_unit 10328@cindex querying function unit reservations 10329The following construction describes CPU functional units analogously 10330to @code{define_cpu_unit}. The reservation of such units can be 10331queried for an automaton state. The instruction scheduler never 10332queries reservation of functional units for given automaton state. So 10333as a rule, you don't need this construction. This construction could 10334be used for future code generation goals (e.g.@: to generate 10335@acronym{VLIW} insn templates). 10336 10337@smallexample 10338(define_query_cpu_unit @var{unit-names} [@var{automaton-name}]) 10339@end smallexample 10340 10341@var{unit-names} is a string giving names of the functional units 10342separated by commas. 10343 10344@var{automaton-name} is a string giving the name of the automaton with 10345which the unit is bound. 10346 10347@findex define_insn_reservation 10348@cindex instruction latency time 10349@cindex regular expressions 10350@cindex data bypass 10351The following construction is the major one to describe pipeline 10352characteristics of an instruction. 10353 10354@smallexample 10355(define_insn_reservation @var{insn-name} @var{default_latency} 10356 @var{condition} @var{regexp}) 10357@end smallexample 10358 10359@var{default_latency} is a number giving latency time of the 10360instruction. There is an important difference between the old 10361description and the automaton based pipeline description. The latency 10362time is used for all dependencies when we use the old description. In 10363the automaton based pipeline description, the given latency time is only 10364used for true dependencies. The cost of anti-dependencies is always 10365zero and the cost of output dependencies is the difference between 10366latency times of the producing and consuming insns (if the difference 10367is negative, the cost is considered to be zero). You can always 10368change the default costs for any description by using the target hook 10369@code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}). 10370 10371@var{insn-name} is a string giving the internal name of the insn. The 10372internal names are used in constructions @code{define_bypass} and in 10373the automaton description file generated for debugging. The internal 10374name has nothing in common with the names in @code{define_insn}. It is a 10375good practice to use insn classes described in the processor manual. 10376 10377@var{condition} defines what RTL insns are described by this 10378construction. You should remember that you will be in trouble if 10379@var{condition} for two or more different 10380@code{define_insn_reservation} constructions is TRUE for an insn. In 10381this case what reservation will be used for the insn is not defined. 10382Such cases are not checked during generation of the pipeline hazards 10383recognizer because in general recognizing that two conditions may have 10384the same value is quite difficult (especially if the conditions 10385contain @code{symbol_ref}). It is also not checked during the 10386pipeline hazard recognizer work because it would slow down the 10387recognizer considerably. 10388 10389@var{regexp} is a string describing the reservation of the cpu's functional 10390units by the instruction. The reservations are described by a regular 10391expression according to the following syntax: 10392 10393@smallexample 10394 regexp = regexp "," oneof 10395 | oneof 10396 10397 oneof = oneof "|" allof 10398 | allof 10399 10400 allof = allof "+" repeat 10401 | repeat 10402 10403 repeat = element "*" number 10404 | element 10405 10406 element = cpu_function_unit_name 10407 | reservation_name 10408 | result_name 10409 | "nothing" 10410 | "(" regexp ")" 10411@end smallexample 10412 10413@itemize @bullet 10414@item 10415@samp{,} is used for describing the start of the next cycle in 10416the reservation. 10417 10418@item 10419@samp{|} is used for describing a reservation described by the first 10420regular expression @strong{or} a reservation described by the second 10421regular expression @strong{or} etc. 10422 10423@item 10424@samp{+} is used for describing a reservation described by the first 10425regular expression @strong{and} a reservation described by the 10426second regular expression @strong{and} etc. 10427 10428@item 10429@samp{*} is used for convenience and simply means a sequence in which 10430the regular expression are repeated @var{number} times with cycle 10431advancing (see @samp{,}). 10432 10433@item 10434@samp{cpu_function_unit_name} denotes reservation of the named 10435functional unit. 10436 10437@item 10438@samp{reservation_name} --- see description of construction 10439@samp{define_reservation}. 10440 10441@item 10442@samp{nothing} denotes no unit reservations. 10443@end itemize 10444 10445@findex define_reservation 10446Sometimes unit reservations for different insns contain common parts. 10447In such case, you can simplify the pipeline description by describing 10448the common part by the following construction 10449 10450@smallexample 10451(define_reservation @var{reservation-name} @var{regexp}) 10452@end smallexample 10453 10454@var{reservation-name} is a string giving name of @var{regexp}. 10455Functional unit names and reservation names are in the same name 10456space. So the reservation names should be different from the 10457functional unit names and cannot be the reserved name @samp{nothing}. 10458 10459@findex define_bypass 10460@cindex instruction latency time 10461@cindex data bypass 10462The following construction is used to describe exceptions in the 10463latency time for given instruction pair. This is so called bypasses. 10464 10465@smallexample 10466(define_bypass @var{number} @var{out_insn_names} @var{in_insn_names} 10467 [@var{guard}]) 10468@end smallexample 10469 10470@var{number} defines when the result generated by the instructions 10471given in string @var{out_insn_names} will be ready for the 10472instructions given in string @var{in_insn_names}. Each of these 10473strings is a comma-separated list of filename-style globs and 10474they refer to the names of @code{define_insn_reservation}s. 10475For example: 10476@smallexample 10477(define_bypass 1 "cpu1_load_*, cpu1_store_*" "cpu1_load_*") 10478@end smallexample 10479defines a bypass between instructions that start with 10480@samp{cpu1_load_} or @samp{cpu1_store_} and those that start with 10481@samp{cpu1_load_}. 10482 10483@var{guard} is an optional string giving the name of a C function which 10484defines an additional guard for the bypass. The function will get the 10485two insns as parameters. If the function returns zero the bypass will 10486be ignored for this case. The additional guard is necessary to 10487recognize complicated bypasses, e.g.@: when the consumer is only an address 10488of insn @samp{store} (not a stored value). 10489 10490If there are more one bypass with the same output and input insns, the 10491chosen bypass is the first bypass with a guard in description whose 10492guard function returns nonzero. If there is no such bypass, then 10493bypass without the guard function is chosen. 10494 10495@findex exclusion_set 10496@findex presence_set 10497@findex final_presence_set 10498@findex absence_set 10499@findex final_absence_set 10500@cindex VLIW 10501@cindex RISC 10502The following five constructions are usually used to describe 10503@acronym{VLIW} processors, or more precisely, to describe a placement 10504of small instructions into @acronym{VLIW} instruction slots. They 10505can be used for @acronym{RISC} processors, too. 10506 10507@smallexample 10508(exclusion_set @var{unit-names} @var{unit-names}) 10509(presence_set @var{unit-names} @var{patterns}) 10510(final_presence_set @var{unit-names} @var{patterns}) 10511(absence_set @var{unit-names} @var{patterns}) 10512(final_absence_set @var{unit-names} @var{patterns}) 10513@end smallexample 10514 10515@var{unit-names} is a string giving names of functional units 10516separated by commas. 10517 10518@var{patterns} is a string giving patterns of functional units 10519separated by comma. Currently pattern is one unit or units 10520separated by white-spaces. 10521 10522The first construction (@samp{exclusion_set}) means that each 10523functional unit in the first string cannot be reserved simultaneously 10524with a unit whose name is in the second string and vice versa. For 10525example, the construction is useful for describing processors 10526(e.g.@: some SPARC processors) with a fully pipelined floating point 10527functional unit which can execute simultaneously only single floating 10528point insns or only double floating point insns. 10529 10530The second construction (@samp{presence_set}) means that each 10531functional unit in the first string cannot be reserved unless at 10532least one of pattern of units whose names are in the second string is 10533reserved. This is an asymmetric relation. For example, it is useful 10534for description that @acronym{VLIW} @samp{slot1} is reserved after 10535@samp{slot0} reservation. We could describe it by the following 10536construction 10537 10538@smallexample 10539(presence_set "slot1" "slot0") 10540@end smallexample 10541 10542Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0} 10543reservation. In this case we could write 10544 10545@smallexample 10546(presence_set "slot1" "slot0 b0") 10547@end smallexample 10548 10549The third construction (@samp{final_presence_set}) is analogous to 10550@samp{presence_set}. The difference between them is when checking is 10551done. When an instruction is issued in given automaton state 10552reflecting all current and planned unit reservations, the automaton 10553state is changed. The first state is a source state, the second one 10554is a result state. Checking for @samp{presence_set} is done on the 10555source state reservation, checking for @samp{final_presence_set} is 10556done on the result reservation. This construction is useful to 10557describe a reservation which is actually two subsequent reservations. 10558For example, if we use 10559 10560@smallexample 10561(presence_set "slot1" "slot0") 10562@end smallexample 10563 10564the following insn will be never issued (because @samp{slot1} requires 10565@samp{slot0} which is absent in the source state). 10566 10567@smallexample 10568(define_reservation "insn_and_nop" "slot0 + slot1") 10569@end smallexample 10570 10571but it can be issued if we use analogous @samp{final_presence_set}. 10572 10573The forth construction (@samp{absence_set}) means that each functional 10574unit in the first string can be reserved only if each pattern of units 10575whose names are in the second string is not reserved. This is an 10576asymmetric relation (actually @samp{exclusion_set} is analogous to 10577this one but it is symmetric). For example it might be useful in a 10578@acronym{VLIW} description to say that @samp{slot0} cannot be reserved 10579after either @samp{slot1} or @samp{slot2} have been reserved. This 10580can be described as: 10581 10582@smallexample 10583(absence_set "slot0" "slot1, slot2") 10584@end smallexample 10585 10586Or @samp{slot2} cannot be reserved if @samp{slot0} and unit @samp{b0} 10587are reserved or @samp{slot1} and unit @samp{b1} are reserved. In 10588this case we could write 10589 10590@smallexample 10591(absence_set "slot2" "slot0 b0, slot1 b1") 10592@end smallexample 10593 10594All functional units mentioned in a set should belong to the same 10595automaton. 10596 10597The last construction (@samp{final_absence_set}) is analogous to 10598@samp{absence_set} but checking is done on the result (state) 10599reservation. See comments for @samp{final_presence_set}. 10600 10601@findex automata_option 10602@cindex deterministic finite state automaton 10603@cindex nondeterministic finite state automaton 10604@cindex finite state automaton minimization 10605You can control the generator of the pipeline hazard recognizer with 10606the following construction. 10607 10608@smallexample 10609(automata_option @var{options}) 10610@end smallexample 10611 10612@var{options} is a string giving options which affect the generated 10613code. Currently there are the following options: 10614 10615@itemize @bullet 10616@item 10617@dfn{no-minimization} makes no minimization of the automaton. This is 10618only worth to do when we are debugging the description and need to 10619look more accurately at reservations of states. 10620 10621@item 10622@dfn{time} means printing time statistics about the generation of 10623automata. 10624 10625@item 10626@dfn{stats} means printing statistics about the generated automata 10627such as the number of DFA states, NDFA states and arcs. 10628 10629@item 10630@dfn{v} means a generation of the file describing the result automata. 10631The file has suffix @samp{.dfa} and can be used for the description 10632verification and debugging. 10633 10634@item 10635@dfn{w} means a generation of warning instead of error for 10636non-critical errors. 10637 10638@item 10639@dfn{no-comb-vect} prevents the automaton generator from generating 10640two data structures and comparing them for space efficiency. Using 10641a comb vector to represent transitions may be better, but it can be 10642very expensive to construct. This option is useful if the build 10643process spends an unacceptably long time in genautomata. 10644 10645@item 10646@dfn{ndfa} makes nondeterministic finite state automata. This affects 10647the treatment of operator @samp{|} in the regular expressions. The 10648usual treatment of the operator is to try the first alternative and, 10649if the reservation is not possible, the second alternative. The 10650nondeterministic treatment means trying all alternatives, some of them 10651may be rejected by reservations in the subsequent insns. 10652 10653@item 10654@dfn{collapse-ndfa} modifies the behavior of the generator when 10655producing an automaton. An additional state transition to collapse a 10656nondeterministic @acronym{NDFA} state to a deterministic @acronym{DFA} 10657state is generated. It can be triggered by passing @code{const0_rtx} to 10658state_transition. In such an automaton, cycle advance transitions are 10659available only for these collapsed states. This option is useful for 10660ports that want to use the @code{ndfa} option, but also want to use 10661@code{define_query_cpu_unit} to assign units to insns issued in a cycle. 10662 10663@item 10664@dfn{progress} means output of a progress bar showing how many states 10665were generated so far for automaton being processed. This is useful 10666during debugging a @acronym{DFA} description. If you see too many 10667generated states, you could interrupt the generator of the pipeline 10668hazard recognizer and try to figure out a reason for generation of the 10669huge automaton. 10670@end itemize 10671 10672As an example, consider a superscalar @acronym{RISC} machine which can 10673issue three insns (two integer insns and one floating point insn) on 10674the cycle but can finish only two insns. To describe this, we define 10675the following functional units. 10676 10677@smallexample 10678(define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline") 10679(define_cpu_unit "port0, port1") 10680@end smallexample 10681 10682All simple integer insns can be executed in any integer pipeline and 10683their result is ready in two cycles. The simple integer insns are 10684issued into the first pipeline unless it is reserved, otherwise they 10685are issued into the second pipeline. Integer division and 10686multiplication insns can be executed only in the second integer 10687pipeline and their results are ready correspondingly in 9 and 4 10688cycles. The integer division is not pipelined, i.e.@: the subsequent 10689integer division insn cannot be issued until the current division 10690insn finished. Floating point insns are fully pipelined and their 10691results are ready in 3 cycles. Where the result of a floating point 10692insn is used by an integer insn, an additional delay of one cycle is 10693incurred. To describe all of this we could specify 10694 10695@smallexample 10696(define_cpu_unit "div") 10697 10698(define_insn_reservation "simple" 2 (eq_attr "type" "int") 10699 "(i0_pipeline | i1_pipeline), (port0 | port1)") 10700 10701(define_insn_reservation "mult" 4 (eq_attr "type" "mult") 10702 "i1_pipeline, nothing*2, (port0 | port1)") 10703 10704(define_insn_reservation "div" 9 (eq_attr "type" "div") 10705 "i1_pipeline, div*7, div + (port0 | port1)") 10706 10707(define_insn_reservation "float" 3 (eq_attr "type" "float") 10708 "f_pipeline, nothing, (port0 | port1)) 10709 10710(define_bypass 4 "float" "simple,mult,div") 10711@end smallexample 10712 10713To simplify the description we could describe the following reservation 10714 10715@smallexample 10716(define_reservation "finish" "port0|port1") 10717@end smallexample 10718 10719and use it in all @code{define_insn_reservation} as in the following 10720construction 10721 10722@smallexample 10723(define_insn_reservation "simple" 2 (eq_attr "type" "int") 10724 "(i0_pipeline | i1_pipeline), finish") 10725@end smallexample 10726 10727 10728@end ifset 10729@ifset INTERNALS 10730@node Conditional Execution 10731@section Conditional Execution 10732@cindex conditional execution 10733@cindex predication 10734 10735A number of architectures provide for some form of conditional 10736execution, or predication. The hallmark of this feature is the 10737ability to nullify most of the instructions in the instruction set. 10738When the instruction set is large and not entirely symmetric, it 10739can be quite tedious to describe these forms directly in the 10740@file{.md} file. An alternative is the @code{define_cond_exec} template. 10741 10742@findex define_cond_exec 10743@smallexample 10744(define_cond_exec 10745 [@var{predicate-pattern}] 10746 "@var{condition}" 10747 "@var{output-template}" 10748 "@var{optional-insn-attribues}") 10749@end smallexample 10750 10751@var{predicate-pattern} is the condition that must be true for the 10752insn to be executed at runtime and should match a relational operator. 10753One can use @code{match_operator} to match several relational operators 10754at once. Any @code{match_operand} operands must have no more than one 10755alternative. 10756 10757@var{condition} is a C expression that must be true for the generated 10758pattern to match. 10759 10760@findex current_insn_predicate 10761@var{output-template} is a string similar to the @code{define_insn} 10762output template (@pxref{Output Template}), except that the @samp{*} 10763and @samp{@@} special cases do not apply. This is only useful if the 10764assembly text for the predicate is a simple prefix to the main insn. 10765In order to handle the general case, there is a global variable 10766@code{current_insn_predicate} that will contain the entire predicate 10767if the current insn is predicated, and will otherwise be @code{NULL}. 10768 10769@var{optional-insn-attributes} is an optional vector of attributes that gets 10770appended to the insn attributes of the produced cond_exec rtx. It can 10771be used to add some distinguishing attribute to cond_exec rtxs produced 10772that way. An example usage would be to use this attribute in conjunction 10773with attributes on the main pattern to disable particular alternatives under 10774certain conditions. 10775 10776When @code{define_cond_exec} is used, an implicit reference to 10777the @code{predicable} instruction attribute is made. 10778@xref{Insn Attributes}. This attribute must be a boolean (i.e.@: have 10779exactly two elements in its @var{list-of-values}), with the possible 10780values being @code{no} and @code{yes}. The default and all uses in 10781the insns must be a simple constant, not a complex expressions. It 10782may, however, depend on the alternative, by using a comma-separated 10783list of values. If that is the case, the port should also define an 10784@code{enabled} attribute (@pxref{Disable Insn Alternatives}), which 10785should also allow only @code{no} and @code{yes} as its values. 10786 10787For each @code{define_insn} for which the @code{predicable} 10788attribute is true, a new @code{define_insn} pattern will be 10789generated that matches a predicated version of the instruction. 10790For example, 10791 10792@smallexample 10793(define_insn "addsi" 10794 [(set (match_operand:SI 0 "register_operand" "r") 10795 (plus:SI (match_operand:SI 1 "register_operand" "r") 10796 (match_operand:SI 2 "register_operand" "r")))] 10797 "@var{test1}" 10798 "add %2,%1,%0") 10799 10800(define_cond_exec 10801 [(ne (match_operand:CC 0 "register_operand" "c") 10802 (const_int 0))] 10803 "@var{test2}" 10804 "(%0)") 10805@end smallexample 10806 10807@noindent 10808generates a new pattern 10809 10810@smallexample 10811(define_insn "" 10812 [(cond_exec 10813 (ne (match_operand:CC 3 "register_operand" "c") (const_int 0)) 10814 (set (match_operand:SI 0 "register_operand" "r") 10815 (plus:SI (match_operand:SI 1 "register_operand" "r") 10816 (match_operand:SI 2 "register_operand" "r"))))] 10817 "(@var{test2}) && (@var{test1})" 10818 "(%3) add %2,%1,%0") 10819@end smallexample 10820 10821@end ifset 10822@ifset INTERNALS 10823@node Define Subst 10824@section RTL Templates Transformations 10825@cindex define_subst 10826 10827For some hardware architectures there are common cases when the RTL 10828templates for the instructions can be derived from the other RTL 10829templates using simple transformations. E.g., @file{i386.md} contains 10830an RTL template for the ordinary @code{sub} instruction--- 10831@code{*subsi_1}, and for the @code{sub} instruction with subsequent 10832zero-extension---@code{*subsi_1_zext}. Such cases can be easily 10833implemented by a single meta-template capable of generating a modified 10834case based on the initial one: 10835 10836@findex define_subst 10837@smallexample 10838(define_subst "@var{name}" 10839 [@var{input-template}] 10840 "@var{condition}" 10841 [@var{output-template}]) 10842@end smallexample 10843@var{input-template} is a pattern describing the source RTL template, 10844which will be transformed. 10845 10846@var{condition} is a C expression that is conjunct with the condition 10847from the input-template to generate a condition to be used in the 10848output-template. 10849 10850@var{output-template} is a pattern that will be used in the resulting 10851template. 10852 10853@code{define_subst} mechanism is tightly coupled with the notion of the 10854subst attribute (@pxref{Subst Iterators}). The use of 10855@code{define_subst} is triggered by a reference to a subst attribute in 10856the transforming RTL template. This reference initiates duplication of 10857the source RTL template and substitution of the attributes with their 10858values. The source RTL template is left unchanged, while the copy is 10859transformed by @code{define_subst}. This transformation can fail in the 10860case when the source RTL template is not matched against the 10861input-template of the @code{define_subst}. In such case the copy is 10862deleted. 10863 10864@code{define_subst} can be used only in @code{define_insn} and 10865@code{define_expand}, it cannot be used in other expressions (e.g.@: in 10866@code{define_insn_and_split}). 10867 10868@menu 10869* Define Subst Example:: Example of @code{define_subst} work. 10870* Define Subst Pattern Matching:: Process of template comparison. 10871* Define Subst Output Template:: Generation of output template. 10872@end menu 10873 10874@node Define Subst Example 10875@subsection @code{define_subst} Example 10876@cindex define_subst 10877 10878To illustrate how @code{define_subst} works, let us examine a simple 10879template transformation. 10880 10881Suppose there are two kinds of instructions: one that touches flags and 10882the other that does not. The instructions of the second type could be 10883generated with the following @code{define_subst}: 10884 10885@smallexample 10886(define_subst "add_clobber_subst" 10887 [(set (match_operand:SI 0 "" "") 10888 (match_operand:SI 1 "" ""))] 10889 "" 10890 [(set (match_dup 0) 10891 (match_dup 1)) 10892 (clobber (reg:CC FLAGS_REG))]) 10893@end smallexample 10894 10895This @code{define_subst} can be applied to any RTL pattern containing 10896@code{set} of mode SI and generates a copy with clobber when it is 10897applied. 10898 10899Assume there is an RTL template for a @code{max} instruction to be used 10900in @code{define_subst} mentioned above: 10901 10902@smallexample 10903(define_insn "maxsi" 10904 [(set (match_operand:SI 0 "register_operand" "=r") 10905 (max:SI 10906 (match_operand:SI 1 "register_operand" "r") 10907 (match_operand:SI 2 "register_operand" "r")))] 10908 "" 10909 "max\t@{%2, %1, %0|%0, %1, %2@}" 10910 [@dots{}]) 10911@end smallexample 10912 10913To mark the RTL template for @code{define_subst} application, 10914subst-attributes are used. They should be declared in advance: 10915 10916@smallexample 10917(define_subst_attr "add_clobber_name" "add_clobber_subst" "_noclobber" "_clobber") 10918@end smallexample 10919 10920Here @samp{add_clobber_name} is the attribute name, 10921@samp{add_clobber_subst} is the name of the corresponding 10922@code{define_subst}, the third argument (@samp{_noclobber}) is the 10923attribute value that would be substituted into the unchanged version of 10924the source RTL template, and the last argument (@samp{_clobber}) is the 10925value that would be substituted into the second, transformed, 10926version of the RTL template. 10927 10928Once the subst-attribute has been defined, it should be used in RTL 10929templates which need to be processed by the @code{define_subst}. So, 10930the original RTL template should be changed: 10931 10932@smallexample 10933(define_insn "maxsi<add_clobber_name>" 10934 [(set (match_operand:SI 0 "register_operand" "=r") 10935 (max:SI 10936 (match_operand:SI 1 "register_operand" "r") 10937 (match_operand:SI 2 "register_operand" "r")))] 10938 "" 10939 "max\t@{%2, %1, %0|%0, %1, %2@}" 10940 [@dots{}]) 10941@end smallexample 10942 10943The result of the @code{define_subst} usage would look like the following: 10944 10945@smallexample 10946(define_insn "maxsi_noclobber" 10947 [(set (match_operand:SI 0 "register_operand" "=r") 10948 (max:SI 10949 (match_operand:SI 1 "register_operand" "r") 10950 (match_operand:SI 2 "register_operand" "r")))] 10951 "" 10952 "max\t@{%2, %1, %0|%0, %1, %2@}" 10953 [@dots{}]) 10954(define_insn "maxsi_clobber" 10955 [(set (match_operand:SI 0 "register_operand" "=r") 10956 (max:SI 10957 (match_operand:SI 1 "register_operand" "r") 10958 (match_operand:SI 2 "register_operand" "r"))) 10959 (clobber (reg:CC FLAGS_REG))] 10960 "" 10961 "max\t@{%2, %1, %0|%0, %1, %2@}" 10962 [@dots{}]) 10963@end smallexample 10964 10965@node Define Subst Pattern Matching 10966@subsection Pattern Matching in @code{define_subst} 10967@cindex define_subst 10968 10969All expressions, allowed in @code{define_insn} or @code{define_expand}, 10970are allowed in the input-template of @code{define_subst}, except 10971@code{match_par_dup}, @code{match_scratch}, @code{match_parallel}. The 10972meanings of expressions in the input-template were changed: 10973 10974@code{match_operand} matches any expression (possibly, a subtree in 10975RTL-template), if modes of the @code{match_operand} and this expression 10976are the same, or mode of the @code{match_operand} is @code{VOIDmode}, or 10977this expression is @code{match_dup}, @code{match_op_dup}. If the 10978expression is @code{match_operand} too, and predicate of 10979@code{match_operand} from the input pattern is not empty, then the 10980predicates are compared. That can be used for more accurate filtering 10981of accepted RTL-templates. 10982 10983@code{match_operator} matches common operators (like @code{plus}, 10984@code{minus}), @code{unspec}, @code{unspec_volatile} operators and 10985@code{match_operator}s from the original pattern if the modes match and 10986@code{match_operator} from the input pattern has the same number of 10987operands as the operator from the original pattern. 10988 10989@node Define Subst Output Template 10990@subsection Generation of output template in @code{define_subst} 10991@cindex define_subst 10992 10993If all necessary checks for @code{define_subst} application pass, a new 10994RTL-pattern, based on the output-template, is created to replace the old 10995template. Like in input-patterns, meanings of some RTL expressions are 10996changed when they are used in output-patterns of a @code{define_subst}. 10997Thus, @code{match_dup} is used for copying the whole expression from the 10998original pattern, which matched corresponding @code{match_operand} from 10999the input pattern. 11000 11001@code{match_dup N} is used in the output template to be replaced with 11002the expression from the original pattern, which matched 11003@code{match_operand N} from the input pattern. As a consequence, 11004@code{match_dup} cannot be used to point to @code{match_operand}s from 11005the output pattern, it should always refer to a @code{match_operand} 11006from the input pattern. If a @code{match_dup N} occurs more than once 11007in the output template, its first occurrence is replaced with the 11008expression from the original pattern, and the subsequent expressions 11009are replaced with @code{match_dup N}, i.e., a reference to the first 11010expression. 11011 11012In the output template one can refer to the expressions from the 11013original pattern and create new ones. For instance, some operands could 11014be added by means of standard @code{match_operand}. 11015 11016After replacing @code{match_dup} with some RTL-subtree from the original 11017pattern, it could happen that several @code{match_operand}s in the 11018output pattern have the same indexes. It is unknown, how many and what 11019indexes would be used in the expression which would replace 11020@code{match_dup}, so such conflicts in indexes are inevitable. To 11021overcome this issue, @code{match_operands} and @code{match_operators}, 11022which were introduced into the output pattern, are renumerated when all 11023@code{match_dup}s are replaced. 11024 11025Number of alternatives in @code{match_operand}s introduced into the 11026output template @code{M} could differ from the number of alternatives in 11027the original pattern @code{N}, so in the resultant pattern there would 11028be @code{N*M} alternatives. Thus, constraints from the original pattern 11029would be duplicated @code{N} times, constraints from the output pattern 11030would be duplicated @code{M} times, producing all possible combinations. 11031@end ifset 11032 11033@ifset INTERNALS 11034@node Constant Definitions 11035@section Constant Definitions 11036@cindex constant definitions 11037@findex define_constants 11038 11039Using literal constants inside instruction patterns reduces legibility and 11040can be a maintenance problem. 11041 11042To overcome this problem, you may use the @code{define_constants} 11043expression. It contains a vector of name-value pairs. From that 11044point on, wherever any of the names appears in the MD file, it is as 11045if the corresponding value had been written instead. You may use 11046@code{define_constants} multiple times; each appearance adds more 11047constants to the table. It is an error to redefine a constant with 11048a different value. 11049 11050To come back to the a29k load multiple example, instead of 11051 11052@smallexample 11053(define_insn "" 11054 [(match_parallel 0 "load_multiple_operation" 11055 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 11056 (match_operand:SI 2 "memory_operand" "m")) 11057 (use (reg:SI 179)) 11058 (clobber (reg:SI 179))])] 11059 "" 11060 "loadm 0,0,%1,%2") 11061@end smallexample 11062 11063You could write: 11064 11065@smallexample 11066(define_constants [ 11067 (R_BP 177) 11068 (R_FC 178) 11069 (R_CR 179) 11070 (R_Q 180) 11071]) 11072 11073(define_insn "" 11074 [(match_parallel 0 "load_multiple_operation" 11075 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 11076 (match_operand:SI 2 "memory_operand" "m")) 11077 (use (reg:SI R_CR)) 11078 (clobber (reg:SI R_CR))])] 11079 "" 11080 "loadm 0,0,%1,%2") 11081@end smallexample 11082 11083The constants that are defined with a define_constant are also output 11084in the insn-codes.h header file as #defines. 11085 11086@cindex enumerations 11087@findex define_c_enum 11088You can also use the machine description file to define enumerations. 11089Like the constants defined by @code{define_constant}, these enumerations 11090are visible to both the machine description file and the main C code. 11091 11092The syntax is as follows: 11093 11094@smallexample 11095(define_c_enum "@var{name}" [ 11096 @var{value0} 11097 @var{value1} 11098 (@var{value32} 32) 11099 @var{value33} 11100 @dots{} 11101 @var{valuen} 11102]) 11103@end smallexample 11104 11105This definition causes the equivalent of the following C code to appear 11106in @file{insn-constants.h}: 11107 11108@smallexample 11109enum @var{name} @{ 11110 @var{value0} = 0, 11111 @var{value1} = 1, 11112 @var{value32} = 32, 11113 @var{value33} = 33, 11114 @dots{} 11115 @var{valuen} = @var{n} 11116@}; 11117#define NUM_@var{cname}_VALUES (@var{n} + 1) 11118@end smallexample 11119 11120where @var{cname} is the capitalized form of @var{name}. 11121It also makes each @var{valuei} available in the machine description 11122file, just as if it had been declared with: 11123 11124@smallexample 11125(define_constants [(@var{valuei} @var{i})]) 11126@end smallexample 11127 11128Each @var{valuei} is usually an upper-case identifier and usually 11129begins with @var{cname}. 11130 11131You can split the enumeration definition into as many statements as 11132you like. The above example is directly equivalent to: 11133 11134@smallexample 11135(define_c_enum "@var{name}" [@var{value0}]) 11136(define_c_enum "@var{name}" [@var{value1}]) 11137@dots{} 11138(define_c_enum "@var{name}" [@var{valuen}]) 11139@end smallexample 11140 11141Splitting the enumeration helps to improve the modularity of each 11142individual @code{.md} file. For example, if a port defines its 11143synchronization instructions in a separate @file{sync.md} file, 11144it is convenient to define all synchronization-specific enumeration 11145values in @file{sync.md} rather than in the main @file{.md} file. 11146 11147Some enumeration names have special significance to GCC: 11148 11149@table @code 11150@item unspecv 11151@findex unspec_volatile 11152If an enumeration called @code{unspecv} is defined, GCC will use it 11153when printing out @code{unspec_volatile} expressions. For example: 11154 11155@smallexample 11156(define_c_enum "unspecv" [ 11157 UNSPECV_BLOCKAGE 11158]) 11159@end smallexample 11160 11161causes GCC to print @samp{(unspec_volatile @dots{} 0)} as: 11162 11163@smallexample 11164(unspec_volatile ... UNSPECV_BLOCKAGE) 11165@end smallexample 11166 11167@item unspec 11168@findex unspec 11169If an enumeration called @code{unspec} is defined, GCC will use 11170it when printing out @code{unspec} expressions. GCC will also use 11171it when printing out @code{unspec_volatile} expressions unless an 11172@code{unspecv} enumeration is also defined. You can therefore 11173decide whether to keep separate enumerations for volatile and 11174non-volatile expressions or whether to use the same enumeration 11175for both. 11176@end table 11177 11178@findex define_enum 11179@anchor{define_enum} 11180Another way of defining an enumeration is to use @code{define_enum}: 11181 11182@smallexample 11183(define_enum "@var{name}" [ 11184 @var{value0} 11185 @var{value1} 11186 @dots{} 11187 @var{valuen} 11188]) 11189@end smallexample 11190 11191This directive implies: 11192 11193@smallexample 11194(define_c_enum "@var{name}" [ 11195 @var{cname}_@var{cvalue0} 11196 @var{cname}_@var{cvalue1} 11197 @dots{} 11198 @var{cname}_@var{cvaluen} 11199]) 11200@end smallexample 11201 11202@findex define_enum_attr 11203where @var{cvaluei} is the capitalized form of @var{valuei}. 11204However, unlike @code{define_c_enum}, the enumerations defined 11205by @code{define_enum} can be used in attribute specifications 11206(@pxref{define_enum_attr}). 11207@end ifset 11208@ifset INTERNALS 11209@node Iterators 11210@section Iterators 11211@cindex iterators in @file{.md} files 11212 11213Ports often need to define similar patterns for more than one machine 11214mode or for more than one rtx code. GCC provides some simple iterator 11215facilities to make this process easier. 11216 11217@menu 11218* Mode Iterators:: Generating variations of patterns for different modes. 11219* Code Iterators:: Doing the same for codes. 11220* Int Iterators:: Doing the same for integers. 11221* Subst Iterators:: Generating variations of patterns for define_subst. 11222* Parameterized Names:: Specifying iterator values in C++ code. 11223@end menu 11224 11225@node Mode Iterators 11226@subsection Mode Iterators 11227@cindex mode iterators in @file{.md} files 11228 11229Ports often need to define similar patterns for two or more different modes. 11230For example: 11231 11232@itemize @bullet 11233@item 11234If a processor has hardware support for both single and double 11235floating-point arithmetic, the @code{SFmode} patterns tend to be 11236very similar to the @code{DFmode} ones. 11237 11238@item 11239If a port uses @code{SImode} pointers in one configuration and 11240@code{DImode} pointers in another, it will usually have very similar 11241@code{SImode} and @code{DImode} patterns for manipulating pointers. 11242@end itemize 11243 11244Mode iterators allow several patterns to be instantiated from one 11245@file{.md} file template. They can be used with any type of 11246rtx-based construct, such as a @code{define_insn}, 11247@code{define_split}, or @code{define_peephole2}. 11248 11249@menu 11250* Defining Mode Iterators:: Defining a new mode iterator. 11251* Substitutions:: Combining mode iterators with substitutions 11252* Examples:: Examples 11253@end menu 11254 11255@node Defining Mode Iterators 11256@subsubsection Defining Mode Iterators 11257@findex define_mode_iterator 11258 11259The syntax for defining a mode iterator is: 11260 11261@smallexample 11262(define_mode_iterator @var{name} [(@var{mode1} "@var{cond1}") @dots{} (@var{moden} "@var{condn}")]) 11263@end smallexample 11264 11265This allows subsequent @file{.md} file constructs to use the mode suffix 11266@code{:@var{name}}. Every construct that does so will be expanded 11267@var{n} times, once with every use of @code{:@var{name}} replaced by 11268@code{:@var{mode1}}, once with every use replaced by @code{:@var{mode2}}, 11269and so on. In the expansion for a particular @var{modei}, every 11270C condition will also require that @var{condi} be true. 11271 11272For example: 11273 11274@smallexample 11275(define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")]) 11276@end smallexample 11277 11278defines a new mode suffix @code{:P}. Every construct that uses 11279@code{:P} will be expanded twice, once with every @code{:P} replaced 11280by @code{:SI} and once with every @code{:P} replaced by @code{:DI}. 11281The @code{:SI} version will only apply if @code{Pmode == SImode} and 11282the @code{:DI} version will only apply if @code{Pmode == DImode}. 11283 11284As with other @file{.md} conditions, an empty string is treated 11285as ``always true''. @code{(@var{mode} "")} can also be abbreviated 11286to @code{@var{mode}}. For example: 11287 11288@smallexample 11289(define_mode_iterator GPR [SI (DI "TARGET_64BIT")]) 11290@end smallexample 11291 11292means that the @code{:DI} expansion only applies if @code{TARGET_64BIT} 11293but that the @code{:SI} expansion has no such constraint. 11294 11295Iterators are applied in the order they are defined. This can be 11296significant if two iterators are used in a construct that requires 11297substitutions. @xref{Substitutions}. 11298 11299@node Substitutions 11300@subsubsection Substitution in Mode Iterators 11301@findex define_mode_attr 11302 11303If an @file{.md} file construct uses mode iterators, each version of the 11304construct will often need slightly different strings or modes. For 11305example: 11306 11307@itemize @bullet 11308@item 11309When a @code{define_expand} defines several @code{add@var{m}3} patterns 11310(@pxref{Standard Names}), each expander will need to use the 11311appropriate mode name for @var{m}. 11312 11313@item 11314When a @code{define_insn} defines several instruction patterns, 11315each instruction will often use a different assembler mnemonic. 11316 11317@item 11318When a @code{define_insn} requires operands with different modes, 11319using an iterator for one of the operand modes usually requires a specific 11320mode for the other operand(s). 11321@end itemize 11322 11323GCC supports such variations through a system of ``mode attributes''. 11324There are two standard attributes: @code{mode}, which is the name of 11325the mode in lower case, and @code{MODE}, which is the same thing in 11326upper case. You can define other attributes using: 11327 11328@smallexample 11329(define_mode_attr @var{name} [(@var{mode1} "@var{value1}") @dots{} (@var{moden} "@var{valuen}")]) 11330@end smallexample 11331 11332where @var{name} is the name of the attribute and @var{valuei} 11333is the value associated with @var{modei}. 11334 11335When GCC replaces some @var{:iterator} with @var{:mode}, it will scan 11336each string and mode in the pattern for sequences of the form 11337@code{<@var{iterator}:@var{attr}>}, where @var{attr} is the name of a 11338mode attribute. If the attribute is defined for @var{mode}, the whole 11339@code{<@dots{}>} sequence will be replaced by the appropriate attribute 11340value. 11341 11342For example, suppose an @file{.md} file has: 11343 11344@smallexample 11345(define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")]) 11346(define_mode_attr load [(SI "lw") (DI "ld")]) 11347@end smallexample 11348 11349If one of the patterns that uses @code{:P} contains the string 11350@code{"<P:load>\t%0,%1"}, the @code{SI} version of that pattern 11351will use @code{"lw\t%0,%1"} and the @code{DI} version will use 11352@code{"ld\t%0,%1"}. 11353 11354Here is an example of using an attribute for a mode: 11355 11356@smallexample 11357(define_mode_iterator LONG [SI DI]) 11358(define_mode_attr SHORT [(SI "HI") (DI "SI")]) 11359(define_insn @dots{} 11360 (sign_extend:LONG (match_operand:<LONG:SHORT> @dots{})) @dots{}) 11361@end smallexample 11362 11363The @code{@var{iterator}:} prefix may be omitted, in which case the 11364substitution will be attempted for every iterator expansion. 11365 11366@node Examples 11367@subsubsection Mode Iterator Examples 11368 11369Here is an example from the MIPS port. It defines the following 11370modes and attributes (among others): 11371 11372@smallexample 11373(define_mode_iterator GPR [SI (DI "TARGET_64BIT")]) 11374(define_mode_attr d [(SI "") (DI "d")]) 11375@end smallexample 11376 11377and uses the following template to define both @code{subsi3} 11378and @code{subdi3}: 11379 11380@smallexample 11381(define_insn "sub<mode>3" 11382 [(set (match_operand:GPR 0 "register_operand" "=d") 11383 (minus:GPR (match_operand:GPR 1 "register_operand" "d") 11384 (match_operand:GPR 2 "register_operand" "d")))] 11385 "" 11386 "<d>subu\t%0,%1,%2" 11387 [(set_attr "type" "arith") 11388 (set_attr "mode" "<MODE>")]) 11389@end smallexample 11390 11391This is exactly equivalent to: 11392 11393@smallexample 11394(define_insn "subsi3" 11395 [(set (match_operand:SI 0 "register_operand" "=d") 11396 (minus:SI (match_operand:SI 1 "register_operand" "d") 11397 (match_operand:SI 2 "register_operand" "d")))] 11398 "" 11399 "subu\t%0,%1,%2" 11400 [(set_attr "type" "arith") 11401 (set_attr "mode" "SI")]) 11402 11403(define_insn "subdi3" 11404 [(set (match_operand:DI 0 "register_operand" "=d") 11405 (minus:DI (match_operand:DI 1 "register_operand" "d") 11406 (match_operand:DI 2 "register_operand" "d")))] 11407 "" 11408 "dsubu\t%0,%1,%2" 11409 [(set_attr "type" "arith") 11410 (set_attr "mode" "DI")]) 11411@end smallexample 11412 11413@node Code Iterators 11414@subsection Code Iterators 11415@cindex code iterators in @file{.md} files 11416@findex define_code_iterator 11417@findex define_code_attr 11418 11419Code iterators operate in a similar way to mode iterators. @xref{Mode Iterators}. 11420 11421The construct: 11422 11423@smallexample 11424(define_code_iterator @var{name} [(@var{code1} "@var{cond1}") @dots{} (@var{coden} "@var{condn}")]) 11425@end smallexample 11426 11427defines a pseudo rtx code @var{name} that can be instantiated as 11428@var{codei} if condition @var{condi} is true. Each @var{codei} 11429must have the same rtx format. @xref{RTL Classes}. 11430 11431As with mode iterators, each pattern that uses @var{name} will be 11432expanded @var{n} times, once with all uses of @var{name} replaced by 11433@var{code1}, once with all uses replaced by @var{code2}, and so on. 11434@xref{Defining Mode Iterators}. 11435 11436It is possible to define attributes for codes as well as for modes. 11437There are two standard code attributes: @code{code}, the name of the 11438code in lower case, and @code{CODE}, the name of the code in upper case. 11439Other attributes are defined using: 11440 11441@smallexample 11442(define_code_attr @var{name} [(@var{code1} "@var{value1}") @dots{} (@var{coden} "@var{valuen}")]) 11443@end smallexample 11444 11445Instruction patterns can use code attributes as rtx codes, which can be 11446useful if two sets of codes act in tandem. For example, the following 11447@code{define_insn} defines two patterns, one calculating a signed absolute 11448difference and another calculating an unsigned absolute difference: 11449 11450@smallexample 11451(define_code_iterator any_max [smax umax]) 11452(define_code_attr paired_min [(smax "smin") (umax "umin")]) 11453(define_insn @dots{} 11454 [(set (match_operand:SI 0 @dots{}) 11455 (minus:SI (any_max:SI (match_operand:SI 1 @dots{}) 11456 (match_operand:SI 2 @dots{})) 11457 (<paired_min>:SI (match_dup 1) (match_dup 2))))] 11458 @dots{}) 11459@end smallexample 11460 11461The signed version of the instruction uses @code{smax} and @code{smin} 11462while the unsigned version uses @code{umax} and @code{umin}. There 11463are no versions that pair @code{smax} with @code{umin} or @code{umax} 11464with @code{smin}. 11465 11466Here's an example of code iterators in action, taken from the MIPS port: 11467 11468@smallexample 11469(define_code_iterator any_cond [unordered ordered unlt unge uneq ltgt unle ungt 11470 eq ne gt ge lt le gtu geu ltu leu]) 11471 11472(define_expand "b<code>" 11473 [(set (pc) 11474 (if_then_else (any_cond:CC (cc0) 11475 (const_int 0)) 11476 (label_ref (match_operand 0 "")) 11477 (pc)))] 11478 "" 11479@{ 11480 gen_conditional_branch (operands, <CODE>); 11481 DONE; 11482@}) 11483@end smallexample 11484 11485This is equivalent to: 11486 11487@smallexample 11488(define_expand "bunordered" 11489 [(set (pc) 11490 (if_then_else (unordered:CC (cc0) 11491 (const_int 0)) 11492 (label_ref (match_operand 0 "")) 11493 (pc)))] 11494 "" 11495@{ 11496 gen_conditional_branch (operands, UNORDERED); 11497 DONE; 11498@}) 11499 11500(define_expand "bordered" 11501 [(set (pc) 11502 (if_then_else (ordered:CC (cc0) 11503 (const_int 0)) 11504 (label_ref (match_operand 0 "")) 11505 (pc)))] 11506 "" 11507@{ 11508 gen_conditional_branch (operands, ORDERED); 11509 DONE; 11510@}) 11511 11512@dots{} 11513@end smallexample 11514 11515@node Int Iterators 11516@subsection Int Iterators 11517@cindex int iterators in @file{.md} files 11518@findex define_int_iterator 11519@findex define_int_attr 11520 11521Int iterators operate in a similar way to code iterators. @xref{Code Iterators}. 11522 11523The construct: 11524 11525@smallexample 11526(define_int_iterator @var{name} [(@var{int1} "@var{cond1}") @dots{} (@var{intn} "@var{condn}")]) 11527@end smallexample 11528 11529defines a pseudo integer constant @var{name} that can be instantiated as 11530@var{inti} if condition @var{condi} is true. Each @var{int} must have the 11531same rtx format. @xref{RTL Classes}. Int iterators can appear in only 11532those rtx fields that have 'i', 'n', 'w', or 'p' as the specifier. This 11533means that each @var{int} has to be a constant defined using define_constant 11534or define_c_enum. 11535 11536As with mode and code iterators, each pattern that uses @var{name} will be 11537expanded @var{n} times, once with all uses of @var{name} replaced by 11538@var{int1}, once with all uses replaced by @var{int2}, and so on. 11539@xref{Defining Mode Iterators}. 11540 11541It is possible to define attributes for ints as well as for codes and modes. 11542Attributes are defined using: 11543 11544@smallexample 11545(define_int_attr @var{name} [(@var{int1} "@var{value1}") @dots{} (@var{intn} "@var{valuen}")]) 11546@end smallexample 11547 11548Here's an example of int iterators in action, taken from the ARM port: 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 "TARGET_NEON" 11561 "vq<absneg>.<V_s_elem>\t%<V_reg>0, %<V_reg>1" 11562 [(set_attr "type" "neon_vqneg_vqabs")] 11563) 11564 11565@end smallexample 11566 11567This is equivalent to: 11568 11569@smallexample 11570(define_insn "neon_vqabs<mode>" 11571 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 11572 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 11573 (match_operand:SI 2 "immediate_operand" "i")] 11574 UNSPEC_VQABS))] 11575 "TARGET_NEON" 11576 "vqabs.<V_s_elem>\t%<V_reg>0, %<V_reg>1" 11577 [(set_attr "type" "neon_vqneg_vqabs")] 11578) 11579 11580(define_insn "neon_vqneg<mode>" 11581 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 11582 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 11583 (match_operand:SI 2 "immediate_operand" "i")] 11584 UNSPEC_VQNEG))] 11585 "TARGET_NEON" 11586 "vqneg.<V_s_elem>\t%<V_reg>0, %<V_reg>1" 11587 [(set_attr "type" "neon_vqneg_vqabs")] 11588) 11589 11590@end smallexample 11591 11592@node Subst Iterators 11593@subsection Subst Iterators 11594@cindex subst iterators in @file{.md} files 11595@findex define_subst 11596@findex define_subst_attr 11597 11598Subst iterators are special type of iterators with the following 11599restrictions: they could not be declared explicitly, they always have 11600only two values, and they do not have explicit dedicated name. 11601Subst-iterators are triggered only when corresponding subst-attribute is 11602used in RTL-pattern. 11603 11604Subst iterators transform templates in the following way: the templates 11605are duplicated, the subst-attributes in these templates are replaced 11606with the corresponding values, and a new attribute is implicitly added 11607to the given @code{define_insn}/@code{define_expand}. The name of the 11608added attribute matches the name of @code{define_subst}. Such 11609attributes are declared implicitly, and it is not allowed to have a 11610@code{define_attr} named as a @code{define_subst}. 11611 11612Each subst iterator is linked to a @code{define_subst}. It is declared 11613implicitly by the first appearance of the corresponding 11614@code{define_subst_attr}, and it is not allowed to define it explicitly. 11615 11616Declarations of subst-attributes have the following syntax: 11617 11618@findex define_subst_attr 11619@smallexample 11620(define_subst_attr "@var{name}" 11621 "@var{subst-name}" 11622 "@var{no-subst-value}" 11623 "@var{subst-applied-value}") 11624@end smallexample 11625 11626@var{name} is a string with which the given subst-attribute could be 11627referred to. 11628 11629@var{subst-name} shows which @code{define_subst} should be applied to an 11630RTL-template if the given subst-attribute is present in the 11631RTL-template. 11632 11633@var{no-subst-value} is a value with which subst-attribute would be 11634replaced in the first copy of the original RTL-template. 11635 11636@var{subst-applied-value} is a value with which subst-attribute would be 11637replaced in the second copy of the original RTL-template. 11638 11639@node Parameterized Names 11640@subsection Parameterized Names 11641@cindex @samp{@@} in instruction pattern names 11642Ports sometimes need to apply iterators using C++ code, in order to 11643get the code or RTL pattern for a specific instruction. For example, 11644suppose we have the @samp{neon_vq<absneg><mode>} pattern given above: 11645 11646@smallexample 11647(define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG]) 11648 11649(define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")]) 11650 11651(define_insn "neon_vq<absneg><mode>" 11652 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 11653 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 11654 (match_operand:SI 2 "immediate_operand" "i")] 11655 QABSNEG))] 11656 @dots{} 11657) 11658@end smallexample 11659 11660A port might need to generate this pattern for a variable 11661@samp{QABSNEG} value and a variable @samp{VDQIW} mode. There are two 11662ways of doing this. The first is to build the rtx for the pattern 11663directly from C++ code; this is a valid technique and avoids any risk 11664of combinatorial explosion. The second is to prefix the instruction 11665name with the special character @samp{@@}, which tells GCC to generate 11666the four additional functions below. In each case, @var{name} is the 11667name of the instruction without the leading @samp{@@} character, 11668without the @samp{<@dots{}>} placeholders, and with any underscore 11669before a @samp{<@dots{}>} placeholder removed if keeping it would 11670lead to a double or trailing underscore. 11671 11672@table @samp 11673@item insn_code maybe_code_for_@var{name} (@var{i1}, @var{i2}, @dots{}) 11674See whether replacing the first @samp{<@dots{}>} placeholder with 11675iterator value @var{i1}, the second with iterator value @var{i2}, and 11676so on, gives a valid instruction. Return its code if so, otherwise 11677return @code{CODE_FOR_nothing}. 11678 11679@item insn_code code_for_@var{name} (@var{i1}, @var{i2}, @dots{}) 11680Same, but abort the compiler if the requested instruction does not exist. 11681 11682@item rtx maybe_gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{}) 11683Check for a valid instruction in the same way as 11684@code{maybe_code_for_@var{name}}. If the instruction exists, 11685generate an instance of it using the operand values given by @var{op0}, 11686@var{op1}, and so on, otherwise return null. 11687 11688@item rtx gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{}) 11689Same, but abort the compiler if the requested instruction does not exist, 11690or if the instruction generator invoked the @code{FAIL} macro. 11691@end table 11692 11693For example, changing the pattern above to: 11694 11695@smallexample 11696(define_insn "@@neon_vq<absneg><mode>" 11697 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 11698 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 11699 (match_operand:SI 2 "immediate_operand" "i")] 11700 QABSNEG))] 11701 @dots{} 11702) 11703@end smallexample 11704 11705would define the same patterns as before, but in addition would generate 11706the four functions below: 11707 11708@smallexample 11709insn_code maybe_code_for_neon_vq (int, machine_mode); 11710insn_code code_for_neon_vq (int, machine_mode); 11711rtx maybe_gen_neon_vq (int, machine_mode, rtx, rtx, rtx); 11712rtx gen_neon_vq (int, machine_mode, rtx, rtx, rtx); 11713@end smallexample 11714 11715Calling @samp{code_for_neon_vq (UNSPEC_VQABS, V8QImode)} 11716would then give @code{CODE_FOR_neon_vqabsv8qi}. 11717 11718It is possible to have multiple @samp{@@} patterns with the same 11719name and same types of iterator. For example: 11720 11721@smallexample 11722(define_insn "@@some_arithmetic_op<mode>" 11723 [(set (match_operand:INTEGER_MODES 0 "register_operand") @dots{})] 11724 @dots{} 11725) 11726 11727(define_insn "@@some_arithmetic_op<mode>" 11728 [(set (match_operand:FLOAT_MODES 0 "register_operand") @dots{})] 11729 @dots{} 11730) 11731@end smallexample 11732 11733would produce a single set of functions that handles both 11734@code{INTEGER_MODES} and @code{FLOAT_MODES}. 11735 11736It is also possible for these @samp{@@} patterns to have different 11737numbers of operands from each other. For example, patterns with 11738a binary rtl code might take three operands (one output and two inputs) 11739while patterns with a ternary rtl code might take four operands (one 11740output and three inputs). This combination would produce separate 11741@samp{maybe_gen_@var{name}} and @samp{gen_@var{name}} functions for 11742each operand count, but it would still produce a single 11743@samp{maybe_code_for_@var{name}} and a single @samp{code_for_@var{name}}. 11744 11745@end ifset 11746