1@c Copyright (C) 1988-2018 Free Software Foundation, Inc. 2@c This is part of the GCC manual. 3@c For copying conditions, see the file gcc.texi. 4 5@ifset INTERNALS 6@node Machine Desc 7@chapter Machine Descriptions 8@cindex machine descriptions 9 10A machine description has two parts: a file of instruction patterns 11(@file{.md} file) and a C header file of macro definitions. 12 13The @file{.md} file for a target machine contains a pattern for each 14instruction that the target machine supports (or at least each instruction 15that is worth telling the compiler about). It may also contain comments. 16A semicolon causes the rest of the line to be a comment, unless the semicolon 17is inside a quoted string. 18 19See the next chapter for information on the C header file. 20 21@menu 22* Overview:: How the machine description is used. 23* Patterns:: How to write instruction patterns. 24* Example:: An explained example of a @code{define_insn} pattern. 25* RTL Template:: The RTL template defines what insns match a pattern. 26* Output Template:: The output template says how to make assembler code 27 from such an insn. 28* Output Statement:: For more generality, write C code to output 29 the assembler code. 30* Predicates:: Controlling what kinds of operands can be used 31 for an insn. 32* Constraints:: Fine-tuning operand selection. 33* Standard Names:: Names mark patterns to use for code generation. 34* Pattern Ordering:: When the order of patterns makes a difference. 35* Dependent Patterns:: Having one pattern may make you need another. 36* Jump Patterns:: Special considerations for patterns for jump insns. 37* Looping Patterns:: How to define patterns for special looping insns. 38* Insn Canonicalizations::Canonicalization of Instructions 39* Expander Definitions::Generating a sequence of several RTL insns 40 for a standard operation. 41* Insn Splitting:: Splitting Instructions into Multiple Instructions. 42* Including Patterns:: Including Patterns in Machine Descriptions. 43* Peephole Definitions::Defining machine-specific peephole optimizations. 44* Insn Attributes:: Specifying the value of attributes for generated insns. 45* Conditional Execution::Generating @code{define_insn} patterns for 46 predication. 47* Define Subst:: Generating @code{define_insn} and @code{define_expand} 48 patterns from other patterns. 49* Constant Definitions::Defining symbolic constants that can be used in the 50 md file. 51* Iterators:: Using iterators to generate patterns from a template. 52@end menu 53 54@node Overview 55@section Overview of How the Machine Description is Used 56 57There are three main conversions that happen in the compiler: 58 59@enumerate 60 61@item 62The front end reads the source code and builds a parse tree. 63 64@item 65The parse tree is used to generate an RTL insn list based on named 66instruction patterns. 67 68@item 69The insn list is matched against the RTL templates to produce assembler 70code. 71 72@end enumerate 73 74For the generate pass, only the names of the insns matter, from either a 75named @code{define_insn} or a @code{define_expand}. The compiler will 76choose the pattern with the right name and apply the operands according 77to the documentation later in this chapter, without regard for the RTL 78template or operand constraints. Note that the names the compiler looks 79for are hard-coded in the compiler---it will ignore unnamed patterns and 80patterns with names it doesn't know about, but if you don't provide a 81named pattern it needs, it will abort. 82 83If a @code{define_insn} is used, the template given is inserted into the 84insn list. If a @code{define_expand} is used, one of three things 85happens, based on the condition logic. The condition logic may manually 86create new insns for the insn list, say via @code{emit_insn()}, and 87invoke @code{DONE}. For certain named patterns, it may invoke @code{FAIL} to tell the 88compiler to use an alternate way of performing that task. If it invokes 89neither @code{DONE} nor @code{FAIL}, the template given in the pattern 90is inserted, as if the @code{define_expand} were a @code{define_insn}. 91 92Once the insn list is generated, various optimization passes convert, 93replace, and rearrange the insns in the insn list. This is where the 94@code{define_split} and @code{define_peephole} patterns get used, for 95example. 96 97Finally, the insn list's RTL is matched up with the RTL templates in the 98@code{define_insn} patterns, and those patterns are used to emit the 99final assembly code. For this purpose, each named @code{define_insn} 100acts like it's unnamed, since the names are ignored. 101 102@node Patterns 103@section Everything about Instruction Patterns 104@cindex patterns 105@cindex instruction patterns 106 107@findex define_insn 108A @code{define_insn} expression is used to define instruction patterns 109to which insns may be matched. A @code{define_insn} expression contains 110an incomplete RTL expression, with pieces to be filled in later, operand 111constraints that restrict how the pieces can be filled in, and an output 112template or C code to generate the assembler output. 113 114A @code{define_insn} is an RTL expression containing four or five operands: 115 116@enumerate 117@item 118An optional name. The presence of a name indicates that this instruction 119pattern can perform a certain standard job for the RTL-generation 120pass of the compiler. This pass knows certain names and will use 121the instruction patterns with those names, if the names are defined 122in the machine description. 123 124The absence of a name is indicated by writing an empty string 125where the name should go. Nameless instruction patterns are never 126used for generating RTL code, but they may permit several simpler insns 127to be combined later on. 128 129Names that are not thus known and used in RTL-generation have no 130effect; they are equivalent to no name at all. 131 132For the purpose of debugging the compiler, you may also specify a 133name beginning with the @samp{*} character. Such a name is used only 134for identifying the instruction in RTL dumps; it is equivalent to having 135a nameless pattern for all other purposes. Names beginning with the 136@samp{*} character are not required to be unique. 137 138@item 139The @dfn{RTL template}: This is a vector of incomplete RTL expressions 140which describe the semantics of the instruction (@pxref{RTL Template}). 141It is incomplete because it may contain @code{match_operand}, 142@code{match_operator}, and @code{match_dup} expressions that stand for 143operands of the instruction. 144 145If the vector has multiple elements, the RTL template is treated as a 146@code{parallel} expression. 147 148@item 149@cindex pattern conditions 150@cindex conditions, in patterns 151The condition: This is a string which contains a C expression. When the 152compiler attempts to match RTL against a pattern, the condition is 153evaluated. If the condition evaluates to @code{true}, the match is 154permitted. The condition may be an empty string, which is treated 155as always @code{true}. 156 157@cindex named patterns and conditions 158For a named pattern, the condition may not depend on the data in the 159insn being matched, but only the target-machine-type flags. The compiler 160needs to test these conditions during initialization in order to learn 161exactly which named instructions are available in a particular run. 162 163@findex operands 164For nameless patterns, the condition is applied only when matching an 165individual insn, and only after the insn has matched the pattern's 166recognition template. The insn's operands may be found in the vector 167@code{operands}. 168 169An instruction condition cannot become more restrictive as compilation 170progresses. If the condition accepts a particular RTL instruction at 171one stage of compilation, it must continue to accept that instruction 172until the final pass. For example, @samp{!reload_completed} and 173@samp{can_create_pseudo_p ()} are both invalid instruction conditions, 174because they are true during the earlier RTL passes and false during 175the later ones. For the same reason, if a condition accepts an 176instruction before register allocation, it cannot later try to control 177register allocation by excluding certain register or value combinations. 178 179Although a condition cannot become more restrictive as compilation 180progresses, the condition for a nameless pattern @emph{can} become 181more permissive. For example, a nameless instruction can require 182@samp{reload_completed} to be true, in which case it only matches 183after register allocation. 184 185@item 186The @dfn{output template} or @dfn{output statement}: This is either 187a string, or a fragment of C code which returns a string. 188 189When simple substitution isn't general enough, you can specify a piece 190of C code to compute the output. @xref{Output Statement}. 191 192@item 193The @dfn{insn attributes}: This is an optional vector containing the values of 194attributes for insns matching this pattern (@pxref{Insn Attributes}). 195@end enumerate 196 197@node Example 198@section Example of @code{define_insn} 199@cindex @code{define_insn} example 200 201Here is an example of an instruction pattern, taken from the machine 202description for the 68000/68020. 203 204@smallexample 205(define_insn "tstsi" 206 [(set (cc0) 207 (match_operand:SI 0 "general_operand" "rm"))] 208 "" 209 "* 210@{ 211 if (TARGET_68020 || ! ADDRESS_REG_P (operands[0])) 212 return \"tstl %0\"; 213 return \"cmpl #0,%0\"; 214@}") 215@end smallexample 216 217@noindent 218This can also be written using braced strings: 219 220@smallexample 221(define_insn "tstsi" 222 [(set (cc0) 223 (match_operand:SI 0 "general_operand" "rm"))] 224 "" 225@{ 226 if (TARGET_68020 || ! ADDRESS_REG_P (operands[0])) 227 return "tstl %0"; 228 return "cmpl #0,%0"; 229@}) 230@end smallexample 231 232This describes an instruction which sets the condition codes based on the 233value of a general operand. It has no condition, so any insn with an RTL 234description of the form shown may be matched to this pattern. The name 235@samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL 236generation pass that, when it is necessary to test such a value, an insn 237to do so can be constructed using this pattern. 238 239The output control string is a piece of C code which chooses which 240output template to return based on the kind of operand and the specific 241type of CPU for which code is being generated. 242 243@samp{"rm"} is an operand constraint. Its meaning is explained below. 244 245@node RTL Template 246@section RTL Template 247@cindex RTL insn template 248@cindex generating insns 249@cindex insns, generating 250@cindex recognizing insns 251@cindex insns, recognizing 252 253The RTL template is used to define which insns match the particular pattern 254and how to find their operands. For named patterns, the RTL template also 255says how to construct an insn from specified operands. 256 257Construction involves substituting specified operands into a copy of the 258template. Matching involves determining the values that serve as the 259operands in the insn being matched. Both of these activities are 260controlled by special expression types that direct matching and 261substitution of the operands. 262 263@table @code 264@findex match_operand 265@item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint}) 266This expression is a placeholder for operand number @var{n} of 267the insn. When constructing an insn, operand number @var{n} 268will be substituted at this point. When matching an insn, whatever 269appears at this position in the insn will be taken as operand 270number @var{n}; but it must satisfy @var{predicate} or this instruction 271pattern will not match at all. 272 273Operand numbers must be chosen consecutively counting from zero in 274each instruction pattern. There may be only one @code{match_operand} 275expression in the pattern for each operand number. Usually operands 276are numbered in the order of appearance in @code{match_operand} 277expressions. In the case of a @code{define_expand}, any operand numbers 278used only in @code{match_dup} expressions have higher values than all 279other operand numbers. 280 281@var{predicate} is a string that is the name of a function that 282accepts two arguments, an expression and a machine mode. 283@xref{Predicates}. During matching, the function will be called with 284the putative operand as the expression and @var{m} as the mode 285argument (if @var{m} is not specified, @code{VOIDmode} will be used, 286which normally causes @var{predicate} to accept any mode). If it 287returns zero, this instruction pattern fails to match. 288@var{predicate} may be an empty string; then it means no test is to be 289done on the operand, so anything which occurs in this position is 290valid. 291 292Most of the time, @var{predicate} will reject modes other than @var{m}---but 293not always. For example, the predicate @code{address_operand} uses 294@var{m} as the mode of memory ref that the address should be valid for. 295Many predicates accept @code{const_int} nodes even though their mode is 296@code{VOIDmode}. 297 298@var{constraint} controls reloading and the choice of the best register 299class to use for a value, as explained later (@pxref{Constraints}). 300If the constraint would be an empty string, it can be omitted. 301 302People are often unclear on the difference between the constraint and the 303predicate. The predicate helps decide whether a given insn matches the 304pattern. The constraint plays no role in this decision; instead, it 305controls various decisions in the case of an insn which does match. 306 307@findex match_scratch 308@item (match_scratch:@var{m} @var{n} @var{constraint}) 309This expression is also a placeholder for operand number @var{n} 310and indicates that operand must be a @code{scratch} or @code{reg} 311expression. 312 313When matching patterns, this is equivalent to 314 315@smallexample 316(match_operand:@var{m} @var{n} "scratch_operand" @var{constraint}) 317@end smallexample 318 319but, when generating RTL, it produces a (@code{scratch}:@var{m}) 320expression. 321 322If the last few expressions in a @code{parallel} are @code{clobber} 323expressions whose operands are either a hard register or 324@code{match_scratch}, the combiner can add or delete them when 325necessary. @xref{Side Effects}. 326 327@findex match_dup 328@item (match_dup @var{n}) 329This expression is also a placeholder for operand number @var{n}. 330It is used when the operand needs to appear more than once in the 331insn. 332 333In construction, @code{match_dup} acts just like @code{match_operand}: 334the operand is substituted into the insn being constructed. But in 335matching, @code{match_dup} behaves differently. It assumes that operand 336number @var{n} has already been determined by a @code{match_operand} 337appearing earlier in the recognition template, and it matches only an 338identical-looking expression. 339 340Note that @code{match_dup} should not be used to tell the compiler that 341a particular register is being used for two operands (example: 342@code{add} that adds one register to another; the second register is 343both an input operand and the output operand). Use a matching 344constraint (@pxref{Simple Constraints}) for those. @code{match_dup} is for the cases where one 345operand is used in two places in the template, such as an instruction 346that computes both a quotient and a remainder, where the opcode takes 347two input operands but the RTL template has to refer to each of those 348twice; once for the quotient pattern and once for the remainder pattern. 349 350@findex match_operator 351@item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}]) 352This pattern is a kind of placeholder for a variable RTL expression 353code. 354 355When constructing an insn, it stands for an RTL expression whose 356expression code is taken from that of operand @var{n}, and whose 357operands are constructed from the patterns @var{operands}. 358 359When matching an expression, it matches an expression if the function 360@var{predicate} returns nonzero on that expression @emph{and} the 361patterns @var{operands} match the operands of the expression. 362 363Suppose that the function @code{commutative_operator} is defined as 364follows, to match any expression whose operator is one of the 365commutative arithmetic operators of RTL and whose mode is @var{mode}: 366 367@smallexample 368int 369commutative_integer_operator (x, mode) 370 rtx x; 371 machine_mode mode; 372@{ 373 enum rtx_code code = GET_CODE (x); 374 if (GET_MODE (x) != mode) 375 return 0; 376 return (GET_RTX_CLASS (code) == RTX_COMM_ARITH 377 || code == EQ || code == NE); 378@} 379@end smallexample 380 381Then the following pattern will match any RTL expression consisting 382of a commutative operator applied to two general operands: 383 384@smallexample 385(match_operator:SI 3 "commutative_operator" 386 [(match_operand:SI 1 "general_operand" "g") 387 (match_operand:SI 2 "general_operand" "g")]) 388@end smallexample 389 390Here the vector @code{[@var{operands}@dots{}]} contains two patterns 391because the expressions to be matched all contain two operands. 392 393When this pattern does match, the two operands of the commutative 394operator are recorded as operands 1 and 2 of the insn. (This is done 395by the two instances of @code{match_operand}.) Operand 3 of the insn 396will be the entire commutative expression: use @code{GET_CODE 397(operands[3])} to see which commutative operator was used. 398 399The machine mode @var{m} of @code{match_operator} works like that of 400@code{match_operand}: it is passed as the second argument to the 401predicate function, and that function is solely responsible for 402deciding whether the expression to be matched ``has'' that mode. 403 404When constructing an insn, argument 3 of the gen-function will specify 405the operation (i.e.@: the expression code) for the expression to be 406made. It should be an RTL expression, whose expression code is copied 407into a new expression whose operands are arguments 1 and 2 of the 408gen-function. The subexpressions of argument 3 are not used; 409only its expression code matters. 410 411When @code{match_operator} is used in a pattern for matching an insn, 412it usually best if the operand number of the @code{match_operator} 413is higher than that of the actual operands of the insn. This improves 414register allocation because the register allocator often looks at 415operands 1 and 2 of insns to see if it can do register tying. 416 417There is no way to specify constraints in @code{match_operator}. The 418operand of the insn which corresponds to the @code{match_operator} 419never has any constraints because it is never reloaded as a whole. 420However, if parts of its @var{operands} are matched by 421@code{match_operand} patterns, those parts may have constraints of 422their own. 423 424@findex match_op_dup 425@item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}]) 426Like @code{match_dup}, except that it applies to operators instead of 427operands. When constructing an insn, operand number @var{n} will be 428substituted at this point. But in matching, @code{match_op_dup} behaves 429differently. It assumes that operand number @var{n} has already been 430determined by a @code{match_operator} appearing earlier in the 431recognition template, and it matches only an identical-looking 432expression. 433 434@findex match_parallel 435@item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}]) 436This pattern is a placeholder for an insn that consists of a 437@code{parallel} expression with a variable number of elements. This 438expression should only appear at the top level of an insn pattern. 439 440When constructing an insn, operand number @var{n} will be substituted at 441this point. When matching an insn, it matches if the body of the insn 442is a @code{parallel} expression with at least as many elements as the 443vector of @var{subpat} expressions in the @code{match_parallel}, if each 444@var{subpat} matches the corresponding element of the @code{parallel}, 445@emph{and} the function @var{predicate} returns nonzero on the 446@code{parallel} that is the body of the insn. It is the responsibility 447of the predicate to validate elements of the @code{parallel} beyond 448those listed in the @code{match_parallel}. 449 450A typical use of @code{match_parallel} is to match load and store 451multiple expressions, which can contain a variable number of elements 452in a @code{parallel}. For example, 453 454@smallexample 455(define_insn "" 456 [(match_parallel 0 "load_multiple_operation" 457 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 458 (match_operand:SI 2 "memory_operand" "m")) 459 (use (reg:SI 179)) 460 (clobber (reg:SI 179))])] 461 "" 462 "loadm 0,0,%1,%2") 463@end smallexample 464 465This example comes from @file{a29k.md}. The function 466@code{load_multiple_operation} is defined in @file{a29k.c} and checks 467that subsequent elements in the @code{parallel} are the same as the 468@code{set} in the pattern, except that they are referencing subsequent 469registers and memory locations. 470 471An insn that matches this pattern might look like: 472 473@smallexample 474(parallel 475 [(set (reg:SI 20) (mem:SI (reg:SI 100))) 476 (use (reg:SI 179)) 477 (clobber (reg:SI 179)) 478 (set (reg:SI 21) 479 (mem:SI (plus:SI (reg:SI 100) 480 (const_int 4)))) 481 (set (reg:SI 22) 482 (mem:SI (plus:SI (reg:SI 100) 483 (const_int 8))))]) 484@end smallexample 485 486@findex match_par_dup 487@item (match_par_dup @var{n} [@var{subpat}@dots{}]) 488Like @code{match_op_dup}, but for @code{match_parallel} instead of 489@code{match_operator}. 490 491@end table 492 493@node Output Template 494@section Output Templates and Operand Substitution 495@cindex output templates 496@cindex operand substitution 497 498@cindex @samp{%} in template 499@cindex percent sign 500The @dfn{output template} is a string which specifies how to output the 501assembler code for an instruction pattern. Most of the template is a 502fixed string which is output literally. The character @samp{%} is used 503to specify where to substitute an operand; it can also be used to 504identify places where different variants of the assembler require 505different syntax. 506 507In the simplest case, a @samp{%} followed by a digit @var{n} says to output 508operand @var{n} at that point in the string. 509 510@samp{%} followed by a letter and a digit says to output an operand in an 511alternate fashion. Four letters have standard, built-in meanings described 512below. The machine description macro @code{PRINT_OPERAND} can define 513additional letters with nonstandard meanings. 514 515@samp{%c@var{digit}} can be used to substitute an operand that is a 516constant value without the syntax that normally indicates an immediate 517operand. 518 519@samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of 520the constant is negated before printing. 521 522@samp{%a@var{digit}} can be used to substitute an operand as if it were a 523memory reference, with the actual operand treated as the address. This may 524be useful when outputting a ``load address'' instruction, because often the 525assembler syntax for such an instruction requires you to write the operand 526as if it were a memory reference. 527 528@samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump 529instruction. 530 531@samp{%=} outputs a number which is unique to each instruction in the 532entire compilation. This is useful for making local labels to be 533referred to more than once in a single template that generates multiple 534assembler instructions. 535 536@samp{%} followed by a punctuation character specifies a substitution that 537does not use an operand. Only one case is standard: @samp{%%} outputs a 538@samp{%} into the assembler code. Other nonstandard cases can be 539defined in the @code{PRINT_OPERAND} macro. You must also define 540which punctuation characters are valid with the 541@code{PRINT_OPERAND_PUNCT_VALID_P} macro. 542 543@cindex \ 544@cindex backslash 545The template may generate multiple assembler instructions. Write the text 546for the instructions, with @samp{\;} between them. 547 548@cindex matching operands 549When the RTL contains two operands which are required by constraint to match 550each other, the output template must refer only to the lower-numbered operand. 551Matching operands are not always identical, and the rest of the compiler 552arranges to put the proper RTL expression for printing into the lower-numbered 553operand. 554 555One use of nonstandard letters or punctuation following @samp{%} is to 556distinguish between different assembler languages for the same machine; for 557example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax 558requires periods in most opcode names, while MIT syntax does not. For 559example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola 560syntax. The same file of patterns is used for both kinds of output syntax, 561but the character sequence @samp{%.} is used in each place where Motorola 562syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax 563defines the sequence to output a period; the macro for MIT syntax defines 564it to do nothing. 565 566@cindex @code{#} in template 567As a special case, a template consisting of the single character @code{#} 568instructs the compiler to first split the insn, and then output the 569resulting instructions separately. This helps eliminate redundancy in the 570output templates. If you have a @code{define_insn} that needs to emit 571multiple assembler instructions, and there is a matching @code{define_split} 572already defined, then you can simply use @code{#} as the output template 573instead of writing an output template that emits the multiple assembler 574instructions. 575 576Note that @code{#} only has an effect while generating assembly code; 577it does not affect whether a split occurs earlier. An associated 578@code{define_split} must exist and it must be suitable for use after 579register allocation. 580 581If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct 582of the form @samp{@{option0|option1|option2@}} in the templates. These 583describe multiple variants of assembler language syntax. 584@xref{Instruction Output}. 585 586@node Output Statement 587@section C Statements for Assembler Output 588@cindex output statements 589@cindex C statements for assembler output 590@cindex generating assembler output 591 592Often a single fixed template string cannot produce correct and efficient 593assembler code for all the cases that are recognized by a single 594instruction pattern. For example, the opcodes may depend on the kinds of 595operands; or some unfortunate combinations of operands may require extra 596machine instructions. 597 598If the output control string starts with a @samp{@@}, then it is actually 599a series of templates, each on a separate line. (Blank lines and 600leading spaces and tabs are ignored.) The templates correspond to the 601pattern's constraint alternatives (@pxref{Multi-Alternative}). For example, 602if a target machine has a two-address add instruction @samp{addr} to add 603into a register and another @samp{addm} to add a register to memory, you 604might write this pattern: 605 606@smallexample 607(define_insn "addsi3" 608 [(set (match_operand:SI 0 "general_operand" "=r,m") 609 (plus:SI (match_operand:SI 1 "general_operand" "0,0") 610 (match_operand:SI 2 "general_operand" "g,r")))] 611 "" 612 "@@ 613 addr %2,%0 614 addm %2,%0") 615@end smallexample 616 617@cindex @code{*} in template 618@cindex asterisk in template 619If the output control string starts with a @samp{*}, then it is not an 620output template but rather a piece of C program that should compute a 621template. It should execute a @code{return} statement to return the 622template-string you want. Most such templates use C string literals, which 623require doublequote characters to delimit them. To include these 624doublequote characters in the string, prefix each one with @samp{\}. 625 626If the output control string is written as a brace block instead of a 627double-quoted string, it is automatically assumed to be C code. In that 628case, it is not necessary to put in a leading asterisk, or to escape the 629doublequotes surrounding C string literals. 630 631The operands may be found in the array @code{operands}, whose C data type 632is @code{rtx []}. 633 634It is very common to select different ways of generating assembler code 635based on whether an immediate operand is within a certain range. Be 636careful when doing this, because the result of @code{INTVAL} is an 637integer on the host machine. If the host machine has more bits in an 638@code{int} than the target machine has in the mode in which the constant 639will be used, then some of the bits you get from @code{INTVAL} will be 640superfluous. For proper results, you must carefully disregard the 641values of those bits. 642 643@findex output_asm_insn 644It is possible to output an assembler instruction and then go on to output 645or compute more of them, using the subroutine @code{output_asm_insn}. This 646receives two arguments: a template-string and a vector of operands. The 647vector may be @code{operands}, or it may be another array of @code{rtx} 648that you declare locally and initialize yourself. 649 650@findex which_alternative 651When an insn pattern has multiple alternatives in its constraints, often 652the appearance of the assembler code is determined mostly by which alternative 653was matched. When this is so, the C code can test the variable 654@code{which_alternative}, which is the ordinal number of the alternative 655that was actually satisfied (0 for the first, 1 for the second alternative, 656etc.). 657 658For example, suppose there are two opcodes for storing zero, @samp{clrreg} 659for registers and @samp{clrmem} for memory locations. Here is how 660a pattern could use @code{which_alternative} to choose between them: 661 662@smallexample 663(define_insn "" 664 [(set (match_operand:SI 0 "general_operand" "=r,m") 665 (const_int 0))] 666 "" 667 @{ 668 return (which_alternative == 0 669 ? "clrreg %0" : "clrmem %0"); 670 @}) 671@end smallexample 672 673The example above, where the assembler code to generate was 674@emph{solely} determined by the alternative, could also have been specified 675as follows, having the output control string start with a @samp{@@}: 676 677@smallexample 678@group 679(define_insn "" 680 [(set (match_operand:SI 0 "general_operand" "=r,m") 681 (const_int 0))] 682 "" 683 "@@ 684 clrreg %0 685 clrmem %0") 686@end group 687@end smallexample 688 689If you just need a little bit of C code in one (or a few) alternatives, 690you can use @samp{*} inside of a @samp{@@} multi-alternative template: 691 692@smallexample 693@group 694(define_insn "" 695 [(set (match_operand:SI 0 "general_operand" "=r,<,m") 696 (const_int 0))] 697 "" 698 "@@ 699 clrreg %0 700 * return stack_mem_p (operands[0]) ? \"push 0\" : \"clrmem %0\"; 701 clrmem %0") 702@end group 703@end smallexample 704 705@node Predicates 706@section Predicates 707@cindex predicates 708@cindex operand predicates 709@cindex operator predicates 710 711A predicate determines whether a @code{match_operand} or 712@code{match_operator} expression matches, and therefore whether the 713surrounding instruction pattern will be used for that combination of 714operands. GCC has a number of machine-independent predicates, and you 715can define machine-specific predicates as needed. By convention, 716predicates used with @code{match_operand} have names that end in 717@samp{_operand}, and those used with @code{match_operator} have names 718that end in @samp{_operator}. 719 720All predicates are boolean functions (in the mathematical sense) of 721two arguments: the RTL expression that is being considered at that 722position in the instruction pattern, and the machine mode that the 723@code{match_operand} or @code{match_operator} specifies. In this 724section, the first argument is called @var{op} and the second argument 725@var{mode}. Predicates can be called from C as ordinary two-argument 726functions; this can be useful in output templates or other 727machine-specific code. 728 729Operand predicates can allow operands that are not actually acceptable 730to the hardware, as long as the constraints give reload the ability to 731fix them up (@pxref{Constraints}). However, GCC will usually generate 732better code if the predicates specify the requirements of the machine 733instructions as closely as possible. Reload cannot fix up operands 734that must be constants (``immediate operands''); you must use a 735predicate that allows only constants, or else enforce the requirement 736in the extra condition. 737 738@cindex predicates and machine modes 739@cindex normal predicates 740@cindex special predicates 741Most predicates handle their @var{mode} argument in a uniform manner. 742If @var{mode} is @code{VOIDmode} (unspecified), then @var{op} can have 743any mode. If @var{mode} is anything else, then @var{op} must have the 744same mode, unless @var{op} is a @code{CONST_INT} or integer 745@code{CONST_DOUBLE}. These RTL expressions always have 746@code{VOIDmode}, so it would be counterproductive to check that their 747mode matches. Instead, predicates that accept @code{CONST_INT} and/or 748integer @code{CONST_DOUBLE} check that the value stored in the 749constant will fit in the requested mode. 750 751Predicates with this behavior are called @dfn{normal}. 752@command{genrecog} can optimize the instruction recognizer based on 753knowledge of how normal predicates treat modes. It can also diagnose 754certain kinds of common errors in the use of normal predicates; for 755instance, it is almost always an error to use a normal predicate 756without specifying a mode. 757 758Predicates that do something different with their @var{mode} argument 759are called @dfn{special}. The generic predicates 760@code{address_operand} and @code{pmode_register_operand} are special 761predicates. @command{genrecog} does not do any optimizations or 762diagnosis when special predicates are used. 763 764@menu 765* Machine-Independent Predicates:: Predicates available to all back ends. 766* Defining Predicates:: How to write machine-specific predicate 767 functions. 768@end menu 769 770@node Machine-Independent Predicates 771@subsection Machine-Independent Predicates 772@cindex machine-independent predicates 773@cindex generic predicates 774 775These are the generic predicates available to all back ends. They are 776defined in @file{recog.c}. The first category of predicates allow 777only constant, or @dfn{immediate}, operands. 778 779@defun immediate_operand 780This predicate allows any sort of constant that fits in @var{mode}. 781It is an appropriate choice for instructions that take operands that 782must be constant. 783@end defun 784 785@defun const_int_operand 786This predicate allows any @code{CONST_INT} expression that fits in 787@var{mode}. It is an appropriate choice for an immediate operand that 788does not allow a symbol or label. 789@end defun 790 791@defun const_double_operand 792This predicate accepts any @code{CONST_DOUBLE} expression that has 793exactly @var{mode}. If @var{mode} is @code{VOIDmode}, it will also 794accept @code{CONST_INT}. It is intended for immediate floating point 795constants. 796@end defun 797 798@noindent 799The second category of predicates allow only some kind of machine 800register. 801 802@defun register_operand 803This predicate allows any @code{REG} or @code{SUBREG} expression that 804is valid for @var{mode}. It is often suitable for arithmetic 805instruction operands on a RISC machine. 806@end defun 807 808@defun pmode_register_operand 809This is a slight variant on @code{register_operand} which works around 810a limitation in the machine-description reader. 811 812@smallexample 813(match_operand @var{n} "pmode_register_operand" @var{constraint}) 814@end smallexample 815 816@noindent 817means exactly what 818 819@smallexample 820(match_operand:P @var{n} "register_operand" @var{constraint}) 821@end smallexample 822 823@noindent 824would mean, if the machine-description reader accepted @samp{:P} 825mode suffixes. Unfortunately, it cannot, because @code{Pmode} is an 826alias for some other mode, and might vary with machine-specific 827options. @xref{Misc}. 828@end defun 829 830@defun scratch_operand 831This predicate allows hard registers and @code{SCRATCH} expressions, 832but not pseudo-registers. It is used internally by @code{match_scratch}; 833it should not be used directly. 834@end defun 835 836@noindent 837The third category of predicates allow only some kind of memory reference. 838 839@defun memory_operand 840This predicate allows any valid reference to a quantity of mode 841@var{mode} in memory, as determined by the weak form of 842@code{GO_IF_LEGITIMATE_ADDRESS} (@pxref{Addressing Modes}). 843@end defun 844 845@defun address_operand 846This predicate is a little unusual; it allows any operand that is a 847valid expression for the @emph{address} of a quantity of mode 848@var{mode}, again determined by the weak form of 849@code{GO_IF_LEGITIMATE_ADDRESS}. To first order, if 850@samp{@w{(mem:@var{mode} (@var{exp}))}} is acceptable to 851@code{memory_operand}, then @var{exp} is acceptable to 852@code{address_operand}. Note that @var{exp} does not necessarily have 853the mode @var{mode}. 854@end defun 855 856@defun indirect_operand 857This is a stricter form of @code{memory_operand} which allows only 858memory references with a @code{general_operand} as the address 859expression. New uses of this predicate are discouraged, because 860@code{general_operand} is very permissive, so it's hard to tell what 861an @code{indirect_operand} does or does not allow. If a target has 862different requirements for memory operands for different instructions, 863it is better to define target-specific predicates which enforce the 864hardware's requirements explicitly. 865@end defun 866 867@defun push_operand 868This predicate allows a memory reference suitable for pushing a value 869onto the stack. This will be a @code{MEM} which refers to 870@code{stack_pointer_rtx}, with a side effect in its address expression 871(@pxref{Incdec}); which one is determined by the 872@code{STACK_PUSH_CODE} macro (@pxref{Frame Layout}). 873@end defun 874 875@defun pop_operand 876This predicate allows a memory reference suitable for popping a value 877off the stack. Again, this will be a @code{MEM} referring to 878@code{stack_pointer_rtx}, with a side effect in its address 879expression. However, this time @code{STACK_POP_CODE} is expected. 880@end defun 881 882@noindent 883The fourth category of predicates allow some combination of the above 884operands. 885 886@defun nonmemory_operand 887This predicate allows any immediate or register operand valid for @var{mode}. 888@end defun 889 890@defun nonimmediate_operand 891This predicate allows any register or memory operand valid for @var{mode}. 892@end defun 893 894@defun general_operand 895This predicate allows any immediate, register, or memory operand 896valid for @var{mode}. 897@end defun 898 899@noindent 900Finally, there are two generic operator predicates. 901 902@defun comparison_operator 903This predicate matches any expression which performs an arithmetic 904comparison in @var{mode}; that is, @code{COMPARISON_P} is true for the 905expression code. 906@end defun 907 908@defun ordered_comparison_operator 909This predicate matches any expression which performs an arithmetic 910comparison in @var{mode} and whose expression code is valid for integer 911modes; that is, the expression code will be one of @code{eq}, @code{ne}, 912@code{lt}, @code{ltu}, @code{le}, @code{leu}, @code{gt}, @code{gtu}, 913@code{ge}, @code{geu}. 914@end defun 915 916@node Defining Predicates 917@subsection Defining Machine-Specific Predicates 918@cindex defining predicates 919@findex define_predicate 920@findex define_special_predicate 921 922Many machines have requirements for their operands that cannot be 923expressed precisely using the generic predicates. You can define 924additional predicates using @code{define_predicate} and 925@code{define_special_predicate} expressions. These expressions have 926three operands: 927 928@itemize @bullet 929@item 930The name of the predicate, as it will be referred to in 931@code{match_operand} or @code{match_operator} expressions. 932 933@item 934An RTL expression which evaluates to true if the predicate allows the 935operand @var{op}, false if it does not. This expression can only use 936the following RTL codes: 937 938@table @code 939@item MATCH_OPERAND 940When written inside a predicate expression, a @code{MATCH_OPERAND} 941expression evaluates to true if the predicate it names would allow 942@var{op}. The operand number and constraint are ignored. Due to 943limitations in @command{genrecog}, you can only refer to generic 944predicates and predicates that have already been defined. 945 946@item MATCH_CODE 947This expression evaluates to true if @var{op} or a specified 948subexpression of @var{op} has one of a given list of RTX codes. 949 950The first operand of this expression is a string constant containing a 951comma-separated list of RTX code names (in lower case). These are the 952codes for which the @code{MATCH_CODE} will be true. 953 954The second operand is a string constant which indicates what 955subexpression of @var{op} to examine. If it is absent or the empty 956string, @var{op} itself is examined. Otherwise, the string constant 957must be a sequence of digits and/or lowercase letters. Each character 958indicates a subexpression to extract from the current expression; for 959the first character this is @var{op}, for the second and subsequent 960characters it is the result of the previous character. A digit 961@var{n} extracts @samp{@w{XEXP (@var{e}, @var{n})}}; a letter @var{l} 962extracts @samp{@w{XVECEXP (@var{e}, 0, @var{n})}} where @var{n} is the 963alphabetic ordinal of @var{l} (0 for `a', 1 for 'b', and so on). The 964@code{MATCH_CODE} then examines the RTX code of the subexpression 965extracted by the complete string. It is not possible to extract 966components of an @code{rtvec} that is not at position 0 within its RTX 967object. 968 969@item MATCH_TEST 970This expression has one operand, a string constant containing a C 971expression. The predicate's arguments, @var{op} and @var{mode}, are 972available with those names in the C expression. The @code{MATCH_TEST} 973evaluates to true if the C expression evaluates to a nonzero value. 974@code{MATCH_TEST} expressions must not have side effects. 975 976@item AND 977@itemx IOR 978@itemx NOT 979@itemx IF_THEN_ELSE 980The basic @samp{MATCH_} expressions can be combined using these 981logical operators, which have the semantics of the C operators 982@samp{&&}, @samp{||}, @samp{!}, and @samp{@w{? :}} respectively. As 983in Common Lisp, you may give an @code{AND} or @code{IOR} expression an 984arbitrary number of arguments; this has exactly the same effect as 985writing a chain of two-argument @code{AND} or @code{IOR} expressions. 986@end table 987 988@item 989An optional block of C code, which should execute 990@samp{@w{return true}} if the predicate is found to match and 991@samp{@w{return false}} if it does not. It must not have any side 992effects. The predicate arguments, @var{op} and @var{mode}, are 993available with those names. 994 995If a code block is present in a predicate definition, then the RTL 996expression must evaluate to true @emph{and} the code block must 997execute @samp{@w{return true}} for the predicate to allow the operand. 998The RTL expression is evaluated first; do not re-check anything in the 999code block that was checked in the RTL expression. 1000@end itemize 1001 1002The program @command{genrecog} scans @code{define_predicate} and 1003@code{define_special_predicate} expressions to determine which RTX 1004codes are possibly allowed. You should always make this explicit in 1005the RTL predicate expression, using @code{MATCH_OPERAND} and 1006@code{MATCH_CODE}. 1007 1008Here is an example of a simple predicate definition, from the IA64 1009machine description: 1010 1011@smallexample 1012@group 1013;; @r{True if @var{op} is a @code{SYMBOL_REF} which refers to the sdata section.} 1014(define_predicate "small_addr_symbolic_operand" 1015 (and (match_code "symbol_ref") 1016 (match_test "SYMBOL_REF_SMALL_ADDR_P (op)"))) 1017@end group 1018@end smallexample 1019 1020@noindent 1021And here is another, showing the use of the C block. 1022 1023@smallexample 1024@group 1025;; @r{True if @var{op} is a register operand that is (or could be) a GR reg.} 1026(define_predicate "gr_register_operand" 1027 (match_operand 0 "register_operand") 1028@{ 1029 unsigned int regno; 1030 if (GET_CODE (op) == SUBREG) 1031 op = SUBREG_REG (op); 1032 1033 regno = REGNO (op); 1034 return (regno >= FIRST_PSEUDO_REGISTER || GENERAL_REGNO_P (regno)); 1035@}) 1036@end group 1037@end smallexample 1038 1039Predicates written with @code{define_predicate} automatically include 1040a test that @var{mode} is @code{VOIDmode}, or @var{op} has the same 1041mode as @var{mode}, or @var{op} is a @code{CONST_INT} or 1042@code{CONST_DOUBLE}. They do @emph{not} check specifically for 1043integer @code{CONST_DOUBLE}, nor do they test that the value of either 1044kind of constant fits in the requested mode. This is because 1045target-specific predicates that take constants usually have to do more 1046stringent value checks anyway. If you need the exact same treatment 1047of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic predicates 1048provide, use a @code{MATCH_OPERAND} subexpression to call 1049@code{const_int_operand}, @code{const_double_operand}, or 1050@code{immediate_operand}. 1051 1052Predicates written with @code{define_special_predicate} do not get any 1053automatic mode checks, and are treated as having special mode handling 1054by @command{genrecog}. 1055 1056The program @command{genpreds} is responsible for generating code to 1057test predicates. It also writes a header file containing function 1058declarations for all machine-specific predicates. It is not necessary 1059to declare these predicates in @file{@var{cpu}-protos.h}. 1060@end ifset 1061 1062@c Most of this node appears by itself (in a different place) even 1063@c when the INTERNALS flag is clear. Passages that require the internals 1064@c manual's context are conditionalized to appear only in the internals manual. 1065@ifset INTERNALS 1066@node Constraints 1067@section Operand Constraints 1068@cindex operand constraints 1069@cindex constraints 1070 1071Each @code{match_operand} in an instruction pattern can specify 1072constraints for the operands allowed. The constraints allow you to 1073fine-tune matching within the set of operands allowed by the 1074predicate. 1075 1076@end ifset 1077@ifclear INTERNALS 1078@node Constraints 1079@section Constraints for @code{asm} Operands 1080@cindex operand constraints, @code{asm} 1081@cindex constraints, @code{asm} 1082@cindex @code{asm} constraints 1083 1084Here are specific details on what constraint letters you can use with 1085@code{asm} operands. 1086@end ifclear 1087Constraints can say whether 1088an operand may be in a register, and which kinds of register; whether the 1089operand can be a memory reference, and which kinds of address; whether the 1090operand may be an immediate constant, and which possible values it may 1091have. Constraints can also require two operands to match. 1092Side-effects aren't allowed in operands of inline @code{asm}, unless 1093@samp{<} or @samp{>} constraints are used, because there is no guarantee 1094that the side effects will happen exactly once in an instruction that can update 1095the addressing register. 1096 1097@ifset INTERNALS 1098@menu 1099* Simple Constraints:: Basic use of constraints. 1100* Multi-Alternative:: When an insn has two alternative constraint-patterns. 1101* Class Preferences:: Constraints guide which hard register to put things in. 1102* Modifiers:: More precise control over effects of constraints. 1103* Machine Constraints:: Existing constraints for some particular machines. 1104* Disable Insn Alternatives:: Disable insn alternatives using attributes. 1105* Define Constraints:: How to define machine-specific constraints. 1106* C Constraint Interface:: How to test constraints from C code. 1107@end menu 1108@end ifset 1109 1110@ifclear INTERNALS 1111@menu 1112* Simple Constraints:: Basic use of constraints. 1113* Multi-Alternative:: When an insn has two alternative constraint-patterns. 1114* Modifiers:: More precise control over effects of constraints. 1115* Machine Constraints:: Special constraints for some particular machines. 1116@end menu 1117@end ifclear 1118 1119@node Simple Constraints 1120@subsection Simple Constraints 1121@cindex simple constraints 1122 1123The simplest kind of constraint is a string full of letters, each of 1124which describes one kind of operand that is permitted. Here are 1125the letters that are allowed: 1126 1127@table @asis 1128@item whitespace 1129Whitespace characters are ignored and can be inserted at any position 1130except the first. This enables each alternative for different operands to 1131be visually aligned in the machine description even if they have different 1132number of constraints and modifiers. 1133 1134@cindex @samp{m} in constraint 1135@cindex memory references in constraints 1136@item @samp{m} 1137A memory operand is allowed, with any kind of address that the machine 1138supports in general. 1139Note that the letter used for the general memory constraint can be 1140re-defined by a back end using the @code{TARGET_MEM_CONSTRAINT} macro. 1141 1142@cindex offsettable address 1143@cindex @samp{o} in constraint 1144@item @samp{o} 1145A memory operand is allowed, but only if the address is 1146@dfn{offsettable}. This means that adding a small integer (actually, 1147the width in bytes of the operand, as determined by its machine mode) 1148may be added to the address and the result is also a valid memory 1149address. 1150 1151@cindex autoincrement/decrement addressing 1152For example, an address which is constant is offsettable; so is an 1153address that is the sum of a register and a constant (as long as a 1154slightly larger constant is also within the range of address-offsets 1155supported by the machine); but an autoincrement or autodecrement 1156address is not offsettable. More complicated indirect/indexed 1157addresses may or may not be offsettable depending on the other 1158addressing modes that the machine supports. 1159 1160Note that in an output operand which can be matched by another 1161operand, the constraint letter @samp{o} is valid only when accompanied 1162by both @samp{<} (if the target machine has predecrement addressing) 1163and @samp{>} (if the target machine has preincrement addressing). 1164 1165@cindex @samp{V} in constraint 1166@item @samp{V} 1167A memory operand that is not offsettable. In other words, anything that 1168would fit the @samp{m} constraint but not the @samp{o} constraint. 1169 1170@cindex @samp{<} in constraint 1171@item @samp{<} 1172A memory operand with autodecrement addressing (either predecrement or 1173postdecrement) is allowed. In inline @code{asm} this constraint is only 1174allowed if the operand is used exactly once in an instruction that can 1175handle the side effects. Not using an operand with @samp{<} in constraint 1176string in the inline @code{asm} pattern at all or using it in multiple 1177instructions isn't valid, because the side effects wouldn't be performed 1178or would be performed more than once. Furthermore, on some targets 1179the operand with @samp{<} in constraint string must be accompanied by 1180special instruction suffixes like @code{%U0} instruction suffix on PowerPC 1181or @code{%P0} on IA-64. 1182 1183@cindex @samp{>} in constraint 1184@item @samp{>} 1185A memory operand with autoincrement addressing (either preincrement or 1186postincrement) is allowed. In inline @code{asm} the same restrictions 1187as for @samp{<} apply. 1188 1189@cindex @samp{r} in constraint 1190@cindex registers in constraints 1191@item @samp{r} 1192A register operand is allowed provided that it is in a general 1193register. 1194 1195@cindex constants in constraints 1196@cindex @samp{i} in constraint 1197@item @samp{i} 1198An immediate integer operand (one with constant value) is allowed. 1199This includes symbolic constants whose values will be known only at 1200assembly time or later. 1201 1202@cindex @samp{n} in constraint 1203@item @samp{n} 1204An immediate integer operand with a known numeric value is allowed. 1205Many systems cannot support assembly-time constants for operands less 1206than a word wide. Constraints for these operands should use @samp{n} 1207rather than @samp{i}. 1208 1209@cindex @samp{I} in constraint 1210@item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P} 1211Other letters in the range @samp{I} through @samp{P} may be defined in 1212a machine-dependent fashion to permit immediate integer operands with 1213explicit integer values in specified ranges. For example, on the 121468000, @samp{I} is defined to stand for the range of values 1 to 8. 1215This is the range permitted as a shift count in the shift 1216instructions. 1217 1218@cindex @samp{E} in constraint 1219@item @samp{E} 1220An immediate floating operand (expression code @code{const_double}) is 1221allowed, but only if the target floating point format is the same as 1222that of the host machine (on which the compiler is running). 1223 1224@cindex @samp{F} in constraint 1225@item @samp{F} 1226An immediate floating operand (expression code @code{const_double} or 1227@code{const_vector}) is allowed. 1228 1229@cindex @samp{G} in constraint 1230@cindex @samp{H} in constraint 1231@item @samp{G}, @samp{H} 1232@samp{G} and @samp{H} may be defined in a machine-dependent fashion to 1233permit immediate floating operands in particular ranges of values. 1234 1235@cindex @samp{s} in constraint 1236@item @samp{s} 1237An immediate integer operand whose value is not an explicit integer is 1238allowed. 1239 1240This might appear strange; if an insn allows a constant operand with a 1241value not known at compile time, it certainly must allow any known 1242value. So why use @samp{s} instead of @samp{i}? Sometimes it allows 1243better code to be generated. 1244 1245For example, on the 68000 in a fullword instruction it is possible to 1246use an immediate operand; but if the immediate value is between @minus{}128 1247and 127, better code results from loading the value into a register and 1248using the register. This is because the load into the register can be 1249done with a @samp{moveq} instruction. We arrange for this to happen 1250by defining the letter @samp{K} to mean ``any integer outside the 1251range @minus{}128 to 127'', and then specifying @samp{Ks} in the operand 1252constraints. 1253 1254@cindex @samp{g} in constraint 1255@item @samp{g} 1256Any register, memory or immediate integer operand is allowed, except for 1257registers that are not general registers. 1258 1259@cindex @samp{X} in constraint 1260@item @samp{X} 1261@ifset INTERNALS 1262Any operand whatsoever is allowed, even if it does not satisfy 1263@code{general_operand}. This is normally used in the constraint of 1264a @code{match_scratch} when certain alternatives will not actually 1265require a scratch register. 1266@end ifset 1267@ifclear INTERNALS 1268Any operand whatsoever is allowed. 1269@end ifclear 1270 1271@cindex @samp{0} in constraint 1272@cindex digits in constraint 1273@item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{9} 1274An operand that matches the specified operand number is allowed. If a 1275digit is used together with letters within the same alternative, the 1276digit should come last. 1277 1278This number is allowed to be more than a single digit. If multiple 1279digits are encountered consecutively, they are interpreted as a single 1280decimal integer. There is scant chance for ambiguity, since to-date 1281it has never been desirable that @samp{10} be interpreted as matching 1282either operand 1 @emph{or} operand 0. Should this be desired, one 1283can use multiple alternatives instead. 1284 1285@cindex matching constraint 1286@cindex constraint, matching 1287This is called a @dfn{matching constraint} and what it really means is 1288that the assembler has only a single operand that fills two roles 1289@ifset INTERNALS 1290considered separate in the RTL insn. For example, an add insn has two 1291input operands and one output operand in the RTL, but on most CISC 1292@end ifset 1293@ifclear INTERNALS 1294which @code{asm} distinguishes. For example, an add instruction uses 1295two input operands and an output operand, but on most CISC 1296@end ifclear 1297machines an add instruction really has only two operands, one of them an 1298input-output operand: 1299 1300@smallexample 1301addl #35,r12 1302@end smallexample 1303 1304Matching constraints are used in these circumstances. 1305More precisely, the two operands that match must include one input-only 1306operand and one output-only operand. Moreover, the digit must be a 1307smaller number than the number of the operand that uses it in the 1308constraint. 1309 1310@ifset INTERNALS 1311For operands to match in a particular case usually means that they 1312are identical-looking RTL expressions. But in a few special cases 1313specific kinds of dissimilarity are allowed. For example, @code{*x} 1314as an input operand will match @code{*x++} as an output operand. 1315For proper results in such cases, the output template should always 1316use the output-operand's number when printing the operand. 1317@end ifset 1318 1319@cindex load address instruction 1320@cindex push address instruction 1321@cindex address constraints 1322@cindex @samp{p} in constraint 1323@item @samp{p} 1324An operand that is a valid memory address is allowed. This is 1325for ``load address'' and ``push address'' instructions. 1326 1327@findex address_operand 1328@samp{p} in the constraint must be accompanied by @code{address_operand} 1329as the predicate in the @code{match_operand}. This predicate interprets 1330the mode specified in the @code{match_operand} as the mode of the memory 1331reference for which the address would be valid. 1332 1333@cindex other register constraints 1334@cindex extensible constraints 1335@item @var{other-letters} 1336Other letters can be defined in machine-dependent fashion to stand for 1337particular classes of registers or other arbitrary operand types. 1338@samp{d}, @samp{a} and @samp{f} are defined on the 68000/68020 to stand 1339for data, address and floating point registers. 1340@end table 1341 1342@ifset INTERNALS 1343In order to have valid assembler code, each operand must satisfy 1344its constraint. But a failure to do so does not prevent the pattern 1345from applying to an insn. Instead, it directs the compiler to modify 1346the code so that the constraint will be satisfied. Usually this is 1347done by copying an operand into a register. 1348 1349Contrast, therefore, the two instruction patterns that follow: 1350 1351@smallexample 1352(define_insn "" 1353 [(set (match_operand:SI 0 "general_operand" "=r") 1354 (plus:SI (match_dup 0) 1355 (match_operand:SI 1 "general_operand" "r")))] 1356 "" 1357 "@dots{}") 1358@end smallexample 1359 1360@noindent 1361which has two operands, one of which must appear in two places, and 1362 1363@smallexample 1364(define_insn "" 1365 [(set (match_operand:SI 0 "general_operand" "=r") 1366 (plus:SI (match_operand:SI 1 "general_operand" "0") 1367 (match_operand:SI 2 "general_operand" "r")))] 1368 "" 1369 "@dots{}") 1370@end smallexample 1371 1372@noindent 1373which has three operands, two of which are required by a constraint to be 1374identical. If we are considering an insn of the form 1375 1376@smallexample 1377(insn @var{n} @var{prev} @var{next} 1378 (set (reg:SI 3) 1379 (plus:SI (reg:SI 6) (reg:SI 109))) 1380 @dots{}) 1381@end smallexample 1382 1383@noindent 1384the first pattern would not apply at all, because this insn does not 1385contain two identical subexpressions in the right place. The pattern would 1386say, ``That does not look like an add instruction; try other patterns''. 1387The second pattern would say, ``Yes, that's an add instruction, but there 1388is something wrong with it''. It would direct the reload pass of the 1389compiler to generate additional insns to make the constraint true. The 1390results might look like this: 1391 1392@smallexample 1393(insn @var{n2} @var{prev} @var{n} 1394 (set (reg:SI 3) (reg:SI 6)) 1395 @dots{}) 1396 1397(insn @var{n} @var{n2} @var{next} 1398 (set (reg:SI 3) 1399 (plus:SI (reg:SI 3) (reg:SI 109))) 1400 @dots{}) 1401@end smallexample 1402 1403It is up to you to make sure that each operand, in each pattern, has 1404constraints that can handle any RTL expression that could be present for 1405that operand. (When multiple alternatives are in use, each pattern must, 1406for each possible combination of operand expressions, have at least one 1407alternative which can handle that combination of operands.) The 1408constraints don't need to @emph{allow} any possible operand---when this is 1409the case, they do not constrain---but they must at least point the way to 1410reloading any possible operand so that it will fit. 1411 1412@itemize @bullet 1413@item 1414If the constraint accepts whatever operands the predicate permits, 1415there is no problem: reloading is never necessary for this operand. 1416 1417For example, an operand whose constraints permit everything except 1418registers is safe provided its predicate rejects registers. 1419 1420An operand whose predicate accepts only constant values is safe 1421provided its constraints include the letter @samp{i}. If any possible 1422constant value is accepted, then nothing less than @samp{i} will do; 1423if the predicate is more selective, then the constraints may also be 1424more selective. 1425 1426@item 1427Any operand expression can be reloaded by copying it into a register. 1428So if an operand's constraints allow some kind of register, it is 1429certain to be safe. It need not permit all classes of registers; the 1430compiler knows how to copy a register into another register of the 1431proper class in order to make an instruction valid. 1432 1433@cindex nonoffsettable memory reference 1434@cindex memory reference, nonoffsettable 1435@item 1436A nonoffsettable memory reference can be reloaded by copying the 1437address into a register. So if the constraint uses the letter 1438@samp{o}, all memory references are taken care of. 1439 1440@item 1441A constant operand can be reloaded by allocating space in memory to 1442hold it as preinitialized data. Then the memory reference can be used 1443in place of the constant. So if the constraint uses the letters 1444@samp{o} or @samp{m}, constant operands are not a problem. 1445 1446@item 1447If the constraint permits a constant and a pseudo register used in an insn 1448was not allocated to a hard register and is equivalent to a constant, 1449the register will be replaced with the constant. If the predicate does 1450not permit a constant and the insn is re-recognized for some reason, the 1451compiler will crash. Thus the predicate must always recognize any 1452objects allowed by the constraint. 1453@end itemize 1454 1455If the operand's predicate can recognize registers, but the constraint does 1456not permit them, it can make the compiler crash. When this operand happens 1457to be a register, the reload pass will be stymied, because it does not know 1458how to copy a register temporarily into memory. 1459 1460If the predicate accepts a unary operator, the constraint applies to the 1461operand. For example, the MIPS processor at ISA level 3 supports an 1462instruction which adds two registers in @code{SImode} to produce a 1463@code{DImode} result, but only if the registers are correctly sign 1464extended. This predicate for the input operands accepts a 1465@code{sign_extend} of an @code{SImode} register. Write the constraint 1466to indicate the type of register that is required for the operand of the 1467@code{sign_extend}. 1468@end ifset 1469 1470@node Multi-Alternative 1471@subsection Multiple Alternative Constraints 1472@cindex multiple alternative constraints 1473 1474Sometimes a single instruction has multiple alternative sets of possible 1475operands. For example, on the 68000, a logical-or instruction can combine 1476register or an immediate value into memory, or it can combine any kind of 1477operand into a register; but it cannot combine one memory location into 1478another. 1479 1480These constraints are represented as multiple alternatives. An alternative 1481can be described by a series of letters for each operand. The overall 1482constraint for an operand is made from the letters for this operand 1483from the first alternative, a comma, the letters for this operand from 1484the second alternative, a comma, and so on until the last alternative. 1485All operands for a single instruction must have the same number of 1486alternatives. 1487@ifset INTERNALS 1488Here is how it is done for fullword logical-or on the 68000: 1489 1490@smallexample 1491(define_insn "iorsi3" 1492 [(set (match_operand:SI 0 "general_operand" "=m,d") 1493 (ior:SI (match_operand:SI 1 "general_operand" "%0,0") 1494 (match_operand:SI 2 "general_operand" "dKs,dmKs")))] 1495 @dots{}) 1496@end smallexample 1497 1498The first alternative has @samp{m} (memory) for operand 0, @samp{0} for 1499operand 1 (meaning it must match operand 0), and @samp{dKs} for operand 15002. The second alternative has @samp{d} (data register) for operand 0, 1501@samp{0} for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and 1502@samp{%} in the constraints apply to all the alternatives; their 1503meaning is explained in the next section (@pxref{Class Preferences}). 1504 1505If all the operands fit any one alternative, the instruction is valid. 1506Otherwise, for each alternative, the compiler counts how many instructions 1507must be added to copy the operands so that that alternative applies. 1508The alternative requiring the least copying is chosen. If two alternatives 1509need the same amount of copying, the one that comes first is chosen. 1510These choices can be altered with the @samp{?} and @samp{!} characters: 1511 1512@table @code 1513@cindex @samp{?} in constraint 1514@cindex question mark 1515@item ? 1516Disparage slightly the alternative that the @samp{?} appears in, 1517as a choice when no alternative applies exactly. The compiler regards 1518this alternative as one unit more costly for each @samp{?} that appears 1519in it. 1520 1521@cindex @samp{!} in constraint 1522@cindex exclamation point 1523@item ! 1524Disparage severely the alternative that the @samp{!} appears in. 1525This alternative can still be used if it fits without reloading, 1526but if reloading is needed, some other alternative will be used. 1527 1528@cindex @samp{^} in constraint 1529@cindex caret 1530@item ^ 1531This constraint is analogous to @samp{?} but it disparages slightly 1532the alternative only if the operand with the @samp{^} needs a reload. 1533 1534@cindex @samp{$} in constraint 1535@cindex dollar sign 1536@item $ 1537This constraint is analogous to @samp{!} but it disparages severely 1538the alternative only if the operand with the @samp{$} needs a reload. 1539@end table 1540 1541When an insn pattern has multiple alternatives in its constraints, often 1542the appearance of the assembler code is determined mostly by which 1543alternative was matched. When this is so, the C code for writing the 1544assembler code can use the variable @code{which_alternative}, which is 1545the ordinal number of the alternative that was actually satisfied (0 for 1546the first, 1 for the second alternative, etc.). @xref{Output Statement}. 1547@end ifset 1548@ifclear INTERNALS 1549 1550So the first alternative for the 68000's logical-or could be written as 1551@code{"+m" (output) : "ir" (input)}. The second could be @code{"+r" 1552(output): "irm" (input)}. However, the fact that two memory locations 1553cannot be used in a single instruction prevents simply using @code{"+rm" 1554(output) : "irm" (input)}. Using multi-alternatives, this might be 1555written as @code{"+m,r" (output) : "ir,irm" (input)}. This describes 1556all the available alternatives to the compiler, allowing it to choose 1557the most efficient one for the current conditions. 1558 1559There is no way within the template to determine which alternative was 1560chosen. However you may be able to wrap your @code{asm} statements with 1561builtins such as @code{__builtin_constant_p} to achieve the desired results. 1562@end ifclear 1563 1564@ifset INTERNALS 1565@node Class Preferences 1566@subsection Register Class Preferences 1567@cindex class preference constraints 1568@cindex register class preference constraints 1569 1570@cindex voting between constraint alternatives 1571The operand constraints have another function: they enable the compiler 1572to decide which kind of hardware register a pseudo register is best 1573allocated to. The compiler examines the constraints that apply to the 1574insns that use the pseudo register, looking for the machine-dependent 1575letters such as @samp{d} and @samp{a} that specify classes of registers. 1576The pseudo register is put in whichever class gets the most ``votes''. 1577The constraint letters @samp{g} and @samp{r} also vote: they vote in 1578favor of a general register. The machine description says which registers 1579are considered general. 1580 1581Of course, on some machines all registers are equivalent, and no register 1582classes are defined. Then none of this complexity is relevant. 1583@end ifset 1584 1585@node Modifiers 1586@subsection Constraint Modifier Characters 1587@cindex modifiers in constraints 1588@cindex constraint modifier characters 1589 1590@c prevent bad page break with this line 1591Here are constraint modifier characters. 1592 1593@table @samp 1594@cindex @samp{=} in constraint 1595@item = 1596Means that this operand is written to by this instruction: 1597the previous value is discarded and replaced by new data. 1598 1599@cindex @samp{+} in constraint 1600@item + 1601Means that this operand is both read and written by the instruction. 1602 1603When the compiler fixes up the operands to satisfy the constraints, 1604it needs to know which operands are read by the instruction and 1605which are written by it. @samp{=} identifies an operand which is only 1606written; @samp{+} identifies an operand that is both read and written; all 1607other operands are assumed to only be read. 1608 1609If you specify @samp{=} or @samp{+} in a constraint, you put it in the 1610first character of the constraint string. 1611 1612@cindex @samp{&} in constraint 1613@cindex earlyclobber operand 1614@item & 1615Means (in a particular alternative) that this operand is an 1616@dfn{earlyclobber} operand, which is written before the instruction is 1617finished using the input operands. Therefore, this operand may not lie 1618in a register that is read by the instruction or as part of any memory 1619address. 1620 1621@samp{&} applies only to the alternative in which it is written. In 1622constraints with multiple alternatives, sometimes one alternative 1623requires @samp{&} while others do not. See, for example, the 1624@samp{movdf} insn of the 68000. 1625 1626A operand which is read by the instruction can be tied to an earlyclobber 1627operand if its only use as an input occurs before the early result is 1628written. Adding alternatives of this form often allows GCC to produce 1629better code when only some of the read operands can be affected by the 1630earlyclobber. See, for example, the @samp{mulsi3} insn of the ARM@. 1631 1632Furthermore, if the @dfn{earlyclobber} operand is also a read/write 1633operand, then that operand is written only after it's used. 1634 1635@samp{&} does not obviate the need to write @samp{=} or @samp{+}. As 1636@dfn{earlyclobber} operands are always written, a read-only 1637@dfn{earlyclobber} operand is ill-formed and will be rejected by the 1638compiler. 1639 1640@cindex @samp{%} in constraint 1641@item % 1642Declares the instruction to be commutative for this operand and the 1643following operand. This means that the compiler may interchange the 1644two operands if that is the cheapest way to make all operands fit the 1645constraints. @samp{%} applies to all alternatives and must appear as 1646the first character in the constraint. Only read-only operands can use 1647@samp{%}. 1648 1649@ifset INTERNALS 1650This is often used in patterns for addition instructions 1651that really have only two operands: the result must go in one of the 1652arguments. Here for example, is how the 68000 halfword-add 1653instruction is defined: 1654 1655@smallexample 1656(define_insn "addhi3" 1657 [(set (match_operand:HI 0 "general_operand" "=m,r") 1658 (plus:HI (match_operand:HI 1 "general_operand" "%0,0") 1659 (match_operand:HI 2 "general_operand" "di,g")))] 1660 @dots{}) 1661@end smallexample 1662@end ifset 1663GCC can only handle one commutative pair in an asm; if you use more, 1664the compiler may fail. Note that you need not use the modifier if 1665the two alternatives are strictly identical; this would only waste 1666time in the reload pass. 1667@ifset INTERNALS 1668The modifier is not operational after 1669register allocation, so the result of @code{define_peephole2} 1670and @code{define_split}s performed after reload cannot rely on 1671@samp{%} to make the intended insn match. 1672 1673@cindex @samp{#} in constraint 1674@item # 1675Says that all following characters, up to the next comma, are to be 1676ignored as a constraint. They are significant only for choosing 1677register preferences. 1678 1679@cindex @samp{*} in constraint 1680@item * 1681Says that the following character should be ignored when choosing 1682register preferences. @samp{*} has no effect on the meaning of the 1683constraint as a constraint, and no effect on reloading. For LRA 1684@samp{*} additionally disparages slightly the alternative if the 1685following character matches the operand. 1686 1687Here is an example: the 68000 has an instruction to sign-extend a 1688halfword in a data register, and can also sign-extend a value by 1689copying it into an address register. While either kind of register is 1690acceptable, the constraints on an address-register destination are 1691less strict, so it is best if register allocation makes an address 1692register its goal. Therefore, @samp{*} is used so that the @samp{d} 1693constraint letter (for data register) is ignored when computing 1694register preferences. 1695 1696@smallexample 1697(define_insn "extendhisi2" 1698 [(set (match_operand:SI 0 "general_operand" "=*d,a") 1699 (sign_extend:SI 1700 (match_operand:HI 1 "general_operand" "0,g")))] 1701 @dots{}) 1702@end smallexample 1703@end ifset 1704@end table 1705 1706@node Machine Constraints 1707@subsection Constraints for Particular Machines 1708@cindex machine specific constraints 1709@cindex constraints, machine specific 1710 1711Whenever possible, you should use the general-purpose constraint letters 1712in @code{asm} arguments, since they will convey meaning more readily to 1713people reading your code. Failing that, use the constraint letters 1714that usually have very similar meanings across architectures. The most 1715commonly used constraints are @samp{m} and @samp{r} (for memory and 1716general-purpose registers respectively; @pxref{Simple Constraints}), and 1717@samp{I}, usually the letter indicating the most common 1718immediate-constant format. 1719 1720Each architecture defines additional constraints. These constraints 1721are used by the compiler itself for instruction generation, as well as 1722for @code{asm} statements; therefore, some of the constraints are not 1723particularly useful for @code{asm}. Here is a summary of some of the 1724machine-dependent constraints available on some particular machines; 1725it includes both constraints that are useful for @code{asm} and 1726constraints that aren't. The compiler source file mentioned in the 1727table heading for each architecture is the definitive reference for 1728the meanings of that architecture's constraints. 1729 1730@c Please keep this table alphabetized by target! 1731@table @emph 1732@item AArch64 family---@file{config/aarch64/constraints.md} 1733@table @code 1734@item k 1735The stack pointer register (@code{SP}) 1736 1737@item w 1738Floating point register, Advanced SIMD vector register or SVE vector register 1739 1740@item Upl 1741One of the low eight SVE predicate registers (@code{P0} to @code{P7}) 1742 1743@item Upa 1744Any of the SVE predicate registers (@code{P0} to @code{P15}) 1745 1746@item I 1747Integer constant that is valid as an immediate operand in an @code{ADD} 1748instruction 1749 1750@item J 1751Integer constant that is valid as an immediate operand in a @code{SUB} 1752instruction (once negated) 1753 1754@item K 1755Integer constant that can be used with a 32-bit logical instruction 1756 1757@item L 1758Integer constant that can be used with a 64-bit logical instruction 1759 1760@item M 1761Integer constant that is valid as an immediate operand in a 32-bit @code{MOV} 1762pseudo instruction. The @code{MOV} may be assembled to one of several different 1763machine instructions depending on the value 1764 1765@item N 1766Integer constant that is valid as an immediate operand in a 64-bit @code{MOV} 1767pseudo instruction 1768 1769@item S 1770An absolute symbolic address or a label reference 1771 1772@item Y 1773Floating point constant zero 1774 1775@item Z 1776Integer constant zero 1777 1778@item Ush 1779The high part (bits 12 and upwards) of the pc-relative address of a symbol 1780within 4GB of the instruction 1781 1782@item Q 1783A memory address which uses a single base register with no offset 1784 1785@item Ump 1786A memory address suitable for a load/store pair instruction in SI, DI, SF and 1787DF modes 1788 1789@end table 1790 1791 1792@item ARC ---@file{config/arc/constraints.md} 1793@table @code 1794@item q 1795Registers usable in ARCompact 16-bit instructions: @code{r0}-@code{r3}, 1796@code{r12}-@code{r15}. This constraint can only match when the @option{-mq} 1797option is in effect. 1798 1799@item e 1800Registers usable as base-regs of memory addresses in ARCompact 16-bit memory 1801instructions: @code{r0}-@code{r3}, @code{r12}-@code{r15}, @code{sp}. 1802This constraint can only match when the @option{-mq} 1803option is in effect. 1804@item D 1805ARC FPX (dpfp) 64-bit registers. @code{D0}, @code{D1}. 1806 1807@item I 1808A signed 12-bit integer constant. 1809 1810@item Cal 1811constant for arithmetic/logical operations. This might be any constant 1812that can be put into a long immediate by the assmbler or linker without 1813involving a PIC relocation. 1814 1815@item K 1816A 3-bit unsigned integer constant. 1817 1818@item L 1819A 6-bit unsigned integer constant. 1820 1821@item CnL 1822One's complement of a 6-bit unsigned integer constant. 1823 1824@item CmL 1825Two's complement of a 6-bit unsigned integer constant. 1826 1827@item M 1828A 5-bit unsigned integer constant. 1829 1830@item O 1831A 7-bit unsigned integer constant. 1832 1833@item P 1834A 8-bit unsigned integer constant. 1835 1836@item H 1837Any const_double value. 1838@end table 1839 1840@item ARM family---@file{config/arm/constraints.md} 1841@table @code 1842 1843@item h 1844In Thumb state, the core registers @code{r8}-@code{r15}. 1845 1846@item k 1847The stack pointer register. 1848 1849@item l 1850In Thumb State the core registers @code{r0}-@code{r7}. In ARM state this 1851is an alias for the @code{r} constraint. 1852 1853@item t 1854VFP floating-point registers @code{s0}-@code{s31}. Used for 32 bit values. 1855 1856@item w 1857VFP floating-point registers @code{d0}-@code{d31} and the appropriate 1858subset @code{d0}-@code{d15} based on command line options. 1859Used for 64 bit values only. Not valid for Thumb1. 1860 1861@item y 1862The iWMMX co-processor registers. 1863 1864@item z 1865The iWMMX GR registers. 1866 1867@item G 1868The floating-point constant 0.0 1869 1870@item I 1871Integer that is valid as an immediate operand in a data processing 1872instruction. That is, an integer in the range 0 to 255 rotated by a 1873multiple of 2 1874 1875@item J 1876Integer in the range @minus{}4095 to 4095 1877 1878@item K 1879Integer that satisfies constraint @samp{I} when inverted (ones complement) 1880 1881@item L 1882Integer that satisfies constraint @samp{I} when negated (twos complement) 1883 1884@item M 1885Integer in the range 0 to 32 1886 1887@item Q 1888A memory reference where the exact address is in a single register 1889(`@samp{m}' is preferable for @code{asm} statements) 1890 1891@item R 1892An item in the constant pool 1893 1894@item S 1895A symbol in the text segment of the current file 1896 1897@item Uv 1898A memory reference suitable for VFP load/store insns (reg+constant offset) 1899 1900@item Uy 1901A memory reference suitable for iWMMXt load/store instructions. 1902 1903@item Uq 1904A memory reference suitable for the ARMv4 ldrsb instruction. 1905@end table 1906 1907@item AVR family---@file{config/avr/constraints.md} 1908@table @code 1909@item l 1910Registers from r0 to r15 1911 1912@item a 1913Registers from r16 to r23 1914 1915@item d 1916Registers from r16 to r31 1917 1918@item w 1919Registers from r24 to r31. These registers can be used in @samp{adiw} command 1920 1921@item e 1922Pointer register (r26--r31) 1923 1924@item b 1925Base pointer register (r28--r31) 1926 1927@item q 1928Stack pointer register (SPH:SPL) 1929 1930@item t 1931Temporary register r0 1932 1933@item x 1934Register pair X (r27:r26) 1935 1936@item y 1937Register pair Y (r29:r28) 1938 1939@item z 1940Register pair Z (r31:r30) 1941 1942@item I 1943Constant greater than @minus{}1, less than 64 1944 1945@item J 1946Constant greater than @minus{}64, less than 1 1947 1948@item K 1949Constant integer 2 1950 1951@item L 1952Constant integer 0 1953 1954@item M 1955Constant that fits in 8 bits 1956 1957@item N 1958Constant integer @minus{}1 1959 1960@item O 1961Constant integer 8, 16, or 24 1962 1963@item P 1964Constant integer 1 1965 1966@item G 1967A floating point constant 0.0 1968 1969@item Q 1970A memory address based on Y or Z pointer with displacement. 1971@end table 1972 1973@item Blackfin family---@file{config/bfin/constraints.md} 1974@table @code 1975@item a 1976P register 1977 1978@item d 1979D register 1980 1981@item z 1982A call clobbered P register. 1983 1984@item q@var{n} 1985A single register. If @var{n} is in the range 0 to 7, the corresponding D 1986register. If it is @code{A}, then the register P0. 1987 1988@item D 1989Even-numbered D register 1990 1991@item W 1992Odd-numbered D register 1993 1994@item e 1995Accumulator register. 1996 1997@item A 1998Even-numbered accumulator register. 1999 2000@item B 2001Odd-numbered accumulator register. 2002 2003@item b 2004I register 2005 2006@item v 2007B register 2008 2009@item f 2010M register 2011 2012@item c 2013Registers used for circular buffering, i.e. I, B, or L registers. 2014 2015@item C 2016The CC register. 2017 2018@item t 2019LT0 or LT1. 2020 2021@item k 2022LC0 or LC1. 2023 2024@item u 2025LB0 or LB1. 2026 2027@item x 2028Any D, P, B, M, I or L register. 2029 2030@item y 2031Additional registers typically used only in prologues and epilogues: RETS, 2032RETN, RETI, RETX, RETE, ASTAT, SEQSTAT and USP. 2033 2034@item w 2035Any register except accumulators or CC. 2036 2037@item Ksh 2038Signed 16 bit integer (in the range @minus{}32768 to 32767) 2039 2040@item Kuh 2041Unsigned 16 bit integer (in the range 0 to 65535) 2042 2043@item Ks7 2044Signed 7 bit integer (in the range @minus{}64 to 63) 2045 2046@item Ku7 2047Unsigned 7 bit integer (in the range 0 to 127) 2048 2049@item Ku5 2050Unsigned 5 bit integer (in the range 0 to 31) 2051 2052@item Ks4 2053Signed 4 bit integer (in the range @minus{}8 to 7) 2054 2055@item Ks3 2056Signed 3 bit integer (in the range @minus{}3 to 4) 2057 2058@item Ku3 2059Unsigned 3 bit integer (in the range 0 to 7) 2060 2061@item P@var{n} 2062Constant @var{n}, where @var{n} is a single-digit constant in the range 0 to 4. 2063 2064@item PA 2065An integer equal to one of the MACFLAG_XXX constants that is suitable for 2066use with either accumulator. 2067 2068@item PB 2069An integer equal to one of the MACFLAG_XXX constants that is suitable for 2070use only with accumulator A1. 2071 2072@item M1 2073Constant 255. 2074 2075@item M2 2076Constant 65535. 2077 2078@item J 2079An integer constant with exactly a single bit set. 2080 2081@item L 2082An integer constant with all bits set except exactly one. 2083 2084@item H 2085 2086@item Q 2087Any SYMBOL_REF. 2088@end table 2089 2090@item CR16 Architecture---@file{config/cr16/cr16.h} 2091@table @code 2092 2093@item b 2094Registers from r0 to r14 (registers without stack pointer) 2095 2096@item t 2097Register from r0 to r11 (all 16-bit registers) 2098 2099@item p 2100Register from r12 to r15 (all 32-bit registers) 2101 2102@item I 2103Signed constant that fits in 4 bits 2104 2105@item J 2106Signed constant that fits in 5 bits 2107 2108@item K 2109Signed constant that fits in 6 bits 2110 2111@item L 2112Unsigned constant that fits in 4 bits 2113 2114@item M 2115Signed constant that fits in 32 bits 2116 2117@item N 2118Check for 64 bits wide constants for add/sub instructions 2119 2120@item G 2121Floating point constant that is legal for store immediate 2122@end table 2123 2124@item Epiphany---@file{config/epiphany/constraints.md} 2125@table @code 2126@item U16 2127An unsigned 16-bit constant. 2128 2129@item K 2130An unsigned 5-bit constant. 2131 2132@item L 2133A signed 11-bit constant. 2134 2135@item Cm1 2136A signed 11-bit constant added to @minus{}1. 2137Can only match when the @option{-m1reg-@var{reg}} option is active. 2138 2139@item Cl1 2140Left-shift of @minus{}1, i.e., a bit mask with a block of leading ones, the rest 2141being a block of trailing zeroes. 2142Can only match when the @option{-m1reg-@var{reg}} option is active. 2143 2144@item Cr1 2145Right-shift of @minus{}1, i.e., a bit mask with a trailing block of ones, the 2146rest being zeroes. Or to put it another way, one less than a power of two. 2147Can only match when the @option{-m1reg-@var{reg}} option is active. 2148 2149@item Cal 2150Constant for arithmetic/logical operations. 2151This is like @code{i}, except that for position independent code, 2152no symbols / expressions needing relocations are allowed. 2153 2154@item Csy 2155Symbolic constant for call/jump instruction. 2156 2157@item Rcs 2158The register class usable in short insns. This is a register class 2159constraint, and can thus drive register allocation. 2160This constraint won't match unless @option{-mprefer-short-insn-regs} is 2161in effect. 2162 2163@item Rsc 2164The the register class of registers that can be used to hold a 2165sibcall call address. I.e., a caller-saved register. 2166 2167@item Rct 2168Core control register class. 2169 2170@item Rgs 2171The register group usable in short insns. 2172This constraint does not use a register class, so that it only 2173passively matches suitable registers, and doesn't drive register allocation. 2174 2175@ifset INTERNALS 2176@item Car 2177Constant suitable for the addsi3_r pattern. This is a valid offset 2178For byte, halfword, or word addressing. 2179@end ifset 2180 2181@item Rra 2182Matches the return address if it can be replaced with the link register. 2183 2184@item Rcc 2185Matches the integer condition code register. 2186 2187@item Sra 2188Matches the return address if it is in a stack slot. 2189 2190@item Cfm 2191Matches control register values to switch fp mode, which are encapsulated in 2192@code{UNSPEC_FP_MODE}. 2193@end table 2194 2195@item FRV---@file{config/frv/frv.h} 2196@table @code 2197@item a 2198Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}). 2199 2200@item b 2201Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}). 2202 2203@item c 2204Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and 2205@code{icc0} to @code{icc3}). 2206 2207@item d 2208Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}). 2209 2210@item e 2211Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}). 2212Odd registers are excluded not in the class but through the use of a machine 2213mode larger than 4 bytes. 2214 2215@item f 2216Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}). 2217 2218@item h 2219Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}). 2220Odd registers are excluded not in the class but through the use of a machine 2221mode larger than 4 bytes. 2222 2223@item l 2224Register in the class @code{LR_REG} (the @code{lr} register). 2225 2226@item q 2227Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}). 2228Register numbers not divisible by 4 are excluded not in the class but through 2229the use of a machine mode larger than 8 bytes. 2230 2231@item t 2232Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}). 2233 2234@item u 2235Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}). 2236 2237@item v 2238Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}). 2239 2240@item w 2241Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}). 2242 2243@item x 2244Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}). 2245Register numbers not divisible by 4 are excluded not in the class but through 2246the use of a machine mode larger than 8 bytes. 2247 2248@item z 2249Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}). 2250 2251@item A 2252Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}). 2253 2254@item B 2255Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}). 2256 2257@item C 2258Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}). 2259 2260@item G 2261Floating point constant zero 2262 2263@item I 22646-bit signed integer constant 2265 2266@item J 226710-bit signed integer constant 2268 2269@item L 227016-bit signed integer constant 2271 2272@item M 227316-bit unsigned integer constant 2274 2275@item N 227612-bit signed integer constant that is negative---i.e.@: in the 2277range of @minus{}2048 to @minus{}1 2278 2279@item O 2280Constant zero 2281 2282@item P 228312-bit signed integer constant that is greater than zero---i.e.@: in the 2284range of 1 to 2047. 2285 2286@end table 2287 2288@item FT32---@file{config/ft32/constraints.md} 2289@table @code 2290@item A 2291An absolute address 2292 2293@item B 2294An offset address 2295 2296@item W 2297A register indirect memory operand 2298 2299@item e 2300An offset address. 2301 2302@item f 2303An offset address. 2304 2305@item O 2306The constant zero or one 2307 2308@item I 2309A 16-bit signed constant (@minus{}32768 @dots{} 32767) 2310 2311@item w 2312A bitfield mask suitable for bext or bins 2313 2314@item x 2315An inverted bitfield mask suitable for bext or bins 2316 2317@item L 2318A 16-bit unsigned constant, multiple of 4 (0 @dots{} 65532) 2319 2320@item S 2321A 20-bit signed constant (@minus{}524288 @dots{} 524287) 2322 2323@item b 2324A constant for a bitfield width (1 @dots{} 16) 2325 2326@item KA 2327A 10-bit signed constant (@minus{}512 @dots{} 511) 2328 2329@end table 2330 2331@item Hewlett-Packard PA-RISC---@file{config/pa/pa.h} 2332@table @code 2333@item a 2334General register 1 2335 2336@item f 2337Floating point register 2338 2339@item q 2340Shift amount register 2341 2342@item x 2343Floating point register (deprecated) 2344 2345@item y 2346Upper floating point register (32-bit), floating point register (64-bit) 2347 2348@item Z 2349Any register 2350 2351@item I 2352Signed 11-bit integer constant 2353 2354@item J 2355Signed 14-bit integer constant 2356 2357@item K 2358Integer constant that can be deposited with a @code{zdepi} instruction 2359 2360@item L 2361Signed 5-bit integer constant 2362 2363@item M 2364Integer constant 0 2365 2366@item N 2367Integer constant that can be loaded with a @code{ldil} instruction 2368 2369@item O 2370Integer constant whose value plus one is a power of 2 2371 2372@item P 2373Integer constant that can be used for @code{and} operations in @code{depi} 2374and @code{extru} instructions 2375 2376@item S 2377Integer constant 31 2378 2379@item U 2380Integer constant 63 2381 2382@item G 2383Floating-point constant 0.0 2384 2385@item A 2386A @code{lo_sum} data-linkage-table memory operand 2387 2388@item Q 2389A memory operand that can be used as the destination operand of an 2390integer store instruction 2391 2392@item R 2393A scaled or unscaled indexed memory operand 2394 2395@item T 2396A memory operand for floating-point loads and stores 2397 2398@item W 2399A register indirect memory operand 2400@end table 2401 2402@item Intel IA-64---@file{config/ia64/ia64.h} 2403@table @code 2404@item a 2405General register @code{r0} to @code{r3} for @code{addl} instruction 2406 2407@item b 2408Branch register 2409 2410@item c 2411Predicate register (@samp{c} as in ``conditional'') 2412 2413@item d 2414Application register residing in M-unit 2415 2416@item e 2417Application register residing in I-unit 2418 2419@item f 2420Floating-point register 2421 2422@item m 2423Memory operand. If used together with @samp{<} or @samp{>}, 2424the operand can have postincrement and postdecrement which 2425require printing with @samp{%Pn} on IA-64. 2426 2427@item G 2428Floating-point constant 0.0 or 1.0 2429 2430@item I 243114-bit signed integer constant 2432 2433@item J 243422-bit signed integer constant 2435 2436@item K 24378-bit signed integer constant for logical instructions 2438 2439@item L 24408-bit adjusted signed integer constant for compare pseudo-ops 2441 2442@item M 24436-bit unsigned integer constant for shift counts 2444 2445@item N 24469-bit signed integer constant for load and store postincrements 2447 2448@item O 2449The constant zero 2450 2451@item P 24520 or @minus{}1 for @code{dep} instruction 2453 2454@item Q 2455Non-volatile memory for floating-point loads and stores 2456 2457@item R 2458Integer constant in the range 1 to 4 for @code{shladd} instruction 2459 2460@item S 2461Memory operand except postincrement and postdecrement. This is 2462now roughly the same as @samp{m} when not used together with @samp{<} 2463or @samp{>}. 2464@end table 2465 2466@item M32C---@file{config/m32c/m32c.c} 2467@table @code 2468@item Rsp 2469@itemx Rfb 2470@itemx Rsb 2471@samp{$sp}, @samp{$fb}, @samp{$sb}. 2472 2473@item Rcr 2474Any control register, when they're 16 bits wide (nothing if control 2475registers are 24 bits wide) 2476 2477@item Rcl 2478Any control register, when they're 24 bits wide. 2479 2480@item R0w 2481@itemx R1w 2482@itemx R2w 2483@itemx R3w 2484$r0, $r1, $r2, $r3. 2485 2486@item R02 2487$r0 or $r2, or $r2r0 for 32 bit values. 2488 2489@item R13 2490$r1 or $r3, or $r3r1 for 32 bit values. 2491 2492@item Rdi 2493A register that can hold a 64 bit value. 2494 2495@item Rhl 2496$r0 or $r1 (registers with addressable high/low bytes) 2497 2498@item R23 2499$r2 or $r3 2500 2501@item Raa 2502Address registers 2503 2504@item Raw 2505Address registers when they're 16 bits wide. 2506 2507@item Ral 2508Address registers when they're 24 bits wide. 2509 2510@item Rqi 2511Registers that can hold QI values. 2512 2513@item Rad 2514Registers that can be used with displacements ($a0, $a1, $sb). 2515 2516@item Rsi 2517Registers that can hold 32 bit values. 2518 2519@item Rhi 2520Registers that can hold 16 bit values. 2521 2522@item Rhc 2523Registers chat can hold 16 bit values, including all control 2524registers. 2525 2526@item Rra 2527$r0 through R1, plus $a0 and $a1. 2528 2529@item Rfl 2530The flags register. 2531 2532@item Rmm 2533The memory-based pseudo-registers $mem0 through $mem15. 2534 2535@item Rpi 2536Registers that can hold pointers (16 bit registers for r8c, m16c; 24 2537bit registers for m32cm, m32c). 2538 2539@item Rpa 2540Matches multiple registers in a PARALLEL to form a larger register. 2541Used to match function return values. 2542 2543@item Is3 2544@minus{}8 @dots{} 7 2545 2546@item IS1 2547@minus{}128 @dots{} 127 2548 2549@item IS2 2550@minus{}32768 @dots{} 32767 2551 2552@item IU2 25530 @dots{} 65535 2554 2555@item In4 2556@minus{}8 @dots{} @minus{}1 or 1 @dots{} 8 2557 2558@item In5 2559@minus{}16 @dots{} @minus{}1 or 1 @dots{} 16 2560 2561@item In6 2562@minus{}32 @dots{} @minus{}1 or 1 @dots{} 32 2563 2564@item IM2 2565@minus{}65536 @dots{} @minus{}1 2566 2567@item Ilb 2568An 8 bit value with exactly one bit set. 2569 2570@item Ilw 2571A 16 bit value with exactly one bit set. 2572 2573@item Sd 2574The common src/dest memory addressing modes. 2575 2576@item Sa 2577Memory addressed using $a0 or $a1. 2578 2579@item Si 2580Memory addressed with immediate addresses. 2581 2582@item Ss 2583Memory addressed using the stack pointer ($sp). 2584 2585@item Sf 2586Memory addressed using the frame base register ($fb). 2587 2588@item Ss 2589Memory addressed using the small base register ($sb). 2590 2591@item S1 2592$r1h 2593@end table 2594 2595@item MicroBlaze---@file{config/microblaze/constraints.md} 2596@table @code 2597@item d 2598A general register (@code{r0} to @code{r31}). 2599 2600@item z 2601A status register (@code{rmsr}, @code{$fcc1} to @code{$fcc7}). 2602 2603@end table 2604 2605@item MIPS---@file{config/mips/constraints.md} 2606@table @code 2607@item d 2608A general-purpose register. This is equivalent to @code{r} unless 2609generating MIPS16 code, in which case the MIPS16 register set is used. 2610 2611@item f 2612A floating-point register (if available). 2613 2614@item h 2615Formerly the @code{hi} register. This constraint is no longer supported. 2616 2617@item l 2618The @code{lo} register. Use this register to store values that are 2619no bigger than a word. 2620 2621@item x 2622The concatenated @code{hi} and @code{lo} registers. Use this register 2623to store doubleword values. 2624 2625@item c 2626A register suitable for use in an indirect jump. This will always be 2627@code{$25} for @option{-mabicalls}. 2628 2629@item v 2630Register @code{$3}. Do not use this constraint in new code; 2631it is retained only for compatibility with glibc. 2632 2633@item y 2634Equivalent to @code{r}; retained for backwards compatibility. 2635 2636@item z 2637A floating-point condition code register. 2638 2639@item I 2640A signed 16-bit constant (for arithmetic instructions). 2641 2642@item J 2643Integer zero. 2644 2645@item K 2646An unsigned 16-bit constant (for logic instructions). 2647 2648@item L 2649A signed 32-bit constant in which the lower 16 bits are zero. 2650Such constants can be loaded using @code{lui}. 2651 2652@item M 2653A constant that cannot be loaded using @code{lui}, @code{addiu} 2654or @code{ori}. 2655 2656@item N 2657A constant in the range @minus{}65535 to @minus{}1 (inclusive). 2658 2659@item O 2660A signed 15-bit constant. 2661 2662@item P 2663A constant in the range 1 to 65535 (inclusive). 2664 2665@item G 2666Floating-point zero. 2667 2668@item R 2669An address that can be used in a non-macro load or store. 2670 2671@item ZC 2672A memory operand whose address is formed by a base register and offset 2673that is suitable for use in instructions with the same addressing mode 2674as @code{ll} and @code{sc}. 2675 2676@item ZD 2677An address suitable for a @code{prefetch} instruction, or for any other 2678instruction with the same addressing mode as @code{prefetch}. 2679@end table 2680 2681@item Motorola 680x0---@file{config/m68k/constraints.md} 2682@table @code 2683@item a 2684Address register 2685 2686@item d 2687Data register 2688 2689@item f 269068881 floating-point register, if available 2691 2692@item I 2693Integer in the range 1 to 8 2694 2695@item J 269616-bit signed number 2697 2698@item K 2699Signed number whose magnitude is greater than 0x80 2700 2701@item L 2702Integer in the range @minus{}8 to @minus{}1 2703 2704@item M 2705Signed number whose magnitude is greater than 0x100 2706 2707@item N 2708Range 24 to 31, rotatert:SI 8 to 1 expressed as rotate 2709 2710@item O 271116 (for rotate using swap) 2712 2713@item P 2714Range 8 to 15, rotatert:HI 8 to 1 expressed as rotate 2715 2716@item R 2717Numbers that mov3q can handle 2718 2719@item G 2720Floating point constant that is not a 68881 constant 2721 2722@item S 2723Operands that satisfy 'm' when -mpcrel is in effect 2724 2725@item T 2726Operands that satisfy 's' when -mpcrel is not in effect 2727 2728@item Q 2729Address register indirect addressing mode 2730 2731@item U 2732Register offset addressing 2733 2734@item W 2735const_call_operand 2736 2737@item Cs 2738symbol_ref or const 2739 2740@item Ci 2741const_int 2742 2743@item C0 2744const_int 0 2745 2746@item Cj 2747Range of signed numbers that don't fit in 16 bits 2748 2749@item Cmvq 2750Integers valid for mvq 2751 2752@item Capsw 2753Integers valid for a moveq followed by a swap 2754 2755@item Cmvz 2756Integers valid for mvz 2757 2758@item Cmvs 2759Integers valid for mvs 2760 2761@item Ap 2762push_operand 2763 2764@item Ac 2765Non-register operands allowed in clr 2766 2767@end table 2768 2769@item Moxie---@file{config/moxie/constraints.md} 2770@table @code 2771@item A 2772An absolute address 2773 2774@item B 2775An offset address 2776 2777@item W 2778A register indirect memory operand 2779 2780@item I 2781A constant in the range of 0 to 255. 2782 2783@item N 2784A constant in the range of 0 to @minus{}255. 2785 2786@end table 2787 2788@item MSP430--@file{config/msp430/constraints.md} 2789@table @code 2790 2791@item R12 2792Register R12. 2793 2794@item R13 2795Register R13. 2796 2797@item K 2798Integer constant 1. 2799 2800@item L 2801Integer constant -1^20..1^19. 2802 2803@item M 2804Integer constant 1-4. 2805 2806@item Ya 2807Memory references which do not require an extended MOVX instruction. 2808 2809@item Yl 2810Memory reference, labels only. 2811 2812@item Ys 2813Memory reference, stack only. 2814 2815@end table 2816 2817@item NDS32---@file{config/nds32/constraints.md} 2818@table @code 2819@item w 2820LOW register class $r0 to $r7 constraint for V3/V3M ISA. 2821@item l 2822LOW register class $r0 to $r7. 2823@item d 2824MIDDLE register class $r0 to $r11, $r16 to $r19. 2825@item h 2826HIGH register class $r12 to $r14, $r20 to $r31. 2827@item t 2828Temporary assist register $ta (i.e.@: $r15). 2829@item k 2830Stack register $sp. 2831@item Iu03 2832Unsigned immediate 3-bit value. 2833@item In03 2834Negative immediate 3-bit value in the range of @minus{}7--0. 2835@item Iu04 2836Unsigned immediate 4-bit value. 2837@item Is05 2838Signed immediate 5-bit value. 2839@item Iu05 2840Unsigned immediate 5-bit value. 2841@item In05 2842Negative immediate 5-bit value in the range of @minus{}31--0. 2843@item Ip05 2844Unsigned immediate 5-bit value for movpi45 instruction with range 16--47. 2845@item Iu06 2846Unsigned immediate 6-bit value constraint for addri36.sp instruction. 2847@item Iu08 2848Unsigned immediate 8-bit value. 2849@item Iu09 2850Unsigned immediate 9-bit value. 2851@item Is10 2852Signed immediate 10-bit value. 2853@item Is11 2854Signed immediate 11-bit value. 2855@item Is15 2856Signed immediate 15-bit value. 2857@item Iu15 2858Unsigned immediate 15-bit value. 2859@item Ic15 2860A constant which is not in the range of imm15u but ok for bclr instruction. 2861@item Ie15 2862A constant which is not in the range of imm15u but ok for bset instruction. 2863@item It15 2864A constant which is not in the range of imm15u but ok for btgl instruction. 2865@item Ii15 2866A constant whose compliment value is in the range of imm15u 2867and ok for bitci instruction. 2868@item Is16 2869Signed immediate 16-bit value. 2870@item Is17 2871Signed immediate 17-bit value. 2872@item Is19 2873Signed immediate 19-bit value. 2874@item Is20 2875Signed immediate 20-bit value. 2876@item Ihig 2877The immediate value that can be simply set high 20-bit. 2878@item Izeb 2879The immediate value 0xff. 2880@item Izeh 2881The immediate value 0xffff. 2882@item Ixls 2883The immediate value 0x01. 2884@item Ix11 2885The immediate value 0x7ff. 2886@item Ibms 2887The immediate value with power of 2. 2888@item Ifex 2889The immediate value with power of 2 minus 1. 2890@item U33 2891Memory constraint for 333 format. 2892@item U45 2893Memory constraint for 45 format. 2894@item U37 2895Memory constraint for 37 format. 2896@end table 2897 2898@item Nios II family---@file{config/nios2/constraints.md} 2899@table @code 2900 2901@item I 2902Integer that is valid as an immediate operand in an 2903instruction taking a signed 16-bit number. Range 2904@minus{}32768 to 32767. 2905 2906@item J 2907Integer that is valid as an immediate operand in an 2908instruction taking an unsigned 16-bit number. Range 29090 to 65535. 2910 2911@item K 2912Integer that is valid as an immediate operand in an 2913instruction taking only the upper 16-bits of a 291432-bit number. Range 32-bit numbers with the lower 291516-bits being 0. 2916 2917@item L 2918Integer that is valid as an immediate operand for a 2919shift instruction. Range 0 to 31. 2920 2921@item M 2922Integer that is valid as an immediate operand for 2923only the value 0. Can be used in conjunction with 2924the format modifier @code{z} to use @code{r0} 2925instead of @code{0} in the assembly output. 2926 2927@item N 2928Integer that is valid as an immediate operand for 2929a custom instruction opcode. Range 0 to 255. 2930 2931@item P 2932An immediate operand for R2 andchi/andci instructions. 2933 2934@item S 2935Matches immediates which are addresses in the small 2936data section and therefore can be added to @code{gp} 2937as a 16-bit immediate to re-create their 32-bit value. 2938 2939@item U 2940Matches constants suitable as an operand for the rdprs and 2941cache instructions. 2942 2943@item v 2944A memory operand suitable for Nios II R2 load/store 2945exclusive instructions. 2946 2947@item w 2948A memory operand suitable for load/store IO and cache 2949instructions. 2950 2951@ifset INTERNALS 2952@item T 2953A @code{const} wrapped @code{UNSPEC} expression, 2954representing a supported PIC or TLS relocation. 2955@end ifset 2956 2957@end table 2958 2959@item PDP-11---@file{config/pdp11/constraints.md} 2960@table @code 2961@item a 2962Floating point registers AC0 through AC3. These can be loaded from/to 2963memory with a single instruction. 2964 2965@item d 2966Odd numbered general registers (R1, R3, R5). These are used for 296716-bit multiply operations. 2968 2969@item f 2970Any of the floating point registers (AC0 through AC5). 2971 2972@item G 2973Floating point constant 0. 2974 2975@item I 2976An integer constant that fits in 16 bits. 2977 2978@item J 2979An integer constant whose low order 16 bits are zero. 2980 2981@item K 2982An integer constant that does not meet the constraints for codes 2983@samp{I} or @samp{J}. 2984 2985@item L 2986The integer constant 1. 2987 2988@item M 2989The integer constant @minus{}1. 2990 2991@item N 2992The integer constant 0. 2993 2994@item O 2995Integer constants @minus{}4 through @minus{}1 and 1 through 4; shifts by these 2996amounts are handled as multiple single-bit shifts rather than a single 2997variable-length shift. 2998 2999@item Q 3000A memory reference which requires an additional word (address or 3001offset) after the opcode. 3002 3003@item R 3004A memory reference that is encoded within the opcode. 3005 3006@end table 3007 3008@item PowerPC and IBM RS6000---@file{config/rs6000/constraints.md} 3009@table @code 3010@item b 3011Address base register 3012 3013@item d 3014Floating point register (containing 64-bit value) 3015 3016@item f 3017Floating point register (containing 32-bit value) 3018 3019@item v 3020Altivec vector register 3021 3022@item wa 3023Any VSX register if the @option{-mvsx} option was used or NO_REGS. 3024 3025When using any of the register constraints (@code{wa}, @code{wd}, 3026@code{wf}, @code{wg}, @code{wh}, @code{wi}, @code{wj}, @code{wk}, 3027@code{wl}, @code{wm}, @code{wo}, @code{wp}, @code{wq}, @code{ws}, 3028@code{wt}, @code{wu}, @code{wv}, @code{ww}, or @code{wy}) 3029that take VSX registers, you must use @code{%x<n>} in the template so 3030that the correct register is used. Otherwise the register number 3031output in the assembly file will be incorrect if an Altivec register 3032is an operand of a VSX instruction that expects VSX register 3033numbering. 3034 3035@smallexample 3036asm ("xvadddp %x0,%x1,%x2" 3037 : "=wa" (v1) 3038 : "wa" (v2), "wa" (v3)); 3039@end smallexample 3040 3041@noindent 3042is correct, but: 3043 3044@smallexample 3045asm ("xvadddp %0,%1,%2" 3046 : "=wa" (v1) 3047 : "wa" (v2), "wa" (v3)); 3048@end smallexample 3049 3050@noindent 3051is not correct. 3052 3053If an instruction only takes Altivec registers, you do not want to use 3054@code{%x<n>}. 3055 3056@smallexample 3057asm ("xsaddqp %0,%1,%2" 3058 : "=v" (v1) 3059 : "v" (v2), "v" (v3)); 3060@end smallexample 3061 3062@noindent 3063is correct because the @code{xsaddqp} instruction only takes Altivec 3064registers, while: 3065 3066@smallexample 3067asm ("xsaddqp %x0,%x1,%x2" 3068 : "=v" (v1) 3069 : "v" (v2), "v" (v3)); 3070@end smallexample 3071 3072@noindent 3073is incorrect. 3074 3075@item wb 3076Altivec register if @option{-mcpu=power9} is used or NO_REGS. 3077 3078@item wd 3079VSX vector register to hold vector double data or NO_REGS. 3080 3081@item we 3082VSX register if the @option{-mcpu=power9} and @option{-m64} options 3083were used or NO_REGS. 3084 3085@item wf 3086VSX vector register to hold vector float data or NO_REGS. 3087 3088@item wg 3089If @option{-mmfpgpr} was used, a floating point register or NO_REGS. 3090 3091@item wh 3092Floating point register if direct moves are available, or NO_REGS. 3093 3094@item wi 3095FP or VSX register to hold 64-bit integers for VSX insns or NO_REGS. 3096 3097@item wj 3098FP or VSX register to hold 64-bit integers for direct moves or NO_REGS. 3099 3100@item wk 3101FP or VSX register to hold 64-bit doubles for direct moves or NO_REGS. 3102 3103@item wl 3104Floating point register if the LFIWAX instruction is enabled or NO_REGS. 3105 3106@item wm 3107VSX register if direct move instructions are enabled, or NO_REGS. 3108 3109@item wn 3110No register (NO_REGS). 3111 3112@item wo 3113VSX register to use for ISA 3.0 vector instructions, or NO_REGS. 3114 3115@item wp 3116VSX register to use for IEEE 128-bit floating point TFmode, or NO_REGS. 3117 3118@item wq 3119VSX register to use for IEEE 128-bit floating point, or NO_REGS. 3120 3121@item wr 3122General purpose register if 64-bit instructions are enabled or NO_REGS. 3123 3124@item ws 3125VSX vector register to hold scalar double values or NO_REGS. 3126 3127@item wt 3128VSX vector register to hold 128 bit integer or NO_REGS. 3129 3130@item wu 3131Altivec register to use for float/32-bit int loads/stores or NO_REGS. 3132 3133@item wv 3134Altivec register to use for double loads/stores or NO_REGS. 3135 3136@item ww 3137FP or VSX register to perform float operations under @option{-mvsx} or NO_REGS. 3138 3139@item wx 3140Floating point register if the STFIWX instruction is enabled or NO_REGS. 3141 3142@item wy 3143FP or VSX register to perform ISA 2.07 float ops or NO_REGS. 3144 3145@item wz 3146Floating point register if the LFIWZX instruction is enabled or NO_REGS. 3147 3148@item wA 3149Address base register if 64-bit instructions are enabled or NO_REGS. 3150 3151@item wB 3152Signed 5-bit constant integer that can be loaded into an altivec register. 3153 3154@item wD 3155Int constant that is the element number of the 64-bit scalar in a vector. 3156 3157@item wE 3158Vector constant that can be loaded with the XXSPLTIB instruction. 3159 3160@item wF 3161Memory operand suitable for power9 fusion load/stores. 3162 3163@item wG 3164Memory operand suitable for TOC fusion memory references. 3165 3166@item wH 3167Altivec register if @option{-mvsx-small-integer}. 3168 3169@item wI 3170Floating point register if @option{-mvsx-small-integer}. 3171 3172@item wJ 3173FP register if @option{-mvsx-small-integer} and @option{-mpower9-vector}. 3174 3175@item wK 3176Altivec register if @option{-mvsx-small-integer} and @option{-mpower9-vector}. 3177 3178@item wL 3179Int constant that is the element number that the MFVSRLD instruction. 3180targets. 3181 3182@item wM 3183Match vector constant with all 1's if the XXLORC instruction is available. 3184 3185@item wO 3186A memory operand suitable for the ISA 3.0 vector d-form instructions. 3187 3188@item wQ 3189A memory address that will work with the @code{lq} and @code{stq} 3190instructions. 3191 3192@item wS 3193Vector constant that can be loaded with XXSPLTIB & sign extension. 3194 3195@item h 3196@samp{MQ}, @samp{CTR}, or @samp{LINK} register 3197 3198@item c 3199@samp{CTR} register 3200 3201@item l 3202@samp{LINK} register 3203 3204@item x 3205@samp{CR} register (condition register) number 0 3206 3207@item y 3208@samp{CR} register (condition register) 3209 3210@item z 3211@samp{XER[CA]} carry bit (part of the XER register) 3212 3213@item I 3214Signed 16-bit constant 3215 3216@item J 3217Unsigned 16-bit constant shifted left 16 bits (use @samp{L} instead for 3218@code{SImode} constants) 3219 3220@item K 3221Unsigned 16-bit constant 3222 3223@item L 3224Signed 16-bit constant shifted left 16 bits 3225 3226@item M 3227Constant larger than 31 3228 3229@item N 3230Exact power of 2 3231 3232@item O 3233Zero 3234 3235@item P 3236Constant whose negation is a signed 16-bit constant 3237 3238@item G 3239Floating point constant that can be loaded into a register with one 3240instruction per word 3241 3242@item H 3243Integer/Floating point constant that can be loaded into a register using 3244three instructions 3245 3246@item m 3247Memory operand. 3248Normally, @code{m} does not allow addresses that update the base register. 3249If @samp{<} or @samp{>} constraint is also used, they are allowed and 3250therefore on PowerPC targets in that case it is only safe 3251to use @samp{m<>} in an @code{asm} statement if that @code{asm} statement 3252accesses the operand exactly once. The @code{asm} statement must also 3253use @samp{%U@var{<opno>}} as a placeholder for the ``update'' flag in the 3254corresponding load or store instruction. For example: 3255 3256@smallexample 3257asm ("st%U0 %1,%0" : "=m<>" (mem) : "r" (val)); 3258@end smallexample 3259 3260is correct but: 3261 3262@smallexample 3263asm ("st %1,%0" : "=m<>" (mem) : "r" (val)); 3264@end smallexample 3265 3266is not. 3267 3268@item es 3269A ``stable'' memory operand; that is, one which does not include any 3270automodification of the base register. This used to be useful when 3271@samp{m} allowed automodification of the base register, but as those are now only 3272allowed when @samp{<} or @samp{>} is used, @samp{es} is basically the same 3273as @samp{m} without @samp{<} and @samp{>}. 3274 3275@item Q 3276Memory operand that is an offset from a register (it is usually better 3277to use @samp{m} or @samp{es} in @code{asm} statements) 3278 3279@item Z 3280Memory operand that is an indexed or indirect from a register (it is 3281usually better to use @samp{m} or @samp{es} in @code{asm} statements) 3282 3283@item R 3284AIX TOC entry 3285 3286@item a 3287Address operand that is an indexed or indirect from a register (@samp{p} is 3288preferable for @code{asm} statements) 3289 3290@item U 3291System V Release 4 small data area reference 3292 3293@item W 3294Vector constant that does not require memory 3295 3296@item j 3297Vector constant that is all zeros. 3298 3299@end table 3300 3301@item RL78---@file{config/rl78/constraints.md} 3302@table @code 3303 3304@item Int3 3305An integer constant in the range 1 @dots{} 7. 3306@item Int8 3307An integer constant in the range 0 @dots{} 255. 3308@item J 3309An integer constant in the range @minus{}255 @dots{} 0 3310@item K 3311The integer constant 1. 3312@item L 3313The integer constant -1. 3314@item M 3315The integer constant 0. 3316@item N 3317The integer constant 2. 3318@item O 3319The integer constant -2. 3320@item P 3321An integer constant in the range 1 @dots{} 15. 3322@item Qbi 3323The built-in compare types--eq, ne, gtu, ltu, geu, and leu. 3324@item Qsc 3325The synthetic compare types--gt, lt, ge, and le. 3326@item Wab 3327A memory reference with an absolute address. 3328@item Wbc 3329A memory reference using @code{BC} as a base register, with an optional offset. 3330@item Wca 3331A memory reference using @code{AX}, @code{BC}, @code{DE}, or @code{HL} for the address, for calls. 3332@item Wcv 3333A memory reference using any 16-bit register pair for the address, for calls. 3334@item Wd2 3335A memory reference using @code{DE} as a base register, with an optional offset. 3336@item Wde 3337A memory reference using @code{DE} as a base register, without any offset. 3338@item Wfr 3339Any memory reference to an address in the far address space. 3340@item Wh1 3341A memory reference using @code{HL} as a base register, with an optional one-byte offset. 3342@item Whb 3343A memory reference using @code{HL} as a base register, with @code{B} or @code{C} as the index register. 3344@item Whl 3345A memory reference using @code{HL} as a base register, without any offset. 3346@item Ws1 3347A memory reference using @code{SP} as a base register, with an optional one-byte offset. 3348@item Y 3349Any memory reference to an address in the near address space. 3350@item A 3351The @code{AX} register. 3352@item B 3353The @code{BC} register. 3354@item D 3355The @code{DE} register. 3356@item R 3357@code{A} through @code{L} registers. 3358@item S 3359The @code{SP} register. 3360@item T 3361The @code{HL} register. 3362@item Z08W 3363The 16-bit @code{R8} register. 3364@item Z10W 3365The 16-bit @code{R10} register. 3366@item Zint 3367The registers reserved for interrupts (@code{R24} to @code{R31}). 3368@item a 3369The @code{A} register. 3370@item b 3371The @code{B} register. 3372@item c 3373The @code{C} register. 3374@item d 3375The @code{D} register. 3376@item e 3377The @code{E} register. 3378@item h 3379The @code{H} register. 3380@item l 3381The @code{L} register. 3382@item v 3383The virtual registers. 3384@item w 3385The @code{PSW} register. 3386@item x 3387The @code{X} register. 3388 3389@end table 3390 3391@item RISC-V---@file{config/riscv/constraints.md} 3392@table @code 3393 3394@item f 3395A floating-point register (if available). 3396 3397@item I 3398An I-type 12-bit signed immediate. 3399 3400@item J 3401Integer zero. 3402 3403@item K 3404A 5-bit unsigned immediate for CSR access instructions. 3405 3406@item A 3407An address that is held in a general-purpose register. 3408 3409@end table 3410 3411@item RX---@file{config/rx/constraints.md} 3412@table @code 3413@item Q 3414An address which does not involve register indirect addressing or 3415pre/post increment/decrement addressing. 3416 3417@item Symbol 3418A symbol reference. 3419 3420@item Int08 3421A constant in the range @minus{}256 to 255, inclusive. 3422 3423@item Sint08 3424A constant in the range @minus{}128 to 127, inclusive. 3425 3426@item Sint16 3427A constant in the range @minus{}32768 to 32767, inclusive. 3428 3429@item Sint24 3430A constant in the range @minus{}8388608 to 8388607, inclusive. 3431 3432@item Uint04 3433A constant in the range 0 to 15, inclusive. 3434 3435@end table 3436 3437@item S/390 and zSeries---@file{config/s390/s390.h} 3438@table @code 3439@item a 3440Address register (general purpose register except r0) 3441 3442@item c 3443Condition code register 3444 3445@item d 3446Data register (arbitrary general purpose register) 3447 3448@item f 3449Floating-point register 3450 3451@item I 3452Unsigned 8-bit constant (0--255) 3453 3454@item J 3455Unsigned 12-bit constant (0--4095) 3456 3457@item K 3458Signed 16-bit constant (@minus{}32768--32767) 3459 3460@item L 3461Value appropriate as displacement. 3462@table @code 3463@item (0..4095) 3464for short displacement 3465@item (@minus{}524288..524287) 3466for long displacement 3467@end table 3468 3469@item M 3470Constant integer with a value of 0x7fffffff. 3471 3472@item N 3473Multiple letter constraint followed by 4 parameter letters. 3474@table @code 3475@item 0..9: 3476number of the part counting from most to least significant 3477@item H,Q: 3478mode of the part 3479@item D,S,H: 3480mode of the containing operand 3481@item 0,F: 3482value of the other parts (F---all bits set) 3483@end table 3484The constraint matches if the specified part of a constant 3485has a value different from its other parts. 3486 3487@item Q 3488Memory reference without index register and with short displacement. 3489 3490@item R 3491Memory reference with index register and short displacement. 3492 3493@item S 3494Memory reference without index register but with long displacement. 3495 3496@item T 3497Memory reference with index register and long displacement. 3498 3499@item U 3500Pointer with short displacement. 3501 3502@item W 3503Pointer with long displacement. 3504 3505@item Y 3506Shift count operand. 3507 3508@end table 3509 3510@need 1000 3511@item SPARC---@file{config/sparc/sparc.h} 3512@table @code 3513@item f 3514Floating-point register on the SPARC-V8 architecture and 3515lower floating-point register on the SPARC-V9 architecture. 3516 3517@item e 3518Floating-point register. It is equivalent to @samp{f} on the 3519SPARC-V8 architecture and contains both lower and upper 3520floating-point registers on the SPARC-V9 architecture. 3521 3522@item c 3523Floating-point condition code register. 3524 3525@item d 3526Lower floating-point register. It is only valid on the SPARC-V9 3527architecture when the Visual Instruction Set is available. 3528 3529@item b 3530Floating-point register. It is only valid on the SPARC-V9 architecture 3531when the Visual Instruction Set is available. 3532 3533@item h 353464-bit global or out register for the SPARC-V8+ architecture. 3535 3536@item C 3537The constant all-ones, for floating-point. 3538 3539@item A 3540Signed 5-bit constant 3541 3542@item D 3543A vector constant 3544 3545@item I 3546Signed 13-bit constant 3547 3548@item J 3549Zero 3550 3551@item K 355232-bit constant with the low 12 bits clear (a constant that can be 3553loaded with the @code{sethi} instruction) 3554 3555@item L 3556A constant in the range supported by @code{movcc} instructions (11-bit 3557signed immediate) 3558 3559@item M 3560A constant in the range supported by @code{movrcc} instructions (10-bit 3561signed immediate) 3562 3563@item N 3564Same as @samp{K}, except that it verifies that bits that are not in the 3565lower 32-bit range are all zero. Must be used instead of @samp{K} for 3566modes wider than @code{SImode} 3567 3568@item O 3569The constant 4096 3570 3571@item G 3572Floating-point zero 3573 3574@item H 3575Signed 13-bit constant, sign-extended to 32 or 64 bits 3576 3577@item P 3578The constant -1 3579 3580@item Q 3581Floating-point constant whose integral representation can 3582be moved into an integer register using a single sethi 3583instruction 3584 3585@item R 3586Floating-point constant whose integral representation can 3587be moved into an integer register using a single mov 3588instruction 3589 3590@item S 3591Floating-point constant whose integral representation can 3592be moved into an integer register using a high/lo_sum 3593instruction sequence 3594 3595@item T 3596Memory address aligned to an 8-byte boundary 3597 3598@item U 3599Even register 3600 3601@item W 3602Memory address for @samp{e} constraint registers 3603 3604@item w 3605Memory address with only a base register 3606 3607@item Y 3608Vector zero 3609 3610@end table 3611 3612@item SPU---@file{config/spu/spu.h} 3613@table @code 3614@item a 3615An immediate which can be loaded with the il/ila/ilh/ilhu instructions. const_int is treated as a 64 bit value. 3616 3617@item c 3618An immediate for and/xor/or instructions. const_int is treated as a 64 bit value. 3619 3620@item d 3621An immediate for the @code{iohl} instruction. const_int is treated as a 64 bit value. 3622 3623@item f 3624An immediate which can be loaded with @code{fsmbi}. 3625 3626@item A 3627An immediate which can be loaded with the il/ila/ilh/ilhu instructions. const_int is treated as a 32 bit value. 3628 3629@item B 3630An immediate for most arithmetic instructions. const_int is treated as a 32 bit value. 3631 3632@item C 3633An immediate for and/xor/or instructions. const_int is treated as a 32 bit value. 3634 3635@item D 3636An immediate for the @code{iohl} instruction. const_int is treated as a 32 bit value. 3637 3638@item I 3639A constant in the range [@minus{}64, 63] for shift/rotate instructions. 3640 3641@item J 3642An unsigned 7-bit constant for conversion/nop/channel instructions. 3643 3644@item K 3645A signed 10-bit constant for most arithmetic instructions. 3646 3647@item M 3648A signed 16 bit immediate for @code{stop}. 3649 3650@item N 3651An unsigned 16-bit constant for @code{iohl} and @code{fsmbi}. 3652 3653@item O 3654An unsigned 7-bit constant whose 3 least significant bits are 0. 3655 3656@item P 3657An unsigned 3-bit constant for 16-byte rotates and shifts 3658 3659@item R 3660Call operand, reg, for indirect calls 3661 3662@item S 3663Call operand, symbol, for relative calls. 3664 3665@item T 3666Call operand, const_int, for absolute calls. 3667 3668@item U 3669An immediate which can be loaded with the il/ila/ilh/ilhu instructions. const_int is sign extended to 128 bit. 3670 3671@item W 3672An immediate for shift and rotate instructions. const_int is treated as a 32 bit value. 3673 3674@item Y 3675An immediate for and/xor/or instructions. const_int is sign extended as a 128 bit. 3676 3677@item Z 3678An immediate for the @code{iohl} instruction. const_int is sign extended to 128 bit. 3679 3680@end table 3681 3682@item TI C6X family---@file{config/c6x/constraints.md} 3683@table @code 3684@item a 3685Register file A (A0--A31). 3686 3687@item b 3688Register file B (B0--B31). 3689 3690@item A 3691Predicate registers in register file A (A0--A2 on C64X and 3692higher, A1 and A2 otherwise). 3693 3694@item B 3695Predicate registers in register file B (B0--B2). 3696 3697@item C 3698A call-used register in register file B (B0--B9, B16--B31). 3699 3700@item Da 3701Register file A, excluding predicate registers (A3--A31, 3702plus A0 if not C64X or higher). 3703 3704@item Db 3705Register file B, excluding predicate registers (B3--B31). 3706 3707@item Iu4 3708Integer constant in the range 0 @dots{} 15. 3709 3710@item Iu5 3711Integer constant in the range 0 @dots{} 31. 3712 3713@item In5 3714Integer constant in the range @minus{}31 @dots{} 0. 3715 3716@item Is5 3717Integer constant in the range @minus{}16 @dots{} 15. 3718 3719@item I5x 3720Integer constant that can be the operand of an ADDA or a SUBA insn. 3721 3722@item IuB 3723Integer constant in the range 0 @dots{} 65535. 3724 3725@item IsB 3726Integer constant in the range @minus{}32768 @dots{} 32767. 3727 3728@item IsC 3729Integer constant in the range @math{-2^{20}} @dots{} @math{2^{20} - 1}. 3730 3731@item Jc 3732Integer constant that is a valid mask for the clr instruction. 3733 3734@item Js 3735Integer constant that is a valid mask for the set instruction. 3736 3737@item Q 3738Memory location with A base register. 3739 3740@item R 3741Memory location with B base register. 3742 3743@ifset INTERNALS 3744@item S0 3745On C64x+ targets, a GP-relative small data reference. 3746 3747@item S1 3748Any kind of @code{SYMBOL_REF}, for use in a call address. 3749 3750@item Si 3751Any kind of immediate operand, unless it matches the S0 constraint. 3752 3753@item T 3754Memory location with B base register, but not using a long offset. 3755 3756@item W 3757A memory operand with an address that cannot be used in an unaligned access. 3758 3759@end ifset 3760@item Z 3761Register B14 (aka DP). 3762 3763@end table 3764 3765@item TILE-Gx---@file{config/tilegx/constraints.md} 3766@table @code 3767@item R00 3768@itemx R01 3769@itemx R02 3770@itemx R03 3771@itemx R04 3772@itemx R05 3773@itemx R06 3774@itemx R07 3775@itemx R08 3776@itemx R09 3777@itemx R10 3778Each of these represents a register constraint for an individual 3779register, from r0 to r10. 3780 3781@item I 3782Signed 8-bit integer constant. 3783 3784@item J 3785Signed 16-bit integer constant. 3786 3787@item K 3788Unsigned 16-bit integer constant. 3789 3790@item L 3791Integer constant that fits in one signed byte when incremented by one 3792(@minus{}129 @dots{} 126). 3793 3794@item m 3795Memory operand. If used together with @samp{<} or @samp{>}, the 3796operand can have postincrement which requires printing with @samp{%In} 3797and @samp{%in} on TILE-Gx. For example: 3798 3799@smallexample 3800asm ("st_add %I0,%1,%i0" : "=m<>" (*mem) : "r" (val)); 3801@end smallexample 3802 3803@item M 3804A bit mask suitable for the BFINS instruction. 3805 3806@item N 3807Integer constant that is a byte tiled out eight times. 3808 3809@item O 3810The integer zero constant. 3811 3812@item P 3813Integer constant that is a sign-extended byte tiled out as four shorts. 3814 3815@item Q 3816Integer constant that fits in one signed byte when incremented 3817(@minus{}129 @dots{} 126), but excluding -1. 3818 3819@item S 3820Integer constant that has all 1 bits consecutive and starting at bit 0. 3821 3822@item T 3823A 16-bit fragment of a got, tls, or pc-relative reference. 3824 3825@item U 3826Memory operand except postincrement. This is roughly the same as 3827@samp{m} when not used together with @samp{<} or @samp{>}. 3828 3829@item W 3830An 8-element vector constant with identical elements. 3831 3832@item Y 3833A 4-element vector constant with identical elements. 3834 3835@item Z0 3836The integer constant 0xffffffff. 3837 3838@item Z1 3839The integer constant 0xffffffff00000000. 3840 3841@end table 3842 3843@item TILEPro---@file{config/tilepro/constraints.md} 3844@table @code 3845@item R00 3846@itemx R01 3847@itemx R02 3848@itemx R03 3849@itemx R04 3850@itemx R05 3851@itemx R06 3852@itemx R07 3853@itemx R08 3854@itemx R09 3855@itemx R10 3856Each of these represents a register constraint for an individual 3857register, from r0 to r10. 3858 3859@item I 3860Signed 8-bit integer constant. 3861 3862@item J 3863Signed 16-bit integer constant. 3864 3865@item K 3866Nonzero integer constant with low 16 bits zero. 3867 3868@item L 3869Integer constant that fits in one signed byte when incremented by one 3870(@minus{}129 @dots{} 126). 3871 3872@item m 3873Memory operand. If used together with @samp{<} or @samp{>}, the 3874operand can have postincrement which requires printing with @samp{%In} 3875and @samp{%in} on TILEPro. For example: 3876 3877@smallexample 3878asm ("swadd %I0,%1,%i0" : "=m<>" (mem) : "r" (val)); 3879@end smallexample 3880 3881@item M 3882A bit mask suitable for the MM instruction. 3883 3884@item N 3885Integer constant that is a byte tiled out four times. 3886 3887@item O 3888The integer zero constant. 3889 3890@item P 3891Integer constant that is a sign-extended byte tiled out as two shorts. 3892 3893@item Q 3894Integer constant that fits in one signed byte when incremented 3895(@minus{}129 @dots{} 126), but excluding -1. 3896 3897@item T 3898A symbolic operand, or a 16-bit fragment of a got, tls, or pc-relative 3899reference. 3900 3901@item U 3902Memory operand except postincrement. This is roughly the same as 3903@samp{m} when not used together with @samp{<} or @samp{>}. 3904 3905@item W 3906A 4-element vector constant with identical elements. 3907 3908@item Y 3909A 2-element vector constant with identical elements. 3910 3911@end table 3912 3913@item Visium---@file{config/visium/constraints.md} 3914@table @code 3915@item b 3916EAM register @code{mdb} 3917 3918@item c 3919EAM register @code{mdc} 3920 3921@item f 3922Floating point register 3923 3924@ifset INTERNALS 3925@item k 3926Register for sibcall optimization 3927@end ifset 3928 3929@item l 3930General register, but not @code{r29}, @code{r30} and @code{r31} 3931 3932@item t 3933Register @code{r1} 3934 3935@item u 3936Register @code{r2} 3937 3938@item v 3939Register @code{r3} 3940 3941@item G 3942Floating-point constant 0.0 3943 3944@item J 3945Integer constant in the range 0 .. 65535 (16-bit immediate) 3946 3947@item K 3948Integer constant in the range 1 .. 31 (5-bit immediate) 3949 3950@item L 3951Integer constant in the range @minus{}65535 .. @minus{}1 (16-bit negative immediate) 3952 3953@item M 3954Integer constant @minus{}1 3955 3956@item O 3957Integer constant 0 3958 3959@item P 3960Integer constant 32 3961@end table 3962 3963@item x86 family---@file{config/i386/constraints.md} 3964@table @code 3965@item R 3966Legacy register---the eight integer registers available on all 3967i386 processors (@code{a}, @code{b}, @code{c}, @code{d}, 3968@code{si}, @code{di}, @code{bp}, @code{sp}). 3969 3970@item q 3971Any register accessible as @code{@var{r}l}. In 32-bit mode, @code{a}, 3972@code{b}, @code{c}, and @code{d}; in 64-bit mode, any integer register. 3973 3974@item Q 3975Any register accessible as @code{@var{r}h}: @code{a}, @code{b}, 3976@code{c}, and @code{d}. 3977 3978@ifset INTERNALS 3979@item l 3980Any register that can be used as the index in a base+index memory 3981access: that is, any general register except the stack pointer. 3982@end ifset 3983 3984@item a 3985The @code{a} register. 3986 3987@item b 3988The @code{b} register. 3989 3990@item c 3991The @code{c} register. 3992 3993@item d 3994The @code{d} register. 3995 3996@item S 3997The @code{si} register. 3998 3999@item D 4000The @code{di} register. 4001 4002@item A 4003The @code{a} and @code{d} registers. This class is used for instructions 4004that return double word results in the @code{ax:dx} register pair. Single 4005word values will be allocated either in @code{ax} or @code{dx}. 4006For example on i386 the following implements @code{rdtsc}: 4007 4008@smallexample 4009unsigned long long rdtsc (void) 4010@{ 4011 unsigned long long tick; 4012 __asm__ __volatile__("rdtsc":"=A"(tick)); 4013 return tick; 4014@} 4015@end smallexample 4016 4017This is not correct on x86-64 as it would allocate tick in either @code{ax} 4018or @code{dx}. You have to use the following variant instead: 4019 4020@smallexample 4021unsigned long long rdtsc (void) 4022@{ 4023 unsigned int tickl, tickh; 4024 __asm__ __volatile__("rdtsc":"=a"(tickl),"=d"(tickh)); 4025 return ((unsigned long long)tickh << 32)|tickl; 4026@} 4027@end smallexample 4028 4029@item U 4030The call-clobbered integer registers. 4031 4032@item f 4033Any 80387 floating-point (stack) register. 4034 4035@item t 4036Top of 80387 floating-point stack (@code{%st(0)}). 4037 4038@item u 4039Second from top of 80387 floating-point stack (@code{%st(1)}). 4040 4041@ifset INTERNALS 4042@item Yk 4043Any mask register that can be used as a predicate, i.e. @code{k1-k7}. 4044 4045@item k 4046Any mask register. 4047@end ifset 4048 4049@item y 4050Any MMX register. 4051 4052@item x 4053Any SSE register. 4054 4055@item v 4056Any EVEX encodable SSE register (@code{%xmm0-%xmm31}). 4057 4058@ifset INTERNALS 4059@item w 4060Any bound register. 4061@end ifset 4062 4063@item Yz 4064First SSE register (@code{%xmm0}). 4065 4066@ifset INTERNALS 4067@item Yi 4068Any SSE register, when SSE2 and inter-unit moves are enabled. 4069 4070@item Yj 4071Any SSE register, when SSE2 and inter-unit moves from vector registers are enabled. 4072 4073@item Ym 4074Any MMX register, when inter-unit moves are enabled. 4075 4076@item Yn 4077Any MMX register, when inter-unit moves from vector registers are enabled. 4078 4079@item Yp 4080Any integer register when @code{TARGET_PARTIAL_REG_STALL} is disabled. 4081 4082@item Ya 4083Any integer register when zero extensions with @code{AND} are disabled. 4084 4085@item Yb 4086Any register that can be used as the GOT base when calling@* 4087@code{___tls_get_addr}: that is, any general register except @code{a} 4088and @code{sp} registers, for @option{-fno-plt} if linker supports it. 4089Otherwise, @code{b} register. 4090 4091@item Yf 4092Any x87 register when 80387 floating-point arithmetic is enabled. 4093 4094@item Yr 4095Lower SSE register when avoiding REX prefix and all SSE registers otherwise. 4096 4097@item Yv 4098For AVX512VL, any EVEX-encodable SSE register (@code{%xmm0-%xmm31}), 4099otherwise any SSE register. 4100 4101@item Yh 4102Any EVEX-encodable SSE register, that has number factor of four. 4103 4104@item Bf 4105Flags register operand. 4106 4107@item Bg 4108GOT memory operand. 4109 4110@item Bm 4111Vector memory operand. 4112 4113@item Bc 4114Constant memory operand. 4115 4116@item Bn 4117Memory operand without REX prefix. 4118 4119@item Bs 4120Sibcall memory operand. 4121 4122@item Bw 4123Call memory operand. 4124 4125@item Bz 4126Constant call address operand. 4127 4128@item BC 4129SSE constant -1 operand. 4130@end ifset 4131 4132@item I 4133Integer constant in the range 0 @dots{} 31, for 32-bit shifts. 4134 4135@item J 4136Integer constant in the range 0 @dots{} 63, for 64-bit shifts. 4137 4138@item K 4139Signed 8-bit integer constant. 4140 4141@item L 4142@code{0xFF} or @code{0xFFFF}, for andsi as a zero-extending move. 4143 4144@item M 41450, 1, 2, or 3 (shifts for the @code{lea} instruction). 4146 4147@item N 4148Unsigned 8-bit integer constant (for @code{in} and @code{out} 4149instructions). 4150 4151@ifset INTERNALS 4152@item O 4153Integer constant in the range 0 @dots{} 127, for 128-bit shifts. 4154@end ifset 4155 4156@item G 4157Standard 80387 floating point constant. 4158 4159@item C 4160SSE constant zero operand. 4161 4162@item e 416332-bit signed integer constant, or a symbolic reference known 4164to fit that range (for immediate operands in sign-extending x86-64 4165instructions). 4166 4167@item We 416832-bit signed integer constant, or a symbolic reference known 4169to fit that range (for sign-extending conversion operations that 4170require non-@code{VOIDmode} immediate operands). 4171 4172@item Wz 417332-bit unsigned integer constant, or a symbolic reference known 4174to fit that range (for zero-extending conversion operations that 4175require non-@code{VOIDmode} immediate operands). 4176 4177@item Wd 4178128-bit integer constant where both the high and low 64-bit word 4179satisfy the @code{e} constraint. 4180 4181@item Z 418232-bit unsigned integer constant, or a symbolic reference known 4183to fit that range (for immediate operands in zero-extending x86-64 4184instructions). 4185 4186@item Tv 4187VSIB address operand. 4188 4189@item Ts 4190Address operand without segment register. 4191 4192@item Ti 4193MPX address operand without index. 4194 4195@item Tb 4196MPX address operand without base. 4197 4198@end table 4199 4200@item Xstormy16---@file{config/stormy16/stormy16.h} 4201@table @code 4202@item a 4203Register r0. 4204 4205@item b 4206Register r1. 4207 4208@item c 4209Register r2. 4210 4211@item d 4212Register r8. 4213 4214@item e 4215Registers r0 through r7. 4216 4217@item t 4218Registers r0 and r1. 4219 4220@item y 4221The carry register. 4222 4223@item z 4224Registers r8 and r9. 4225 4226@item I 4227A constant between 0 and 3 inclusive. 4228 4229@item J 4230A constant that has exactly one bit set. 4231 4232@item K 4233A constant that has exactly one bit clear. 4234 4235@item L 4236A constant between 0 and 255 inclusive. 4237 4238@item M 4239A constant between @minus{}255 and 0 inclusive. 4240 4241@item N 4242A constant between @minus{}3 and 0 inclusive. 4243 4244@item O 4245A constant between 1 and 4 inclusive. 4246 4247@item P 4248A constant between @minus{}4 and @minus{}1 inclusive. 4249 4250@item Q 4251A memory reference that is a stack push. 4252 4253@item R 4254A memory reference that is a stack pop. 4255 4256@item S 4257A memory reference that refers to a constant address of known value. 4258 4259@item T 4260The register indicated by Rx (not implemented yet). 4261 4262@item U 4263A constant that is not between 2 and 15 inclusive. 4264 4265@item Z 4266The constant 0. 4267 4268@end table 4269 4270@item Xtensa---@file{config/xtensa/constraints.md} 4271@table @code 4272@item a 4273General-purpose 32-bit register 4274 4275@item b 4276One-bit boolean register 4277 4278@item A 4279MAC16 40-bit accumulator register 4280 4281@item I 4282Signed 12-bit integer constant, for use in MOVI instructions 4283 4284@item J 4285Signed 8-bit integer constant, for use in ADDI instructions 4286 4287@item K 4288Integer constant valid for BccI instructions 4289 4290@item L 4291Unsigned constant valid for BccUI instructions 4292 4293@end table 4294 4295@end table 4296 4297@ifset INTERNALS 4298@node Disable Insn Alternatives 4299@subsection Disable insn alternatives using the @code{enabled} attribute 4300@cindex enabled 4301 4302There are three insn attributes that may be used to selectively disable 4303instruction alternatives: 4304 4305@table @code 4306@item enabled 4307Says whether an alternative is available on the current subtarget. 4308 4309@item preferred_for_size 4310Says whether an enabled alternative should be used in code that is 4311optimized for size. 4312 4313@item preferred_for_speed 4314Says whether an enabled alternative should be used in code that is 4315optimized for speed. 4316@end table 4317 4318All these attributes should use @code{(const_int 1)} to allow an alternative 4319or @code{(const_int 0)} to disallow it. The attributes must be a static 4320property of the subtarget; they cannot for example depend on the 4321current operands, on the current optimization level, on the location 4322of the insn within the body of a loop, on whether register allocation 4323has finished, or on the current compiler pass. 4324 4325The @code{enabled} attribute is a correctness property. It tells GCC to act 4326as though the disabled alternatives were never defined in the first place. 4327This is useful when adding new instructions to an existing pattern in 4328cases where the new instructions are only available for certain cpu 4329architecture levels (typically mapped to the @code{-march=} command-line 4330option). 4331 4332In contrast, the @code{preferred_for_size} and @code{preferred_for_speed} 4333attributes are strong optimization hints rather than correctness properties. 4334@code{preferred_for_size} tells GCC which alternatives to consider when 4335adding or modifying an instruction that GCC wants to optimize for size. 4336@code{preferred_for_speed} does the same thing for speed. Note that things 4337like code motion can lead to cases where code optimized for size uses 4338alternatives that are not preferred for size, and similarly for speed. 4339 4340Although @code{define_insn}s can in principle specify the @code{enabled} 4341attribute directly, it is often clearer to have subsiduary attributes 4342for each architectural feature of interest. The @code{define_insn}s 4343can then use these subsiduary attributes to say which alternatives 4344require which features. The example below does this for @code{cpu_facility}. 4345 4346E.g. the following two patterns could easily be merged using the @code{enabled} 4347attribute: 4348 4349@smallexample 4350 4351(define_insn "*movdi_old" 4352 [(set (match_operand:DI 0 "register_operand" "=d") 4353 (match_operand:DI 1 "register_operand" " d"))] 4354 "!TARGET_NEW" 4355 "lgr %0,%1") 4356 4357(define_insn "*movdi_new" 4358 [(set (match_operand:DI 0 "register_operand" "=d,f,d") 4359 (match_operand:DI 1 "register_operand" " d,d,f"))] 4360 "TARGET_NEW" 4361 "@@ 4362 lgr %0,%1 4363 ldgr %0,%1 4364 lgdr %0,%1") 4365 4366@end smallexample 4367 4368to: 4369 4370@smallexample 4371 4372(define_insn "*movdi_combined" 4373 [(set (match_operand:DI 0 "register_operand" "=d,f,d") 4374 (match_operand:DI 1 "register_operand" " d,d,f"))] 4375 "" 4376 "@@ 4377 lgr %0,%1 4378 ldgr %0,%1 4379 lgdr %0,%1" 4380 [(set_attr "cpu_facility" "*,new,new")]) 4381 4382@end smallexample 4383 4384with the @code{enabled} attribute defined like this: 4385 4386@smallexample 4387 4388(define_attr "cpu_facility" "standard,new" (const_string "standard")) 4389 4390(define_attr "enabled" "" 4391 (cond [(eq_attr "cpu_facility" "standard") (const_int 1) 4392 (and (eq_attr "cpu_facility" "new") 4393 (ne (symbol_ref "TARGET_NEW") (const_int 0))) 4394 (const_int 1)] 4395 (const_int 0))) 4396 4397@end smallexample 4398 4399@end ifset 4400 4401@ifset INTERNALS 4402@node Define Constraints 4403@subsection Defining Machine-Specific Constraints 4404@cindex defining constraints 4405@cindex constraints, defining 4406 4407Machine-specific constraints fall into two categories: register and 4408non-register constraints. Within the latter category, constraints 4409which allow subsets of all possible memory or address operands should 4410be specially marked, to give @code{reload} more information. 4411 4412Machine-specific constraints can be given names of arbitrary length, 4413but they must be entirely composed of letters, digits, underscores 4414(@samp{_}), and angle brackets (@samp{< >}). Like C identifiers, they 4415must begin with a letter or underscore. 4416 4417In order to avoid ambiguity in operand constraint strings, no 4418constraint can have a name that begins with any other constraint's 4419name. For example, if @code{x} is defined as a constraint name, 4420@code{xy} may not be, and vice versa. As a consequence of this rule, 4421no constraint may begin with one of the generic constraint letters: 4422@samp{E F V X g i m n o p r s}. 4423 4424Register constraints correspond directly to register classes. 4425@xref{Register Classes}. There is thus not much flexibility in their 4426definitions. 4427 4428@deffn {MD Expression} define_register_constraint name regclass docstring 4429All three arguments are string constants. 4430@var{name} is the name of the constraint, as it will appear in 4431@code{match_operand} expressions. If @var{name} is a multi-letter 4432constraint its length shall be the same for all constraints starting 4433with the same letter. @var{regclass} can be either the 4434name of the corresponding register class (@pxref{Register Classes}), 4435or a C expression which evaluates to the appropriate register class. 4436If it is an expression, it must have no side effects, and it cannot 4437look at the operand. The usual use of expressions is to map some 4438register constraints to @code{NO_REGS} when the register class 4439is not available on a given subarchitecture. 4440 4441@var{docstring} is a sentence documenting the meaning of the 4442constraint. Docstrings are explained further below. 4443@end deffn 4444 4445Non-register constraints are more like predicates: the constraint 4446definition gives a boolean expression which indicates whether the 4447constraint matches. 4448 4449@deffn {MD Expression} define_constraint name docstring exp 4450The @var{name} and @var{docstring} arguments are the same as for 4451@code{define_register_constraint}, but note that the docstring comes 4452immediately after the name for these expressions. @var{exp} is an RTL 4453expression, obeying the same rules as the RTL expressions in predicate 4454definitions. @xref{Defining Predicates}, for details. If it 4455evaluates true, the constraint matches; if it evaluates false, it 4456doesn't. Constraint expressions should indicate which RTL codes they 4457might match, just like predicate expressions. 4458 4459@code{match_test} C expressions have access to the 4460following variables: 4461 4462@table @var 4463@item op 4464The RTL object defining the operand. 4465@item mode 4466The machine mode of @var{op}. 4467@item ival 4468@samp{INTVAL (@var{op})}, if @var{op} is a @code{const_int}. 4469@item hval 4470@samp{CONST_DOUBLE_HIGH (@var{op})}, if @var{op} is an integer 4471@code{const_double}. 4472@item lval 4473@samp{CONST_DOUBLE_LOW (@var{op})}, if @var{op} is an integer 4474@code{const_double}. 4475@item rval 4476@samp{CONST_DOUBLE_REAL_VALUE (@var{op})}, if @var{op} is a floating-point 4477@code{const_double}. 4478@end table 4479 4480The @var{*val} variables should only be used once another piece of the 4481expression has verified that @var{op} is the appropriate kind of RTL 4482object. 4483@end deffn 4484 4485Most non-register constraints should be defined with 4486@code{define_constraint}. The remaining two definition expressions 4487are only appropriate for constraints that should be handled specially 4488by @code{reload} if they fail to match. 4489 4490@deffn {MD Expression} define_memory_constraint name docstring exp 4491Use this expression for constraints that match a subset of all memory 4492operands: that is, @code{reload} can make them match by converting the 4493operand to the form @samp{@w{(mem (reg @var{X}))}}, where @var{X} is a 4494base register (from the register class specified by 4495@code{BASE_REG_CLASS}, @pxref{Register Classes}). 4496 4497For example, on the S/390, some instructions do not accept arbitrary 4498memory references, but only those that do not make use of an index 4499register. The constraint letter @samp{Q} is defined to represent a 4500memory address of this type. If @samp{Q} is defined with 4501@code{define_memory_constraint}, a @samp{Q} constraint can handle any 4502memory operand, because @code{reload} knows it can simply copy the 4503memory address into a base register if required. This is analogous to 4504the way an @samp{o} constraint can handle any memory operand. 4505 4506The syntax and semantics are otherwise identical to 4507@code{define_constraint}. 4508@end deffn 4509 4510@deffn {MD Expression} define_special_memory_constraint name docstring exp 4511Use this expression for constraints that match a subset of all memory 4512operands: that is, @code{reload} can not make them match by reloading 4513the address as it is described for @code{define_memory_constraint} or 4514such address reload is undesirable with the performance point of view. 4515 4516For example, @code{define_special_memory_constraint} can be useful if 4517specifically aligned memory is necessary or desirable for some insn 4518operand. 4519 4520The syntax and semantics are otherwise identical to 4521@code{define_constraint}. 4522@end deffn 4523 4524@deffn {MD Expression} define_address_constraint name docstring exp 4525Use this expression for constraints that match a subset of all address 4526operands: that is, @code{reload} can make the constraint match by 4527converting the operand to the form @samp{@w{(reg @var{X})}}, again 4528with @var{X} a base register. 4529 4530Constraints defined with @code{define_address_constraint} can only be 4531used with the @code{address_operand} predicate, or machine-specific 4532predicates that work the same way. They are treated analogously to 4533the generic @samp{p} constraint. 4534 4535The syntax and semantics are otherwise identical to 4536@code{define_constraint}. 4537@end deffn 4538 4539For historical reasons, names beginning with the letters @samp{G H} 4540are reserved for constraints that match only @code{const_double}s, and 4541names beginning with the letters @samp{I J K L M N O P} are reserved 4542for constraints that match only @code{const_int}s. This may change in 4543the future. For the time being, constraints with these names must be 4544written in a stylized form, so that @code{genpreds} can tell you did 4545it correctly: 4546 4547@smallexample 4548@group 4549(define_constraint "[@var{GHIJKLMNOP}]@dots{}" 4550 "@var{doc}@dots{}" 4551 (and (match_code "const_int") ; @r{@code{const_double} for G/H} 4552 @var{condition}@dots{})) ; @r{usually a @code{match_test}} 4553@end group 4554@end smallexample 4555@c the semicolons line up in the formatted manual 4556 4557It is fine to use names beginning with other letters for constraints 4558that match @code{const_double}s or @code{const_int}s. 4559 4560Each docstring in a constraint definition should be one or more complete 4561sentences, marked up in Texinfo format. @emph{They are currently unused.} 4562In the future they will be copied into the GCC manual, in @ref{Machine 4563Constraints}, replacing the hand-maintained tables currently found in 4564that section. Also, in the future the compiler may use this to give 4565more helpful diagnostics when poor choice of @code{asm} constraints 4566causes a reload failure. 4567 4568If you put the pseudo-Texinfo directive @samp{@@internal} at the 4569beginning of a docstring, then (in the future) it will appear only in 4570the internals manual's version of the machine-specific constraint tables. 4571Use this for constraints that should not appear in @code{asm} statements. 4572 4573@node C Constraint Interface 4574@subsection Testing constraints from C 4575@cindex testing constraints 4576@cindex constraints, testing 4577 4578It is occasionally useful to test a constraint from C code rather than 4579implicitly via the constraint string in a @code{match_operand}. The 4580generated file @file{tm_p.h} declares a few interfaces for working 4581with constraints. At present these are defined for all constraints 4582except @code{g} (which is equivalent to @code{general_operand}). 4583 4584Some valid constraint names are not valid C identifiers, so there is a 4585mangling scheme for referring to them from C@. Constraint names that 4586do not contain angle brackets or underscores are left unchanged. 4587Underscores are doubled, each @samp{<} is replaced with @samp{_l}, and 4588each @samp{>} with @samp{_g}. Here are some examples: 4589 4590@c the @c's prevent double blank lines in the printed manual. 4591@example 4592@multitable {Original} {Mangled} 4593@item @strong{Original} @tab @strong{Mangled} @c 4594@item @code{x} @tab @code{x} @c 4595@item @code{P42x} @tab @code{P42x} @c 4596@item @code{P4_x} @tab @code{P4__x} @c 4597@item @code{P4>x} @tab @code{P4_gx} @c 4598@item @code{P4>>} @tab @code{P4_g_g} @c 4599@item @code{P4_g>} @tab @code{P4__g_g} @c 4600@end multitable 4601@end example 4602 4603Throughout this section, the variable @var{c} is either a constraint 4604in the abstract sense, or a constant from @code{enum constraint_num}; 4605the variable @var{m} is a mangled constraint name (usually as part of 4606a larger identifier). 4607 4608@deftp Enum constraint_num 4609For each constraint except @code{g}, there is a corresponding 4610enumeration constant: @samp{CONSTRAINT_} plus the mangled name of the 4611constraint. Functions that take an @code{enum constraint_num} as an 4612argument expect one of these constants. 4613@end deftp 4614 4615@deftypefun {inline bool} satisfies_constraint_@var{m} (rtx @var{exp}) 4616For each non-register constraint @var{m} except @code{g}, there is 4617one of these functions; it returns @code{true} if @var{exp} satisfies the 4618constraint. These functions are only visible if @file{rtl.h} was included 4619before @file{tm_p.h}. 4620@end deftypefun 4621 4622@deftypefun bool constraint_satisfied_p (rtx @var{exp}, enum constraint_num @var{c}) 4623Like the @code{satisfies_constraint_@var{m}} functions, but the 4624constraint to test is given as an argument, @var{c}. If @var{c} 4625specifies a register constraint, this function will always return 4626@code{false}. 4627@end deftypefun 4628 4629@deftypefun {enum reg_class} reg_class_for_constraint (enum constraint_num @var{c}) 4630Returns the register class associated with @var{c}. If @var{c} is not 4631a register constraint, or those registers are not available for the 4632currently selected subtarget, returns @code{NO_REGS}. 4633@end deftypefun 4634 4635Here is an example use of @code{satisfies_constraint_@var{m}}. In 4636peephole optimizations (@pxref{Peephole Definitions}), operand 4637constraint strings are ignored, so if there are relevant constraints, 4638they must be tested in the C condition. In the example, the 4639optimization is applied if operand 2 does @emph{not} satisfy the 4640@samp{K} constraint. (This is a simplified version of a peephole 4641definition from the i386 machine description.) 4642 4643@smallexample 4644(define_peephole2 4645 [(match_scratch:SI 3 "r") 4646 (set (match_operand:SI 0 "register_operand" "") 4647 (mult:SI (match_operand:SI 1 "memory_operand" "") 4648 (match_operand:SI 2 "immediate_operand" "")))] 4649 4650 "!satisfies_constraint_K (operands[2])" 4651 4652 [(set (match_dup 3) (match_dup 1)) 4653 (set (match_dup 0) (mult:SI (match_dup 3) (match_dup 2)))] 4654 4655 "") 4656@end smallexample 4657 4658@node Standard Names 4659@section Standard Pattern Names For Generation 4660@cindex standard pattern names 4661@cindex pattern names 4662@cindex names, pattern 4663 4664Here is a table of the instruction names that are meaningful in the RTL 4665generation pass of the compiler. Giving one of these names to an 4666instruction pattern tells the RTL generation pass that it can use the 4667pattern to accomplish a certain task. 4668 4669@table @asis 4670@cindex @code{mov@var{m}} instruction pattern 4671@item @samp{mov@var{m}} 4672Here @var{m} stands for a two-letter machine mode name, in lowercase. 4673This instruction pattern moves data with that machine mode from operand 46741 to operand 0. For example, @samp{movsi} moves full-word data. 4675 4676If operand 0 is a @code{subreg} with mode @var{m} of a register whose 4677own mode is wider than @var{m}, the effect of this instruction is 4678to store the specified value in the part of the register that corresponds 4679to mode @var{m}. Bits outside of @var{m}, but which are within the 4680same target word as the @code{subreg} are undefined. Bits which are 4681outside the target word are left unchanged. 4682 4683This class of patterns is special in several ways. First of all, each 4684of these names up to and including full word size @emph{must} be defined, 4685because there is no other way to copy a datum from one place to another. 4686If there are patterns accepting operands in larger modes, 4687@samp{mov@var{m}} must be defined for integer modes of those sizes. 4688 4689Second, these patterns are not used solely in the RTL generation pass. 4690Even the reload pass can generate move insns to copy values from stack 4691slots into temporary registers. When it does so, one of the operands is 4692a hard register and the other is an operand that can need to be reloaded 4693into a register. 4694 4695@findex force_reg 4696Therefore, when given such a pair of operands, the pattern must generate 4697RTL which needs no reloading and needs no temporary registers---no 4698registers other than the operands. For example, if you support the 4699pattern with a @code{define_expand}, then in such a case the 4700@code{define_expand} mustn't call @code{force_reg} or any other such 4701function which might generate new pseudo registers. 4702 4703This requirement exists even for subword modes on a RISC machine where 4704fetching those modes from memory normally requires several insns and 4705some temporary registers. 4706 4707@findex change_address 4708During reload a memory reference with an invalid address may be passed 4709as an operand. Such an address will be replaced with a valid address 4710later in the reload pass. In this case, nothing may be done with the 4711address except to use it as it stands. If it is copied, it will not be 4712replaced with a valid address. No attempt should be made to make such 4713an address into a valid address and no routine (such as 4714@code{change_address}) that will do so may be called. Note that 4715@code{general_operand} will fail when applied to such an address. 4716 4717@findex reload_in_progress 4718The global variable @code{reload_in_progress} (which must be explicitly 4719declared if required) can be used to determine whether such special 4720handling is required. 4721 4722The variety of operands that have reloads depends on the rest of the 4723machine description, but typically on a RISC machine these can only be 4724pseudo registers that did not get hard registers, while on other 4725machines explicit memory references will get optional reloads. 4726 4727If a scratch register is required to move an object to or from memory, 4728it can be allocated using @code{gen_reg_rtx} prior to life analysis. 4729 4730If there are cases which need scratch registers during or after reload, 4731you must provide an appropriate secondary_reload target hook. 4732 4733@findex can_create_pseudo_p 4734The macro @code{can_create_pseudo_p} can be used to determine if it 4735is unsafe to create new pseudo registers. If this variable is nonzero, then 4736it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo. 4737 4738The constraints on a @samp{mov@var{m}} must permit moving any hard 4739register to any other hard register provided that 4740@code{TARGET_HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and 4741@code{TARGET_REGISTER_MOVE_COST} applied to their classes returns a value 4742of 2. 4743 4744It is obligatory to support floating point @samp{mov@var{m}} 4745instructions into and out of any registers that can hold fixed point 4746values, because unions and structures (which have modes @code{SImode} or 4747@code{DImode}) can be in those registers and they may have floating 4748point members. 4749 4750There may also be a need to support fixed point @samp{mov@var{m}} 4751instructions in and out of floating point registers. Unfortunately, I 4752have forgotten why this was so, and I don't know whether it is still 4753true. If @code{TARGET_HARD_REGNO_MODE_OK} rejects fixed point values in 4754floating point registers, then the constraints of the fixed point 4755@samp{mov@var{m}} instructions must be designed to avoid ever trying to 4756reload into a floating point register. 4757 4758@cindex @code{reload_in} instruction pattern 4759@cindex @code{reload_out} instruction pattern 4760@item @samp{reload_in@var{m}} 4761@itemx @samp{reload_out@var{m}} 4762These named patterns have been obsoleted by the target hook 4763@code{secondary_reload}. 4764 4765Like @samp{mov@var{m}}, but used when a scratch register is required to 4766move between operand 0 and operand 1. Operand 2 describes the scratch 4767register. See the discussion of the @code{SECONDARY_RELOAD_CLASS} 4768macro in @pxref{Register Classes}. 4769 4770There are special restrictions on the form of the @code{match_operand}s 4771used in these patterns. First, only the predicate for the reload 4772operand is examined, i.e., @code{reload_in} examines operand 1, but not 4773the predicates for operand 0 or 2. Second, there may be only one 4774alternative in the constraints. Third, only a single register class 4775letter may be used for the constraint; subsequent constraint letters 4776are ignored. As a special exception, an empty constraint string 4777matches the @code{ALL_REGS} register class. This may relieve ports 4778of the burden of defining an @code{ALL_REGS} constraint letter just 4779for these patterns. 4780 4781@cindex @code{movstrict@var{m}} instruction pattern 4782@item @samp{movstrict@var{m}} 4783Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg} 4784with mode @var{m} of a register whose natural mode is wider, 4785the @samp{movstrict@var{m}} instruction is guaranteed not to alter 4786any of the register except the part which belongs to mode @var{m}. 4787 4788@cindex @code{movmisalign@var{m}} instruction pattern 4789@item @samp{movmisalign@var{m}} 4790This variant of a move pattern is designed to load or store a value 4791from a memory address that is not naturally aligned for its mode. 4792For a store, the memory will be in operand 0; for a load, the memory 4793will be in operand 1. The other operand is guaranteed not to be a 4794memory, so that it's easy to tell whether this is a load or store. 4795 4796This pattern is used by the autovectorizer, and when expanding a 4797@code{MISALIGNED_INDIRECT_REF} expression. 4798 4799@cindex @code{load_multiple} instruction pattern 4800@item @samp{load_multiple} 4801Load several consecutive memory locations into consecutive registers. 4802Operand 0 is the first of the consecutive registers, operand 1 4803is the first memory location, and operand 2 is a constant: the 4804number of consecutive registers. 4805 4806Define this only if the target machine really has such an instruction; 4807do not define this if the most efficient way of loading consecutive 4808registers from memory is to do them one at a time. 4809 4810On some machines, there are restrictions as to which consecutive 4811registers can be stored into memory, such as particular starting or 4812ending register numbers or only a range of valid counts. For those 4813machines, use a @code{define_expand} (@pxref{Expander Definitions}) 4814and make the pattern fail if the restrictions are not met. 4815 4816Write the generated insn as a @code{parallel} with elements being a 4817@code{set} of one register from the appropriate memory location (you may 4818also need @code{use} or @code{clobber} elements). Use a 4819@code{match_parallel} (@pxref{RTL Template}) to recognize the insn. See 4820@file{rs6000.md} for examples of the use of this insn pattern. 4821 4822@cindex @samp{store_multiple} instruction pattern 4823@item @samp{store_multiple} 4824Similar to @samp{load_multiple}, but store several consecutive registers 4825into consecutive memory locations. Operand 0 is the first of the 4826consecutive memory locations, operand 1 is the first register, and 4827operand 2 is a constant: the number of consecutive registers. 4828 4829@cindex @code{vec_load_lanes@var{m}@var{n}} instruction pattern 4830@item @samp{vec_load_lanes@var{m}@var{n}} 4831Perform an interleaved load of several vectors from memory operand 1 4832into register operand 0. Both operands have mode @var{m}. The register 4833operand is viewed as holding consecutive vectors of mode @var{n}, 4834while the memory operand is a flat array that contains the same number 4835of elements. The operation is equivalent to: 4836 4837@smallexample 4838int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4839for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4840 for (i = 0; i < c; i++) 4841 operand0[i][j] = operand1[j * c + i]; 4842@end smallexample 4843 4844For example, @samp{vec_load_lanestiv4hi} loads 8 16-bit values 4845from memory into a register of mode @samp{TI}@. The register 4846contains two consecutive vectors of mode @samp{V4HI}@. 4847 4848This pattern can only be used if: 4849@smallexample 4850TARGET_ARRAY_MODE_SUPPORTED_P (@var{n}, @var{c}) 4851@end smallexample 4852is true. GCC assumes that, if a target supports this kind of 4853instruction for some mode @var{n}, it also supports unaligned 4854loads for vectors of mode @var{n}. 4855 4856This pattern is not allowed to @code{FAIL}. 4857 4858@cindex @code{vec_mask_load_lanes@var{m}@var{n}} instruction pattern 4859@item @samp{vec_mask_load_lanes@var{m}@var{n}} 4860Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional 4861mask operand (operand 2) that specifies which elements of the destination 4862vectors should be loaded. Other elements of the destination 4863vectors are set to zero. The operation is equivalent to: 4864 4865@smallexample 4866int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4867for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4868 if (operand2[j]) 4869 for (i = 0; i < c; i++) 4870 operand0[i][j] = operand1[j * c + i]; 4871 else 4872 for (i = 0; i < c; i++) 4873 operand0[i][j] = 0; 4874@end smallexample 4875 4876This pattern is not allowed to @code{FAIL}. 4877 4878@cindex @code{vec_store_lanes@var{m}@var{n}} instruction pattern 4879@item @samp{vec_store_lanes@var{m}@var{n}} 4880Equivalent to @samp{vec_load_lanes@var{m}@var{n}}, with the memory 4881and register operands reversed. That is, the instruction is 4882equivalent to: 4883 4884@smallexample 4885int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4886for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4887 for (i = 0; i < c; i++) 4888 operand0[j * c + i] = operand1[i][j]; 4889@end smallexample 4890 4891for a memory operand 0 and register operand 1. 4892 4893This pattern is not allowed to @code{FAIL}. 4894 4895@cindex @code{vec_mask_store_lanes@var{m}@var{n}} instruction pattern 4896@item @samp{vec_mask_store_lanes@var{m}@var{n}} 4897Like @samp{vec_store_lanes@var{m}@var{n}}, but takes an additional 4898mask operand (operand 2) that specifies which elements of the source 4899vectors should be stored. The operation is equivalent to: 4900 4901@smallexample 4902int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n}); 4903for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++) 4904 if (operand2[j]) 4905 for (i = 0; i < c; i++) 4906 operand0[j * c + i] = operand1[i][j]; 4907@end smallexample 4908 4909This pattern is not allowed to @code{FAIL}. 4910 4911@cindex @code{gather_load@var{m}} instruction pattern 4912@item @samp{gather_load@var{m}} 4913Load several separate memory locations into a vector of mode @var{m}. 4914Operand 1 is a scalar base address and operand 2 is a vector of 4915offsets from that base. Operand 0 is a destination vector with the 4916same number of elements as the offset. For each element index @var{i}: 4917 4918@itemize @bullet 4919@item 4920extend the offset element @var{i} to address width, using zero 4921extension if operand 3 is 1 and sign extension if operand 3 is zero; 4922@item 4923multiply the extended offset by operand 4; 4924@item 4925add the result to the base; and 4926@item 4927load the value at that address into element @var{i} of operand 0. 4928@end itemize 4929 4930The value of operand 3 does not matter if the offsets are already 4931address width. 4932 4933@cindex @code{mask_gather_load@var{m}} instruction pattern 4934@item @samp{mask_gather_load@var{m}} 4935Like @samp{gather_load@var{m}}, but takes an extra mask operand as 4936operand 5. Bit @var{i} of the mask is set if element @var{i} 4937of the result should be loaded from memory and clear if element @var{i} 4938of the result should be set to zero. 4939 4940@cindex @code{scatter_store@var{m}} instruction pattern 4941@item @samp{scatter_store@var{m}} 4942Store a vector of mode @var{m} into several distinct memory locations. 4943Operand 0 is a scalar base address and operand 1 is a vector of offsets 4944from that base. Operand 4 is the vector of values that should be stored, 4945which has the same number of elements as the offset. For each element 4946index @var{i}: 4947 4948@itemize @bullet 4949@item 4950extend the offset element @var{i} to address width, using zero 4951extension if operand 2 is 1 and sign extension if operand 2 is zero; 4952@item 4953multiply the extended offset by operand 3; 4954@item 4955add the result to the base; and 4956@item 4957store element @var{i} of operand 4 to that address. 4958@end itemize 4959 4960The value of operand 2 does not matter if the offsets are already 4961address width. 4962 4963@cindex @code{mask_scatter_store@var{m}} instruction pattern 4964@item @samp{mask_scatter_store@var{m}} 4965Like @samp{scatter_store@var{m}}, but takes an extra mask operand as 4966operand 5. Bit @var{i} of the mask is set if element @var{i} 4967of the result should be stored to memory. 4968 4969@cindex @code{vec_set@var{m}} instruction pattern 4970@item @samp{vec_set@var{m}} 4971Set given field in the vector value. Operand 0 is the vector to modify, 4972operand 1 is new value of field and operand 2 specify the field index. 4973 4974@cindex @code{vec_extract@var{m}@var{n}} instruction pattern 4975@item @samp{vec_extract@var{m}@var{n}} 4976Extract given field from the vector value. Operand 1 is the vector, operand 2 4977specify field index and operand 0 place to store value into. The 4978@var{n} mode is the mode of the field or vector of fields that should be 4979extracted, should be either element mode of the vector mode @var{m}, or 4980a vector mode with the same element mode and smaller number of elements. 4981If @var{n} is a vector mode, the index is counted in units of that mode. 4982 4983@cindex @code{vec_init@var{m}@var{n}} instruction pattern 4984@item @samp{vec_init@var{m}@var{n}} 4985Initialize the vector to given values. Operand 0 is the vector to initialize 4986and operand 1 is parallel containing values for individual fields. The 4987@var{n} mode is the mode of the elements, should be either element mode of 4988the vector mode @var{m}, or a vector mode with the same element mode and 4989smaller number of elements. 4990 4991@cindex @code{vec_duplicate@var{m}} instruction pattern 4992@item @samp{vec_duplicate@var{m}} 4993Initialize vector output operand 0 so that each element has the value given 4994by scalar input operand 1. The vector has mode @var{m} and the scalar has 4995the mode appropriate for one element of @var{m}. 4996 4997This pattern only handles duplicates of non-constant inputs. Constant 4998vectors go through the @code{mov@var{m}} pattern instead. 4999 5000This pattern is not allowed to @code{FAIL}. 5001 5002@cindex @code{vec_series@var{m}} instruction pattern 5003@item @samp{vec_series@var{m}} 5004Initialize vector output operand 0 so that element @var{i} is equal to 5005operand 1 plus @var{i} times operand 2. In other words, create a linear 5006series whose base value is operand 1 and whose step is operand 2. 5007 5008The vector output has mode @var{m} and the scalar inputs have the mode 5009appropriate for one element of @var{m}. This pattern is not used for 5010floating-point vectors, in order to avoid having to specify the 5011rounding behavior for @var{i} > 1. 5012 5013This pattern is not allowed to @code{FAIL}. 5014 5015@cindex @code{while_ult@var{m}@var{n}} instruction pattern 5016@item @code{while_ult@var{m}@var{n}} 5017Set operand 0 to a mask that is true while incrementing operand 1 5018gives a value that is less than operand 2. Operand 0 has mode @var{n} 5019and operands 1 and 2 are scalar integers of mode @var{m}. 5020The operation is equivalent to: 5021 5022@smallexample 5023operand0[0] = operand1 < operand2; 5024for (i = 1; i < GET_MODE_NUNITS (@var{n}); i++) 5025 operand0[i] = operand0[i - 1] && (operand1 + i < operand2); 5026@end smallexample 5027 5028@cindex @code{vec_cmp@var{m}@var{n}} instruction pattern 5029@item @samp{vec_cmp@var{m}@var{n}} 5030Output a vector comparison. Operand 0 of mode @var{n} is the destination for 5031predicate in operand 1 which is a signed vector comparison with operands of 5032mode @var{m} in operands 2 and 3. Predicate is computed by element-wise 5033evaluation of the vector comparison with a truth value of all-ones and a false 5034value of all-zeros. 5035 5036@cindex @code{vec_cmpu@var{m}@var{n}} instruction pattern 5037@item @samp{vec_cmpu@var{m}@var{n}} 5038Similar to @code{vec_cmp@var{m}@var{n}} but perform unsigned vector comparison. 5039 5040@cindex @code{vec_cmpeq@var{m}@var{n}} instruction pattern 5041@item @samp{vec_cmpeq@var{m}@var{n}} 5042Similar to @code{vec_cmp@var{m}@var{n}} but perform equality or non-equality 5043vector comparison only. If @code{vec_cmp@var{m}@var{n}} 5044or @code{vec_cmpu@var{m}@var{n}} instruction pattern is supported, 5045it will be preferred over @code{vec_cmpeq@var{m}@var{n}}, so there is 5046no need to define this instruction pattern if the others are supported. 5047 5048@cindex @code{vcond@var{m}@var{n}} instruction pattern 5049@item @samp{vcond@var{m}@var{n}} 5050Output a conditional vector move. Operand 0 is the destination to 5051receive a combination of operand 1 and operand 2, which are of mode @var{m}, 5052dependent on the outcome of the predicate in operand 3 which is a signed 5053vector comparison with operands of mode @var{n} in operands 4 and 5. The 5054modes @var{m} and @var{n} should have the same size. Operand 0 5055will be set to the value @var{op1} & @var{msk} | @var{op2} & ~@var{msk} 5056where @var{msk} is computed by element-wise evaluation of the vector 5057comparison with a truth value of all-ones and a false value of all-zeros. 5058 5059@cindex @code{vcondu@var{m}@var{n}} instruction pattern 5060@item @samp{vcondu@var{m}@var{n}} 5061Similar to @code{vcond@var{m}@var{n}} but performs unsigned vector 5062comparison. 5063 5064@cindex @code{vcondeq@var{m}@var{n}} instruction pattern 5065@item @samp{vcondeq@var{m}@var{n}} 5066Similar to @code{vcond@var{m}@var{n}} but performs equality or 5067non-equality vector comparison only. If @code{vcond@var{m}@var{n}} 5068or @code{vcondu@var{m}@var{n}} instruction pattern is supported, 5069it will be preferred over @code{vcondeq@var{m}@var{n}}, so there is 5070no need to define this instruction pattern if the others are supported. 5071 5072@cindex @code{vcond_mask_@var{m}@var{n}} instruction pattern 5073@item @samp{vcond_mask_@var{m}@var{n}} 5074Similar to @code{vcond@var{m}@var{n}} but operand 3 holds a pre-computed 5075result of vector comparison. 5076 5077@cindex @code{maskload@var{m}@var{n}} instruction pattern 5078@item @samp{maskload@var{m}@var{n}} 5079Perform a masked load of vector from memory operand 1 of mode @var{m} 5080into register operand 0. Mask is provided in register operand 2 of 5081mode @var{n}. 5082 5083This pattern is not allowed to @code{FAIL}. 5084 5085@cindex @code{maskstore@var{m}@var{n}} instruction pattern 5086@item @samp{maskstore@var{m}@var{n}} 5087Perform a masked store of vector from register operand 1 of mode @var{m} 5088into memory operand 0. Mask is provided in register operand 2 of 5089mode @var{n}. 5090 5091This pattern is not allowed to @code{FAIL}. 5092 5093@cindex @code{vec_perm@var{m}} instruction pattern 5094@item @samp{vec_perm@var{m}} 5095Output a (variable) vector permutation. Operand 0 is the destination 5096to receive elements from operand 1 and operand 2, which are of mode 5097@var{m}. Operand 3 is the @dfn{selector}. It is an integral mode 5098vector of the same width and number of elements as mode @var{m}. 5099 5100The input elements are numbered from 0 in operand 1 through 5101@math{2*@var{N}-1} in operand 2. The elements of the selector must 5102be computed modulo @math{2*@var{N}}. Note that if 5103@code{rtx_equal_p(operand1, operand2)}, this can be implemented 5104with just operand 1 and selector elements modulo @var{N}. 5105 5106In order to make things easy for a number of targets, if there is no 5107@samp{vec_perm} pattern for mode @var{m}, but there is for mode @var{q} 5108where @var{q} is a vector of @code{QImode} of the same width as @var{m}, 5109the middle-end will lower the mode @var{m} @code{VEC_PERM_EXPR} to 5110mode @var{q}. 5111 5112See also @code{TARGET_VECTORIZER_VEC_PERM_CONST}, which performs 5113the analogous operation for constant selectors. 5114 5115@cindex @code{push@var{m}1} instruction pattern 5116@item @samp{push@var{m}1} 5117Output a push instruction. Operand 0 is value to push. Used only when 5118@code{PUSH_ROUNDING} is defined. For historical reason, this pattern may be 5119missing and in such case an @code{mov} expander is used instead, with a 5120@code{MEM} expression forming the push operation. The @code{mov} expander 5121method is deprecated. 5122 5123@cindex @code{add@var{m}3} instruction pattern 5124@item @samp{add@var{m}3} 5125Add operand 2 and operand 1, storing the result in operand 0. All operands 5126must have mode @var{m}. This can be used even on two-address machines, by 5127means of constraints requiring operands 1 and 0 to be the same location. 5128 5129@cindex @code{ssadd@var{m}3} instruction pattern 5130@cindex @code{usadd@var{m}3} instruction pattern 5131@cindex @code{sub@var{m}3} instruction pattern 5132@cindex @code{sssub@var{m}3} instruction pattern 5133@cindex @code{ussub@var{m}3} instruction pattern 5134@cindex @code{mul@var{m}3} instruction pattern 5135@cindex @code{ssmul@var{m}3} instruction pattern 5136@cindex @code{usmul@var{m}3} instruction pattern 5137@cindex @code{div@var{m}3} instruction pattern 5138@cindex @code{ssdiv@var{m}3} instruction pattern 5139@cindex @code{udiv@var{m}3} instruction pattern 5140@cindex @code{usdiv@var{m}3} instruction pattern 5141@cindex @code{mod@var{m}3} instruction pattern 5142@cindex @code{umod@var{m}3} instruction pattern 5143@cindex @code{umin@var{m}3} instruction pattern 5144@cindex @code{umax@var{m}3} instruction pattern 5145@cindex @code{and@var{m}3} instruction pattern 5146@cindex @code{ior@var{m}3} instruction pattern 5147@cindex @code{xor@var{m}3} instruction pattern 5148@item @samp{ssadd@var{m}3}, @samp{usadd@var{m}3} 5149@itemx @samp{sub@var{m}3}, @samp{sssub@var{m}3}, @samp{ussub@var{m}3} 5150@itemx @samp{mul@var{m}3}, @samp{ssmul@var{m}3}, @samp{usmul@var{m}3} 5151@itemx @samp{div@var{m}3}, @samp{ssdiv@var{m}3} 5152@itemx @samp{udiv@var{m}3}, @samp{usdiv@var{m}3} 5153@itemx @samp{mod@var{m}3}, @samp{umod@var{m}3} 5154@itemx @samp{umin@var{m}3}, @samp{umax@var{m}3} 5155@itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3} 5156Similar, for other arithmetic operations. 5157 5158@cindex @code{addv@var{m}4} instruction pattern 5159@item @samp{addv@var{m}4} 5160Like @code{add@var{m}3} but takes a @code{code_label} as operand 3 and 5161emits code to jump to it if signed overflow occurs during the addition. 5162This pattern is used to implement the built-in functions performing 5163signed integer addition with overflow checking. 5164 5165@cindex @code{subv@var{m}4} instruction pattern 5166@cindex @code{mulv@var{m}4} instruction pattern 5167@item @samp{subv@var{m}4}, @samp{mulv@var{m}4} 5168Similar, for other signed arithmetic operations. 5169 5170@cindex @code{uaddv@var{m}4} instruction pattern 5171@item @samp{uaddv@var{m}4} 5172Like @code{addv@var{m}4} but for unsigned addition. That is to 5173say, the operation is the same as signed addition but the jump 5174is taken only on unsigned overflow. 5175 5176@cindex @code{usubv@var{m}4} instruction pattern 5177@cindex @code{umulv@var{m}4} instruction pattern 5178@item @samp{usubv@var{m}4}, @samp{umulv@var{m}4} 5179Similar, for other unsigned arithmetic operations. 5180 5181@cindex @code{addptr@var{m}3} instruction pattern 5182@item @samp{addptr@var{m}3} 5183Like @code{add@var{m}3} but is guaranteed to only be used for address 5184calculations. The expanded code is not allowed to clobber the 5185condition code. It only needs to be defined if @code{add@var{m}3} 5186sets the condition code. If adds used for address calculations and 5187normal adds are not compatible it is required to expand a distinct 5188pattern (e.g. using an unspec). The pattern is used by LRA to emit 5189address calculations. @code{add@var{m}3} is used if 5190@code{addptr@var{m}3} is not defined. 5191 5192@cindex @code{fma@var{m}4} instruction pattern 5193@item @samp{fma@var{m}4} 5194Multiply operand 2 and operand 1, then add operand 3, storing the 5195result in operand 0 without doing an intermediate rounding step. All 5196operands must have mode @var{m}. This pattern is used to implement 5197the @code{fma}, @code{fmaf}, and @code{fmal} builtin functions from 5198the ISO C99 standard. 5199 5200@cindex @code{fms@var{m}4} instruction pattern 5201@item @samp{fms@var{m}4} 5202Like @code{fma@var{m}4}, except operand 3 subtracted from the 5203product instead of added to the product. This is represented 5204in the rtl as 5205 5206@smallexample 5207(fma:@var{m} @var{op1} @var{op2} (neg:@var{m} @var{op3})) 5208@end smallexample 5209 5210@cindex @code{fnma@var{m}4} instruction pattern 5211@item @samp{fnma@var{m}4} 5212Like @code{fma@var{m}4} except that the intermediate product 5213is negated before being added to operand 3. This is represented 5214in the rtl as 5215 5216@smallexample 5217(fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} @var{op3}) 5218@end smallexample 5219 5220@cindex @code{fnms@var{m}4} instruction pattern 5221@item @samp{fnms@var{m}4} 5222Like @code{fms@var{m}4} except that the intermediate product 5223is negated before subtracting operand 3. This is represented 5224in the rtl as 5225 5226@smallexample 5227(fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} (neg:@var{m} @var{op3})) 5228@end smallexample 5229 5230@cindex @code{min@var{m}3} instruction pattern 5231@cindex @code{max@var{m}3} instruction pattern 5232@item @samp{smin@var{m}3}, @samp{smax@var{m}3} 5233Signed minimum and maximum operations. When used with floating point, 5234if both operands are zeros, or if either operand is @code{NaN}, then 5235it is unspecified which of the two operands is returned as the result. 5236 5237@cindex @code{fmin@var{m}3} instruction pattern 5238@cindex @code{fmax@var{m}3} instruction pattern 5239@item @samp{fmin@var{m}3}, @samp{fmax@var{m}3} 5240IEEE-conformant minimum and maximum operations. If one operand is a quiet 5241@code{NaN}, then the other operand is returned. If both operands are quiet 5242@code{NaN}, then a quiet @code{NaN} is returned. In the case when gcc supports 5243signaling @code{NaN} (-fsignaling-nans) an invalid floating point exception is 5244raised and a quiet @code{NaN} is returned. 5245 5246All operands have mode @var{m}, which is a scalar or vector 5247floating-point mode. These patterns are not allowed to @code{FAIL}. 5248 5249@cindex @code{reduc_smin_scal_@var{m}} instruction pattern 5250@cindex @code{reduc_smax_scal_@var{m}} instruction pattern 5251@item @samp{reduc_smin_scal_@var{m}}, @samp{reduc_smax_scal_@var{m}} 5252Find the signed minimum/maximum of the elements of a vector. The vector is 5253operand 1, and operand 0 is the scalar result, with mode equal to the mode of 5254the elements of the input vector. 5255 5256@cindex @code{reduc_umin_scal_@var{m}} instruction pattern 5257@cindex @code{reduc_umax_scal_@var{m}} instruction pattern 5258@item @samp{reduc_umin_scal_@var{m}}, @samp{reduc_umax_scal_@var{m}} 5259Find the unsigned minimum/maximum of the elements of a vector. The vector is 5260operand 1, and operand 0 is the scalar result, with mode equal to the mode of 5261the elements of the input vector. 5262 5263@cindex @code{reduc_plus_scal_@var{m}} instruction pattern 5264@item @samp{reduc_plus_scal_@var{m}} 5265Compute the sum of the elements of a vector. The vector is operand 1, and 5266operand 0 is the scalar result, with mode equal to the mode of the elements of 5267the input vector. 5268 5269@cindex @code{reduc_and_scal_@var{m}} instruction pattern 5270@item @samp{reduc_and_scal_@var{m}} 5271@cindex @code{reduc_ior_scal_@var{m}} instruction pattern 5272@itemx @samp{reduc_ior_scal_@var{m}} 5273@cindex @code{reduc_xor_scal_@var{m}} instruction pattern 5274@itemx @samp{reduc_xor_scal_@var{m}} 5275Compute the bitwise @code{AND}/@code{IOR}/@code{XOR} reduction of the elements 5276of a vector of mode @var{m}. Operand 1 is the vector input and operand 0 5277is the scalar result. The mode of the scalar result is the same as one 5278element of @var{m}. 5279 5280@cindex @code{extract_last_@var{m}} instruction pattern 5281@item @code{extract_last_@var{m}} 5282Find the last set bit in mask operand 1 and extract the associated element 5283of vector operand 2. Store the result in scalar operand 0. Operand 2 5284has vector mode @var{m} while operand 0 has the mode appropriate for one 5285element of @var{m}. Operand 1 has the usual mask mode for vectors of mode 5286@var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}. 5287 5288@cindex @code{fold_extract_last_@var{m}} instruction pattern 5289@item @code{fold_extract_last_@var{m}} 5290If any bits of mask operand 2 are set, find the last set bit, extract 5291the associated element from vector operand 3, and store the result 5292in operand 0. Store operand 1 in operand 0 otherwise. Operand 3 5293has mode @var{m} and operands 0 and 1 have the mode appropriate for 5294one element of @var{m}. Operand 2 has the usual mask mode for vectors 5295of mode @var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}. 5296 5297@cindex @code{fold_left_plus_@var{m}} instruction pattern 5298@item @code{fold_left_plus_@var{m}} 5299Take scalar operand 1 and successively add each element from vector 5300operand 2. Store the result in scalar operand 0. The vector has 5301mode @var{m} and the scalars have the mode appropriate for one 5302element of @var{m}. The operation is strictly in-order: there is 5303no reassociation. 5304 5305@cindex @code{sdot_prod@var{m}} instruction pattern 5306@item @samp{sdot_prod@var{m}} 5307@cindex @code{udot_prod@var{m}} instruction pattern 5308@itemx @samp{udot_prod@var{m}} 5309Compute the sum of the products of two signed/unsigned elements. 5310Operand 1 and operand 2 are of the same mode. Their product, which is of a 5311wider mode, is computed and added to operand 3. Operand 3 is of a mode equal or 5312wider than the mode of the product. The result is placed in operand 0, which 5313is of the same mode as operand 3. 5314 5315@cindex @code{ssad@var{m}} instruction pattern 5316@item @samp{ssad@var{m}} 5317@cindex @code{usad@var{m}} instruction pattern 5318@item @samp{usad@var{m}} 5319Compute the sum of absolute differences of two signed/unsigned elements. 5320Operand 1 and operand 2 are of the same mode. Their absolute difference, which 5321is of a wider mode, is computed and added to operand 3. Operand 3 is of a mode 5322equal or wider than the mode of the absolute difference. The result is placed 5323in operand 0, which is of the same mode as operand 3. 5324 5325@cindex @code{widen_ssum@var{m3}} instruction pattern 5326@item @samp{widen_ssum@var{m3}} 5327@cindex @code{widen_usum@var{m3}} instruction pattern 5328@itemx @samp{widen_usum@var{m3}} 5329Operands 0 and 2 are of the same mode, which is wider than the mode of 5330operand 1. Add operand 1 to operand 2 and place the widened result in 5331operand 0. (This is used express accumulation of elements into an accumulator 5332of a wider mode.) 5333 5334@cindex @code{vec_shl_insert_@var{m}} instruction pattern 5335@item @samp{vec_shl_insert_@var{m}} 5336Shift the elements in vector input operand 1 left one element (i.e. 5337away from element 0) and fill the vacated element 0 with the scalar 5338in operand 2. Store the result in vector output operand 0. Operands 53390 and 1 have mode @var{m} and operand 2 has the mode appropriate for 5340one element of @var{m}. 5341 5342@cindex @code{vec_shr_@var{m}} instruction pattern 5343@item @samp{vec_shr_@var{m}} 5344Whole vector right shift in bits, i.e. towards element 0. 5345Operand 1 is a vector to be shifted. 5346Operand 2 is an integer shift amount in bits. 5347Operand 0 is where the resulting shifted vector is stored. 5348The output and input vectors should have the same modes. 5349 5350@cindex @code{vec_pack_trunc_@var{m}} instruction pattern 5351@item @samp{vec_pack_trunc_@var{m}} 5352Narrow (demote) and merge the elements of two vectors. Operands 1 and 2 5353are vectors of the same mode having N integral or floating point elements 5354of size S@. Operand 0 is the resulting vector in which 2*N elements of 5355size N/2 are concatenated after narrowing them down using truncation. 5356 5357@cindex @code{vec_pack_ssat_@var{m}} instruction pattern 5358@cindex @code{vec_pack_usat_@var{m}} instruction pattern 5359@item @samp{vec_pack_ssat_@var{m}}, @samp{vec_pack_usat_@var{m}} 5360Narrow (demote) and merge the elements of two vectors. Operands 1 and 2 5361are vectors of the same mode having N integral elements of size S. 5362Operand 0 is the resulting vector in which the elements of the two input 5363vectors are concatenated after narrowing them down using signed/unsigned 5364saturating arithmetic. 5365 5366@cindex @code{vec_pack_sfix_trunc_@var{m}} instruction pattern 5367@cindex @code{vec_pack_ufix_trunc_@var{m}} instruction pattern 5368@item @samp{vec_pack_sfix_trunc_@var{m}}, @samp{vec_pack_ufix_trunc_@var{m}} 5369Narrow, convert to signed/unsigned integral type and merge the elements 5370of two vectors. Operands 1 and 2 are vectors of the same mode having N 5371floating point elements of size S@. Operand 0 is the resulting vector 5372in which 2*N elements of size N/2 are concatenated. 5373 5374@cindex @code{vec_unpacks_hi_@var{m}} instruction pattern 5375@cindex @code{vec_unpacks_lo_@var{m}} instruction pattern 5376@item @samp{vec_unpacks_hi_@var{m}}, @samp{vec_unpacks_lo_@var{m}} 5377Extract and widen (promote) the high/low part of a vector of signed 5378integral or floating point elements. The input vector (operand 1) has N 5379elements of size S@. Widen (promote) the high/low elements of the vector 5380using signed or floating point extension and place the resulting N/2 5381values of size 2*S in the output vector (operand 0). 5382 5383@cindex @code{vec_unpacku_hi_@var{m}} instruction pattern 5384@cindex @code{vec_unpacku_lo_@var{m}} instruction pattern 5385@item @samp{vec_unpacku_hi_@var{m}}, @samp{vec_unpacku_lo_@var{m}} 5386Extract and widen (promote) the high/low part of a vector of unsigned 5387integral elements. The input vector (operand 1) has N elements of size S. 5388Widen (promote) the high/low elements of the vector using zero extension and 5389place the resulting N/2 values of size 2*S in the output vector (operand 0). 5390 5391@cindex @code{vec_unpacks_float_hi_@var{m}} instruction pattern 5392@cindex @code{vec_unpacks_float_lo_@var{m}} instruction pattern 5393@cindex @code{vec_unpacku_float_hi_@var{m}} instruction pattern 5394@cindex @code{vec_unpacku_float_lo_@var{m}} instruction pattern 5395@item @samp{vec_unpacks_float_hi_@var{m}}, @samp{vec_unpacks_float_lo_@var{m}} 5396@itemx @samp{vec_unpacku_float_hi_@var{m}}, @samp{vec_unpacku_float_lo_@var{m}} 5397Extract, convert to floating point type and widen the high/low part of a 5398vector of signed/unsigned integral elements. The input vector (operand 1) 5399has N elements of size S@. Convert the high/low elements of the vector using 5400floating point conversion and place the resulting N/2 values of size 2*S in 5401the output vector (operand 0). 5402 5403@cindex @code{vec_widen_umult_hi_@var{m}} instruction pattern 5404@cindex @code{vec_widen_umult_lo_@var{m}} instruction pattern 5405@cindex @code{vec_widen_smult_hi_@var{m}} instruction pattern 5406@cindex @code{vec_widen_smult_lo_@var{m}} instruction pattern 5407@cindex @code{vec_widen_umult_even_@var{m}} instruction pattern 5408@cindex @code{vec_widen_umult_odd_@var{m}} instruction pattern 5409@cindex @code{vec_widen_smult_even_@var{m}} instruction pattern 5410@cindex @code{vec_widen_smult_odd_@var{m}} instruction pattern 5411@item @samp{vec_widen_umult_hi_@var{m}}, @samp{vec_widen_umult_lo_@var{m}} 5412@itemx @samp{vec_widen_smult_hi_@var{m}}, @samp{vec_widen_smult_lo_@var{m}} 5413@itemx @samp{vec_widen_umult_even_@var{m}}, @samp{vec_widen_umult_odd_@var{m}} 5414@itemx @samp{vec_widen_smult_even_@var{m}}, @samp{vec_widen_smult_odd_@var{m}} 5415Signed/Unsigned widening multiplication. The two inputs (operands 1 and 2) 5416are vectors with N signed/unsigned elements of size S@. Multiply the high/low 5417or even/odd elements of the two vectors, and put the N/2 products of size 2*S 5418in the output vector (operand 0). A target shouldn't implement even/odd pattern 5419pair if it is less efficient than lo/hi one. 5420 5421@cindex @code{vec_widen_ushiftl_hi_@var{m}} instruction pattern 5422@cindex @code{vec_widen_ushiftl_lo_@var{m}} instruction pattern 5423@cindex @code{vec_widen_sshiftl_hi_@var{m}} instruction pattern 5424@cindex @code{vec_widen_sshiftl_lo_@var{m}} instruction pattern 5425@item @samp{vec_widen_ushiftl_hi_@var{m}}, @samp{vec_widen_ushiftl_lo_@var{m}} 5426@itemx @samp{vec_widen_sshiftl_hi_@var{m}}, @samp{vec_widen_sshiftl_lo_@var{m}} 5427Signed/Unsigned widening shift left. The first input (operand 1) is a vector 5428with N signed/unsigned elements of size S@. Operand 2 is a constant. Shift 5429the high/low elements of operand 1, and put the N/2 results of size 2*S in the 5430output vector (operand 0). 5431 5432@cindex @code{mulhisi3} instruction pattern 5433@item @samp{mulhisi3} 5434Multiply operands 1 and 2, which have mode @code{HImode}, and store 5435a @code{SImode} product in operand 0. 5436 5437@cindex @code{mulqihi3} instruction pattern 5438@cindex @code{mulsidi3} instruction pattern 5439@item @samp{mulqihi3}, @samp{mulsidi3} 5440Similar widening-multiplication instructions of other widths. 5441 5442@cindex @code{umulqihi3} instruction pattern 5443@cindex @code{umulhisi3} instruction pattern 5444@cindex @code{umulsidi3} instruction pattern 5445@item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3} 5446Similar widening-multiplication instructions that do unsigned 5447multiplication. 5448 5449@cindex @code{usmulqihi3} instruction pattern 5450@cindex @code{usmulhisi3} instruction pattern 5451@cindex @code{usmulsidi3} instruction pattern 5452@item @samp{usmulqihi3}, @samp{usmulhisi3}, @samp{usmulsidi3} 5453Similar widening-multiplication instructions that interpret the first 5454operand as unsigned and the second operand as signed, then do a signed 5455multiplication. 5456 5457@cindex @code{smul@var{m}3_highpart} instruction pattern 5458@item @samp{smul@var{m}3_highpart} 5459Perform a signed multiplication of operands 1 and 2, which have mode 5460@var{m}, and store the most significant half of the product in operand 0. 5461The least significant half of the product is discarded. 5462 5463@cindex @code{umul@var{m}3_highpart} instruction pattern 5464@item @samp{umul@var{m}3_highpart} 5465Similar, but the multiplication is unsigned. 5466 5467@cindex @code{madd@var{m}@var{n}4} instruction pattern 5468@item @samp{madd@var{m}@var{n}4} 5469Multiply operands 1 and 2, sign-extend them to mode @var{n}, add 5470operand 3, and store the result in operand 0. Operands 1 and 2 5471have mode @var{m} and operands 0 and 3 have mode @var{n}. 5472Both modes must be integer or fixed-point modes and @var{n} must be twice 5473the size of @var{m}. 5474 5475In other words, @code{madd@var{m}@var{n}4} is like 5476@code{mul@var{m}@var{n}3} except that it also adds operand 3. 5477 5478These instructions are not allowed to @code{FAIL}. 5479 5480@cindex @code{umadd@var{m}@var{n}4} instruction pattern 5481@item @samp{umadd@var{m}@var{n}4} 5482Like @code{madd@var{m}@var{n}4}, but zero-extend the multiplication 5483operands instead of sign-extending them. 5484 5485@cindex @code{ssmadd@var{m}@var{n}4} instruction pattern 5486@item @samp{ssmadd@var{m}@var{n}4} 5487Like @code{madd@var{m}@var{n}4}, but all involved operations must be 5488signed-saturating. 5489 5490@cindex @code{usmadd@var{m}@var{n}4} instruction pattern 5491@item @samp{usmadd@var{m}@var{n}4} 5492Like @code{umadd@var{m}@var{n}4}, but all involved operations must be 5493unsigned-saturating. 5494 5495@cindex @code{msub@var{m}@var{n}4} instruction pattern 5496@item @samp{msub@var{m}@var{n}4} 5497Multiply operands 1 and 2, sign-extend them to mode @var{n}, subtract the 5498result from operand 3, and store the result in operand 0. Operands 1 and 2 5499have mode @var{m} and operands 0 and 3 have mode @var{n}. 5500Both modes must be integer or fixed-point modes and @var{n} must be twice 5501the size of @var{m}. 5502 5503In other words, @code{msub@var{m}@var{n}4} is like 5504@code{mul@var{m}@var{n}3} except that it also subtracts the result 5505from operand 3. 5506 5507These instructions are not allowed to @code{FAIL}. 5508 5509@cindex @code{umsub@var{m}@var{n}4} instruction pattern 5510@item @samp{umsub@var{m}@var{n}4} 5511Like @code{msub@var{m}@var{n}4}, but zero-extend the multiplication 5512operands instead of sign-extending them. 5513 5514@cindex @code{ssmsub@var{m}@var{n}4} instruction pattern 5515@item @samp{ssmsub@var{m}@var{n}4} 5516Like @code{msub@var{m}@var{n}4}, but all involved operations must be 5517signed-saturating. 5518 5519@cindex @code{usmsub@var{m}@var{n}4} instruction pattern 5520@item @samp{usmsub@var{m}@var{n}4} 5521Like @code{umsub@var{m}@var{n}4}, but all involved operations must be 5522unsigned-saturating. 5523 5524@cindex @code{divmod@var{m}4} instruction pattern 5525@item @samp{divmod@var{m}4} 5526Signed division that produces both a quotient and a remainder. 5527Operand 1 is divided by operand 2 to produce a quotient stored 5528in operand 0 and a remainder stored in operand 3. 5529 5530For machines with an instruction that produces both a quotient and a 5531remainder, provide a pattern for @samp{divmod@var{m}4} but do not 5532provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}. This 5533allows optimization in the relatively common case when both the quotient 5534and remainder are computed. 5535 5536If an instruction that just produces a quotient or just a remainder 5537exists and is more efficient than the instruction that produces both, 5538write the output routine of @samp{divmod@var{m}4} to call 5539@code{find_reg_note} and look for a @code{REG_UNUSED} note on the 5540quotient or remainder and generate the appropriate instruction. 5541 5542@cindex @code{udivmod@var{m}4} instruction pattern 5543@item @samp{udivmod@var{m}4} 5544Similar, but does unsigned division. 5545 5546@anchor{shift patterns} 5547@cindex @code{ashl@var{m}3} instruction pattern 5548@cindex @code{ssashl@var{m}3} instruction pattern 5549@cindex @code{usashl@var{m}3} instruction pattern 5550@item @samp{ashl@var{m}3}, @samp{ssashl@var{m}3}, @samp{usashl@var{m}3} 5551Arithmetic-shift operand 1 left by a number of bits specified by operand 55522, and store the result in operand 0. Here @var{m} is the mode of 5553operand 0 and operand 1; operand 2's mode is specified by the 5554instruction pattern, and the compiler will convert the operand to that 5555mode before generating the instruction. The shift or rotate expander 5556or instruction pattern should explicitly specify the mode of the operand 2, 5557it should never be @code{VOIDmode}. The meaning of out-of-range shift 5558counts can optionally be specified by @code{TARGET_SHIFT_TRUNCATION_MASK}. 5559@xref{TARGET_SHIFT_TRUNCATION_MASK}. Operand 2 is always a scalar type. 5560 5561@cindex @code{ashr@var{m}3} instruction pattern 5562@cindex @code{lshr@var{m}3} instruction pattern 5563@cindex @code{rotl@var{m}3} instruction pattern 5564@cindex @code{rotr@var{m}3} instruction pattern 5565@item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3} 5566Other shift and rotate instructions, analogous to the 5567@code{ashl@var{m}3} instructions. Operand 2 is always a scalar type. 5568 5569@cindex @code{vashl@var{m}3} instruction pattern 5570@cindex @code{vashr@var{m}3} instruction pattern 5571@cindex @code{vlshr@var{m}3} instruction pattern 5572@cindex @code{vrotl@var{m}3} instruction pattern 5573@cindex @code{vrotr@var{m}3} instruction pattern 5574@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} 5575Vector shift and rotate instructions that take vectors as operand 2 5576instead of a scalar type. 5577 5578@cindex @code{bswap@var{m}2} instruction pattern 5579@item @samp{bswap@var{m}2} 5580Reverse the order of bytes of operand 1 and store the result in operand 0. 5581 5582@cindex @code{neg@var{m}2} instruction pattern 5583@cindex @code{ssneg@var{m}2} instruction pattern 5584@cindex @code{usneg@var{m}2} instruction pattern 5585@item @samp{neg@var{m}2}, @samp{ssneg@var{m}2}, @samp{usneg@var{m}2} 5586Negate operand 1 and store the result in operand 0. 5587 5588@cindex @code{negv@var{m}3} instruction pattern 5589@item @samp{negv@var{m}3} 5590Like @code{neg@var{m}2} but takes a @code{code_label} as operand 2 and 5591emits code to jump to it if signed overflow occurs during the negation. 5592 5593@cindex @code{abs@var{m}2} instruction pattern 5594@item @samp{abs@var{m}2} 5595Store the absolute value of operand 1 into operand 0. 5596 5597@cindex @code{sqrt@var{m}2} instruction pattern 5598@item @samp{sqrt@var{m}2} 5599Store the square root of operand 1 into operand 0. Both operands have 5600mode @var{m}, which is a scalar or vector floating-point mode. 5601 5602This pattern is not allowed to @code{FAIL}. 5603 5604@cindex @code{rsqrt@var{m}2} instruction pattern 5605@item @samp{rsqrt@var{m}2} 5606Store the reciprocal of the square root of operand 1 into operand 0. 5607Both operands have mode @var{m}, which is a scalar or vector 5608floating-point mode. 5609 5610On most architectures this pattern is only approximate, so either 5611its C condition or the @code{TARGET_OPTAB_SUPPORTED_P} hook should 5612check for the appropriate math flags. (Using the C condition is 5613more direct, but using @code{TARGET_OPTAB_SUPPORTED_P} can be useful 5614if a target-specific built-in also uses the @samp{rsqrt@var{m}2} 5615pattern.) 5616 5617This pattern is not allowed to @code{FAIL}. 5618 5619@cindex @code{fmod@var{m}3} instruction pattern 5620@item @samp{fmod@var{m}3} 5621Store the remainder of dividing operand 1 by operand 2 into 5622operand 0, rounded towards zero to an integer. All operands have 5623mode @var{m}, which is a scalar or vector floating-point mode. 5624 5625This pattern is not allowed to @code{FAIL}. 5626 5627@cindex @code{remainder@var{m}3} instruction pattern 5628@item @samp{remainder@var{m}3} 5629Store the remainder of dividing operand 1 by operand 2 into 5630operand 0, rounded to the nearest integer. All operands have 5631mode @var{m}, which is a scalar or vector floating-point mode. 5632 5633This pattern is not allowed to @code{FAIL}. 5634 5635@cindex @code{scalb@var{m}3} instruction pattern 5636@item @samp{scalb@var{m}3} 5637Raise @code{FLT_RADIX} to the power of operand 2, multiply it by 5638operand 1, and store the result in operand 0. All operands have 5639mode @var{m}, which is a scalar or vector floating-point mode. 5640 5641This pattern is not allowed to @code{FAIL}. 5642 5643@cindex @code{ldexp@var{m}3} instruction pattern 5644@item @samp{ldexp@var{m}3} 5645Raise 2 to the power of operand 2, multiply it by operand 1, and store 5646the result in operand 0. Operands 0 and 1 have mode @var{m}, which is 5647a scalar or vector floating-point mode. Operand 2's mode has 5648the same number of elements as @var{m} and each element is wide 5649enough to store an @code{int}. The integers are signed. 5650 5651This pattern is not allowed to @code{FAIL}. 5652 5653@cindex @code{cos@var{m}2} instruction pattern 5654@item @samp{cos@var{m}2} 5655Store the cosine of operand 1 into operand 0. Both operands have 5656mode @var{m}, which is a scalar or vector floating-point mode. 5657 5658This pattern is not allowed to @code{FAIL}. 5659 5660@cindex @code{sin@var{m}2} instruction pattern 5661@item @samp{sin@var{m}2} 5662Store the sine of operand 1 into operand 0. Both operands have 5663mode @var{m}, which is a scalar or vector floating-point mode. 5664 5665This pattern is not allowed to @code{FAIL}. 5666 5667@cindex @code{sincos@var{m}3} instruction pattern 5668@item @samp{sincos@var{m}3} 5669Store the cosine of operand 2 into operand 0 and the sine of 5670operand 2 into operand 1. All operands have mode @var{m}, 5671which is a scalar or vector floating-point mode. 5672 5673Targets that can calculate the sine and cosine simultaneously can 5674implement this pattern as opposed to implementing individual 5675@code{sin@var{m}2} and @code{cos@var{m}2} patterns. The @code{sin} 5676and @code{cos} built-in functions will then be expanded to the 5677@code{sincos@var{m}3} pattern, with one of the output values 5678left unused. 5679 5680@cindex @code{tan@var{m}2} instruction pattern 5681@item @samp{tan@var{m}2} 5682Store the tangent of operand 1 into operand 0. Both operands have 5683mode @var{m}, which is a scalar or vector floating-point mode. 5684 5685This pattern is not allowed to @code{FAIL}. 5686 5687@cindex @code{asin@var{m}2} instruction pattern 5688@item @samp{asin@var{m}2} 5689Store the arc sine of operand 1 into operand 0. Both operands have 5690mode @var{m}, which is a scalar or vector floating-point mode. 5691 5692This pattern is not allowed to @code{FAIL}. 5693 5694@cindex @code{acos@var{m}2} instruction pattern 5695@item @samp{acos@var{m}2} 5696Store the arc cosine of operand 1 into operand 0. Both operands have 5697mode @var{m}, which is a scalar or vector floating-point mode. 5698 5699This pattern is not allowed to @code{FAIL}. 5700 5701@cindex @code{atan@var{m}2} instruction pattern 5702@item @samp{atan@var{m}2} 5703Store the arc tangent of operand 1 into operand 0. Both operands have 5704mode @var{m}, which is a scalar or vector floating-point mode. 5705 5706This pattern is not allowed to @code{FAIL}. 5707 5708@cindex @code{exp@var{m}2} instruction pattern 5709@item @samp{exp@var{m}2} 5710Raise e (the base of natural logarithms) to the power of operand 1 5711and store the result in operand 0. Both operands have mode @var{m}, 5712which is a scalar or vector floating-point mode. 5713 5714This pattern is not allowed to @code{FAIL}. 5715 5716@cindex @code{expm1@var{m}2} instruction pattern 5717@item @samp{expm1@var{m}2} 5718Raise e (the base of natural logarithms) to the power of operand 1, 5719subtract 1, and store the result in operand 0. Both operands have 5720mode @var{m}, which is a scalar or vector floating-point mode. 5721 5722For inputs close to zero, the pattern is expected to be more 5723accurate than a separate @code{exp@var{m}2} and @code{sub@var{m}3} 5724would be. 5725 5726This pattern is not allowed to @code{FAIL}. 5727 5728@cindex @code{exp10@var{m}2} instruction pattern 5729@item @samp{exp10@var{m}2} 5730Raise 10 to the power of operand 1 and store the result in operand 0. 5731Both operands have mode @var{m}, which is a scalar or vector 5732floating-point mode. 5733 5734This pattern is not allowed to @code{FAIL}. 5735 5736@cindex @code{exp2@var{m}2} instruction pattern 5737@item @samp{exp2@var{m}2} 5738Raise 2 to the power of operand 1 and store the result in operand 0. 5739Both operands have mode @var{m}, which is a scalar or vector 5740floating-point mode. 5741 5742This pattern is not allowed to @code{FAIL}. 5743 5744@cindex @code{log@var{m}2} instruction pattern 5745@item @samp{log@var{m}2} 5746Store the natural logarithm of operand 1 into operand 0. Both operands 5747have mode @var{m}, which is a scalar or vector floating-point mode. 5748 5749This pattern is not allowed to @code{FAIL}. 5750 5751@cindex @code{log1p@var{m}2} instruction pattern 5752@item @samp{log1p@var{m}2} 5753Add 1 to operand 1, compute the natural logarithm, and store 5754the result in operand 0. Both operands have mode @var{m}, which is 5755a scalar or vector floating-point mode. 5756 5757For inputs close to zero, the pattern is expected to be more 5758accurate than a separate @code{add@var{m}3} and @code{log@var{m}2} 5759would be. 5760 5761This pattern is not allowed to @code{FAIL}. 5762 5763@cindex @code{log10@var{m}2} instruction pattern 5764@item @samp{log10@var{m}2} 5765Store the base-10 logarithm of operand 1 into operand 0. Both operands 5766have mode @var{m}, which is a scalar or vector floating-point mode. 5767 5768This pattern is not allowed to @code{FAIL}. 5769 5770@cindex @code{log2@var{m}2} instruction pattern 5771@item @samp{log2@var{m}2} 5772Store the base-2 logarithm of operand 1 into operand 0. Both operands 5773have mode @var{m}, which is a scalar or vector floating-point mode. 5774 5775This pattern is not allowed to @code{FAIL}. 5776 5777@cindex @code{logb@var{m}2} instruction pattern 5778@item @samp{logb@var{m}2} 5779Store the base-@code{FLT_RADIX} logarithm of operand 1 into operand 0. 5780Both operands have mode @var{m}, which is a scalar or vector 5781floating-point mode. 5782 5783This pattern is not allowed to @code{FAIL}. 5784 5785@cindex @code{significand@var{m}2} instruction pattern 5786@item @samp{significand@var{m}2} 5787Store the significand of floating-point operand 1 in operand 0. 5788Both operands have mode @var{m}, which is a scalar or vector 5789floating-point mode. 5790 5791This pattern is not allowed to @code{FAIL}. 5792 5793@cindex @code{pow@var{m}3} instruction pattern 5794@item @samp{pow@var{m}3} 5795Store the value of operand 1 raised to the exponent operand 2 5796into operand 0. All operands have mode @var{m}, which is a scalar 5797or vector floating-point mode. 5798 5799This pattern is not allowed to @code{FAIL}. 5800 5801@cindex @code{atan2@var{m}3} instruction pattern 5802@item @samp{atan2@var{m}3} 5803Store the arc tangent (inverse tangent) of operand 1 divided by 5804operand 2 into operand 0, using the signs of both arguments to 5805determine the quadrant of the result. All operands have mode 5806@var{m}, which is a scalar or vector floating-point mode. 5807 5808This pattern is not allowed to @code{FAIL}. 5809 5810@cindex @code{floor@var{m}2} instruction pattern 5811@item @samp{floor@var{m}2} 5812Store the largest integral value not greater than operand 1 in operand 0. 5813Both operands have mode @var{m}, which is a scalar or vector 5814floating-point mode. If @option{-ffp-int-builtin-inexact} is in 5815effect, the ``inexact'' exception may be raised for noninteger 5816operands; otherwise, it may not. 5817 5818This pattern is not allowed to @code{FAIL}. 5819 5820@cindex @code{btrunc@var{m}2} instruction pattern 5821@item @samp{btrunc@var{m}2} 5822Round operand 1 to an integer, towards zero, and store the result in 5823operand 0. Both operands have mode @var{m}, which is a scalar or 5824vector floating-point mode. If @option{-ffp-int-builtin-inexact} is 5825in effect, the ``inexact'' exception may be raised for noninteger 5826operands; otherwise, it may not. 5827 5828This pattern is not allowed to @code{FAIL}. 5829 5830@cindex @code{round@var{m}2} instruction pattern 5831@item @samp{round@var{m}2} 5832Round operand 1 to the nearest integer, rounding away from zero in the 5833event of a tie, and store the result in operand 0. Both operands have 5834mode @var{m}, which is a scalar or vector floating-point mode. If 5835@option{-ffp-int-builtin-inexact} is in effect, the ``inexact'' 5836exception may be raised for noninteger operands; otherwise, it may 5837not. 5838 5839This pattern is not allowed to @code{FAIL}. 5840 5841@cindex @code{ceil@var{m}2} instruction pattern 5842@item @samp{ceil@var{m}2} 5843Store the smallest integral value not less than operand 1 in operand 0. 5844Both operands have mode @var{m}, which is a scalar or vector 5845floating-point mode. If @option{-ffp-int-builtin-inexact} is in 5846effect, the ``inexact'' exception may be raised for noninteger 5847operands; otherwise, it may not. 5848 5849This pattern is not allowed to @code{FAIL}. 5850 5851@cindex @code{nearbyint@var{m}2} instruction pattern 5852@item @samp{nearbyint@var{m}2} 5853Round operand 1 to an integer, using the current rounding mode, and 5854store the result in operand 0. Do not raise an inexact condition when 5855the result is different from the argument. Both operands have mode 5856@var{m}, which is a scalar or vector floating-point mode. 5857 5858This pattern is not allowed to @code{FAIL}. 5859 5860@cindex @code{rint@var{m}2} instruction pattern 5861@item @samp{rint@var{m}2} 5862Round operand 1 to an integer, using the current rounding mode, and 5863store the result in operand 0. Raise an inexact condition when 5864the result is different from the argument. Both operands have mode 5865@var{m}, which is a scalar or vector floating-point mode. 5866 5867This pattern is not allowed to @code{FAIL}. 5868 5869@cindex @code{lrint@var{m}@var{n}2} 5870@item @samp{lrint@var{m}@var{n}2} 5871Convert operand 1 (valid for floating point mode @var{m}) to fixed 5872point mode @var{n} as a signed number according to the current 5873rounding mode and store in operand 0 (which has mode @var{n}). 5874 5875@cindex @code{lround@var{m}@var{n}2} 5876@item @samp{lround@var{m}@var{n}2} 5877Convert operand 1 (valid for floating point mode @var{m}) to fixed 5878point mode @var{n} as a signed number rounding to nearest and away 5879from zero and store in operand 0 (which has mode @var{n}). 5880 5881@cindex @code{lfloor@var{m}@var{n}2} 5882@item @samp{lfloor@var{m}@var{n}2} 5883Convert operand 1 (valid for floating point mode @var{m}) to fixed 5884point mode @var{n} as a signed number rounding down and store in 5885operand 0 (which has mode @var{n}). 5886 5887@cindex @code{lceil@var{m}@var{n}2} 5888@item @samp{lceil@var{m}@var{n}2} 5889Convert operand 1 (valid for floating point mode @var{m}) to fixed 5890point mode @var{n} as a signed number rounding up and store in 5891operand 0 (which has mode @var{n}). 5892 5893@cindex @code{copysign@var{m}3} instruction pattern 5894@item @samp{copysign@var{m}3} 5895Store a value with the magnitude of operand 1 and the sign of operand 58962 into operand 0. All operands have mode @var{m}, which is a scalar or 5897vector floating-point mode. 5898 5899This pattern is not allowed to @code{FAIL}. 5900 5901@cindex @code{ffs@var{m}2} instruction pattern 5902@item @samp{ffs@var{m}2} 5903Store into operand 0 one plus the index of the least significant 1-bit 5904of operand 1. If operand 1 is zero, store zero. 5905 5906@var{m} is either a scalar or vector integer mode. When it is a scalar, 5907operand 1 has mode @var{m} but operand 0 can have whatever scalar 5908integer mode is suitable for the target. The compiler will insert 5909conversion instructions as necessary (typically to convert the result 5910to the same width as @code{int}). When @var{m} is a vector, both 5911operands must have mode @var{m}. 5912 5913This pattern is not allowed to @code{FAIL}. 5914 5915@cindex @code{clrsb@var{m}2} instruction pattern 5916@item @samp{clrsb@var{m}2} 5917Count leading redundant sign bits. 5918Store into operand 0 the number of redundant sign bits in operand 1, starting 5919at the most significant bit position. 5920A redundant sign bit is defined as any sign bit after the first. As such, 5921this count will be one less than the count of leading sign bits. 5922 5923@var{m} is either a scalar or vector integer mode. When it is a scalar, 5924operand 1 has mode @var{m} but operand 0 can have whatever scalar 5925integer mode is suitable for the target. The compiler will insert 5926conversion instructions as necessary (typically to convert the result 5927to the same width as @code{int}). When @var{m} is a vector, both 5928operands must have mode @var{m}. 5929 5930This pattern is not allowed to @code{FAIL}. 5931 5932@cindex @code{clz@var{m}2} instruction pattern 5933@item @samp{clz@var{m}2} 5934Store into operand 0 the number of leading 0-bits in operand 1, starting 5935at the most significant bit position. If operand 1 is 0, the 5936@code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if 5937the result is undefined or has a useful value. 5938 5939@var{m} is either a scalar or vector integer mode. When it is a scalar, 5940operand 1 has mode @var{m} but operand 0 can have whatever scalar 5941integer mode is suitable for the target. The compiler will insert 5942conversion instructions as necessary (typically to convert the result 5943to the same width as @code{int}). When @var{m} is a vector, both 5944operands must have mode @var{m}. 5945 5946This pattern is not allowed to @code{FAIL}. 5947 5948@cindex @code{ctz@var{m}2} instruction pattern 5949@item @samp{ctz@var{m}2} 5950Store into operand 0 the number of trailing 0-bits in operand 1, starting 5951at the least significant bit position. If operand 1 is 0, the 5952@code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if 5953the result is undefined or has a useful value. 5954 5955@var{m} is either a scalar or vector integer mode. When it is a scalar, 5956operand 1 has mode @var{m} but operand 0 can have whatever scalar 5957integer mode is suitable for the target. The compiler will insert 5958conversion instructions as necessary (typically to convert the result 5959to the same width as @code{int}). When @var{m} is a vector, both 5960operands must have mode @var{m}. 5961 5962This pattern is not allowed to @code{FAIL}. 5963 5964@cindex @code{popcount@var{m}2} instruction pattern 5965@item @samp{popcount@var{m}2} 5966Store into operand 0 the number of 1-bits in operand 1. 5967 5968@var{m} is either a scalar or vector integer mode. When it is a scalar, 5969operand 1 has mode @var{m} but operand 0 can have whatever scalar 5970integer mode is suitable for the target. The compiler will insert 5971conversion instructions as necessary (typically to convert the result 5972to the same width as @code{int}). When @var{m} is a vector, both 5973operands must have mode @var{m}. 5974 5975This pattern is not allowed to @code{FAIL}. 5976 5977@cindex @code{parity@var{m}2} instruction pattern 5978@item @samp{parity@var{m}2} 5979Store into operand 0 the parity of operand 1, i.e.@: the number of 1-bits 5980in operand 1 modulo 2. 5981 5982@var{m} is either a scalar or vector integer mode. When it is a scalar, 5983operand 1 has mode @var{m} but operand 0 can have whatever scalar 5984integer mode is suitable for the target. The compiler will insert 5985conversion instructions as necessary (typically to convert the result 5986to the same width as @code{int}). When @var{m} is a vector, both 5987operands must have mode @var{m}. 5988 5989This pattern is not allowed to @code{FAIL}. 5990 5991@cindex @code{one_cmpl@var{m}2} instruction pattern 5992@item @samp{one_cmpl@var{m}2} 5993Store the bitwise-complement of operand 1 into operand 0. 5994 5995@cindex @code{movmem@var{m}} instruction pattern 5996@item @samp{movmem@var{m}} 5997Block move instruction. The destination and source blocks of memory 5998are the first two operands, and both are @code{mem:BLK}s with an 5999address in mode @code{Pmode}. 6000 6001The number of bytes to move is the third operand, in mode @var{m}. 6002Usually, you specify @code{Pmode} for @var{m}. However, if you can 6003generate better code knowing the range of valid lengths is smaller than 6004those representable in a full Pmode pointer, you should provide 6005a pattern with a 6006mode corresponding to the range of values you can handle efficiently 6007(e.g., @code{QImode} for values in the range 0--127; note we avoid numbers 6008that appear negative) and also a pattern with @code{Pmode}. 6009 6010The fourth operand is the known shared alignment of the source and 6011destination, in the form of a @code{const_int} rtx. Thus, if the 6012compiler knows that both source and destination are word-aligned, 6013it may provide the value 4 for this operand. 6014 6015Optional operands 5 and 6 specify expected alignment and size of block 6016respectively. The expected alignment differs from alignment in operand 4 6017in a way that the blocks are not required to be aligned according to it in 6018all cases. This expected alignment is also in bytes, just like operand 4. 6019Expected size, when unknown, is set to @code{(const_int -1)}. 6020 6021Descriptions of multiple @code{movmem@var{m}} patterns can only be 6022beneficial if the patterns for smaller modes have fewer restrictions 6023on their first, second and fourth operands. Note that the mode @var{m} 6024in @code{movmem@var{m}} does not impose any restriction on the mode of 6025individually moved data units in the block. 6026 6027These patterns need not give special consideration to the possibility 6028that the source and destination strings might overlap. 6029 6030@cindex @code{movstr} instruction pattern 6031@item @samp{movstr} 6032String copy instruction, with @code{stpcpy} semantics. Operand 0 is 6033an output operand in mode @code{Pmode}. The addresses of the 6034destination and source strings are operands 1 and 2, and both are 6035@code{mem:BLK}s with addresses in mode @code{Pmode}. The execution of 6036the expansion of this pattern should store in operand 0 the address in 6037which the @code{NUL} terminator was stored in the destination string. 6038 6039This patern has also several optional operands that are same as in 6040@code{setmem}. 6041 6042@cindex @code{setmem@var{m}} instruction pattern 6043@item @samp{setmem@var{m}} 6044Block set instruction. The destination string is the first operand, 6045given as a @code{mem:BLK} whose address is in mode @code{Pmode}. The 6046number of bytes to set is the second operand, in mode @var{m}. The value to 6047initialize the memory with is the third operand. Targets that only support the 6048clearing of memory should reject any value that is not the constant 0. See 6049@samp{movmem@var{m}} for a discussion of the choice of mode. 6050 6051The fourth operand is the known alignment of the destination, in the form 6052of a @code{const_int} rtx. Thus, if the compiler knows that the 6053destination is word-aligned, it may provide the value 4 for this 6054operand. 6055 6056Optional operands 5 and 6 specify expected alignment and size of block 6057respectively. The expected alignment differs from alignment in operand 4 6058in a way that the blocks are not required to be aligned according to it in 6059all cases. This expected alignment is also in bytes, just like operand 4. 6060Expected size, when unknown, is set to @code{(const_int -1)}. 6061Operand 7 is the minimal size of the block and operand 8 is the 6062maximal size of the block (NULL if it can not be represented as CONST_INT). 6063Operand 9 is the probable maximal size (i.e. we can not rely on it for correctness, 6064but it can be used for choosing proper code sequence for a given size). 6065 6066The use for multiple @code{setmem@var{m}} is as for @code{movmem@var{m}}. 6067 6068@cindex @code{cmpstrn@var{m}} instruction pattern 6069@item @samp{cmpstrn@var{m}} 6070String compare instruction, with five operands. Operand 0 is the output; 6071it has mode @var{m}. The remaining four operands are like the operands 6072of @samp{movmem@var{m}}. The two memory blocks specified are compared 6073byte by byte in lexicographic order starting at the beginning of each 6074string. The instruction is not allowed to prefetch more than one byte 6075at a time since either string may end in the first byte and reading past 6076that may access an invalid page or segment and cause a fault. The 6077comparison terminates early if the fetched bytes are different or if 6078they are equal to zero. The effect of the instruction is to store a 6079value in operand 0 whose sign indicates the result of the comparison. 6080 6081@cindex @code{cmpstr@var{m}} instruction pattern 6082@item @samp{cmpstr@var{m}} 6083String compare instruction, without known maximum length. Operand 0 is the 6084output; it has mode @var{m}. The second and third operand are the blocks of 6085memory to be compared; both are @code{mem:BLK} with an address in mode 6086@code{Pmode}. 6087 6088The fourth operand is the known shared alignment of the source and 6089destination, in the form of a @code{const_int} rtx. Thus, if the 6090compiler knows that both source and destination are word-aligned, 6091it may provide the value 4 for this operand. 6092 6093The two memory blocks specified are compared byte by byte in lexicographic 6094order starting at the beginning of each string. The instruction is not allowed 6095to prefetch more than one byte at a time since either string may end in the 6096first byte and reading past that may access an invalid page or segment and 6097cause a fault. The comparison will terminate when the fetched bytes 6098are different or if they are equal to zero. The effect of the 6099instruction is to store a value in operand 0 whose sign indicates the 6100result of the comparison. 6101 6102@cindex @code{cmpmem@var{m}} instruction pattern 6103@item @samp{cmpmem@var{m}} 6104Block compare instruction, with five operands like the operands 6105of @samp{cmpstr@var{m}}. The two memory blocks specified are compared 6106byte by byte in lexicographic order starting at the beginning of each 6107block. Unlike @samp{cmpstr@var{m}} the instruction can prefetch 6108any bytes in the two memory blocks. Also unlike @samp{cmpstr@var{m}} 6109the comparison will not stop if both bytes are zero. The effect of 6110the instruction is to store a value in operand 0 whose sign indicates 6111the result of the comparison. 6112 6113@cindex @code{strlen@var{m}} instruction pattern 6114@item @samp{strlen@var{m}} 6115Compute the length of a string, with three operands. 6116Operand 0 is the result (of mode @var{m}), operand 1 is 6117a @code{mem} referring to the first character of the string, 6118operand 2 is the character to search for (normally zero), 6119and operand 3 is a constant describing the known alignment 6120of the beginning of the string. 6121 6122@cindex @code{float@var{m}@var{n}2} instruction pattern 6123@item @samp{float@var{m}@var{n}2} 6124Convert signed integer operand 1 (valid for fixed point mode @var{m}) to 6125floating point mode @var{n} and store in operand 0 (which has mode 6126@var{n}). 6127 6128@cindex @code{floatuns@var{m}@var{n}2} instruction pattern 6129@item @samp{floatuns@var{m}@var{n}2} 6130Convert unsigned integer operand 1 (valid for fixed point mode @var{m}) 6131to floating point mode @var{n} and store in operand 0 (which has mode 6132@var{n}). 6133 6134@cindex @code{fix@var{m}@var{n}2} instruction pattern 6135@item @samp{fix@var{m}@var{n}2} 6136Convert operand 1 (valid for floating point mode @var{m}) to fixed 6137point mode @var{n} as a signed number and store in operand 0 (which 6138has mode @var{n}). This instruction's result is defined only when 6139the value of operand 1 is an integer. 6140 6141If the machine description defines this pattern, it also needs to 6142define the @code{ftrunc} pattern. 6143 6144@cindex @code{fixuns@var{m}@var{n}2} instruction pattern 6145@item @samp{fixuns@var{m}@var{n}2} 6146Convert operand 1 (valid for floating point mode @var{m}) to fixed 6147point mode @var{n} as an unsigned number and store in operand 0 (which 6148has mode @var{n}). This instruction's result is defined only when the 6149value of operand 1 is an integer. 6150 6151@cindex @code{ftrunc@var{m}2} instruction pattern 6152@item @samp{ftrunc@var{m}2} 6153Convert operand 1 (valid for floating point mode @var{m}) to an 6154integer value, still represented in floating point mode @var{m}, and 6155store it in operand 0 (valid for floating point mode @var{m}). 6156 6157@cindex @code{fix_trunc@var{m}@var{n}2} instruction pattern 6158@item @samp{fix_trunc@var{m}@var{n}2} 6159Like @samp{fix@var{m}@var{n}2} but works for any floating point value 6160of mode @var{m} by converting the value to an integer. 6161 6162@cindex @code{fixuns_trunc@var{m}@var{n}2} instruction pattern 6163@item @samp{fixuns_trunc@var{m}@var{n}2} 6164Like @samp{fixuns@var{m}@var{n}2} but works for any floating point 6165value of mode @var{m} by converting the value to an integer. 6166 6167@cindex @code{trunc@var{m}@var{n}2} instruction pattern 6168@item @samp{trunc@var{m}@var{n}2} 6169Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and 6170store in operand 0 (which has mode @var{n}). Both modes must be fixed 6171point or both floating point. 6172 6173@cindex @code{extend@var{m}@var{n}2} instruction pattern 6174@item @samp{extend@var{m}@var{n}2} 6175Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and 6176store in operand 0 (which has mode @var{n}). Both modes must be fixed 6177point or both floating point. 6178 6179@cindex @code{zero_extend@var{m}@var{n}2} instruction pattern 6180@item @samp{zero_extend@var{m}@var{n}2} 6181Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and 6182store in operand 0 (which has mode @var{n}). Both modes must be fixed 6183point. 6184 6185@cindex @code{fract@var{m}@var{n}2} instruction pattern 6186@item @samp{fract@var{m}@var{n}2} 6187Convert operand 1 of mode @var{m} to mode @var{n} and store in 6188operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} 6189could be fixed-point to fixed-point, signed integer to fixed-point, 6190fixed-point to signed integer, floating-point to fixed-point, 6191or fixed-point to floating-point. 6192When overflows or underflows happen, the results are undefined. 6193 6194@cindex @code{satfract@var{m}@var{n}2} instruction pattern 6195@item @samp{satfract@var{m}@var{n}2} 6196Convert operand 1 of mode @var{m} to mode @var{n} and store in 6197operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} 6198could be fixed-point to fixed-point, signed integer to fixed-point, 6199or floating-point to fixed-point. 6200When overflows or underflows happen, the instruction saturates the 6201results to the maximum or the minimum. 6202 6203@cindex @code{fractuns@var{m}@var{n}2} instruction pattern 6204@item @samp{fractuns@var{m}@var{n}2} 6205Convert operand 1 of mode @var{m} to mode @var{n} and store in 6206operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n} 6207could be unsigned integer to fixed-point, or 6208fixed-point to unsigned integer. 6209When overflows or underflows happen, the results are undefined. 6210 6211@cindex @code{satfractuns@var{m}@var{n}2} instruction pattern 6212@item @samp{satfractuns@var{m}@var{n}2} 6213Convert unsigned integer operand 1 of mode @var{m} to fixed-point mode 6214@var{n} and store in operand 0 (which has mode @var{n}). 6215When overflows or underflows happen, the instruction saturates the 6216results to the maximum or the minimum. 6217 6218@cindex @code{extv@var{m}} instruction pattern 6219@item @samp{extv@var{m}} 6220Extract a bit-field from register operand 1, sign-extend it, and store 6221it in operand 0. Operand 2 specifies the width of the field in bits 6222and operand 3 the starting bit, which counts from the most significant 6223bit if @samp{BITS_BIG_ENDIAN} is true and from the least significant bit 6224otherwise. 6225 6226Operands 0 and 1 both have mode @var{m}. Operands 2 and 3 have a 6227target-specific mode. 6228 6229@cindex @code{extvmisalign@var{m}} instruction pattern 6230@item @samp{extvmisalign@var{m}} 6231Extract a bit-field from memory operand 1, sign extend it, and store 6232it in operand 0. Operand 2 specifies the width in bits and operand 3 6233the starting bit. The starting bit is always somewhere in the first byte of 6234operand 1; it counts from the most significant bit if @samp{BITS_BIG_ENDIAN} 6235is true and from the least significant bit otherwise. 6236 6237Operand 0 has mode @var{m} while operand 1 has @code{BLK} mode. 6238Operands 2 and 3 have a target-specific mode. 6239 6240The instruction must not read beyond the last byte of the bit-field. 6241 6242@cindex @code{extzv@var{m}} instruction pattern 6243@item @samp{extzv@var{m}} 6244Like @samp{extv@var{m}} except that the bit-field value is zero-extended. 6245 6246@cindex @code{extzvmisalign@var{m}} instruction pattern 6247@item @samp{extzvmisalign@var{m}} 6248Like @samp{extvmisalign@var{m}} except that the bit-field value is 6249zero-extended. 6250 6251@cindex @code{insv@var{m}} instruction pattern 6252@item @samp{insv@var{m}} 6253Insert operand 3 into a bit-field of register operand 0. Operand 1 6254specifies the width of the field in bits and operand 2 the starting bit, 6255which counts from the most significant bit if @samp{BITS_BIG_ENDIAN} 6256is true and from the least significant bit otherwise. 6257 6258Operands 0 and 3 both have mode @var{m}. Operands 1 and 2 have a 6259target-specific mode. 6260 6261@cindex @code{insvmisalign@var{m}} instruction pattern 6262@item @samp{insvmisalign@var{m}} 6263Insert operand 3 into a bit-field of memory operand 0. Operand 1 6264specifies the width of the field in bits and operand 2 the starting bit. 6265The starting bit is always somewhere in the first byte of operand 0; 6266it counts from the most significant bit if @samp{BITS_BIG_ENDIAN} 6267is true and from the least significant bit otherwise. 6268 6269Operand 3 has mode @var{m} while operand 0 has @code{BLK} mode. 6270Operands 1 and 2 have a target-specific mode. 6271 6272The instruction must not read or write beyond the last byte of the bit-field. 6273 6274@cindex @code{extv} instruction pattern 6275@item @samp{extv} 6276Extract a bit-field from operand 1 (a register or memory operand), where 6277operand 2 specifies the width in bits and operand 3 the starting bit, 6278and store it in operand 0. Operand 0 must have mode @code{word_mode}. 6279Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often 6280@code{word_mode} is allowed only for registers. Operands 2 and 3 must 6281be valid for @code{word_mode}. 6282 6283The RTL generation pass generates this instruction only with constants 6284for operands 2 and 3 and the constant is never zero for operand 2. 6285 6286The bit-field value is sign-extended to a full word integer 6287before it is stored in operand 0. 6288 6289This pattern is deprecated; please use @samp{extv@var{m}} and 6290@code{extvmisalign@var{m}} instead. 6291 6292@cindex @code{extzv} instruction pattern 6293@item @samp{extzv} 6294Like @samp{extv} except that the bit-field value is zero-extended. 6295 6296This pattern is deprecated; please use @samp{extzv@var{m}} and 6297@code{extzvmisalign@var{m}} instead. 6298 6299@cindex @code{insv} instruction pattern 6300@item @samp{insv} 6301Store operand 3 (which must be valid for @code{word_mode}) into a 6302bit-field in operand 0, where operand 1 specifies the width in bits and 6303operand 2 the starting bit. Operand 0 may have mode @code{byte_mode} or 6304@code{word_mode}; often @code{word_mode} is allowed only for registers. 6305Operands 1 and 2 must be valid for @code{word_mode}. 6306 6307The RTL generation pass generates this instruction only with constants 6308for operands 1 and 2 and the constant is never zero for operand 1. 6309 6310This pattern is deprecated; please use @samp{insv@var{m}} and 6311@code{insvmisalign@var{m}} instead. 6312 6313@cindex @code{mov@var{mode}cc} instruction pattern 6314@item @samp{mov@var{mode}cc} 6315Conditionally move operand 2 or operand 3 into operand 0 according to the 6316comparison in operand 1. If the comparison is true, operand 2 is moved 6317into operand 0, otherwise operand 3 is moved. 6318 6319The mode of the operands being compared need not be the same as the operands 6320being moved. Some machines, sparc64 for example, have instructions that 6321conditionally move an integer value based on the floating point condition 6322codes and vice versa. 6323 6324If the machine does not have conditional move instructions, do not 6325define these patterns. 6326 6327@cindex @code{add@var{mode}cc} instruction pattern 6328@item @samp{add@var{mode}cc} 6329Similar to @samp{mov@var{mode}cc} but for conditional addition. Conditionally 6330move operand 2 or (operands 2 + operand 3) into operand 0 according to the 6331comparison in operand 1. If the comparison is false, operand 2 is moved into 6332operand 0, otherwise (operand 2 + operand 3) is moved. 6333 6334@cindex @code{cond_add@var{mode}} instruction pattern 6335@cindex @code{cond_sub@var{mode}} instruction pattern 6336@cindex @code{cond_and@var{mode}} instruction pattern 6337@cindex @code{cond_ior@var{mode}} instruction pattern 6338@cindex @code{cond_xor@var{mode}} instruction pattern 6339@cindex @code{cond_smin@var{mode}} instruction pattern 6340@cindex @code{cond_smax@var{mode}} instruction pattern 6341@cindex @code{cond_umin@var{mode}} instruction pattern 6342@cindex @code{cond_umax@var{mode}} instruction pattern 6343@item @samp{cond_add@var{mode}} 6344@itemx @samp{cond_sub@var{mode}} 6345@itemx @samp{cond_and@var{mode}} 6346@itemx @samp{cond_ior@var{mode}} 6347@itemx @samp{cond_xor@var{mode}} 6348@itemx @samp{cond_smin@var{mode}} 6349@itemx @samp{cond_smax@var{mode}} 6350@itemx @samp{cond_umin@var{mode}} 6351@itemx @samp{cond_umax@var{mode}} 6352Perform an elementwise operation on vector operands 2 and 3, 6353under the control of the vector mask in operand 1, and store the result 6354in operand 0. This is equivalent to: 6355 6356@smallexample 6357for (i = 0; i < GET_MODE_NUNITS (@var{n}); i++) 6358 op0[i] = op1[i] ? op2[i] @var{op} op3[i] : op2[i]; 6359@end smallexample 6360 6361where, for example, @var{op} is @code{+} for @samp{cond_add@var{mode}}. 6362 6363When defined for floating-point modes, the contents of @samp{op3[i]} 6364are not interpreted if @var{op1[i]} is false, just like they would not 6365be in a normal C @samp{?:} condition. 6366 6367Operands 0, 2 and 3 all have mode @var{m}, while operand 1 has the mode 6368returned by @code{TARGET_VECTORIZE_GET_MASK_MODE}. 6369 6370@cindex @code{neg@var{mode}cc} instruction pattern 6371@item @samp{neg@var{mode}cc} 6372Similar to @samp{mov@var{mode}cc} but for conditional negation. Conditionally 6373move the negation of operand 2 or the unchanged operand 3 into operand 0 6374according to the comparison in operand 1. If the comparison is true, the negation 6375of operand 2 is moved into operand 0, otherwise operand 3 is moved. 6376 6377@cindex @code{not@var{mode}cc} instruction pattern 6378@item @samp{not@var{mode}cc} 6379Similar to @samp{neg@var{mode}cc} but for conditional complement. 6380Conditionally move the bitwise complement of operand 2 or the unchanged 6381operand 3 into operand 0 according to the comparison in operand 1. 6382If the comparison is true, the complement of operand 2 is moved into 6383operand 0, otherwise operand 3 is moved. 6384 6385@cindex @code{cstore@var{mode}4} instruction pattern 6386@item @samp{cstore@var{mode}4} 6387Store zero or nonzero in operand 0 according to whether a comparison 6388is true. Operand 1 is a comparison operator. Operand 2 and operand 3 6389are the first and second operand of the comparison, respectively. 6390You specify the mode that operand 0 must have when you write the 6391@code{match_operand} expression. The compiler automatically sees which 6392mode you have used and supplies an operand of that mode. 6393 6394The value stored for a true condition must have 1 as its low bit, or 6395else must be negative. Otherwise the instruction is not suitable and 6396you should omit it from the machine description. You describe to the 6397compiler exactly which value is stored by defining the macro 6398@code{STORE_FLAG_VALUE} (@pxref{Misc}). If a description cannot be 6399found that can be used for all the possible comparison operators, you 6400should pick one and use a @code{define_expand} to map all results 6401onto the one you chose. 6402 6403These operations may @code{FAIL}, but should do so only in relatively 6404uncommon cases; if they would @code{FAIL} for common cases involving 6405integer comparisons, it is best to restrict the predicates to not 6406allow these operands. Likewise if a given comparison operator will 6407always fail, independent of the operands (for floating-point modes, the 6408@code{ordered_comparison_operator} predicate is often useful in this case). 6409 6410If this pattern is omitted, the compiler will generate a conditional 6411branch---for example, it may copy a constant one to the target and branching 6412around an assignment of zero to the target---or a libcall. If the predicate 6413for operand 1 only rejects some operators, it will also try reordering the 6414operands and/or inverting the result value (e.g.@: by an exclusive OR). 6415These possibilities could be cheaper or equivalent to the instructions 6416used for the @samp{cstore@var{mode}4} pattern followed by those required 6417to convert a positive result from @code{STORE_FLAG_VALUE} to 1; in this 6418case, you can and should make operand 1's predicate reject some operators 6419in the @samp{cstore@var{mode}4} pattern, or remove the pattern altogether 6420from the machine description. 6421 6422@cindex @code{cbranch@var{mode}4} instruction pattern 6423@item @samp{cbranch@var{mode}4} 6424Conditional branch instruction combined with a compare instruction. 6425Operand 0 is a comparison operator. Operand 1 and operand 2 are the 6426first and second operands of the comparison, respectively. Operand 3 6427is the @code{code_label} to jump to. 6428 6429@cindex @code{jump} instruction pattern 6430@item @samp{jump} 6431A jump inside a function; an unconditional branch. Operand 0 is the 6432@code{code_label} to jump to. This pattern name is mandatory on all 6433machines. 6434 6435@cindex @code{call} instruction pattern 6436@item @samp{call} 6437Subroutine call instruction returning no value. Operand 0 is the 6438function to call; operand 1 is the number of bytes of arguments pushed 6439as a @code{const_int}; operand 2 is the number of registers used as 6440operands. 6441 6442On most machines, operand 2 is not actually stored into the RTL 6443pattern. It is supplied for the sake of some RISC machines which need 6444to put this information into the assembler code; they can put it in 6445the RTL instead of operand 1. 6446 6447Operand 0 should be a @code{mem} RTX whose address is the address of the 6448function. Note, however, that this address can be a @code{symbol_ref} 6449expression even if it would not be a legitimate memory address on the 6450target machine. If it is also not a valid argument for a call 6451instruction, the pattern for this operation should be a 6452@code{define_expand} (@pxref{Expander Definitions}) that places the 6453address into a register and uses that register in the call instruction. 6454 6455@cindex @code{call_value} instruction pattern 6456@item @samp{call_value} 6457Subroutine call instruction returning a value. Operand 0 is the hard 6458register in which the value is returned. There are three more 6459operands, the same as the three operands of the @samp{call} 6460instruction (but with numbers increased by one). 6461 6462Subroutines that return @code{BLKmode} objects use the @samp{call} 6463insn. 6464 6465@cindex @code{call_pop} instruction pattern 6466@cindex @code{call_value_pop} instruction pattern 6467@item @samp{call_pop}, @samp{call_value_pop} 6468Similar to @samp{call} and @samp{call_value}, except used if defined and 6469if @code{RETURN_POPS_ARGS} is nonzero. They should emit a @code{parallel} 6470that contains both the function call and a @code{set} to indicate the 6471adjustment made to the frame pointer. 6472 6473For machines where @code{RETURN_POPS_ARGS} can be nonzero, the use of these 6474patterns increases the number of functions for which the frame pointer 6475can be eliminated, if desired. 6476 6477@cindex @code{untyped_call} instruction pattern 6478@item @samp{untyped_call} 6479Subroutine call instruction returning a value of any type. Operand 0 is 6480the function to call; operand 1 is a memory location where the result of 6481calling the function is to be stored; operand 2 is a @code{parallel} 6482expression where each element is a @code{set} expression that indicates 6483the saving of a function return value into the result block. 6484 6485This instruction pattern should be defined to support 6486@code{__builtin_apply} on machines where special instructions are needed 6487to call a subroutine with arbitrary arguments or to save the value 6488returned. This instruction pattern is required on machines that have 6489multiple registers that can hold a return value 6490(i.e.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register). 6491 6492@cindex @code{return} instruction pattern 6493@item @samp{return} 6494Subroutine return instruction. This instruction pattern name should be 6495defined only if a single instruction can do all the work of returning 6496from a function. 6497 6498Like the @samp{mov@var{m}} patterns, this pattern is also used after the 6499RTL generation phase. In this case it is to support machines where 6500multiple instructions are usually needed to return from a function, but 6501some class of functions only requires one instruction to implement a 6502return. Normally, the applicable functions are those which do not need 6503to save any registers or allocate stack space. 6504 6505It is valid for this pattern to expand to an instruction using 6506@code{simple_return} if no epilogue is required. 6507 6508@cindex @code{simple_return} instruction pattern 6509@item @samp{simple_return} 6510Subroutine return instruction. This instruction pattern name should be 6511defined only if a single instruction can do all the work of returning 6512from a function on a path where no epilogue is required. This pattern 6513is very similar to the @code{return} instruction pattern, but it is emitted 6514only by the shrink-wrapping optimization on paths where the function 6515prologue has not been executed, and a function return should occur without 6516any of the effects of the epilogue. Additional uses may be introduced on 6517paths where both the prologue and the epilogue have executed. 6518 6519@findex reload_completed 6520@findex leaf_function_p 6521For such machines, the condition specified in this pattern should only 6522be true when @code{reload_completed} is nonzero and the function's 6523epilogue would only be a single instruction. For machines with register 6524windows, the routine @code{leaf_function_p} may be used to determine if 6525a register window push is required. 6526 6527Machines that have conditional return instructions should define patterns 6528such as 6529 6530@smallexample 6531(define_insn "" 6532 [(set (pc) 6533 (if_then_else (match_operator 6534 0 "comparison_operator" 6535 [(cc0) (const_int 0)]) 6536 (return) 6537 (pc)))] 6538 "@var{condition}" 6539 "@dots{}") 6540@end smallexample 6541 6542where @var{condition} would normally be the same condition specified on the 6543named @samp{return} pattern. 6544 6545@cindex @code{untyped_return} instruction pattern 6546@item @samp{untyped_return} 6547Untyped subroutine return instruction. This instruction pattern should 6548be defined to support @code{__builtin_return} on machines where special 6549instructions are needed to return a value of any type. 6550 6551Operand 0 is a memory location where the result of calling a function 6552with @code{__builtin_apply} is stored; operand 1 is a @code{parallel} 6553expression where each element is a @code{set} expression that indicates 6554the restoring of a function return value from the result block. 6555 6556@cindex @code{nop} instruction pattern 6557@item @samp{nop} 6558No-op instruction. This instruction pattern name should always be defined 6559to output a no-op in assembler code. @code{(const_int 0)} will do as an 6560RTL pattern. 6561 6562@cindex @code{indirect_jump} instruction pattern 6563@item @samp{indirect_jump} 6564An instruction to jump to an address which is operand zero. 6565This pattern name is mandatory on all machines. 6566 6567@cindex @code{casesi} instruction pattern 6568@item @samp{casesi} 6569Instruction to jump through a dispatch table, including bounds checking. 6570This instruction takes five operands: 6571 6572@enumerate 6573@item 6574The index to dispatch on, which has mode @code{SImode}. 6575 6576@item 6577The lower bound for indices in the table, an integer constant. 6578 6579@item 6580The total range of indices in the table---the largest index 6581minus the smallest one (both inclusive). 6582 6583@item 6584A label that precedes the table itself. 6585 6586@item 6587A label to jump to if the index has a value outside the bounds. 6588@end enumerate 6589 6590The table is an @code{addr_vec} or @code{addr_diff_vec} inside of a 6591@code{jump_table_data}. The number of elements in the table is one plus the 6592difference between the upper bound and the lower bound. 6593 6594@cindex @code{tablejump} instruction pattern 6595@item @samp{tablejump} 6596Instruction to jump to a variable address. This is a low-level 6597capability which can be used to implement a dispatch table when there 6598is no @samp{casesi} pattern. 6599 6600This pattern requires two operands: the address or offset, and a label 6601which should immediately precede the jump table. If the macro 6602@code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first 6603operand is an offset which counts from the address of the table; otherwise, 6604it is an absolute address to jump to. In either case, the first operand has 6605mode @code{Pmode}. 6606 6607The @samp{tablejump} insn is always the last insn before the jump 6608table it uses. Its assembler code normally has no need to use the 6609second operand, but you should incorporate it in the RTL pattern so 6610that the jump optimizer will not delete the table as unreachable code. 6611 6612 6613@cindex @code{decrement_and_branch_until_zero} instruction pattern 6614@item @samp{decrement_and_branch_until_zero} 6615Conditional branch instruction that decrements a register and 6616jumps if the register is nonzero. Operand 0 is the register to 6617decrement and test; operand 1 is the label to jump to if the 6618register is nonzero. @xref{Looping Patterns}. 6619 6620This optional instruction pattern is only used by the combiner, 6621typically for loops reversed by the loop optimizer when strength 6622reduction is enabled. 6623 6624@cindex @code{doloop_end} instruction pattern 6625@item @samp{doloop_end} 6626Conditional branch instruction that decrements a register and 6627jumps if the register is nonzero. Operand 0 is the register to 6628decrement and test; operand 1 is the label to jump to if the 6629register is nonzero. 6630@xref{Looping Patterns}. 6631 6632This optional instruction pattern should be defined for machines with 6633low-overhead looping instructions as the loop optimizer will try to 6634modify suitable loops to utilize it. The target hook 6635@code{TARGET_CAN_USE_DOLOOP_P} controls the conditions under which 6636low-overhead loops can be used. 6637 6638@cindex @code{doloop_begin} instruction pattern 6639@item @samp{doloop_begin} 6640Companion instruction to @code{doloop_end} required for machines that 6641need to perform some initialization, such as loading a special counter 6642register. Operand 1 is the associated @code{doloop_end} pattern and 6643operand 0 is the register that it decrements. 6644 6645If initialization insns do not always need to be emitted, use a 6646@code{define_expand} (@pxref{Expander Definitions}) and make it fail. 6647 6648@cindex @code{canonicalize_funcptr_for_compare} instruction pattern 6649@item @samp{canonicalize_funcptr_for_compare} 6650Canonicalize the function pointer in operand 1 and store the result 6651into operand 0. 6652 6653Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1 6654may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc 6655and also has mode @code{Pmode}. 6656 6657Canonicalization of a function pointer usually involves computing 6658the address of the function which would be called if the function 6659pointer were used in an indirect call. 6660 6661Only define this pattern if function pointers on the target machine 6662can have different values but still call the same function when 6663used in an indirect call. 6664 6665@cindex @code{save_stack_block} instruction pattern 6666@cindex @code{save_stack_function} instruction pattern 6667@cindex @code{save_stack_nonlocal} instruction pattern 6668@cindex @code{restore_stack_block} instruction pattern 6669@cindex @code{restore_stack_function} instruction pattern 6670@cindex @code{restore_stack_nonlocal} instruction pattern 6671@item @samp{save_stack_block} 6672@itemx @samp{save_stack_function} 6673@itemx @samp{save_stack_nonlocal} 6674@itemx @samp{restore_stack_block} 6675@itemx @samp{restore_stack_function} 6676@itemx @samp{restore_stack_nonlocal} 6677Most machines save and restore the stack pointer by copying it to or 6678from an object of mode @code{Pmode}. Do not define these patterns on 6679such machines. 6680 6681Some machines require special handling for stack pointer saves and 6682restores. On those machines, define the patterns corresponding to the 6683non-standard cases by using a @code{define_expand} (@pxref{Expander 6684Definitions}) that produces the required insns. The three types of 6685saves and restores are: 6686 6687@enumerate 6688@item 6689@samp{save_stack_block} saves the stack pointer at the start of a block 6690that allocates a variable-sized object, and @samp{restore_stack_block} 6691restores the stack pointer when the block is exited. 6692 6693@item 6694@samp{save_stack_function} and @samp{restore_stack_function} do a 6695similar job for the outermost block of a function and are used when the 6696function allocates variable-sized objects or calls @code{alloca}. Only 6697the epilogue uses the restored stack pointer, allowing a simpler save or 6698restore sequence on some machines. 6699 6700@item 6701@samp{save_stack_nonlocal} is used in functions that contain labels 6702branched to by nested functions. It saves the stack pointer in such a 6703way that the inner function can use @samp{restore_stack_nonlocal} to 6704restore the stack pointer. The compiler generates code to restore the 6705frame and argument pointer registers, but some machines require saving 6706and restoring additional data such as register window information or 6707stack backchains. Place insns in these patterns to save and restore any 6708such required data. 6709@end enumerate 6710 6711When saving the stack pointer, operand 0 is the save area and operand 1 6712is the stack pointer. The mode used to allocate the save area defaults 6713to @code{Pmode} but you can override that choice by defining the 6714@code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}). You must 6715specify an integral mode, or @code{VOIDmode} if no save area is needed 6716for a particular type of save (either because no save is needed or 6717because a machine-specific save area can be used). Operand 0 is the 6718stack pointer and operand 1 is the save area for restore operations. If 6719@samp{save_stack_block} is defined, operand 0 must not be 6720@code{VOIDmode} since these saves can be arbitrarily nested. 6721 6722A save area is a @code{mem} that is at a constant offset from 6723@code{virtual_stack_vars_rtx} when the stack pointer is saved for use by 6724nonlocal gotos and a @code{reg} in the other two cases. 6725 6726@cindex @code{allocate_stack} instruction pattern 6727@item @samp{allocate_stack} 6728Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from 6729the stack pointer to create space for dynamically allocated data. 6730 6731Store the resultant pointer to this space into operand 0. If you 6732are allocating space from the main stack, do this by emitting a 6733move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0. 6734If you are allocating the space elsewhere, generate code to copy the 6735location of the space to operand 0. In the latter case, you must 6736ensure this space gets freed when the corresponding space on the main 6737stack is free. 6738 6739Do not define this pattern if all that must be done is the subtraction. 6740Some machines require other operations such as stack probes or 6741maintaining the back chain. Define this pattern to emit those 6742operations in addition to updating the stack pointer. 6743 6744@cindex @code{check_stack} instruction pattern 6745@item @samp{check_stack} 6746If stack checking (@pxref{Stack Checking}) cannot be done on your system by 6747probing the stack, define this pattern to perform the needed check and signal 6748an error if the stack has overflowed. The single operand is the address in 6749the stack farthest from the current stack pointer that you need to validate. 6750Normally, on platforms where this pattern is needed, you would obtain the 6751stack limit from a global or thread-specific variable or register. 6752 6753@cindex @code{probe_stack_address} instruction pattern 6754@item @samp{probe_stack_address} 6755If stack checking (@pxref{Stack Checking}) can be done on your system by 6756probing the stack but without the need to actually access it, define this 6757pattern and signal an error if the stack has overflowed. The single operand 6758is the memory address in the stack that needs to be probed. 6759 6760@cindex @code{probe_stack} instruction pattern 6761@item @samp{probe_stack} 6762If stack checking (@pxref{Stack Checking}) can be done on your system by 6763probing the stack but doing it with a ``store zero'' instruction is not valid 6764or optimal, define this pattern to do the probing differently and signal an 6765error if the stack has overflowed. The single operand is the memory reference 6766in the stack that needs to be probed. 6767 6768@cindex @code{nonlocal_goto} instruction pattern 6769@item @samp{nonlocal_goto} 6770Emit code to generate a non-local goto, e.g., a jump from one function 6771to a label in an outer function. This pattern has four arguments, 6772each representing a value to be used in the jump. The first 6773argument is to be loaded into the frame pointer, the second is 6774the address to branch to (code to dispatch to the actual label), 6775the third is the address of a location where the stack is saved, 6776and the last is the address of the label, to be placed in the 6777location for the incoming static chain. 6778 6779On most machines you need not define this pattern, since GCC will 6780already generate the correct code, which is to load the frame pointer 6781and static chain, restore the stack (using the 6782@samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly 6783to the dispatcher. You need only define this pattern if this code will 6784not work on your machine. 6785 6786@cindex @code{nonlocal_goto_receiver} instruction pattern 6787@item @samp{nonlocal_goto_receiver} 6788This pattern, if defined, contains code needed at the target of a 6789nonlocal goto after the code already generated by GCC@. You will not 6790normally need to define this pattern. A typical reason why you might 6791need this pattern is if some value, such as a pointer to a global table, 6792must be restored when the frame pointer is restored. Note that a nonlocal 6793goto only occurs within a unit-of-translation, so a global table pointer 6794that is shared by all functions of a given module need not be restored. 6795There are no arguments. 6796 6797@cindex @code{exception_receiver} instruction pattern 6798@item @samp{exception_receiver} 6799This pattern, if defined, contains code needed at the site of an 6800exception handler that isn't needed at the site of a nonlocal goto. You 6801will not normally need to define this pattern. A typical reason why you 6802might need this pattern is if some value, such as a pointer to a global 6803table, must be restored after control flow is branched to the handler of 6804an exception. There are no arguments. 6805 6806@cindex @code{builtin_setjmp_setup} instruction pattern 6807@item @samp{builtin_setjmp_setup} 6808This pattern, if defined, contains additional code needed to initialize 6809the @code{jmp_buf}. You will not normally need to define this pattern. 6810A typical reason why you might need this pattern is if some value, such 6811as a pointer to a global table, must be restored. Though it is 6812preferred that the pointer value be recalculated if possible (given the 6813address of a label for instance). The single argument is a pointer to 6814the @code{jmp_buf}. Note that the buffer is five words long and that 6815the first three are normally used by the generic mechanism. 6816 6817@cindex @code{builtin_setjmp_receiver} instruction pattern 6818@item @samp{builtin_setjmp_receiver} 6819This pattern, if defined, contains code needed at the site of a 6820built-in setjmp that isn't needed at the site of a nonlocal goto. You 6821will not normally need to define this pattern. A typical reason why you 6822might need this pattern is if some value, such as a pointer to a global 6823table, must be restored. It takes one argument, which is the label 6824to which builtin_longjmp transferred control; this pattern may be emitted 6825at a small offset from that label. 6826 6827@cindex @code{builtin_longjmp} instruction pattern 6828@item @samp{builtin_longjmp} 6829This pattern, if defined, performs the entire action of the longjmp. 6830You will not normally need to define this pattern unless you also define 6831@code{builtin_setjmp_setup}. The single argument is a pointer to the 6832@code{jmp_buf}. 6833 6834@cindex @code{eh_return} instruction pattern 6835@item @samp{eh_return} 6836This pattern, if defined, affects the way @code{__builtin_eh_return}, 6837and thence the call frame exception handling library routines, are 6838built. It is intended to handle non-trivial actions needed along 6839the abnormal return path. 6840 6841The address of the exception handler to which the function should return 6842is passed as operand to this pattern. It will normally need to copied by 6843the pattern to some special register or memory location. 6844If the pattern needs to determine the location of the target call 6845frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX}, 6846if defined; it will have already been assigned. 6847 6848If this pattern is not defined, the default action will be to simply 6849copy the return address to @code{EH_RETURN_HANDLER_RTX}. Either 6850that macro or this pattern needs to be defined if call frame exception 6851handling is to be used. 6852 6853@cindex @code{prologue} instruction pattern 6854@anchor{prologue instruction pattern} 6855@item @samp{prologue} 6856This pattern, if defined, emits RTL for entry to a function. The function 6857entry is responsible for setting up the stack frame, initializing the frame 6858pointer register, saving callee saved registers, etc. 6859 6860Using a prologue pattern is generally preferred over defining 6861@code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue. 6862 6863The @code{prologue} pattern is particularly useful for targets which perform 6864instruction scheduling. 6865 6866@cindex @code{window_save} instruction pattern 6867@anchor{window_save instruction pattern} 6868@item @samp{window_save} 6869This pattern, if defined, emits RTL for a register window save. It should 6870be defined if the target machine has register windows but the window events 6871are decoupled from calls to subroutines. The canonical example is the SPARC 6872architecture. 6873 6874@cindex @code{epilogue} instruction pattern 6875@anchor{epilogue instruction pattern} 6876@item @samp{epilogue} 6877This pattern emits RTL for exit from a function. The function 6878exit is responsible for deallocating the stack frame, restoring callee saved 6879registers and emitting the return instruction. 6880 6881Using an epilogue pattern is generally preferred over defining 6882@code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue. 6883 6884The @code{epilogue} pattern is particularly useful for targets which perform 6885instruction scheduling or which have delay slots for their return instruction. 6886 6887@cindex @code{sibcall_epilogue} instruction pattern 6888@item @samp{sibcall_epilogue} 6889This pattern, if defined, emits RTL for exit from a function without the final 6890branch back to the calling function. This pattern will be emitted before any 6891sibling call (aka tail call) sites. 6892 6893The @code{sibcall_epilogue} pattern must not clobber any arguments used for 6894parameter passing or any stack slots for arguments passed to the current 6895function. 6896 6897@cindex @code{trap} instruction pattern 6898@item @samp{trap} 6899This pattern, if defined, signals an error, typically by causing some 6900kind of signal to be raised. 6901 6902@cindex @code{ctrap@var{MM}4} instruction pattern 6903@item @samp{ctrap@var{MM}4} 6904Conditional trap instruction. Operand 0 is a piece of RTL which 6905performs a comparison, and operands 1 and 2 are the arms of the 6906comparison. Operand 3 is the trap code, an integer. 6907 6908A typical @code{ctrap} pattern looks like 6909 6910@smallexample 6911(define_insn "ctrapsi4" 6912 [(trap_if (match_operator 0 "trap_operator" 6913 [(match_operand 1 "register_operand") 6914 (match_operand 2 "immediate_operand")]) 6915 (match_operand 3 "const_int_operand" "i"))] 6916 "" 6917 "@dots{}") 6918@end smallexample 6919 6920@cindex @code{prefetch} instruction pattern 6921@item @samp{prefetch} 6922This pattern, if defined, emits code for a non-faulting data prefetch 6923instruction. Operand 0 is the address of the memory to prefetch. Operand 1 6924is a constant 1 if the prefetch is preparing for a write to the memory 6925address, or a constant 0 otherwise. Operand 2 is the expected degree of 6926temporal locality of the data and is a value between 0 and 3, inclusive; 0 6927means that the data has no temporal locality, so it need not be left in the 6928cache after the access; 3 means that the data has a high degree of temporal 6929locality and should be left in all levels of cache possible; 1 and 2 mean, 6930respectively, a low or moderate degree of temporal locality. 6931 6932Targets that do not support write prefetches or locality hints can ignore 6933the values of operands 1 and 2. 6934 6935@cindex @code{blockage} instruction pattern 6936@item @samp{blockage} 6937This pattern defines a pseudo insn that prevents the instruction 6938scheduler and other passes from moving instructions and using register 6939equivalences across the boundary defined by the blockage insn. 6940This needs to be an UNSPEC_VOLATILE pattern or a volatile ASM. 6941 6942@cindex @code{memory_blockage} instruction pattern 6943@item @samp{memory_blockage} 6944This pattern, if defined, represents a compiler memory barrier, and will be 6945placed at points across which RTL passes may not propagate memory accesses. 6946This instruction needs to read and write volatile BLKmode memory. It does 6947not need to generate any machine instruction. If this pattern is not defined, 6948the compiler falls back to emitting an instruction corresponding 6949to @code{asm volatile ("" ::: "memory")}. 6950 6951@cindex @code{memory_barrier} instruction pattern 6952@item @samp{memory_barrier} 6953If the target memory model is not fully synchronous, then this pattern 6954should be defined to an instruction that orders both loads and stores 6955before the instruction with respect to loads and stores after the instruction. 6956This pattern has no operands. 6957 6958@cindex @code{sync_compare_and_swap@var{mode}} instruction pattern 6959@item @samp{sync_compare_and_swap@var{mode}} 6960This pattern, if defined, emits code for an atomic compare-and-swap 6961operation. Operand 1 is the memory on which the atomic operation is 6962performed. Operand 2 is the ``old'' value to be compared against the 6963current contents of the memory location. Operand 3 is the ``new'' value 6964to store in the memory if the compare succeeds. Operand 0 is the result 6965of the operation; it should contain the contents of the memory 6966before the operation. If the compare succeeds, this should obviously be 6967a copy of operand 2. 6968 6969This pattern must show that both operand 0 and operand 1 are modified. 6970 6971This pattern must issue any memory barrier instructions such that all 6972memory operations before the atomic operation occur before the atomic 6973operation and all memory operations after the atomic operation occur 6974after the atomic operation. 6975 6976For targets where the success or failure of the compare-and-swap 6977operation is available via the status flags, it is possible to 6978avoid a separate compare operation and issue the subsequent 6979branch or store-flag operation immediately after the compare-and-swap. 6980To this end, GCC will look for a @code{MODE_CC} set in the 6981output of @code{sync_compare_and_swap@var{mode}}; if the machine 6982description includes such a set, the target should also define special 6983@code{cbranchcc4} and/or @code{cstorecc4} instructions. GCC will then 6984be able to take the destination of the @code{MODE_CC} set and pass it 6985to the @code{cbranchcc4} or @code{cstorecc4} pattern as the first 6986operand of the comparison (the second will be @code{(const_int 0)}). 6987 6988For targets where the operating system may provide support for this 6989operation via library calls, the @code{sync_compare_and_swap_optab} 6990may be initialized to a function with the same interface as the 6991@code{__sync_val_compare_and_swap_@var{n}} built-in. If the entire 6992set of @var{__sync} builtins are supported via library calls, the 6993target can initialize all of the optabs at once with 6994@code{init_sync_libfuncs}. 6995For the purposes of C++11 @code{std::atomic::is_lock_free}, it is 6996assumed that these library calls do @emph{not} use any kind of 6997interruptable locking. 6998 6999@cindex @code{sync_add@var{mode}} instruction pattern 7000@cindex @code{sync_sub@var{mode}} instruction pattern 7001@cindex @code{sync_ior@var{mode}} instruction pattern 7002@cindex @code{sync_and@var{mode}} instruction pattern 7003@cindex @code{sync_xor@var{mode}} instruction pattern 7004@cindex @code{sync_nand@var{mode}} instruction pattern 7005@item @samp{sync_add@var{mode}}, @samp{sync_sub@var{mode}} 7006@itemx @samp{sync_ior@var{mode}}, @samp{sync_and@var{mode}} 7007@itemx @samp{sync_xor@var{mode}}, @samp{sync_nand@var{mode}} 7008These patterns emit code for an atomic operation on memory. 7009Operand 0 is the memory on which the atomic operation is performed. 7010Operand 1 is the second operand to the binary operator. 7011 7012This pattern must issue any memory barrier instructions such that all 7013memory operations before the atomic operation occur before the atomic 7014operation and all memory operations after the atomic operation occur 7015after the atomic operation. 7016 7017If these patterns are not defined, the operation will be constructed 7018from a compare-and-swap operation, if defined. 7019 7020@cindex @code{sync_old_add@var{mode}} instruction pattern 7021@cindex @code{sync_old_sub@var{mode}} instruction pattern 7022@cindex @code{sync_old_ior@var{mode}} instruction pattern 7023@cindex @code{sync_old_and@var{mode}} instruction pattern 7024@cindex @code{sync_old_xor@var{mode}} instruction pattern 7025@cindex @code{sync_old_nand@var{mode}} instruction pattern 7026@item @samp{sync_old_add@var{mode}}, @samp{sync_old_sub@var{mode}} 7027@itemx @samp{sync_old_ior@var{mode}}, @samp{sync_old_and@var{mode}} 7028@itemx @samp{sync_old_xor@var{mode}}, @samp{sync_old_nand@var{mode}} 7029These patterns emit code for an atomic operation on memory, 7030and return the value that the memory contained before the operation. 7031Operand 0 is the result value, operand 1 is the memory on which the 7032atomic operation is performed, and operand 2 is the second operand 7033to the binary operator. 7034 7035This pattern must issue any memory barrier instructions such that all 7036memory operations before the atomic operation occur before the atomic 7037operation and all memory operations after the atomic operation occur 7038after the atomic operation. 7039 7040If these patterns are not defined, the operation will be constructed 7041from a compare-and-swap operation, if defined. 7042 7043@cindex @code{sync_new_add@var{mode}} instruction pattern 7044@cindex @code{sync_new_sub@var{mode}} instruction pattern 7045@cindex @code{sync_new_ior@var{mode}} instruction pattern 7046@cindex @code{sync_new_and@var{mode}} instruction pattern 7047@cindex @code{sync_new_xor@var{mode}} instruction pattern 7048@cindex @code{sync_new_nand@var{mode}} instruction pattern 7049@item @samp{sync_new_add@var{mode}}, @samp{sync_new_sub@var{mode}} 7050@itemx @samp{sync_new_ior@var{mode}}, @samp{sync_new_and@var{mode}} 7051@itemx @samp{sync_new_xor@var{mode}}, @samp{sync_new_nand@var{mode}} 7052These patterns are like their @code{sync_old_@var{op}} counterparts, 7053except that they return the value that exists in the memory location 7054after the operation, rather than before the operation. 7055 7056@cindex @code{sync_lock_test_and_set@var{mode}} instruction pattern 7057@item @samp{sync_lock_test_and_set@var{mode}} 7058This pattern takes two forms, based on the capabilities of the target. 7059In either case, operand 0 is the result of the operand, operand 1 is 7060the memory on which the atomic operation is performed, and operand 2 7061is the value to set in the lock. 7062 7063In the ideal case, this operation is an atomic exchange operation, in 7064which the previous value in memory operand is copied into the result 7065operand, and the value operand is stored in the memory operand. 7066 7067For less capable targets, any value operand that is not the constant 1 7068should be rejected with @code{FAIL}. In this case the target may use 7069an atomic test-and-set bit operation. The result operand should contain 70701 if the bit was previously set and 0 if the bit was previously clear. 7071The true contents of the memory operand are implementation defined. 7072 7073This pattern must issue any memory barrier instructions such that the 7074pattern as a whole acts as an acquire barrier, that is all memory 7075operations after the pattern do not occur until the lock is acquired. 7076 7077If this pattern is not defined, the operation will be constructed from 7078a compare-and-swap operation, if defined. 7079 7080@cindex @code{sync_lock_release@var{mode}} instruction pattern 7081@item @samp{sync_lock_release@var{mode}} 7082This pattern, if defined, releases a lock set by 7083@code{sync_lock_test_and_set@var{mode}}. Operand 0 is the memory 7084that contains the lock; operand 1 is the value to store in the lock. 7085 7086If the target doesn't implement full semantics for 7087@code{sync_lock_test_and_set@var{mode}}, any value operand which is not 7088the constant 0 should be rejected with @code{FAIL}, and the true contents 7089of the memory operand are implementation defined. 7090 7091This pattern must issue any memory barrier instructions such that the 7092pattern as a whole acts as a release barrier, that is the lock is 7093released only after all previous memory operations have completed. 7094 7095If this pattern is not defined, then a @code{memory_barrier} pattern 7096will be emitted, followed by a store of the value to the memory operand. 7097 7098@cindex @code{atomic_compare_and_swap@var{mode}} instruction pattern 7099@item @samp{atomic_compare_and_swap@var{mode}} 7100This pattern, if defined, emits code for an atomic compare-and-swap 7101operation with memory model semantics. Operand 2 is the memory on which 7102the atomic operation is performed. Operand 0 is an output operand which 7103is set to true or false based on whether the operation succeeded. Operand 71041 is an output operand which is set to the contents of the memory before 7105the operation was attempted. Operand 3 is the value that is expected to 7106be in memory. Operand 4 is the value to put in memory if the expected 7107value is found there. Operand 5 is set to 1 if this compare and swap is to 7108be treated as a weak operation. Operand 6 is the memory model to be used 7109if the operation is a success. Operand 7 is the memory model to be used 7110if the operation fails. 7111 7112If memory referred to in operand 2 contains the value in operand 3, then 7113operand 4 is stored in memory pointed to by operand 2 and fencing based on 7114the memory model in operand 6 is issued. 7115 7116If memory referred to in operand 2 does not contain the value in operand 3, 7117then fencing based on the memory model in operand 7 is issued. 7118 7119If a target does not support weak compare-and-swap operations, or the port 7120elects not to implement weak operations, the argument in operand 5 can be 7121ignored. Note a strong implementation must be provided. 7122 7123If this pattern is not provided, the @code{__atomic_compare_exchange} 7124built-in functions will utilize the legacy @code{sync_compare_and_swap} 7125pattern with an @code{__ATOMIC_SEQ_CST} memory model. 7126 7127@cindex @code{atomic_load@var{mode}} instruction pattern 7128@item @samp{atomic_load@var{mode}} 7129This pattern implements an atomic load operation with memory model 7130semantics. Operand 1 is the memory address being loaded from. Operand 0 7131is the result of the load. Operand 2 is the memory model to be used for 7132the load operation. 7133 7134If not present, the @code{__atomic_load} built-in function will either 7135resort to a normal load with memory barriers, or a compare-and-swap 7136operation if a normal load would not be atomic. 7137 7138@cindex @code{atomic_store@var{mode}} instruction pattern 7139@item @samp{atomic_store@var{mode}} 7140This pattern implements an atomic store operation with memory model 7141semantics. Operand 0 is the memory address being stored to. Operand 1 7142is the value to be written. Operand 2 is the memory model to be used for 7143the operation. 7144 7145If not present, the @code{__atomic_store} built-in function will attempt to 7146perform a normal store and surround it with any required memory fences. If 7147the store would not be atomic, then an @code{__atomic_exchange} is 7148attempted with the result being ignored. 7149 7150@cindex @code{atomic_exchange@var{mode}} instruction pattern 7151@item @samp{atomic_exchange@var{mode}} 7152This pattern implements an atomic exchange operation with memory model 7153semantics. Operand 1 is the memory location the operation is performed on. 7154Operand 0 is an output operand which is set to the original value contained 7155in the memory pointed to by operand 1. Operand 2 is the value to be 7156stored. Operand 3 is the memory model to be used. 7157 7158If this pattern is not present, the built-in function 7159@code{__atomic_exchange} will attempt to preform the operation with a 7160compare and swap loop. 7161 7162@cindex @code{atomic_add@var{mode}} instruction pattern 7163@cindex @code{atomic_sub@var{mode}} instruction pattern 7164@cindex @code{atomic_or@var{mode}} instruction pattern 7165@cindex @code{atomic_and@var{mode}} instruction pattern 7166@cindex @code{atomic_xor@var{mode}} instruction pattern 7167@cindex @code{atomic_nand@var{mode}} instruction pattern 7168@item @samp{atomic_add@var{mode}}, @samp{atomic_sub@var{mode}} 7169@itemx @samp{atomic_or@var{mode}}, @samp{atomic_and@var{mode}} 7170@itemx @samp{atomic_xor@var{mode}}, @samp{atomic_nand@var{mode}} 7171These patterns emit code for an atomic operation on memory with memory 7172model semantics. Operand 0 is the memory on which the atomic operation is 7173performed. Operand 1 is the second operand to the binary operator. 7174Operand 2 is the memory model to be used by the operation. 7175 7176If these patterns are not defined, attempts will be made to use legacy 7177@code{sync} patterns, or equivalent patterns which return a result. If 7178none of these are available a compare-and-swap loop will be used. 7179 7180@cindex @code{atomic_fetch_add@var{mode}} instruction pattern 7181@cindex @code{atomic_fetch_sub@var{mode}} instruction pattern 7182@cindex @code{atomic_fetch_or@var{mode}} instruction pattern 7183@cindex @code{atomic_fetch_and@var{mode}} instruction pattern 7184@cindex @code{atomic_fetch_xor@var{mode}} instruction pattern 7185@cindex @code{atomic_fetch_nand@var{mode}} instruction pattern 7186@item @samp{atomic_fetch_add@var{mode}}, @samp{atomic_fetch_sub@var{mode}} 7187@itemx @samp{atomic_fetch_or@var{mode}}, @samp{atomic_fetch_and@var{mode}} 7188@itemx @samp{atomic_fetch_xor@var{mode}}, @samp{atomic_fetch_nand@var{mode}} 7189These patterns emit code for an atomic operation on memory with memory 7190model semantics, and return the original value. Operand 0 is an output 7191operand which contains the value of the memory location before the 7192operation was performed. Operand 1 is the memory on which the atomic 7193operation is performed. Operand 2 is the second operand to the binary 7194operator. Operand 3 is the memory model to be used by the operation. 7195 7196If these patterns are not defined, attempts will be made to use legacy 7197@code{sync} patterns. If none of these are available a compare-and-swap 7198loop will be used. 7199 7200@cindex @code{atomic_add_fetch@var{mode}} instruction pattern 7201@cindex @code{atomic_sub_fetch@var{mode}} instruction pattern 7202@cindex @code{atomic_or_fetch@var{mode}} instruction pattern 7203@cindex @code{atomic_and_fetch@var{mode}} instruction pattern 7204@cindex @code{atomic_xor_fetch@var{mode}} instruction pattern 7205@cindex @code{atomic_nand_fetch@var{mode}} instruction pattern 7206@item @samp{atomic_add_fetch@var{mode}}, @samp{atomic_sub_fetch@var{mode}} 7207@itemx @samp{atomic_or_fetch@var{mode}}, @samp{atomic_and_fetch@var{mode}} 7208@itemx @samp{atomic_xor_fetch@var{mode}}, @samp{atomic_nand_fetch@var{mode}} 7209These patterns emit code for an atomic operation on memory with memory 7210model semantics and return the result after the operation is performed. 7211Operand 0 is an output operand which contains the value after the 7212operation. Operand 1 is the memory on which the atomic operation is 7213performed. Operand 2 is the second operand to the binary operator. 7214Operand 3 is the memory model to be used by the operation. 7215 7216If these patterns are not defined, attempts will be made to use legacy 7217@code{sync} patterns, or equivalent patterns which return the result before 7218the operation followed by the arithmetic operation required to produce the 7219result. If none of these are available a compare-and-swap loop will be 7220used. 7221 7222@cindex @code{atomic_test_and_set} instruction pattern 7223@item @samp{atomic_test_and_set} 7224This pattern emits code for @code{__builtin_atomic_test_and_set}. 7225Operand 0 is an output operand which is set to true if the previous 7226previous contents of the byte was "set", and false otherwise. Operand 1 7227is the @code{QImode} memory to be modified. Operand 2 is the memory 7228model to be used. 7229 7230The specific value that defines "set" is implementation defined, and 7231is normally based on what is performed by the native atomic test and set 7232instruction. 7233 7234@cindex @code{atomic_bit_test_and_set@var{mode}} instruction pattern 7235@cindex @code{atomic_bit_test_and_complement@var{mode}} instruction pattern 7236@cindex @code{atomic_bit_test_and_reset@var{mode}} instruction pattern 7237@item @samp{atomic_bit_test_and_set@var{mode}} 7238@itemx @samp{atomic_bit_test_and_complement@var{mode}} 7239@itemx @samp{atomic_bit_test_and_reset@var{mode}} 7240These patterns emit code for an atomic bitwise operation on memory with memory 7241model semantics, and return the original value of the specified bit. 7242Operand 0 is an output operand which contains the value of the specified bit 7243from the memory location before the operation was performed. Operand 1 is the 7244memory on which the atomic operation is performed. Operand 2 is the bit within 7245the operand, starting with least significant bit. Operand 3 is the memory model 7246to be used by the operation. Operand 4 is a flag - it is @code{const1_rtx} 7247if operand 0 should contain the original value of the specified bit in the 7248least significant bit of the operand, and @code{const0_rtx} if the bit should 7249be in its original position in the operand. 7250@code{atomic_bit_test_and_set@var{mode}} atomically sets the specified bit after 7251remembering its original value, @code{atomic_bit_test_and_complement@var{mode}} 7252inverts the specified bit and @code{atomic_bit_test_and_reset@var{mode}} clears 7253the specified bit. 7254 7255If these patterns are not defined, attempts will be made to use 7256@code{atomic_fetch_or@var{mode}}, @code{atomic_fetch_xor@var{mode}} or 7257@code{atomic_fetch_and@var{mode}} instruction patterns, or their @code{sync} 7258counterparts. If none of these are available a compare-and-swap 7259loop will be used. 7260 7261@cindex @code{mem_thread_fence} instruction pattern 7262@item @samp{mem_thread_fence} 7263This pattern emits code required to implement a thread fence with 7264memory model semantics. Operand 0 is the memory model to be used. 7265 7266For the @code{__ATOMIC_RELAXED} model no instructions need to be issued 7267and this expansion is not invoked. 7268 7269The compiler always emits a compiler memory barrier regardless of what 7270expanding this pattern produced. 7271 7272If this pattern is not defined, the compiler falls back to expanding the 7273@code{memory_barrier} pattern, then to emitting @code{__sync_synchronize} 7274library call, and finally to just placing a compiler memory barrier. 7275 7276@cindex @code{get_thread_pointer@var{mode}} instruction pattern 7277@cindex @code{set_thread_pointer@var{mode}} instruction pattern 7278@item @samp{get_thread_pointer@var{mode}} 7279@itemx @samp{set_thread_pointer@var{mode}} 7280These patterns emit code that reads/sets the TLS thread pointer. Currently, 7281these are only needed if the target needs to support the 7282@code{__builtin_thread_pointer} and @code{__builtin_set_thread_pointer} 7283builtins. 7284 7285The get/set patterns have a single output/input operand respectively, 7286with @var{mode} intended to be @code{Pmode}. 7287 7288@cindex @code{stack_protect_set} instruction pattern 7289@item @samp{stack_protect_set} 7290This pattern, if defined, moves a @code{ptr_mode} value from the memory 7291in operand 1 to the memory in operand 0 without leaving the value in 7292a register afterward. This is to avoid leaking the value some place 7293that an attacker might use to rewrite the stack guard slot after 7294having clobbered it. 7295 7296If this pattern is not defined, then a plain move pattern is generated. 7297 7298@cindex @code{stack_protect_test} instruction pattern 7299@item @samp{stack_protect_test} 7300This pattern, if defined, compares a @code{ptr_mode} value from the 7301memory in operand 1 with the memory in operand 0 without leaving the 7302value in a register afterward and branches to operand 2 if the values 7303were equal. 7304 7305If this pattern is not defined, then a plain compare pattern and 7306conditional branch pattern is used. 7307 7308@cindex @code{clear_cache} instruction pattern 7309@item @samp{clear_cache} 7310This pattern, if defined, flushes the instruction cache for a region of 7311memory. The region is bounded to by the Pmode pointers in operand 0 7312inclusive and operand 1 exclusive. 7313 7314If this pattern is not defined, a call to the library function 7315@code{__clear_cache} is used. 7316 7317@end table 7318 7319@end ifset 7320@c Each of the following nodes are wrapped in separate 7321@c "@ifset INTERNALS" to work around memory limits for the default 7322@c configuration in older tetex distributions. Known to not work: 7323@c tetex-1.0.7, known to work: tetex-2.0.2. 7324@ifset INTERNALS 7325@node Pattern Ordering 7326@section When the Order of Patterns Matters 7327@cindex Pattern Ordering 7328@cindex Ordering of Patterns 7329 7330Sometimes an insn can match more than one instruction pattern. Then the 7331pattern that appears first in the machine description is the one used. 7332Therefore, more specific patterns (patterns that will match fewer things) 7333and faster instructions (those that will produce better code when they 7334do match) should usually go first in the description. 7335 7336In some cases the effect of ordering the patterns can be used to hide 7337a pattern when it is not valid. For example, the 68000 has an 7338instruction for converting a fullword to floating point and another 7339for converting a byte to floating point. An instruction converting 7340an integer to floating point could match either one. We put the 7341pattern to convert the fullword first to make sure that one will 7342be used rather than the other. (Otherwise a large integer might 7343be generated as a single-byte immediate quantity, which would not work.) 7344Instead of using this pattern ordering it would be possible to make the 7345pattern for convert-a-byte smart enough to deal properly with any 7346constant value. 7347 7348@end ifset 7349@ifset INTERNALS 7350@node Dependent Patterns 7351@section Interdependence of Patterns 7352@cindex Dependent Patterns 7353@cindex Interdependence of Patterns 7354 7355In some cases machines support instructions identical except for the 7356machine mode of one or more operands. For example, there may be 7357``sign-extend halfword'' and ``sign-extend byte'' instructions whose 7358patterns are 7359 7360@smallexample 7361(set (match_operand:SI 0 @dots{}) 7362 (extend:SI (match_operand:HI 1 @dots{}))) 7363 7364(set (match_operand:SI 0 @dots{}) 7365 (extend:SI (match_operand:QI 1 @dots{}))) 7366@end smallexample 7367 7368@noindent 7369Constant integers do not specify a machine mode, so an instruction to 7370extend a constant value could match either pattern. The pattern it 7371actually will match is the one that appears first in the file. For correct 7372results, this must be the one for the widest possible mode (@code{HImode}, 7373here). If the pattern matches the @code{QImode} instruction, the results 7374will be incorrect if the constant value does not actually fit that mode. 7375 7376Such instructions to extend constants are rarely generated because they are 7377optimized away, but they do occasionally happen in nonoptimized 7378compilations. 7379 7380If a constraint in a pattern allows a constant, the reload pass may 7381replace a register with a constant permitted by the constraint in some 7382cases. Similarly for memory references. Because of this substitution, 7383you should not provide separate patterns for increment and decrement 7384instructions. Instead, they should be generated from the same pattern 7385that supports register-register add insns by examining the operands and 7386generating the appropriate machine instruction. 7387 7388@end ifset 7389@ifset INTERNALS 7390@node Jump Patterns 7391@section Defining Jump Instruction Patterns 7392@cindex jump instruction patterns 7393@cindex defining jump instruction patterns 7394 7395GCC does not assume anything about how the machine realizes jumps. 7396The machine description should define a single pattern, usually 7397a @code{define_expand}, which expands to all the required insns. 7398 7399Usually, this would be a comparison insn to set the condition code 7400and a separate branch insn testing the condition code and branching 7401or not according to its value. For many machines, however, 7402separating compares and branches is limiting, which is why the 7403more flexible approach with one @code{define_expand} is used in GCC. 7404The machine description becomes clearer for architectures that 7405have compare-and-branch instructions but no condition code. It also 7406works better when different sets of comparison operators are supported 7407by different kinds of conditional branches (e.g. integer vs. floating-point), 7408or by conditional branches with respect to conditional stores. 7409 7410Two separate insns are always used if the machine description represents 7411a condition code register using the legacy RTL expression @code{(cc0)}, 7412and on most machines that use a separate condition code register 7413(@pxref{Condition Code}). For machines that use @code{(cc0)}, in 7414fact, the set and use of the condition code must be separate and 7415adjacent@footnote{@code{note} insns can separate them, though.}, thus 7416allowing flags in @code{cc_status} to be used (@pxref{Condition Code}) and 7417so that the comparison and branch insns could be located from each other 7418by using the functions @code{prev_cc0_setter} and @code{next_cc0_user}. 7419 7420Even in this case having a single entry point for conditional branches 7421is advantageous, because it handles equally well the case where a single 7422comparison instruction records the results of both signed and unsigned 7423comparison of the given operands (with the branch insns coming in distinct 7424signed and unsigned flavors) as in the x86 or SPARC, and the case where 7425there are distinct signed and unsigned compare instructions and only 7426one set of conditional branch instructions as in the PowerPC. 7427 7428@end ifset 7429@ifset INTERNALS 7430@node Looping Patterns 7431@section Defining Looping Instruction Patterns 7432@cindex looping instruction patterns 7433@cindex defining looping instruction patterns 7434 7435Some machines have special jump instructions that can be utilized to 7436make loops more efficient. A common example is the 68000 @samp{dbra} 7437instruction which performs a decrement of a register and a branch if the 7438result was greater than zero. Other machines, in particular digital 7439signal processors (DSPs), have special block repeat instructions to 7440provide low-overhead loop support. For example, the TI TMS320C3x/C4x 7441DSPs have a block repeat instruction that loads special registers to 7442mark the top and end of a loop and to count the number of loop 7443iterations. This avoids the need for fetching and executing a 7444@samp{dbra}-like instruction and avoids pipeline stalls associated with 7445the jump. 7446 7447GCC has three special named patterns to support low overhead looping. 7448They are @samp{decrement_and_branch_until_zero}, @samp{doloop_begin}, 7449and @samp{doloop_end}. The first pattern, 7450@samp{decrement_and_branch_until_zero}, is not emitted during RTL 7451generation but may be emitted during the instruction combination phase. 7452This requires the assistance of the loop optimizer, using information 7453collected during strength reduction, to reverse a loop to count down to 7454zero. Some targets also require the loop optimizer to add a 7455@code{REG_NONNEG} note to indicate that the iteration count is always 7456positive. This is needed if the target performs a signed loop 7457termination test. For example, the 68000 uses a pattern similar to the 7458following for its @code{dbra} instruction: 7459 7460@smallexample 7461@group 7462(define_insn "decrement_and_branch_until_zero" 7463 [(set (pc) 7464 (if_then_else 7465 (ge (plus:SI (match_operand:SI 0 "general_operand" "+d*am") 7466 (const_int -1)) 7467 (const_int 0)) 7468 (label_ref (match_operand 1 "" "")) 7469 (pc))) 7470 (set (match_dup 0) 7471 (plus:SI (match_dup 0) 7472 (const_int -1)))] 7473 "find_reg_note (insn, REG_NONNEG, 0)" 7474 "@dots{}") 7475@end group 7476@end smallexample 7477 7478Note that since the insn is both a jump insn and has an output, it must 7479deal with its own reloads, hence the `m' constraints. Also note that 7480since this insn is generated by the instruction combination phase 7481combining two sequential insns together into an implicit parallel insn, 7482the iteration counter needs to be biased by the same amount as the 7483decrement operation, in this case @minus{}1. Note that the following similar 7484pattern will not be matched by the combiner. 7485 7486@smallexample 7487@group 7488(define_insn "decrement_and_branch_until_zero" 7489 [(set (pc) 7490 (if_then_else 7491 (ge (match_operand:SI 0 "general_operand" "+d*am") 7492 (const_int 1)) 7493 (label_ref (match_operand 1 "" "")) 7494 (pc))) 7495 (set (match_dup 0) 7496 (plus:SI (match_dup 0) 7497 (const_int -1)))] 7498 "find_reg_note (insn, REG_NONNEG, 0)" 7499 "@dots{}") 7500@end group 7501@end smallexample 7502 7503The other two special looping patterns, @samp{doloop_begin} and 7504@samp{doloop_end}, are emitted by the loop optimizer for certain 7505well-behaved loops with a finite number of loop iterations using 7506information collected during strength reduction. 7507 7508The @samp{doloop_end} pattern describes the actual looping instruction 7509(or the implicit looping operation) and the @samp{doloop_begin} pattern 7510is an optional companion pattern that can be used for initialization 7511needed for some low-overhead looping instructions. 7512 7513Note that some machines require the actual looping instruction to be 7514emitted at the top of the loop (e.g., the TMS320C3x/C4x DSPs). Emitting 7515the true RTL for a looping instruction at the top of the loop can cause 7516problems with flow analysis. So instead, a dummy @code{doloop} insn is 7517emitted at the end of the loop. The machine dependent reorg pass checks 7518for the presence of this @code{doloop} insn and then searches back to 7519the top of the loop, where it inserts the true looping insn (provided 7520there are no instructions in the loop which would cause problems). Any 7521additional labels can be emitted at this point. In addition, if the 7522desired special iteration counter register was not allocated, this 7523machine dependent reorg pass could emit a traditional compare and jump 7524instruction pair. 7525 7526The essential difference between the 7527@samp{decrement_and_branch_until_zero} and the @samp{doloop_end} 7528patterns is that the loop optimizer allocates an additional pseudo 7529register for the latter as an iteration counter. This pseudo register 7530cannot be used within the loop (i.e., general induction variables cannot 7531be derived from it), however, in many cases the loop induction variable 7532may become redundant and removed by the flow pass. 7533 7534 7535@end ifset 7536@ifset INTERNALS 7537@node Insn Canonicalizations 7538@section Canonicalization of Instructions 7539@cindex canonicalization of instructions 7540@cindex insn canonicalization 7541 7542There are often cases where multiple RTL expressions could represent an 7543operation performed by a single machine instruction. This situation is 7544most commonly encountered with logical, branch, and multiply-accumulate 7545instructions. In such cases, the compiler attempts to convert these 7546multiple RTL expressions into a single canonical form to reduce the 7547number of insn patterns required. 7548 7549In addition to algebraic simplifications, following canonicalizations 7550are performed: 7551 7552@itemize @bullet 7553@item 7554For commutative and comparison operators, a constant is always made the 7555second operand. If a machine only supports a constant as the second 7556operand, only patterns that match a constant in the second operand need 7557be supplied. 7558 7559@item 7560For associative operators, a sequence of operators will always chain 7561to the left; for instance, only the left operand of an integer @code{plus} 7562can itself be a @code{plus}. @code{and}, @code{ior}, @code{xor}, 7563@code{plus}, @code{mult}, @code{smin}, @code{smax}, @code{umin}, and 7564@code{umax} are associative when applied to integers, and sometimes to 7565floating-point. 7566 7567@item 7568@cindex @code{neg}, canonicalization of 7569@cindex @code{not}, canonicalization of 7570@cindex @code{mult}, canonicalization of 7571@cindex @code{plus}, canonicalization of 7572@cindex @code{minus}, canonicalization of 7573For these operators, if only one operand is a @code{neg}, @code{not}, 7574@code{mult}, @code{plus}, or @code{minus} expression, it will be the 7575first operand. 7576 7577@item 7578In combinations of @code{neg}, @code{mult}, @code{plus}, and 7579@code{minus}, the @code{neg} operations (if any) will be moved inside 7580the operations as far as possible. For instance, 7581@code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but 7582@code{(plus (mult (neg B) C) A)} is canonicalized as 7583@code{(minus A (mult B C))}. 7584 7585@cindex @code{compare}, canonicalization of 7586@item 7587For the @code{compare} operator, a constant is always the second operand 7588if the first argument is a condition code register or @code{(cc0)}. 7589 7590@item 7591For instructions that inherently set a condition code register, the 7592@code{compare} operator is always written as the first RTL expression of 7593the @code{parallel} instruction pattern. For example, 7594 7595@smallexample 7596(define_insn "" 7597 [(set (reg:CCZ FLAGS_REG) 7598 (compare:CCZ 7599 (plus:SI 7600 (match_operand:SI 1 "register_operand" "%r") 7601 (match_operand:SI 2 "register_operand" "r")) 7602 (const_int 0))) 7603 (set (match_operand:SI 0 "register_operand" "=r") 7604 (plus:SI (match_dup 1) (match_dup 2)))] 7605 "" 7606 "addl %0, %1, %2") 7607@end smallexample 7608 7609@item 7610An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or 7611@code{minus} is made the first operand under the same conditions as 7612above. 7613 7614@item 7615@code{(ltu (plus @var{a} @var{b}) @var{b})} is converted to 7616@code{(ltu (plus @var{a} @var{b}) @var{a})}. Likewise with @code{geu} instead 7617of @code{ltu}. 7618 7619@item 7620@code{(minus @var{x} (const_int @var{n}))} is converted to 7621@code{(plus @var{x} (const_int @var{-n}))}. 7622 7623@item 7624Within address computations (i.e., inside @code{mem}), a left shift is 7625converted into the appropriate multiplication by a power of two. 7626 7627@cindex @code{ior}, canonicalization of 7628@cindex @code{and}, canonicalization of 7629@cindex De Morgan's law 7630@item 7631De Morgan's Law is used to move bitwise negation inside a bitwise 7632logical-and or logical-or operation. If this results in only one 7633operand being a @code{not} expression, it will be the first one. 7634 7635A machine that has an instruction that performs a bitwise logical-and of one 7636operand with the bitwise negation of the other should specify the pattern 7637for that instruction as 7638 7639@smallexample 7640(define_insn "" 7641 [(set (match_operand:@var{m} 0 @dots{}) 7642 (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) 7643 (match_operand:@var{m} 2 @dots{})))] 7644 "@dots{}" 7645 "@dots{}") 7646@end smallexample 7647 7648@noindent 7649Similarly, a pattern for a ``NAND'' instruction should be written 7650 7651@smallexample 7652(define_insn "" 7653 [(set (match_operand:@var{m} 0 @dots{}) 7654 (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) 7655 (not:@var{m} (match_operand:@var{m} 2 @dots{}))))] 7656 "@dots{}" 7657 "@dots{}") 7658@end smallexample 7659 7660In both cases, it is not necessary to include patterns for the many 7661logically equivalent RTL expressions. 7662 7663@cindex @code{xor}, canonicalization of 7664@item 7665The only possible RTL expressions involving both bitwise exclusive-or 7666and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})} 7667and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}. 7668 7669@item 7670The sum of three items, one of which is a constant, will only appear in 7671the form 7672 7673@smallexample 7674(plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant}) 7675@end smallexample 7676 7677@cindex @code{zero_extract}, canonicalization of 7678@cindex @code{sign_extract}, canonicalization of 7679@item 7680Equality comparisons of a group of bits (usually a single bit) with zero 7681will be written using @code{zero_extract} rather than the equivalent 7682@code{and} or @code{sign_extract} operations. 7683 7684@cindex @code{mult}, canonicalization of 7685@item 7686@code{(sign_extend:@var{m1} (mult:@var{m2} (sign_extend:@var{m2} @var{x}) 7687(sign_extend:@var{m2} @var{y})))} is converted to @code{(mult:@var{m1} 7688(sign_extend:@var{m1} @var{x}) (sign_extend:@var{m1} @var{y}))}, and likewise 7689for @code{zero_extend}. 7690 7691@item 7692@code{(sign_extend:@var{m1} (mult:@var{m2} (ashiftrt:@var{m2} 7693@var{x} @var{s}) (sign_extend:@var{m2} @var{y})))} is converted 7694to @code{(mult:@var{m1} (sign_extend:@var{m1} (ashiftrt:@var{m2} 7695@var{x} @var{s})) (sign_extend:@var{m1} @var{y}))}, and likewise for 7696patterns using @code{zero_extend} and @code{lshiftrt}. If the second 7697operand of @code{mult} is also a shift, then that is extended also. 7698This transformation is only applied when it can be proven that the 7699original operation had sufficient precision to prevent overflow. 7700 7701@end itemize 7702 7703Further canonicalization rules are defined in the function 7704@code{commutative_operand_precedence} in @file{gcc/rtlanal.c}. 7705 7706@end ifset 7707@ifset INTERNALS 7708@node Expander Definitions 7709@section Defining RTL Sequences for Code Generation 7710@cindex expander definitions 7711@cindex code generation RTL sequences 7712@cindex defining RTL sequences for code generation 7713 7714On some target machines, some standard pattern names for RTL generation 7715cannot be handled with single insn, but a sequence of RTL insns can 7716represent them. For these target machines, you can write a 7717@code{define_expand} to specify how to generate the sequence of RTL@. 7718 7719@findex define_expand 7720A @code{define_expand} is an RTL expression that looks almost like a 7721@code{define_insn}; but, unlike the latter, a @code{define_expand} is used 7722only for RTL generation and it can produce more than one RTL insn. 7723 7724A @code{define_expand} RTX has four operands: 7725 7726@itemize @bullet 7727@item 7728The name. Each @code{define_expand} must have a name, since the only 7729use for it is to refer to it by name. 7730 7731@item 7732The RTL template. This is a vector of RTL expressions representing 7733a sequence of separate instructions. Unlike @code{define_insn}, there 7734is no implicit surrounding @code{PARALLEL}. 7735 7736@item 7737The condition, a string containing a C expression. This expression is 7738used to express how the availability of this pattern depends on 7739subclasses of target machine, selected by command-line options when GCC 7740is run. This is just like the condition of a @code{define_insn} that 7741has a standard name. Therefore, the condition (if present) may not 7742depend on the data in the insn being matched, but only the 7743target-machine-type flags. The compiler needs to test these conditions 7744during initialization in order to learn exactly which named instructions 7745are available in a particular run. 7746 7747@item 7748The preparation statements, a string containing zero or more C 7749statements which are to be executed before RTL code is generated from 7750the RTL template. 7751 7752Usually these statements prepare temporary registers for use as 7753internal operands in the RTL template, but they can also generate RTL 7754insns directly by calling routines such as @code{emit_insn}, etc. 7755Any such insns precede the ones that come from the RTL template. 7756 7757@item 7758Optionally, a vector containing the values of attributes. @xref{Insn 7759Attributes}. 7760@end itemize 7761 7762Every RTL insn emitted by a @code{define_expand} must match some 7763@code{define_insn} in the machine description. Otherwise, the compiler 7764will crash when trying to generate code for the insn or trying to optimize 7765it. 7766 7767The RTL template, in addition to controlling generation of RTL insns, 7768also describes the operands that need to be specified when this pattern 7769is used. In particular, it gives a predicate for each operand. 7770 7771A true operand, which needs to be specified in order to generate RTL from 7772the pattern, should be described with a @code{match_operand} in its first 7773occurrence in the RTL template. This enters information on the operand's 7774predicate into the tables that record such things. GCC uses the 7775information to preload the operand into a register if that is required for 7776valid RTL code. If the operand is referred to more than once, subsequent 7777references should use @code{match_dup}. 7778 7779The RTL template may also refer to internal ``operands'' which are 7780temporary registers or labels used only within the sequence made by the 7781@code{define_expand}. Internal operands are substituted into the RTL 7782template with @code{match_dup}, never with @code{match_operand}. The 7783values of the internal operands are not passed in as arguments by the 7784compiler when it requests use of this pattern. Instead, they are computed 7785within the pattern, in the preparation statements. These statements 7786compute the values and store them into the appropriate elements of 7787@code{operands} so that @code{match_dup} can find them. 7788 7789There are two special macros defined for use in the preparation statements: 7790@code{DONE} and @code{FAIL}. Use them with a following semicolon, 7791as a statement. 7792 7793@table @code 7794 7795@findex DONE 7796@item DONE 7797Use the @code{DONE} macro to end RTL generation for the pattern. The 7798only RTL insns resulting from the pattern on this occasion will be 7799those already emitted by explicit calls to @code{emit_insn} within the 7800preparation statements; the RTL template will not be generated. 7801 7802@findex FAIL 7803@item FAIL 7804Make the pattern fail on this occasion. When a pattern fails, it means 7805that the pattern was not truly available. The calling routines in the 7806compiler will try other strategies for code generation using other patterns. 7807 7808Failure is currently supported only for binary (addition, multiplication, 7809shifting, etc.) and bit-field (@code{extv}, @code{extzv}, and @code{insv}) 7810operations. 7811@end table 7812 7813If the preparation falls through (invokes neither @code{DONE} nor 7814@code{FAIL}), then the @code{define_expand} acts like a 7815@code{define_insn} in that the RTL template is used to generate the 7816insn. 7817 7818The RTL template is not used for matching, only for generating the 7819initial insn list. If the preparation statement always invokes 7820@code{DONE} or @code{FAIL}, the RTL template may be reduced to a simple 7821list of operands, such as this example: 7822 7823@smallexample 7824@group 7825(define_expand "addsi3" 7826 [(match_operand:SI 0 "register_operand" "") 7827 (match_operand:SI 1 "register_operand" "") 7828 (match_operand:SI 2 "register_operand" "")] 7829@end group 7830@group 7831 "" 7832 " 7833@{ 7834 handle_add (operands[0], operands[1], operands[2]); 7835 DONE; 7836@}") 7837@end group 7838@end smallexample 7839 7840Here is an example, the definition of left-shift for the SPUR chip: 7841 7842@smallexample 7843@group 7844(define_expand "ashlsi3" 7845 [(set (match_operand:SI 0 "register_operand" "") 7846 (ashift:SI 7847@end group 7848@group 7849 (match_operand:SI 1 "register_operand" "") 7850 (match_operand:SI 2 "nonmemory_operand" "")))] 7851 "" 7852 " 7853@end group 7854@end smallexample 7855 7856@smallexample 7857@group 7858@{ 7859 if (GET_CODE (operands[2]) != CONST_INT 7860 || (unsigned) INTVAL (operands[2]) > 3) 7861 FAIL; 7862@}") 7863@end group 7864@end smallexample 7865 7866@noindent 7867This example uses @code{define_expand} so that it can generate an RTL insn 7868for shifting when the shift-count is in the supported range of 0 to 3 but 7869fail in other cases where machine insns aren't available. When it fails, 7870the compiler tries another strategy using different patterns (such as, a 7871library call). 7872 7873If the compiler were able to handle nontrivial condition-strings in 7874patterns with names, then it would be possible to use a 7875@code{define_insn} in that case. Here is another case (zero-extension 7876on the 68000) which makes more use of the power of @code{define_expand}: 7877 7878@smallexample 7879(define_expand "zero_extendhisi2" 7880 [(set (match_operand:SI 0 "general_operand" "") 7881 (const_int 0)) 7882 (set (strict_low_part 7883 (subreg:HI 7884 (match_dup 0) 7885 0)) 7886 (match_operand:HI 1 "general_operand" ""))] 7887 "" 7888 "operands[1] = make_safe_from (operands[1], operands[0]);") 7889@end smallexample 7890 7891@noindent 7892@findex make_safe_from 7893Here two RTL insns are generated, one to clear the entire output operand 7894and the other to copy the input operand into its low half. This sequence 7895is incorrect if the input operand refers to [the old value of] the output 7896operand, so the preparation statement makes sure this isn't so. The 7897function @code{make_safe_from} copies the @code{operands[1]} into a 7898temporary register if it refers to @code{operands[0]}. It does this 7899by emitting another RTL insn. 7900 7901Finally, a third example shows the use of an internal operand. 7902Zero-extension on the SPUR chip is done by @code{and}-ing the result 7903against a halfword mask. But this mask cannot be represented by a 7904@code{const_int} because the constant value is too large to be legitimate 7905on this machine. So it must be copied into a register with 7906@code{force_reg} and then the register used in the @code{and}. 7907 7908@smallexample 7909(define_expand "zero_extendhisi2" 7910 [(set (match_operand:SI 0 "register_operand" "") 7911 (and:SI (subreg:SI 7912 (match_operand:HI 1 "register_operand" "") 7913 0) 7914 (match_dup 2)))] 7915 "" 7916 "operands[2] 7917 = force_reg (SImode, GEN_INT (65535)); ") 7918@end smallexample 7919 7920@emph{Note:} If the @code{define_expand} is used to serve a 7921standard binary or unary arithmetic operation or a bit-field operation, 7922then the last insn it generates must not be a @code{code_label}, 7923@code{barrier} or @code{note}. It must be an @code{insn}, 7924@code{jump_insn} or @code{call_insn}. If you don't need a real insn 7925at the end, emit an insn to copy the result of the operation into 7926itself. Such an insn will generate no code, but it can avoid problems 7927in the compiler. 7928 7929@end ifset 7930@ifset INTERNALS 7931@node Insn Splitting 7932@section Defining How to Split Instructions 7933@cindex insn splitting 7934@cindex instruction splitting 7935@cindex splitting instructions 7936 7937There are two cases where you should specify how to split a pattern 7938into multiple insns. On machines that have instructions requiring 7939delay slots (@pxref{Delay Slots}) or that have instructions whose 7940output is not available for multiple cycles (@pxref{Processor pipeline 7941description}), the compiler phases that optimize these cases need to 7942be able to move insns into one-instruction delay slots. However, some 7943insns may generate more than one machine instruction. These insns 7944cannot be placed into a delay slot. 7945 7946Often you can rewrite the single insn as a list of individual insns, 7947each corresponding to one machine instruction. The disadvantage of 7948doing so is that it will cause the compilation to be slower and require 7949more space. If the resulting insns are too complex, it may also 7950suppress some optimizations. The compiler splits the insn if there is a 7951reason to believe that it might improve instruction or delay slot 7952scheduling. 7953 7954The insn combiner phase also splits putative insns. If three insns are 7955merged into one insn with a complex expression that cannot be matched by 7956some @code{define_insn} pattern, the combiner phase attempts to split 7957the complex pattern into two insns that are recognized. Usually it can 7958break the complex pattern into two patterns by splitting out some 7959subexpression. However, in some other cases, such as performing an 7960addition of a large constant in two insns on a RISC machine, the way to 7961split the addition into two insns is machine-dependent. 7962 7963@findex define_split 7964The @code{define_split} definition tells the compiler how to split a 7965complex insn into several simpler insns. It looks like this: 7966 7967@smallexample 7968(define_split 7969 [@var{insn-pattern}] 7970 "@var{condition}" 7971 [@var{new-insn-pattern-1} 7972 @var{new-insn-pattern-2} 7973 @dots{}] 7974 "@var{preparation-statements}") 7975@end smallexample 7976 7977@var{insn-pattern} is a pattern that needs to be split and 7978@var{condition} is the final condition to be tested, as in a 7979@code{define_insn}. When an insn matching @var{insn-pattern} and 7980satisfying @var{condition} is found, it is replaced in the insn list 7981with the insns given by @var{new-insn-pattern-1}, 7982@var{new-insn-pattern-2}, etc. 7983 7984The @var{preparation-statements} are similar to those statements that 7985are specified for @code{define_expand} (@pxref{Expander Definitions}) 7986and are executed before the new RTL is generated to prepare for the 7987generated code or emit some insns whose pattern is not fixed. Unlike 7988those in @code{define_expand}, however, these statements must not 7989generate any new pseudo-registers. Once reload has completed, they also 7990must not allocate any space in the stack frame. 7991 7992Patterns are matched against @var{insn-pattern} in two different 7993circumstances. If an insn needs to be split for delay slot scheduling 7994or insn scheduling, the insn is already known to be valid, which means 7995that it must have been matched by some @code{define_insn} and, if 7996@code{reload_completed} is nonzero, is known to satisfy the constraints 7997of that @code{define_insn}. In that case, the new insn patterns must 7998also be insns that are matched by some @code{define_insn} and, if 7999@code{reload_completed} is nonzero, must also satisfy the constraints 8000of those definitions. 8001 8002As an example of this usage of @code{define_split}, consider the following 8003example from @file{a29k.md}, which splits a @code{sign_extend} from 8004@code{HImode} to @code{SImode} into a pair of shift insns: 8005 8006@smallexample 8007(define_split 8008 [(set (match_operand:SI 0 "gen_reg_operand" "") 8009 (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))] 8010 "" 8011 [(set (match_dup 0) 8012 (ashift:SI (match_dup 1) 8013 (const_int 16))) 8014 (set (match_dup 0) 8015 (ashiftrt:SI (match_dup 0) 8016 (const_int 16)))] 8017 " 8018@{ operands[1] = gen_lowpart (SImode, operands[1]); @}") 8019@end smallexample 8020 8021When the combiner phase tries to split an insn pattern, it is always the 8022case that the pattern is @emph{not} matched by any @code{define_insn}. 8023The combiner pass first tries to split a single @code{set} expression 8024and then the same @code{set} expression inside a @code{parallel}, but 8025followed by a @code{clobber} of a pseudo-reg to use as a scratch 8026register. In these cases, the combiner expects exactly two new insn 8027patterns to be generated. It will verify that these patterns match some 8028@code{define_insn} definitions, so you need not do this test in the 8029@code{define_split} (of course, there is no point in writing a 8030@code{define_split} that will never produce insns that match). 8031 8032Here is an example of this use of @code{define_split}, taken from 8033@file{rs6000.md}: 8034 8035@smallexample 8036(define_split 8037 [(set (match_operand:SI 0 "gen_reg_operand" "") 8038 (plus:SI (match_operand:SI 1 "gen_reg_operand" "") 8039 (match_operand:SI 2 "non_add_cint_operand" "")))] 8040 "" 8041 [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3))) 8042 (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))] 8043" 8044@{ 8045 int low = INTVAL (operands[2]) & 0xffff; 8046 int high = (unsigned) INTVAL (operands[2]) >> 16; 8047 8048 if (low & 0x8000) 8049 high++, low |= 0xffff0000; 8050 8051 operands[3] = GEN_INT (high << 16); 8052 operands[4] = GEN_INT (low); 8053@}") 8054@end smallexample 8055 8056Here the predicate @code{non_add_cint_operand} matches any 8057@code{const_int} that is @emph{not} a valid operand of a single add 8058insn. The add with the smaller displacement is written so that it 8059can be substituted into the address of a subsequent operation. 8060 8061An example that uses a scratch register, from the same file, generates 8062an equality comparison of a register and a large constant: 8063 8064@smallexample 8065(define_split 8066 [(set (match_operand:CC 0 "cc_reg_operand" "") 8067 (compare:CC (match_operand:SI 1 "gen_reg_operand" "") 8068 (match_operand:SI 2 "non_short_cint_operand" ""))) 8069 (clobber (match_operand:SI 3 "gen_reg_operand" ""))] 8070 "find_single_use (operands[0], insn, 0) 8071 && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ 8072 || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)" 8073 [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4))) 8074 (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))] 8075 " 8076@{ 8077 /* @r{Get the constant we are comparing against, C, and see what it 8078 looks like sign-extended to 16 bits. Then see what constant 8079 could be XOR'ed with C to get the sign-extended value.} */ 8080 8081 int c = INTVAL (operands[2]); 8082 int sextc = (c << 16) >> 16; 8083 int xorv = c ^ sextc; 8084 8085 operands[4] = GEN_INT (xorv); 8086 operands[5] = GEN_INT (sextc); 8087@}") 8088@end smallexample 8089 8090To avoid confusion, don't write a single @code{define_split} that 8091accepts some insns that match some @code{define_insn} as well as some 8092insns that don't. Instead, write two separate @code{define_split} 8093definitions, one for the insns that are valid and one for the insns that 8094are not valid. 8095 8096The splitter is allowed to split jump instructions into sequence of 8097jumps or create new jumps in while splitting non-jump instructions. As 8098the control flow graph and branch prediction information needs to be updated, 8099several restriction apply. 8100 8101Splitting of jump instruction into sequence that over by another jump 8102instruction is always valid, as compiler expect identical behavior of new 8103jump. When new sequence contains multiple jump instructions or new labels, 8104more assistance is needed. Splitter is required to create only unconditional 8105jumps, or simple conditional jump instructions. Additionally it must attach a 8106@code{REG_BR_PROB} note to each conditional jump. A global variable 8107@code{split_branch_probability} holds the probability of the original branch in case 8108it was a simple conditional jump, @minus{}1 otherwise. To simplify 8109recomputing of edge frequencies, the new sequence is required to have only 8110forward jumps to the newly created labels. 8111 8112@findex define_insn_and_split 8113For the common case where the pattern of a define_split exactly matches the 8114pattern of a define_insn, use @code{define_insn_and_split}. It looks like 8115this: 8116 8117@smallexample 8118(define_insn_and_split 8119 [@var{insn-pattern}] 8120 "@var{condition}" 8121 "@var{output-template}" 8122 "@var{split-condition}" 8123 [@var{new-insn-pattern-1} 8124 @var{new-insn-pattern-2} 8125 @dots{}] 8126 "@var{preparation-statements}" 8127 [@var{insn-attributes}]) 8128 8129@end smallexample 8130 8131@var{insn-pattern}, @var{condition}, @var{output-template}, and 8132@var{insn-attributes} are used as in @code{define_insn}. The 8133@var{new-insn-pattern} vector and the @var{preparation-statements} are used as 8134in a @code{define_split}. The @var{split-condition} is also used as in 8135@code{define_split}, with the additional behavior that if the condition starts 8136with @samp{&&}, the condition used for the split will be the constructed as a 8137logical ``and'' of the split condition with the insn condition. For example, 8138from i386.md: 8139 8140@smallexample 8141(define_insn_and_split "zero_extendhisi2_and" 8142 [(set (match_operand:SI 0 "register_operand" "=r") 8143 (zero_extend:SI (match_operand:HI 1 "register_operand" "0"))) 8144 (clobber (reg:CC 17))] 8145 "TARGET_ZERO_EXTEND_WITH_AND && !optimize_size" 8146 "#" 8147 "&& reload_completed" 8148 [(parallel [(set (match_dup 0) 8149 (and:SI (match_dup 0) (const_int 65535))) 8150 (clobber (reg:CC 17))])] 8151 "" 8152 [(set_attr "type" "alu1")]) 8153 8154@end smallexample 8155 8156In this case, the actual split condition will be 8157@samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}. 8158 8159The @code{define_insn_and_split} construction provides exactly the same 8160functionality as two separate @code{define_insn} and @code{define_split} 8161patterns. It exists for compactness, and as a maintenance tool to prevent 8162having to ensure the two patterns' templates match. 8163 8164@end ifset 8165@ifset INTERNALS 8166@node Including Patterns 8167@section Including Patterns in Machine Descriptions. 8168@cindex insn includes 8169 8170@findex include 8171The @code{include} pattern tells the compiler tools where to 8172look for patterns that are in files other than in the file 8173@file{.md}. This is used only at build time and there is no preprocessing allowed. 8174 8175It looks like: 8176 8177@smallexample 8178 8179(include 8180 @var{pathname}) 8181@end smallexample 8182 8183For example: 8184 8185@smallexample 8186 8187(include "filestuff") 8188 8189@end smallexample 8190 8191Where @var{pathname} is a string that specifies the location of the file, 8192specifies the include file to be in @file{gcc/config/target/filestuff}. The 8193directory @file{gcc/config/target} is regarded as the default directory. 8194 8195 8196Machine descriptions may be split up into smaller more manageable subsections 8197and placed into subdirectories. 8198 8199By specifying: 8200 8201@smallexample 8202 8203(include "BOGUS/filestuff") 8204 8205@end smallexample 8206 8207the include file is specified to be in @file{gcc/config/@var{target}/BOGUS/filestuff}. 8208 8209Specifying an absolute path for the include file such as; 8210@smallexample 8211 8212(include "/u2/BOGUS/filestuff") 8213 8214@end smallexample 8215is permitted but is not encouraged. 8216 8217@subsection RTL Generation Tool Options for Directory Search 8218@cindex directory options .md 8219@cindex options, directory search 8220@cindex search options 8221 8222The @option{-I@var{dir}} option specifies directories to search for machine descriptions. 8223For example: 8224 8225@smallexample 8226 8227genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md 8228 8229@end smallexample 8230 8231 8232Add the directory @var{dir} to the head of the list of directories to be 8233searched for header files. This can be used to override a system machine definition 8234file, substituting your own version, since these directories are 8235searched before the default machine description file directories. If you use more than 8236one @option{-I} option, the directories are scanned in left-to-right 8237order; the standard default directory come after. 8238 8239 8240@end ifset 8241@ifset INTERNALS 8242@node Peephole Definitions 8243@section Machine-Specific Peephole Optimizers 8244@cindex peephole optimizer definitions 8245@cindex defining peephole optimizers 8246 8247In addition to instruction patterns the @file{md} file may contain 8248definitions of machine-specific peephole optimizations. 8249 8250The combiner does not notice certain peephole optimizations when the data 8251flow in the program does not suggest that it should try them. For example, 8252sometimes two consecutive insns related in purpose can be combined even 8253though the second one does not appear to use a register computed in the 8254first one. A machine-specific peephole optimizer can detect such 8255opportunities. 8256 8257There are two forms of peephole definitions that may be used. The 8258original @code{define_peephole} is run at assembly output time to 8259match insns and substitute assembly text. Use of @code{define_peephole} 8260is deprecated. 8261 8262A newer @code{define_peephole2} matches insns and substitutes new 8263insns. The @code{peephole2} pass is run after register allocation 8264but before scheduling, which may result in much better code for 8265targets that do scheduling. 8266 8267@menu 8268* define_peephole:: RTL to Text Peephole Optimizers 8269* define_peephole2:: RTL to RTL Peephole Optimizers 8270@end menu 8271 8272@end ifset 8273@ifset INTERNALS 8274@node define_peephole 8275@subsection RTL to Text Peephole Optimizers 8276@findex define_peephole 8277 8278@need 1000 8279A definition looks like this: 8280 8281@smallexample 8282(define_peephole 8283 [@var{insn-pattern-1} 8284 @var{insn-pattern-2} 8285 @dots{}] 8286 "@var{condition}" 8287 "@var{template}" 8288 "@var{optional-insn-attributes}") 8289@end smallexample 8290 8291@noindent 8292The last string operand may be omitted if you are not using any 8293machine-specific information in this machine description. If present, 8294it must obey the same rules as in a @code{define_insn}. 8295 8296In this skeleton, @var{insn-pattern-1} and so on are patterns to match 8297consecutive insns. The optimization applies to a sequence of insns when 8298@var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches 8299the next, and so on. 8300 8301Each of the insns matched by a peephole must also match a 8302@code{define_insn}. Peepholes are checked only at the last stage just 8303before code generation, and only optionally. Therefore, any insn which 8304would match a peephole but no @code{define_insn} will cause a crash in code 8305generation in an unoptimized compilation, or at various optimization 8306stages. 8307 8308The operands of the insns are matched with @code{match_operands}, 8309@code{match_operator}, and @code{match_dup}, as usual. What is not 8310usual is that the operand numbers apply to all the insn patterns in the 8311definition. So, you can check for identical operands in two insns by 8312using @code{match_operand} in one insn and @code{match_dup} in the 8313other. 8314 8315The operand constraints used in @code{match_operand} patterns do not have 8316any direct effect on the applicability of the peephole, but they will 8317be validated afterward, so make sure your constraints are general enough 8318to apply whenever the peephole matches. If the peephole matches 8319but the constraints are not satisfied, the compiler will crash. 8320 8321It is safe to omit constraints in all the operands of the peephole; or 8322you can write constraints which serve as a double-check on the criteria 8323previously tested. 8324 8325Once a sequence of insns matches the patterns, the @var{condition} is 8326checked. This is a C expression which makes the final decision whether to 8327perform the optimization (we do so if the expression is nonzero). If 8328@var{condition} is omitted (in other words, the string is empty) then the 8329optimization is applied to every sequence of insns that matches the 8330patterns. 8331 8332The defined peephole optimizations are applied after register allocation 8333is complete. Therefore, the peephole definition can check which 8334operands have ended up in which kinds of registers, just by looking at 8335the operands. 8336 8337@findex prev_active_insn 8338The way to refer to the operands in @var{condition} is to write 8339@code{operands[@var{i}]} for operand number @var{i} (as matched by 8340@code{(match_operand @var{i} @dots{})}). Use the variable @code{insn} 8341to refer to the last of the insns being matched; use 8342@code{prev_active_insn} to find the preceding insns. 8343 8344@findex dead_or_set_p 8345When optimizing computations with intermediate results, you can use 8346@var{condition} to match only when the intermediate results are not used 8347elsewhere. Use the C expression @code{dead_or_set_p (@var{insn}, 8348@var{op})}, where @var{insn} is the insn in which you expect the value 8349to be used for the last time (from the value of @code{insn}, together 8350with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate 8351value (from @code{operands[@var{i}]}). 8352 8353Applying the optimization means replacing the sequence of insns with one 8354new insn. The @var{template} controls ultimate output of assembler code 8355for this combined insn. It works exactly like the template of a 8356@code{define_insn}. Operand numbers in this template are the same ones 8357used in matching the original sequence of insns. 8358 8359The result of a defined peephole optimizer does not need to match any of 8360the insn patterns in the machine description; it does not even have an 8361opportunity to match them. The peephole optimizer definition itself serves 8362as the insn pattern to control how the insn is output. 8363 8364Defined peephole optimizers are run as assembler code is being output, 8365so the insns they produce are never combined or rearranged in any way. 8366 8367Here is an example, taken from the 68000 machine description: 8368 8369@smallexample 8370(define_peephole 8371 [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4))) 8372 (set (match_operand:DF 0 "register_operand" "=f") 8373 (match_operand:DF 1 "register_operand" "ad"))] 8374 "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])" 8375@{ 8376 rtx xoperands[2]; 8377 xoperands[1] = gen_rtx_REG (SImode, REGNO (operands[1]) + 1); 8378#ifdef MOTOROLA 8379 output_asm_insn ("move.l %1,(sp)", xoperands); 8380 output_asm_insn ("move.l %1,-(sp)", operands); 8381 return "fmove.d (sp)+,%0"; 8382#else 8383 output_asm_insn ("movel %1,sp@@", xoperands); 8384 output_asm_insn ("movel %1,sp@@-", operands); 8385 return "fmoved sp@@+,%0"; 8386#endif 8387@}) 8388@end smallexample 8389 8390@need 1000 8391The effect of this optimization is to change 8392 8393@smallexample 8394@group 8395jbsr _foobar 8396addql #4,sp 8397movel d1,sp@@- 8398movel d0,sp@@- 8399fmoved sp@@+,fp0 8400@end group 8401@end smallexample 8402 8403@noindent 8404into 8405 8406@smallexample 8407@group 8408jbsr _foobar 8409movel d1,sp@@ 8410movel d0,sp@@- 8411fmoved sp@@+,fp0 8412@end group 8413@end smallexample 8414 8415@ignore 8416@findex CC_REVERSED 8417If a peephole matches a sequence including one or more jump insns, you must 8418take account of the flags such as @code{CC_REVERSED} which specify that the 8419condition codes are represented in an unusual manner. The compiler 8420automatically alters any ordinary conditional jumps which occur in such 8421situations, but the compiler cannot alter jumps which have been replaced by 8422peephole optimizations. So it is up to you to alter the assembler code 8423that the peephole produces. Supply C code to write the assembler output, 8424and in this C code check the condition code status flags and change the 8425assembler code as appropriate. 8426@end ignore 8427 8428@var{insn-pattern-1} and so on look @emph{almost} like the second 8429operand of @code{define_insn}. There is one important difference: the 8430second operand of @code{define_insn} consists of one or more RTX's 8431enclosed in square brackets. Usually, there is only one: then the same 8432action can be written as an element of a @code{define_peephole}. But 8433when there are multiple actions in a @code{define_insn}, they are 8434implicitly enclosed in a @code{parallel}. Then you must explicitly 8435write the @code{parallel}, and the square brackets within it, in the 8436@code{define_peephole}. Thus, if an insn pattern looks like this, 8437 8438@smallexample 8439(define_insn "divmodsi4" 8440 [(set (match_operand:SI 0 "general_operand" "=d") 8441 (div:SI (match_operand:SI 1 "general_operand" "0") 8442 (match_operand:SI 2 "general_operand" "dmsK"))) 8443 (set (match_operand:SI 3 "general_operand" "=d") 8444 (mod:SI (match_dup 1) (match_dup 2)))] 8445 "TARGET_68020" 8446 "divsl%.l %2,%3:%0") 8447@end smallexample 8448 8449@noindent 8450then the way to mention this insn in a peephole is as follows: 8451 8452@smallexample 8453(define_peephole 8454 [@dots{} 8455 (parallel 8456 [(set (match_operand:SI 0 "general_operand" "=d") 8457 (div:SI (match_operand:SI 1 "general_operand" "0") 8458 (match_operand:SI 2 "general_operand" "dmsK"))) 8459 (set (match_operand:SI 3 "general_operand" "=d") 8460 (mod:SI (match_dup 1) (match_dup 2)))]) 8461 @dots{}] 8462 @dots{}) 8463@end smallexample 8464 8465@end ifset 8466@ifset INTERNALS 8467@node define_peephole2 8468@subsection RTL to RTL Peephole Optimizers 8469@findex define_peephole2 8470 8471The @code{define_peephole2} definition tells the compiler how to 8472substitute one sequence of instructions for another sequence, 8473what additional scratch registers may be needed and what their 8474lifetimes must be. 8475 8476@smallexample 8477(define_peephole2 8478 [@var{insn-pattern-1} 8479 @var{insn-pattern-2} 8480 @dots{}] 8481 "@var{condition}" 8482 [@var{new-insn-pattern-1} 8483 @var{new-insn-pattern-2} 8484 @dots{}] 8485 "@var{preparation-statements}") 8486@end smallexample 8487 8488The definition is almost identical to @code{define_split} 8489(@pxref{Insn Splitting}) except that the pattern to match is not a 8490single instruction, but a sequence of instructions. 8491 8492It is possible to request additional scratch registers for use in the 8493output template. If appropriate registers are not free, the pattern 8494will simply not match. 8495 8496@findex match_scratch 8497@findex match_dup 8498Scratch registers are requested with a @code{match_scratch} pattern at 8499the top level of the input pattern. The allocated register (initially) will 8500be dead at the point requested within the original sequence. If the scratch 8501is used at more than a single point, a @code{match_dup} pattern at the 8502top level of the input pattern marks the last position in the input sequence 8503at which the register must be available. 8504 8505Here is an example from the IA-32 machine description: 8506 8507@smallexample 8508(define_peephole2 8509 [(match_scratch:SI 2 "r") 8510 (parallel [(set (match_operand:SI 0 "register_operand" "") 8511 (match_operator:SI 3 "arith_or_logical_operator" 8512 [(match_dup 0) 8513 (match_operand:SI 1 "memory_operand" "")])) 8514 (clobber (reg:CC 17))])] 8515 "! optimize_size && ! TARGET_READ_MODIFY" 8516 [(set (match_dup 2) (match_dup 1)) 8517 (parallel [(set (match_dup 0) 8518 (match_op_dup 3 [(match_dup 0) (match_dup 2)])) 8519 (clobber (reg:CC 17))])] 8520 "") 8521@end smallexample 8522 8523@noindent 8524This pattern tries to split a load from its use in the hopes that we'll be 8525able to schedule around the memory load latency. It allocates a single 8526@code{SImode} register of class @code{GENERAL_REGS} (@code{"r"}) that needs 8527to be live only at the point just before the arithmetic. 8528 8529A real example requiring extended scratch lifetimes is harder to come by, 8530so here's a silly made-up example: 8531 8532@smallexample 8533(define_peephole2 8534 [(match_scratch:SI 4 "r") 8535 (set (match_operand:SI 0 "" "") (match_operand:SI 1 "" "")) 8536 (set (match_operand:SI 2 "" "") (match_dup 1)) 8537 (match_dup 4) 8538 (set (match_operand:SI 3 "" "") (match_dup 1))] 8539 "/* @r{determine 1 does not overlap 0 and 2} */" 8540 [(set (match_dup 4) (match_dup 1)) 8541 (set (match_dup 0) (match_dup 4)) 8542 (set (match_dup 2) (match_dup 4)) 8543 (set (match_dup 3) (match_dup 4))] 8544 "") 8545@end smallexample 8546 8547@noindent 8548If we had not added the @code{(match_dup 4)} in the middle of the input 8549sequence, it might have been the case that the register we chose at the 8550beginning of the sequence is killed by the first or second @code{set}. 8551 8552@end ifset 8553@ifset INTERNALS 8554@node Insn Attributes 8555@section Instruction Attributes 8556@cindex insn attributes 8557@cindex instruction attributes 8558 8559In addition to describing the instruction supported by the target machine, 8560the @file{md} file also defines a group of @dfn{attributes} and a set of 8561values for each. Every generated insn is assigned a value for each attribute. 8562One possible attribute would be the effect that the insn has on the machine's 8563condition code. This attribute can then be used by @code{NOTICE_UPDATE_CC} 8564to track the condition codes. 8565 8566@menu 8567* Defining Attributes:: Specifying attributes and their values. 8568* Expressions:: Valid expressions for attribute values. 8569* Tagging Insns:: Assigning attribute values to insns. 8570* Attr Example:: An example of assigning attributes. 8571* Insn Lengths:: Computing the length of insns. 8572* Constant Attributes:: Defining attributes that are constant. 8573* Mnemonic Attribute:: Obtain the instruction mnemonic as attribute value. 8574* Delay Slots:: Defining delay slots required for a machine. 8575* Processor pipeline description:: Specifying information for insn scheduling. 8576@end menu 8577 8578@end ifset 8579@ifset INTERNALS 8580@node Defining Attributes 8581@subsection Defining Attributes and their Values 8582@cindex defining attributes and their values 8583@cindex attributes, defining 8584 8585@findex define_attr 8586The @code{define_attr} expression is used to define each attribute required 8587by the target machine. It looks like: 8588 8589@smallexample 8590(define_attr @var{name} @var{list-of-values} @var{default}) 8591@end smallexample 8592 8593@var{name} is a string specifying the name of the attribute being 8594defined. Some attributes are used in a special way by the rest of the 8595compiler. The @code{enabled} attribute can be used to conditionally 8596enable or disable insn alternatives (@pxref{Disable Insn 8597Alternatives}). The @code{predicable} attribute, together with a 8598suitable @code{define_cond_exec} (@pxref{Conditional Execution}), can 8599be used to automatically generate conditional variants of instruction 8600patterns. The @code{mnemonic} attribute can be used to check for the 8601instruction mnemonic (@pxref{Mnemonic Attribute}). The compiler 8602internally uses the names @code{ce_enabled} and @code{nonce_enabled}, 8603so they should not be used elsewhere as alternative names. 8604 8605@var{list-of-values} is either a string that specifies a comma-separated 8606list of values that can be assigned to the attribute, or a null string to 8607indicate that the attribute takes numeric values. 8608 8609@var{default} is an attribute expression that gives the value of this 8610attribute for insns that match patterns whose definition does not include 8611an explicit value for this attribute. @xref{Attr Example}, for more 8612information on the handling of defaults. @xref{Constant Attributes}, 8613for information on attributes that do not depend on any particular insn. 8614 8615@findex insn-attr.h 8616For each defined attribute, a number of definitions are written to the 8617@file{insn-attr.h} file. For cases where an explicit set of values is 8618specified for an attribute, the following are defined: 8619 8620@itemize @bullet 8621@item 8622A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}. 8623 8624@item 8625An enumerated class is defined for @samp{attr_@var{name}} with 8626elements of the form @samp{@var{upper-name}_@var{upper-value}} where 8627the attribute name and value are first converted to uppercase. 8628 8629@item 8630A function @samp{get_attr_@var{name}} is defined that is passed an insn and 8631returns the attribute value for that insn. 8632@end itemize 8633 8634For example, if the following is present in the @file{md} file: 8635 8636@smallexample 8637(define_attr "type" "branch,fp,load,store,arith" @dots{}) 8638@end smallexample 8639 8640@noindent 8641the following lines will be written to the file @file{insn-attr.h}. 8642 8643@smallexample 8644#define HAVE_ATTR_type 1 8645enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD, 8646 TYPE_STORE, TYPE_ARITH@}; 8647extern enum attr_type get_attr_type (); 8648@end smallexample 8649 8650If the attribute takes numeric values, no @code{enum} type will be 8651defined and the function to obtain the attribute's value will return 8652@code{int}. 8653 8654There are attributes which are tied to a specific meaning. These 8655attributes are not free to use for other purposes: 8656 8657@table @code 8658@item length 8659The @code{length} attribute is used to calculate the length of emitted 8660code chunks. This is especially important when verifying branch 8661distances. @xref{Insn Lengths}. 8662 8663@item enabled 8664The @code{enabled} attribute can be defined to prevent certain 8665alternatives of an insn definition from being used during code 8666generation. @xref{Disable Insn Alternatives}. 8667 8668@item mnemonic 8669The @code{mnemonic} attribute can be defined to implement instruction 8670specific checks in e.g. the pipeline description. 8671@xref{Mnemonic Attribute}. 8672@end table 8673 8674For each of these special attributes, the corresponding 8675@samp{HAVE_ATTR_@var{name}} @samp{#define} is also written when the 8676attribute is not defined; in that case, it is defined as @samp{0}. 8677 8678@findex define_enum_attr 8679@anchor{define_enum_attr} 8680Another way of defining an attribute is to use: 8681 8682@smallexample 8683(define_enum_attr "@var{attr}" "@var{enum}" @var{default}) 8684@end smallexample 8685 8686This works in just the same way as @code{define_attr}, except that 8687the list of values is taken from a separate enumeration called 8688@var{enum} (@pxref{define_enum}). This form allows you to use 8689the same list of values for several attributes without having to 8690repeat the list each time. For example: 8691 8692@smallexample 8693(define_enum "processor" [ 8694 model_a 8695 model_b 8696 @dots{} 8697]) 8698(define_enum_attr "arch" "processor" 8699 (const (symbol_ref "target_arch"))) 8700(define_enum_attr "tune" "processor" 8701 (const (symbol_ref "target_tune"))) 8702@end smallexample 8703 8704defines the same attributes as: 8705 8706@smallexample 8707(define_attr "arch" "model_a,model_b,@dots{}" 8708 (const (symbol_ref "target_arch"))) 8709(define_attr "tune" "model_a,model_b,@dots{}" 8710 (const (symbol_ref "target_tune"))) 8711@end smallexample 8712 8713but without duplicating the processor list. The second example defines two 8714separate C enums (@code{attr_arch} and @code{attr_tune}) whereas the first 8715defines a single C enum (@code{processor}). 8716@end ifset 8717@ifset INTERNALS 8718@node Expressions 8719@subsection Attribute Expressions 8720@cindex attribute expressions 8721 8722RTL expressions used to define attributes use the codes described above 8723plus a few specific to attribute definitions, to be discussed below. 8724Attribute value expressions must have one of the following forms: 8725 8726@table @code 8727@cindex @code{const_int} and attributes 8728@item (const_int @var{i}) 8729The integer @var{i} specifies the value of a numeric attribute. @var{i} 8730must be non-negative. 8731 8732The value of a numeric attribute can be specified either with a 8733@code{const_int}, or as an integer represented as a string in 8734@code{const_string}, @code{eq_attr} (see below), @code{attr}, 8735@code{symbol_ref}, simple arithmetic expressions, and @code{set_attr} 8736overrides on specific instructions (@pxref{Tagging Insns}). 8737 8738@cindex @code{const_string} and attributes 8739@item (const_string @var{value}) 8740The string @var{value} specifies a constant attribute value. 8741If @var{value} is specified as @samp{"*"}, it means that the default value of 8742the attribute is to be used for the insn containing this expression. 8743@samp{"*"} obviously cannot be used in the @var{default} expression 8744of a @code{define_attr}. 8745 8746If the attribute whose value is being specified is numeric, @var{value} 8747must be a string containing a non-negative integer (normally 8748@code{const_int} would be used in this case). Otherwise, it must 8749contain one of the valid values for the attribute. 8750 8751@cindex @code{if_then_else} and attributes 8752@item (if_then_else @var{test} @var{true-value} @var{false-value}) 8753@var{test} specifies an attribute test, whose format is defined below. 8754The value of this expression is @var{true-value} if @var{test} is true, 8755otherwise it is @var{false-value}. 8756 8757@cindex @code{cond} and attributes 8758@item (cond [@var{test1} @var{value1} @dots{}] @var{default}) 8759The first operand of this expression is a vector containing an even 8760number of expressions and consisting of pairs of @var{test} and @var{value} 8761expressions. The value of the @code{cond} expression is that of the 8762@var{value} corresponding to the first true @var{test} expression. If 8763none of the @var{test} expressions are true, the value of the @code{cond} 8764expression is that of the @var{default} expression. 8765@end table 8766 8767@var{test} expressions can have one of the following forms: 8768 8769@table @code 8770@cindex @code{const_int} and attribute tests 8771@item (const_int @var{i}) 8772This test is true if @var{i} is nonzero and false otherwise. 8773 8774@cindex @code{not} and attributes 8775@cindex @code{ior} and attributes 8776@cindex @code{and} and attributes 8777@item (not @var{test}) 8778@itemx (ior @var{test1} @var{test2}) 8779@itemx (and @var{test1} @var{test2}) 8780These tests are true if the indicated logical function is true. 8781 8782@cindex @code{match_operand} and attributes 8783@item (match_operand:@var{m} @var{n} @var{pred} @var{constraints}) 8784This test is true if operand @var{n} of the insn whose attribute value 8785is being determined has mode @var{m} (this part of the test is ignored 8786if @var{m} is @code{VOIDmode}) and the function specified by the string 8787@var{pred} returns a nonzero value when passed operand @var{n} and mode 8788@var{m} (this part of the test is ignored if @var{pred} is the null 8789string). 8790 8791The @var{constraints} operand is ignored and should be the null string. 8792 8793@cindex @code{match_test} and attributes 8794@item (match_test @var{c-expr}) 8795The test is true if C expression @var{c-expr} is true. In non-constant 8796attributes, @var{c-expr} has access to the following variables: 8797 8798@table @var 8799@item insn 8800The rtl instruction under test. 8801@item which_alternative 8802The @code{define_insn} alternative that @var{insn} matches. 8803@xref{Output Statement}. 8804@item operands 8805An array of @var{insn}'s rtl operands. 8806@end table 8807 8808@var{c-expr} behaves like the condition in a C @code{if} statement, 8809so there is no need to explicitly convert the expression into a boolean 88100 or 1 value. For example, the following two tests are equivalent: 8811 8812@smallexample 8813(match_test "x & 2") 8814(match_test "(x & 2) != 0") 8815@end smallexample 8816 8817@cindex @code{le} and attributes 8818@cindex @code{leu} and attributes 8819@cindex @code{lt} and attributes 8820@cindex @code{gt} and attributes 8821@cindex @code{gtu} and attributes 8822@cindex @code{ge} and attributes 8823@cindex @code{geu} and attributes 8824@cindex @code{ne} and attributes 8825@cindex @code{eq} and attributes 8826@cindex @code{plus} and attributes 8827@cindex @code{minus} and attributes 8828@cindex @code{mult} and attributes 8829@cindex @code{div} and attributes 8830@cindex @code{mod} and attributes 8831@cindex @code{abs} and attributes 8832@cindex @code{neg} and attributes 8833@cindex @code{ashift} and attributes 8834@cindex @code{lshiftrt} and attributes 8835@cindex @code{ashiftrt} and attributes 8836@item (le @var{arith1} @var{arith2}) 8837@itemx (leu @var{arith1} @var{arith2}) 8838@itemx (lt @var{arith1} @var{arith2}) 8839@itemx (ltu @var{arith1} @var{arith2}) 8840@itemx (gt @var{arith1} @var{arith2}) 8841@itemx (gtu @var{arith1} @var{arith2}) 8842@itemx (ge @var{arith1} @var{arith2}) 8843@itemx (geu @var{arith1} @var{arith2}) 8844@itemx (ne @var{arith1} @var{arith2}) 8845@itemx (eq @var{arith1} @var{arith2}) 8846These tests are true if the indicated comparison of the two arithmetic 8847expressions is true. Arithmetic expressions are formed with 8848@code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod}, 8849@code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not}, 8850@code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions. 8851 8852@findex get_attr 8853@code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn 8854Lengths},for additional forms). @code{symbol_ref} is a string 8855denoting a C expression that yields an @code{int} when evaluated by the 8856@samp{get_attr_@dots{}} routine. It should normally be a global 8857variable. 8858 8859@findex eq_attr 8860@item (eq_attr @var{name} @var{value}) 8861@var{name} is a string specifying the name of an attribute. 8862 8863@var{value} is a string that is either a valid value for attribute 8864@var{name}, a comma-separated list of values, or @samp{!} followed by a 8865value or list. If @var{value} does not begin with a @samp{!}, this 8866test is true if the value of the @var{name} attribute of the current 8867insn is in the list specified by @var{value}. If @var{value} begins 8868with a @samp{!}, this test is true if the attribute's value is 8869@emph{not} in the specified list. 8870 8871For example, 8872 8873@smallexample 8874(eq_attr "type" "load,store") 8875@end smallexample 8876 8877@noindent 8878is equivalent to 8879 8880@smallexample 8881(ior (eq_attr "type" "load") (eq_attr "type" "store")) 8882@end smallexample 8883 8884If @var{name} specifies an attribute of @samp{alternative}, it refers to the 8885value of the compiler variable @code{which_alternative} 8886(@pxref{Output Statement}) and the values must be small integers. For 8887example, 8888 8889@smallexample 8890(eq_attr "alternative" "2,3") 8891@end smallexample 8892 8893@noindent 8894is equivalent to 8895 8896@smallexample 8897(ior (eq (symbol_ref "which_alternative") (const_int 2)) 8898 (eq (symbol_ref "which_alternative") (const_int 3))) 8899@end smallexample 8900 8901Note that, for most attributes, an @code{eq_attr} test is simplified in cases 8902where the value of the attribute being tested is known for all insns matching 8903a particular pattern. This is by far the most common case. 8904 8905@findex attr_flag 8906@item (attr_flag @var{name}) 8907The value of an @code{attr_flag} expression is true if the flag 8908specified by @var{name} is true for the @code{insn} currently being 8909scheduled. 8910 8911@var{name} is a string specifying one of a fixed set of flags to test. 8912Test the flags @code{forward} and @code{backward} to determine the 8913direction of a conditional branch. 8914 8915This example describes a conditional branch delay slot which 8916can be nullified for forward branches that are taken (annul-true) or 8917for backward branches which are not taken (annul-false). 8918 8919@smallexample 8920(define_delay (eq_attr "type" "cbranch") 8921 [(eq_attr "in_branch_delay" "true") 8922 (and (eq_attr "in_branch_delay" "true") 8923 (attr_flag "forward")) 8924 (and (eq_attr "in_branch_delay" "true") 8925 (attr_flag "backward"))]) 8926@end smallexample 8927 8928The @code{forward} and @code{backward} flags are false if the current 8929@code{insn} being scheduled is not a conditional branch. 8930 8931@code{attr_flag} is only used during delay slot scheduling and has no 8932meaning to other passes of the compiler. 8933 8934@findex attr 8935@item (attr @var{name}) 8936The value of another attribute is returned. This is most useful 8937for numeric attributes, as @code{eq_attr} and @code{attr_flag} 8938produce more efficient code for non-numeric attributes. 8939@end table 8940 8941@end ifset 8942@ifset INTERNALS 8943@node Tagging Insns 8944@subsection Assigning Attribute Values to Insns 8945@cindex tagging insns 8946@cindex assigning attribute values to insns 8947 8948The value assigned to an attribute of an insn is primarily determined by 8949which pattern is matched by that insn (or which @code{define_peephole} 8950generated it). Every @code{define_insn} and @code{define_peephole} can 8951have an optional last argument to specify the values of attributes for 8952matching insns. The value of any attribute not specified in a particular 8953insn is set to the default value for that attribute, as specified in its 8954@code{define_attr}. Extensive use of default values for attributes 8955permits the specification of the values for only one or two attributes 8956in the definition of most insn patterns, as seen in the example in the 8957next section. 8958 8959The optional last argument of @code{define_insn} and 8960@code{define_peephole} is a vector of expressions, each of which defines 8961the value for a single attribute. The most general way of assigning an 8962attribute's value is to use a @code{set} expression whose first operand is an 8963@code{attr} expression giving the name of the attribute being set. The 8964second operand of the @code{set} is an attribute expression 8965(@pxref{Expressions}) giving the value of the attribute. 8966 8967When the attribute value depends on the @samp{alternative} attribute 8968(i.e., which is the applicable alternative in the constraint of the 8969insn), the @code{set_attr_alternative} expression can be used. It 8970allows the specification of a vector of attribute expressions, one for 8971each alternative. 8972 8973@findex set_attr 8974When the generality of arbitrary attribute expressions is not required, 8975the simpler @code{set_attr} expression can be used, which allows 8976specifying a string giving either a single attribute value or a list 8977of attribute values, one for each alternative. 8978 8979The form of each of the above specifications is shown below. In each case, 8980@var{name} is a string specifying the attribute to be set. 8981 8982@table @code 8983@item (set_attr @var{name} @var{value-string}) 8984@var{value-string} is either a string giving the desired attribute value, 8985or a string containing a comma-separated list giving the values for 8986succeeding alternatives. The number of elements must match the number 8987of alternatives in the constraint of the insn pattern. 8988 8989Note that it may be useful to specify @samp{*} for some alternative, in 8990which case the attribute will assume its default value for insns matching 8991that alternative. 8992 8993@findex set_attr_alternative 8994@item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}]) 8995Depending on the alternative of the insn, the value will be one of the 8996specified values. This is a shorthand for using a @code{cond} with 8997tests on the @samp{alternative} attribute. 8998 8999@findex attr 9000@item (set (attr @var{name}) @var{value}) 9001The first operand of this @code{set} must be the special RTL expression 9002@code{attr}, whose sole operand is a string giving the name of the 9003attribute being set. @var{value} is the value of the attribute. 9004@end table 9005 9006The following shows three different ways of representing the same 9007attribute value specification: 9008 9009@smallexample 9010(set_attr "type" "load,store,arith") 9011 9012(set_attr_alternative "type" 9013 [(const_string "load") (const_string "store") 9014 (const_string "arith")]) 9015 9016(set (attr "type") 9017 (cond [(eq_attr "alternative" "1") (const_string "load") 9018 (eq_attr "alternative" "2") (const_string "store")] 9019 (const_string "arith"))) 9020@end smallexample 9021 9022@need 1000 9023@findex define_asm_attributes 9024The @code{define_asm_attributes} expression provides a mechanism to 9025specify the attributes assigned to insns produced from an @code{asm} 9026statement. It has the form: 9027 9028@smallexample 9029(define_asm_attributes [@var{attr-sets}]) 9030@end smallexample 9031 9032@noindent 9033where @var{attr-sets} is specified the same as for both the 9034@code{define_insn} and the @code{define_peephole} expressions. 9035 9036These values will typically be the ``worst case'' attribute values. For 9037example, they might indicate that the condition code will be clobbered. 9038 9039A specification for a @code{length} attribute is handled specially. The 9040way to compute the length of an @code{asm} insn is to multiply the 9041length specified in the expression @code{define_asm_attributes} by the 9042number of machine instructions specified in the @code{asm} statement, 9043determined by counting the number of semicolons and newlines in the 9044string. Therefore, the value of the @code{length} attribute specified 9045in a @code{define_asm_attributes} should be the maximum possible length 9046of a single machine instruction. 9047 9048@end ifset 9049@ifset INTERNALS 9050@node Attr Example 9051@subsection Example of Attribute Specifications 9052@cindex attribute specifications example 9053@cindex attribute specifications 9054 9055The judicious use of defaulting is important in the efficient use of 9056insn attributes. Typically, insns are divided into @dfn{types} and an 9057attribute, customarily called @code{type}, is used to represent this 9058value. This attribute is normally used only to define the default value 9059for other attributes. An example will clarify this usage. 9060 9061Assume we have a RISC machine with a condition code and in which only 9062full-word operations are performed in registers. Let us assume that we 9063can divide all insns into loads, stores, (integer) arithmetic 9064operations, floating point operations, and branches. 9065 9066Here we will concern ourselves with determining the effect of an insn on 9067the condition code and will limit ourselves to the following possible 9068effects: The condition code can be set unpredictably (clobbered), not 9069be changed, be set to agree with the results of the operation, or only 9070changed if the item previously set into the condition code has been 9071modified. 9072 9073Here is part of a sample @file{md} file for such a machine: 9074 9075@smallexample 9076(define_attr "type" "load,store,arith,fp,branch" (const_string "arith")) 9077 9078(define_attr "cc" "clobber,unchanged,set,change0" 9079 (cond [(eq_attr "type" "load") 9080 (const_string "change0") 9081 (eq_attr "type" "store,branch") 9082 (const_string "unchanged") 9083 (eq_attr "type" "arith") 9084 (if_then_else (match_operand:SI 0 "" "") 9085 (const_string "set") 9086 (const_string "clobber"))] 9087 (const_string "clobber"))) 9088 9089(define_insn "" 9090 [(set (match_operand:SI 0 "general_operand" "=r,r,m") 9091 (match_operand:SI 1 "general_operand" "r,m,r"))] 9092 "" 9093 "@@ 9094 move %0,%1 9095 load %0,%1 9096 store %0,%1" 9097 [(set_attr "type" "arith,load,store")]) 9098@end smallexample 9099 9100Note that we assume in the above example that arithmetic operations 9101performed on quantities smaller than a machine word clobber the condition 9102code since they will set the condition code to a value corresponding to the 9103full-word result. 9104 9105@end ifset 9106@ifset INTERNALS 9107@node Insn Lengths 9108@subsection Computing the Length of an Insn 9109@cindex insn lengths, computing 9110@cindex computing the length of an insn 9111 9112For many machines, multiple types of branch instructions are provided, each 9113for different length branch displacements. In most cases, the assembler 9114will choose the correct instruction to use. However, when the assembler 9115cannot do so, GCC can when a special attribute, the @code{length} 9116attribute, is defined. This attribute must be defined to have numeric 9117values by specifying a null string in its @code{define_attr}. 9118 9119In the case of the @code{length} attribute, two additional forms of 9120arithmetic terms are allowed in test expressions: 9121 9122@table @code 9123@cindex @code{match_dup} and attributes 9124@item (match_dup @var{n}) 9125This refers to the address of operand @var{n} of the current insn, which 9126must be a @code{label_ref}. 9127 9128@cindex @code{pc} and attributes 9129@item (pc) 9130For non-branch instructions and backward branch instructions, this refers 9131to the address of the current insn. But for forward branch instructions, 9132this refers to the address of the next insn, because the length of the 9133current insn is to be computed. 9134@end table 9135 9136@cindex @code{addr_vec}, length of 9137@cindex @code{addr_diff_vec}, length of 9138For normal insns, the length will be determined by value of the 9139@code{length} attribute. In the case of @code{addr_vec} and 9140@code{addr_diff_vec} insn patterns, the length is computed as 9141the number of vectors multiplied by the size of each vector. 9142 9143Lengths are measured in addressable storage units (bytes). 9144 9145Note that it is possible to call functions via the @code{symbol_ref} 9146mechanism to compute the length of an insn. However, if you use this 9147mechanism you must provide dummy clauses to express the maximum length 9148without using the function call. You can an example of this in the 9149@code{pa} machine description for the @code{call_symref} pattern. 9150 9151The following macros can be used to refine the length computation: 9152 9153@table @code 9154@findex ADJUST_INSN_LENGTH 9155@item ADJUST_INSN_LENGTH (@var{insn}, @var{length}) 9156If defined, modifies the length assigned to instruction @var{insn} as a 9157function of the context in which it is used. @var{length} is an lvalue 9158that contains the initially computed length of the insn and should be 9159updated with the correct length of the insn. 9160 9161This macro will normally not be required. A case in which it is 9162required is the ROMP@. On this machine, the size of an @code{addr_vec} 9163insn must be increased by two to compensate for the fact that alignment 9164may be required. 9165@end table 9166 9167@findex get_attr_length 9168The routine that returns @code{get_attr_length} (the value of the 9169@code{length} attribute) can be used by the output routine to 9170determine the form of the branch instruction to be written, as the 9171example below illustrates. 9172 9173As an example of the specification of variable-length branches, consider 9174the IBM 360. If we adopt the convention that a register will be set to 9175the starting address of a function, we can jump to labels within 4k of 9176the start using a four-byte instruction. Otherwise, we need a six-byte 9177sequence to load the address from memory and then branch to it. 9178 9179On such a machine, a pattern for a branch instruction might be specified 9180as follows: 9181 9182@smallexample 9183(define_insn "jump" 9184 [(set (pc) 9185 (label_ref (match_operand 0 "" "")))] 9186 "" 9187@{ 9188 return (get_attr_length (insn) == 4 9189 ? "b %l0" : "l r15,=a(%l0); br r15"); 9190@} 9191 [(set (attr "length") 9192 (if_then_else (lt (match_dup 0) (const_int 4096)) 9193 (const_int 4) 9194 (const_int 6)))]) 9195@end smallexample 9196 9197@end ifset 9198@ifset INTERNALS 9199@node Constant Attributes 9200@subsection Constant Attributes 9201@cindex constant attributes 9202 9203A special form of @code{define_attr}, where the expression for the 9204default value is a @code{const} expression, indicates an attribute that 9205is constant for a given run of the compiler. Constant attributes may be 9206used to specify which variety of processor is used. For example, 9207 9208@smallexample 9209(define_attr "cpu" "m88100,m88110,m88000" 9210 (const 9211 (cond [(symbol_ref "TARGET_88100") (const_string "m88100") 9212 (symbol_ref "TARGET_88110") (const_string "m88110")] 9213 (const_string "m88000")))) 9214 9215(define_attr "memory" "fast,slow" 9216 (const 9217 (if_then_else (symbol_ref "TARGET_FAST_MEM") 9218 (const_string "fast") 9219 (const_string "slow")))) 9220@end smallexample 9221 9222The routine generated for constant attributes has no parameters as it 9223does not depend on any particular insn. RTL expressions used to define 9224the value of a constant attribute may use the @code{symbol_ref} form, 9225but may not use either the @code{match_operand} form or @code{eq_attr} 9226forms involving insn attributes. 9227 9228@end ifset 9229@ifset INTERNALS 9230@node Mnemonic Attribute 9231@subsection Mnemonic Attribute 9232@cindex mnemonic attribute 9233 9234The @code{mnemonic} attribute is a string type attribute holding the 9235instruction mnemonic for an insn alternative. The attribute values 9236will automatically be generated by the machine description parser if 9237there is an attribute definition in the md file: 9238 9239@smallexample 9240(define_attr "mnemonic" "unknown" (const_string "unknown")) 9241@end smallexample 9242 9243The default value can be freely chosen as long as it does not collide 9244with any of the instruction mnemonics. This value will be used 9245whenever the machine description parser is not able to determine the 9246mnemonic string. This might be the case for output templates 9247containing more than a single instruction as in 9248@code{"mvcle\t%0,%1,0\;jo\t.-4"}. 9249 9250The @code{mnemonic} attribute set is not generated automatically if the 9251instruction string is generated via C code. 9252 9253An existing @code{mnemonic} attribute set in an insn definition will not 9254be overriden by the md file parser. That way it is possible to 9255manually set the instruction mnemonics for the cases where the md file 9256parser fails to determine it automatically. 9257 9258The @code{mnemonic} attribute is useful for dealing with instruction 9259specific properties in the pipeline description without defining 9260additional insn attributes. 9261 9262@smallexample 9263(define_attr "ooo_expanded" "" 9264 (cond [(eq_attr "mnemonic" "dlr,dsgr,d,dsgf,stam,dsgfr,dlgr") 9265 (const_int 1)] 9266 (const_int 0))) 9267@end smallexample 9268 9269@end ifset 9270@ifset INTERNALS 9271@node Delay Slots 9272@subsection Delay Slot Scheduling 9273@cindex delay slots, defining 9274 9275The insn attribute mechanism can be used to specify the requirements for 9276delay slots, if any, on a target machine. An instruction is said to 9277require a @dfn{delay slot} if some instructions that are physically 9278after the instruction are executed as if they were located before it. 9279Classic examples are branch and call instructions, which often execute 9280the following instruction before the branch or call is performed. 9281 9282On some machines, conditional branch instructions can optionally 9283@dfn{annul} instructions in the delay slot. This means that the 9284instruction will not be executed for certain branch outcomes. Both 9285instructions that annul if the branch is true and instructions that 9286annul if the branch is false are supported. 9287 9288Delay slot scheduling differs from instruction scheduling in that 9289determining whether an instruction needs a delay slot is dependent only 9290on the type of instruction being generated, not on data flow between the 9291instructions. See the next section for a discussion of data-dependent 9292instruction scheduling. 9293 9294@findex define_delay 9295The requirement of an insn needing one or more delay slots is indicated 9296via the @code{define_delay} expression. It has the following form: 9297 9298@smallexample 9299(define_delay @var{test} 9300 [@var{delay-1} @var{annul-true-1} @var{annul-false-1} 9301 @var{delay-2} @var{annul-true-2} @var{annul-false-2} 9302 @dots{}]) 9303@end smallexample 9304 9305@var{test} is an attribute test that indicates whether this 9306@code{define_delay} applies to a particular insn. If so, the number of 9307required delay slots is determined by the length of the vector specified 9308as the second argument. An insn placed in delay slot @var{n} must 9309satisfy attribute test @var{delay-n}. @var{annul-true-n} is an 9310attribute test that specifies which insns may be annulled if the branch 9311is true. Similarly, @var{annul-false-n} specifies which insns in the 9312delay slot may be annulled if the branch is false. If annulling is not 9313supported for that delay slot, @code{(nil)} should be coded. 9314 9315For example, in the common case where branch and call insns require 9316a single delay slot, which may contain any insn other than a branch or 9317call, the following would be placed in the @file{md} file: 9318 9319@smallexample 9320(define_delay (eq_attr "type" "branch,call") 9321 [(eq_attr "type" "!branch,call") (nil) (nil)]) 9322@end smallexample 9323 9324Multiple @code{define_delay} expressions may be specified. In this 9325case, each such expression specifies different delay slot requirements 9326and there must be no insn for which tests in two @code{define_delay} 9327expressions are both true. 9328 9329For example, if we have a machine that requires one delay slot for branches 9330but two for calls, no delay slot can contain a branch or call insn, 9331and any valid insn in the delay slot for the branch can be annulled if the 9332branch is true, we might represent this as follows: 9333 9334@smallexample 9335(define_delay (eq_attr "type" "branch") 9336 [(eq_attr "type" "!branch,call") 9337 (eq_attr "type" "!branch,call") 9338 (nil)]) 9339 9340(define_delay (eq_attr "type" "call") 9341 [(eq_attr "type" "!branch,call") (nil) (nil) 9342 (eq_attr "type" "!branch,call") (nil) (nil)]) 9343@end smallexample 9344@c the above is *still* too long. --mew 4feb93 9345 9346@end ifset 9347@ifset INTERNALS 9348@node Processor pipeline description 9349@subsection Specifying processor pipeline description 9350@cindex processor pipeline description 9351@cindex processor functional units 9352@cindex instruction latency time 9353@cindex interlock delays 9354@cindex data dependence delays 9355@cindex reservation delays 9356@cindex pipeline hazard recognizer 9357@cindex automaton based pipeline description 9358@cindex regular expressions 9359@cindex deterministic finite state automaton 9360@cindex automaton based scheduler 9361@cindex RISC 9362@cindex VLIW 9363 9364To achieve better performance, most modern processors 9365(super-pipelined, superscalar @acronym{RISC}, and @acronym{VLIW} 9366processors) have many @dfn{functional units} on which several 9367instructions can be executed simultaneously. An instruction starts 9368execution if its issue conditions are satisfied. If not, the 9369instruction is stalled until its conditions are satisfied. Such 9370@dfn{interlock (pipeline) delay} causes interruption of the fetching 9371of successor instructions (or demands nop instructions, e.g.@: for some 9372MIPS processors). 9373 9374There are two major kinds of interlock delays in modern processors. 9375The first one is a data dependence delay determining @dfn{instruction 9376latency time}. The instruction execution is not started until all 9377source data have been evaluated by prior instructions (there are more 9378complex cases when the instruction execution starts even when the data 9379are not available but will be ready in given time after the 9380instruction execution start). Taking the data dependence delays into 9381account is simple. The data dependence (true, output, and 9382anti-dependence) delay between two instructions is given by a 9383constant. In most cases this approach is adequate. The second kind 9384of interlock delays is a reservation delay. The reservation delay 9385means that two instructions under execution will be in need of shared 9386processors resources, i.e.@: buses, internal registers, and/or 9387functional units, which are reserved for some time. Taking this kind 9388of delay into account is complex especially for modern @acronym{RISC} 9389processors. 9390 9391The task of exploiting more processor parallelism is solved by an 9392instruction scheduler. For a better solution to this problem, the 9393instruction scheduler has to have an adequate description of the 9394processor parallelism (or @dfn{pipeline description}). GCC 9395machine descriptions describe processor parallelism and functional 9396unit reservations for groups of instructions with the aid of 9397@dfn{regular expressions}. 9398 9399The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to 9400figure out the possibility of the instruction issue by the processor 9401on a given simulated processor cycle. The pipeline hazard recognizer is 9402automatically generated from the processor pipeline description. The 9403pipeline hazard recognizer generated from the machine description 9404is based on a deterministic finite state automaton (@acronym{DFA}): 9405the instruction issue is possible if there is a transition from one 9406automaton state to another one. This algorithm is very fast, and 9407furthermore, its speed is not dependent on processor 9408complexity@footnote{However, the size of the automaton depends on 9409processor complexity. To limit this effect, machine descriptions 9410can split orthogonal parts of the machine description among several 9411automata: but then, since each of these must be stepped independently, 9412this does cause a small decrease in the algorithm's performance.}. 9413 9414@cindex automaton based pipeline description 9415The rest of this section describes the directives that constitute 9416an automaton-based processor pipeline description. The order of 9417these constructions within the machine description file is not 9418important. 9419 9420@findex define_automaton 9421@cindex pipeline hazard recognizer 9422The following optional construction describes names of automata 9423generated and used for the pipeline hazards recognition. Sometimes 9424the generated finite state automaton used by the pipeline hazard 9425recognizer is large. If we use more than one automaton and bind functional 9426units to the automata, the total size of the automata is usually 9427less than the size of the single automaton. If there is no one such 9428construction, only one finite state automaton is generated. 9429 9430@smallexample 9431(define_automaton @var{automata-names}) 9432@end smallexample 9433 9434@var{automata-names} is a string giving names of the automata. The 9435names are separated by commas. All the automata should have unique names. 9436The automaton name is used in the constructions @code{define_cpu_unit} and 9437@code{define_query_cpu_unit}. 9438 9439@findex define_cpu_unit 9440@cindex processor functional units 9441Each processor functional unit used in the description of instruction 9442reservations should be described by the following construction. 9443 9444@smallexample 9445(define_cpu_unit @var{unit-names} [@var{automaton-name}]) 9446@end smallexample 9447 9448@var{unit-names} is a string giving the names of the functional units 9449separated by commas. Don't use name @samp{nothing}, it is reserved 9450for other goals. 9451 9452@var{automaton-name} is a string giving the name of the automaton with 9453which the unit is bound. The automaton should be described in 9454construction @code{define_automaton}. You should give 9455@dfn{automaton-name}, if there is a defined automaton. 9456 9457The assignment of units to automata are constrained by the uses of the 9458units in insn reservations. The most important constraint is: if a 9459unit reservation is present on a particular cycle of an alternative 9460for an insn reservation, then some unit from the same automaton must 9461be present on the same cycle for the other alternatives of the insn 9462reservation. The rest of the constraints are mentioned in the 9463description of the subsequent constructions. 9464 9465@findex define_query_cpu_unit 9466@cindex querying function unit reservations 9467The following construction describes CPU functional units analogously 9468to @code{define_cpu_unit}. The reservation of such units can be 9469queried for an automaton state. The instruction scheduler never 9470queries reservation of functional units for given automaton state. So 9471as a rule, you don't need this construction. This construction could 9472be used for future code generation goals (e.g.@: to generate 9473@acronym{VLIW} insn templates). 9474 9475@smallexample 9476(define_query_cpu_unit @var{unit-names} [@var{automaton-name}]) 9477@end smallexample 9478 9479@var{unit-names} is a string giving names of the functional units 9480separated by commas. 9481 9482@var{automaton-name} is a string giving the name of the automaton with 9483which the unit is bound. 9484 9485@findex define_insn_reservation 9486@cindex instruction latency time 9487@cindex regular expressions 9488@cindex data bypass 9489The following construction is the major one to describe pipeline 9490characteristics of an instruction. 9491 9492@smallexample 9493(define_insn_reservation @var{insn-name} @var{default_latency} 9494 @var{condition} @var{regexp}) 9495@end smallexample 9496 9497@var{default_latency} is a number giving latency time of the 9498instruction. There is an important difference between the old 9499description and the automaton based pipeline description. The latency 9500time is used for all dependencies when we use the old description. In 9501the automaton based pipeline description, the given latency time is only 9502used for true dependencies. The cost of anti-dependencies is always 9503zero and the cost of output dependencies is the difference between 9504latency times of the producing and consuming insns (if the difference 9505is negative, the cost is considered to be zero). You can always 9506change the default costs for any description by using the target hook 9507@code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}). 9508 9509@var{insn-name} is a string giving the internal name of the insn. The 9510internal names are used in constructions @code{define_bypass} and in 9511the automaton description file generated for debugging. The internal 9512name has nothing in common with the names in @code{define_insn}. It is a 9513good practice to use insn classes described in the processor manual. 9514 9515@var{condition} defines what RTL insns are described by this 9516construction. You should remember that you will be in trouble if 9517@var{condition} for two or more different 9518@code{define_insn_reservation} constructions is TRUE for an insn. In 9519this case what reservation will be used for the insn is not defined. 9520Such cases are not checked during generation of the pipeline hazards 9521recognizer because in general recognizing that two conditions may have 9522the same value is quite difficult (especially if the conditions 9523contain @code{symbol_ref}). It is also not checked during the 9524pipeline hazard recognizer work because it would slow down the 9525recognizer considerably. 9526 9527@var{regexp} is a string describing the reservation of the cpu's functional 9528units by the instruction. The reservations are described by a regular 9529expression according to the following syntax: 9530 9531@smallexample 9532 regexp = regexp "," oneof 9533 | oneof 9534 9535 oneof = oneof "|" allof 9536 | allof 9537 9538 allof = allof "+" repeat 9539 | repeat 9540 9541 repeat = element "*" number 9542 | element 9543 9544 element = cpu_function_unit_name 9545 | reservation_name 9546 | result_name 9547 | "nothing" 9548 | "(" regexp ")" 9549@end smallexample 9550 9551@itemize @bullet 9552@item 9553@samp{,} is used for describing the start of the next cycle in 9554the reservation. 9555 9556@item 9557@samp{|} is used for describing a reservation described by the first 9558regular expression @strong{or} a reservation described by the second 9559regular expression @strong{or} etc. 9560 9561@item 9562@samp{+} is used for describing a reservation described by the first 9563regular expression @strong{and} a reservation described by the 9564second regular expression @strong{and} etc. 9565 9566@item 9567@samp{*} is used for convenience and simply means a sequence in which 9568the regular expression are repeated @var{number} times with cycle 9569advancing (see @samp{,}). 9570 9571@item 9572@samp{cpu_function_unit_name} denotes reservation of the named 9573functional unit. 9574 9575@item 9576@samp{reservation_name} --- see description of construction 9577@samp{define_reservation}. 9578 9579@item 9580@samp{nothing} denotes no unit reservations. 9581@end itemize 9582 9583@findex define_reservation 9584Sometimes unit reservations for different insns contain common parts. 9585In such case, you can simplify the pipeline description by describing 9586the common part by the following construction 9587 9588@smallexample 9589(define_reservation @var{reservation-name} @var{regexp}) 9590@end smallexample 9591 9592@var{reservation-name} is a string giving name of @var{regexp}. 9593Functional unit names and reservation names are in the same name 9594space. So the reservation names should be different from the 9595functional unit names and can not be the reserved name @samp{nothing}. 9596 9597@findex define_bypass 9598@cindex instruction latency time 9599@cindex data bypass 9600The following construction is used to describe exceptions in the 9601latency time for given instruction pair. This is so called bypasses. 9602 9603@smallexample 9604(define_bypass @var{number} @var{out_insn_names} @var{in_insn_names} 9605 [@var{guard}]) 9606@end smallexample 9607 9608@var{number} defines when the result generated by the instructions 9609given in string @var{out_insn_names} will be ready for the 9610instructions given in string @var{in_insn_names}. Each of these 9611strings is a comma-separated list of filename-style globs and 9612they refer to the names of @code{define_insn_reservation}s. 9613For example: 9614@smallexample 9615(define_bypass 1 "cpu1_load_*, cpu1_store_*" "cpu1_load_*") 9616@end smallexample 9617defines a bypass between instructions that start with 9618@samp{cpu1_load_} or @samp{cpu1_store_} and those that start with 9619@samp{cpu1_load_}. 9620 9621@var{guard} is an optional string giving the name of a C function which 9622defines an additional guard for the bypass. The function will get the 9623two insns as parameters. If the function returns zero the bypass will 9624be ignored for this case. The additional guard is necessary to 9625recognize complicated bypasses, e.g.@: when the consumer is only an address 9626of insn @samp{store} (not a stored value). 9627 9628If there are more one bypass with the same output and input insns, the 9629chosen bypass is the first bypass with a guard in description whose 9630guard function returns nonzero. If there is no such bypass, then 9631bypass without the guard function is chosen. 9632 9633@findex exclusion_set 9634@findex presence_set 9635@findex final_presence_set 9636@findex absence_set 9637@findex final_absence_set 9638@cindex VLIW 9639@cindex RISC 9640The following five constructions are usually used to describe 9641@acronym{VLIW} processors, or more precisely, to describe a placement 9642of small instructions into @acronym{VLIW} instruction slots. They 9643can be used for @acronym{RISC} processors, too. 9644 9645@smallexample 9646(exclusion_set @var{unit-names} @var{unit-names}) 9647(presence_set @var{unit-names} @var{patterns}) 9648(final_presence_set @var{unit-names} @var{patterns}) 9649(absence_set @var{unit-names} @var{patterns}) 9650(final_absence_set @var{unit-names} @var{patterns}) 9651@end smallexample 9652 9653@var{unit-names} is a string giving names of functional units 9654separated by commas. 9655 9656@var{patterns} is a string giving patterns of functional units 9657separated by comma. Currently pattern is one unit or units 9658separated by white-spaces. 9659 9660The first construction (@samp{exclusion_set}) means that each 9661functional unit in the first string can not be reserved simultaneously 9662with a unit whose name is in the second string and vice versa. For 9663example, the construction is useful for describing processors 9664(e.g.@: some SPARC processors) with a fully pipelined floating point 9665functional unit which can execute simultaneously only single floating 9666point insns or only double floating point insns. 9667 9668The second construction (@samp{presence_set}) means that each 9669functional unit in the first string can not be reserved unless at 9670least one of pattern of units whose names are in the second string is 9671reserved. This is an asymmetric relation. For example, it is useful 9672for description that @acronym{VLIW} @samp{slot1} is reserved after 9673@samp{slot0} reservation. We could describe it by the following 9674construction 9675 9676@smallexample 9677(presence_set "slot1" "slot0") 9678@end smallexample 9679 9680Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0} 9681reservation. In this case we could write 9682 9683@smallexample 9684(presence_set "slot1" "slot0 b0") 9685@end smallexample 9686 9687The third construction (@samp{final_presence_set}) is analogous to 9688@samp{presence_set}. The difference between them is when checking is 9689done. When an instruction is issued in given automaton state 9690reflecting all current and planned unit reservations, the automaton 9691state is changed. The first state is a source state, the second one 9692is a result state. Checking for @samp{presence_set} is done on the 9693source state reservation, checking for @samp{final_presence_set} is 9694done on the result reservation. This construction is useful to 9695describe a reservation which is actually two subsequent reservations. 9696For example, if we use 9697 9698@smallexample 9699(presence_set "slot1" "slot0") 9700@end smallexample 9701 9702the following insn will be never issued (because @samp{slot1} requires 9703@samp{slot0} which is absent in the source state). 9704 9705@smallexample 9706(define_reservation "insn_and_nop" "slot0 + slot1") 9707@end smallexample 9708 9709but it can be issued if we use analogous @samp{final_presence_set}. 9710 9711The forth construction (@samp{absence_set}) means that each functional 9712unit in the first string can be reserved only if each pattern of units 9713whose names are in the second string is not reserved. This is an 9714asymmetric relation (actually @samp{exclusion_set} is analogous to 9715this one but it is symmetric). For example it might be useful in a 9716@acronym{VLIW} description to say that @samp{slot0} cannot be reserved 9717after either @samp{slot1} or @samp{slot2} have been reserved. This 9718can be described as: 9719 9720@smallexample 9721(absence_set "slot0" "slot1, slot2") 9722@end smallexample 9723 9724Or @samp{slot2} can not be reserved if @samp{slot0} and unit @samp{b0} 9725are reserved or @samp{slot1} and unit @samp{b1} are reserved. In 9726this case we could write 9727 9728@smallexample 9729(absence_set "slot2" "slot0 b0, slot1 b1") 9730@end smallexample 9731 9732All functional units mentioned in a set should belong to the same 9733automaton. 9734 9735The last construction (@samp{final_absence_set}) is analogous to 9736@samp{absence_set} but checking is done on the result (state) 9737reservation. See comments for @samp{final_presence_set}. 9738 9739@findex automata_option 9740@cindex deterministic finite state automaton 9741@cindex nondeterministic finite state automaton 9742@cindex finite state automaton minimization 9743You can control the generator of the pipeline hazard recognizer with 9744the following construction. 9745 9746@smallexample 9747(automata_option @var{options}) 9748@end smallexample 9749 9750@var{options} is a string giving options which affect the generated 9751code. Currently there are the following options: 9752 9753@itemize @bullet 9754@item 9755@dfn{no-minimization} makes no minimization of the automaton. This is 9756only worth to do when we are debugging the description and need to 9757look more accurately at reservations of states. 9758 9759@item 9760@dfn{time} means printing time statistics about the generation of 9761automata. 9762 9763@item 9764@dfn{stats} means printing statistics about the generated automata 9765such as the number of DFA states, NDFA states and arcs. 9766 9767@item 9768@dfn{v} means a generation of the file describing the result automata. 9769The file has suffix @samp{.dfa} and can be used for the description 9770verification and debugging. 9771 9772@item 9773@dfn{w} means a generation of warning instead of error for 9774non-critical errors. 9775 9776@item 9777@dfn{no-comb-vect} prevents the automaton generator from generating 9778two data structures and comparing them for space efficiency. Using 9779a comb vector to represent transitions may be better, but it can be 9780very expensive to construct. This option is useful if the build 9781process spends an unacceptably long time in genautomata. 9782 9783@item 9784@dfn{ndfa} makes nondeterministic finite state automata. This affects 9785the treatment of operator @samp{|} in the regular expressions. The 9786usual treatment of the operator is to try the first alternative and, 9787if the reservation is not possible, the second alternative. The 9788nondeterministic treatment means trying all alternatives, some of them 9789may be rejected by reservations in the subsequent insns. 9790 9791@item 9792@dfn{collapse-ndfa} modifies the behavior of the generator when 9793producing an automaton. An additional state transition to collapse a 9794nondeterministic @acronym{NDFA} state to a deterministic @acronym{DFA} 9795state is generated. It can be triggered by passing @code{const0_rtx} to 9796state_transition. In such an automaton, cycle advance transitions are 9797available only for these collapsed states. This option is useful for 9798ports that want to use the @code{ndfa} option, but also want to use 9799@code{define_query_cpu_unit} to assign units to insns issued in a cycle. 9800 9801@item 9802@dfn{progress} means output of a progress bar showing how many states 9803were generated so far for automaton being processed. This is useful 9804during debugging a @acronym{DFA} description. If you see too many 9805generated states, you could interrupt the generator of the pipeline 9806hazard recognizer and try to figure out a reason for generation of the 9807huge automaton. 9808@end itemize 9809 9810As an example, consider a superscalar @acronym{RISC} machine which can 9811issue three insns (two integer insns and one floating point insn) on 9812the cycle but can finish only two insns. To describe this, we define 9813the following functional units. 9814 9815@smallexample 9816(define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline") 9817(define_cpu_unit "port0, port1") 9818@end smallexample 9819 9820All simple integer insns can be executed in any integer pipeline and 9821their result is ready in two cycles. The simple integer insns are 9822issued into the first pipeline unless it is reserved, otherwise they 9823are issued into the second pipeline. Integer division and 9824multiplication insns can be executed only in the second integer 9825pipeline and their results are ready correspondingly in 9 and 4 9826cycles. The integer division is not pipelined, i.e.@: the subsequent 9827integer division insn can not be issued until the current division 9828insn finished. Floating point insns are fully pipelined and their 9829results are ready in 3 cycles. Where the result of a floating point 9830insn is used by an integer insn, an additional delay of one cycle is 9831incurred. To describe all of this we could specify 9832 9833@smallexample 9834(define_cpu_unit "div") 9835 9836(define_insn_reservation "simple" 2 (eq_attr "type" "int") 9837 "(i0_pipeline | i1_pipeline), (port0 | port1)") 9838 9839(define_insn_reservation "mult" 4 (eq_attr "type" "mult") 9840 "i1_pipeline, nothing*2, (port0 | port1)") 9841 9842(define_insn_reservation "div" 9 (eq_attr "type" "div") 9843 "i1_pipeline, div*7, div + (port0 | port1)") 9844 9845(define_insn_reservation "float" 3 (eq_attr "type" "float") 9846 "f_pipeline, nothing, (port0 | port1)) 9847 9848(define_bypass 4 "float" "simple,mult,div") 9849@end smallexample 9850 9851To simplify the description we could describe the following reservation 9852 9853@smallexample 9854(define_reservation "finish" "port0|port1") 9855@end smallexample 9856 9857and use it in all @code{define_insn_reservation} as in the following 9858construction 9859 9860@smallexample 9861(define_insn_reservation "simple" 2 (eq_attr "type" "int") 9862 "(i0_pipeline | i1_pipeline), finish") 9863@end smallexample 9864 9865 9866@end ifset 9867@ifset INTERNALS 9868@node Conditional Execution 9869@section Conditional Execution 9870@cindex conditional execution 9871@cindex predication 9872 9873A number of architectures provide for some form of conditional 9874execution, or predication. The hallmark of this feature is the 9875ability to nullify most of the instructions in the instruction set. 9876When the instruction set is large and not entirely symmetric, it 9877can be quite tedious to describe these forms directly in the 9878@file{.md} file. An alternative is the @code{define_cond_exec} template. 9879 9880@findex define_cond_exec 9881@smallexample 9882(define_cond_exec 9883 [@var{predicate-pattern}] 9884 "@var{condition}" 9885 "@var{output-template}" 9886 "@var{optional-insn-attribues}") 9887@end smallexample 9888 9889@var{predicate-pattern} is the condition that must be true for the 9890insn to be executed at runtime and should match a relational operator. 9891One can use @code{match_operator} to match several relational operators 9892at once. Any @code{match_operand} operands must have no more than one 9893alternative. 9894 9895@var{condition} is a C expression that must be true for the generated 9896pattern to match. 9897 9898@findex current_insn_predicate 9899@var{output-template} is a string similar to the @code{define_insn} 9900output template (@pxref{Output Template}), except that the @samp{*} 9901and @samp{@@} special cases do not apply. This is only useful if the 9902assembly text for the predicate is a simple prefix to the main insn. 9903In order to handle the general case, there is a global variable 9904@code{current_insn_predicate} that will contain the entire predicate 9905if the current insn is predicated, and will otherwise be @code{NULL}. 9906 9907@var{optional-insn-attributes} is an optional vector of attributes that gets 9908appended to the insn attributes of the produced cond_exec rtx. It can 9909be used to add some distinguishing attribute to cond_exec rtxs produced 9910that way. An example usage would be to use this attribute in conjunction 9911with attributes on the main pattern to disable particular alternatives under 9912certain conditions. 9913 9914When @code{define_cond_exec} is used, an implicit reference to 9915the @code{predicable} instruction attribute is made. 9916@xref{Insn Attributes}. This attribute must be a boolean (i.e.@: have 9917exactly two elements in its @var{list-of-values}), with the possible 9918values being @code{no} and @code{yes}. The default and all uses in 9919the insns must be a simple constant, not a complex expressions. It 9920may, however, depend on the alternative, by using a comma-separated 9921list of values. If that is the case, the port should also define an 9922@code{enabled} attribute (@pxref{Disable Insn Alternatives}), which 9923should also allow only @code{no} and @code{yes} as its values. 9924 9925For each @code{define_insn} for which the @code{predicable} 9926attribute is true, a new @code{define_insn} pattern will be 9927generated that matches a predicated version of the instruction. 9928For example, 9929 9930@smallexample 9931(define_insn "addsi" 9932 [(set (match_operand:SI 0 "register_operand" "r") 9933 (plus:SI (match_operand:SI 1 "register_operand" "r") 9934 (match_operand:SI 2 "register_operand" "r")))] 9935 "@var{test1}" 9936 "add %2,%1,%0") 9937 9938(define_cond_exec 9939 [(ne (match_operand:CC 0 "register_operand" "c") 9940 (const_int 0))] 9941 "@var{test2}" 9942 "(%0)") 9943@end smallexample 9944 9945@noindent 9946generates a new pattern 9947 9948@smallexample 9949(define_insn "" 9950 [(cond_exec 9951 (ne (match_operand:CC 3 "register_operand" "c") (const_int 0)) 9952 (set (match_operand:SI 0 "register_operand" "r") 9953 (plus:SI (match_operand:SI 1 "register_operand" "r") 9954 (match_operand:SI 2 "register_operand" "r"))))] 9955 "(@var{test2}) && (@var{test1})" 9956 "(%3) add %2,%1,%0") 9957@end smallexample 9958 9959@end ifset 9960@ifset INTERNALS 9961@node Define Subst 9962@section RTL Templates Transformations 9963@cindex define_subst 9964 9965For some hardware architectures there are common cases when the RTL 9966templates for the instructions can be derived from the other RTL 9967templates using simple transformations. E.g., @file{i386.md} contains 9968an RTL template for the ordinary @code{sub} instruction--- 9969@code{*subsi_1}, and for the @code{sub} instruction with subsequent 9970zero-extension---@code{*subsi_1_zext}. Such cases can be easily 9971implemented by a single meta-template capable of generating a modified 9972case based on the initial one: 9973 9974@findex define_subst 9975@smallexample 9976(define_subst "@var{name}" 9977 [@var{input-template}] 9978 "@var{condition}" 9979 [@var{output-template}]) 9980@end smallexample 9981@var{input-template} is a pattern describing the source RTL template, 9982which will be transformed. 9983 9984@var{condition} is a C expression that is conjunct with the condition 9985from the input-template to generate a condition to be used in the 9986output-template. 9987 9988@var{output-template} is a pattern that will be used in the resulting 9989template. 9990 9991@code{define_subst} mechanism is tightly coupled with the notion of the 9992subst attribute (@pxref{Subst Iterators}). The use of 9993@code{define_subst} is triggered by a reference to a subst attribute in 9994the transforming RTL template. This reference initiates duplication of 9995the source RTL template and substitution of the attributes with their 9996values. The source RTL template is left unchanged, while the copy is 9997transformed by @code{define_subst}. This transformation can fail in the 9998case when the source RTL template is not matched against the 9999input-template of the @code{define_subst}. In such case the copy is 10000deleted. 10001 10002@code{define_subst} can be used only in @code{define_insn} and 10003@code{define_expand}, it cannot be used in other expressions (e.g. in 10004@code{define_insn_and_split}). 10005 10006@menu 10007* Define Subst Example:: Example of @code{define_subst} work. 10008* Define Subst Pattern Matching:: Process of template comparison. 10009* Define Subst Output Template:: Generation of output template. 10010@end menu 10011 10012@node Define Subst Example 10013@subsection @code{define_subst} Example 10014@cindex define_subst 10015 10016To illustrate how @code{define_subst} works, let us examine a simple 10017template transformation. 10018 10019Suppose there are two kinds of instructions: one that touches flags and 10020the other that does not. The instructions of the second type could be 10021generated with the following @code{define_subst}: 10022 10023@smallexample 10024(define_subst "add_clobber_subst" 10025 [(set (match_operand:SI 0 "" "") 10026 (match_operand:SI 1 "" ""))] 10027 "" 10028 [(set (match_dup 0) 10029 (match_dup 1)) 10030 (clobber (reg:CC FLAGS_REG))] 10031@end smallexample 10032 10033This @code{define_subst} can be applied to any RTL pattern containing 10034@code{set} of mode SI and generates a copy with clobber when it is 10035applied. 10036 10037Assume there is an RTL template for a @code{max} instruction to be used 10038in @code{define_subst} mentioned above: 10039 10040@smallexample 10041(define_insn "maxsi" 10042 [(set (match_operand:SI 0 "register_operand" "=r") 10043 (max:SI 10044 (match_operand:SI 1 "register_operand" "r") 10045 (match_operand:SI 2 "register_operand" "r")))] 10046 "" 10047 "max\t@{%2, %1, %0|%0, %1, %2@}" 10048 [@dots{}]) 10049@end smallexample 10050 10051To mark the RTL template for @code{define_subst} application, 10052subst-attributes are used. They should be declared in advance: 10053 10054@smallexample 10055(define_subst_attr "add_clobber_name" "add_clobber_subst" "_noclobber" "_clobber") 10056@end smallexample 10057 10058Here @samp{add_clobber_name} is the attribute name, 10059@samp{add_clobber_subst} is the name of the corresponding 10060@code{define_subst}, the third argument (@samp{_noclobber}) is the 10061attribute value that would be substituted into the unchanged version of 10062the source RTL template, and the last argument (@samp{_clobber}) is the 10063value that would be substituted into the second, transformed, 10064version of the RTL template. 10065 10066Once the subst-attribute has been defined, it should be used in RTL 10067templates which need to be processed by the @code{define_subst}. So, 10068the original RTL template should be changed: 10069 10070@smallexample 10071(define_insn "maxsi<add_clobber_name>" 10072 [(set (match_operand:SI 0 "register_operand" "=r") 10073 (max:SI 10074 (match_operand:SI 1 "register_operand" "r") 10075 (match_operand:SI 2 "register_operand" "r")))] 10076 "" 10077 "max\t@{%2, %1, %0|%0, %1, %2@}" 10078 [@dots{}]) 10079@end smallexample 10080 10081The result of the @code{define_subst} usage would look like the following: 10082 10083@smallexample 10084(define_insn "maxsi_noclobber" 10085 [(set (match_operand:SI 0 "register_operand" "=r") 10086 (max:SI 10087 (match_operand:SI 1 "register_operand" "r") 10088 (match_operand:SI 2 "register_operand" "r")))] 10089 "" 10090 "max\t@{%2, %1, %0|%0, %1, %2@}" 10091 [@dots{}]) 10092(define_insn "maxsi_clobber" 10093 [(set (match_operand:SI 0 "register_operand" "=r") 10094 (max:SI 10095 (match_operand:SI 1 "register_operand" "r") 10096 (match_operand:SI 2 "register_operand" "r"))) 10097 (clobber (reg:CC FLAGS_REG))] 10098 "" 10099 "max\t@{%2, %1, %0|%0, %1, %2@}" 10100 [@dots{}]) 10101@end smallexample 10102 10103@node Define Subst Pattern Matching 10104@subsection Pattern Matching in @code{define_subst} 10105@cindex define_subst 10106 10107All expressions, allowed in @code{define_insn} or @code{define_expand}, 10108are allowed in the input-template of @code{define_subst}, except 10109@code{match_par_dup}, @code{match_scratch}, @code{match_parallel}. The 10110meanings of expressions in the input-template were changed: 10111 10112@code{match_operand} matches any expression (possibly, a subtree in 10113RTL-template), if modes of the @code{match_operand} and this expression 10114are the same, or mode of the @code{match_operand} is @code{VOIDmode}, or 10115this expression is @code{match_dup}, @code{match_op_dup}. If the 10116expression is @code{match_operand} too, and predicate of 10117@code{match_operand} from the input pattern is not empty, then the 10118predicates are compared. That can be used for more accurate filtering 10119of accepted RTL-templates. 10120 10121@code{match_operator} matches common operators (like @code{plus}, 10122@code{minus}), @code{unspec}, @code{unspec_volatile} operators and 10123@code{match_operator}s from the original pattern if the modes match and 10124@code{match_operator} from the input pattern has the same number of 10125operands as the operator from the original pattern. 10126 10127@node Define Subst Output Template 10128@subsection Generation of output template in @code{define_subst} 10129@cindex define_subst 10130 10131If all necessary checks for @code{define_subst} application pass, a new 10132RTL-pattern, based on the output-template, is created to replace the old 10133template. Like in input-patterns, meanings of some RTL expressions are 10134changed when they are used in output-patterns of a @code{define_subst}. 10135Thus, @code{match_dup} is used for copying the whole expression from the 10136original pattern, which matched corresponding @code{match_operand} from 10137the input pattern. 10138 10139@code{match_dup N} is used in the output template to be replaced with 10140the expression from the original pattern, which matched 10141@code{match_operand N} from the input pattern. As a consequence, 10142@code{match_dup} cannot be used to point to @code{match_operand}s from 10143the output pattern, it should always refer to a @code{match_operand} 10144from the input pattern. 10145 10146In the output template one can refer to the expressions from the 10147original pattern and create new ones. For instance, some operands could 10148be added by means of standard @code{match_operand}. 10149 10150After replacing @code{match_dup} with some RTL-subtree from the original 10151pattern, it could happen that several @code{match_operand}s in the 10152output pattern have the same indexes. It is unknown, how many and what 10153indexes would be used in the expression which would replace 10154@code{match_dup}, so such conflicts in indexes are inevitable. To 10155overcome this issue, @code{match_operands} and @code{match_operators}, 10156which were introduced into the output pattern, are renumerated when all 10157@code{match_dup}s are replaced. 10158 10159Number of alternatives in @code{match_operand}s introduced into the 10160output template @code{M} could differ from the number of alternatives in 10161the original pattern @code{N}, so in the resultant pattern there would 10162be @code{N*M} alternatives. Thus, constraints from the original pattern 10163would be duplicated @code{N} times, constraints from the output pattern 10164would be duplicated @code{M} times, producing all possible combinations. 10165@end ifset 10166 10167@ifset INTERNALS 10168@node Constant Definitions 10169@section Constant Definitions 10170@cindex constant definitions 10171@findex define_constants 10172 10173Using literal constants inside instruction patterns reduces legibility and 10174can be a maintenance problem. 10175 10176To overcome this problem, you may use the @code{define_constants} 10177expression. It contains a vector of name-value pairs. From that 10178point on, wherever any of the names appears in the MD file, it is as 10179if the corresponding value had been written instead. You may use 10180@code{define_constants} multiple times; each appearance adds more 10181constants to the table. It is an error to redefine a constant with 10182a different value. 10183 10184To come back to the a29k load multiple example, instead of 10185 10186@smallexample 10187(define_insn "" 10188 [(match_parallel 0 "load_multiple_operation" 10189 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 10190 (match_operand:SI 2 "memory_operand" "m")) 10191 (use (reg:SI 179)) 10192 (clobber (reg:SI 179))])] 10193 "" 10194 "loadm 0,0,%1,%2") 10195@end smallexample 10196 10197You could write: 10198 10199@smallexample 10200(define_constants [ 10201 (R_BP 177) 10202 (R_FC 178) 10203 (R_CR 179) 10204 (R_Q 180) 10205]) 10206 10207(define_insn "" 10208 [(match_parallel 0 "load_multiple_operation" 10209 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 10210 (match_operand:SI 2 "memory_operand" "m")) 10211 (use (reg:SI R_CR)) 10212 (clobber (reg:SI R_CR))])] 10213 "" 10214 "loadm 0,0,%1,%2") 10215@end smallexample 10216 10217The constants that are defined with a define_constant are also output 10218in the insn-codes.h header file as #defines. 10219 10220@cindex enumerations 10221@findex define_c_enum 10222You can also use the machine description file to define enumerations. 10223Like the constants defined by @code{define_constant}, these enumerations 10224are visible to both the machine description file and the main C code. 10225 10226The syntax is as follows: 10227 10228@smallexample 10229(define_c_enum "@var{name}" [ 10230 @var{value0} 10231 @var{value1} 10232 @dots{} 10233 @var{valuen} 10234]) 10235@end smallexample 10236 10237This definition causes the equivalent of the following C code to appear 10238in @file{insn-constants.h}: 10239 10240@smallexample 10241enum @var{name} @{ 10242 @var{value0} = 0, 10243 @var{value1} = 1, 10244 @dots{} 10245 @var{valuen} = @var{n} 10246@}; 10247#define NUM_@var{cname}_VALUES (@var{n} + 1) 10248@end smallexample 10249 10250where @var{cname} is the capitalized form of @var{name}. 10251It also makes each @var{valuei} available in the machine description 10252file, just as if it had been declared with: 10253 10254@smallexample 10255(define_constants [(@var{valuei} @var{i})]) 10256@end smallexample 10257 10258Each @var{valuei} is usually an upper-case identifier and usually 10259begins with @var{cname}. 10260 10261You can split the enumeration definition into as many statements as 10262you like. The above example is directly equivalent to: 10263 10264@smallexample 10265(define_c_enum "@var{name}" [@var{value0}]) 10266(define_c_enum "@var{name}" [@var{value1}]) 10267@dots{} 10268(define_c_enum "@var{name}" [@var{valuen}]) 10269@end smallexample 10270 10271Splitting the enumeration helps to improve the modularity of each 10272individual @code{.md} file. For example, if a port defines its 10273synchronization instructions in a separate @file{sync.md} file, 10274it is convenient to define all synchronization-specific enumeration 10275values in @file{sync.md} rather than in the main @file{.md} file. 10276 10277Some enumeration names have special significance to GCC: 10278 10279@table @code 10280@item unspecv 10281@findex unspec_volatile 10282If an enumeration called @code{unspecv} is defined, GCC will use it 10283when printing out @code{unspec_volatile} expressions. For example: 10284 10285@smallexample 10286(define_c_enum "unspecv" [ 10287 UNSPECV_BLOCKAGE 10288]) 10289@end smallexample 10290 10291causes GCC to print @samp{(unspec_volatile @dots{} 0)} as: 10292 10293@smallexample 10294(unspec_volatile ... UNSPECV_BLOCKAGE) 10295@end smallexample 10296 10297@item unspec 10298@findex unspec 10299If an enumeration called @code{unspec} is defined, GCC will use 10300it when printing out @code{unspec} expressions. GCC will also use 10301it when printing out @code{unspec_volatile} expressions unless an 10302@code{unspecv} enumeration is also defined. You can therefore 10303decide whether to keep separate enumerations for volatile and 10304non-volatile expressions or whether to use the same enumeration 10305for both. 10306@end table 10307 10308@findex define_enum 10309@anchor{define_enum} 10310Another way of defining an enumeration is to use @code{define_enum}: 10311 10312@smallexample 10313(define_enum "@var{name}" [ 10314 @var{value0} 10315 @var{value1} 10316 @dots{} 10317 @var{valuen} 10318]) 10319@end smallexample 10320 10321This directive implies: 10322 10323@smallexample 10324(define_c_enum "@var{name}" [ 10325 @var{cname}_@var{cvalue0} 10326 @var{cname}_@var{cvalue1} 10327 @dots{} 10328 @var{cname}_@var{cvaluen} 10329]) 10330@end smallexample 10331 10332@findex define_enum_attr 10333where @var{cvaluei} is the capitalized form of @var{valuei}. 10334However, unlike @code{define_c_enum}, the enumerations defined 10335by @code{define_enum} can be used in attribute specifications 10336(@pxref{define_enum_attr}). 10337@end ifset 10338@ifset INTERNALS 10339@node Iterators 10340@section Iterators 10341@cindex iterators in @file{.md} files 10342 10343Ports often need to define similar patterns for more than one machine 10344mode or for more than one rtx code. GCC provides some simple iterator 10345facilities to make this process easier. 10346 10347@menu 10348* Mode Iterators:: Generating variations of patterns for different modes. 10349* Code Iterators:: Doing the same for codes. 10350* Int Iterators:: Doing the same for integers. 10351* Subst Iterators:: Generating variations of patterns for define_subst. 10352@end menu 10353 10354@node Mode Iterators 10355@subsection Mode Iterators 10356@cindex mode iterators in @file{.md} files 10357 10358Ports often need to define similar patterns for two or more different modes. 10359For example: 10360 10361@itemize @bullet 10362@item 10363If a processor has hardware support for both single and double 10364floating-point arithmetic, the @code{SFmode} patterns tend to be 10365very similar to the @code{DFmode} ones. 10366 10367@item 10368If a port uses @code{SImode} pointers in one configuration and 10369@code{DImode} pointers in another, it will usually have very similar 10370@code{SImode} and @code{DImode} patterns for manipulating pointers. 10371@end itemize 10372 10373Mode iterators allow several patterns to be instantiated from one 10374@file{.md} file template. They can be used with any type of 10375rtx-based construct, such as a @code{define_insn}, 10376@code{define_split}, or @code{define_peephole2}. 10377 10378@menu 10379* Defining Mode Iterators:: Defining a new mode iterator. 10380* Substitutions:: Combining mode iterators with substitutions 10381* Examples:: Examples 10382@end menu 10383 10384@node Defining Mode Iterators 10385@subsubsection Defining Mode Iterators 10386@findex define_mode_iterator 10387 10388The syntax for defining a mode iterator is: 10389 10390@smallexample 10391(define_mode_iterator @var{name} [(@var{mode1} "@var{cond1}") @dots{} (@var{moden} "@var{condn}")]) 10392@end smallexample 10393 10394This allows subsequent @file{.md} file constructs to use the mode suffix 10395@code{:@var{name}}. Every construct that does so will be expanded 10396@var{n} times, once with every use of @code{:@var{name}} replaced by 10397@code{:@var{mode1}}, once with every use replaced by @code{:@var{mode2}}, 10398and so on. In the expansion for a particular @var{modei}, every 10399C condition will also require that @var{condi} be true. 10400 10401For example: 10402 10403@smallexample 10404(define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")]) 10405@end smallexample 10406 10407defines a new mode suffix @code{:P}. Every construct that uses 10408@code{:P} will be expanded twice, once with every @code{:P} replaced 10409by @code{:SI} and once with every @code{:P} replaced by @code{:DI}. 10410The @code{:SI} version will only apply if @code{Pmode == SImode} and 10411the @code{:DI} version will only apply if @code{Pmode == DImode}. 10412 10413As with other @file{.md} conditions, an empty string is treated 10414as ``always true''. @code{(@var{mode} "")} can also be abbreviated 10415to @code{@var{mode}}. For example: 10416 10417@smallexample 10418(define_mode_iterator GPR [SI (DI "TARGET_64BIT")]) 10419@end smallexample 10420 10421means that the @code{:DI} expansion only applies if @code{TARGET_64BIT} 10422but that the @code{:SI} expansion has no such constraint. 10423 10424Iterators are applied in the order they are defined. This can be 10425significant if two iterators are used in a construct that requires 10426substitutions. @xref{Substitutions}. 10427 10428@node Substitutions 10429@subsubsection Substitution in Mode Iterators 10430@findex define_mode_attr 10431 10432If an @file{.md} file construct uses mode iterators, each version of the 10433construct will often need slightly different strings or modes. For 10434example: 10435 10436@itemize @bullet 10437@item 10438When a @code{define_expand} defines several @code{add@var{m}3} patterns 10439(@pxref{Standard Names}), each expander will need to use the 10440appropriate mode name for @var{m}. 10441 10442@item 10443When a @code{define_insn} defines several instruction patterns, 10444each instruction will often use a different assembler mnemonic. 10445 10446@item 10447When a @code{define_insn} requires operands with different modes, 10448using an iterator for one of the operand modes usually requires a specific 10449mode for the other operand(s). 10450@end itemize 10451 10452GCC supports such variations through a system of ``mode attributes''. 10453There are two standard attributes: @code{mode}, which is the name of 10454the mode in lower case, and @code{MODE}, which is the same thing in 10455upper case. You can define other attributes using: 10456 10457@smallexample 10458(define_mode_attr @var{name} [(@var{mode1} "@var{value1}") @dots{} (@var{moden} "@var{valuen}")]) 10459@end smallexample 10460 10461where @var{name} is the name of the attribute and @var{valuei} 10462is the value associated with @var{modei}. 10463 10464When GCC replaces some @var{:iterator} with @var{:mode}, it will scan 10465each string and mode in the pattern for sequences of the form 10466@code{<@var{iterator}:@var{attr}>}, where @var{attr} is the name of a 10467mode attribute. If the attribute is defined for @var{mode}, the whole 10468@code{<@dots{}>} sequence will be replaced by the appropriate attribute 10469value. 10470 10471For example, suppose an @file{.md} file has: 10472 10473@smallexample 10474(define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")]) 10475(define_mode_attr load [(SI "lw") (DI "ld")]) 10476@end smallexample 10477 10478If one of the patterns that uses @code{:P} contains the string 10479@code{"<P:load>\t%0,%1"}, the @code{SI} version of that pattern 10480will use @code{"lw\t%0,%1"} and the @code{DI} version will use 10481@code{"ld\t%0,%1"}. 10482 10483Here is an example of using an attribute for a mode: 10484 10485@smallexample 10486(define_mode_iterator LONG [SI DI]) 10487(define_mode_attr SHORT [(SI "HI") (DI "SI")]) 10488(define_insn @dots{} 10489 (sign_extend:LONG (match_operand:<LONG:SHORT> @dots{})) @dots{}) 10490@end smallexample 10491 10492The @code{@var{iterator}:} prefix may be omitted, in which case the 10493substitution will be attempted for every iterator expansion. 10494 10495@node Examples 10496@subsubsection Mode Iterator Examples 10497 10498Here is an example from the MIPS port. It defines the following 10499modes and attributes (among others): 10500 10501@smallexample 10502(define_mode_iterator GPR [SI (DI "TARGET_64BIT")]) 10503(define_mode_attr d [(SI "") (DI "d")]) 10504@end smallexample 10505 10506and uses the following template to define both @code{subsi3} 10507and @code{subdi3}: 10508 10509@smallexample 10510(define_insn "sub<mode>3" 10511 [(set (match_operand:GPR 0 "register_operand" "=d") 10512 (minus:GPR (match_operand:GPR 1 "register_operand" "d") 10513 (match_operand:GPR 2 "register_operand" "d")))] 10514 "" 10515 "<d>subu\t%0,%1,%2" 10516 [(set_attr "type" "arith") 10517 (set_attr "mode" "<MODE>")]) 10518@end smallexample 10519 10520This is exactly equivalent to: 10521 10522@smallexample 10523(define_insn "subsi3" 10524 [(set (match_operand:SI 0 "register_operand" "=d") 10525 (minus:SI (match_operand:SI 1 "register_operand" "d") 10526 (match_operand:SI 2 "register_operand" "d")))] 10527 "" 10528 "subu\t%0,%1,%2" 10529 [(set_attr "type" "arith") 10530 (set_attr "mode" "SI")]) 10531 10532(define_insn "subdi3" 10533 [(set (match_operand:DI 0 "register_operand" "=d") 10534 (minus:DI (match_operand:DI 1 "register_operand" "d") 10535 (match_operand:DI 2 "register_operand" "d")))] 10536 "" 10537 "dsubu\t%0,%1,%2" 10538 [(set_attr "type" "arith") 10539 (set_attr "mode" "DI")]) 10540@end smallexample 10541 10542@node Code Iterators 10543@subsection Code Iterators 10544@cindex code iterators in @file{.md} files 10545@findex define_code_iterator 10546@findex define_code_attr 10547 10548Code iterators operate in a similar way to mode iterators. @xref{Mode Iterators}. 10549 10550The construct: 10551 10552@smallexample 10553(define_code_iterator @var{name} [(@var{code1} "@var{cond1}") @dots{} (@var{coden} "@var{condn}")]) 10554@end smallexample 10555 10556defines a pseudo rtx code @var{name} that can be instantiated as 10557@var{codei} if condition @var{condi} is true. Each @var{codei} 10558must have the same rtx format. @xref{RTL Classes}. 10559 10560As with mode iterators, each pattern that uses @var{name} will be 10561expanded @var{n} times, once with all uses of @var{name} replaced by 10562@var{code1}, once with all uses replaced by @var{code2}, and so on. 10563@xref{Defining Mode Iterators}. 10564 10565It is possible to define attributes for codes as well as for modes. 10566There are two standard code attributes: @code{code}, the name of the 10567code in lower case, and @code{CODE}, the name of the code in upper case. 10568Other attributes are defined using: 10569 10570@smallexample 10571(define_code_attr @var{name} [(@var{code1} "@var{value1}") @dots{} (@var{coden} "@var{valuen}")]) 10572@end smallexample 10573 10574Here's an example of code iterators in action, taken from the MIPS port: 10575 10576@smallexample 10577(define_code_iterator any_cond [unordered ordered unlt unge uneq ltgt unle ungt 10578 eq ne gt ge lt le gtu geu ltu leu]) 10579 10580(define_expand "b<code>" 10581 [(set (pc) 10582 (if_then_else (any_cond:CC (cc0) 10583 (const_int 0)) 10584 (label_ref (match_operand 0 "")) 10585 (pc)))] 10586 "" 10587@{ 10588 gen_conditional_branch (operands, <CODE>); 10589 DONE; 10590@}) 10591@end smallexample 10592 10593This is equivalent to: 10594 10595@smallexample 10596(define_expand "bunordered" 10597 [(set (pc) 10598 (if_then_else (unordered:CC (cc0) 10599 (const_int 0)) 10600 (label_ref (match_operand 0 "")) 10601 (pc)))] 10602 "" 10603@{ 10604 gen_conditional_branch (operands, UNORDERED); 10605 DONE; 10606@}) 10607 10608(define_expand "bordered" 10609 [(set (pc) 10610 (if_then_else (ordered:CC (cc0) 10611 (const_int 0)) 10612 (label_ref (match_operand 0 "")) 10613 (pc)))] 10614 "" 10615@{ 10616 gen_conditional_branch (operands, ORDERED); 10617 DONE; 10618@}) 10619 10620@dots{} 10621@end smallexample 10622 10623@node Int Iterators 10624@subsection Int Iterators 10625@cindex int iterators in @file{.md} files 10626@findex define_int_iterator 10627@findex define_int_attr 10628 10629Int iterators operate in a similar way to code iterators. @xref{Code Iterators}. 10630 10631The construct: 10632 10633@smallexample 10634(define_int_iterator @var{name} [(@var{int1} "@var{cond1}") @dots{} (@var{intn} "@var{condn}")]) 10635@end smallexample 10636 10637defines a pseudo integer constant @var{name} that can be instantiated as 10638@var{inti} if condition @var{condi} is true. Each @var{int} 10639must have the same rtx format. @xref{RTL Classes}. Int iterators can appear 10640in only those rtx fields that have 'i' as the specifier. This means that 10641each @var{int} has to be a constant defined using define_constant or 10642define_c_enum. 10643 10644As with mode and code iterators, each pattern that uses @var{name} will be 10645expanded @var{n} times, once with all uses of @var{name} replaced by 10646@var{int1}, once with all uses replaced by @var{int2}, and so on. 10647@xref{Defining Mode Iterators}. 10648 10649It is possible to define attributes for ints as well as for codes and modes. 10650Attributes are defined using: 10651 10652@smallexample 10653(define_int_attr @var{name} [(@var{int1} "@var{value1}") @dots{} (@var{intn} "@var{valuen}")]) 10654@end smallexample 10655 10656Here's an example of int iterators in action, taken from the ARM port: 10657 10658@smallexample 10659(define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG]) 10660 10661(define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")]) 10662 10663(define_insn "neon_vq<absneg><mode>" 10664 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 10665 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 10666 (match_operand:SI 2 "immediate_operand" "i")] 10667 QABSNEG))] 10668 "TARGET_NEON" 10669 "vq<absneg>.<V_s_elem>\t%<V_reg>0, %<V_reg>1" 10670 [(set_attr "type" "neon_vqneg_vqabs")] 10671) 10672 10673@end smallexample 10674 10675This is equivalent to: 10676 10677@smallexample 10678(define_insn "neon_vqabs<mode>" 10679 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 10680 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 10681 (match_operand:SI 2 "immediate_operand" "i")] 10682 UNSPEC_VQABS))] 10683 "TARGET_NEON" 10684 "vqabs.<V_s_elem>\t%<V_reg>0, %<V_reg>1" 10685 [(set_attr "type" "neon_vqneg_vqabs")] 10686) 10687 10688(define_insn "neon_vqneg<mode>" 10689 [(set (match_operand:VDQIW 0 "s_register_operand" "=w") 10690 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w") 10691 (match_operand:SI 2 "immediate_operand" "i")] 10692 UNSPEC_VQNEG))] 10693 "TARGET_NEON" 10694 "vqneg.<V_s_elem>\t%<V_reg>0, %<V_reg>1" 10695 [(set_attr "type" "neon_vqneg_vqabs")] 10696) 10697 10698@end smallexample 10699 10700@node Subst Iterators 10701@subsection Subst Iterators 10702@cindex subst iterators in @file{.md} files 10703@findex define_subst 10704@findex define_subst_attr 10705 10706Subst iterators are special type of iterators with the following 10707restrictions: they could not be declared explicitly, they always have 10708only two values, and they do not have explicit dedicated name. 10709Subst-iterators are triggered only when corresponding subst-attribute is 10710used in RTL-pattern. 10711 10712Subst iterators transform templates in the following way: the templates 10713are duplicated, the subst-attributes in these templates are replaced 10714with the corresponding values, and a new attribute is implicitly added 10715to the given @code{define_insn}/@code{define_expand}. The name of the 10716added attribute matches the name of @code{define_subst}. Such 10717attributes are declared implicitly, and it is not allowed to have a 10718@code{define_attr} named as a @code{define_subst}. 10719 10720Each subst iterator is linked to a @code{define_subst}. It is declared 10721implicitly by the first appearance of the corresponding 10722@code{define_subst_attr}, and it is not allowed to define it explicitly. 10723 10724Declarations of subst-attributes have the following syntax: 10725 10726@findex define_subst_attr 10727@smallexample 10728(define_subst_attr "@var{name}" 10729 "@var{subst-name}" 10730 "@var{no-subst-value}" 10731 "@var{subst-applied-value}") 10732@end smallexample 10733 10734@var{name} is a string with which the given subst-attribute could be 10735referred to. 10736 10737@var{subst-name} shows which @code{define_subst} should be applied to an 10738RTL-template if the given subst-attribute is present in the 10739RTL-template. 10740 10741@var{no-subst-value} is a value with which subst-attribute would be 10742replaced in the first copy of the original RTL-template. 10743 10744@var{subst-applied-value} is a value with which subst-attribute would be 10745replaced in the second copy of the original RTL-template. 10746 10747@end ifset 10748