1@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001, 2@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. 3@c This is part of the GCC manual. 4@c For copying conditions, see the file gcc.texi. 5 6@ifset INTERNALS 7@node Machine Desc 8@chapter Machine Descriptions 9@cindex machine descriptions 10 11A machine description has two parts: a file of instruction patterns 12(@file{.md} file) and a C header file of macro definitions. 13 14The @file{.md} file for a target machine contains a pattern for each 15instruction that the target machine supports (or at least each instruction 16that is worth telling the compiler about). It may also contain comments. 17A semicolon causes the rest of the line to be a comment, unless the semicolon 18is inside a quoted string. 19 20See the next chapter for information on the C header file. 21 22@menu 23* Overview:: How the machine description is used. 24* Patterns:: How to write instruction patterns. 25* Example:: An explained example of a @code{define_insn} pattern. 26* RTL Template:: The RTL template defines what insns match a pattern. 27* Output Template:: The output template says how to make assembler code 28 from such an insn. 29* Output Statement:: For more generality, write C code to output 30 the assembler code. 31* Predicates:: Controlling what kinds of operands can be used 32 for an insn. 33* Constraints:: Fine-tuning operand selection. 34* Standard Names:: Names mark patterns to use for code generation. 35* Pattern Ordering:: When the order of patterns makes a difference. 36* Dependent Patterns:: Having one pattern may make you need another. 37* Jump Patterns:: Special considerations for patterns for jump insns. 38* Looping Patterns:: How to define patterns for special looping insns. 39* Insn Canonicalizations::Canonicalization of Instructions 40* Expander Definitions::Generating a sequence of several RTL insns 41 for a standard operation. 42* Insn Splitting:: Splitting Instructions into Multiple Instructions. 43* Including Patterns:: Including Patterns in Machine Descriptions. 44* Peephole Definitions::Defining machine-specific peephole optimizations. 45* Insn Attributes:: Specifying the value of attributes for generated insns. 46* Conditional Execution::Generating @code{define_insn} patterns for 47 predication. 48* Constant Definitions::Defining symbolic constants that can be used in the 49 md file. 50* Macros:: Using macros to generate patterns from a template. 51@end menu 52 53@node Overview 54@section Overview of How the Machine Description is Used 55 56There are three main conversions that happen in the compiler: 57 58@enumerate 59 60@item 61The front end reads the source code and builds a parse tree. 62 63@item 64The parse tree is used to generate an RTL insn list based on named 65instruction patterns. 66 67@item 68The insn list is matched against the RTL templates to produce assembler 69code. 70 71@end enumerate 72 73For the generate pass, only the names of the insns matter, from either a 74named @code{define_insn} or a @code{define_expand}. The compiler will 75choose the pattern with the right name and apply the operands according 76to the documentation later in this chapter, without regard for the RTL 77template or operand constraints. Note that the names the compiler looks 78for are hard-coded in the compiler---it will ignore unnamed patterns and 79patterns with names it doesn't know about, but if you don't provide a 80named pattern it needs, it will abort. 81 82If a @code{define_insn} is used, the template given is inserted into the 83insn list. If a @code{define_expand} is used, one of three things 84happens, based on the condition logic. The condition logic may manually 85create new insns for the insn list, say via @code{emit_insn()}, and 86invoke @code{DONE}. For certain named patterns, it may invoke @code{FAIL} to tell the 87compiler to use an alternate way of performing that task. If it invokes 88neither @code{DONE} nor @code{FAIL}, the template given in the pattern 89is inserted, as if the @code{define_expand} were a @code{define_insn}. 90 91Once the insn list is generated, various optimization passes convert, 92replace, and rearrange the insns in the insn list. This is where the 93@code{define_split} and @code{define_peephole} patterns get used, for 94example. 95 96Finally, the insn list's RTL is matched up with the RTL templates in the 97@code{define_insn} patterns, and those patterns are used to emit the 98final assembly code. For this purpose, each named @code{define_insn} 99acts like it's unnamed, since the names are ignored. 100 101@node Patterns 102@section Everything about Instruction Patterns 103@cindex patterns 104@cindex instruction patterns 105 106@findex define_insn 107Each instruction pattern contains an incomplete RTL expression, with pieces 108to be filled in later, operand constraints that restrict how the pieces can 109be filled in, and an output pattern or C code to generate the assembler 110output, all wrapped up in a @code{define_insn} expression. 111 112A @code{define_insn} is an RTL expression containing four or five operands: 113 114@enumerate 115@item 116An optional name. The presence of a name indicate that this instruction 117pattern can perform a certain standard job for the RTL-generation 118pass of the compiler. This pass knows certain names and will use 119the instruction patterns with those names, if the names are defined 120in the machine description. 121 122The absence of a name is indicated by writing an empty string 123where the name should go. Nameless instruction patterns are never 124used for generating RTL code, but they may permit several simpler insns 125to be combined later on. 126 127Names that are not thus known and used in RTL-generation have no 128effect; they are equivalent to no name at all. 129 130For the purpose of debugging the compiler, you may also specify a 131name beginning with the @samp{*} character. Such a name is used only 132for identifying the instruction in RTL dumps; it is entirely equivalent 133to having a nameless pattern for all other purposes. 134 135@item 136The @dfn{RTL template} (@pxref{RTL Template}) is a vector of incomplete 137RTL expressions which show what the instruction should look like. It is 138incomplete because it may contain @code{match_operand}, 139@code{match_operator}, and @code{match_dup} expressions that stand for 140operands of the instruction. 141 142If the vector has only one element, that element is the template for the 143instruction pattern. If the vector has multiple elements, then the 144instruction pattern is a @code{parallel} expression containing the 145elements described. 146 147@item 148@cindex pattern conditions 149@cindex conditions, in patterns 150A condition. This is a string which contains a C expression that is 151the final test to decide whether an insn body matches this pattern. 152 153@cindex named patterns and conditions 154For a named pattern, the condition (if present) may not depend on 155the data in the insn being matched, but only the target-machine-type 156flags. The compiler needs to test these conditions during 157initialization in order to learn exactly which named instructions are 158available in a particular run. 159 160@findex operands 161For nameless patterns, the condition is applied only when matching an 162individual insn, and only after the insn has matched the pattern's 163recognition template. The insn's operands may be found in the vector 164@code{operands}. For an insn where the condition has once matched, it 165can't be used to control register allocation, for example by excluding 166certain hard registers or hard register combinations. 167 168@item 169The @dfn{output template}: a string that says how to output matching 170insns as assembler code. @samp{%} in this string specifies where 171to substitute the value of an operand. @xref{Output Template}. 172 173When simple substitution isn't general enough, you can specify a piece 174of C code to compute the output. @xref{Output Statement}. 175 176@item 177Optionally, a vector containing the values of attributes for insns matching 178this pattern. @xref{Insn Attributes}. 179@end enumerate 180 181@node Example 182@section Example of @code{define_insn} 183@cindex @code{define_insn} example 184 185Here is an actual example of an instruction pattern, for the 68000/68020. 186 187@smallexample 188(define_insn "tstsi" 189 [(set (cc0) 190 (match_operand:SI 0 "general_operand" "rm"))] 191 "" 192 "* 193@{ 194 if (TARGET_68020 || ! ADDRESS_REG_P (operands[0])) 195 return \"tstl %0\"; 196 return \"cmpl #0,%0\"; 197@}") 198@end smallexample 199 200@noindent 201This can also be written using braced strings: 202 203@smallexample 204(define_insn "tstsi" 205 [(set (cc0) 206 (match_operand:SI 0 "general_operand" "rm"))] 207 "" 208@{ 209 if (TARGET_68020 || ! ADDRESS_REG_P (operands[0])) 210 return "tstl %0"; 211 return "cmpl #0,%0"; 212@}) 213@end smallexample 214 215This is an instruction that sets the condition codes based on the value of 216a general operand. It has no condition, so any insn whose RTL description 217has the form shown may be handled according to this pattern. The name 218@samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation 219pass that, when it is necessary to test such a value, an insn to do so 220can be constructed using this pattern. 221 222The output control string is a piece of C code which chooses which 223output template to return based on the kind of operand and the specific 224type of CPU for which code is being generated. 225 226@samp{"rm"} is an operand constraint. Its meaning is explained below. 227 228@node RTL Template 229@section RTL Template 230@cindex RTL insn template 231@cindex generating insns 232@cindex insns, generating 233@cindex recognizing insns 234@cindex insns, recognizing 235 236The RTL template is used to define which insns match the particular pattern 237and how to find their operands. For named patterns, the RTL template also 238says how to construct an insn from specified operands. 239 240Construction involves substituting specified operands into a copy of the 241template. Matching involves determining the values that serve as the 242operands in the insn being matched. Both of these activities are 243controlled by special expression types that direct matching and 244substitution of the operands. 245 246@table @code 247@findex match_operand 248@item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint}) 249This expression is a placeholder for operand number @var{n} of 250the insn. When constructing an insn, operand number @var{n} 251will be substituted at this point. When matching an insn, whatever 252appears at this position in the insn will be taken as operand 253number @var{n}; but it must satisfy @var{predicate} or this instruction 254pattern will not match at all. 255 256Operand numbers must be chosen consecutively counting from zero in 257each instruction pattern. There may be only one @code{match_operand} 258expression in the pattern for each operand number. Usually operands 259are numbered in the order of appearance in @code{match_operand} 260expressions. In the case of a @code{define_expand}, any operand numbers 261used only in @code{match_dup} expressions have higher values than all 262other operand numbers. 263 264@var{predicate} is a string that is the name of a function that 265accepts two arguments, an expression and a machine mode. 266@xref{Predicates}. During matching, the function will be called with 267the putative operand as the expression and @var{m} as the mode 268argument (if @var{m} is not specified, @code{VOIDmode} will be used, 269which normally causes @var{predicate} to accept any mode). If it 270returns zero, this instruction pattern fails to match. 271@var{predicate} may be an empty string; then it means no test is to be 272done on the operand, so anything which occurs in this position is 273valid. 274 275Most of the time, @var{predicate} will reject modes other than @var{m}---but 276not always. For example, the predicate @code{address_operand} uses 277@var{m} as the mode of memory ref that the address should be valid for. 278Many predicates accept @code{const_int} nodes even though their mode is 279@code{VOIDmode}. 280 281@var{constraint} controls reloading and the choice of the best register 282class to use for a value, as explained later (@pxref{Constraints}). 283If the constraint would be an empty string, it can be omitted. 284 285People are often unclear on the difference between the constraint and the 286predicate. The predicate helps decide whether a given insn matches the 287pattern. The constraint plays no role in this decision; instead, it 288controls various decisions in the case of an insn which does match. 289 290@findex match_scratch 291@item (match_scratch:@var{m} @var{n} @var{constraint}) 292This expression is also a placeholder for operand number @var{n} 293and indicates that operand must be a @code{scratch} or @code{reg} 294expression. 295 296When matching patterns, this is equivalent to 297 298@smallexample 299(match_operand:@var{m} @var{n} "scratch_operand" @var{pred}) 300@end smallexample 301 302but, when generating RTL, it produces a (@code{scratch}:@var{m}) 303expression. 304 305If the last few expressions in a @code{parallel} are @code{clobber} 306expressions whose operands are either a hard register or 307@code{match_scratch}, the combiner can add or delete them when 308necessary. @xref{Side Effects}. 309 310@findex match_dup 311@item (match_dup @var{n}) 312This expression is also a placeholder for operand number @var{n}. 313It is used when the operand needs to appear more than once in the 314insn. 315 316In construction, @code{match_dup} acts just like @code{match_operand}: 317the operand is substituted into the insn being constructed. But in 318matching, @code{match_dup} behaves differently. It assumes that operand 319number @var{n} has already been determined by a @code{match_operand} 320appearing earlier in the recognition template, and it matches only an 321identical-looking expression. 322 323Note that @code{match_dup} should not be used to tell the compiler that 324a particular register is being used for two operands (example: 325@code{add} that adds one register to another; the second register is 326both an input operand and the output operand). Use a matching 327constraint (@pxref{Simple Constraints}) for those. @code{match_dup} is for the cases where one 328operand is used in two places in the template, such as an instruction 329that computes both a quotient and a remainder, where the opcode takes 330two input operands but the RTL template has to refer to each of those 331twice; once for the quotient pattern and once for the remainder pattern. 332 333@findex match_operator 334@item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}]) 335This pattern is a kind of placeholder for a variable RTL expression 336code. 337 338When constructing an insn, it stands for an RTL expression whose 339expression code is taken from that of operand @var{n}, and whose 340operands are constructed from the patterns @var{operands}. 341 342When matching an expression, it matches an expression if the function 343@var{predicate} returns nonzero on that expression @emph{and} the 344patterns @var{operands} match the operands of the expression. 345 346Suppose that the function @code{commutative_operator} is defined as 347follows, to match any expression whose operator is one of the 348commutative arithmetic operators of RTL and whose mode is @var{mode}: 349 350@smallexample 351int 352commutative_integer_operator (x, mode) 353 rtx x; 354 enum machine_mode mode; 355@{ 356 enum rtx_code code = GET_CODE (x); 357 if (GET_MODE (x) != mode) 358 return 0; 359 return (GET_RTX_CLASS (code) == RTX_COMM_ARITH 360 || code == EQ || code == NE); 361@} 362@end smallexample 363 364Then the following pattern will match any RTL expression consisting 365of a commutative operator applied to two general operands: 366 367@smallexample 368(match_operator:SI 3 "commutative_operator" 369 [(match_operand:SI 1 "general_operand" "g") 370 (match_operand:SI 2 "general_operand" "g")]) 371@end smallexample 372 373Here the vector @code{[@var{operands}@dots{}]} contains two patterns 374because the expressions to be matched all contain two operands. 375 376When this pattern does match, the two operands of the commutative 377operator are recorded as operands 1 and 2 of the insn. (This is done 378by the two instances of @code{match_operand}.) Operand 3 of the insn 379will be the entire commutative expression: use @code{GET_CODE 380(operands[3])} to see which commutative operator was used. 381 382The machine mode @var{m} of @code{match_operator} works like that of 383@code{match_operand}: it is passed as the second argument to the 384predicate function, and that function is solely responsible for 385deciding whether the expression to be matched ``has'' that mode. 386 387When constructing an insn, argument 3 of the gen-function will specify 388the operation (i.e.@: the expression code) for the expression to be 389made. It should be an RTL expression, whose expression code is copied 390into a new expression whose operands are arguments 1 and 2 of the 391gen-function. The subexpressions of argument 3 are not used; 392only its expression code matters. 393 394When @code{match_operator} is used in a pattern for matching an insn, 395it usually best if the operand number of the @code{match_operator} 396is higher than that of the actual operands of the insn. This improves 397register allocation because the register allocator often looks at 398operands 1 and 2 of insns to see if it can do register tying. 399 400There is no way to specify constraints in @code{match_operator}. The 401operand of the insn which corresponds to the @code{match_operator} 402never has any constraints because it is never reloaded as a whole. 403However, if parts of its @var{operands} are matched by 404@code{match_operand} patterns, those parts may have constraints of 405their own. 406 407@findex match_op_dup 408@item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}]) 409Like @code{match_dup}, except that it applies to operators instead of 410operands. When constructing an insn, operand number @var{n} will be 411substituted at this point. But in matching, @code{match_op_dup} behaves 412differently. It assumes that operand number @var{n} has already been 413determined by a @code{match_operator} appearing earlier in the 414recognition template, and it matches only an identical-looking 415expression. 416 417@findex match_parallel 418@item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}]) 419This pattern is a placeholder for an insn that consists of a 420@code{parallel} expression with a variable number of elements. This 421expression should only appear at the top level of an insn pattern. 422 423When constructing an insn, operand number @var{n} will be substituted at 424this point. When matching an insn, it matches if the body of the insn 425is a @code{parallel} expression with at least as many elements as the 426vector of @var{subpat} expressions in the @code{match_parallel}, if each 427@var{subpat} matches the corresponding element of the @code{parallel}, 428@emph{and} the function @var{predicate} returns nonzero on the 429@code{parallel} that is the body of the insn. It is the responsibility 430of the predicate to validate elements of the @code{parallel} beyond 431those listed in the @code{match_parallel}. 432 433A typical use of @code{match_parallel} is to match load and store 434multiple expressions, which can contain a variable number of elements 435in a @code{parallel}. For example, 436 437@smallexample 438(define_insn "" 439 [(match_parallel 0 "load_multiple_operation" 440 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 441 (match_operand:SI 2 "memory_operand" "m")) 442 (use (reg:SI 179)) 443 (clobber (reg:SI 179))])] 444 "" 445 "loadm 0,0,%1,%2") 446@end smallexample 447 448This example comes from @file{a29k.md}. The function 449@code{load_multiple_operation} is defined in @file{a29k.c} and checks 450that subsequent elements in the @code{parallel} are the same as the 451@code{set} in the pattern, except that they are referencing subsequent 452registers and memory locations. 453 454An insn that matches this pattern might look like: 455 456@smallexample 457(parallel 458 [(set (reg:SI 20) (mem:SI (reg:SI 100))) 459 (use (reg:SI 179)) 460 (clobber (reg:SI 179)) 461 (set (reg:SI 21) 462 (mem:SI (plus:SI (reg:SI 100) 463 (const_int 4)))) 464 (set (reg:SI 22) 465 (mem:SI (plus:SI (reg:SI 100) 466 (const_int 8))))]) 467@end smallexample 468 469@findex match_par_dup 470@item (match_par_dup @var{n} [@var{subpat}@dots{}]) 471Like @code{match_op_dup}, but for @code{match_parallel} instead of 472@code{match_operator}. 473 474@end table 475 476@node Output Template 477@section Output Templates and Operand Substitution 478@cindex output templates 479@cindex operand substitution 480 481@cindex @samp{%} in template 482@cindex percent sign 483The @dfn{output template} is a string which specifies how to output the 484assembler code for an instruction pattern. Most of the template is a 485fixed string which is output literally. The character @samp{%} is used 486to specify where to substitute an operand; it can also be used to 487identify places where different variants of the assembler require 488different syntax. 489 490In the simplest case, a @samp{%} followed by a digit @var{n} says to output 491operand @var{n} at that point in the string. 492 493@samp{%} followed by a letter and a digit says to output an operand in an 494alternate fashion. Four letters have standard, built-in meanings described 495below. The machine description macro @code{PRINT_OPERAND} can define 496additional letters with nonstandard meanings. 497 498@samp{%c@var{digit}} can be used to substitute an operand that is a 499constant value without the syntax that normally indicates an immediate 500operand. 501 502@samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of 503the constant is negated before printing. 504 505@samp{%a@var{digit}} can be used to substitute an operand as if it were a 506memory reference, with the actual operand treated as the address. This may 507be useful when outputting a ``load address'' instruction, because often the 508assembler syntax for such an instruction requires you to write the operand 509as if it were a memory reference. 510 511@samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump 512instruction. 513 514@samp{%=} outputs a number which is unique to each instruction in the 515entire compilation. This is useful for making local labels to be 516referred to more than once in a single template that generates multiple 517assembler instructions. 518 519@samp{%} followed by a punctuation character specifies a substitution that 520does not use an operand. Only one case is standard: @samp{%%} outputs a 521@samp{%} into the assembler code. Other nonstandard cases can be 522defined in the @code{PRINT_OPERAND} macro. You must also define 523which punctuation characters are valid with the 524@code{PRINT_OPERAND_PUNCT_VALID_P} macro. 525 526@cindex \ 527@cindex backslash 528The template may generate multiple assembler instructions. Write the text 529for the instructions, with @samp{\;} between them. 530 531@cindex matching operands 532When the RTL contains two operands which are required by constraint to match 533each other, the output template must refer only to the lower-numbered operand. 534Matching operands are not always identical, and the rest of the compiler 535arranges to put the proper RTL expression for printing into the lower-numbered 536operand. 537 538One use of nonstandard letters or punctuation following @samp{%} is to 539distinguish between different assembler languages for the same machine; for 540example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax 541requires periods in most opcode names, while MIT syntax does not. For 542example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola 543syntax. The same file of patterns is used for both kinds of output syntax, 544but the character sequence @samp{%.} is used in each place where Motorola 545syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax 546defines the sequence to output a period; the macro for MIT syntax defines 547it to do nothing. 548 549@cindex @code{#} in template 550As a special case, a template consisting of the single character @code{#} 551instructs the compiler to first split the insn, and then output the 552resulting instructions separately. This helps eliminate redundancy in the 553output templates. If you have a @code{define_insn} that needs to emit 554multiple assembler instructions, and there is an matching @code{define_split} 555already defined, then you can simply use @code{#} as the output template 556instead of writing an output template that emits the multiple assembler 557instructions. 558 559If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct 560of the form @samp{@{option0|option1|option2@}} in the templates. These 561describe multiple variants of assembler language syntax. 562@xref{Instruction Output}. 563 564@node Output Statement 565@section C Statements for Assembler Output 566@cindex output statements 567@cindex C statements for assembler output 568@cindex generating assembler output 569 570Often a single fixed template string cannot produce correct and efficient 571assembler code for all the cases that are recognized by a single 572instruction pattern. For example, the opcodes may depend on the kinds of 573operands; or some unfortunate combinations of operands may require extra 574machine instructions. 575 576If the output control string starts with a @samp{@@}, then it is actually 577a series of templates, each on a separate line. (Blank lines and 578leading spaces and tabs are ignored.) The templates correspond to the 579pattern's constraint alternatives (@pxref{Multi-Alternative}). For example, 580if a target machine has a two-address add instruction @samp{addr} to add 581into a register and another @samp{addm} to add a register to memory, you 582might write this pattern: 583 584@smallexample 585(define_insn "addsi3" 586 [(set (match_operand:SI 0 "general_operand" "=r,m") 587 (plus:SI (match_operand:SI 1 "general_operand" "0,0") 588 (match_operand:SI 2 "general_operand" "g,r")))] 589 "" 590 "@@ 591 addr %2,%0 592 addm %2,%0") 593@end smallexample 594 595@cindex @code{*} in template 596@cindex asterisk in template 597If the output control string starts with a @samp{*}, then it is not an 598output template but rather a piece of C program that should compute a 599template. It should execute a @code{return} statement to return the 600template-string you want. Most such templates use C string literals, which 601require doublequote characters to delimit them. To include these 602doublequote characters in the string, prefix each one with @samp{\}. 603 604If the output control string is written as a brace block instead of a 605double-quoted string, it is automatically assumed to be C code. In that 606case, it is not necessary to put in a leading asterisk, or to escape the 607doublequotes surrounding C string literals. 608 609The operands may be found in the array @code{operands}, whose C data type 610is @code{rtx []}. 611 612It is very common to select different ways of generating assembler code 613based on whether an immediate operand is within a certain range. Be 614careful when doing this, because the result of @code{INTVAL} is an 615integer on the host machine. If the host machine has more bits in an 616@code{int} than the target machine has in the mode in which the constant 617will be used, then some of the bits you get from @code{INTVAL} will be 618superfluous. For proper results, you must carefully disregard the 619values of those bits. 620 621@findex output_asm_insn 622It is possible to output an assembler instruction and then go on to output 623or compute more of them, using the subroutine @code{output_asm_insn}. This 624receives two arguments: a template-string and a vector of operands. The 625vector may be @code{operands}, or it may be another array of @code{rtx} 626that you declare locally and initialize yourself. 627 628@findex which_alternative 629When an insn pattern has multiple alternatives in its constraints, often 630the appearance of the assembler code is determined mostly by which alternative 631was matched. When this is so, the C code can test the variable 632@code{which_alternative}, which is the ordinal number of the alternative 633that was actually satisfied (0 for the first, 1 for the second alternative, 634etc.). 635 636For example, suppose there are two opcodes for storing zero, @samp{clrreg} 637for registers and @samp{clrmem} for memory locations. Here is how 638a pattern could use @code{which_alternative} to choose between them: 639 640@smallexample 641(define_insn "" 642 [(set (match_operand:SI 0 "general_operand" "=r,m") 643 (const_int 0))] 644 "" 645 @{ 646 return (which_alternative == 0 647 ? "clrreg %0" : "clrmem %0"); 648 @}) 649@end smallexample 650 651The example above, where the assembler code to generate was 652@emph{solely} determined by the alternative, could also have been specified 653as follows, having the output control string start with a @samp{@@}: 654 655@smallexample 656@group 657(define_insn "" 658 [(set (match_operand:SI 0 "general_operand" "=r,m") 659 (const_int 0))] 660 "" 661 "@@ 662 clrreg %0 663 clrmem %0") 664@end group 665@end smallexample 666 667@node Predicates 668@section Predicates 669@cindex predicates 670@cindex operand predicates 671@cindex operator predicates 672 673A predicate determines whether a @code{match_operand} or 674@code{match_operator} expression matches, and therefore whether the 675surrounding instruction pattern will be used for that combination of 676operands. GCC has a number of machine-independent predicates, and you 677can define machine-specific predicates as needed. By convention, 678predicates used with @code{match_operand} have names that end in 679@samp{_operand}, and those used with @code{match_operator} have names 680that end in @samp{_operator}. 681 682All predicates are Boolean functions (in the mathematical sense) of 683two arguments: the RTL expression that is being considered at that 684position in the instruction pattern, and the machine mode that the 685@code{match_operand} or @code{match_operator} specifies. In this 686section, the first argument is called @var{op} and the second argument 687@var{mode}. Predicates can be called from C as ordinary two-argument 688functions; this can be useful in output templates or other 689machine-specific code. 690 691Operand predicates can allow operands that are not actually acceptable 692to the hardware, as long as the constraints give reload the ability to 693fix them up (@pxref{Constraints}). However, GCC will usually generate 694better code if the predicates specify the requirements of the machine 695instructions as closely as possible. Reload cannot fix up operands 696that must be constants (``immediate operands''); you must use a 697predicate that allows only constants, or else enforce the requirement 698in the extra condition. 699 700@cindex predicates and machine modes 701@cindex normal predicates 702@cindex special predicates 703Most predicates handle their @var{mode} argument in a uniform manner. 704If @var{mode} is @code{VOIDmode} (unspecified), then @var{op} can have 705any mode. If @var{mode} is anything else, then @var{op} must have the 706same mode, unless @var{op} is a @code{CONST_INT} or integer 707@code{CONST_DOUBLE}. These RTL expressions always have 708@code{VOIDmode}, so it would be counterproductive to check that their 709mode matches. Instead, predicates that accept @code{CONST_INT} and/or 710integer @code{CONST_DOUBLE} check that the value stored in the 711constant will fit in the requested mode. 712 713Predicates with this behavior are called @dfn{normal}. 714@command{genrecog} can optimize the instruction recognizer based on 715knowledge of how normal predicates treat modes. It can also diagnose 716certain kinds of common errors in the use of normal predicates; for 717instance, it is almost always an error to use a normal predicate 718without specifying a mode. 719 720Predicates that do something different with their @var{mode} argument 721are called @dfn{special}. The generic predicates 722@code{address_operand} and @code{pmode_register_operand} are special 723predicates. @command{genrecog} does not do any optimizations or 724diagnosis when special predicates are used. 725 726@menu 727* Machine-Independent Predicates:: Predicates available to all back ends. 728* Defining Predicates:: How to write machine-specific predicate 729 functions. 730@end menu 731 732@node Machine-Independent Predicates 733@subsection Machine-Independent Predicates 734@cindex machine-independent predicates 735@cindex generic predicates 736 737These are the generic predicates available to all back ends. They are 738defined in @file{recog.c}. The first category of predicates allow 739only constant, or @dfn{immediate}, operands. 740 741@defun immediate_operand 742This predicate allows any sort of constant that fits in @var{mode}. 743It is an appropriate choice for instructions that take operands that 744must be constant. 745@end defun 746 747@defun const_int_operand 748This predicate allows any @code{CONST_INT} expression that fits in 749@var{mode}. It is an appropriate choice for an immediate operand that 750does not allow a symbol or label. 751@end defun 752 753@defun const_double_operand 754This predicate accepts any @code{CONST_DOUBLE} expression that has 755exactly @var{mode}. If @var{mode} is @code{VOIDmode}, it will also 756accept @code{CONST_INT}. It is intended for immediate floating point 757constants. 758@end defun 759 760@noindent 761The second category of predicates allow only some kind of machine 762register. 763 764@defun register_operand 765This predicate allows any @code{REG} or @code{SUBREG} expression that 766is valid for @var{mode}. It is often suitable for arithmetic 767instruction operands on a RISC machine. 768@end defun 769 770@defun pmode_register_operand 771This is a slight variant on @code{register_operand} which works around 772a limitation in the machine-description reader. 773 774@smallexample 775(match_operand @var{n} "pmode_register_operand" @var{constraint}) 776@end smallexample 777 778@noindent 779means exactly what 780 781@smallexample 782(match_operand:P @var{n} "register_operand" @var{constraint}) 783@end smallexample 784 785@noindent 786would mean, if the machine-description reader accepted @samp{:P} 787mode suffixes. Unfortunately, it cannot, because @code{Pmode} is an 788alias for some other mode, and might vary with machine-specific 789options. @xref{Misc}. 790@end defun 791 792@defun scratch_operand 793This predicate allows hard registers and @code{SCRATCH} expressions, 794but not pseudo-registers. It is used internally by @code{match_scratch}; 795it should not be used directly. 796@end defun 797 798@noindent 799The third category of predicates allow only some kind of memory reference. 800 801@defun memory_operand 802This predicate allows any valid reference to a quantity of mode 803@var{mode} in memory, as determined by the weak form of 804@code{GO_IF_LEGITIMATE_ADDRESS} (@pxref{Addressing Modes}). 805@end defun 806 807@defun address_operand 808This predicate is a little unusual; it allows any operand that is a 809valid expression for the @emph{address} of a quantity of mode 810@var{mode}, again determined by the weak form of 811@code{GO_IF_LEGITIMATE_ADDRESS}. To first order, if 812@samp{@w{(mem:@var{mode} (@var{exp}))}} is acceptable to 813@code{memory_operand}, then @var{exp} is acceptable to 814@code{address_operand}. Note that @var{exp} does not necessarily have 815the mode @var{mode}. 816@end defun 817 818@defun indirect_operand 819This is a stricter form of @code{memory_operand} which allows only 820memory references with a @code{general_operand} as the address 821expression. New uses of this predicate are discouraged, because 822@code{general_operand} is very permissive, so it's hard to tell what 823an @code{indirect_operand} does or does not allow. If a target has 824different requirements for memory operands for different instructions, 825it is better to define target-specific predicates which enforce the 826hardware's requirements explicitly. 827@end defun 828 829@defun push_operand 830This predicate allows a memory reference suitable for pushing a value 831onto the stack. This will be a @code{MEM} which refers to 832@code{stack_pointer_rtx}, with a side-effect in its address expression 833(@pxref{Incdec}); which one is determined by the 834@code{STACK_PUSH_CODE} macro (@pxref{Frame Layout}). 835@end defun 836 837@defun pop_operand 838This predicate allows a memory reference suitable for popping a value 839off the stack. Again, this will be a @code{MEM} referring to 840@code{stack_pointer_rtx}, with a side-effect in its address 841expression. However, this time @code{STACK_POP_CODE} is expected. 842@end defun 843 844@noindent 845The fourth category of predicates allow some combination of the above 846operands. 847 848@defun nonmemory_operand 849This predicate allows any immediate or register operand valid for @var{mode}. 850@end defun 851 852@defun nonimmediate_operand 853This predicate allows any register or memory operand valid for @var{mode}. 854@end defun 855 856@defun general_operand 857This predicate allows any immediate, register, or memory operand 858valid for @var{mode}. 859@end defun 860 861@noindent 862Finally, there is one generic operator predicate. 863 864@defun comparison_operator 865This predicate matches any expression which performs an arithmetic 866comparison in @var{mode}; that is, @code{COMPARISON_P} is true for the 867expression code. 868@end defun 869 870@node Defining Predicates 871@subsection Defining Machine-Specific Predicates 872@cindex defining predicates 873@findex define_predicate 874@findex define_special_predicate 875 876Many machines have requirements for their operands that cannot be 877expressed precisely using the generic predicates. You can define 878additional predicates using @code{define_predicate} and 879@code{define_special_predicate} expressions. These expressions have 880three operands: 881 882@itemize @bullet 883@item 884The name of the predicate, as it will be referred to in 885@code{match_operand} or @code{match_operator} expressions. 886 887@item 888An RTL expression which evaluates to true if the predicate allows the 889operand @var{op}, false if it does not. This expression can only use 890the following RTL codes: 891 892@table @code 893@item MATCH_OPERAND 894When written inside a predicate expression, a @code{MATCH_OPERAND} 895expression evaluates to true if the predicate it names would allow 896@var{op}. The operand number and constraint are ignored. Due to 897limitations in @command{genrecog}, you can only refer to generic 898predicates and predicates that have already been defined. 899 900@item MATCH_CODE 901This expression evaluates to true if @var{op} or a specified 902subexpression of @var{op} has one of a given list of RTX codes. 903 904The first operand of this expression is a string constant containing a 905comma-separated list of RTX code names (in lower case). These are the 906codes for which the @code{MATCH_CODE} will be true. 907 908The second operand is a string constant which indicates what 909subexpression of @var{op} to examine. If it is absent or the empty 910string, @var{op} itself is examined. Otherwise, the string constant 911must be a sequence of digits and/or lowercase letters. Each character 912indicates a subexpression to extract from the current expression; for 913the first character this is @var{op}, for the second and subsequent 914characters it is the result of the previous character. A digit 915@var{n} extracts @samp{@w{XEXP (@var{e}, @var{n})}}; a letter @var{l} 916extracts @samp{@w{XVECEXP (@var{e}, 0, @var{n})}} where @var{n} is the 917alphabetic ordinal of @var{l} (0 for `a', 1 for 'b', and so on). The 918@code{MATCH_CODE} then examines the RTX code of the subexpression 919extracted by the complete string. It is not possible to extract 920components of an @code{rtvec} that is not at position 0 within its RTX 921object. 922 923@item MATCH_TEST 924This expression has one operand, a string constant containing a C 925expression. The predicate's arguments, @var{op} and @var{mode}, are 926available with those names in the C expression. The @code{MATCH_TEST} 927evaluates to true if the C expression evaluates to a nonzero value. 928@code{MATCH_TEST} expressions must not have side effects. 929 930@item AND 931@itemx IOR 932@itemx NOT 933@itemx IF_THEN_ELSE 934The basic @samp{MATCH_} expressions can be combined using these 935logical operators, which have the semantics of the C operators 936@samp{&&}, @samp{||}, @samp{!}, and @samp{@w{? :}} respectively. As 937in Common Lisp, you may give an @code{AND} or @code{IOR} expression an 938arbitrary number of arguments; this has exactly the same effect as 939writing a chain of two-argument @code{AND} or @code{IOR} expressions. 940@end table 941 942@item 943An optional block of C code, which should execute 944@samp{@w{return true}} if the predicate is found to match and 945@samp{@w{return false}} if it does not. It must not have any side 946effects. The predicate arguments, @var{op} and @var{mode}, are 947available with those names. 948 949If a code block is present in a predicate definition, then the RTL 950expression must evaluate to true @emph{and} the code block must 951execute @samp{@w{return true}} for the predicate to allow the operand. 952The RTL expression is evaluated first; do not re-check anything in the 953code block that was checked in the RTL expression. 954@end itemize 955 956The program @command{genrecog} scans @code{define_predicate} and 957@code{define_special_predicate} expressions to determine which RTX 958codes are possibly allowed. You should always make this explicit in 959the RTL predicate expression, using @code{MATCH_OPERAND} and 960@code{MATCH_CODE}. 961 962Here is an example of a simple predicate definition, from the IA64 963machine description: 964 965@smallexample 966@group 967;; @r{True if @var{op} is a @code{SYMBOL_REF} which refers to the sdata section.} 968(define_predicate "small_addr_symbolic_operand" 969 (and (match_code "symbol_ref") 970 (match_test "SYMBOL_REF_SMALL_ADDR_P (op)"))) 971@end group 972@end smallexample 973 974@noindent 975And here is another, showing the use of the C block. 976 977@smallexample 978@group 979;; @r{True if @var{op} is a register operand that is (or could be) a GR reg.} 980(define_predicate "gr_register_operand" 981 (match_operand 0 "register_operand") 982@{ 983 unsigned int regno; 984 if (GET_CODE (op) == SUBREG) 985 op = SUBREG_REG (op); 986 987 regno = REGNO (op); 988 return (regno >= FIRST_PSEUDO_REGISTER || GENERAL_REGNO_P (regno)); 989@}) 990@end group 991@end smallexample 992 993Predicates written with @code{define_predicate} automatically include 994a test that @var{mode} is @code{VOIDmode}, or @var{op} has the same 995mode as @var{mode}, or @var{op} is a @code{CONST_INT} or 996@code{CONST_DOUBLE}. They do @emph{not} check specifically for 997integer @code{CONST_DOUBLE}, nor do they test that the value of either 998kind of constant fits in the requested mode. This is because 999target-specific predicates that take constants usually have to do more 1000stringent value checks anyway. If you need the exact same treatment 1001of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic predicates 1002provide, use a @code{MATCH_OPERAND} subexpression to call 1003@code{const_int_operand}, @code{const_double_operand}, or 1004@code{immediate_operand}. 1005 1006Predicates written with @code{define_special_predicate} do not get any 1007automatic mode checks, and are treated as having special mode handling 1008by @command{genrecog}. 1009 1010The program @command{genpreds} is responsible for generating code to 1011test predicates. It also writes a header file containing function 1012declarations for all machine-specific predicates. It is not necessary 1013to declare these predicates in @file{@var{cpu}-protos.h}. 1014@end ifset 1015 1016@c Most of this node appears by itself (in a different place) even 1017@c when the INTERNALS flag is clear. Passages that require the internals 1018@c manual's context are conditionalized to appear only in the internals manual. 1019@ifset INTERNALS 1020@node Constraints 1021@section Operand Constraints 1022@cindex operand constraints 1023@cindex constraints 1024 1025Each @code{match_operand} in an instruction pattern can specify 1026constraints for the operands allowed. The constraints allow you to 1027fine-tune matching within the set of operands allowed by the 1028predicate. 1029 1030@end ifset 1031@ifclear INTERNALS 1032@node Constraints 1033@section Constraints for @code{asm} Operands 1034@cindex operand constraints, @code{asm} 1035@cindex constraints, @code{asm} 1036@cindex @code{asm} constraints 1037 1038Here are specific details on what constraint letters you can use with 1039@code{asm} operands. 1040@end ifclear 1041Constraints can say whether 1042an operand may be in a register, and which kinds of register; whether the 1043operand can be a memory reference, and which kinds of address; whether the 1044operand may be an immediate constant, and which possible values it may 1045have. Constraints can also require two operands to match. 1046 1047@ifset INTERNALS 1048@menu 1049* Simple Constraints:: Basic use of constraints. 1050* Multi-Alternative:: When an insn has two alternative constraint-patterns. 1051* Class Preferences:: Constraints guide which hard register to put things in. 1052* Modifiers:: More precise control over effects of constraints. 1053* Machine Constraints:: Existing constraints for some particular machines. 1054* Define Constraints:: How to define machine-specific constraints. 1055* C Constraint Interface:: How to test constraints from C code. 1056@end menu 1057@end ifset 1058 1059@ifclear INTERNALS 1060@menu 1061* Simple Constraints:: Basic use of constraints. 1062* Multi-Alternative:: When an insn has two alternative constraint-patterns. 1063* Modifiers:: More precise control over effects of constraints. 1064* Machine Constraints:: Special constraints for some particular machines. 1065@end menu 1066@end ifclear 1067 1068@node Simple Constraints 1069@subsection Simple Constraints 1070@cindex simple constraints 1071 1072The simplest kind of constraint is a string full of letters, each of 1073which describes one kind of operand that is permitted. Here are 1074the letters that are allowed: 1075 1076@table @asis 1077@item whitespace 1078Whitespace characters are ignored and can be inserted at any position 1079except the first. This enables each alternative for different operands to 1080be visually aligned in the machine description even if they have different 1081number of constraints and modifiers. 1082 1083@cindex @samp{m} in constraint 1084@cindex memory references in constraints 1085@item @samp{m} 1086A memory operand is allowed, with any kind of address that the machine 1087supports in general. 1088 1089@cindex offsettable address 1090@cindex @samp{o} in constraint 1091@item @samp{o} 1092A memory operand is allowed, but only if the address is 1093@dfn{offsettable}. This means that adding a small integer (actually, 1094the width in bytes of the operand, as determined by its machine mode) 1095may be added to the address and the result is also a valid memory 1096address. 1097 1098@cindex autoincrement/decrement addressing 1099For example, an address which is constant is offsettable; so is an 1100address that is the sum of a register and a constant (as long as a 1101slightly larger constant is also within the range of address-offsets 1102supported by the machine); but an autoincrement or autodecrement 1103address is not offsettable. More complicated indirect/indexed 1104addresses may or may not be offsettable depending on the other 1105addressing modes that the machine supports. 1106 1107Note that in an output operand which can be matched by another 1108operand, the constraint letter @samp{o} is valid only when accompanied 1109by both @samp{<} (if the target machine has predecrement addressing) 1110and @samp{>} (if the target machine has preincrement addressing). 1111 1112@cindex @samp{V} in constraint 1113@item @samp{V} 1114A memory operand that is not offsettable. In other words, anything that 1115would fit the @samp{m} constraint but not the @samp{o} constraint. 1116 1117@cindex @samp{<} in constraint 1118@item @samp{<} 1119A memory operand with autodecrement addressing (either predecrement or 1120postdecrement) is allowed. 1121 1122@cindex @samp{>} in constraint 1123@item @samp{>} 1124A memory operand with autoincrement addressing (either preincrement or 1125postincrement) is allowed. 1126 1127@cindex @samp{r} in constraint 1128@cindex registers in constraints 1129@item @samp{r} 1130A register operand is allowed provided that it is in a general 1131register. 1132 1133@cindex constants in constraints 1134@cindex @samp{i} in constraint 1135@item @samp{i} 1136An immediate integer operand (one with constant value) is allowed. 1137This includes symbolic constants whose values will be known only at 1138assembly time or later. 1139 1140@cindex @samp{n} in constraint 1141@item @samp{n} 1142An immediate integer operand with a known numeric value is allowed. 1143Many systems cannot support assembly-time constants for operands less 1144than a word wide. Constraints for these operands should use @samp{n} 1145rather than @samp{i}. 1146 1147@cindex @samp{I} in constraint 1148@item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P} 1149Other letters in the range @samp{I} through @samp{P} may be defined in 1150a machine-dependent fashion to permit immediate integer operands with 1151explicit integer values in specified ranges. For example, on the 115268000, @samp{I} is defined to stand for the range of values 1 to 8. 1153This is the range permitted as a shift count in the shift 1154instructions. 1155 1156@cindex @samp{E} in constraint 1157@item @samp{E} 1158An immediate floating operand (expression code @code{const_double}) is 1159allowed, but only if the target floating point format is the same as 1160that of the host machine (on which the compiler is running). 1161 1162@cindex @samp{F} in constraint 1163@item @samp{F} 1164An immediate floating operand (expression code @code{const_double} or 1165@code{const_vector}) is allowed. 1166 1167@cindex @samp{G} in constraint 1168@cindex @samp{H} in constraint 1169@item @samp{G}, @samp{H} 1170@samp{G} and @samp{H} may be defined in a machine-dependent fashion to 1171permit immediate floating operands in particular ranges of values. 1172 1173@cindex @samp{s} in constraint 1174@item @samp{s} 1175An immediate integer operand whose value is not an explicit integer is 1176allowed. 1177 1178This might appear strange; if an insn allows a constant operand with a 1179value not known at compile time, it certainly must allow any known 1180value. So why use @samp{s} instead of @samp{i}? Sometimes it allows 1181better code to be generated. 1182 1183For example, on the 68000 in a fullword instruction it is possible to 1184use an immediate operand; but if the immediate value is between @minus{}128 1185and 127, better code results from loading the value into a register and 1186using the register. This is because the load into the register can be 1187done with a @samp{moveq} instruction. We arrange for this to happen 1188by defining the letter @samp{K} to mean ``any integer outside the 1189range @minus{}128 to 127'', and then specifying @samp{Ks} in the operand 1190constraints. 1191 1192@cindex @samp{g} in constraint 1193@item @samp{g} 1194Any register, memory or immediate integer operand is allowed, except for 1195registers that are not general registers. 1196 1197@cindex @samp{X} in constraint 1198@item @samp{X} 1199@ifset INTERNALS 1200Any operand whatsoever is allowed, even if it does not satisfy 1201@code{general_operand}. This is normally used in the constraint of 1202a @code{match_scratch} when certain alternatives will not actually 1203require a scratch register. 1204@end ifset 1205@ifclear INTERNALS 1206Any operand whatsoever is allowed. 1207@end ifclear 1208 1209@cindex @samp{0} in constraint 1210@cindex digits in constraint 1211@item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{9} 1212An operand that matches the specified operand number is allowed. If a 1213digit is used together with letters within the same alternative, the 1214digit should come last. 1215 1216This number is allowed to be more than a single digit. If multiple 1217digits are encountered consecutively, they are interpreted as a single 1218decimal integer. There is scant chance for ambiguity, since to-date 1219it has never been desirable that @samp{10} be interpreted as matching 1220either operand 1 @emph{or} operand 0. Should this be desired, one 1221can use multiple alternatives instead. 1222 1223@cindex matching constraint 1224@cindex constraint, matching 1225This is called a @dfn{matching constraint} and what it really means is 1226that the assembler has only a single operand that fills two roles 1227@ifset INTERNALS 1228considered separate in the RTL insn. For example, an add insn has two 1229input operands and one output operand in the RTL, but on most CISC 1230@end ifset 1231@ifclear INTERNALS 1232which @code{asm} distinguishes. For example, an add instruction uses 1233two input operands and an output operand, but on most CISC 1234@end ifclear 1235machines an add instruction really has only two operands, one of them an 1236input-output operand: 1237 1238@smallexample 1239addl #35,r12 1240@end smallexample 1241 1242Matching constraints are used in these circumstances. 1243More precisely, the two operands that match must include one input-only 1244operand and one output-only operand. Moreover, the digit must be a 1245smaller number than the number of the operand that uses it in the 1246constraint. 1247 1248@ifset INTERNALS 1249For operands to match in a particular case usually means that they 1250are identical-looking RTL expressions. But in a few special cases 1251specific kinds of dissimilarity are allowed. For example, @code{*x} 1252as an input operand will match @code{*x++} as an output operand. 1253For proper results in such cases, the output template should always 1254use the output-operand's number when printing the operand. 1255@end ifset 1256 1257@cindex load address instruction 1258@cindex push address instruction 1259@cindex address constraints 1260@cindex @samp{p} in constraint 1261@item @samp{p} 1262An operand that is a valid memory address is allowed. This is 1263for ``load address'' and ``push address'' instructions. 1264 1265@findex address_operand 1266@samp{p} in the constraint must be accompanied by @code{address_operand} 1267as the predicate in the @code{match_operand}. This predicate interprets 1268the mode specified in the @code{match_operand} as the mode of the memory 1269reference for which the address would be valid. 1270 1271@cindex other register constraints 1272@cindex extensible constraints 1273@item @var{other-letters} 1274Other letters can be defined in machine-dependent fashion to stand for 1275particular classes of registers or other arbitrary operand types. 1276@samp{d}, @samp{a} and @samp{f} are defined on the 68000/68020 to stand 1277for data, address and floating point registers. 1278@end table 1279 1280@ifset INTERNALS 1281In order to have valid assembler code, each operand must satisfy 1282its constraint. But a failure to do so does not prevent the pattern 1283from applying to an insn. Instead, it directs the compiler to modify 1284the code so that the constraint will be satisfied. Usually this is 1285done by copying an operand into a register. 1286 1287Contrast, therefore, the two instruction patterns that follow: 1288 1289@smallexample 1290(define_insn "" 1291 [(set (match_operand:SI 0 "general_operand" "=r") 1292 (plus:SI (match_dup 0) 1293 (match_operand:SI 1 "general_operand" "r")))] 1294 "" 1295 "@dots{}") 1296@end smallexample 1297 1298@noindent 1299which has two operands, one of which must appear in two places, and 1300 1301@smallexample 1302(define_insn "" 1303 [(set (match_operand:SI 0 "general_operand" "=r") 1304 (plus:SI (match_operand:SI 1 "general_operand" "0") 1305 (match_operand:SI 2 "general_operand" "r")))] 1306 "" 1307 "@dots{}") 1308@end smallexample 1309 1310@noindent 1311which has three operands, two of which are required by a constraint to be 1312identical. If we are considering an insn of the form 1313 1314@smallexample 1315(insn @var{n} @var{prev} @var{next} 1316 (set (reg:SI 3) 1317 (plus:SI (reg:SI 6) (reg:SI 109))) 1318 @dots{}) 1319@end smallexample 1320 1321@noindent 1322the first pattern would not apply at all, because this insn does not 1323contain two identical subexpressions in the right place. The pattern would 1324say, ``That does not look like an add instruction; try other patterns''. 1325The second pattern would say, ``Yes, that's an add instruction, but there 1326is something wrong with it''. It would direct the reload pass of the 1327compiler to generate additional insns to make the constraint true. The 1328results might look like this: 1329 1330@smallexample 1331(insn @var{n2} @var{prev} @var{n} 1332 (set (reg:SI 3) (reg:SI 6)) 1333 @dots{}) 1334 1335(insn @var{n} @var{n2} @var{next} 1336 (set (reg:SI 3) 1337 (plus:SI (reg:SI 3) (reg:SI 109))) 1338 @dots{}) 1339@end smallexample 1340 1341It is up to you to make sure that each operand, in each pattern, has 1342constraints that can handle any RTL expression that could be present for 1343that operand. (When multiple alternatives are in use, each pattern must, 1344for each possible combination of operand expressions, have at least one 1345alternative which can handle that combination of operands.) The 1346constraints don't need to @emph{allow} any possible operand---when this is 1347the case, they do not constrain---but they must at least point the way to 1348reloading any possible operand so that it will fit. 1349 1350@itemize @bullet 1351@item 1352If the constraint accepts whatever operands the predicate permits, 1353there is no problem: reloading is never necessary for this operand. 1354 1355For example, an operand whose constraints permit everything except 1356registers is safe provided its predicate rejects registers. 1357 1358An operand whose predicate accepts only constant values is safe 1359provided its constraints include the letter @samp{i}. If any possible 1360constant value is accepted, then nothing less than @samp{i} will do; 1361if the predicate is more selective, then the constraints may also be 1362more selective. 1363 1364@item 1365Any operand expression can be reloaded by copying it into a register. 1366So if an operand's constraints allow some kind of register, it is 1367certain to be safe. It need not permit all classes of registers; the 1368compiler knows how to copy a register into another register of the 1369proper class in order to make an instruction valid. 1370 1371@cindex nonoffsettable memory reference 1372@cindex memory reference, nonoffsettable 1373@item 1374A nonoffsettable memory reference can be reloaded by copying the 1375address into a register. So if the constraint uses the letter 1376@samp{o}, all memory references are taken care of. 1377 1378@item 1379A constant operand can be reloaded by allocating space in memory to 1380hold it as preinitialized data. Then the memory reference can be used 1381in place of the constant. So if the constraint uses the letters 1382@samp{o} or @samp{m}, constant operands are not a problem. 1383 1384@item 1385If the constraint permits a constant and a pseudo register used in an insn 1386was not allocated to a hard register and is equivalent to a constant, 1387the register will be replaced with the constant. If the predicate does 1388not permit a constant and the insn is re-recognized for some reason, the 1389compiler will crash. Thus the predicate must always recognize any 1390objects allowed by the constraint. 1391@end itemize 1392 1393If the operand's predicate can recognize registers, but the constraint does 1394not permit them, it can make the compiler crash. When this operand happens 1395to be a register, the reload pass will be stymied, because it does not know 1396how to copy a register temporarily into memory. 1397 1398If the predicate accepts a unary operator, the constraint applies to the 1399operand. For example, the MIPS processor at ISA level 3 supports an 1400instruction which adds two registers in @code{SImode} to produce a 1401@code{DImode} result, but only if the registers are correctly sign 1402extended. This predicate for the input operands accepts a 1403@code{sign_extend} of an @code{SImode} register. Write the constraint 1404to indicate the type of register that is required for the operand of the 1405@code{sign_extend}. 1406@end ifset 1407 1408@node Multi-Alternative 1409@subsection Multiple Alternative Constraints 1410@cindex multiple alternative constraints 1411 1412Sometimes a single instruction has multiple alternative sets of possible 1413operands. For example, on the 68000, a logical-or instruction can combine 1414register or an immediate value into memory, or it can combine any kind of 1415operand into a register; but it cannot combine one memory location into 1416another. 1417 1418These constraints are represented as multiple alternatives. An alternative 1419can be described by a series of letters for each operand. The overall 1420constraint for an operand is made from the letters for this operand 1421from the first alternative, a comma, the letters for this operand from 1422the second alternative, a comma, and so on until the last alternative. 1423@ifset INTERNALS 1424Here is how it is done for fullword logical-or on the 68000: 1425 1426@smallexample 1427(define_insn "iorsi3" 1428 [(set (match_operand:SI 0 "general_operand" "=m,d") 1429 (ior:SI (match_operand:SI 1 "general_operand" "%0,0") 1430 (match_operand:SI 2 "general_operand" "dKs,dmKs")))] 1431 @dots{}) 1432@end smallexample 1433 1434The first alternative has @samp{m} (memory) for operand 0, @samp{0} for 1435operand 1 (meaning it must match operand 0), and @samp{dKs} for operand 14362. The second alternative has @samp{d} (data register) for operand 0, 1437@samp{0} for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and 1438@samp{%} in the constraints apply to all the alternatives; their 1439meaning is explained in the next section (@pxref{Class Preferences}). 1440@end ifset 1441 1442@c FIXME Is this ? and ! stuff of use in asm()? If not, hide unless INTERNAL 1443If all the operands fit any one alternative, the instruction is valid. 1444Otherwise, for each alternative, the compiler counts how many instructions 1445must be added to copy the operands so that that alternative applies. 1446The alternative requiring the least copying is chosen. If two alternatives 1447need the same amount of copying, the one that comes first is chosen. 1448These choices can be altered with the @samp{?} and @samp{!} characters: 1449 1450@table @code 1451@cindex @samp{?} in constraint 1452@cindex question mark 1453@item ? 1454Disparage slightly the alternative that the @samp{?} appears in, 1455as a choice when no alternative applies exactly. The compiler regards 1456this alternative as one unit more costly for each @samp{?} that appears 1457in it. 1458 1459@cindex @samp{!} in constraint 1460@cindex exclamation point 1461@item ! 1462Disparage severely the alternative that the @samp{!} appears in. 1463This alternative can still be used if it fits without reloading, 1464but if reloading is needed, some other alternative will be used. 1465@end table 1466 1467@ifset INTERNALS 1468When an insn pattern has multiple alternatives in its constraints, often 1469the appearance of the assembler code is determined mostly by which 1470alternative was matched. When this is so, the C code for writing the 1471assembler code can use the variable @code{which_alternative}, which is 1472the ordinal number of the alternative that was actually satisfied (0 for 1473the first, 1 for the second alternative, etc.). @xref{Output Statement}. 1474@end ifset 1475 1476@ifset INTERNALS 1477@node Class Preferences 1478@subsection Register Class Preferences 1479@cindex class preference constraints 1480@cindex register class preference constraints 1481 1482@cindex voting between constraint alternatives 1483The operand constraints have another function: they enable the compiler 1484to decide which kind of hardware register a pseudo register is best 1485allocated to. The compiler examines the constraints that apply to the 1486insns that use the pseudo register, looking for the machine-dependent 1487letters such as @samp{d} and @samp{a} that specify classes of registers. 1488The pseudo register is put in whichever class gets the most ``votes''. 1489The constraint letters @samp{g} and @samp{r} also vote: they vote in 1490favor of a general register. The machine description says which registers 1491are considered general. 1492 1493Of course, on some machines all registers are equivalent, and no register 1494classes are defined. Then none of this complexity is relevant. 1495@end ifset 1496 1497@node Modifiers 1498@subsection Constraint Modifier Characters 1499@cindex modifiers in constraints 1500@cindex constraint modifier characters 1501 1502@c prevent bad page break with this line 1503Here are constraint modifier characters. 1504 1505@table @samp 1506@cindex @samp{=} in constraint 1507@item = 1508Means that this operand is write-only for this instruction: the previous 1509value is discarded and replaced by output data. 1510 1511@cindex @samp{+} in constraint 1512@item + 1513Means that this operand is both read and written by the instruction. 1514 1515When the compiler fixes up the operands to satisfy the constraints, 1516it needs to know which operands are inputs to the instruction and 1517which are outputs from it. @samp{=} identifies an output; @samp{+} 1518identifies an operand that is both input and output; all other operands 1519are assumed to be input only. 1520 1521If you specify @samp{=} or @samp{+} in a constraint, you put it in the 1522first character of the constraint string. 1523 1524@cindex @samp{&} in constraint 1525@cindex earlyclobber operand 1526@item & 1527Means (in a particular alternative) that this operand is an 1528@dfn{earlyclobber} operand, which is modified before the instruction is 1529finished using the input operands. Therefore, this operand may not lie 1530in a register that is used as an input operand or as part of any memory 1531address. 1532 1533@samp{&} applies only to the alternative in which it is written. In 1534constraints with multiple alternatives, sometimes one alternative 1535requires @samp{&} while others do not. See, for example, the 1536@samp{movdf} insn of the 68000. 1537 1538An input operand can be tied to an earlyclobber operand if its only 1539use as an input occurs before the early result is written. Adding 1540alternatives of this form often allows GCC to produce better code 1541when only some of the inputs can be affected by the earlyclobber. 1542See, for example, the @samp{mulsi3} insn of the ARM@. 1543 1544@samp{&} does not obviate the need to write @samp{=}. 1545 1546@cindex @samp{%} in constraint 1547@item % 1548Declares the instruction to be commutative for this operand and the 1549following operand. This means that the compiler may interchange the 1550two operands if that is the cheapest way to make all operands fit the 1551constraints. 1552@ifset INTERNALS 1553This is often used in patterns for addition instructions 1554that really have only two operands: the result must go in one of the 1555arguments. Here for example, is how the 68000 halfword-add 1556instruction is defined: 1557 1558@smallexample 1559(define_insn "addhi3" 1560 [(set (match_operand:HI 0 "general_operand" "=m,r") 1561 (plus:HI (match_operand:HI 1 "general_operand" "%0,0") 1562 (match_operand:HI 2 "general_operand" "di,g")))] 1563 @dots{}) 1564@end smallexample 1565@end ifset 1566GCC can only handle one commutative pair in an asm; if you use more, 1567the compiler may fail. Note that you need not use the modifier if 1568the two alternatives are strictly identical; this would only waste 1569time in the reload pass. The modifier is not operational after 1570register allocation, so the result of @code{define_peephole2} 1571and @code{define_split}s performed after reload cannot rely on 1572@samp{%} to make the intended insn match. 1573 1574@cindex @samp{#} in constraint 1575@item # 1576Says that all following characters, up to the next comma, are to be 1577ignored as a constraint. They are significant only for choosing 1578register preferences. 1579 1580@cindex @samp{*} in constraint 1581@item * 1582Says that the following character should be ignored when choosing 1583register preferences. @samp{*} has no effect on the meaning of the 1584constraint as a constraint, and no effect on reloading. 1585 1586@ifset INTERNALS 1587Here is an example: the 68000 has an instruction to sign-extend a 1588halfword in a data register, and can also sign-extend a value by 1589copying it into an address register. While either kind of register is 1590acceptable, the constraints on an address-register destination are 1591less strict, so it is best if register allocation makes an address 1592register its goal. Therefore, @samp{*} is used so that the @samp{d} 1593constraint letter (for data register) is ignored when computing 1594register preferences. 1595 1596@smallexample 1597(define_insn "extendhisi2" 1598 [(set (match_operand:SI 0 "general_operand" "=*d,a") 1599 (sign_extend:SI 1600 (match_operand:HI 1 "general_operand" "0,g")))] 1601 @dots{}) 1602@end smallexample 1603@end ifset 1604@end table 1605 1606@node Machine Constraints 1607@subsection Constraints for Particular Machines 1608@cindex machine specific constraints 1609@cindex constraints, machine specific 1610 1611Whenever possible, you should use the general-purpose constraint letters 1612in @code{asm} arguments, since they will convey meaning more readily to 1613people reading your code. Failing that, use the constraint letters 1614that usually have very similar meanings across architectures. The most 1615commonly used constraints are @samp{m} and @samp{r} (for memory and 1616general-purpose registers respectively; @pxref{Simple Constraints}), and 1617@samp{I}, usually the letter indicating the most common 1618immediate-constant format. 1619 1620Each architecture defines additional constraints. These constraints 1621are used by the compiler itself for instruction generation, as well as 1622for @code{asm} statements; therefore, some of the constraints are not 1623particularly useful for @code{asm}. Here is a summary of some of the 1624machine-dependent constraints available on some particular machines; 1625it includes both constraints that are useful for @code{asm} and 1626constraints that aren't. The compiler source file mentioned in the 1627table heading for each architecture is the definitive reference for 1628the meanings of that architecture's constraints. 1629 1630@table @emph 1631@item ARM family---@file{config/arm/arm.h} 1632@table @code 1633@item f 1634Floating-point register 1635 1636@item w 1637VFP floating-point register 1638 1639@item F 1640One of the floating-point constants 0.0, 0.5, 1.0, 2.0, 3.0, 4.0, 5.0 1641or 10.0 1642 1643@item G 1644Floating-point constant that would satisfy the constraint @samp{F} if it 1645were negated 1646 1647@item I 1648Integer that is valid as an immediate operand in a data processing 1649instruction. That is, an integer in the range 0 to 255 rotated by a 1650multiple of 2 1651 1652@item J 1653Integer in the range @minus{}4095 to 4095 1654 1655@item K 1656Integer that satisfies constraint @samp{I} when inverted (ones complement) 1657 1658@item L 1659Integer that satisfies constraint @samp{I} when negated (twos complement) 1660 1661@item M 1662Integer in the range 0 to 32 1663 1664@item Q 1665A memory reference where the exact address is in a single register 1666(`@samp{m}' is preferable for @code{asm} statements) 1667 1668@item R 1669An item in the constant pool 1670 1671@item S 1672A symbol in the text segment of the current file 1673 1674@item Uv 1675A memory reference suitable for VFP load/store insns (reg+constant offset) 1676 1677@item Uy 1678A memory reference suitable for iWMMXt load/store instructions. 1679 1680@item Uq 1681A memory reference suitable for the ARMv4 ldrsb instruction. 1682@end table 1683 1684@item AVR family---@file{config/avr/constraints.md} 1685@table @code 1686@item l 1687Registers from r0 to r15 1688 1689@item a 1690Registers from r16 to r23 1691 1692@item d 1693Registers from r16 to r31 1694 1695@item w 1696Registers from r24 to r31. These registers can be used in @samp{adiw} command 1697 1698@item e 1699Pointer register (r26--r31) 1700 1701@item b 1702Base pointer register (r28--r31) 1703 1704@item q 1705Stack pointer register (SPH:SPL) 1706 1707@item t 1708Temporary register r0 1709 1710@item x 1711Register pair X (r27:r26) 1712 1713@item y 1714Register pair Y (r29:r28) 1715 1716@item z 1717Register pair Z (r31:r30) 1718 1719@item I 1720Constant greater than @minus{}1, less than 64 1721 1722@item J 1723Constant greater than @minus{}64, less than 1 1724 1725@item K 1726Constant integer 2 1727 1728@item L 1729Constant integer 0 1730 1731@item M 1732Constant that fits in 8 bits 1733 1734@item N 1735Constant integer @minus{}1 1736 1737@item O 1738Constant integer 8, 16, or 24 1739 1740@item P 1741Constant integer 1 1742 1743@item G 1744A floating point constant 0.0 1745@end table 1746 1747@item CRX Architecture---@file{config/crx/crx.h} 1748@table @code 1749 1750@item b 1751Registers from r0 to r14 (registers without stack pointer) 1752 1753@item l 1754Register r16 (64-bit accumulator lo register) 1755 1756@item h 1757Register r17 (64-bit accumulator hi register) 1758 1759@item k 1760Register pair r16-r17. (64-bit accumulator lo-hi pair) 1761 1762@item I 1763Constant that fits in 3 bits 1764 1765@item J 1766Constant that fits in 4 bits 1767 1768@item K 1769Constant that fits in 5 bits 1770 1771@item L 1772Constant that is one of -1, 4, -4, 7, 8, 12, 16, 20, 32, 48 1773 1774@item G 1775Floating point constant that is legal for store immediate 1776@end table 1777 1778@item PowerPC and IBM RS6000---@file{config/rs6000/rs6000.h} 1779@table @code 1780@item b 1781Address base register 1782 1783@item f 1784Floating point register 1785 1786@item v 1787Vector register 1788 1789@item h 1790@samp{MQ}, @samp{CTR}, or @samp{LINK} register 1791 1792@item q 1793@samp{MQ} register 1794 1795@item c 1796@samp{CTR} register 1797 1798@item l 1799@samp{LINK} register 1800 1801@item x 1802@samp{CR} register (condition register) number 0 1803 1804@item y 1805@samp{CR} register (condition register) 1806 1807@item z 1808@samp{FPMEM} stack memory for FPR-GPR transfers 1809 1810@item I 1811Signed 16-bit constant 1812 1813@item J 1814Unsigned 16-bit constant shifted left 16 bits (use @samp{L} instead for 1815@code{SImode} constants) 1816 1817@item K 1818Unsigned 16-bit constant 1819 1820@item L 1821Signed 16-bit constant shifted left 16 bits 1822 1823@item M 1824Constant larger than 31 1825 1826@item N 1827Exact power of 2 1828 1829@item O 1830Zero 1831 1832@item P 1833Constant whose negation is a signed 16-bit constant 1834 1835@item G 1836Floating point constant that can be loaded into a register with one 1837instruction per word 1838 1839@item Q 1840Memory operand that is an offset from a register (@samp{m} is preferable 1841for @code{asm} statements) 1842 1843@item R 1844AIX TOC entry 1845 1846@item S 1847Constant suitable as a 64-bit mask operand 1848 1849@item T 1850Constant suitable as a 32-bit mask operand 1851 1852@item U 1853System V Release 4 small data area reference 1854@end table 1855 1856@item MorphoTech family---@file{config/mt/mt.h} 1857@table @code 1858@item I 1859Constant for an arithmetic insn (16-bit signed integer). 1860 1861@item J 1862The constant 0. 1863 1864@item K 1865Constant for a logical insn (16-bit zero-extended integer). 1866 1867@item L 1868A constant that can be loaded with @code{lui} (i.e.@: the bottom 16 1869bits are zero). 1870 1871@item M 1872A constant that takes two words to load (i.e.@: not matched by 1873@code{I}, @code{K}, or @code{L}). 1874 1875@item N 1876Negative 16-bit constants other than -65536. 1877 1878@item O 1879A 15-bit signed integer constant. 1880 1881@item P 1882A positive 16-bit constant. 1883@end table 1884 1885@item Intel 386---@file{config/i386/constraints.md} 1886@table @code 1887@item R 1888Legacy register---the eight integer registers available on all 1889i386 processors (@code{a}, @code{b}, @code{c}, @code{d}, 1890@code{si}, @code{di}, @code{bp}, @code{sp}). 1891 1892@item q 1893Any register accessible as @code{@var{r}l}. In 32-bit mode, @code{a}, 1894@code{b}, @code{c}, and @code{d}; in 64-bit mode, any integer register. 1895 1896@item Q 1897Any register accessible as @code{@var{r}h}: @code{a}, @code{b}, 1898@code{c}, and @code{d}. 1899 1900@ifset INTERNALS 1901@item l 1902Any register that can be used as the index in a base+index memory 1903access: that is, any general register except the stack pointer. 1904@end ifset 1905 1906@item a 1907The @code{a} register. 1908 1909@item b 1910The @code{b} register. 1911 1912@item c 1913The @code{c} register. 1914 1915@item d 1916The @code{d} register. 1917 1918@item S 1919The @code{si} register. 1920 1921@item D 1922The @code{di} register. 1923 1924@item A 1925The @code{a} and @code{d} registers, as a pair (for instructions that 1926return half the result in one and half in the other). 1927 1928@item f 1929Any 80387 floating-point (stack) register. 1930 1931@item t 1932Top of 80387 floating-point stack (@code{%st(0)}). 1933 1934@item u 1935Second from top of 80387 floating-point stack (@code{%st(1)}). 1936 1937@item y 1938Any MMX register. 1939 1940@item x 1941Any SSE register. 1942 1943@ifset INTERNALS 1944@item Y 1945Any SSE2 register. 1946@end ifset 1947 1948@item I 1949Integer constant in the range 0 @dots{} 31, for 32-bit shifts. 1950 1951@item J 1952Integer constant in the range 0 @dots{} 63, for 64-bit shifts. 1953 1954@item K 1955Signed 8-bit integer constant. 1956 1957@item L 1958@code{0xFF} or @code{0xFFFF}, for andsi as a zero-extending move. 1959 1960@item M 19610, 1, 2, or 3 (shifts for the @code{lea} instruction). 1962 1963@item N 1964Unsigned 8-bit integer constant (for @code{in} and @code{out} 1965instructions). 1966 1967@ifset INTERNALS 1968@item O 1969Integer constant in the range 0 @dots{} 127, for 128-bit shifts. 1970@end ifset 1971 1972@item G 1973Standard 80387 floating point constant. 1974 1975@item C 1976Standard SSE floating point constant. 1977 1978@item e 197932-bit signed integer constant, or a symbolic reference known 1980to fit that range (for immediate operands in sign-extending x86-64 1981instructions). 1982 1983@item Z 198432-bit unsigned integer constant, or a symbolic reference known 1985to fit that range (for immediate operands in zero-extending x86-64 1986instructions). 1987 1988@end table 1989 1990@item Intel IA-64---@file{config/ia64/ia64.h} 1991@table @code 1992@item a 1993General register @code{r0} to @code{r3} for @code{addl} instruction 1994 1995@item b 1996Branch register 1997 1998@item c 1999Predicate register (@samp{c} as in ``conditional'') 2000 2001@item d 2002Application register residing in M-unit 2003 2004@item e 2005Application register residing in I-unit 2006 2007@item f 2008Floating-point register 2009 2010@item m 2011Memory operand. 2012Remember that @samp{m} allows postincrement and postdecrement which 2013require printing with @samp{%Pn} on IA-64. 2014Use @samp{S} to disallow postincrement and postdecrement. 2015 2016@item G 2017Floating-point constant 0.0 or 1.0 2018 2019@item I 202014-bit signed integer constant 2021 2022@item J 202322-bit signed integer constant 2024 2025@item K 20268-bit signed integer constant for logical instructions 2027 2028@item L 20298-bit adjusted signed integer constant for compare pseudo-ops 2030 2031@item M 20326-bit unsigned integer constant for shift counts 2033 2034@item N 20359-bit signed integer constant for load and store postincrements 2036 2037@item O 2038The constant zero 2039 2040@item P 20410 or @minus{}1 for @code{dep} instruction 2042 2043@item Q 2044Non-volatile memory for floating-point loads and stores 2045 2046@item R 2047Integer constant in the range 1 to 4 for @code{shladd} instruction 2048 2049@item S 2050Memory operand except postincrement and postdecrement 2051@end table 2052 2053@item FRV---@file{config/frv/frv.h} 2054@table @code 2055@item a 2056Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}). 2057 2058@item b 2059Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}). 2060 2061@item c 2062Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and 2063@code{icc0} to @code{icc3}). 2064 2065@item d 2066Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}). 2067 2068@item e 2069Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}). 2070Odd registers are excluded not in the class but through the use of a machine 2071mode larger than 4 bytes. 2072 2073@item f 2074Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}). 2075 2076@item h 2077Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}). 2078Odd registers are excluded not in the class but through the use of a machine 2079mode larger than 4 bytes. 2080 2081@item l 2082Register in the class @code{LR_REG} (the @code{lr} register). 2083 2084@item q 2085Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}). 2086Register numbers not divisible by 4 are excluded not in the class but through 2087the use of a machine mode larger than 8 bytes. 2088 2089@item t 2090Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}). 2091 2092@item u 2093Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}). 2094 2095@item v 2096Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}). 2097 2098@item w 2099Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}). 2100 2101@item x 2102Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}). 2103Register numbers not divisible by 4 are excluded not in the class but through 2104the use of a machine mode larger than 8 bytes. 2105 2106@item z 2107Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}). 2108 2109@item A 2110Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}). 2111 2112@item B 2113Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}). 2114 2115@item C 2116Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}). 2117 2118@item G 2119Floating point constant zero 2120 2121@item I 21226-bit signed integer constant 2123 2124@item J 212510-bit signed integer constant 2126 2127@item L 212816-bit signed integer constant 2129 2130@item M 213116-bit unsigned integer constant 2132 2133@item N 213412-bit signed integer constant that is negative---i.e.@: in the 2135range of @minus{}2048 to @minus{}1 2136 2137@item O 2138Constant zero 2139 2140@item P 214112-bit signed integer constant that is greater than zero---i.e.@: in the 2142range of 1 to 2047. 2143 2144@end table 2145 2146@item Blackfin family---@file{config/bfin/bfin.h} 2147@table @code 2148@item a 2149P register 2150 2151@item d 2152D register 2153 2154@item z 2155A call clobbered P register. 2156 2157@item D 2158Even-numbered D register 2159 2160@item W 2161Odd-numbered D register 2162 2163@item e 2164Accumulator register. 2165 2166@item A 2167Even-numbered accumulator register. 2168 2169@item B 2170Odd-numbered accumulator register. 2171 2172@item b 2173I register 2174 2175@item v 2176B register 2177 2178@item f 2179M register 2180 2181@item c 2182Registers used for circular buffering, i.e. I, B, or L registers. 2183 2184@item C 2185The CC register. 2186 2187@item t 2188LT0 or LT1. 2189 2190@item k 2191LC0 or LC1. 2192 2193@item u 2194LB0 or LB1. 2195 2196@item x 2197Any D, P, B, M, I or L register. 2198 2199@item y 2200Additional registers typically used only in prologues and epilogues: RETS, 2201RETN, RETI, RETX, RETE, ASTAT, SEQSTAT and USP. 2202 2203@item w 2204Any register except accumulators or CC. 2205 2206@item Ksh 2207Signed 16 bit integer (in the range -32768 to 32767) 2208 2209@item Kuh 2210Unsigned 16 bit integer (in the range 0 to 65535) 2211 2212@item Ks7 2213Signed 7 bit integer (in the range -64 to 63) 2214 2215@item Ku7 2216Unsigned 7 bit integer (in the range 0 to 127) 2217 2218@item Ku5 2219Unsigned 5 bit integer (in the range 0 to 31) 2220 2221@item Ks4 2222Signed 4 bit integer (in the range -8 to 7) 2223 2224@item Ks3 2225Signed 3 bit integer (in the range -3 to 4) 2226 2227@item Ku3 2228Unsigned 3 bit integer (in the range 0 to 7) 2229 2230@item P@var{n} 2231Constant @var{n}, where @var{n} is a single-digit constant in the range 0 to 4. 2232 2233@item M1 2234Constant 255. 2235 2236@item M2 2237Constant 65535. 2238 2239@item J 2240An integer constant with exactly a single bit set. 2241 2242@item L 2243An integer constant with all bits set except exactly one. 2244 2245@item H 2246 2247@item Q 2248Any SYMBOL_REF. 2249@end table 2250 2251@item M32C---@file{config/m32c/m32c.c} 2252@table @code 2253@item Rsp 2254@itemx Rfb 2255@itemx Rsb 2256@samp{$sp}, @samp{$fb}, @samp{$sb}. 2257 2258@item Rcr 2259Any control register, when they're 16 bits wide (nothing if control 2260registers are 24 bits wide) 2261 2262@item Rcl 2263Any control register, when they're 24 bits wide. 2264 2265@item R0w 2266@itemx R1w 2267@itemx R2w 2268@itemx R3w 2269$r0, $r1, $r2, $r3. 2270 2271@item R02 2272$r0 or $r2, or $r2r0 for 32 bit values. 2273 2274@item R13 2275$r1 or $r3, or $r3r1 for 32 bit values. 2276 2277@item Rdi 2278A register that can hold a 64 bit value. 2279 2280@item Rhl 2281$r0 or $r1 (registers with addressable high/low bytes) 2282 2283@item R23 2284$r2 or $r3 2285 2286@item Raa 2287Address registers 2288 2289@item Raw 2290Address registers when they're 16 bits wide. 2291 2292@item Ral 2293Address registers when they're 24 bits wide. 2294 2295@item Rqi 2296Registers that can hold QI values. 2297 2298@item Rad 2299Registers that can be used with displacements ($a0, $a1, $sb). 2300 2301@item Rsi 2302Registers that can hold 32 bit values. 2303 2304@item Rhi 2305Registers that can hold 16 bit values. 2306 2307@item Rhc 2308Registers chat can hold 16 bit values, including all control 2309registers. 2310 2311@item Rra 2312$r0 through R1, plus $a0 and $a1. 2313 2314@item Rfl 2315The flags register. 2316 2317@item Rmm 2318The memory-based pseudo-registers $mem0 through $mem15. 2319 2320@item Rpi 2321Registers that can hold pointers (16 bit registers for r8c, m16c; 24 2322bit registers for m32cm, m32c). 2323 2324@item Rpa 2325Matches multiple registers in a PARALLEL to form a larger register. 2326Used to match function return values. 2327 2328@item Is3 2329-8 @dots{} 7 2330 2331@item IS1 2332-128 @dots{} 127 2333 2334@item IS2 2335-32768 @dots{} 32767 2336 2337@item IU2 23380 @dots{} 65535 2339 2340@item In4 2341-8 @dots{} -1 or 1 @dots{} 8 2342 2343@item In5 2344-16 @dots{} -1 or 1 @dots{} 16 2345 2346@item In6 2347-32 @dots{} -1 or 1 @dots{} 32 2348 2349@item IM2 2350-65536 @dots{} -1 2351 2352@item Ilb 2353An 8 bit value with exactly one bit set. 2354 2355@item Ilw 2356A 16 bit value with exactly one bit set. 2357 2358@item Sd 2359The common src/dest memory addressing modes. 2360 2361@item Sa 2362Memory addressed using $a0 or $a1. 2363 2364@item Si 2365Memory addressed with immediate addresses. 2366 2367@item Ss 2368Memory addressed using the stack pointer ($sp). 2369 2370@item Sf 2371Memory addressed using the frame base register ($fb). 2372 2373@item Ss 2374Memory addressed using the small base register ($sb). 2375 2376@item S1 2377$r1h 2378@end table 2379 2380@item MIPS---@file{config/mips/constraints.md} 2381@table @code 2382@item d 2383An address register. This is equivalent to @code{r} unless 2384generating MIPS16 code. 2385 2386@item f 2387A floating-point register (if available). 2388 2389@item h 2390The @code{hi} register. 2391 2392@item l 2393The @code{lo} register. 2394 2395@item x 2396The @code{hi} and @code{lo} registers. 2397 2398@item c 2399A register suitable for use in an indirect jump. This will always be 2400@code{$25} for @option{-mabicalls}. 2401 2402@item y 2403Equivalent to @code{r}; retained for backwards compatibility. 2404 2405@item z 2406A floating-point condition code register. 2407 2408@item I 2409A signed 16-bit constant (for arithmetic instructions). 2410 2411@item J 2412Integer zero. 2413 2414@item K 2415An unsigned 16-bit constant (for logic instructions). 2416 2417@item L 2418A signed 32-bit constant in which the lower 16 bits are zero. 2419Such constants can be loaded using @code{lui}. 2420 2421@item M 2422A constant that cannot be loaded using @code{lui}, @code{addiu} 2423or @code{ori}. 2424 2425@item N 2426A constant in the range -65535 to -1 (inclusive). 2427 2428@item O 2429A signed 15-bit constant. 2430 2431@item P 2432A constant in the range 1 to 65535 (inclusive). 2433 2434@item G 2435Floating-point zero. 2436 2437@item R 2438An address that can be used in a non-macro load or store. 2439@end table 2440 2441@item Motorola 680x0---@file{config/m68k/m68k.h} 2442@table @code 2443@item a 2444Address register 2445 2446@item d 2447Data register 2448 2449@item f 245068881 floating-point register, if available 2451 2452@item I 2453Integer in the range 1 to 8 2454 2455@item J 245616-bit signed number 2457 2458@item K 2459Signed number whose magnitude is greater than 0x80 2460 2461@item L 2462Integer in the range @minus{}8 to @minus{}1 2463 2464@item M 2465Signed number whose magnitude is greater than 0x100 2466 2467@item G 2468Floating point constant that is not a 68881 constant 2469@end table 2470 2471@item Motorola 68HC11 & 68HC12 families---@file{config/m68hc11/m68hc11.h} 2472@table @code 2473@item a 2474Register `a' 2475 2476@item b 2477Register `b' 2478 2479@item d 2480Register `d' 2481 2482@item q 2483An 8-bit register 2484 2485@item t 2486Temporary soft register _.tmp 2487 2488@item u 2489A soft register _.d1 to _.d31 2490 2491@item w 2492Stack pointer register 2493 2494@item x 2495Register `x' 2496 2497@item y 2498Register `y' 2499 2500@item z 2501Pseudo register `z' (replaced by `x' or `y' at the end) 2502 2503@item A 2504An address register: x, y or z 2505 2506@item B 2507An address register: x or y 2508 2509@item D 2510Register pair (x:d) to form a 32-bit value 2511 2512@item L 2513Constants in the range @minus{}65536 to 65535 2514 2515@item M 2516Constants whose 16-bit low part is zero 2517 2518@item N 2519Constant integer 1 or @minus{}1 2520 2521@item O 2522Constant integer 16 2523 2524@item P 2525Constants in the range @minus{}8 to 2 2526 2527@end table 2528 2529@need 1000 2530@item SPARC---@file{config/sparc/sparc.h} 2531@table @code 2532@item f 2533Floating-point register on the SPARC-V8 architecture and 2534lower floating-point register on the SPARC-V9 architecture. 2535 2536@item e 2537Floating-point register. It is equivalent to @samp{f} on the 2538SPARC-V8 architecture and contains both lower and upper 2539floating-point registers on the SPARC-V9 architecture. 2540 2541@item c 2542Floating-point condition code register. 2543 2544@item d 2545Lower floating-point register. It is only valid on the SPARC-V9 2546architecture when the Visual Instruction Set is available. 2547 2548@item b 2549Floating-point register. It is only valid on the SPARC-V9 architecture 2550when the Visual Instruction Set is available. 2551 2552@item h 255364-bit global or out register for the SPARC-V8+ architecture. 2554 2555@item I 2556Signed 13-bit constant 2557 2558@item J 2559Zero 2560 2561@item K 256232-bit constant with the low 12 bits clear (a constant that can be 2563loaded with the @code{sethi} instruction) 2564 2565@item L 2566A constant in the range supported by @code{movcc} instructions 2567 2568@item M 2569A constant in the range supported by @code{movrcc} instructions 2570 2571@item N 2572Same as @samp{K}, except that it verifies that bits that are not in the 2573lower 32-bit range are all zero. Must be used instead of @samp{K} for 2574modes wider than @code{SImode} 2575 2576@item O 2577The constant 4096 2578 2579@item G 2580Floating-point zero 2581 2582@item H 2583Signed 13-bit constant, sign-extended to 32 or 64 bits 2584 2585@item Q 2586Floating-point constant whose integral representation can 2587be moved into an integer register using a single sethi 2588instruction 2589 2590@item R 2591Floating-point constant whose integral representation can 2592be moved into an integer register using a single mov 2593instruction 2594 2595@item S 2596Floating-point constant whose integral representation can 2597be moved into an integer register using a high/lo_sum 2598instruction sequence 2599 2600@item T 2601Memory address aligned to an 8-byte boundary 2602 2603@item U 2604Even register 2605 2606@item W 2607Memory address for @samp{e} constraint registers 2608 2609@item Y 2610Vector zero 2611 2612@end table 2613 2614@item TMS320C3x/C4x---@file{config/c4x/c4x.h} 2615@table @code 2616@item a 2617Auxiliary (address) register (ar0-ar7) 2618 2619@item b 2620Stack pointer register (sp) 2621 2622@item c 2623Standard (32-bit) precision integer register 2624 2625@item f 2626Extended (40-bit) precision register (r0-r11) 2627 2628@item k 2629Block count register (bk) 2630 2631@item q 2632Extended (40-bit) precision low register (r0-r7) 2633 2634@item t 2635Extended (40-bit) precision register (r0-r1) 2636 2637@item u 2638Extended (40-bit) precision register (r2-r3) 2639 2640@item v 2641Repeat count register (rc) 2642 2643@item x 2644Index register (ir0-ir1) 2645 2646@item y 2647Status (condition code) register (st) 2648 2649@item z 2650Data page register (dp) 2651 2652@item G 2653Floating-point zero 2654 2655@item H 2656Immediate 16-bit floating-point constant 2657 2658@item I 2659Signed 16-bit constant 2660 2661@item J 2662Signed 8-bit constant 2663 2664@item K 2665Signed 5-bit constant 2666 2667@item L 2668Unsigned 16-bit constant 2669 2670@item M 2671Unsigned 8-bit constant 2672 2673@item N 2674Ones complement of unsigned 16-bit constant 2675 2676@item O 2677High 16-bit constant (32-bit constant with 16 LSBs zero) 2678 2679@item Q 2680Indirect memory reference with signed 8-bit or index register displacement 2681 2682@item R 2683Indirect memory reference with unsigned 5-bit displacement 2684 2685@item S 2686Indirect memory reference with 1 bit or index register displacement 2687 2688@item T 2689Direct memory reference 2690 2691@item U 2692Symbolic address 2693 2694@end table 2695 2696@item S/390 and zSeries---@file{config/s390/s390.h} 2697@table @code 2698@item a 2699Address register (general purpose register except r0) 2700 2701@item c 2702Condition code register 2703 2704@item d 2705Data register (arbitrary general purpose register) 2706 2707@item f 2708Floating-point register 2709 2710@item I 2711Unsigned 8-bit constant (0--255) 2712 2713@item J 2714Unsigned 12-bit constant (0--4095) 2715 2716@item K 2717Signed 16-bit constant (@minus{}32768--32767) 2718 2719@item L 2720Value appropriate as displacement. 2721@table @code 2722 @item (0..4095) 2723 for short displacement 2724 @item (-524288..524287) 2725 for long displacement 2726@end table 2727 2728@item M 2729Constant integer with a value of 0x7fffffff. 2730 2731@item N 2732Multiple letter constraint followed by 4 parameter letters. 2733@table @code 2734 @item 0..9: 2735 number of the part counting from most to least significant 2736 @item H,Q: 2737 mode of the part 2738 @item D,S,H: 2739 mode of the containing operand 2740 @item 0,F: 2741 value of the other parts (F---all bits set) 2742@end table 2743The constraint matches if the specified part of a constant 2744has a value different from it's other parts. 2745 2746@item Q 2747Memory reference without index register and with short displacement. 2748 2749@item R 2750Memory reference with index register and short displacement. 2751 2752@item S 2753Memory reference without index register but with long displacement. 2754 2755@item T 2756Memory reference with index register and long displacement. 2757 2758@item U 2759Pointer with short displacement. 2760 2761@item W 2762Pointer with long displacement. 2763 2764@item Y 2765Shift count operand. 2766 2767@end table 2768 2769@item Score family---@file{config/score/score.h} 2770@table @code 2771@item d 2772Registers from r0 to r32. 2773 2774@item e 2775Registers from r0 to r16. 2776 2777@item t 2778r8---r11 or r22---r27 registers. 2779 2780@item h 2781hi register. 2782 2783@item l 2784lo register. 2785 2786@item x 2787hi + lo register. 2788 2789@item q 2790cnt register. 2791 2792@item y 2793lcb register. 2794 2795@item z 2796scb register. 2797 2798@item a 2799cnt + lcb + scb register. 2800 2801@item c 2802cr0---cr15 register. 2803 2804@item b 2805cp1 registers. 2806 2807@item f 2808cp2 registers. 2809 2810@item i 2811cp3 registers. 2812 2813@item j 2814cp1 + cp2 + cp3 registers. 2815 2816@item I 2817High 16-bit constant (32-bit constant with 16 LSBs zero). 2818 2819@item J 2820Unsigned 5 bit integer (in the range 0 to 31). 2821 2822@item K 2823Unsigned 16 bit integer (in the range 0 to 65535). 2824 2825@item L 2826Signed 16 bit integer (in the range @minus{}32768 to 32767). 2827 2828@item M 2829Unsigned 14 bit integer (in the range 0 to 16383). 2830 2831@item N 2832Signed 14 bit integer (in the range @minus{}8192 to 8191). 2833 2834@item Z 2835Any SYMBOL_REF. 2836@end table 2837 2838@item Xstormy16---@file{config/stormy16/stormy16.h} 2839@table @code 2840@item a 2841Register r0. 2842 2843@item b 2844Register r1. 2845 2846@item c 2847Register r2. 2848 2849@item d 2850Register r8. 2851 2852@item e 2853Registers r0 through r7. 2854 2855@item t 2856Registers r0 and r1. 2857 2858@item y 2859The carry register. 2860 2861@item z 2862Registers r8 and r9. 2863 2864@item I 2865A constant between 0 and 3 inclusive. 2866 2867@item J 2868A constant that has exactly one bit set. 2869 2870@item K 2871A constant that has exactly one bit clear. 2872 2873@item L 2874A constant between 0 and 255 inclusive. 2875 2876@item M 2877A constant between @minus{}255 and 0 inclusive. 2878 2879@item N 2880A constant between @minus{}3 and 0 inclusive. 2881 2882@item O 2883A constant between 1 and 4 inclusive. 2884 2885@item P 2886A constant between @minus{}4 and @minus{}1 inclusive. 2887 2888@item Q 2889A memory reference that is a stack push. 2890 2891@item R 2892A memory reference that is a stack pop. 2893 2894@item S 2895A memory reference that refers to a constant address of known value. 2896 2897@item T 2898The register indicated by Rx (not implemented yet). 2899 2900@item U 2901A constant that is not between 2 and 15 inclusive. 2902 2903@item Z 2904The constant 0. 2905 2906@end table 2907 2908@item Xtensa---@file{config/xtensa/xtensa.h} 2909@table @code 2910@item a 2911General-purpose 32-bit register 2912 2913@item b 2914One-bit boolean register 2915 2916@item A 2917MAC16 40-bit accumulator register 2918 2919@item I 2920Signed 12-bit integer constant, for use in MOVI instructions 2921 2922@item J 2923Signed 8-bit integer constant, for use in ADDI instructions 2924 2925@item K 2926Integer constant valid for BccI instructions 2927 2928@item L 2929Unsigned constant valid for BccUI instructions 2930 2931@end table 2932 2933@end table 2934 2935@ifset INTERNALS 2936@node Define Constraints 2937@subsection Defining Machine-Specific Constraints 2938@cindex defining constraints 2939@cindex constraints, defining 2940 2941Machine-specific constraints fall into two categories: register and 2942non-register constraints. Within the latter category, constraints 2943which allow subsets of all possible memory or address operands should 2944be specially marked, to give @code{reload} more information. 2945 2946Machine-specific constraints can be given names of arbitrary length, 2947but they must be entirely composed of letters, digits, underscores 2948(@samp{_}), and angle brackets (@samp{< >}). Like C identifiers, they 2949must begin with a letter or underscore. 2950 2951In order to avoid ambiguity in operand constraint strings, no 2952constraint can have a name that begins with any other constraint's 2953name. For example, if @code{x} is defined as a constraint name, 2954@code{xy} may not be, and vice versa. As a consequence of this rule, 2955no constraint may begin with one of the generic constraint letters: 2956@samp{E F V X g i m n o p r s}. 2957 2958Register constraints correspond directly to register classes. 2959@xref{Register Classes}. There is thus not much flexibility in their 2960definitions. 2961 2962@deffn {MD Expression} define_register_constraint name regclass docstring 2963All three arguments are string constants. 2964@var{name} is the name of the constraint, as it will appear in 2965@code{match_operand} expressions. @var{regclass} can be either the 2966name of the corresponding register class (@pxref{Register Classes}), 2967or a C expression which evaluates to the appropriate register class. 2968If it is an expression, it must have no side effects, and it cannot 2969look at the operand. The usual use of expressions is to map some 2970register constraints to @code{NO_REGS} when the register class 2971is not available on a given subarchitecture. 2972 2973@var{docstring} is a sentence documenting the meaning of the 2974constraint. Docstrings are explained further below. 2975@end deffn 2976 2977Non-register constraints are more like predicates: the constraint 2978definition gives a Boolean expression which indicates whether the 2979constraint matches. 2980 2981@deffn {MD Expression} define_constraint name docstring exp 2982The @var{name} and @var{docstring} arguments are the same as for 2983@code{define_register_constraint}, but note that the docstring comes 2984immediately after the name for these expressions. @var{exp} is an RTL 2985expression, obeying the same rules as the RTL expressions in predicate 2986definitions. @xref{Defining Predicates}, for details. If it 2987evaluates true, the constraint matches; if it evaluates false, it 2988doesn't. Constraint expressions should indicate which RTL codes they 2989might match, just like predicate expressions. 2990 2991@code{match_test} C expressions have access to the 2992following variables: 2993 2994@table @var 2995@item op 2996The RTL object defining the operand. 2997@item mode 2998The machine mode of @var{op}. 2999@item ival 3000@samp{INTVAL (@var{op})}, if @var{op} is a @code{const_int}. 3001@item hval 3002@samp{CONST_DOUBLE_HIGH (@var{op})}, if @var{op} is an integer 3003@code{const_double}. 3004@item lval 3005@samp{CONST_DOUBLE_LOW (@var{op})}, if @var{op} is an integer 3006@code{const_double}. 3007@item rval 3008@samp{CONST_DOUBLE_REAL_VALUE (@var{op})}, if @var{op} is a floating-point 3009@code{const_double}. 3010@end table 3011 3012The @var{*val} variables should only be used once another piece of the 3013expression has verified that @var{op} is the appropriate kind of RTL 3014object. 3015@end deffn 3016 3017Most non-register constraints should be defined with 3018@code{define_constraint}. The remaining two definition expressions 3019are only appropriate for constraints that should be handled specially 3020by @code{reload} if they fail to match. 3021 3022@deffn {MD Expression} define_memory_constraint name docstring exp 3023Use this expression for constraints that match a subset of all memory 3024operands: that is, @code{reload} can make them match by converting the 3025operand to the form @samp{@w{(mem (reg @var{X}))}}, where @var{X} is a 3026base register (from the register class specified by 3027@code{BASE_REG_CLASS}, @pxref{Register Classes}). 3028 3029For example, on the S/390, some instructions do not accept arbitrary 3030memory references, but only those that do not make use of an index 3031register. The constraint letter @samp{Q} is defined to represent a 3032memory address of this type. If @samp{Q} is defined with 3033@code{define_memory_constraint}, a @samp{Q} constraint can handle any 3034memory operand, because @code{reload} knows it can simply copy the 3035memory address into a base register if required. This is analogous to 3036the way a @samp{o} constraint can handle any memory operand. 3037 3038The syntax and semantics are otherwise identical to 3039@code{define_constraint}. 3040@end deffn 3041 3042@deffn {MD Expression} define_address_constraint name docstring exp 3043Use this expression for constraints that match a subset of all address 3044operands: that is, @code{reload} can make the constraint match by 3045converting the operand to the form @samp{@w{(reg @var{X})}}, again 3046with @var{X} a base register. 3047 3048Constraints defined with @code{define_address_constraint} can only be 3049used with the @code{address_operand} predicate, or machine-specific 3050predicates that work the same way. They are treated analogously to 3051the generic @samp{p} constraint. 3052 3053The syntax and semantics are otherwise identical to 3054@code{define_constraint}. 3055@end deffn 3056 3057For historical reasons, names beginning with the letters @samp{G H} 3058are reserved for constraints that match only @code{const_double}s, and 3059names beginning with the letters @samp{I J K L M N O P} are reserved 3060for constraints that match only @code{const_int}s. This may change in 3061the future. For the time being, constraints with these names must be 3062written in a stylized form, so that @code{genpreds} can tell you did 3063it correctly: 3064 3065@smallexample 3066@group 3067(define_constraint "[@var{GHIJKLMNOP}]@dots{}" 3068 "@var{doc}@dots{}" 3069 (and (match_code "const_int") ; @r{@code{const_double} for G/H} 3070 @var{condition}@dots{})) ; @r{usually a @code{match_test}} 3071@end group 3072@end smallexample 3073@c the semicolons line up in the formatted manual 3074 3075It is fine to use names beginning with other letters for constraints 3076that match @code{const_double}s or @code{const_int}s. 3077 3078Each docstring in a constraint definition should be one or more complete 3079sentences, marked up in Texinfo format. @emph{They are currently unused.} 3080In the future they will be copied into the GCC manual, in @ref{Machine 3081Constraints}, replacing the hand-maintained tables currently found in 3082that section. Also, in the future the compiler may use this to give 3083more helpful diagnostics when poor choice of @code{asm} constraints 3084causes a reload failure. 3085 3086If you put the pseudo-Texinfo directive @samp{@@internal} at the 3087beginning of a docstring, then (in the future) it will appear only in 3088the internals manual's version of the machine-specific constraint tables. 3089Use this for constraints that should not appear in @code{asm} statements. 3090 3091@node C Constraint Interface 3092@subsection Testing constraints from C 3093@cindex testing constraints 3094@cindex constraints, testing 3095 3096It is occasionally useful to test a constraint from C code rather than 3097implicitly via the constraint string in a @code{match_operand}. The 3098generated file @file{tm_p.h} declares a few interfaces for working 3099with machine-specific constraints. None of these interfaces work with 3100the generic constraints described in @ref{Simple Constraints}. This 3101may change in the future. 3102 3103@strong{Warning:} @file{tm_p.h} may declare other functions that 3104operate on constraints, besides the ones documented here. Do not use 3105those functions from machine-dependent code. They exist to implement 3106the old constraint interface that machine-independent components of 3107the compiler still expect. They will change or disappear in the 3108future. 3109 3110Some valid constraint names are not valid C identifiers, so there is a 3111mangling scheme for referring to them from C@. Constraint names that 3112do not contain angle brackets or underscores are left unchanged. 3113Underscores are doubled, each @samp{<} is replaced with @samp{_l}, and 3114each @samp{>} with @samp{_g}. Here are some examples: 3115 3116@c the @c's prevent double blank lines in the printed manual. 3117@example 3118@multitable {Original} {Mangled} 3119@item @strong{Original} @tab @strong{Mangled} @c 3120@item @code{x} @tab @code{x} @c 3121@item @code{P42x} @tab @code{P42x} @c 3122@item @code{P4_x} @tab @code{P4__x} @c 3123@item @code{P4>x} @tab @code{P4_gx} @c 3124@item @code{P4>>} @tab @code{P4_g_g} @c 3125@item @code{P4_g>} @tab @code{P4__g_g} @c 3126@end multitable 3127@end example 3128 3129Throughout this section, the variable @var{c} is either a constraint 3130in the abstract sense, or a constant from @code{enum constraint_num}; 3131the variable @var{m} is a mangled constraint name (usually as part of 3132a larger identifier). 3133 3134@deftp Enum constraint_num 3135For each machine-specific constraint, there is a corresponding 3136enumeration constant: @samp{CONSTRAINT_} plus the mangled name of the 3137constraint. Functions that take an @code{enum constraint_num} as an 3138argument expect one of these constants. 3139 3140Machine-independent constraints do not have associated constants. 3141This may change in the future. 3142@end deftp 3143 3144@deftypefun {inline bool} satisfies_constraint_@var{m} (rtx @var{exp}) 3145For each machine-specific, non-register constraint @var{m}, there is 3146one of these functions; it returns @code{true} if @var{exp} satisfies the 3147constraint. These functions are only visible if @file{rtl.h} was included 3148before @file{tm_p.h}. 3149@end deftypefun 3150 3151@deftypefun bool constraint_satisfied_p (rtx @var{exp}, enum constraint_num @var{c}) 3152Like the @code{satisfies_constraint_@var{m}} functions, but the 3153constraint to test is given as an argument, @var{c}. If @var{c} 3154specifies a register constraint, this function will always return 3155@code{false}. 3156@end deftypefun 3157 3158@deftypefun {enum reg_class} regclass_for_constraint (enum constraint_num @var{c}) 3159Returns the register class associated with @var{c}. If @var{c} is not 3160a register constraint, or those registers are not available for the 3161currently selected subtarget, returns @code{NO_REGS}. 3162@end deftypefun 3163 3164Here is an example use of @code{satisfies_constraint_@var{m}}. In 3165peephole optimizations (@pxref{Peephole Definitions}), operand 3166constraint strings are ignored, so if there are relevant constraints, 3167they must be tested in the C condition. In the example, the 3168optimization is applied if operand 2 does @emph{not} satisfy the 3169@samp{K} constraint. (This is a simplified version of a peephole 3170definition from the i386 machine description.) 3171 3172@smallexample 3173(define_peephole2 3174 [(match_scratch:SI 3 "r") 3175 (set (match_operand:SI 0 "register_operand" "") 3176 (mult:SI (match_operand:SI 1 "memory_operand" "") 3177 (match_operand:SI 2 "immediate_operand" "")))] 3178 3179 "!satisfies_constraint_K (operands[2])" 3180 3181 [(set (match_dup 3) (match_dup 1)) 3182 (set (match_dup 0) (mult:SI (match_dup 3) (match_dup 2)))] 3183 3184 "") 3185@end smallexample 3186 3187@node Standard Names 3188@section Standard Pattern Names For Generation 3189@cindex standard pattern names 3190@cindex pattern names 3191@cindex names, pattern 3192 3193Here is a table of the instruction names that are meaningful in the RTL 3194generation pass of the compiler. Giving one of these names to an 3195instruction pattern tells the RTL generation pass that it can use the 3196pattern to accomplish a certain task. 3197 3198@table @asis 3199@cindex @code{mov@var{m}} instruction pattern 3200@item @samp{mov@var{m}} 3201Here @var{m} stands for a two-letter machine mode name, in lowercase. 3202This instruction pattern moves data with that machine mode from operand 32031 to operand 0. For example, @samp{movsi} moves full-word data. 3204 3205If operand 0 is a @code{subreg} with mode @var{m} of a register whose 3206own mode is wider than @var{m}, the effect of this instruction is 3207to store the specified value in the part of the register that corresponds 3208to mode @var{m}. Bits outside of @var{m}, but which are within the 3209same target word as the @code{subreg} are undefined. Bits which are 3210outside the target word are left unchanged. 3211 3212This class of patterns is special in several ways. First of all, each 3213of these names up to and including full word size @emph{must} be defined, 3214because there is no other way to copy a datum from one place to another. 3215If there are patterns accepting operands in larger modes, 3216@samp{mov@var{m}} must be defined for integer modes of those sizes. 3217 3218Second, these patterns are not used solely in the RTL generation pass. 3219Even the reload pass can generate move insns to copy values from stack 3220slots into temporary registers. When it does so, one of the operands is 3221a hard register and the other is an operand that can need to be reloaded 3222into a register. 3223 3224@findex force_reg 3225Therefore, when given such a pair of operands, the pattern must generate 3226RTL which needs no reloading and needs no temporary registers---no 3227registers other than the operands. For example, if you support the 3228pattern with a @code{define_expand}, then in such a case the 3229@code{define_expand} mustn't call @code{force_reg} or any other such 3230function which might generate new pseudo registers. 3231 3232This requirement exists even for subword modes on a RISC machine where 3233fetching those modes from memory normally requires several insns and 3234some temporary registers. 3235 3236@findex change_address 3237During reload a memory reference with an invalid address may be passed 3238as an operand. Such an address will be replaced with a valid address 3239later in the reload pass. In this case, nothing may be done with the 3240address except to use it as it stands. If it is copied, it will not be 3241replaced with a valid address. No attempt should be made to make such 3242an address into a valid address and no routine (such as 3243@code{change_address}) that will do so may be called. Note that 3244@code{general_operand} will fail when applied to such an address. 3245 3246@findex reload_in_progress 3247The global variable @code{reload_in_progress} (which must be explicitly 3248declared if required) can be used to determine whether such special 3249handling is required. 3250 3251The variety of operands that have reloads depends on the rest of the 3252machine description, but typically on a RISC machine these can only be 3253pseudo registers that did not get hard registers, while on other 3254machines explicit memory references will get optional reloads. 3255 3256If a scratch register is required to move an object to or from memory, 3257it can be allocated using @code{gen_reg_rtx} prior to life analysis. 3258 3259If there are cases which need scratch registers during or after reload, 3260you must provide an appropriate secondary_reload target hook. 3261 3262@findex no_new_pseudos 3263The global variable @code{no_new_pseudos} can be used to determine if it 3264is unsafe to create new pseudo registers. If this variable is nonzero, then 3265it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo. 3266 3267The constraints on a @samp{mov@var{m}} must permit moving any hard 3268register to any other hard register provided that 3269@code{HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and 3270@code{REGISTER_MOVE_COST} applied to their classes returns a value of 2. 3271 3272It is obligatory to support floating point @samp{mov@var{m}} 3273instructions into and out of any registers that can hold fixed point 3274values, because unions and structures (which have modes @code{SImode} or 3275@code{DImode}) can be in those registers and they may have floating 3276point members. 3277 3278There may also be a need to support fixed point @samp{mov@var{m}} 3279instructions in and out of floating point registers. Unfortunately, I 3280have forgotten why this was so, and I don't know whether it is still 3281true. If @code{HARD_REGNO_MODE_OK} rejects fixed point values in 3282floating point registers, then the constraints of the fixed point 3283@samp{mov@var{m}} instructions must be designed to avoid ever trying to 3284reload into a floating point register. 3285 3286@cindex @code{reload_in} instruction pattern 3287@cindex @code{reload_out} instruction pattern 3288@item @samp{reload_in@var{m}} 3289@itemx @samp{reload_out@var{m}} 3290These named patterns have been obsoleted by the target hook 3291@code{secondary_reload}. 3292 3293Like @samp{mov@var{m}}, but used when a scratch register is required to 3294move between operand 0 and operand 1. Operand 2 describes the scratch 3295register. See the discussion of the @code{SECONDARY_RELOAD_CLASS} 3296macro in @pxref{Register Classes}. 3297 3298There are special restrictions on the form of the @code{match_operand}s 3299used in these patterns. First, only the predicate for the reload 3300operand is examined, i.e., @code{reload_in} examines operand 1, but not 3301the predicates for operand 0 or 2. Second, there may be only one 3302alternative in the constraints. Third, only a single register class 3303letter may be used for the constraint; subsequent constraint letters 3304are ignored. As a special exception, an empty constraint string 3305matches the @code{ALL_REGS} register class. This may relieve ports 3306of the burden of defining an @code{ALL_REGS} constraint letter just 3307for these patterns. 3308 3309@cindex @code{movstrict@var{m}} instruction pattern 3310@item @samp{movstrict@var{m}} 3311Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg} 3312with mode @var{m} of a register whose natural mode is wider, 3313the @samp{movstrict@var{m}} instruction is guaranteed not to alter 3314any of the register except the part which belongs to mode @var{m}. 3315 3316@cindex @code{movmisalign@var{m}} instruction pattern 3317@item @samp{movmisalign@var{m}} 3318This variant of a move pattern is designed to load or store a value 3319from a memory address that is not naturally aligned for its mode. 3320For a store, the memory will be in operand 0; for a load, the memory 3321will be in operand 1. The other operand is guaranteed not to be a 3322memory, so that it's easy to tell whether this is a load or store. 3323 3324This pattern is used by the autovectorizer, and when expanding a 3325@code{MISALIGNED_INDIRECT_REF} expression. 3326 3327@cindex @code{load_multiple} instruction pattern 3328@item @samp{load_multiple} 3329Load several consecutive memory locations into consecutive registers. 3330Operand 0 is the first of the consecutive registers, operand 1 3331is the first memory location, and operand 2 is a constant: the 3332number of consecutive registers. 3333 3334Define this only if the target machine really has such an instruction; 3335do not define this if the most efficient way of loading consecutive 3336registers from memory is to do them one at a time. 3337 3338On some machines, there are restrictions as to which consecutive 3339registers can be stored into memory, such as particular starting or 3340ending register numbers or only a range of valid counts. For those 3341machines, use a @code{define_expand} (@pxref{Expander Definitions}) 3342and make the pattern fail if the restrictions are not met. 3343 3344Write the generated insn as a @code{parallel} with elements being a 3345@code{set} of one register from the appropriate memory location (you may 3346also need @code{use} or @code{clobber} elements). Use a 3347@code{match_parallel} (@pxref{RTL Template}) to recognize the insn. See 3348@file{rs6000.md} for examples of the use of this insn pattern. 3349 3350@cindex @samp{store_multiple} instruction pattern 3351@item @samp{store_multiple} 3352Similar to @samp{load_multiple}, but store several consecutive registers 3353into consecutive memory locations. Operand 0 is the first of the 3354consecutive memory locations, operand 1 is the first register, and 3355operand 2 is a constant: the number of consecutive registers. 3356 3357@cindex @code{vec_set@var{m}} instruction pattern 3358@item @samp{vec_set@var{m}} 3359Set given field in the vector value. Operand 0 is the vector to modify, 3360operand 1 is new value of field and operand 2 specify the field index. 3361 3362@cindex @code{vec_extract@var{m}} instruction pattern 3363@item @samp{vec_extract@var{m}} 3364Extract given field from the vector value. Operand 1 is the vector, operand 2 3365specify field index and operand 0 place to store value into. 3366 3367@cindex @code{vec_init@var{m}} instruction pattern 3368@item @samp{vec_init@var{m}} 3369Initialize the vector to given values. Operand 0 is the vector to initialize 3370and operand 1 is parallel containing values for individual fields. 3371 3372@cindex @code{push@var{m}1} instruction pattern 3373@item @samp{push@var{m}1} 3374Output a push instruction. Operand 0 is value to push. Used only when 3375@code{PUSH_ROUNDING} is defined. For historical reason, this pattern may be 3376missing and in such case an @code{mov} expander is used instead, with a 3377@code{MEM} expression forming the push operation. The @code{mov} expander 3378method is deprecated. 3379 3380@cindex @code{add@var{m}3} instruction pattern 3381@item @samp{add@var{m}3} 3382Add operand 2 and operand 1, storing the result in operand 0. All operands 3383must have mode @var{m}. This can be used even on two-address machines, by 3384means of constraints requiring operands 1 and 0 to be the same location. 3385 3386@cindex @code{sub@var{m}3} instruction pattern 3387@cindex @code{mul@var{m}3} instruction pattern 3388@cindex @code{div@var{m}3} instruction pattern 3389@cindex @code{udiv@var{m}3} instruction pattern 3390@cindex @code{mod@var{m}3} instruction pattern 3391@cindex @code{umod@var{m}3} instruction pattern 3392@cindex @code{umin@var{m}3} instruction pattern 3393@cindex @code{umax@var{m}3} instruction pattern 3394@cindex @code{and@var{m}3} instruction pattern 3395@cindex @code{ior@var{m}3} instruction pattern 3396@cindex @code{xor@var{m}3} instruction pattern 3397@item @samp{sub@var{m}3}, @samp{mul@var{m}3} 3398@itemx @samp{div@var{m}3}, @samp{udiv@var{m}3} 3399@itemx @samp{mod@var{m}3}, @samp{umod@var{m}3} 3400@itemx @samp{umin@var{m}3}, @samp{umax@var{m}3} 3401@itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3} 3402Similar, for other arithmetic operations. 3403 3404@cindex @code{min@var{m}3} instruction pattern 3405@cindex @code{max@var{m}3} instruction pattern 3406@item @samp{smin@var{m}3}, @samp{smax@var{m}3} 3407Signed minimum and maximum operations. When used with floating point, 3408if both operands are zeros, or if either operand is @code{NaN}, then 3409it is unspecified which of the two operands is returned as the result. 3410 3411@cindex @code{reduc_smin_@var{m}} instruction pattern 3412@cindex @code{reduc_smax_@var{m}} instruction pattern 3413@item @samp{reduc_smin_@var{m}}, @samp{reduc_smax_@var{m}} 3414Find the signed minimum/maximum of the elements of a vector. The vector is 3415operand 1, and the scalar result is stored in the least significant bits of 3416operand 0 (also a vector). The output and input vector should have the same 3417modes. 3418 3419@cindex @code{reduc_umin_@var{m}} instruction pattern 3420@cindex @code{reduc_umax_@var{m}} instruction pattern 3421@item @samp{reduc_umin_@var{m}}, @samp{reduc_umax_@var{m}} 3422Find the unsigned minimum/maximum of the elements of a vector. The vector is 3423operand 1, and the scalar result is stored in the least significant bits of 3424operand 0 (also a vector). The output and input vector should have the same 3425modes. 3426 3427@cindex @code{reduc_splus_@var{m}} instruction pattern 3428@item @samp{reduc_splus_@var{m}} 3429Compute the sum of the signed elements of a vector. The vector is operand 1, 3430and the scalar result is stored in the least significant bits of operand 0 3431(also a vector). The output and input vector should have the same modes. 3432 3433@cindex @code{reduc_uplus_@var{m}} instruction pattern 3434@item @samp{reduc_uplus_@var{m}} 3435Compute the sum of the unsigned elements of a vector. The vector is operand 1, 3436and the scalar result is stored in the least significant bits of operand 0 3437(also a vector). The output and input vector should have the same modes. 3438 3439@cindex @code{sdot_prod@var{m}} instruction pattern 3440@item @samp{sdot_prod@var{m}} 3441@cindex @code{udot_prod@var{m}} instruction pattern 3442@item @samp{udot_prod@var{m}} 3443Compute the sum of the products of two signed/unsigned elements. 3444Operand 1 and operand 2 are of the same mode. Their product, which is of a 3445wider mode, is computed and added to operand 3. Operand 3 is of a mode equal or 3446wider than the mode of the product. The result is placed in operand 0, which 3447is of the same mode as operand 3. 3448 3449@cindex @code{ssum_widen@var{m3}} instruction pattern 3450@item @samp{ssum_widen@var{m3}} 3451@cindex @code{usum_widen@var{m3}} instruction pattern 3452@item @samp{usum_widen@var{m3}} 3453Operands 0 and 2 are of the same mode, which is wider than the mode of 3454operand 1. Add operand 1 to operand 2 and place the widened result in 3455operand 0. (This is used express accumulation of elements into an accumulator 3456of a wider mode.) 3457 3458@cindex @code{vec_shl_@var{m}} instruction pattern 3459@cindex @code{vec_shr_@var{m}} instruction pattern 3460@item @samp{vec_shl_@var{m}}, @samp{vec_shr_@var{m}} 3461Whole vector left/right shift in bits. 3462Operand 1 is a vector to be shifted. 3463Operand 2 is an integer shift amount in bits. 3464Operand 0 is where the resulting shifted vector is stored. 3465The output and input vectors should have the same modes. 3466 3467@cindex @code{mulhisi3} instruction pattern 3468@item @samp{mulhisi3} 3469Multiply operands 1 and 2, which have mode @code{HImode}, and store 3470a @code{SImode} product in operand 0. 3471 3472@cindex @code{mulqihi3} instruction pattern 3473@cindex @code{mulsidi3} instruction pattern 3474@item @samp{mulqihi3}, @samp{mulsidi3} 3475Similar widening-multiplication instructions of other widths. 3476 3477@cindex @code{umulqihi3} instruction pattern 3478@cindex @code{umulhisi3} instruction pattern 3479@cindex @code{umulsidi3} instruction pattern 3480@item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3} 3481Similar widening-multiplication instructions that do unsigned 3482multiplication. 3483 3484@cindex @code{usmulqihi3} instruction pattern 3485@cindex @code{usmulhisi3} instruction pattern 3486@cindex @code{usmulsidi3} instruction pattern 3487@item @samp{usmulqihi3}, @samp{usmulhisi3}, @samp{usmulsidi3} 3488Similar widening-multiplication instructions that interpret the first 3489operand as unsigned and the second operand as signed, then do a signed 3490multiplication. 3491 3492@cindex @code{smul@var{m}3_highpart} instruction pattern 3493@item @samp{smul@var{m}3_highpart} 3494Perform a signed multiplication of operands 1 and 2, which have mode 3495@var{m}, and store the most significant half of the product in operand 0. 3496The least significant half of the product is discarded. 3497 3498@cindex @code{umul@var{m}3_highpart} instruction pattern 3499@item @samp{umul@var{m}3_highpart} 3500Similar, but the multiplication is unsigned. 3501 3502@cindex @code{divmod@var{m}4} instruction pattern 3503@item @samp{divmod@var{m}4} 3504Signed division that produces both a quotient and a remainder. 3505Operand 1 is divided by operand 2 to produce a quotient stored 3506in operand 0 and a remainder stored in operand 3. 3507 3508For machines with an instruction that produces both a quotient and a 3509remainder, provide a pattern for @samp{divmod@var{m}4} but do not 3510provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}. This 3511allows optimization in the relatively common case when both the quotient 3512and remainder are computed. 3513 3514If an instruction that just produces a quotient or just a remainder 3515exists and is more efficient than the instruction that produces both, 3516write the output routine of @samp{divmod@var{m}4} to call 3517@code{find_reg_note} and look for a @code{REG_UNUSED} note on the 3518quotient or remainder and generate the appropriate instruction. 3519 3520@cindex @code{udivmod@var{m}4} instruction pattern 3521@item @samp{udivmod@var{m}4} 3522Similar, but does unsigned division. 3523 3524@anchor{shift patterns} 3525@cindex @code{ashl@var{m}3} instruction pattern 3526@item @samp{ashl@var{m}3} 3527Arithmetic-shift operand 1 left by a number of bits specified by operand 35282, and store the result in operand 0. Here @var{m} is the mode of 3529operand 0 and operand 1; operand 2's mode is specified by the 3530instruction pattern, and the compiler will convert the operand to that 3531mode before generating the instruction. The meaning of out-of-range shift 3532counts can optionally be specified by @code{TARGET_SHIFT_TRUNCATION_MASK}. 3533@xref{TARGET_SHIFT_TRUNCATION_MASK}. 3534 3535@cindex @code{ashr@var{m}3} instruction pattern 3536@cindex @code{lshr@var{m}3} instruction pattern 3537@cindex @code{rotl@var{m}3} instruction pattern 3538@cindex @code{rotr@var{m}3} instruction pattern 3539@item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3} 3540Other shift and rotate instructions, analogous to the 3541@code{ashl@var{m}3} instructions. 3542 3543@cindex @code{neg@var{m}2} instruction pattern 3544@item @samp{neg@var{m}2} 3545Negate operand 1 and store the result in operand 0. 3546 3547@cindex @code{abs@var{m}2} instruction pattern 3548@item @samp{abs@var{m}2} 3549Store the absolute value of operand 1 into operand 0. 3550 3551@cindex @code{sqrt@var{m}2} instruction pattern 3552@item @samp{sqrt@var{m}2} 3553Store the square root of operand 1 into operand 0. 3554 3555The @code{sqrt} built-in function of C always uses the mode which 3556corresponds to the C data type @code{double} and the @code{sqrtf} 3557built-in function uses the mode which corresponds to the C data 3558type @code{float}. 3559 3560@cindex @code{cos@var{m}2} instruction pattern 3561@item @samp{cos@var{m}2} 3562Store the cosine of operand 1 into operand 0. 3563 3564The @code{cos} built-in function of C always uses the mode which 3565corresponds to the C data type @code{double} and the @code{cosf} 3566built-in function uses the mode which corresponds to the C data 3567type @code{float}. 3568 3569@cindex @code{sin@var{m}2} instruction pattern 3570@item @samp{sin@var{m}2} 3571Store the sine of operand 1 into operand 0. 3572 3573The @code{sin} built-in function of C always uses the mode which 3574corresponds to the C data type @code{double} and the @code{sinf} 3575built-in function uses the mode which corresponds to the C data 3576type @code{float}. 3577 3578@cindex @code{exp@var{m}2} instruction pattern 3579@item @samp{exp@var{m}2} 3580Store the exponential of operand 1 into operand 0. 3581 3582The @code{exp} built-in function of C always uses the mode which 3583corresponds to the C data type @code{double} and the @code{expf} 3584built-in function uses the mode which corresponds to the C data 3585type @code{float}. 3586 3587@cindex @code{log@var{m}2} instruction pattern 3588@item @samp{log@var{m}2} 3589Store the natural logarithm of operand 1 into operand 0. 3590 3591The @code{log} built-in function of C always uses the mode which 3592corresponds to the C data type @code{double} and the @code{logf} 3593built-in function uses the mode which corresponds to the C data 3594type @code{float}. 3595 3596@cindex @code{pow@var{m}3} instruction pattern 3597@item @samp{pow@var{m}3} 3598Store the value of operand 1 raised to the exponent operand 2 3599into operand 0. 3600 3601The @code{pow} built-in function of C always uses the mode which 3602corresponds to the C data type @code{double} and the @code{powf} 3603built-in function uses the mode which corresponds to the C data 3604type @code{float}. 3605 3606@cindex @code{atan2@var{m}3} instruction pattern 3607@item @samp{atan2@var{m}3} 3608Store the arc tangent (inverse tangent) of operand 1 divided by 3609operand 2 into operand 0, using the signs of both arguments to 3610determine the quadrant of the result. 3611 3612The @code{atan2} built-in function of C always uses the mode which 3613corresponds to the C data type @code{double} and the @code{atan2f} 3614built-in function uses the mode which corresponds to the C data 3615type @code{float}. 3616 3617@cindex @code{floor@var{m}2} instruction pattern 3618@item @samp{floor@var{m}2} 3619Store the largest integral value not greater than argument. 3620 3621The @code{floor} built-in function of C always uses the mode which 3622corresponds to the C data type @code{double} and the @code{floorf} 3623built-in function uses the mode which corresponds to the C data 3624type @code{float}. 3625 3626@cindex @code{btrunc@var{m}2} instruction pattern 3627@item @samp{btrunc@var{m}2} 3628Store the argument rounded to integer towards zero. 3629 3630The @code{trunc} built-in function of C always uses the mode which 3631corresponds to the C data type @code{double} and the @code{truncf} 3632built-in function uses the mode which corresponds to the C data 3633type @code{float}. 3634 3635@cindex @code{round@var{m}2} instruction pattern 3636@item @samp{round@var{m}2} 3637Store the argument rounded to integer away from zero. 3638 3639The @code{round} built-in function of C always uses the mode which 3640corresponds to the C data type @code{double} and the @code{roundf} 3641built-in function uses the mode which corresponds to the C data 3642type @code{float}. 3643 3644@cindex @code{ceil@var{m}2} instruction pattern 3645@item @samp{ceil@var{m}2} 3646Store the argument rounded to integer away from zero. 3647 3648The @code{ceil} built-in function of C always uses the mode which 3649corresponds to the C data type @code{double} and the @code{ceilf} 3650built-in function uses the mode which corresponds to the C data 3651type @code{float}. 3652 3653@cindex @code{nearbyint@var{m}2} instruction pattern 3654@item @samp{nearbyint@var{m}2} 3655Store the argument rounded according to the default rounding mode 3656 3657The @code{nearbyint} built-in function of C always uses the mode which 3658corresponds to the C data type @code{double} and the @code{nearbyintf} 3659built-in function uses the mode which corresponds to the C data 3660type @code{float}. 3661 3662@cindex @code{rint@var{m}2} instruction pattern 3663@item @samp{rint@var{m}2} 3664Store the argument rounded according to the default rounding mode and 3665raise the inexact exception when the result differs in value from 3666the argument 3667 3668The @code{rint} built-in function of C always uses the mode which 3669corresponds to the C data type @code{double} and the @code{rintf} 3670built-in function uses the mode which corresponds to the C data 3671type @code{float}. 3672 3673@cindex @code{copysign@var{m}3} instruction pattern 3674@item @samp{copysign@var{m}3} 3675Store a value with the magnitude of operand 1 and the sign of operand 36762 into operand 0. 3677 3678The @code{copysign} built-in function of C always uses the mode which 3679corresponds to the C data type @code{double} and the @code{copysignf} 3680built-in function uses the mode which corresponds to the C data 3681type @code{float}. 3682 3683@cindex @code{ffs@var{m}2} instruction pattern 3684@item @samp{ffs@var{m}2} 3685Store into operand 0 one plus the index of the least significant 1-bit 3686of operand 1. If operand 1 is zero, store zero. @var{m} is the mode 3687of operand 0; operand 1's mode is specified by the instruction 3688pattern, and the compiler will convert the operand to that mode before 3689generating the instruction. 3690 3691The @code{ffs} built-in function of C always uses the mode which 3692corresponds to the C data type @code{int}. 3693 3694@cindex @code{clz@var{m}2} instruction pattern 3695@item @samp{clz@var{m}2} 3696Store into operand 0 the number of leading 0-bits in @var{x}, starting 3697at the most significant bit position. If @var{x} is 0, the result is 3698undefined. @var{m} is the mode of operand 0; operand 1's mode is 3699specified by the instruction pattern, and the compiler will convert the 3700operand to that mode before generating the instruction. 3701 3702@cindex @code{ctz@var{m}2} instruction pattern 3703@item @samp{ctz@var{m}2} 3704Store into operand 0 the number of trailing 0-bits in @var{x}, starting 3705at the least significant bit position. If @var{x} is 0, the result is 3706undefined. @var{m} is the mode of operand 0; operand 1's mode is 3707specified by the instruction pattern, and the compiler will convert the 3708operand to that mode before generating the instruction. 3709 3710@cindex @code{popcount@var{m}2} instruction pattern 3711@item @samp{popcount@var{m}2} 3712Store into operand 0 the number of 1-bits in @var{x}. @var{m} is the 3713mode of operand 0; operand 1's mode is specified by the instruction 3714pattern, and the compiler will convert the operand to that mode before 3715generating the instruction. 3716 3717@cindex @code{parity@var{m}2} instruction pattern 3718@item @samp{parity@var{m}2} 3719Store into operand 0 the parity of @var{x}, i.e.@: the number of 1-bits 3720in @var{x} modulo 2. @var{m} is the mode of operand 0; operand 1's mode 3721is specified by the instruction pattern, and the compiler will convert 3722the operand to that mode before generating the instruction. 3723 3724@cindex @code{one_cmpl@var{m}2} instruction pattern 3725@item @samp{one_cmpl@var{m}2} 3726Store the bitwise-complement of operand 1 into operand 0. 3727 3728@cindex @code{cmp@var{m}} instruction pattern 3729@item @samp{cmp@var{m}} 3730Compare operand 0 and operand 1, and set the condition codes. 3731The RTL pattern should look like this: 3732 3733@smallexample 3734(set (cc0) (compare (match_operand:@var{m} 0 @dots{}) 3735 (match_operand:@var{m} 1 @dots{}))) 3736@end smallexample 3737 3738@cindex @code{tst@var{m}} instruction pattern 3739@item @samp{tst@var{m}} 3740Compare operand 0 against zero, and set the condition codes. 3741The RTL pattern should look like this: 3742 3743@smallexample 3744(set (cc0) (match_operand:@var{m} 0 @dots{})) 3745@end smallexample 3746 3747@samp{tst@var{m}} patterns should not be defined for machines that do 3748not use @code{(cc0)}. Doing so would confuse the optimizer since it 3749would no longer be clear which @code{set} operations were comparisons. 3750The @samp{cmp@var{m}} patterns should be used instead. 3751 3752@cindex @code{movmem@var{m}} instruction pattern 3753@item @samp{movmem@var{m}} 3754Block move instruction. The destination and source blocks of memory 3755are the first two operands, and both are @code{mem:BLK}s with an 3756address in mode @code{Pmode}. 3757 3758The number of bytes to move is the third operand, in mode @var{m}. 3759Usually, you specify @code{word_mode} for @var{m}. However, if you can 3760generate better code knowing the range of valid lengths is smaller than 3761those representable in a full word, you should provide a pattern with a 3762mode corresponding to the range of values you can handle efficiently 3763(e.g., @code{QImode} for values in the range 0--127; note we avoid numbers 3764that appear negative) and also a pattern with @code{word_mode}. 3765 3766The fourth operand is the known shared alignment of the source and 3767destination, in the form of a @code{const_int} rtx. Thus, if the 3768compiler knows that both source and destination are word-aligned, 3769it may provide the value 4 for this operand. 3770 3771Descriptions of multiple @code{movmem@var{m}} patterns can only be 3772beneficial if the patterns for smaller modes have fewer restrictions 3773on their first, second and fourth operands. Note that the mode @var{m} 3774in @code{movmem@var{m}} does not impose any restriction on the mode of 3775individually moved data units in the block. 3776 3777These patterns need not give special consideration to the possibility 3778that the source and destination strings might overlap. 3779 3780@cindex @code{movstr} instruction pattern 3781@item @samp{movstr} 3782String copy instruction, with @code{stpcpy} semantics. Operand 0 is 3783an output operand in mode @code{Pmode}. The addresses of the 3784destination and source strings are operands 1 and 2, and both are 3785@code{mem:BLK}s with addresses in mode @code{Pmode}. The execution of 3786the expansion of this pattern should store in operand 0 the address in 3787which the @code{NUL} terminator was stored in the destination string. 3788 3789@cindex @code{setmem@var{m}} instruction pattern 3790@item @samp{setmem@var{m}} 3791Block set instruction. The destination string is the first operand, 3792given as a @code{mem:BLK} whose address is in mode @code{Pmode}. The 3793number of bytes to set is the second operand, in mode @var{m}. The value to 3794initialize the memory with is the third operand. Targets that only support the 3795clearing of memory should reject any value that is not the constant 0. See 3796@samp{movmem@var{m}} for a discussion of the choice of mode. 3797 3798The fourth operand is the known alignment of the destination, in the form 3799of a @code{const_int} rtx. Thus, if the compiler knows that the 3800destination is word-aligned, it may provide the value 4 for this 3801operand. 3802 3803The use for multiple @code{setmem@var{m}} is as for @code{movmem@var{m}}. 3804 3805@cindex @code{cmpstrn@var{m}} instruction pattern 3806@item @samp{cmpstrn@var{m}} 3807String compare instruction, with five operands. Operand 0 is the output; 3808it has mode @var{m}. The remaining four operands are like the operands 3809of @samp{movmem@var{m}}. The two memory blocks specified are compared 3810byte by byte in lexicographic order starting at the beginning of each 3811string. The instruction is not allowed to prefetch more than one byte 3812at a time since either string may end in the first byte and reading past 3813that may access an invalid page or segment and cause a fault. The 3814effect of the instruction is to store a value in operand 0 whose sign 3815indicates the result of the comparison. 3816 3817@cindex @code{cmpstr@var{m}} instruction pattern 3818@item @samp{cmpstr@var{m}} 3819String compare instruction, without known maximum length. Operand 0 is the 3820output; it has mode @var{m}. The second and third operand are the blocks of 3821memory to be compared; both are @code{mem:BLK} with an address in mode 3822@code{Pmode}. 3823 3824The fourth operand is the known shared alignment of the source and 3825destination, in the form of a @code{const_int} rtx. Thus, if the 3826compiler knows that both source and destination are word-aligned, 3827it may provide the value 4 for this operand. 3828 3829The two memory blocks specified are compared byte by byte in lexicographic 3830order starting at the beginning of each string. The instruction is not allowed 3831to prefetch more than one byte at a time since either string may end in the 3832first byte and reading past that may access an invalid page or segment and 3833cause a fault. The effect of the instruction is to store a value in operand 0 3834whose sign indicates the result of the comparison. 3835 3836@cindex @code{cmpmem@var{m}} instruction pattern 3837@item @samp{cmpmem@var{m}} 3838Block compare instruction, with five operands like the operands 3839of @samp{cmpstr@var{m}}. The two memory blocks specified are compared 3840byte by byte in lexicographic order starting at the beginning of each 3841block. Unlike @samp{cmpstr@var{m}} the instruction can prefetch 3842any bytes in the two memory blocks. The effect of the instruction is 3843to store a value in operand 0 whose sign indicates the result of the 3844comparison. 3845 3846@cindex @code{strlen@var{m}} instruction pattern 3847@item @samp{strlen@var{m}} 3848Compute the length of a string, with three operands. 3849Operand 0 is the result (of mode @var{m}), operand 1 is 3850a @code{mem} referring to the first character of the string, 3851operand 2 is the character to search for (normally zero), 3852and operand 3 is a constant describing the known alignment 3853of the beginning of the string. 3854 3855@cindex @code{float@var{mn}2} instruction pattern 3856@item @samp{float@var{m}@var{n}2} 3857Convert signed integer operand 1 (valid for fixed point mode @var{m}) to 3858floating point mode @var{n} and store in operand 0 (which has mode 3859@var{n}). 3860 3861@cindex @code{floatuns@var{mn}2} instruction pattern 3862@item @samp{floatuns@var{m}@var{n}2} 3863Convert unsigned integer operand 1 (valid for fixed point mode @var{m}) 3864to floating point mode @var{n} and store in operand 0 (which has mode 3865@var{n}). 3866 3867@cindex @code{fix@var{mn}2} instruction pattern 3868@item @samp{fix@var{m}@var{n}2} 3869Convert operand 1 (valid for floating point mode @var{m}) to fixed 3870point mode @var{n} as a signed number and store in operand 0 (which 3871has mode @var{n}). This instruction's result is defined only when 3872the value of operand 1 is an integer. 3873 3874If the machine description defines this pattern, it also needs to 3875define the @code{ftrunc} pattern. 3876 3877@cindex @code{fixuns@var{mn}2} instruction pattern 3878@item @samp{fixuns@var{m}@var{n}2} 3879Convert operand 1 (valid for floating point mode @var{m}) to fixed 3880point mode @var{n} as an unsigned number and store in operand 0 (which 3881has mode @var{n}). This instruction's result is defined only when the 3882value of operand 1 is an integer. 3883 3884@cindex @code{ftrunc@var{m}2} instruction pattern 3885@item @samp{ftrunc@var{m}2} 3886Convert operand 1 (valid for floating point mode @var{m}) to an 3887integer value, still represented in floating point mode @var{m}, and 3888store it in operand 0 (valid for floating point mode @var{m}). 3889 3890@cindex @code{fix_trunc@var{mn}2} instruction pattern 3891@item @samp{fix_trunc@var{m}@var{n}2} 3892Like @samp{fix@var{m}@var{n}2} but works for any floating point value 3893of mode @var{m} by converting the value to an integer. 3894 3895@cindex @code{fixuns_trunc@var{mn}2} instruction pattern 3896@item @samp{fixuns_trunc@var{m}@var{n}2} 3897Like @samp{fixuns@var{m}@var{n}2} but works for any floating point 3898value of mode @var{m} by converting the value to an integer. 3899 3900@cindex @code{trunc@var{mn}2} instruction pattern 3901@item @samp{trunc@var{m}@var{n}2} 3902Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and 3903store in operand 0 (which has mode @var{n}). Both modes must be fixed 3904point or both floating point. 3905 3906@cindex @code{extend@var{mn}2} instruction pattern 3907@item @samp{extend@var{m}@var{n}2} 3908Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and 3909store in operand 0 (which has mode @var{n}). Both modes must be fixed 3910point or both floating point. 3911 3912@cindex @code{zero_extend@var{mn}2} instruction pattern 3913@item @samp{zero_extend@var{m}@var{n}2} 3914Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and 3915store in operand 0 (which has mode @var{n}). Both modes must be fixed 3916point. 3917 3918@cindex @code{extv} instruction pattern 3919@item @samp{extv} 3920Extract a bit-field from operand 1 (a register or memory operand), where 3921operand 2 specifies the width in bits and operand 3 the starting bit, 3922and store it in operand 0. Operand 0 must have mode @code{word_mode}. 3923Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often 3924@code{word_mode} is allowed only for registers. Operands 2 and 3 must 3925be valid for @code{word_mode}. 3926 3927The RTL generation pass generates this instruction only with constants 3928for operands 2 and 3 and the constant is never zero for operand 2. 3929 3930The bit-field value is sign-extended to a full word integer 3931before it is stored in operand 0. 3932 3933@cindex @code{extzv} instruction pattern 3934@item @samp{extzv} 3935Like @samp{extv} except that the bit-field value is zero-extended. 3936 3937@cindex @code{insv} instruction pattern 3938@item @samp{insv} 3939Store operand 3 (which must be valid for @code{word_mode}) into a 3940bit-field in operand 0, where operand 1 specifies the width in bits and 3941operand 2 the starting bit. Operand 0 may have mode @code{byte_mode} or 3942@code{word_mode}; often @code{word_mode} is allowed only for registers. 3943Operands 1 and 2 must be valid for @code{word_mode}. 3944 3945The RTL generation pass generates this instruction only with constants 3946for operands 1 and 2 and the constant is never zero for operand 1. 3947 3948@cindex @code{mov@var{mode}cc} instruction pattern 3949@item @samp{mov@var{mode}cc} 3950Conditionally move operand 2 or operand 3 into operand 0 according to the 3951comparison in operand 1. If the comparison is true, operand 2 is moved 3952into operand 0, otherwise operand 3 is moved. 3953 3954The mode of the operands being compared need not be the same as the operands 3955being moved. Some machines, sparc64 for example, have instructions that 3956conditionally move an integer value based on the floating point condition 3957codes and vice versa. 3958 3959If the machine does not have conditional move instructions, do not 3960define these patterns. 3961 3962@cindex @code{add@var{mode}cc} instruction pattern 3963@item @samp{add@var{mode}cc} 3964Similar to @samp{mov@var{mode}cc} but for conditional addition. Conditionally 3965move operand 2 or (operands 2 + operand 3) into operand 0 according to the 3966comparison in operand 1. If the comparison is true, operand 2 is moved into 3967operand 0, otherwise (operand 2 + operand 3) is moved. 3968 3969@cindex @code{s@var{cond}} instruction pattern 3970@item @samp{s@var{cond}} 3971Store zero or nonzero in the operand according to the condition codes. 3972Value stored is nonzero iff the condition @var{cond} is true. 3973@var{cond} is the name of a comparison operation expression code, such 3974as @code{eq}, @code{lt} or @code{leu}. 3975 3976You specify the mode that the operand must have when you write the 3977@code{match_operand} expression. The compiler automatically sees 3978which mode you have used and supplies an operand of that mode. 3979 3980The value stored for a true condition must have 1 as its low bit, or 3981else must be negative. Otherwise the instruction is not suitable and 3982you should omit it from the machine description. You describe to the 3983compiler exactly which value is stored by defining the macro 3984@code{STORE_FLAG_VALUE} (@pxref{Misc}). If a description cannot be 3985found that can be used for all the @samp{s@var{cond}} patterns, you 3986should omit those operations from the machine description. 3987 3988These operations may fail, but should do so only in relatively 3989uncommon cases; if they would fail for common cases involving 3990integer comparisons, it is best to omit these patterns. 3991 3992If these operations are omitted, the compiler will usually generate code 3993that copies the constant one to the target and branches around an 3994assignment of zero to the target. If this code is more efficient than 3995the potential instructions used for the @samp{s@var{cond}} pattern 3996followed by those required to convert the result into a 1 or a zero in 3997@code{SImode}, you should omit the @samp{s@var{cond}} operations from 3998the machine description. 3999 4000@cindex @code{b@var{cond}} instruction pattern 4001@item @samp{b@var{cond}} 4002Conditional branch instruction. Operand 0 is a @code{label_ref} that 4003refers to the label to jump to. Jump if the condition codes meet 4004condition @var{cond}. 4005 4006Some machines do not follow the model assumed here where a comparison 4007instruction is followed by a conditional branch instruction. In that 4008case, the @samp{cmp@var{m}} (and @samp{tst@var{m}}) patterns should 4009simply store the operands away and generate all the required insns in a 4010@code{define_expand} (@pxref{Expander Definitions}) for the conditional 4011branch operations. All calls to expand @samp{b@var{cond}} patterns are 4012immediately preceded by calls to expand either a @samp{cmp@var{m}} 4013pattern or a @samp{tst@var{m}} pattern. 4014 4015Machines that use a pseudo register for the condition code value, or 4016where the mode used for the comparison depends on the condition being 4017tested, should also use the above mechanism. @xref{Jump Patterns}. 4018 4019The above discussion also applies to the @samp{mov@var{mode}cc} and 4020@samp{s@var{cond}} patterns. 4021 4022@cindex @code{cbranch@var{mode}4} instruction pattern 4023@item @samp{cbranch@var{mode}4} 4024Conditional branch instruction combined with a compare instruction. 4025Operand 0 is a comparison operator. Operand 1 and operand 2 are the 4026first and second operands of the comparison, respectively. Operand 3 4027is a @code{label_ref} that refers to the label to jump to. 4028 4029@cindex @code{jump} instruction pattern 4030@item @samp{jump} 4031A jump inside a function; an unconditional branch. Operand 0 is the 4032@code{label_ref} of the label to jump to. This pattern name is mandatory 4033on all machines. 4034 4035@cindex @code{call} instruction pattern 4036@item @samp{call} 4037Subroutine call instruction returning no value. Operand 0 is the 4038function to call; operand 1 is the number of bytes of arguments pushed 4039as a @code{const_int}; operand 2 is the number of registers used as 4040operands. 4041 4042On most machines, operand 2 is not actually stored into the RTL 4043pattern. It is supplied for the sake of some RISC machines which need 4044to put this information into the assembler code; they can put it in 4045the RTL instead of operand 1. 4046 4047Operand 0 should be a @code{mem} RTX whose address is the address of the 4048function. Note, however, that this address can be a @code{symbol_ref} 4049expression even if it would not be a legitimate memory address on the 4050target machine. If it is also not a valid argument for a call 4051instruction, the pattern for this operation should be a 4052@code{define_expand} (@pxref{Expander Definitions}) that places the 4053address into a register and uses that register in the call instruction. 4054 4055@cindex @code{call_value} instruction pattern 4056@item @samp{call_value} 4057Subroutine call instruction returning a value. Operand 0 is the hard 4058register in which the value is returned. There are three more 4059operands, the same as the three operands of the @samp{call} 4060instruction (but with numbers increased by one). 4061 4062Subroutines that return @code{BLKmode} objects use the @samp{call} 4063insn. 4064 4065@cindex @code{call_pop} instruction pattern 4066@cindex @code{call_value_pop} instruction pattern 4067@item @samp{call_pop}, @samp{call_value_pop} 4068Similar to @samp{call} and @samp{call_value}, except used if defined and 4069if @code{RETURN_POPS_ARGS} is nonzero. They should emit a @code{parallel} 4070that contains both the function call and a @code{set} to indicate the 4071adjustment made to the frame pointer. 4072 4073For machines where @code{RETURN_POPS_ARGS} can be nonzero, the use of these 4074patterns increases the number of functions for which the frame pointer 4075can be eliminated, if desired. 4076 4077@cindex @code{untyped_call} instruction pattern 4078@item @samp{untyped_call} 4079Subroutine call instruction returning a value of any type. Operand 0 is 4080the function to call; operand 1 is a memory location where the result of 4081calling the function is to be stored; operand 2 is a @code{parallel} 4082expression where each element is a @code{set} expression that indicates 4083the saving of a function return value into the result block. 4084 4085This instruction pattern should be defined to support 4086@code{__builtin_apply} on machines where special instructions are needed 4087to call a subroutine with arbitrary arguments or to save the value 4088returned. This instruction pattern is required on machines that have 4089multiple registers that can hold a return value 4090(i.e.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register). 4091 4092@cindex @code{return} instruction pattern 4093@item @samp{return} 4094Subroutine return instruction. This instruction pattern name should be 4095defined only if a single instruction can do all the work of returning 4096from a function. 4097 4098Like the @samp{mov@var{m}} patterns, this pattern is also used after the 4099RTL generation phase. In this case it is to support machines where 4100multiple instructions are usually needed to return from a function, but 4101some class of functions only requires one instruction to implement a 4102return. Normally, the applicable functions are those which do not need 4103to save any registers or allocate stack space. 4104 4105@findex reload_completed 4106@findex leaf_function_p 4107For such machines, the condition specified in this pattern should only 4108be true when @code{reload_completed} is nonzero and the function's 4109epilogue would only be a single instruction. For machines with register 4110windows, the routine @code{leaf_function_p} may be used to determine if 4111a register window push is required. 4112 4113Machines that have conditional return instructions should define patterns 4114such as 4115 4116@smallexample 4117(define_insn "" 4118 [(set (pc) 4119 (if_then_else (match_operator 4120 0 "comparison_operator" 4121 [(cc0) (const_int 0)]) 4122 (return) 4123 (pc)))] 4124 "@var{condition}" 4125 "@dots{}") 4126@end smallexample 4127 4128where @var{condition} would normally be the same condition specified on the 4129named @samp{return} pattern. 4130 4131@cindex @code{untyped_return} instruction pattern 4132@item @samp{untyped_return} 4133Untyped subroutine return instruction. This instruction pattern should 4134be defined to support @code{__builtin_return} on machines where special 4135instructions are needed to return a value of any type. 4136 4137Operand 0 is a memory location where the result of calling a function 4138with @code{__builtin_apply} is stored; operand 1 is a @code{parallel} 4139expression where each element is a @code{set} expression that indicates 4140the restoring of a function return value from the result block. 4141 4142@cindex @code{nop} instruction pattern 4143@item @samp{nop} 4144No-op instruction. This instruction pattern name should always be defined 4145to output a no-op in assembler code. @code{(const_int 0)} will do as an 4146RTL pattern. 4147 4148@cindex @code{indirect_jump} instruction pattern 4149@item @samp{indirect_jump} 4150An instruction to jump to an address which is operand zero. 4151This pattern name is mandatory on all machines. 4152 4153@cindex @code{casesi} instruction pattern 4154@item @samp{casesi} 4155Instruction to jump through a dispatch table, including bounds checking. 4156This instruction takes five operands: 4157 4158@enumerate 4159@item 4160The index to dispatch on, which has mode @code{SImode}. 4161 4162@item 4163The lower bound for indices in the table, an integer constant. 4164 4165@item 4166The total range of indices in the table---the largest index 4167minus the smallest one (both inclusive). 4168 4169@item 4170A label that precedes the table itself. 4171 4172@item 4173A label to jump to if the index has a value outside the bounds. 4174@end enumerate 4175 4176The table is a @code{addr_vec} or @code{addr_diff_vec} inside of a 4177@code{jump_insn}. The number of elements in the table is one plus the 4178difference between the upper bound and the lower bound. 4179 4180@cindex @code{tablejump} instruction pattern 4181@item @samp{tablejump} 4182Instruction to jump to a variable address. This is a low-level 4183capability which can be used to implement a dispatch table when there 4184is no @samp{casesi} pattern. 4185 4186This pattern requires two operands: the address or offset, and a label 4187which should immediately precede the jump table. If the macro 4188@code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first 4189operand is an offset which counts from the address of the table; otherwise, 4190it is an absolute address to jump to. In either case, the first operand has 4191mode @code{Pmode}. 4192 4193The @samp{tablejump} insn is always the last insn before the jump 4194table it uses. Its assembler code normally has no need to use the 4195second operand, but you should incorporate it in the RTL pattern so 4196that the jump optimizer will not delete the table as unreachable code. 4197 4198 4199@cindex @code{decrement_and_branch_until_zero} instruction pattern 4200@item @samp{decrement_and_branch_until_zero} 4201Conditional branch instruction that decrements a register and 4202jumps if the register is nonzero. Operand 0 is the register to 4203decrement and test; operand 1 is the label to jump to if the 4204register is nonzero. @xref{Looping Patterns}. 4205 4206This optional instruction pattern is only used by the combiner, 4207typically for loops reversed by the loop optimizer when strength 4208reduction is enabled. 4209 4210@cindex @code{doloop_end} instruction pattern 4211@item @samp{doloop_end} 4212Conditional branch instruction that decrements a register and jumps if 4213the register is nonzero. This instruction takes five operands: Operand 42140 is the register to decrement and test; operand 1 is the number of loop 4215iterations as a @code{const_int} or @code{const0_rtx} if this cannot be 4216determined until run-time; operand 2 is the actual or estimated maximum 4217number of iterations as a @code{const_int}; operand 3 is the number of 4218enclosed loops as a @code{const_int} (an innermost loop has a value of 42191); operand 4 is the label to jump to if the register is nonzero. 4220@xref{Looping Patterns}. 4221 4222This optional instruction pattern should be defined for machines with 4223low-overhead looping instructions as the loop optimizer will try to 4224modify suitable loops to utilize it. If nested low-overhead looping is 4225not supported, use a @code{define_expand} (@pxref{Expander Definitions}) 4226and make the pattern fail if operand 3 is not @code{const1_rtx}. 4227Similarly, if the actual or estimated maximum number of iterations is 4228too large for this instruction, make it fail. 4229 4230@cindex @code{doloop_begin} instruction pattern 4231@item @samp{doloop_begin} 4232Companion instruction to @code{doloop_end} required for machines that 4233need to perform some initialization, such as loading special registers 4234used by a low-overhead looping instruction. If initialization insns do 4235not always need to be emitted, use a @code{define_expand} 4236(@pxref{Expander Definitions}) and make it fail. 4237 4238 4239@cindex @code{canonicalize_funcptr_for_compare} instruction pattern 4240@item @samp{canonicalize_funcptr_for_compare} 4241Canonicalize the function pointer in operand 1 and store the result 4242into operand 0. 4243 4244Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1 4245may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc 4246and also has mode @code{Pmode}. 4247 4248Canonicalization of a function pointer usually involves computing 4249the address of the function which would be called if the function 4250pointer were used in an indirect call. 4251 4252Only define this pattern if function pointers on the target machine 4253can have different values but still call the same function when 4254used in an indirect call. 4255 4256@cindex @code{save_stack_block} instruction pattern 4257@cindex @code{save_stack_function} instruction pattern 4258@cindex @code{save_stack_nonlocal} instruction pattern 4259@cindex @code{restore_stack_block} instruction pattern 4260@cindex @code{restore_stack_function} instruction pattern 4261@cindex @code{restore_stack_nonlocal} instruction pattern 4262@item @samp{save_stack_block} 4263@itemx @samp{save_stack_function} 4264@itemx @samp{save_stack_nonlocal} 4265@itemx @samp{restore_stack_block} 4266@itemx @samp{restore_stack_function} 4267@itemx @samp{restore_stack_nonlocal} 4268Most machines save and restore the stack pointer by copying it to or 4269from an object of mode @code{Pmode}. Do not define these patterns on 4270such machines. 4271 4272Some machines require special handling for stack pointer saves and 4273restores. On those machines, define the patterns corresponding to the 4274non-standard cases by using a @code{define_expand} (@pxref{Expander 4275Definitions}) that produces the required insns. The three types of 4276saves and restores are: 4277 4278@enumerate 4279@item 4280@samp{save_stack_block} saves the stack pointer at the start of a block 4281that allocates a variable-sized object, and @samp{restore_stack_block} 4282restores the stack pointer when the block is exited. 4283 4284@item 4285@samp{save_stack_function} and @samp{restore_stack_function} do a 4286similar job for the outermost block of a function and are used when the 4287function allocates variable-sized objects or calls @code{alloca}. Only 4288the epilogue uses the restored stack pointer, allowing a simpler save or 4289restore sequence on some machines. 4290 4291@item 4292@samp{save_stack_nonlocal} is used in functions that contain labels 4293branched to by nested functions. It saves the stack pointer in such a 4294way that the inner function can use @samp{restore_stack_nonlocal} to 4295restore the stack pointer. The compiler generates code to restore the 4296frame and argument pointer registers, but some machines require saving 4297and restoring additional data such as register window information or 4298stack backchains. Place insns in these patterns to save and restore any 4299such required data. 4300@end enumerate 4301 4302When saving the stack pointer, operand 0 is the save area and operand 1 4303is the stack pointer. The mode used to allocate the save area defaults 4304to @code{Pmode} but you can override that choice by defining the 4305@code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}). You must 4306specify an integral mode, or @code{VOIDmode} if no save area is needed 4307for a particular type of save (either because no save is needed or 4308because a machine-specific save area can be used). Operand 0 is the 4309stack pointer and operand 1 is the save area for restore operations. If 4310@samp{save_stack_block} is defined, operand 0 must not be 4311@code{VOIDmode} since these saves can be arbitrarily nested. 4312 4313A save area is a @code{mem} that is at a constant offset from 4314@code{virtual_stack_vars_rtx} when the stack pointer is saved for use by 4315nonlocal gotos and a @code{reg} in the other two cases. 4316 4317@cindex @code{allocate_stack} instruction pattern 4318@item @samp{allocate_stack} 4319Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from 4320the stack pointer to create space for dynamically allocated data. 4321 4322Store the resultant pointer to this space into operand 0. If you 4323are allocating space from the main stack, do this by emitting a 4324move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0. 4325If you are allocating the space elsewhere, generate code to copy the 4326location of the space to operand 0. In the latter case, you must 4327ensure this space gets freed when the corresponding space on the main 4328stack is free. 4329 4330Do not define this pattern if all that must be done is the subtraction. 4331Some machines require other operations such as stack probes or 4332maintaining the back chain. Define this pattern to emit those 4333operations in addition to updating the stack pointer. 4334 4335@cindex @code{check_stack} instruction pattern 4336@item @samp{check_stack} 4337If stack checking cannot be done on your system by probing the stack with 4338a load or store instruction (@pxref{Stack Checking}), define this pattern 4339to perform the needed check and signaling an error if the stack 4340has overflowed. The single operand is the location in the stack furthest 4341from the current stack pointer that you need to validate. Normally, 4342on machines where this pattern is needed, you would obtain the stack 4343limit from a global or thread-specific variable or register. 4344 4345@cindex @code{nonlocal_goto} instruction pattern 4346@item @samp{nonlocal_goto} 4347Emit code to generate a non-local goto, e.g., a jump from one function 4348to a label in an outer function. This pattern has four arguments, 4349each representing a value to be used in the jump. The first 4350argument is to be loaded into the frame pointer, the second is 4351the address to branch to (code to dispatch to the actual label), 4352the third is the address of a location where the stack is saved, 4353and the last is the address of the label, to be placed in the 4354location for the incoming static chain. 4355 4356On most machines you need not define this pattern, since GCC will 4357already generate the correct code, which is to load the frame pointer 4358and static chain, restore the stack (using the 4359@samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly 4360to the dispatcher. You need only define this pattern if this code will 4361not work on your machine. 4362 4363@cindex @code{nonlocal_goto_receiver} instruction pattern 4364@item @samp{nonlocal_goto_receiver} 4365This pattern, if defined, contains code needed at the target of a 4366nonlocal goto after the code already generated by GCC@. You will not 4367normally need to define this pattern. A typical reason why you might 4368need this pattern is if some value, such as a pointer to a global table, 4369must be restored when the frame pointer is restored. Note that a nonlocal 4370goto only occurs within a unit-of-translation, so a global table pointer 4371that is shared by all functions of a given module need not be restored. 4372There are no arguments. 4373 4374@cindex @code{exception_receiver} instruction pattern 4375@item @samp{exception_receiver} 4376This pattern, if defined, contains code needed at the site of an 4377exception handler that isn't needed at the site of a nonlocal goto. You 4378will not normally need to define this pattern. A typical reason why you 4379might need this pattern is if some value, such as a pointer to a global 4380table, must be restored after control flow is branched to the handler of 4381an exception. There are no arguments. 4382 4383@cindex @code{builtin_setjmp_setup} instruction pattern 4384@item @samp{builtin_setjmp_setup} 4385This pattern, if defined, contains additional code needed to initialize 4386the @code{jmp_buf}. You will not normally need to define this pattern. 4387A typical reason why you might need this pattern is if some value, such 4388as a pointer to a global table, must be restored. Though it is 4389preferred that the pointer value be recalculated if possible (given the 4390address of a label for instance). The single argument is a pointer to 4391the @code{jmp_buf}. Note that the buffer is five words long and that 4392the first three are normally used by the generic mechanism. 4393 4394@cindex @code{builtin_setjmp_receiver} instruction pattern 4395@item @samp{builtin_setjmp_receiver} 4396This pattern, if defined, contains code needed at the site of an 4397built-in setjmp that isn't needed at the site of a nonlocal goto. You 4398will not normally need to define this pattern. A typical reason why you 4399might need this pattern is if some value, such as a pointer to a global 4400table, must be restored. It takes one argument, which is the label 4401to which builtin_longjmp transfered control; this pattern may be emitted 4402at a small offset from that label. 4403 4404@cindex @code{builtin_longjmp} instruction pattern 4405@item @samp{builtin_longjmp} 4406This pattern, if defined, performs the entire action of the longjmp. 4407You will not normally need to define this pattern unless you also define 4408@code{builtin_setjmp_setup}. The single argument is a pointer to the 4409@code{jmp_buf}. 4410 4411@cindex @code{eh_return} instruction pattern 4412@item @samp{eh_return} 4413This pattern, if defined, affects the way @code{__builtin_eh_return}, 4414and thence the call frame exception handling library routines, are 4415built. It is intended to handle non-trivial actions needed along 4416the abnormal return path. 4417 4418The address of the exception handler to which the function should return 4419is passed as operand to this pattern. It will normally need to copied by 4420the pattern to some special register or memory location. 4421If the pattern needs to determine the location of the target call 4422frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX}, 4423if defined; it will have already been assigned. 4424 4425If this pattern is not defined, the default action will be to simply 4426copy the return address to @code{EH_RETURN_HANDLER_RTX}. Either 4427that macro or this pattern needs to be defined if call frame exception 4428handling is to be used. 4429 4430@cindex @code{prologue} instruction pattern 4431@anchor{prologue instruction pattern} 4432@item @samp{prologue} 4433This pattern, if defined, emits RTL for entry to a function. The function 4434entry is responsible for setting up the stack frame, initializing the frame 4435pointer register, saving callee saved registers, etc. 4436 4437Using a prologue pattern is generally preferred over defining 4438@code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue. 4439 4440The @code{prologue} pattern is particularly useful for targets which perform 4441instruction scheduling. 4442 4443@cindex @code{epilogue} instruction pattern 4444@anchor{epilogue instruction pattern} 4445@item @samp{epilogue} 4446This pattern emits RTL for exit from a function. The function 4447exit is responsible for deallocating the stack frame, restoring callee saved 4448registers and emitting the return instruction. 4449 4450Using an epilogue pattern is generally preferred over defining 4451@code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue. 4452 4453The @code{epilogue} pattern is particularly useful for targets which perform 4454instruction scheduling or which have delay slots for their return instruction. 4455 4456@cindex @code{sibcall_epilogue} instruction pattern 4457@item @samp{sibcall_epilogue} 4458This pattern, if defined, emits RTL for exit from a function without the final 4459branch back to the calling function. This pattern will be emitted before any 4460sibling call (aka tail call) sites. 4461 4462The @code{sibcall_epilogue} pattern must not clobber any arguments used for 4463parameter passing or any stack slots for arguments passed to the current 4464function. 4465 4466@cindex @code{trap} instruction pattern 4467@item @samp{trap} 4468This pattern, if defined, signals an error, typically by causing some 4469kind of signal to be raised. Among other places, it is used by the Java 4470front end to signal `invalid array index' exceptions. 4471 4472@cindex @code{conditional_trap} instruction pattern 4473@item @samp{conditional_trap} 4474Conditional trap instruction. Operand 0 is a piece of RTL which 4475performs a comparison. Operand 1 is the trap code, an integer. 4476 4477A typical @code{conditional_trap} pattern looks like 4478 4479@smallexample 4480(define_insn "conditional_trap" 4481 [(trap_if (match_operator 0 "trap_operator" 4482 [(cc0) (const_int 0)]) 4483 (match_operand 1 "const_int_operand" "i"))] 4484 "" 4485 "@dots{}") 4486@end smallexample 4487 4488@cindex @code{prefetch} instruction pattern 4489@item @samp{prefetch} 4490 4491This pattern, if defined, emits code for a non-faulting data prefetch 4492instruction. Operand 0 is the address of the memory to prefetch. Operand 1 4493is a constant 1 if the prefetch is preparing for a write to the memory 4494address, or a constant 0 otherwise. Operand 2 is the expected degree of 4495temporal locality of the data and is a value between 0 and 3, inclusive; 0 4496means that the data has no temporal locality, so it need not be left in the 4497cache after the access; 3 means that the data has a high degree of temporal 4498locality and should be left in all levels of cache possible; 1 and 2 mean, 4499respectively, a low or moderate degree of temporal locality. 4500 4501Targets that do not support write prefetches or locality hints can ignore 4502the values of operands 1 and 2. 4503 4504@cindex @code{memory_barrier} instruction pattern 4505@item @samp{memory_barrier} 4506 4507If the target memory model is not fully synchronous, then this pattern 4508should be defined to an instruction that orders both loads and stores 4509before the instruction with respect to loads and stores after the instruction. 4510This pattern has no operands. 4511 4512@cindex @code{sync_compare_and_swap@var{mode}} instruction pattern 4513@item @samp{sync_compare_and_swap@var{mode}} 4514 4515This pattern, if defined, emits code for an atomic compare-and-swap 4516operation. Operand 1 is the memory on which the atomic operation is 4517performed. Operand 2 is the ``old'' value to be compared against the 4518current contents of the memory location. Operand 3 is the ``new'' value 4519to store in the memory if the compare succeeds. Operand 0 is the result 4520of the operation; it should contain the contents of the memory 4521before the operation. If the compare succeeds, this should obviously be 4522a copy of operand 2. 4523 4524This pattern must show that both operand 0 and operand 1 are modified. 4525 4526This pattern must issue any memory barrier instructions such that all 4527memory operations before the atomic operation occur before the atomic 4528operation and all memory operations after the atomic operation occur 4529after the atomic operation. 4530 4531@cindex @code{sync_compare_and_swap_cc@var{mode}} instruction pattern 4532@item @samp{sync_compare_and_swap_cc@var{mode}} 4533 4534This pattern is just like @code{sync_compare_and_swap@var{mode}}, except 4535it should act as if compare part of the compare-and-swap were issued via 4536@code{cmp@var{m}}. This comparison will only be used with @code{EQ} and 4537@code{NE} branches and @code{setcc} operations. 4538 4539Some targets do expose the success or failure of the compare-and-swap 4540operation via the status flags. Ideally we wouldn't need a separate 4541named pattern in order to take advantage of this, but the combine pass 4542does not handle patterns with multiple sets, which is required by 4543definition for @code{sync_compare_and_swap@var{mode}}. 4544 4545@cindex @code{sync_add@var{mode}} instruction pattern 4546@cindex @code{sync_sub@var{mode}} instruction pattern 4547@cindex @code{sync_ior@var{mode}} instruction pattern 4548@cindex @code{sync_and@var{mode}} instruction pattern 4549@cindex @code{sync_xor@var{mode}} instruction pattern 4550@cindex @code{sync_nand@var{mode}} instruction pattern 4551@item @samp{sync_add@var{mode}}, @samp{sync_sub@var{mode}} 4552@itemx @samp{sync_ior@var{mode}}, @samp{sync_and@var{mode}} 4553@itemx @samp{sync_xor@var{mode}}, @samp{sync_nand@var{mode}} 4554 4555These patterns emit code for an atomic operation on memory. 4556Operand 0 is the memory on which the atomic operation is performed. 4557Operand 1 is the second operand to the binary operator. 4558 4559The ``nand'' operation is @code{~op0 & op1}. 4560 4561This pattern must issue any memory barrier instructions such that all 4562memory operations before the atomic operation occur before the atomic 4563operation and all memory operations after the atomic operation occur 4564after the atomic operation. 4565 4566If these patterns are not defined, the operation will be constructed 4567from a compare-and-swap operation, if defined. 4568 4569@cindex @code{sync_old_add@var{mode}} instruction pattern 4570@cindex @code{sync_old_sub@var{mode}} instruction pattern 4571@cindex @code{sync_old_ior@var{mode}} instruction pattern 4572@cindex @code{sync_old_and@var{mode}} instruction pattern 4573@cindex @code{sync_old_xor@var{mode}} instruction pattern 4574@cindex @code{sync_old_nand@var{mode}} instruction pattern 4575@item @samp{sync_old_add@var{mode}}, @samp{sync_old_sub@var{mode}} 4576@itemx @samp{sync_old_ior@var{mode}}, @samp{sync_old_and@var{mode}} 4577@itemx @samp{sync_old_xor@var{mode}}, @samp{sync_old_nand@var{mode}} 4578 4579These patterns are emit code for an atomic operation on memory, 4580and return the value that the memory contained before the operation. 4581Operand 0 is the result value, operand 1 is the memory on which the 4582atomic operation is performed, and operand 2 is the second operand 4583to the binary operator. 4584 4585This pattern must issue any memory barrier instructions such that all 4586memory operations before the atomic operation occur before the atomic 4587operation and all memory operations after the atomic operation occur 4588after the atomic operation. 4589 4590If these patterns are not defined, the operation will be constructed 4591from a compare-and-swap operation, if defined. 4592 4593@cindex @code{sync_new_add@var{mode}} instruction pattern 4594@cindex @code{sync_new_sub@var{mode}} instruction pattern 4595@cindex @code{sync_new_ior@var{mode}} instruction pattern 4596@cindex @code{sync_new_and@var{mode}} instruction pattern 4597@cindex @code{sync_new_xor@var{mode}} instruction pattern 4598@cindex @code{sync_new_nand@var{mode}} instruction pattern 4599@item @samp{sync_new_add@var{mode}}, @samp{sync_new_sub@var{mode}} 4600@itemx @samp{sync_new_ior@var{mode}}, @samp{sync_new_and@var{mode}} 4601@itemx @samp{sync_new_xor@var{mode}}, @samp{sync_new_nand@var{mode}} 4602 4603These patterns are like their @code{sync_old_@var{op}} counterparts, 4604except that they return the value that exists in the memory location 4605after the operation, rather than before the operation. 4606 4607@cindex @code{sync_lock_test_and_set@var{mode}} instruction pattern 4608@item @samp{sync_lock_test_and_set@var{mode}} 4609 4610This pattern takes two forms, based on the capabilities of the target. 4611In either case, operand 0 is the result of the operand, operand 1 is 4612the memory on which the atomic operation is performed, and operand 2 4613is the value to set in the lock. 4614 4615In the ideal case, this operation is an atomic exchange operation, in 4616which the previous value in memory operand is copied into the result 4617operand, and the value operand is stored in the memory operand. 4618 4619For less capable targets, any value operand that is not the constant 1 4620should be rejected with @code{FAIL}. In this case the target may use 4621an atomic test-and-set bit operation. The result operand should contain 46221 if the bit was previously set and 0 if the bit was previously clear. 4623The true contents of the memory operand are implementation defined. 4624 4625This pattern must issue any memory barrier instructions such that the 4626pattern as a whole acts as an acquire barrier, that is all memory 4627operations after the pattern do not occur until the lock is acquired. 4628 4629If this pattern is not defined, the operation will be constructed from 4630a compare-and-swap operation, if defined. 4631 4632@cindex @code{sync_lock_release@var{mode}} instruction pattern 4633@item @samp{sync_lock_release@var{mode}} 4634 4635This pattern, if defined, releases a lock set by 4636@code{sync_lock_test_and_set@var{mode}}. Operand 0 is the memory 4637that contains the lock; operand 1 is the value to store in the lock. 4638 4639If the target doesn't implement full semantics for 4640@code{sync_lock_test_and_set@var{mode}}, any value operand which is not 4641the constant 0 should be rejected with @code{FAIL}, and the true contents 4642of the memory operand are implementation defined. 4643 4644This pattern must issue any memory barrier instructions such that the 4645pattern as a whole acts as a release barrier, that is the lock is 4646released only after all previous memory operations have completed. 4647 4648If this pattern is not defined, then a @code{memory_barrier} pattern 4649will be emitted, followed by a store of the value to the memory operand. 4650 4651@cindex @code{stack_protect_set} instruction pattern 4652@item @samp{stack_protect_set} 4653 4654This pattern, if defined, moves a @code{Pmode} value from the memory 4655in operand 1 to the memory in operand 0 without leaving the value in 4656a register afterward. This is to avoid leaking the value some place 4657that an attacker might use to rewrite the stack guard slot after 4658having clobbered it. 4659 4660If this pattern is not defined, then a plain move pattern is generated. 4661 4662@cindex @code{stack_protect_test} instruction pattern 4663@item @samp{stack_protect_test} 4664 4665This pattern, if defined, compares a @code{Pmode} value from the 4666memory in operand 1 with the memory in operand 0 without leaving the 4667value in a register afterward and branches to operand 2 if the values 4668weren't equal. 4669 4670If this pattern is not defined, then a plain compare pattern and 4671conditional branch pattern is used. 4672 4673@end table 4674 4675@end ifset 4676@c Each of the following nodes are wrapped in separate 4677@c "@ifset INTERNALS" to work around memory limits for the default 4678@c configuration in older tetex distributions. Known to not work: 4679@c tetex-1.0.7, known to work: tetex-2.0.2. 4680@ifset INTERNALS 4681@node Pattern Ordering 4682@section When the Order of Patterns Matters 4683@cindex Pattern Ordering 4684@cindex Ordering of Patterns 4685 4686Sometimes an insn can match more than one instruction pattern. Then the 4687pattern that appears first in the machine description is the one used. 4688Therefore, more specific patterns (patterns that will match fewer things) 4689and faster instructions (those that will produce better code when they 4690do match) should usually go first in the description. 4691 4692In some cases the effect of ordering the patterns can be used to hide 4693a pattern when it is not valid. For example, the 68000 has an 4694instruction for converting a fullword to floating point and another 4695for converting a byte to floating point. An instruction converting 4696an integer to floating point could match either one. We put the 4697pattern to convert the fullword first to make sure that one will 4698be used rather than the other. (Otherwise a large integer might 4699be generated as a single-byte immediate quantity, which would not work.) 4700Instead of using this pattern ordering it would be possible to make the 4701pattern for convert-a-byte smart enough to deal properly with any 4702constant value. 4703 4704@end ifset 4705@ifset INTERNALS 4706@node Dependent Patterns 4707@section Interdependence of Patterns 4708@cindex Dependent Patterns 4709@cindex Interdependence of Patterns 4710 4711Every machine description must have a named pattern for each of the 4712conditional branch names @samp{b@var{cond}}. The recognition template 4713must always have the form 4714 4715@smallexample 4716(set (pc) 4717 (if_then_else (@var{cond} (cc0) (const_int 0)) 4718 (label_ref (match_operand 0 "" "")) 4719 (pc))) 4720@end smallexample 4721 4722@noindent 4723In addition, every machine description must have an anonymous pattern 4724for each of the possible reverse-conditional branches. Their templates 4725look like 4726 4727@smallexample 4728(set (pc) 4729 (if_then_else (@var{cond} (cc0) (const_int 0)) 4730 (pc) 4731 (label_ref (match_operand 0 "" "")))) 4732@end smallexample 4733 4734@noindent 4735They are necessary because jump optimization can turn direct-conditional 4736branches into reverse-conditional branches. 4737 4738It is often convenient to use the @code{match_operator} construct to 4739reduce the number of patterns that must be specified for branches. For 4740example, 4741 4742@smallexample 4743(define_insn "" 4744 [(set (pc) 4745 (if_then_else (match_operator 0 "comparison_operator" 4746 [(cc0) (const_int 0)]) 4747 (pc) 4748 (label_ref (match_operand 1 "" ""))))] 4749 "@var{condition}" 4750 "@dots{}") 4751@end smallexample 4752 4753In some cases machines support instructions identical except for the 4754machine mode of one or more operands. For example, there may be 4755``sign-extend halfword'' and ``sign-extend byte'' instructions whose 4756patterns are 4757 4758@smallexample 4759(set (match_operand:SI 0 @dots{}) 4760 (extend:SI (match_operand:HI 1 @dots{}))) 4761 4762(set (match_operand:SI 0 @dots{}) 4763 (extend:SI (match_operand:QI 1 @dots{}))) 4764@end smallexample 4765 4766@noindent 4767Constant integers do not specify a machine mode, so an instruction to 4768extend a constant value could match either pattern. The pattern it 4769actually will match is the one that appears first in the file. For correct 4770results, this must be the one for the widest possible mode (@code{HImode}, 4771here). If the pattern matches the @code{QImode} instruction, the results 4772will be incorrect if the constant value does not actually fit that mode. 4773 4774Such instructions to extend constants are rarely generated because they are 4775optimized away, but they do occasionally happen in nonoptimized 4776compilations. 4777 4778If a constraint in a pattern allows a constant, the reload pass may 4779replace a register with a constant permitted by the constraint in some 4780cases. Similarly for memory references. Because of this substitution, 4781you should not provide separate patterns for increment and decrement 4782instructions. Instead, they should be generated from the same pattern 4783that supports register-register add insns by examining the operands and 4784generating the appropriate machine instruction. 4785 4786@end ifset 4787@ifset INTERNALS 4788@node Jump Patterns 4789@section Defining Jump Instruction Patterns 4790@cindex jump instruction patterns 4791@cindex defining jump instruction patterns 4792 4793For most machines, GCC assumes that the machine has a condition code. 4794A comparison insn sets the condition code, recording the results of both 4795signed and unsigned comparison of the given operands. A separate branch 4796insn tests the condition code and branches or not according its value. 4797The branch insns come in distinct signed and unsigned flavors. Many 4798common machines, such as the VAX, the 68000 and the 32000, work this 4799way. 4800 4801Some machines have distinct signed and unsigned compare instructions, and 4802only one set of conditional branch instructions. The easiest way to handle 4803these machines is to treat them just like the others until the final stage 4804where assembly code is written. At this time, when outputting code for the 4805compare instruction, peek ahead at the following branch using 4806@code{next_cc0_user (insn)}. (The variable @code{insn} refers to the insn 4807being output, in the output-writing code in an instruction pattern.) If 4808the RTL says that is an unsigned branch, output an unsigned compare; 4809otherwise output a signed compare. When the branch itself is output, you 4810can treat signed and unsigned branches identically. 4811 4812The reason you can do this is that GCC always generates a pair of 4813consecutive RTL insns, possibly separated by @code{note} insns, one to 4814set the condition code and one to test it, and keeps the pair inviolate 4815until the end. 4816 4817To go with this technique, you must define the machine-description macro 4818@code{NOTICE_UPDATE_CC} to do @code{CC_STATUS_INIT}; in other words, no 4819compare instruction is superfluous. 4820 4821Some machines have compare-and-branch instructions and no condition code. 4822A similar technique works for them. When it is time to ``output'' a 4823compare instruction, record its operands in two static variables. When 4824outputting the branch-on-condition-code instruction that follows, actually 4825output a compare-and-branch instruction that uses the remembered operands. 4826 4827It also works to define patterns for compare-and-branch instructions. 4828In optimizing compilation, the pair of compare and branch instructions 4829will be combined according to these patterns. But this does not happen 4830if optimization is not requested. So you must use one of the solutions 4831above in addition to any special patterns you define. 4832 4833In many RISC machines, most instructions do not affect the condition 4834code and there may not even be a separate condition code register. On 4835these machines, the restriction that the definition and use of the 4836condition code be adjacent insns is not necessary and can prevent 4837important optimizations. For example, on the IBM RS/6000, there is a 4838delay for taken branches unless the condition code register is set three 4839instructions earlier than the conditional branch. The instruction 4840scheduler cannot perform this optimization if it is not permitted to 4841separate the definition and use of the condition code register. 4842 4843On these machines, do not use @code{(cc0)}, but instead use a register 4844to represent the condition code. If there is a specific condition code 4845register in the machine, use a hard register. If the condition code or 4846comparison result can be placed in any general register, or if there are 4847multiple condition registers, use a pseudo register. 4848 4849@findex prev_cc0_setter 4850@findex next_cc0_user 4851On some machines, the type of branch instruction generated may depend on 4852the way the condition code was produced; for example, on the 68k and 4853SPARC, setting the condition code directly from an add or subtract 4854instruction does not clear the overflow bit the way that a test 4855instruction does, so a different branch instruction must be used for 4856some conditional branches. For machines that use @code{(cc0)}, the set 4857and use of the condition code must be adjacent (separated only by 4858@code{note} insns) allowing flags in @code{cc_status} to be used. 4859(@xref{Condition Code}.) Also, the comparison and branch insns can be 4860located from each other by using the functions @code{prev_cc0_setter} 4861and @code{next_cc0_user}. 4862 4863However, this is not true on machines that do not use @code{(cc0)}. On 4864those machines, no assumptions can be made about the adjacency of the 4865compare and branch insns and the above methods cannot be used. Instead, 4866we use the machine mode of the condition code register to record 4867different formats of the condition code register. 4868 4869Registers used to store the condition code value should have a mode that 4870is in class @code{MODE_CC}. Normally, it will be @code{CCmode}. If 4871additional modes are required (as for the add example mentioned above in 4872the SPARC), define them in @file{@var{machine}-modes.def} 4873(@pxref{Condition Code}). Also define @code{SELECT_CC_MODE} to choose 4874a mode given an operand of a compare. 4875 4876If it is known during RTL generation that a different mode will be 4877required (for example, if the machine has separate compare instructions 4878for signed and unsigned quantities, like most IBM processors), they can 4879be specified at that time. 4880 4881If the cases that require different modes would be made by instruction 4882combination, the macro @code{SELECT_CC_MODE} determines which machine 4883mode should be used for the comparison result. The patterns should be 4884written using that mode. To support the case of the add on the SPARC 4885discussed above, we have the pattern 4886 4887@smallexample 4888(define_insn "" 4889 [(set (reg:CC_NOOV 0) 4890 (compare:CC_NOOV 4891 (plus:SI (match_operand:SI 0 "register_operand" "%r") 4892 (match_operand:SI 1 "arith_operand" "rI")) 4893 (const_int 0)))] 4894 "" 4895 "@dots{}") 4896@end smallexample 4897 4898The @code{SELECT_CC_MODE} macro on the SPARC returns @code{CC_NOOVmode} 4899for comparisons whose argument is a @code{plus}. 4900 4901@end ifset 4902@ifset INTERNALS 4903@node Looping Patterns 4904@section Defining Looping Instruction Patterns 4905@cindex looping instruction patterns 4906@cindex defining looping instruction patterns 4907 4908Some machines have special jump instructions that can be utilized to 4909make loops more efficient. A common example is the 68000 @samp{dbra} 4910instruction which performs a decrement of a register and a branch if the 4911result was greater than zero. Other machines, in particular digital 4912signal processors (DSPs), have special block repeat instructions to 4913provide low-overhead loop support. For example, the TI TMS320C3x/C4x 4914DSPs have a block repeat instruction that loads special registers to 4915mark the top and end of a loop and to count the number of loop 4916iterations. This avoids the need for fetching and executing a 4917@samp{dbra}-like instruction and avoids pipeline stalls associated with 4918the jump. 4919 4920GCC has three special named patterns to support low overhead looping. 4921They are @samp{decrement_and_branch_until_zero}, @samp{doloop_begin}, 4922and @samp{doloop_end}. The first pattern, 4923@samp{decrement_and_branch_until_zero}, is not emitted during RTL 4924generation but may be emitted during the instruction combination phase. 4925This requires the assistance of the loop optimizer, using information 4926collected during strength reduction, to reverse a loop to count down to 4927zero. Some targets also require the loop optimizer to add a 4928@code{REG_NONNEG} note to indicate that the iteration count is always 4929positive. This is needed if the target performs a signed loop 4930termination test. For example, the 68000 uses a pattern similar to the 4931following for its @code{dbra} instruction: 4932 4933@smallexample 4934@group 4935(define_insn "decrement_and_branch_until_zero" 4936 [(set (pc) 4937 (if_then_else 4938 (ge (plus:SI (match_operand:SI 0 "general_operand" "+d*am") 4939 (const_int -1)) 4940 (const_int 0)) 4941 (label_ref (match_operand 1 "" "")) 4942 (pc))) 4943 (set (match_dup 0) 4944 (plus:SI (match_dup 0) 4945 (const_int -1)))] 4946 "find_reg_note (insn, REG_NONNEG, 0)" 4947 "@dots{}") 4948@end group 4949@end smallexample 4950 4951Note that since the insn is both a jump insn and has an output, it must 4952deal with its own reloads, hence the `m' constraints. Also note that 4953since this insn is generated by the instruction combination phase 4954combining two sequential insns together into an implicit parallel insn, 4955the iteration counter needs to be biased by the same amount as the 4956decrement operation, in this case @minus{}1. Note that the following similar 4957pattern will not be matched by the combiner. 4958 4959@smallexample 4960@group 4961(define_insn "decrement_and_branch_until_zero" 4962 [(set (pc) 4963 (if_then_else 4964 (ge (match_operand:SI 0 "general_operand" "+d*am") 4965 (const_int 1)) 4966 (label_ref (match_operand 1 "" "")) 4967 (pc))) 4968 (set (match_dup 0) 4969 (plus:SI (match_dup 0) 4970 (const_int -1)))] 4971 "find_reg_note (insn, REG_NONNEG, 0)" 4972 "@dots{}") 4973@end group 4974@end smallexample 4975 4976The other two special looping patterns, @samp{doloop_begin} and 4977@samp{doloop_end}, are emitted by the loop optimizer for certain 4978well-behaved loops with a finite number of loop iterations using 4979information collected during strength reduction. 4980 4981The @samp{doloop_end} pattern describes the actual looping instruction 4982(or the implicit looping operation) and the @samp{doloop_begin} pattern 4983is an optional companion pattern that can be used for initialization 4984needed for some low-overhead looping instructions. 4985 4986Note that some machines require the actual looping instruction to be 4987emitted at the top of the loop (e.g., the TMS320C3x/C4x DSPs). Emitting 4988the true RTL for a looping instruction at the top of the loop can cause 4989problems with flow analysis. So instead, a dummy @code{doloop} insn is 4990emitted at the end of the loop. The machine dependent reorg pass checks 4991for the presence of this @code{doloop} insn and then searches back to 4992the top of the loop, where it inserts the true looping insn (provided 4993there are no instructions in the loop which would cause problems). Any 4994additional labels can be emitted at this point. In addition, if the 4995desired special iteration counter register was not allocated, this 4996machine dependent reorg pass could emit a traditional compare and jump 4997instruction pair. 4998 4999The essential difference between the 5000@samp{decrement_and_branch_until_zero} and the @samp{doloop_end} 5001patterns is that the loop optimizer allocates an additional pseudo 5002register for the latter as an iteration counter. This pseudo register 5003cannot be used within the loop (i.e., general induction variables cannot 5004be derived from it), however, in many cases the loop induction variable 5005may become redundant and removed by the flow pass. 5006 5007 5008@end ifset 5009@ifset INTERNALS 5010@node Insn Canonicalizations 5011@section Canonicalization of Instructions 5012@cindex canonicalization of instructions 5013@cindex insn canonicalization 5014 5015There are often cases where multiple RTL expressions could represent an 5016operation performed by a single machine instruction. This situation is 5017most commonly encountered with logical, branch, and multiply-accumulate 5018instructions. In such cases, the compiler attempts to convert these 5019multiple RTL expressions into a single canonical form to reduce the 5020number of insn patterns required. 5021 5022In addition to algebraic simplifications, following canonicalizations 5023are performed: 5024 5025@itemize @bullet 5026@item 5027For commutative and comparison operators, a constant is always made the 5028second operand. If a machine only supports a constant as the second 5029operand, only patterns that match a constant in the second operand need 5030be supplied. 5031 5032@item 5033For associative operators, a sequence of operators will always chain 5034to the left; for instance, only the left operand of an integer @code{plus} 5035can itself be a @code{plus}. @code{and}, @code{ior}, @code{xor}, 5036@code{plus}, @code{mult}, @code{smin}, @code{smax}, @code{umin}, and 5037@code{umax} are associative when applied to integers, and sometimes to 5038floating-point. 5039 5040@item 5041@cindex @code{neg}, canonicalization of 5042@cindex @code{not}, canonicalization of 5043@cindex @code{mult}, canonicalization of 5044@cindex @code{plus}, canonicalization of 5045@cindex @code{minus}, canonicalization of 5046For these operators, if only one operand is a @code{neg}, @code{not}, 5047@code{mult}, @code{plus}, or @code{minus} expression, it will be the 5048first operand. 5049 5050@item 5051In combinations of @code{neg}, @code{mult}, @code{plus}, and 5052@code{minus}, the @code{neg} operations (if any) will be moved inside 5053the operations as far as possible. For instance, 5054@code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but 5055@code{(plus (mult (neg A) B) C)} is canonicalized as 5056@code{(minus A (mult B C))}. 5057 5058@cindex @code{compare}, canonicalization of 5059@item 5060For the @code{compare} operator, a constant is always the second operand 5061on machines where @code{cc0} is used (@pxref{Jump Patterns}). On other 5062machines, there are rare cases where the compiler might want to construct 5063a @code{compare} with a constant as the first operand. However, these 5064cases are not common enough for it to be worthwhile to provide a pattern 5065matching a constant as the first operand unless the machine actually has 5066such an instruction. 5067 5068An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or 5069@code{minus} is made the first operand under the same conditions as 5070above. 5071 5072@item 5073@code{(minus @var{x} (const_int @var{n}))} is converted to 5074@code{(plus @var{x} (const_int @var{-n}))}. 5075 5076@item 5077Within address computations (i.e., inside @code{mem}), a left shift is 5078converted into the appropriate multiplication by a power of two. 5079 5080@cindex @code{ior}, canonicalization of 5081@cindex @code{and}, canonicalization of 5082@cindex De Morgan's law 5083@item 5084De Morgan's Law is used to move bitwise negation inside a bitwise 5085logical-and or logical-or operation. If this results in only one 5086operand being a @code{not} expression, it will be the first one. 5087 5088A machine that has an instruction that performs a bitwise logical-and of one 5089operand with the bitwise negation of the other should specify the pattern 5090for that instruction as 5091 5092@smallexample 5093(define_insn "" 5094 [(set (match_operand:@var{m} 0 @dots{}) 5095 (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) 5096 (match_operand:@var{m} 2 @dots{})))] 5097 "@dots{}" 5098 "@dots{}") 5099@end smallexample 5100 5101@noindent 5102Similarly, a pattern for a ``NAND'' instruction should be written 5103 5104@smallexample 5105(define_insn "" 5106 [(set (match_operand:@var{m} 0 @dots{}) 5107 (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) 5108 (not:@var{m} (match_operand:@var{m} 2 @dots{}))))] 5109 "@dots{}" 5110 "@dots{}") 5111@end smallexample 5112 5113In both cases, it is not necessary to include patterns for the many 5114logically equivalent RTL expressions. 5115 5116@cindex @code{xor}, canonicalization of 5117@item 5118The only possible RTL expressions involving both bitwise exclusive-or 5119and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})} 5120and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}. 5121 5122@item 5123The sum of three items, one of which is a constant, will only appear in 5124the form 5125 5126@smallexample 5127(plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant}) 5128@end smallexample 5129 5130@item 5131On machines that do not use @code{cc0}, 5132@code{(compare @var{x} (const_int 0))} will be converted to 5133@var{x}. 5134 5135@cindex @code{zero_extract}, canonicalization of 5136@cindex @code{sign_extract}, canonicalization of 5137@item 5138Equality comparisons of a group of bits (usually a single bit) with zero 5139will be written using @code{zero_extract} rather than the equivalent 5140@code{and} or @code{sign_extract} operations. 5141 5142@end itemize 5143 5144Further canonicalization rules are defined in the function 5145@code{commutative_operand_precedence} in @file{gcc/rtlanal.c}. 5146 5147@end ifset 5148@ifset INTERNALS 5149@node Expander Definitions 5150@section Defining RTL Sequences for Code Generation 5151@cindex expander definitions 5152@cindex code generation RTL sequences 5153@cindex defining RTL sequences for code generation 5154 5155On some target machines, some standard pattern names for RTL generation 5156cannot be handled with single insn, but a sequence of RTL insns can 5157represent them. For these target machines, you can write a 5158@code{define_expand} to specify how to generate the sequence of RTL@. 5159 5160@findex define_expand 5161A @code{define_expand} is an RTL expression that looks almost like a 5162@code{define_insn}; but, unlike the latter, a @code{define_expand} is used 5163only for RTL generation and it can produce more than one RTL insn. 5164 5165A @code{define_expand} RTX has four operands: 5166 5167@itemize @bullet 5168@item 5169The name. Each @code{define_expand} must have a name, since the only 5170use for it is to refer to it by name. 5171 5172@item 5173The RTL template. This is a vector of RTL expressions representing 5174a sequence of separate instructions. Unlike @code{define_insn}, there 5175is no implicit surrounding @code{PARALLEL}. 5176 5177@item 5178The condition, a string containing a C expression. This expression is 5179used to express how the availability of this pattern depends on 5180subclasses of target machine, selected by command-line options when GCC 5181is run. This is just like the condition of a @code{define_insn} that 5182has a standard name. Therefore, the condition (if present) may not 5183depend on the data in the insn being matched, but only the 5184target-machine-type flags. The compiler needs to test these conditions 5185during initialization in order to learn exactly which named instructions 5186are available in a particular run. 5187 5188@item 5189The preparation statements, a string containing zero or more C 5190statements which are to be executed before RTL code is generated from 5191the RTL template. 5192 5193Usually these statements prepare temporary registers for use as 5194internal operands in the RTL template, but they can also generate RTL 5195insns directly by calling routines such as @code{emit_insn}, etc. 5196Any such insns precede the ones that come from the RTL template. 5197@end itemize 5198 5199Every RTL insn emitted by a @code{define_expand} must match some 5200@code{define_insn} in the machine description. Otherwise, the compiler 5201will crash when trying to generate code for the insn or trying to optimize 5202it. 5203 5204The RTL template, in addition to controlling generation of RTL insns, 5205also describes the operands that need to be specified when this pattern 5206is used. In particular, it gives a predicate for each operand. 5207 5208A true operand, which needs to be specified in order to generate RTL from 5209the pattern, should be described with a @code{match_operand} in its first 5210occurrence in the RTL template. This enters information on the operand's 5211predicate into the tables that record such things. GCC uses the 5212information to preload the operand into a register if that is required for 5213valid RTL code. If the operand is referred to more than once, subsequent 5214references should use @code{match_dup}. 5215 5216The RTL template may also refer to internal ``operands'' which are 5217temporary registers or labels used only within the sequence made by the 5218@code{define_expand}. Internal operands are substituted into the RTL 5219template with @code{match_dup}, never with @code{match_operand}. The 5220values of the internal operands are not passed in as arguments by the 5221compiler when it requests use of this pattern. Instead, they are computed 5222within the pattern, in the preparation statements. These statements 5223compute the values and store them into the appropriate elements of 5224@code{operands} so that @code{match_dup} can find them. 5225 5226There are two special macros defined for use in the preparation statements: 5227@code{DONE} and @code{FAIL}. Use them with a following semicolon, 5228as a statement. 5229 5230@table @code 5231 5232@findex DONE 5233@item DONE 5234Use the @code{DONE} macro to end RTL generation for the pattern. The 5235only RTL insns resulting from the pattern on this occasion will be 5236those already emitted by explicit calls to @code{emit_insn} within the 5237preparation statements; the RTL template will not be generated. 5238 5239@findex FAIL 5240@item FAIL 5241Make the pattern fail on this occasion. When a pattern fails, it means 5242that the pattern was not truly available. The calling routines in the 5243compiler will try other strategies for code generation using other patterns. 5244 5245Failure is currently supported only for binary (addition, multiplication, 5246shifting, etc.) and bit-field (@code{extv}, @code{extzv}, and @code{insv}) 5247operations. 5248@end table 5249 5250If the preparation falls through (invokes neither @code{DONE} nor 5251@code{FAIL}), then the @code{define_expand} acts like a 5252@code{define_insn} in that the RTL template is used to generate the 5253insn. 5254 5255The RTL template is not used for matching, only for generating the 5256initial insn list. If the preparation statement always invokes 5257@code{DONE} or @code{FAIL}, the RTL template may be reduced to a simple 5258list of operands, such as this example: 5259 5260@smallexample 5261@group 5262(define_expand "addsi3" 5263 [(match_operand:SI 0 "register_operand" "") 5264 (match_operand:SI 1 "register_operand" "") 5265 (match_operand:SI 2 "register_operand" "")] 5266@end group 5267@group 5268 "" 5269 " 5270@{ 5271 handle_add (operands[0], operands[1], operands[2]); 5272 DONE; 5273@}") 5274@end group 5275@end smallexample 5276 5277Here is an example, the definition of left-shift for the SPUR chip: 5278 5279@smallexample 5280@group 5281(define_expand "ashlsi3" 5282 [(set (match_operand:SI 0 "register_operand" "") 5283 (ashift:SI 5284@end group 5285@group 5286 (match_operand:SI 1 "register_operand" "") 5287 (match_operand:SI 2 "nonmemory_operand" "")))] 5288 "" 5289 " 5290@end group 5291@end smallexample 5292 5293@smallexample 5294@group 5295@{ 5296 if (GET_CODE (operands[2]) != CONST_INT 5297 || (unsigned) INTVAL (operands[2]) > 3) 5298 FAIL; 5299@}") 5300@end group 5301@end smallexample 5302 5303@noindent 5304This example uses @code{define_expand} so that it can generate an RTL insn 5305for shifting when the shift-count is in the supported range of 0 to 3 but 5306fail in other cases where machine insns aren't available. When it fails, 5307the compiler tries another strategy using different patterns (such as, a 5308library call). 5309 5310If the compiler were able to handle nontrivial condition-strings in 5311patterns with names, then it would be possible to use a 5312@code{define_insn} in that case. Here is another case (zero-extension 5313on the 68000) which makes more use of the power of @code{define_expand}: 5314 5315@smallexample 5316(define_expand "zero_extendhisi2" 5317 [(set (match_operand:SI 0 "general_operand" "") 5318 (const_int 0)) 5319 (set (strict_low_part 5320 (subreg:HI 5321 (match_dup 0) 5322 0)) 5323 (match_operand:HI 1 "general_operand" ""))] 5324 "" 5325 "operands[1] = make_safe_from (operands[1], operands[0]);") 5326@end smallexample 5327 5328@noindent 5329@findex make_safe_from 5330Here two RTL insns are generated, one to clear the entire output operand 5331and the other to copy the input operand into its low half. This sequence 5332is incorrect if the input operand refers to [the old value of] the output 5333operand, so the preparation statement makes sure this isn't so. The 5334function @code{make_safe_from} copies the @code{operands[1]} into a 5335temporary register if it refers to @code{operands[0]}. It does this 5336by emitting another RTL insn. 5337 5338Finally, a third example shows the use of an internal operand. 5339Zero-extension on the SPUR chip is done by @code{and}-ing the result 5340against a halfword mask. But this mask cannot be represented by a 5341@code{const_int} because the constant value is too large to be legitimate 5342on this machine. So it must be copied into a register with 5343@code{force_reg} and then the register used in the @code{and}. 5344 5345@smallexample 5346(define_expand "zero_extendhisi2" 5347 [(set (match_operand:SI 0 "register_operand" "") 5348 (and:SI (subreg:SI 5349 (match_operand:HI 1 "register_operand" "") 5350 0) 5351 (match_dup 2)))] 5352 "" 5353 "operands[2] 5354 = force_reg (SImode, GEN_INT (65535)); ") 5355@end smallexample 5356 5357@emph{Note:} If the @code{define_expand} is used to serve a 5358standard binary or unary arithmetic operation or a bit-field operation, 5359then the last insn it generates must not be a @code{code_label}, 5360@code{barrier} or @code{note}. It must be an @code{insn}, 5361@code{jump_insn} or @code{call_insn}. If you don't need a real insn 5362at the end, emit an insn to copy the result of the operation into 5363itself. Such an insn will generate no code, but it can avoid problems 5364in the compiler. 5365 5366@end ifset 5367@ifset INTERNALS 5368@node Insn Splitting 5369@section Defining How to Split Instructions 5370@cindex insn splitting 5371@cindex instruction splitting 5372@cindex splitting instructions 5373 5374There are two cases where you should specify how to split a pattern 5375into multiple insns. On machines that have instructions requiring 5376delay slots (@pxref{Delay Slots}) or that have instructions whose 5377output is not available for multiple cycles (@pxref{Processor pipeline 5378description}), the compiler phases that optimize these cases need to 5379be able to move insns into one-instruction delay slots. However, some 5380insns may generate more than one machine instruction. These insns 5381cannot be placed into a delay slot. 5382 5383Often you can rewrite the single insn as a list of individual insns, 5384each corresponding to one machine instruction. The disadvantage of 5385doing so is that it will cause the compilation to be slower and require 5386more space. If the resulting insns are too complex, it may also 5387suppress some optimizations. The compiler splits the insn if there is a 5388reason to believe that it might improve instruction or delay slot 5389scheduling. 5390 5391The insn combiner phase also splits putative insns. If three insns are 5392merged into one insn with a complex expression that cannot be matched by 5393some @code{define_insn} pattern, the combiner phase attempts to split 5394the complex pattern into two insns that are recognized. Usually it can 5395break the complex pattern into two patterns by splitting out some 5396subexpression. However, in some other cases, such as performing an 5397addition of a large constant in two insns on a RISC machine, the way to 5398split the addition into two insns is machine-dependent. 5399 5400@findex define_split 5401The @code{define_split} definition tells the compiler how to split a 5402complex insn into several simpler insns. It looks like this: 5403 5404@smallexample 5405(define_split 5406 [@var{insn-pattern}] 5407 "@var{condition}" 5408 [@var{new-insn-pattern-1} 5409 @var{new-insn-pattern-2} 5410 @dots{}] 5411 "@var{preparation-statements}") 5412@end smallexample 5413 5414@var{insn-pattern} is a pattern that needs to be split and 5415@var{condition} is the final condition to be tested, as in a 5416@code{define_insn}. When an insn matching @var{insn-pattern} and 5417satisfying @var{condition} is found, it is replaced in the insn list 5418with the insns given by @var{new-insn-pattern-1}, 5419@var{new-insn-pattern-2}, etc. 5420 5421The @var{preparation-statements} are similar to those statements that 5422are specified for @code{define_expand} (@pxref{Expander Definitions}) 5423and are executed before the new RTL is generated to prepare for the 5424generated code or emit some insns whose pattern is not fixed. Unlike 5425those in @code{define_expand}, however, these statements must not 5426generate any new pseudo-registers. Once reload has completed, they also 5427must not allocate any space in the stack frame. 5428 5429Patterns are matched against @var{insn-pattern} in two different 5430circumstances. If an insn needs to be split for delay slot scheduling 5431or insn scheduling, the insn is already known to be valid, which means 5432that it must have been matched by some @code{define_insn} and, if 5433@code{reload_completed} is nonzero, is known to satisfy the constraints 5434of that @code{define_insn}. In that case, the new insn patterns must 5435also be insns that are matched by some @code{define_insn} and, if 5436@code{reload_completed} is nonzero, must also satisfy the constraints 5437of those definitions. 5438 5439As an example of this usage of @code{define_split}, consider the following 5440example from @file{a29k.md}, which splits a @code{sign_extend} from 5441@code{HImode} to @code{SImode} into a pair of shift insns: 5442 5443@smallexample 5444(define_split 5445 [(set (match_operand:SI 0 "gen_reg_operand" "") 5446 (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))] 5447 "" 5448 [(set (match_dup 0) 5449 (ashift:SI (match_dup 1) 5450 (const_int 16))) 5451 (set (match_dup 0) 5452 (ashiftrt:SI (match_dup 0) 5453 (const_int 16)))] 5454 " 5455@{ operands[1] = gen_lowpart (SImode, operands[1]); @}") 5456@end smallexample 5457 5458When the combiner phase tries to split an insn pattern, it is always the 5459case that the pattern is @emph{not} matched by any @code{define_insn}. 5460The combiner pass first tries to split a single @code{set} expression 5461and then the same @code{set} expression inside a @code{parallel}, but 5462followed by a @code{clobber} of a pseudo-reg to use as a scratch 5463register. In these cases, the combiner expects exactly two new insn 5464patterns to be generated. It will verify that these patterns match some 5465@code{define_insn} definitions, so you need not do this test in the 5466@code{define_split} (of course, there is no point in writing a 5467@code{define_split} that will never produce insns that match). 5468 5469Here is an example of this use of @code{define_split}, taken from 5470@file{rs6000.md}: 5471 5472@smallexample 5473(define_split 5474 [(set (match_operand:SI 0 "gen_reg_operand" "") 5475 (plus:SI (match_operand:SI 1 "gen_reg_operand" "") 5476 (match_operand:SI 2 "non_add_cint_operand" "")))] 5477 "" 5478 [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3))) 5479 (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))] 5480" 5481@{ 5482 int low = INTVAL (operands[2]) & 0xffff; 5483 int high = (unsigned) INTVAL (operands[2]) >> 16; 5484 5485 if (low & 0x8000) 5486 high++, low |= 0xffff0000; 5487 5488 operands[3] = GEN_INT (high << 16); 5489 operands[4] = GEN_INT (low); 5490@}") 5491@end smallexample 5492 5493Here the predicate @code{non_add_cint_operand} matches any 5494@code{const_int} that is @emph{not} a valid operand of a single add 5495insn. The add with the smaller displacement is written so that it 5496can be substituted into the address of a subsequent operation. 5497 5498An example that uses a scratch register, from the same file, generates 5499an equality comparison of a register and a large constant: 5500 5501@smallexample 5502(define_split 5503 [(set (match_operand:CC 0 "cc_reg_operand" "") 5504 (compare:CC (match_operand:SI 1 "gen_reg_operand" "") 5505 (match_operand:SI 2 "non_short_cint_operand" ""))) 5506 (clobber (match_operand:SI 3 "gen_reg_operand" ""))] 5507 "find_single_use (operands[0], insn, 0) 5508 && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ 5509 || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)" 5510 [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4))) 5511 (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))] 5512 " 5513@{ 5514 /* @r{Get the constant we are comparing against, C, and see what it 5515 looks like sign-extended to 16 bits. Then see what constant 5516 could be XOR'ed with C to get the sign-extended value.} */ 5517 5518 int c = INTVAL (operands[2]); 5519 int sextc = (c << 16) >> 16; 5520 int xorv = c ^ sextc; 5521 5522 operands[4] = GEN_INT (xorv); 5523 operands[5] = GEN_INT (sextc); 5524@}") 5525@end smallexample 5526 5527To avoid confusion, don't write a single @code{define_split} that 5528accepts some insns that match some @code{define_insn} as well as some 5529insns that don't. Instead, write two separate @code{define_split} 5530definitions, one for the insns that are valid and one for the insns that 5531are not valid. 5532 5533The splitter is allowed to split jump instructions into sequence of 5534jumps or create new jumps in while splitting non-jump instructions. As 5535the central flowgraph and branch prediction information needs to be updated, 5536several restriction apply. 5537 5538Splitting of jump instruction into sequence that over by another jump 5539instruction is always valid, as compiler expect identical behavior of new 5540jump. When new sequence contains multiple jump instructions or new labels, 5541more assistance is needed. Splitter is required to create only unconditional 5542jumps, or simple conditional jump instructions. Additionally it must attach a 5543@code{REG_BR_PROB} note to each conditional jump. A global variable 5544@code{split_branch_probability} holds the probability of the original branch in case 5545it was an simple conditional jump, @minus{}1 otherwise. To simplify 5546recomputing of edge frequencies, the new sequence is required to have only 5547forward jumps to the newly created labels. 5548 5549@findex define_insn_and_split 5550For the common case where the pattern of a define_split exactly matches the 5551pattern of a define_insn, use @code{define_insn_and_split}. It looks like 5552this: 5553 5554@smallexample 5555(define_insn_and_split 5556 [@var{insn-pattern}] 5557 "@var{condition}" 5558 "@var{output-template}" 5559 "@var{split-condition}" 5560 [@var{new-insn-pattern-1} 5561 @var{new-insn-pattern-2} 5562 @dots{}] 5563 "@var{preparation-statements}" 5564 [@var{insn-attributes}]) 5565 5566@end smallexample 5567 5568@var{insn-pattern}, @var{condition}, @var{output-template}, and 5569@var{insn-attributes} are used as in @code{define_insn}. The 5570@var{new-insn-pattern} vector and the @var{preparation-statements} are used as 5571in a @code{define_split}. The @var{split-condition} is also used as in 5572@code{define_split}, with the additional behavior that if the condition starts 5573with @samp{&&}, the condition used for the split will be the constructed as a 5574logical ``and'' of the split condition with the insn condition. For example, 5575from i386.md: 5576 5577@smallexample 5578(define_insn_and_split "zero_extendhisi2_and" 5579 [(set (match_operand:SI 0 "register_operand" "=r") 5580 (zero_extend:SI (match_operand:HI 1 "register_operand" "0"))) 5581 (clobber (reg:CC 17))] 5582 "TARGET_ZERO_EXTEND_WITH_AND && !optimize_size" 5583 "#" 5584 "&& reload_completed" 5585 [(parallel [(set (match_dup 0) 5586 (and:SI (match_dup 0) (const_int 65535))) 5587 (clobber (reg:CC 17))])] 5588 "" 5589 [(set_attr "type" "alu1")]) 5590 5591@end smallexample 5592 5593In this case, the actual split condition will be 5594@samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}. 5595 5596The @code{define_insn_and_split} construction provides exactly the same 5597functionality as two separate @code{define_insn} and @code{define_split} 5598patterns. It exists for compactness, and as a maintenance tool to prevent 5599having to ensure the two patterns' templates match. 5600 5601@end ifset 5602@ifset INTERNALS 5603@node Including Patterns 5604@section Including Patterns in Machine Descriptions. 5605@cindex insn includes 5606 5607@findex include 5608The @code{include} pattern tells the compiler tools where to 5609look for patterns that are in files other than in the file 5610@file{.md}. This is used only at build time and there is no preprocessing allowed. 5611 5612It looks like: 5613 5614@smallexample 5615 5616(include 5617 @var{pathname}) 5618@end smallexample 5619 5620For example: 5621 5622@smallexample 5623 5624(include "filestuff") 5625 5626@end smallexample 5627 5628Where @var{pathname} is a string that specifies the location of the file, 5629specifies the include file to be in @file{gcc/config/target/filestuff}. The 5630directory @file{gcc/config/target} is regarded as the default directory. 5631 5632 5633Machine descriptions may be split up into smaller more manageable subsections 5634and placed into subdirectories. 5635 5636By specifying: 5637 5638@smallexample 5639 5640(include "BOGUS/filestuff") 5641 5642@end smallexample 5643 5644the include file is specified to be in @file{gcc/config/@var{target}/BOGUS/filestuff}. 5645 5646Specifying an absolute path for the include file such as; 5647@smallexample 5648 5649(include "/u2/BOGUS/filestuff") 5650 5651@end smallexample 5652is permitted but is not encouraged. 5653 5654@subsection RTL Generation Tool Options for Directory Search 5655@cindex directory options .md 5656@cindex options, directory search 5657@cindex search options 5658 5659The @option{-I@var{dir}} option specifies directories to search for machine descriptions. 5660For example: 5661 5662@smallexample 5663 5664genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md 5665 5666@end smallexample 5667 5668 5669Add the directory @var{dir} to the head of the list of directories to be 5670searched for header files. This can be used to override a system machine definition 5671file, substituting your own version, since these directories are 5672searched before the default machine description file directories. If you use more than 5673one @option{-I} option, the directories are scanned in left-to-right 5674order; the standard default directory come after. 5675 5676 5677@end ifset 5678@ifset INTERNALS 5679@node Peephole Definitions 5680@section Machine-Specific Peephole Optimizers 5681@cindex peephole optimizer definitions 5682@cindex defining peephole optimizers 5683 5684In addition to instruction patterns the @file{md} file may contain 5685definitions of machine-specific peephole optimizations. 5686 5687The combiner does not notice certain peephole optimizations when the data 5688flow in the program does not suggest that it should try them. For example, 5689sometimes two consecutive insns related in purpose can be combined even 5690though the second one does not appear to use a register computed in the 5691first one. A machine-specific peephole optimizer can detect such 5692opportunities. 5693 5694There are two forms of peephole definitions that may be used. The 5695original @code{define_peephole} is run at assembly output time to 5696match insns and substitute assembly text. Use of @code{define_peephole} 5697is deprecated. 5698 5699A newer @code{define_peephole2} matches insns and substitutes new 5700insns. The @code{peephole2} pass is run after register allocation 5701but before scheduling, which may result in much better code for 5702targets that do scheduling. 5703 5704@menu 5705* define_peephole:: RTL to Text Peephole Optimizers 5706* define_peephole2:: RTL to RTL Peephole Optimizers 5707@end menu 5708 5709@end ifset 5710@ifset INTERNALS 5711@node define_peephole 5712@subsection RTL to Text Peephole Optimizers 5713@findex define_peephole 5714 5715@need 1000 5716A definition looks like this: 5717 5718@smallexample 5719(define_peephole 5720 [@var{insn-pattern-1} 5721 @var{insn-pattern-2} 5722 @dots{}] 5723 "@var{condition}" 5724 "@var{template}" 5725 "@var{optional-insn-attributes}") 5726@end smallexample 5727 5728@noindent 5729The last string operand may be omitted if you are not using any 5730machine-specific information in this machine description. If present, 5731it must obey the same rules as in a @code{define_insn}. 5732 5733In this skeleton, @var{insn-pattern-1} and so on are patterns to match 5734consecutive insns. The optimization applies to a sequence of insns when 5735@var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches 5736the next, and so on. 5737 5738Each of the insns matched by a peephole must also match a 5739@code{define_insn}. Peepholes are checked only at the last stage just 5740before code generation, and only optionally. Therefore, any insn which 5741would match a peephole but no @code{define_insn} will cause a crash in code 5742generation in an unoptimized compilation, or at various optimization 5743stages. 5744 5745The operands of the insns are matched with @code{match_operands}, 5746@code{match_operator}, and @code{match_dup}, as usual. What is not 5747usual is that the operand numbers apply to all the insn patterns in the 5748definition. So, you can check for identical operands in two insns by 5749using @code{match_operand} in one insn and @code{match_dup} in the 5750other. 5751 5752The operand constraints used in @code{match_operand} patterns do not have 5753any direct effect on the applicability of the peephole, but they will 5754be validated afterward, so make sure your constraints are general enough 5755to apply whenever the peephole matches. If the peephole matches 5756but the constraints are not satisfied, the compiler will crash. 5757 5758It is safe to omit constraints in all the operands of the peephole; or 5759you can write constraints which serve as a double-check on the criteria 5760previously tested. 5761 5762Once a sequence of insns matches the patterns, the @var{condition} is 5763checked. This is a C expression which makes the final decision whether to 5764perform the optimization (we do so if the expression is nonzero). If 5765@var{condition} is omitted (in other words, the string is empty) then the 5766optimization is applied to every sequence of insns that matches the 5767patterns. 5768 5769The defined peephole optimizations are applied after register allocation 5770is complete. Therefore, the peephole definition can check which 5771operands have ended up in which kinds of registers, just by looking at 5772the operands. 5773 5774@findex prev_active_insn 5775The way to refer to the operands in @var{condition} is to write 5776@code{operands[@var{i}]} for operand number @var{i} (as matched by 5777@code{(match_operand @var{i} @dots{})}). Use the variable @code{insn} 5778to refer to the last of the insns being matched; use 5779@code{prev_active_insn} to find the preceding insns. 5780 5781@findex dead_or_set_p 5782When optimizing computations with intermediate results, you can use 5783@var{condition} to match only when the intermediate results are not used 5784elsewhere. Use the C expression @code{dead_or_set_p (@var{insn}, 5785@var{op})}, where @var{insn} is the insn in which you expect the value 5786to be used for the last time (from the value of @code{insn}, together 5787with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate 5788value (from @code{operands[@var{i}]}). 5789 5790Applying the optimization means replacing the sequence of insns with one 5791new insn. The @var{template} controls ultimate output of assembler code 5792for this combined insn. It works exactly like the template of a 5793@code{define_insn}. Operand numbers in this template are the same ones 5794used in matching the original sequence of insns. 5795 5796The result of a defined peephole optimizer does not need to match any of 5797the insn patterns in the machine description; it does not even have an 5798opportunity to match them. The peephole optimizer definition itself serves 5799as the insn pattern to control how the insn is output. 5800 5801Defined peephole optimizers are run as assembler code is being output, 5802so the insns they produce are never combined or rearranged in any way. 5803 5804Here is an example, taken from the 68000 machine description: 5805 5806@smallexample 5807(define_peephole 5808 [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4))) 5809 (set (match_operand:DF 0 "register_operand" "=f") 5810 (match_operand:DF 1 "register_operand" "ad"))] 5811 "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])" 5812@{ 5813 rtx xoperands[2]; 5814 xoperands[1] = gen_rtx_REG (SImode, REGNO (operands[1]) + 1); 5815#ifdef MOTOROLA 5816 output_asm_insn ("move.l %1,(sp)", xoperands); 5817 output_asm_insn ("move.l %1,-(sp)", operands); 5818 return "fmove.d (sp)+,%0"; 5819#else 5820 output_asm_insn ("movel %1,sp@@", xoperands); 5821 output_asm_insn ("movel %1,sp@@-", operands); 5822 return "fmoved sp@@+,%0"; 5823#endif 5824@}) 5825@end smallexample 5826 5827@need 1000 5828The effect of this optimization is to change 5829 5830@smallexample 5831@group 5832jbsr _foobar 5833addql #4,sp 5834movel d1,sp@@- 5835movel d0,sp@@- 5836fmoved sp@@+,fp0 5837@end group 5838@end smallexample 5839 5840@noindent 5841into 5842 5843@smallexample 5844@group 5845jbsr _foobar 5846movel d1,sp@@ 5847movel d0,sp@@- 5848fmoved sp@@+,fp0 5849@end group 5850@end smallexample 5851 5852@ignore 5853@findex CC_REVERSED 5854If a peephole matches a sequence including one or more jump insns, you must 5855take account of the flags such as @code{CC_REVERSED} which specify that the 5856condition codes are represented in an unusual manner. The compiler 5857automatically alters any ordinary conditional jumps which occur in such 5858situations, but the compiler cannot alter jumps which have been replaced by 5859peephole optimizations. So it is up to you to alter the assembler code 5860that the peephole produces. Supply C code to write the assembler output, 5861and in this C code check the condition code status flags and change the 5862assembler code as appropriate. 5863@end ignore 5864 5865@var{insn-pattern-1} and so on look @emph{almost} like the second 5866operand of @code{define_insn}. There is one important difference: the 5867second operand of @code{define_insn} consists of one or more RTX's 5868enclosed in square brackets. Usually, there is only one: then the same 5869action can be written as an element of a @code{define_peephole}. But 5870when there are multiple actions in a @code{define_insn}, they are 5871implicitly enclosed in a @code{parallel}. Then you must explicitly 5872write the @code{parallel}, and the square brackets within it, in the 5873@code{define_peephole}. Thus, if an insn pattern looks like this, 5874 5875@smallexample 5876(define_insn "divmodsi4" 5877 [(set (match_operand:SI 0 "general_operand" "=d") 5878 (div:SI (match_operand:SI 1 "general_operand" "0") 5879 (match_operand:SI 2 "general_operand" "dmsK"))) 5880 (set (match_operand:SI 3 "general_operand" "=d") 5881 (mod:SI (match_dup 1) (match_dup 2)))] 5882 "TARGET_68020" 5883 "divsl%.l %2,%3:%0") 5884@end smallexample 5885 5886@noindent 5887then the way to mention this insn in a peephole is as follows: 5888 5889@smallexample 5890(define_peephole 5891 [@dots{} 5892 (parallel 5893 [(set (match_operand:SI 0 "general_operand" "=d") 5894 (div:SI (match_operand:SI 1 "general_operand" "0") 5895 (match_operand:SI 2 "general_operand" "dmsK"))) 5896 (set (match_operand:SI 3 "general_operand" "=d") 5897 (mod:SI (match_dup 1) (match_dup 2)))]) 5898 @dots{}] 5899 @dots{}) 5900@end smallexample 5901 5902@end ifset 5903@ifset INTERNALS 5904@node define_peephole2 5905@subsection RTL to RTL Peephole Optimizers 5906@findex define_peephole2 5907 5908The @code{define_peephole2} definition tells the compiler how to 5909substitute one sequence of instructions for another sequence, 5910what additional scratch registers may be needed and what their 5911lifetimes must be. 5912 5913@smallexample 5914(define_peephole2 5915 [@var{insn-pattern-1} 5916 @var{insn-pattern-2} 5917 @dots{}] 5918 "@var{condition}" 5919 [@var{new-insn-pattern-1} 5920 @var{new-insn-pattern-2} 5921 @dots{}] 5922 "@var{preparation-statements}") 5923@end smallexample 5924 5925The definition is almost identical to @code{define_split} 5926(@pxref{Insn Splitting}) except that the pattern to match is not a 5927single instruction, but a sequence of instructions. 5928 5929It is possible to request additional scratch registers for use in the 5930output template. If appropriate registers are not free, the pattern 5931will simply not match. 5932 5933@findex match_scratch 5934@findex match_dup 5935Scratch registers are requested with a @code{match_scratch} pattern at 5936the top level of the input pattern. The allocated register (initially) will 5937be dead at the point requested within the original sequence. If the scratch 5938is used at more than a single point, a @code{match_dup} pattern at the 5939top level of the input pattern marks the last position in the input sequence 5940at which the register must be available. 5941 5942Here is an example from the IA-32 machine description: 5943 5944@smallexample 5945(define_peephole2 5946 [(match_scratch:SI 2 "r") 5947 (parallel [(set (match_operand:SI 0 "register_operand" "") 5948 (match_operator:SI 3 "arith_or_logical_operator" 5949 [(match_dup 0) 5950 (match_operand:SI 1 "memory_operand" "")])) 5951 (clobber (reg:CC 17))])] 5952 "! optimize_size && ! TARGET_READ_MODIFY" 5953 [(set (match_dup 2) (match_dup 1)) 5954 (parallel [(set (match_dup 0) 5955 (match_op_dup 3 [(match_dup 0) (match_dup 2)])) 5956 (clobber (reg:CC 17))])] 5957 "") 5958@end smallexample 5959 5960@noindent 5961This pattern tries to split a load from its use in the hopes that we'll be 5962able to schedule around the memory load latency. It allocates a single 5963@code{SImode} register of class @code{GENERAL_REGS} (@code{"r"}) that needs 5964to be live only at the point just before the arithmetic. 5965 5966A real example requiring extended scratch lifetimes is harder to come by, 5967so here's a silly made-up example: 5968 5969@smallexample 5970(define_peephole2 5971 [(match_scratch:SI 4 "r") 5972 (set (match_operand:SI 0 "" "") (match_operand:SI 1 "" "")) 5973 (set (match_operand:SI 2 "" "") (match_dup 1)) 5974 (match_dup 4) 5975 (set (match_operand:SI 3 "" "") (match_dup 1))] 5976 "/* @r{determine 1 does not overlap 0 and 2} */" 5977 [(set (match_dup 4) (match_dup 1)) 5978 (set (match_dup 0) (match_dup 4)) 5979 (set (match_dup 2) (match_dup 4))] 5980 (set (match_dup 3) (match_dup 4))] 5981 "") 5982@end smallexample 5983 5984@noindent 5985If we had not added the @code{(match_dup 4)} in the middle of the input 5986sequence, it might have been the case that the register we chose at the 5987beginning of the sequence is killed by the first or second @code{set}. 5988 5989@end ifset 5990@ifset INTERNALS 5991@node Insn Attributes 5992@section Instruction Attributes 5993@cindex insn attributes 5994@cindex instruction attributes 5995 5996In addition to describing the instruction supported by the target machine, 5997the @file{md} file also defines a group of @dfn{attributes} and a set of 5998values for each. Every generated insn is assigned a value for each attribute. 5999One possible attribute would be the effect that the insn has on the machine's 6000condition code. This attribute can then be used by @code{NOTICE_UPDATE_CC} 6001to track the condition codes. 6002 6003@menu 6004* Defining Attributes:: Specifying attributes and their values. 6005* Expressions:: Valid expressions for attribute values. 6006* Tagging Insns:: Assigning attribute values to insns. 6007* Attr Example:: An example of assigning attributes. 6008* Insn Lengths:: Computing the length of insns. 6009* Constant Attributes:: Defining attributes that are constant. 6010* Delay Slots:: Defining delay slots required for a machine. 6011* Processor pipeline description:: Specifying information for insn scheduling. 6012@end menu 6013 6014@end ifset 6015@ifset INTERNALS 6016@node Defining Attributes 6017@subsection Defining Attributes and their Values 6018@cindex defining attributes and their values 6019@cindex attributes, defining 6020 6021@findex define_attr 6022The @code{define_attr} expression is used to define each attribute required 6023by the target machine. It looks like: 6024 6025@smallexample 6026(define_attr @var{name} @var{list-of-values} @var{default}) 6027@end smallexample 6028 6029@var{name} is a string specifying the name of the attribute being defined. 6030 6031@var{list-of-values} is either a string that specifies a comma-separated 6032list of values that can be assigned to the attribute, or a null string to 6033indicate that the attribute takes numeric values. 6034 6035@var{default} is an attribute expression that gives the value of this 6036attribute for insns that match patterns whose definition does not include 6037an explicit value for this attribute. @xref{Attr Example}, for more 6038information on the handling of defaults. @xref{Constant Attributes}, 6039for information on attributes that do not depend on any particular insn. 6040 6041@findex insn-attr.h 6042For each defined attribute, a number of definitions are written to the 6043@file{insn-attr.h} file. For cases where an explicit set of values is 6044specified for an attribute, the following are defined: 6045 6046@itemize @bullet 6047@item 6048A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}. 6049 6050@item 6051An enumerated class is defined for @samp{attr_@var{name}} with 6052elements of the form @samp{@var{upper-name}_@var{upper-value}} where 6053the attribute name and value are first converted to uppercase. 6054 6055@item 6056A function @samp{get_attr_@var{name}} is defined that is passed an insn and 6057returns the attribute value for that insn. 6058@end itemize 6059 6060For example, if the following is present in the @file{md} file: 6061 6062@smallexample 6063(define_attr "type" "branch,fp,load,store,arith" @dots{}) 6064@end smallexample 6065 6066@noindent 6067the following lines will be written to the file @file{insn-attr.h}. 6068 6069@smallexample 6070#define HAVE_ATTR_type 6071enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD, 6072 TYPE_STORE, TYPE_ARITH@}; 6073extern enum attr_type get_attr_type (); 6074@end smallexample 6075 6076If the attribute takes numeric values, no @code{enum} type will be 6077defined and the function to obtain the attribute's value will return 6078@code{int}. 6079 6080@end ifset 6081@ifset INTERNALS 6082@node Expressions 6083@subsection Attribute Expressions 6084@cindex attribute expressions 6085 6086RTL expressions used to define attributes use the codes described above 6087plus a few specific to attribute definitions, to be discussed below. 6088Attribute value expressions must have one of the following forms: 6089 6090@table @code 6091@cindex @code{const_int} and attributes 6092@item (const_int @var{i}) 6093The integer @var{i} specifies the value of a numeric attribute. @var{i} 6094must be non-negative. 6095 6096The value of a numeric attribute can be specified either with a 6097@code{const_int}, or as an integer represented as a string in 6098@code{const_string}, @code{eq_attr} (see below), @code{attr}, 6099@code{symbol_ref}, simple arithmetic expressions, and @code{set_attr} 6100overrides on specific instructions (@pxref{Tagging Insns}). 6101 6102@cindex @code{const_string} and attributes 6103@item (const_string @var{value}) 6104The string @var{value} specifies a constant attribute value. 6105If @var{value} is specified as @samp{"*"}, it means that the default value of 6106the attribute is to be used for the insn containing this expression. 6107@samp{"*"} obviously cannot be used in the @var{default} expression 6108of a @code{define_attr}. 6109 6110If the attribute whose value is being specified is numeric, @var{value} 6111must be a string containing a non-negative integer (normally 6112@code{const_int} would be used in this case). Otherwise, it must 6113contain one of the valid values for the attribute. 6114 6115@cindex @code{if_then_else} and attributes 6116@item (if_then_else @var{test} @var{true-value} @var{false-value}) 6117@var{test} specifies an attribute test, whose format is defined below. 6118The value of this expression is @var{true-value} if @var{test} is true, 6119otherwise it is @var{false-value}. 6120 6121@cindex @code{cond} and attributes 6122@item (cond [@var{test1} @var{value1} @dots{}] @var{default}) 6123The first operand of this expression is a vector containing an even 6124number of expressions and consisting of pairs of @var{test} and @var{value} 6125expressions. The value of the @code{cond} expression is that of the 6126@var{value} corresponding to the first true @var{test} expression. If 6127none of the @var{test} expressions are true, the value of the @code{cond} 6128expression is that of the @var{default} expression. 6129@end table 6130 6131@var{test} expressions can have one of the following forms: 6132 6133@table @code 6134@cindex @code{const_int} and attribute tests 6135@item (const_int @var{i}) 6136This test is true if @var{i} is nonzero and false otherwise. 6137 6138@cindex @code{not} and attributes 6139@cindex @code{ior} and attributes 6140@cindex @code{and} and attributes 6141@item (not @var{test}) 6142@itemx (ior @var{test1} @var{test2}) 6143@itemx (and @var{test1} @var{test2}) 6144These tests are true if the indicated logical function is true. 6145 6146@cindex @code{match_operand} and attributes 6147@item (match_operand:@var{m} @var{n} @var{pred} @var{constraints}) 6148This test is true if operand @var{n} of the insn whose attribute value 6149is being determined has mode @var{m} (this part of the test is ignored 6150if @var{m} is @code{VOIDmode}) and the function specified by the string 6151@var{pred} returns a nonzero value when passed operand @var{n} and mode 6152@var{m} (this part of the test is ignored if @var{pred} is the null 6153string). 6154 6155The @var{constraints} operand is ignored and should be the null string. 6156 6157@cindex @code{le} and attributes 6158@cindex @code{leu} and attributes 6159@cindex @code{lt} and attributes 6160@cindex @code{gt} and attributes 6161@cindex @code{gtu} and attributes 6162@cindex @code{ge} and attributes 6163@cindex @code{geu} and attributes 6164@cindex @code{ne} and attributes 6165@cindex @code{eq} and attributes 6166@cindex @code{plus} and attributes 6167@cindex @code{minus} and attributes 6168@cindex @code{mult} and attributes 6169@cindex @code{div} and attributes 6170@cindex @code{mod} and attributes 6171@cindex @code{abs} and attributes 6172@cindex @code{neg} and attributes 6173@cindex @code{ashift} and attributes 6174@cindex @code{lshiftrt} and attributes 6175@cindex @code{ashiftrt} and attributes 6176@item (le @var{arith1} @var{arith2}) 6177@itemx (leu @var{arith1} @var{arith2}) 6178@itemx (lt @var{arith1} @var{arith2}) 6179@itemx (ltu @var{arith1} @var{arith2}) 6180@itemx (gt @var{arith1} @var{arith2}) 6181@itemx (gtu @var{arith1} @var{arith2}) 6182@itemx (ge @var{arith1} @var{arith2}) 6183@itemx (geu @var{arith1} @var{arith2}) 6184@itemx (ne @var{arith1} @var{arith2}) 6185@itemx (eq @var{arith1} @var{arith2}) 6186These tests are true if the indicated comparison of the two arithmetic 6187expressions is true. Arithmetic expressions are formed with 6188@code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod}, 6189@code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not}, 6190@code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions. 6191 6192@findex get_attr 6193@code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn 6194Lengths},for additional forms). @code{symbol_ref} is a string 6195denoting a C expression that yields an @code{int} when evaluated by the 6196@samp{get_attr_@dots{}} routine. It should normally be a global 6197variable. 6198 6199@findex eq_attr 6200@item (eq_attr @var{name} @var{value}) 6201@var{name} is a string specifying the name of an attribute. 6202 6203@var{value} is a string that is either a valid value for attribute 6204@var{name}, a comma-separated list of values, or @samp{!} followed by a 6205value or list. If @var{value} does not begin with a @samp{!}, this 6206test is true if the value of the @var{name} attribute of the current 6207insn is in the list specified by @var{value}. If @var{value} begins 6208with a @samp{!}, this test is true if the attribute's value is 6209@emph{not} in the specified list. 6210 6211For example, 6212 6213@smallexample 6214(eq_attr "type" "load,store") 6215@end smallexample 6216 6217@noindent 6218is equivalent to 6219 6220@smallexample 6221(ior (eq_attr "type" "load") (eq_attr "type" "store")) 6222@end smallexample 6223 6224If @var{name} specifies an attribute of @samp{alternative}, it refers to the 6225value of the compiler variable @code{which_alternative} 6226(@pxref{Output Statement}) and the values must be small integers. For 6227example, 6228 6229@smallexample 6230(eq_attr "alternative" "2,3") 6231@end smallexample 6232 6233@noindent 6234is equivalent to 6235 6236@smallexample 6237(ior (eq (symbol_ref "which_alternative") (const_int 2)) 6238 (eq (symbol_ref "which_alternative") (const_int 3))) 6239@end smallexample 6240 6241Note that, for most attributes, an @code{eq_attr} test is simplified in cases 6242where the value of the attribute being tested is known for all insns matching 6243a particular pattern. This is by far the most common case. 6244 6245@findex attr_flag 6246@item (attr_flag @var{name}) 6247The value of an @code{attr_flag} expression is true if the flag 6248specified by @var{name} is true for the @code{insn} currently being 6249scheduled. 6250 6251@var{name} is a string specifying one of a fixed set of flags to test. 6252Test the flags @code{forward} and @code{backward} to determine the 6253direction of a conditional branch. Test the flags @code{very_likely}, 6254@code{likely}, @code{very_unlikely}, and @code{unlikely} to determine 6255if a conditional branch is expected to be taken. 6256 6257If the @code{very_likely} flag is true, then the @code{likely} flag is also 6258true. Likewise for the @code{very_unlikely} and @code{unlikely} flags. 6259 6260This example describes a conditional branch delay slot which 6261can be nullified for forward branches that are taken (annul-true) or 6262for backward branches which are not taken (annul-false). 6263 6264@smallexample 6265(define_delay (eq_attr "type" "cbranch") 6266 [(eq_attr "in_branch_delay" "true") 6267 (and (eq_attr "in_branch_delay" "true") 6268 (attr_flag "forward")) 6269 (and (eq_attr "in_branch_delay" "true") 6270 (attr_flag "backward"))]) 6271@end smallexample 6272 6273The @code{forward} and @code{backward} flags are false if the current 6274@code{insn} being scheduled is not a conditional branch. 6275 6276The @code{very_likely} and @code{likely} flags are true if the 6277@code{insn} being scheduled is not a conditional branch. 6278The @code{very_unlikely} and @code{unlikely} flags are false if the 6279@code{insn} being scheduled is not a conditional branch. 6280 6281@code{attr_flag} is only used during delay slot scheduling and has no 6282meaning to other passes of the compiler. 6283 6284@findex attr 6285@item (attr @var{name}) 6286The value of another attribute is returned. This is most useful 6287for numeric attributes, as @code{eq_attr} and @code{attr_flag} 6288produce more efficient code for non-numeric attributes. 6289@end table 6290 6291@end ifset 6292@ifset INTERNALS 6293@node Tagging Insns 6294@subsection Assigning Attribute Values to Insns 6295@cindex tagging insns 6296@cindex assigning attribute values to insns 6297 6298The value assigned to an attribute of an insn is primarily determined by 6299which pattern is matched by that insn (or which @code{define_peephole} 6300generated it). Every @code{define_insn} and @code{define_peephole} can 6301have an optional last argument to specify the values of attributes for 6302matching insns. The value of any attribute not specified in a particular 6303insn is set to the default value for that attribute, as specified in its 6304@code{define_attr}. Extensive use of default values for attributes 6305permits the specification of the values for only one or two attributes 6306in the definition of most insn patterns, as seen in the example in the 6307next section. 6308 6309The optional last argument of @code{define_insn} and 6310@code{define_peephole} is a vector of expressions, each of which defines 6311the value for a single attribute. The most general way of assigning an 6312attribute's value is to use a @code{set} expression whose first operand is an 6313@code{attr} expression giving the name of the attribute being set. The 6314second operand of the @code{set} is an attribute expression 6315(@pxref{Expressions}) giving the value of the attribute. 6316 6317When the attribute value depends on the @samp{alternative} attribute 6318(i.e., which is the applicable alternative in the constraint of the 6319insn), the @code{set_attr_alternative} expression can be used. It 6320allows the specification of a vector of attribute expressions, one for 6321each alternative. 6322 6323@findex set_attr 6324When the generality of arbitrary attribute expressions is not required, 6325the simpler @code{set_attr} expression can be used, which allows 6326specifying a string giving either a single attribute value or a list 6327of attribute values, one for each alternative. 6328 6329The form of each of the above specifications is shown below. In each case, 6330@var{name} is a string specifying the attribute to be set. 6331 6332@table @code 6333@item (set_attr @var{name} @var{value-string}) 6334@var{value-string} is either a string giving the desired attribute value, 6335or a string containing a comma-separated list giving the values for 6336succeeding alternatives. The number of elements must match the number 6337of alternatives in the constraint of the insn pattern. 6338 6339Note that it may be useful to specify @samp{*} for some alternative, in 6340which case the attribute will assume its default value for insns matching 6341that alternative. 6342 6343@findex set_attr_alternative 6344@item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}]) 6345Depending on the alternative of the insn, the value will be one of the 6346specified values. This is a shorthand for using a @code{cond} with 6347tests on the @samp{alternative} attribute. 6348 6349@findex attr 6350@item (set (attr @var{name}) @var{value}) 6351The first operand of this @code{set} must be the special RTL expression 6352@code{attr}, whose sole operand is a string giving the name of the 6353attribute being set. @var{value} is the value of the attribute. 6354@end table 6355 6356The following shows three different ways of representing the same 6357attribute value specification: 6358 6359@smallexample 6360(set_attr "type" "load,store,arith") 6361 6362(set_attr_alternative "type" 6363 [(const_string "load") (const_string "store") 6364 (const_string "arith")]) 6365 6366(set (attr "type") 6367 (cond [(eq_attr "alternative" "1") (const_string "load") 6368 (eq_attr "alternative" "2") (const_string "store")] 6369 (const_string "arith"))) 6370@end smallexample 6371 6372@need 1000 6373@findex define_asm_attributes 6374The @code{define_asm_attributes} expression provides a mechanism to 6375specify the attributes assigned to insns produced from an @code{asm} 6376statement. It has the form: 6377 6378@smallexample 6379(define_asm_attributes [@var{attr-sets}]) 6380@end smallexample 6381 6382@noindent 6383where @var{attr-sets} is specified the same as for both the 6384@code{define_insn} and the @code{define_peephole} expressions. 6385 6386These values will typically be the ``worst case'' attribute values. For 6387example, they might indicate that the condition code will be clobbered. 6388 6389A specification for a @code{length} attribute is handled specially. The 6390way to compute the length of an @code{asm} insn is to multiply the 6391length specified in the expression @code{define_asm_attributes} by the 6392number of machine instructions specified in the @code{asm} statement, 6393determined by counting the number of semicolons and newlines in the 6394string. Therefore, the value of the @code{length} attribute specified 6395in a @code{define_asm_attributes} should be the maximum possible length 6396of a single machine instruction. 6397 6398@end ifset 6399@ifset INTERNALS 6400@node Attr Example 6401@subsection Example of Attribute Specifications 6402@cindex attribute specifications example 6403@cindex attribute specifications 6404 6405The judicious use of defaulting is important in the efficient use of 6406insn attributes. Typically, insns are divided into @dfn{types} and an 6407attribute, customarily called @code{type}, is used to represent this 6408value. This attribute is normally used only to define the default value 6409for other attributes. An example will clarify this usage. 6410 6411Assume we have a RISC machine with a condition code and in which only 6412full-word operations are performed in registers. Let us assume that we 6413can divide all insns into loads, stores, (integer) arithmetic 6414operations, floating point operations, and branches. 6415 6416Here we will concern ourselves with determining the effect of an insn on 6417the condition code and will limit ourselves to the following possible 6418effects: The condition code can be set unpredictably (clobbered), not 6419be changed, be set to agree with the results of the operation, or only 6420changed if the item previously set into the condition code has been 6421modified. 6422 6423Here is part of a sample @file{md} file for such a machine: 6424 6425@smallexample 6426(define_attr "type" "load,store,arith,fp,branch" (const_string "arith")) 6427 6428(define_attr "cc" "clobber,unchanged,set,change0" 6429 (cond [(eq_attr "type" "load") 6430 (const_string "change0") 6431 (eq_attr "type" "store,branch") 6432 (const_string "unchanged") 6433 (eq_attr "type" "arith") 6434 (if_then_else (match_operand:SI 0 "" "") 6435 (const_string "set") 6436 (const_string "clobber"))] 6437 (const_string "clobber"))) 6438 6439(define_insn "" 6440 [(set (match_operand:SI 0 "general_operand" "=r,r,m") 6441 (match_operand:SI 1 "general_operand" "r,m,r"))] 6442 "" 6443 "@@ 6444 move %0,%1 6445 load %0,%1 6446 store %0,%1" 6447 [(set_attr "type" "arith,load,store")]) 6448@end smallexample 6449 6450Note that we assume in the above example that arithmetic operations 6451performed on quantities smaller than a machine word clobber the condition 6452code since they will set the condition code to a value corresponding to the 6453full-word result. 6454 6455@end ifset 6456@ifset INTERNALS 6457@node Insn Lengths 6458@subsection Computing the Length of an Insn 6459@cindex insn lengths, computing 6460@cindex computing the length of an insn 6461 6462For many machines, multiple types of branch instructions are provided, each 6463for different length branch displacements. In most cases, the assembler 6464will choose the correct instruction to use. However, when the assembler 6465cannot do so, GCC can when a special attribute, the @code{length} 6466attribute, is defined. This attribute must be defined to have numeric 6467values by specifying a null string in its @code{define_attr}. 6468 6469In the case of the @code{length} attribute, two additional forms of 6470arithmetic terms are allowed in test expressions: 6471 6472@table @code 6473@cindex @code{match_dup} and attributes 6474@item (match_dup @var{n}) 6475This refers to the address of operand @var{n} of the current insn, which 6476must be a @code{label_ref}. 6477 6478@cindex @code{pc} and attributes 6479@item (pc) 6480This refers to the address of the @emph{current} insn. It might have 6481been more consistent with other usage to make this the address of the 6482@emph{next} insn but this would be confusing because the length of the 6483current insn is to be computed. 6484@end table 6485 6486@cindex @code{addr_vec}, length of 6487@cindex @code{addr_diff_vec}, length of 6488For normal insns, the length will be determined by value of the 6489@code{length} attribute. In the case of @code{addr_vec} and 6490@code{addr_diff_vec} insn patterns, the length is computed as 6491the number of vectors multiplied by the size of each vector. 6492 6493Lengths are measured in addressable storage units (bytes). 6494 6495The following macros can be used to refine the length computation: 6496 6497@table @code 6498@findex ADJUST_INSN_LENGTH 6499@item ADJUST_INSN_LENGTH (@var{insn}, @var{length}) 6500If defined, modifies the length assigned to instruction @var{insn} as a 6501function of the context in which it is used. @var{length} is an lvalue 6502that contains the initially computed length of the insn and should be 6503updated with the correct length of the insn. 6504 6505This macro will normally not be required. A case in which it is 6506required is the ROMP@. On this machine, the size of an @code{addr_vec} 6507insn must be increased by two to compensate for the fact that alignment 6508may be required. 6509@end table 6510 6511@findex get_attr_length 6512The routine that returns @code{get_attr_length} (the value of the 6513@code{length} attribute) can be used by the output routine to 6514determine the form of the branch instruction to be written, as the 6515example below illustrates. 6516 6517As an example of the specification of variable-length branches, consider 6518the IBM 360. If we adopt the convention that a register will be set to 6519the starting address of a function, we can jump to labels within 4k of 6520the start using a four-byte instruction. Otherwise, we need a six-byte 6521sequence to load the address from memory and then branch to it. 6522 6523On such a machine, a pattern for a branch instruction might be specified 6524as follows: 6525 6526@smallexample 6527(define_insn "jump" 6528 [(set (pc) 6529 (label_ref (match_operand 0 "" "")))] 6530 "" 6531@{ 6532 return (get_attr_length (insn) == 4 6533 ? "b %l0" : "l r15,=a(%l0); br r15"); 6534@} 6535 [(set (attr "length") 6536 (if_then_else (lt (match_dup 0) (const_int 4096)) 6537 (const_int 4) 6538 (const_int 6)))]) 6539@end smallexample 6540 6541@end ifset 6542@ifset INTERNALS 6543@node Constant Attributes 6544@subsection Constant Attributes 6545@cindex constant attributes 6546 6547A special form of @code{define_attr}, where the expression for the 6548default value is a @code{const} expression, indicates an attribute that 6549is constant for a given run of the compiler. Constant attributes may be 6550used to specify which variety of processor is used. For example, 6551 6552@smallexample 6553(define_attr "cpu" "m88100,m88110,m88000" 6554 (const 6555 (cond [(symbol_ref "TARGET_88100") (const_string "m88100") 6556 (symbol_ref "TARGET_88110") (const_string "m88110")] 6557 (const_string "m88000")))) 6558 6559(define_attr "memory" "fast,slow" 6560 (const 6561 (if_then_else (symbol_ref "TARGET_FAST_MEM") 6562 (const_string "fast") 6563 (const_string "slow")))) 6564@end smallexample 6565 6566The routine generated for constant attributes has no parameters as it 6567does not depend on any particular insn. RTL expressions used to define 6568the value of a constant attribute may use the @code{symbol_ref} form, 6569but may not use either the @code{match_operand} form or @code{eq_attr} 6570forms involving insn attributes. 6571 6572@end ifset 6573@ifset INTERNALS 6574@node Delay Slots 6575@subsection Delay Slot Scheduling 6576@cindex delay slots, defining 6577 6578The insn attribute mechanism can be used to specify the requirements for 6579delay slots, if any, on a target machine. An instruction is said to 6580require a @dfn{delay slot} if some instructions that are physically 6581after the instruction are executed as if they were located before it. 6582Classic examples are branch and call instructions, which often execute 6583the following instruction before the branch or call is performed. 6584 6585On some machines, conditional branch instructions can optionally 6586@dfn{annul} instructions in the delay slot. This means that the 6587instruction will not be executed for certain branch outcomes. Both 6588instructions that annul if the branch is true and instructions that 6589annul if the branch is false are supported. 6590 6591Delay slot scheduling differs from instruction scheduling in that 6592determining whether an instruction needs a delay slot is dependent only 6593on the type of instruction being generated, not on data flow between the 6594instructions. See the next section for a discussion of data-dependent 6595instruction scheduling. 6596 6597@findex define_delay 6598The requirement of an insn needing one or more delay slots is indicated 6599via the @code{define_delay} expression. It has the following form: 6600 6601@smallexample 6602(define_delay @var{test} 6603 [@var{delay-1} @var{annul-true-1} @var{annul-false-1} 6604 @var{delay-2} @var{annul-true-2} @var{annul-false-2} 6605 @dots{}]) 6606@end smallexample 6607 6608@var{test} is an attribute test that indicates whether this 6609@code{define_delay} applies to a particular insn. If so, the number of 6610required delay slots is determined by the length of the vector specified 6611as the second argument. An insn placed in delay slot @var{n} must 6612satisfy attribute test @var{delay-n}. @var{annul-true-n} is an 6613attribute test that specifies which insns may be annulled if the branch 6614is true. Similarly, @var{annul-false-n} specifies which insns in the 6615delay slot may be annulled if the branch is false. If annulling is not 6616supported for that delay slot, @code{(nil)} should be coded. 6617 6618For example, in the common case where branch and call insns require 6619a single delay slot, which may contain any insn other than a branch or 6620call, the following would be placed in the @file{md} file: 6621 6622@smallexample 6623(define_delay (eq_attr "type" "branch,call") 6624 [(eq_attr "type" "!branch,call") (nil) (nil)]) 6625@end smallexample 6626 6627Multiple @code{define_delay} expressions may be specified. In this 6628case, each such expression specifies different delay slot requirements 6629and there must be no insn for which tests in two @code{define_delay} 6630expressions are both true. 6631 6632For example, if we have a machine that requires one delay slot for branches 6633but two for calls, no delay slot can contain a branch or call insn, 6634and any valid insn in the delay slot for the branch can be annulled if the 6635branch is true, we might represent this as follows: 6636 6637@smallexample 6638(define_delay (eq_attr "type" "branch") 6639 [(eq_attr "type" "!branch,call") 6640 (eq_attr "type" "!branch,call") 6641 (nil)]) 6642 6643(define_delay (eq_attr "type" "call") 6644 [(eq_attr "type" "!branch,call") (nil) (nil) 6645 (eq_attr "type" "!branch,call") (nil) (nil)]) 6646@end smallexample 6647@c the above is *still* too long. --mew 4feb93 6648 6649@end ifset 6650@ifset INTERNALS 6651@node Processor pipeline description 6652@subsection Specifying processor pipeline description 6653@cindex processor pipeline description 6654@cindex processor functional units 6655@cindex instruction latency time 6656@cindex interlock delays 6657@cindex data dependence delays 6658@cindex reservation delays 6659@cindex pipeline hazard recognizer 6660@cindex automaton based pipeline description 6661@cindex regular expressions 6662@cindex deterministic finite state automaton 6663@cindex automaton based scheduler 6664@cindex RISC 6665@cindex VLIW 6666 6667To achieve better performance, most modern processors 6668(super-pipelined, superscalar @acronym{RISC}, and @acronym{VLIW} 6669processors) have many @dfn{functional units} on which several 6670instructions can be executed simultaneously. An instruction starts 6671execution if its issue conditions are satisfied. If not, the 6672instruction is stalled until its conditions are satisfied. Such 6673@dfn{interlock (pipeline) delay} causes interruption of the fetching 6674of successor instructions (or demands nop instructions, e.g.@: for some 6675MIPS processors). 6676 6677There are two major kinds of interlock delays in modern processors. 6678The first one is a data dependence delay determining @dfn{instruction 6679latency time}. The instruction execution is not started until all 6680source data have been evaluated by prior instructions (there are more 6681complex cases when the instruction execution starts even when the data 6682are not available but will be ready in given time after the 6683instruction execution start). Taking the data dependence delays into 6684account is simple. The data dependence (true, output, and 6685anti-dependence) delay between two instructions is given by a 6686constant. In most cases this approach is adequate. The second kind 6687of interlock delays is a reservation delay. The reservation delay 6688means that two instructions under execution will be in need of shared 6689processors resources, i.e.@: buses, internal registers, and/or 6690functional units, which are reserved for some time. Taking this kind 6691of delay into account is complex especially for modern @acronym{RISC} 6692processors. 6693 6694The task of exploiting more processor parallelism is solved by an 6695instruction scheduler. For a better solution to this problem, the 6696instruction scheduler has to have an adequate description of the 6697processor parallelism (or @dfn{pipeline description}). GCC 6698machine descriptions describe processor parallelism and functional 6699unit reservations for groups of instructions with the aid of 6700@dfn{regular expressions}. 6701 6702The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to 6703figure out the possibility of the instruction issue by the processor 6704on a given simulated processor cycle. The pipeline hazard recognizer is 6705automatically generated from the processor pipeline description. The 6706pipeline hazard recognizer generated from the machine description 6707is based on a deterministic finite state automaton (@acronym{DFA}): 6708the instruction issue is possible if there is a transition from one 6709automaton state to another one. This algorithm is very fast, and 6710furthermore, its speed is not dependent on processor 6711complexity@footnote{However, the size of the automaton depends on 6712 processor complexity. To limit this effect, machine descriptions 6713 can split orthogonal parts of the machine description among several 6714 automata: but then, since each of these must be stepped independently, 6715 this does cause a small decrease in the algorithm's performance.}. 6716 6717@cindex automaton based pipeline description 6718The rest of this section describes the directives that constitute 6719an automaton-based processor pipeline description. The order of 6720these constructions within the machine description file is not 6721important. 6722 6723@findex define_automaton 6724@cindex pipeline hazard recognizer 6725The following optional construction describes names of automata 6726generated and used for the pipeline hazards recognition. Sometimes 6727the generated finite state automaton used by the pipeline hazard 6728recognizer is large. If we use more than one automaton and bind functional 6729units to the automata, the total size of the automata is usually 6730less than the size of the single automaton. If there is no one such 6731construction, only one finite state automaton is generated. 6732 6733@smallexample 6734(define_automaton @var{automata-names}) 6735@end smallexample 6736 6737@var{automata-names} is a string giving names of the automata. The 6738names are separated by commas. All the automata should have unique names. 6739The automaton name is used in the constructions @code{define_cpu_unit} and 6740@code{define_query_cpu_unit}. 6741 6742@findex define_cpu_unit 6743@cindex processor functional units 6744Each processor functional unit used in the description of instruction 6745reservations should be described by the following construction. 6746 6747@smallexample 6748(define_cpu_unit @var{unit-names} [@var{automaton-name}]) 6749@end smallexample 6750 6751@var{unit-names} is a string giving the names of the functional units 6752separated by commas. Don't use name @samp{nothing}, it is reserved 6753for other goals. 6754 6755@var{automaton-name} is a string giving the name of the automaton with 6756which the unit is bound. The automaton should be described in 6757construction @code{define_automaton}. You should give 6758@dfn{automaton-name}, if there is a defined automaton. 6759 6760The assignment of units to automata are constrained by the uses of the 6761units in insn reservations. The most important constraint is: if a 6762unit reservation is present on a particular cycle of an alternative 6763for an insn reservation, then some unit from the same automaton must 6764be present on the same cycle for the other alternatives of the insn 6765reservation. The rest of the constraints are mentioned in the 6766description of the subsequent constructions. 6767 6768@findex define_query_cpu_unit 6769@cindex querying function unit reservations 6770The following construction describes CPU functional units analogously 6771to @code{define_cpu_unit}. The reservation of such units can be 6772queried for an automaton state. The instruction scheduler never 6773queries reservation of functional units for given automaton state. So 6774as a rule, you don't need this construction. This construction could 6775be used for future code generation goals (e.g.@: to generate 6776@acronym{VLIW} insn templates). 6777 6778@smallexample 6779(define_query_cpu_unit @var{unit-names} [@var{automaton-name}]) 6780@end smallexample 6781 6782@var{unit-names} is a string giving names of the functional units 6783separated by commas. 6784 6785@var{automaton-name} is a string giving the name of the automaton with 6786which the unit is bound. 6787 6788@findex define_insn_reservation 6789@cindex instruction latency time 6790@cindex regular expressions 6791@cindex data bypass 6792The following construction is the major one to describe pipeline 6793characteristics of an instruction. 6794 6795@smallexample 6796(define_insn_reservation @var{insn-name} @var{default_latency} 6797 @var{condition} @var{regexp}) 6798@end smallexample 6799 6800@var{default_latency} is a number giving latency time of the 6801instruction. There is an important difference between the old 6802description and the automaton based pipeline description. The latency 6803time is used for all dependencies when we use the old description. In 6804the automaton based pipeline description, the given latency time is only 6805used for true dependencies. The cost of anti-dependencies is always 6806zero and the cost of output dependencies is the difference between 6807latency times of the producing and consuming insns (if the difference 6808is negative, the cost is considered to be zero). You can always 6809change the default costs for any description by using the target hook 6810@code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}). 6811 6812@var{insn-name} is a string giving the internal name of the insn. The 6813internal names are used in constructions @code{define_bypass} and in 6814the automaton description file generated for debugging. The internal 6815name has nothing in common with the names in @code{define_insn}. It is a 6816good practice to use insn classes described in the processor manual. 6817 6818@var{condition} defines what RTL insns are described by this 6819construction. You should remember that you will be in trouble if 6820@var{condition} for two or more different 6821@code{define_insn_reservation} constructions is TRUE for an insn. In 6822this case what reservation will be used for the insn is not defined. 6823Such cases are not checked during generation of the pipeline hazards 6824recognizer because in general recognizing that two conditions may have 6825the same value is quite difficult (especially if the conditions 6826contain @code{symbol_ref}). It is also not checked during the 6827pipeline hazard recognizer work because it would slow down the 6828recognizer considerably. 6829 6830@var{regexp} is a string describing the reservation of the cpu's functional 6831units by the instruction. The reservations are described by a regular 6832expression according to the following syntax: 6833 6834@smallexample 6835 regexp = regexp "," oneof 6836 | oneof 6837 6838 oneof = oneof "|" allof 6839 | allof 6840 6841 allof = allof "+" repeat 6842 | repeat 6843 6844 repeat = element "*" number 6845 | element 6846 6847 element = cpu_function_unit_name 6848 | reservation_name 6849 | result_name 6850 | "nothing" 6851 | "(" regexp ")" 6852@end smallexample 6853 6854@itemize @bullet 6855@item 6856@samp{,} is used for describing the start of the next cycle in 6857the reservation. 6858 6859@item 6860@samp{|} is used for describing a reservation described by the first 6861regular expression @strong{or} a reservation described by the second 6862regular expression @strong{or} etc. 6863 6864@item 6865@samp{+} is used for describing a reservation described by the first 6866regular expression @strong{and} a reservation described by the 6867second regular expression @strong{and} etc. 6868 6869@item 6870@samp{*} is used for convenience and simply means a sequence in which 6871the regular expression are repeated @var{number} times with cycle 6872advancing (see @samp{,}). 6873 6874@item 6875@samp{cpu_function_unit_name} denotes reservation of the named 6876functional unit. 6877 6878@item 6879@samp{reservation_name} --- see description of construction 6880@samp{define_reservation}. 6881 6882@item 6883@samp{nothing} denotes no unit reservations. 6884@end itemize 6885 6886@findex define_reservation 6887Sometimes unit reservations for different insns contain common parts. 6888In such case, you can simplify the pipeline description by describing 6889the common part by the following construction 6890 6891@smallexample 6892(define_reservation @var{reservation-name} @var{regexp}) 6893@end smallexample 6894 6895@var{reservation-name} is a string giving name of @var{regexp}. 6896Functional unit names and reservation names are in the same name 6897space. So the reservation names should be different from the 6898functional unit names and can not be the reserved name @samp{nothing}. 6899 6900@findex define_bypass 6901@cindex instruction latency time 6902@cindex data bypass 6903The following construction is used to describe exceptions in the 6904latency time for given instruction pair. This is so called bypasses. 6905 6906@smallexample 6907(define_bypass @var{number} @var{out_insn_names} @var{in_insn_names} 6908 [@var{guard}]) 6909@end smallexample 6910 6911@var{number} defines when the result generated by the instructions 6912given in string @var{out_insn_names} will be ready for the 6913instructions given in string @var{in_insn_names}. The instructions in 6914the string are separated by commas. 6915 6916@var{guard} is an optional string giving the name of a C function which 6917defines an additional guard for the bypass. The function will get the 6918two insns as parameters. If the function returns zero the bypass will 6919be ignored for this case. The additional guard is necessary to 6920recognize complicated bypasses, e.g.@: when the consumer is only an address 6921of insn @samp{store} (not a stored value). 6922 6923@findex exclusion_set 6924@findex presence_set 6925@findex final_presence_set 6926@findex absence_set 6927@findex final_absence_set 6928@cindex VLIW 6929@cindex RISC 6930The following five constructions are usually used to describe 6931@acronym{VLIW} processors, or more precisely, to describe a placement 6932of small instructions into @acronym{VLIW} instruction slots. They 6933can be used for @acronym{RISC} processors, too. 6934 6935@smallexample 6936(exclusion_set @var{unit-names} @var{unit-names}) 6937(presence_set @var{unit-names} @var{patterns}) 6938(final_presence_set @var{unit-names} @var{patterns}) 6939(absence_set @var{unit-names} @var{patterns}) 6940(final_absence_set @var{unit-names} @var{patterns}) 6941@end smallexample 6942 6943@var{unit-names} is a string giving names of functional units 6944separated by commas. 6945 6946@var{patterns} is a string giving patterns of functional units 6947separated by comma. Currently pattern is one unit or units 6948separated by white-spaces. 6949 6950The first construction (@samp{exclusion_set}) means that each 6951functional unit in the first string can not be reserved simultaneously 6952with a unit whose name is in the second string and vice versa. For 6953example, the construction is useful for describing processors 6954(e.g.@: some SPARC processors) with a fully pipelined floating point 6955functional unit which can execute simultaneously only single floating 6956point insns or only double floating point insns. 6957 6958The second construction (@samp{presence_set}) means that each 6959functional unit in the first string can not be reserved unless at 6960least one of pattern of units whose names are in the second string is 6961reserved. This is an asymmetric relation. For example, it is useful 6962for description that @acronym{VLIW} @samp{slot1} is reserved after 6963@samp{slot0} reservation. We could describe it by the following 6964construction 6965 6966@smallexample 6967(presence_set "slot1" "slot0") 6968@end smallexample 6969 6970Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0} 6971reservation. In this case we could write 6972 6973@smallexample 6974(presence_set "slot1" "slot0 b0") 6975@end smallexample 6976 6977The third construction (@samp{final_presence_set}) is analogous to 6978@samp{presence_set}. The difference between them is when checking is 6979done. When an instruction is issued in given automaton state 6980reflecting all current and planned unit reservations, the automaton 6981state is changed. The first state is a source state, the second one 6982is a result state. Checking for @samp{presence_set} is done on the 6983source state reservation, checking for @samp{final_presence_set} is 6984done on the result reservation. This construction is useful to 6985describe a reservation which is actually two subsequent reservations. 6986For example, if we use 6987 6988@smallexample 6989(presence_set "slot1" "slot0") 6990@end smallexample 6991 6992the following insn will be never issued (because @samp{slot1} requires 6993@samp{slot0} which is absent in the source state). 6994 6995@smallexample 6996(define_reservation "insn_and_nop" "slot0 + slot1") 6997@end smallexample 6998 6999but it can be issued if we use analogous @samp{final_presence_set}. 7000 7001The forth construction (@samp{absence_set}) means that each functional 7002unit in the first string can be reserved only if each pattern of units 7003whose names are in the second string is not reserved. This is an 7004asymmetric relation (actually @samp{exclusion_set} is analogous to 7005this one but it is symmetric). For example it might be useful in a 7006@acronym{VLIW} description to say that @samp{slot0} cannot be reserved 7007after either @samp{slot1} or @samp{slot2} have been reserved. This 7008can be described as: 7009 7010@smallexample 7011(absence_set "slot0" "slot1, slot2") 7012@end smallexample 7013 7014Or @samp{slot2} can not be reserved if @samp{slot0} and unit @samp{b0} 7015are reserved or @samp{slot1} and unit @samp{b1} are reserved. In 7016this case we could write 7017 7018@smallexample 7019(absence_set "slot2" "slot0 b0, slot1 b1") 7020@end smallexample 7021 7022All functional units mentioned in a set should belong to the same 7023automaton. 7024 7025The last construction (@samp{final_absence_set}) is analogous to 7026@samp{absence_set} but checking is done on the result (state) 7027reservation. See comments for @samp{final_presence_set}. 7028 7029@findex automata_option 7030@cindex deterministic finite state automaton 7031@cindex nondeterministic finite state automaton 7032@cindex finite state automaton minimization 7033You can control the generator of the pipeline hazard recognizer with 7034the following construction. 7035 7036@smallexample 7037(automata_option @var{options}) 7038@end smallexample 7039 7040@var{options} is a string giving options which affect the generated 7041code. Currently there are the following options: 7042 7043@itemize @bullet 7044@item 7045@dfn{no-minimization} makes no minimization of the automaton. This is 7046only worth to do when we are debugging the description and need to 7047look more accurately at reservations of states. 7048 7049@item 7050@dfn{time} means printing additional time statistics about 7051generation of automata. 7052 7053@item 7054@dfn{v} means a generation of the file describing the result automata. 7055The file has suffix @samp{.dfa} and can be used for the description 7056verification and debugging. 7057 7058@item 7059@dfn{w} means a generation of warning instead of error for 7060non-critical errors. 7061 7062@item 7063@dfn{ndfa} makes nondeterministic finite state automata. This affects 7064the treatment of operator @samp{|} in the regular expressions. The 7065usual treatment of the operator is to try the first alternative and, 7066if the reservation is not possible, the second alternative. The 7067nondeterministic treatment means trying all alternatives, some of them 7068may be rejected by reservations in the subsequent insns. 7069 7070@item 7071@dfn{progress} means output of a progress bar showing how many states 7072were generated so far for automaton being processed. This is useful 7073during debugging a @acronym{DFA} description. If you see too many 7074generated states, you could interrupt the generator of the pipeline 7075hazard recognizer and try to figure out a reason for generation of the 7076huge automaton. 7077@end itemize 7078 7079As an example, consider a superscalar @acronym{RISC} machine which can 7080issue three insns (two integer insns and one floating point insn) on 7081the cycle but can finish only two insns. To describe this, we define 7082the following functional units. 7083 7084@smallexample 7085(define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline") 7086(define_cpu_unit "port0, port1") 7087@end smallexample 7088 7089All simple integer insns can be executed in any integer pipeline and 7090their result is ready in two cycles. The simple integer insns are 7091issued into the first pipeline unless it is reserved, otherwise they 7092are issued into the second pipeline. Integer division and 7093multiplication insns can be executed only in the second integer 7094pipeline and their results are ready correspondingly in 8 and 4 7095cycles. The integer division is not pipelined, i.e.@: the subsequent 7096integer division insn can not be issued until the current division 7097insn finished. Floating point insns are fully pipelined and their 7098results are ready in 3 cycles. Where the result of a floating point 7099insn is used by an integer insn, an additional delay of one cycle is 7100incurred. To describe all of this we could specify 7101 7102@smallexample 7103(define_cpu_unit "div") 7104 7105(define_insn_reservation "simple" 2 (eq_attr "type" "int") 7106 "(i0_pipeline | i1_pipeline), (port0 | port1)") 7107 7108(define_insn_reservation "mult" 4 (eq_attr "type" "mult") 7109 "i1_pipeline, nothing*2, (port0 | port1)") 7110 7111(define_insn_reservation "div" 8 (eq_attr "type" "div") 7112 "i1_pipeline, div*7, div + (port0 | port1)") 7113 7114(define_insn_reservation "float" 3 (eq_attr "type" "float") 7115 "f_pipeline, nothing, (port0 | port1)) 7116 7117(define_bypass 4 "float" "simple,mult,div") 7118@end smallexample 7119 7120To simplify the description we could describe the following reservation 7121 7122@smallexample 7123(define_reservation "finish" "port0|port1") 7124@end smallexample 7125 7126and use it in all @code{define_insn_reservation} as in the following 7127construction 7128 7129@smallexample 7130(define_insn_reservation "simple" 2 (eq_attr "type" "int") 7131 "(i0_pipeline | i1_pipeline), finish") 7132@end smallexample 7133 7134 7135@end ifset 7136@ifset INTERNALS 7137@node Conditional Execution 7138@section Conditional Execution 7139@cindex conditional execution 7140@cindex predication 7141 7142A number of architectures provide for some form of conditional 7143execution, or predication. The hallmark of this feature is the 7144ability to nullify most of the instructions in the instruction set. 7145When the instruction set is large and not entirely symmetric, it 7146can be quite tedious to describe these forms directly in the 7147@file{.md} file. An alternative is the @code{define_cond_exec} template. 7148 7149@findex define_cond_exec 7150@smallexample 7151(define_cond_exec 7152 [@var{predicate-pattern}] 7153 "@var{condition}" 7154 "@var{output-template}") 7155@end smallexample 7156 7157@var{predicate-pattern} is the condition that must be true for the 7158insn to be executed at runtime and should match a relational operator. 7159One can use @code{match_operator} to match several relational operators 7160at once. Any @code{match_operand} operands must have no more than one 7161alternative. 7162 7163@var{condition} is a C expression that must be true for the generated 7164pattern to match. 7165 7166@findex current_insn_predicate 7167@var{output-template} is a string similar to the @code{define_insn} 7168output template (@pxref{Output Template}), except that the @samp{*} 7169and @samp{@@} special cases do not apply. This is only useful if the 7170assembly text for the predicate is a simple prefix to the main insn. 7171In order to handle the general case, there is a global variable 7172@code{current_insn_predicate} that will contain the entire predicate 7173if the current insn is predicated, and will otherwise be @code{NULL}. 7174 7175When @code{define_cond_exec} is used, an implicit reference to 7176the @code{predicable} instruction attribute is made. 7177@xref{Insn Attributes}. This attribute must be boolean (i.e.@: have 7178exactly two elements in its @var{list-of-values}). Further, it must 7179not be used with complex expressions. That is, the default and all 7180uses in the insns must be a simple constant, not dependent on the 7181alternative or anything else. 7182 7183For each @code{define_insn} for which the @code{predicable} 7184attribute is true, a new @code{define_insn} pattern will be 7185generated that matches a predicated version of the instruction. 7186For example, 7187 7188@smallexample 7189(define_insn "addsi" 7190 [(set (match_operand:SI 0 "register_operand" "r") 7191 (plus:SI (match_operand:SI 1 "register_operand" "r") 7192 (match_operand:SI 2 "register_operand" "r")))] 7193 "@var{test1}" 7194 "add %2,%1,%0") 7195 7196(define_cond_exec 7197 [(ne (match_operand:CC 0 "register_operand" "c") 7198 (const_int 0))] 7199 "@var{test2}" 7200 "(%0)") 7201@end smallexample 7202 7203@noindent 7204generates a new pattern 7205 7206@smallexample 7207(define_insn "" 7208 [(cond_exec 7209 (ne (match_operand:CC 3 "register_operand" "c") (const_int 0)) 7210 (set (match_operand:SI 0 "register_operand" "r") 7211 (plus:SI (match_operand:SI 1 "register_operand" "r") 7212 (match_operand:SI 2 "register_operand" "r"))))] 7213 "(@var{test2}) && (@var{test1})" 7214 "(%3) add %2,%1,%0") 7215@end smallexample 7216 7217@end ifset 7218@ifset INTERNALS 7219@node Constant Definitions 7220@section Constant Definitions 7221@cindex constant definitions 7222@findex define_constants 7223 7224Using literal constants inside instruction patterns reduces legibility and 7225can be a maintenance problem. 7226 7227To overcome this problem, you may use the @code{define_constants} 7228expression. It contains a vector of name-value pairs. From that 7229point on, wherever any of the names appears in the MD file, it is as 7230if the corresponding value had been written instead. You may use 7231@code{define_constants} multiple times; each appearance adds more 7232constants to the table. It is an error to redefine a constant with 7233a different value. 7234 7235To come back to the a29k load multiple example, instead of 7236 7237@smallexample 7238(define_insn "" 7239 [(match_parallel 0 "load_multiple_operation" 7240 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 7241 (match_operand:SI 2 "memory_operand" "m")) 7242 (use (reg:SI 179)) 7243 (clobber (reg:SI 179))])] 7244 "" 7245 "loadm 0,0,%1,%2") 7246@end smallexample 7247 7248You could write: 7249 7250@smallexample 7251(define_constants [ 7252 (R_BP 177) 7253 (R_FC 178) 7254 (R_CR 179) 7255 (R_Q 180) 7256]) 7257 7258(define_insn "" 7259 [(match_parallel 0 "load_multiple_operation" 7260 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 7261 (match_operand:SI 2 "memory_operand" "m")) 7262 (use (reg:SI R_CR)) 7263 (clobber (reg:SI R_CR))])] 7264 "" 7265 "loadm 0,0,%1,%2") 7266@end smallexample 7267 7268The constants that are defined with a define_constant are also output 7269in the insn-codes.h header file as #defines. 7270@end ifset 7271@ifset INTERNALS 7272@node Macros 7273@section Macros 7274@cindex macros in @file{.md} files 7275 7276Ports often need to define similar patterns for more than one machine 7277mode or for more than one rtx code. GCC provides some simple macro 7278facilities to make this process easier. 7279 7280@menu 7281* Mode Macros:: Generating variations of patterns for different modes. 7282* Code Macros:: Doing the same for codes. 7283@end menu 7284 7285@node Mode Macros 7286@subsection Mode Macros 7287@cindex mode macros in @file{.md} files 7288 7289Ports often need to define similar patterns for two or more different modes. 7290For example: 7291 7292@itemize @bullet 7293@item 7294If a processor has hardware support for both single and double 7295floating-point arithmetic, the @code{SFmode} patterns tend to be 7296very similar to the @code{DFmode} ones. 7297 7298@item 7299If a port uses @code{SImode} pointers in one configuration and 7300@code{DImode} pointers in another, it will usually have very similar 7301@code{SImode} and @code{DImode} patterns for manipulating pointers. 7302@end itemize 7303 7304Mode macros allow several patterns to be instantiated from one 7305@file{.md} file template. They can be used with any type of 7306rtx-based construct, such as a @code{define_insn}, 7307@code{define_split}, or @code{define_peephole2}. 7308 7309@menu 7310* Defining Mode Macros:: Defining a new mode macro. 7311* Substitutions:: Combining mode macros with substitutions 7312* Examples:: Examples 7313@end menu 7314 7315@node Defining Mode Macros 7316@subsubsection Defining Mode Macros 7317@findex define_mode_macro 7318 7319The syntax for defining a mode macro is: 7320 7321@smallexample 7322(define_mode_macro @var{name} [(@var{mode1} "@var{cond1}") ... (@var{moden} "@var{condn}")]) 7323@end smallexample 7324 7325This allows subsequent @file{.md} file constructs to use the mode suffix 7326@code{:@var{name}}. Every construct that does so will be expanded 7327@var{n} times, once with every use of @code{:@var{name}} replaced by 7328@code{:@var{mode1}}, once with every use replaced by @code{:@var{mode2}}, 7329and so on. In the expansion for a particular @var{modei}, every 7330C condition will also require that @var{condi} be true. 7331 7332For example: 7333 7334@smallexample 7335(define_mode_macro P [(SI "Pmode == SImode") (DI "Pmode == DImode")]) 7336@end smallexample 7337 7338defines a new mode suffix @code{:P}. Every construct that uses 7339@code{:P} will be expanded twice, once with every @code{:P} replaced 7340by @code{:SI} and once with every @code{:P} replaced by @code{:DI}. 7341The @code{:SI} version will only apply if @code{Pmode == SImode} and 7342the @code{:DI} version will only apply if @code{Pmode == DImode}. 7343 7344As with other @file{.md} conditions, an empty string is treated 7345as ``always true''. @code{(@var{mode} "")} can also be abbreviated 7346to @code{@var{mode}}. For example: 7347 7348@smallexample 7349(define_mode_macro GPR [SI (DI "TARGET_64BIT")]) 7350@end smallexample 7351 7352means that the @code{:DI} expansion only applies if @code{TARGET_64BIT} 7353but that the @code{:SI} expansion has no such constraint. 7354 7355Macros are applied in the order they are defined. This can be 7356significant if two macros are used in a construct that requires 7357substitutions. @xref{Substitutions}. 7358 7359@node Substitutions 7360@subsubsection Substitution in Mode Macros 7361@findex define_mode_attr 7362 7363If an @file{.md} file construct uses mode macros, each version of the 7364construct will often need slightly different strings or modes. For 7365example: 7366 7367@itemize @bullet 7368@item 7369When a @code{define_expand} defines several @code{add@var{m}3} patterns 7370(@pxref{Standard Names}), each expander will need to use the 7371appropriate mode name for @var{m}. 7372 7373@item 7374When a @code{define_insn} defines several instruction patterns, 7375each instruction will often use a different assembler mnemonic. 7376 7377@item 7378When a @code{define_insn} requires operands with different modes, 7379using a macro for one of the operand modes usually requires a specific 7380mode for the other operand(s). 7381@end itemize 7382 7383GCC supports such variations through a system of ``mode attributes''. 7384There are two standard attributes: @code{mode}, which is the name of 7385the mode in lower case, and @code{MODE}, which is the same thing in 7386upper case. You can define other attributes using: 7387 7388@smallexample 7389(define_mode_attr @var{name} [(@var{mode1} "@var{value1}") ... (@var{moden} "@var{valuen}")]) 7390@end smallexample 7391 7392where @var{name} is the name of the attribute and @var{valuei} 7393is the value associated with @var{modei}. 7394 7395When GCC replaces some @var{:macro} with @var{:mode}, it will scan 7396each string and mode in the pattern for sequences of the form 7397@code{<@var{macro}:@var{attr}>}, where @var{attr} is the name of a 7398mode attribute. If the attribute is defined for @var{mode}, the whole 7399@code{<...>} sequence will be replaced by the appropriate attribute 7400value. 7401 7402For example, suppose an @file{.md} file has: 7403 7404@smallexample 7405(define_mode_macro P [(SI "Pmode == SImode") (DI "Pmode == DImode")]) 7406(define_mode_attr load [(SI "lw") (DI "ld")]) 7407@end smallexample 7408 7409If one of the patterns that uses @code{:P} contains the string 7410@code{"<P:load>\t%0,%1"}, the @code{SI} version of that pattern 7411will use @code{"lw\t%0,%1"} and the @code{DI} version will use 7412@code{"ld\t%0,%1"}. 7413 7414Here is an example of using an attribute for a mode: 7415 7416@smallexample 7417(define_mode_macro LONG [SI DI]) 7418(define_mode_attr SHORT [(SI "HI") (DI "SI")]) 7419(define_insn ... 7420 (sign_extend:LONG (match_operand:<LONG:SHORT> ...)) ...) 7421@end smallexample 7422 7423The @code{@var{macro}:} prefix may be omitted, in which case the 7424substitution will be attempted for every macro expansion. 7425 7426@node Examples 7427@subsubsection Mode Macro Examples 7428 7429Here is an example from the MIPS port. It defines the following 7430modes and attributes (among others): 7431 7432@smallexample 7433(define_mode_macro GPR [SI (DI "TARGET_64BIT")]) 7434(define_mode_attr d [(SI "") (DI "d")]) 7435@end smallexample 7436 7437and uses the following template to define both @code{subsi3} 7438and @code{subdi3}: 7439 7440@smallexample 7441(define_insn "sub<mode>3" 7442 [(set (match_operand:GPR 0 "register_operand" "=d") 7443 (minus:GPR (match_operand:GPR 1 "register_operand" "d") 7444 (match_operand:GPR 2 "register_operand" "d")))] 7445 "" 7446 "<d>subu\t%0,%1,%2" 7447 [(set_attr "type" "arith") 7448 (set_attr "mode" "<MODE>")]) 7449@end smallexample 7450 7451This is exactly equivalent to: 7452 7453@smallexample 7454(define_insn "subsi3" 7455 [(set (match_operand:SI 0 "register_operand" "=d") 7456 (minus:SI (match_operand:SI 1 "register_operand" "d") 7457 (match_operand:SI 2 "register_operand" "d")))] 7458 "" 7459 "subu\t%0,%1,%2" 7460 [(set_attr "type" "arith") 7461 (set_attr "mode" "SI")]) 7462 7463(define_insn "subdi3" 7464 [(set (match_operand:DI 0 "register_operand" "=d") 7465 (minus:DI (match_operand:DI 1 "register_operand" "d") 7466 (match_operand:DI 2 "register_operand" "d")))] 7467 "" 7468 "dsubu\t%0,%1,%2" 7469 [(set_attr "type" "arith") 7470 (set_attr "mode" "DI")]) 7471@end smallexample 7472 7473@node Code Macros 7474@subsection Code Macros 7475@cindex code macros in @file{.md} files 7476@findex define_code_macro 7477@findex define_code_attr 7478 7479Code macros operate in a similar way to mode macros. @xref{Mode Macros}. 7480 7481The construct: 7482 7483@smallexample 7484(define_code_macro @var{name} [(@var{code1} "@var{cond1}") ... (@var{coden} "@var{condn}")]) 7485@end smallexample 7486 7487defines a pseudo rtx code @var{name} that can be instantiated as 7488@var{codei} if condition @var{condi} is true. Each @var{codei} 7489must have the same rtx format. @xref{RTL Classes}. 7490 7491As with mode macros, each pattern that uses @var{name} will be 7492expanded @var{n} times, once with all uses of @var{name} replaced by 7493@var{code1}, once with all uses replaced by @var{code2}, and so on. 7494@xref{Defining Mode Macros}. 7495 7496It is possible to define attributes for codes as well as for modes. 7497There are two standard code attributes: @code{code}, the name of the 7498code in lower case, and @code{CODE}, the name of the code in upper case. 7499Other attributes are defined using: 7500 7501@smallexample 7502(define_code_attr @var{name} [(@var{code1} "@var{value1}") ... (@var{coden} "@var{valuen}")]) 7503@end smallexample 7504 7505Here's an example of code macros in action, taken from the MIPS port: 7506 7507@smallexample 7508(define_code_macro any_cond [unordered ordered unlt unge uneq ltgt unle ungt 7509 eq ne gt ge lt le gtu geu ltu leu]) 7510 7511(define_expand "b<code>" 7512 [(set (pc) 7513 (if_then_else (any_cond:CC (cc0) 7514 (const_int 0)) 7515 (label_ref (match_operand 0 "")) 7516 (pc)))] 7517 "" 7518@{ 7519 gen_conditional_branch (operands, <CODE>); 7520 DONE; 7521@}) 7522@end smallexample 7523 7524This is equivalent to: 7525 7526@smallexample 7527(define_expand "bunordered" 7528 [(set (pc) 7529 (if_then_else (unordered:CC (cc0) 7530 (const_int 0)) 7531 (label_ref (match_operand 0 "")) 7532 (pc)))] 7533 "" 7534@{ 7535 gen_conditional_branch (operands, UNORDERED); 7536 DONE; 7537@}) 7538 7539(define_expand "bordered" 7540 [(set (pc) 7541 (if_then_else (ordered:CC (cc0) 7542 (const_int 0)) 7543 (label_ref (match_operand 0 "")) 7544 (pc)))] 7545 "" 7546@{ 7547 gen_conditional_branch (operands, ORDERED); 7548 DONE; 7549@}) 7550 7551... 7552@end smallexample 7553 7554@end ifset 7555