1@c Copyright (C) 1988, 89, 92, 93, 94, 96, 1998 Free Software Foundation, Inc. 2@c This is part of the GCC manual. 3@c For copying conditions, see the file gcc.texi. 4 5@ifset INTERNALS 6@node Machine Desc 7@chapter Machine Descriptions 8@cindex machine descriptions 9 10A machine description has two parts: a file of instruction patterns 11(@file{.md} file) and a C header file of macro definitions. 12 13The @file{.md} file for a target machine contains a pattern for each 14instruction that the target machine supports (or at least each instruction 15that is worth telling the compiler about). It may also contain comments. 16A semicolon causes the rest of the line to be a comment, unless the semicolon 17is inside a quoted string. 18 19See the next chapter for information on the C header file. 20 21@menu 22* Patterns:: How to write instruction patterns. 23* Example:: An explained example of a @code{define_insn} pattern. 24* RTL Template:: The RTL template defines what insns match a pattern. 25* Output Template:: The output template says how to make assembler code 26 from such an insn. 27* Output Statement:: For more generality, write C code to output 28 the assembler code. 29* Constraints:: When not all operands are general operands. 30* Standard Names:: Names mark patterns to use for code generation. 31* Pattern Ordering:: When the order of patterns makes a difference. 32* Dependent Patterns:: Having one pattern may make you need another. 33* Jump Patterns:: Special considerations for patterns for jump insns. 34* Insn Canonicalizations::Canonicalization of Instructions 35* Peephole Definitions::Defining machine-specific peephole optimizations. 36* Expander Definitions::Generating a sequence of several RTL insns 37 for a standard operation. 38* Insn Splitting:: Splitting Instructions into Multiple Instructions 39* Insn Attributes:: Specifying the value of attributes for generated insns. 40@end menu 41 42@node Patterns 43@section Everything about Instruction Patterns 44@cindex patterns 45@cindex instruction patterns 46 47@findex define_insn 48Each instruction pattern contains an incomplete RTL expression, with pieces 49to be filled in later, operand constraints that restrict how the pieces can 50be filled in, and an output pattern or C code to generate the assembler 51output, all wrapped up in a @code{define_insn} expression. 52 53A @code{define_insn} is an RTL expression containing four or five operands: 54 55@enumerate 56@item 57An optional name. The presence of a name indicate that this instruction 58pattern can perform a certain standard job for the RTL-generation 59pass of the compiler. This pass knows certain names and will use 60the instruction patterns with those names, if the names are defined 61in the machine description. 62 63The absence of a name is indicated by writing an empty string 64where the name should go. Nameless instruction patterns are never 65used for generating RTL code, but they may permit several simpler insns 66to be combined later on. 67 68Names that are not thus known and used in RTL-generation have no 69effect; they are equivalent to no name at all. 70 71@item 72The @dfn{RTL template} (@pxref{RTL Template}) is a vector of incomplete 73RTL expressions which show what the instruction should look like. It is 74incomplete because it may contain @code{match_operand}, 75@code{match_operator}, and @code{match_dup} expressions that stand for 76operands of the instruction. 77 78If the vector has only one element, that element is the template for the 79instruction pattern. If the vector has multiple elements, then the 80instruction pattern is a @code{parallel} expression containing the 81elements described. 82 83@item 84@cindex pattern conditions 85@cindex conditions, in patterns 86A condition. This is a string which contains a C expression that is 87the final test to decide whether an insn body matches this pattern. 88 89@cindex named patterns and conditions 90For a named pattern, the condition (if present) may not depend on 91the data in the insn being matched, but only the target-machine-type 92flags. The compiler needs to test these conditions during 93initialization in order to learn exactly which named instructions are 94available in a particular run. 95 96@findex operands 97For nameless patterns, the condition is applied only when matching an 98individual insn, and only after the insn has matched the pattern's 99recognition template. The insn's operands may be found in the vector 100@code{operands}. 101 102@item 103The @dfn{output template}: a string that says how to output matching 104insns as assembler code. @samp{%} in this string specifies where 105to substitute the value of an operand. @xref{Output Template}. 106 107When simple substitution isn't general enough, you can specify a piece 108of C code to compute the output. @xref{Output Statement}. 109 110@item 111Optionally, a vector containing the values of attributes for insns matching 112this pattern. @xref{Insn Attributes}. 113@end enumerate 114 115@node Example 116@section Example of @code{define_insn} 117@cindex @code{define_insn} example 118 119Here is an actual example of an instruction pattern, for the 68000/68020. 120 121@example 122(define_insn "tstsi" 123 [(set (cc0) 124 (match_operand:SI 0 "general_operand" "rm"))] 125 "" 126 "* 127@{ if (TARGET_68020 || ! ADDRESS_REG_P (operands[0])) 128 return \"tstl %0\"; 129 return \"cmpl #0,%0\"; @}") 130@end example 131 132This is an instruction that sets the condition codes based on the value of 133a general operand. It has no condition, so any insn whose RTL description 134has the form shown may be handled according to this pattern. The name 135@samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation 136pass that, when it is necessary to test such a value, an insn to do so 137can be constructed using this pattern. 138 139The output control string is a piece of C code which chooses which 140output template to return based on the kind of operand and the specific 141type of CPU for which code is being generated. 142 143@samp{"rm"} is an operand constraint. Its meaning is explained below. 144 145@node RTL Template 146@section RTL Template 147@cindex RTL insn template 148@cindex generating insns 149@cindex insns, generating 150@cindex recognizing insns 151@cindex insns, recognizing 152 153The RTL template is used to define which insns match the particular pattern 154and how to find their operands. For named patterns, the RTL template also 155says how to construct an insn from specified operands. 156 157Construction involves substituting specified operands into a copy of the 158template. Matching involves determining the values that serve as the 159operands in the insn being matched. Both of these activities are 160controlled by special expression types that direct matching and 161substitution of the operands. 162 163@table @code 164@findex match_operand 165@item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint}) 166This expression is a placeholder for operand number @var{n} of 167the insn. When constructing an insn, operand number @var{n} 168will be substituted at this point. When matching an insn, whatever 169appears at this position in the insn will be taken as operand 170number @var{n}; but it must satisfy @var{predicate} or this instruction 171pattern will not match at all. 172 173Operand numbers must be chosen consecutively counting from zero in 174each instruction pattern. There may be only one @code{match_operand} 175expression in the pattern for each operand number. Usually operands 176are numbered in the order of appearance in @code{match_operand} 177expressions. In the case of a @code{define_expand}, any operand numbers 178used only in @code{match_dup} expressions have higher values than all 179other operand numbers. 180 181@var{predicate} is a string that is the name of a C function that accepts two 182arguments, an expression and a machine mode. During matching, the 183function will be called with the putative operand as the expression and 184@var{m} as the mode argument (if @var{m} is not specified, 185@code{VOIDmode} will be used, which normally causes @var{predicate} to accept 186any mode). If it returns zero, this instruction pattern fails to match. 187@var{predicate} may be an empty string; then it means no test is to be done 188on the operand, so anything which occurs in this position is valid. 189 190Most of the time, @var{predicate} will reject modes other than @var{m}---but 191not always. For example, the predicate @code{address_operand} uses 192@var{m} as the mode of memory ref that the address should be valid for. 193Many predicates accept @code{const_int} nodes even though their mode is 194@code{VOIDmode}. 195 196@var{constraint} controls reloading and the choice of the best register 197class to use for a value, as explained later (@pxref{Constraints}). 198 199People are often unclear on the difference between the constraint and the 200predicate. The predicate helps decide whether a given insn matches the 201pattern. The constraint plays no role in this decision; instead, it 202controls various decisions in the case of an insn which does match. 203 204@findex general_operand 205On CISC machines, the most common @var{predicate} is 206@code{"general_operand"}. This function checks that the putative 207operand is either a constant, a register or a memory reference, and that 208it is valid for mode @var{m}. 209 210@findex register_operand 211For an operand that must be a register, @var{predicate} should be 212@code{"register_operand"}. Using @code{"general_operand"} would be 213valid, since the reload pass would copy any non-register operands 214through registers, but this would make GNU CC do extra work, it would 215prevent invariant operands (such as constant) from being removed from 216loops, and it would prevent the register allocator from doing the best 217possible job. On RISC machines, it is usually most efficient to allow 218@var{predicate} to accept only objects that the constraints allow. 219 220@findex immediate_operand 221For an operand that must be a constant, you must be sure to either use 222@code{"immediate_operand"} for @var{predicate}, or make the instruction 223pattern's extra condition require a constant, or both. You cannot 224expect the constraints to do this work! If the constraints allow only 225constants, but the predicate allows something else, the compiler will 226crash when that case arises. 227 228@findex match_scratch 229@item (match_scratch:@var{m} @var{n} @var{constraint}) 230This expression is also a placeholder for operand number @var{n} 231and indicates that operand must be a @code{scratch} or @code{reg} 232expression. 233 234When matching patterns, this is equivalent to 235 236@smallexample 237(match_operand:@var{m} @var{n} "scratch_operand" @var{pred}) 238@end smallexample 239 240but, when generating RTL, it produces a (@code{scratch}:@var{m}) 241expression. 242 243If the last few expressions in a @code{parallel} are @code{clobber} 244expressions whose operands are either a hard register or 245@code{match_scratch}, the combiner can add or delete them when 246necessary. @xref{Side Effects}. 247 248@findex match_dup 249@item (match_dup @var{n}) 250This expression is also a placeholder for operand number @var{n}. 251It is used when the operand needs to appear more than once in the 252insn. 253 254In construction, @code{match_dup} acts just like @code{match_operand}: 255the operand is substituted into the insn being constructed. But in 256matching, @code{match_dup} behaves differently. It assumes that operand 257number @var{n} has already been determined by a @code{match_operand} 258appearing earlier in the recognition template, and it matches only an 259identical-looking expression. 260 261@findex match_operator 262@item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}]) 263This pattern is a kind of placeholder for a variable RTL expression 264code. 265 266When constructing an insn, it stands for an RTL expression whose 267expression code is taken from that of operand @var{n}, and whose 268operands are constructed from the patterns @var{operands}. 269 270When matching an expression, it matches an expression if the function 271@var{predicate} returns nonzero on that expression @emph{and} the 272patterns @var{operands} match the operands of the expression. 273 274Suppose that the function @code{commutative_operator} is defined as 275follows, to match any expression whose operator is one of the 276commutative arithmetic operators of RTL and whose mode is @var{mode}: 277 278@smallexample 279int 280commutative_operator (x, mode) 281 rtx x; 282 enum machine_mode mode; 283@{ 284 enum rtx_code code = GET_CODE (x); 285 if (GET_MODE (x) != mode) 286 return 0; 287 return (GET_RTX_CLASS (code) == 'c' 288 || code == EQ || code == NE); 289@} 290@end smallexample 291 292Then the following pattern will match any RTL expression consisting 293of a commutative operator applied to two general operands: 294 295@smallexample 296(match_operator:SI 3 "commutative_operator" 297 [(match_operand:SI 1 "general_operand" "g") 298 (match_operand:SI 2 "general_operand" "g")]) 299@end smallexample 300 301Here the vector @code{[@var{operands}@dots{}]} contains two patterns 302because the expressions to be matched all contain two operands. 303 304When this pattern does match, the two operands of the commutative 305operator are recorded as operands 1 and 2 of the insn. (This is done 306by the two instances of @code{match_operand}.) Operand 3 of the insn 307will be the entire commutative expression: use @code{GET_CODE 308(operands[3])} to see which commutative operator was used. 309 310The machine mode @var{m} of @code{match_operator} works like that of 311@code{match_operand}: it is passed as the second argument to the 312predicate function, and that function is solely responsible for 313deciding whether the expression to be matched ``has'' that mode. 314 315When constructing an insn, argument 3 of the gen-function will specify 316the operation (i.e. the expression code) for the expression to be 317made. It should be an RTL expression, whose expression code is copied 318into a new expression whose operands are arguments 1 and 2 of the 319gen-function. The subexpressions of argument 3 are not used; 320only its expression code matters. 321 322When @code{match_operator} is used in a pattern for matching an insn, 323it usually best if the operand number of the @code{match_operator} 324is higher than that of the actual operands of the insn. This improves 325register allocation because the register allocator often looks at 326operands 1 and 2 of insns to see if it can do register tying. 327 328There is no way to specify constraints in @code{match_operator}. The 329operand of the insn which corresponds to the @code{match_operator} 330never has any constraints because it is never reloaded as a whole. 331However, if parts of its @var{operands} are matched by 332@code{match_operand} patterns, those parts may have constraints of 333their own. 334 335@findex match_op_dup 336@item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}]) 337Like @code{match_dup}, except that it applies to operators instead of 338operands. When constructing an insn, operand number @var{n} will be 339substituted at this point. But in matching, @code{match_op_dup} behaves 340differently. It assumes that operand number @var{n} has already been 341determined by a @code{match_operator} appearing earlier in the 342recognition template, and it matches only an identical-looking 343expression. 344 345@findex match_parallel 346@item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}]) 347This pattern is a placeholder for an insn that consists of a 348@code{parallel} expression with a variable number of elements. This 349expression should only appear at the top level of an insn pattern. 350 351When constructing an insn, operand number @var{n} will be substituted at 352this point. When matching an insn, it matches if the body of the insn 353is a @code{parallel} expression with at least as many elements as the 354vector of @var{subpat} expressions in the @code{match_parallel}, if each 355@var{subpat} matches the corresponding element of the @code{parallel}, 356@emph{and} the function @var{predicate} returns nonzero on the 357@code{parallel} that is the body of the insn. It is the responsibility 358of the predicate to validate elements of the @code{parallel} beyond 359those listed in the @code{match_parallel}.@refill 360 361A typical use of @code{match_parallel} is to match load and store 362multiple expressions, which can contain a variable number of elements 363in a @code{parallel}. For example, 364@c the following is *still* going over. need to change the code. 365@c also need to work on grouping of this example. --mew 1feb93 366 367@smallexample 368(define_insn "" 369 [(match_parallel 0 "load_multiple_operation" 370 [(set (match_operand:SI 1 "gpc_reg_operand" "=r") 371 (match_operand:SI 2 "memory_operand" "m")) 372 (use (reg:SI 179)) 373 (clobber (reg:SI 179))])] 374 "" 375 "loadm 0,0,%1,%2") 376@end smallexample 377 378This example comes from @file{a29k.md}. The function 379@code{load_multiple_operations} is defined in @file{a29k.c} and checks 380that subsequent elements in the @code{parallel} are the same as the 381@code{set} in the pattern, except that they are referencing subsequent 382registers and memory locations. 383 384An insn that matches this pattern might look like: 385 386@smallexample 387(parallel 388 [(set (reg:SI 20) (mem:SI (reg:SI 100))) 389 (use (reg:SI 179)) 390 (clobber (reg:SI 179)) 391 (set (reg:SI 21) 392 (mem:SI (plus:SI (reg:SI 100) 393 (const_int 4)))) 394 (set (reg:SI 22) 395 (mem:SI (plus:SI (reg:SI 100) 396 (const_int 8))))]) 397@end smallexample 398 399@findex match_par_dup 400@item (match_par_dup @var{n} [@var{subpat}@dots{}]) 401Like @code{match_op_dup}, but for @code{match_parallel} instead of 402@code{match_operator}. 403 404@findex match_insn 405@item (match_insn @var{predicate}) 406Match a complete insn. Unlike the other @code{match_*} recognizers, 407@code{match_insn} does not take an operand number. 408 409The machine mode @var{m} of @code{match_insn} works like that of 410@code{match_operand}: it is passed as the second argument to the 411predicate function, and that function is solely responsible for 412deciding whether the expression to be matched ``has'' that mode. 413 414@findex match_insn2 415@item (match_insn2 @var{n} @var{predicate}) 416Match a complete insn. 417 418The machine mode @var{m} of @code{match_insn2} works like that of 419@code{match_operand}: it is passed as the second argument to the 420predicate function, and that function is solely responsible for 421deciding whether the expression to be matched ``has'' that mode. 422 423@findex address 424@item (address (match_operand:@var{m} @var{n} "address_operand" "")) 425This complex of expressions is a placeholder for an operand number 426@var{n} in a ``load address'' instruction: an operand which specifies 427a memory location in the usual way, but for which the actual operand 428value used is the address of the location, not the contents of the 429location. 430 431@code{address} expressions never appear in RTL code, only in machine 432descriptions. And they are used only in machine descriptions that do 433not use the operand constraint feature. When operand constraints are 434in use, the letter @samp{p} in the constraint serves this purpose. 435 436@var{m} is the machine mode of the @emph{memory location being 437addressed}, not the machine mode of the address itself. That mode is 438always the same on a given target machine (it is @code{Pmode}, which 439normally is @code{SImode}), so there is no point in mentioning it; 440thus, no machine mode is written in the @code{address} expression. If 441some day support is added for machines in which addresses of different 442kinds of objects appear differently or are used differently (such as 443the PDP-10), different formats would perhaps need different machine 444modes and these modes might be written in the @code{address} 445expression. 446@end table 447 448@node Output Template 449@section Output Templates and Operand Substitution 450@cindex output templates 451@cindex operand substitution 452 453@cindex @samp{%} in template 454@cindex percent sign 455The @dfn{output template} is a string which specifies how to output the 456assembler code for an instruction pattern. Most of the template is a 457fixed string which is output literally. The character @samp{%} is used 458to specify where to substitute an operand; it can also be used to 459identify places where different variants of the assembler require 460different syntax. 461 462In the simplest case, a @samp{%} followed by a digit @var{n} says to output 463operand @var{n} at that point in the string. 464 465@samp{%} followed by a letter and a digit says to output an operand in an 466alternate fashion. Four letters have standard, built-in meanings described 467below. The machine description macro @code{PRINT_OPERAND} can define 468additional letters with nonstandard meanings. 469 470@samp{%c@var{digit}} can be used to substitute an operand that is a 471constant value without the syntax that normally indicates an immediate 472operand. 473 474@samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of 475the constant is negated before printing. 476 477@samp{%a@var{digit}} can be used to substitute an operand as if it were a 478memory reference, with the actual operand treated as the address. This may 479be useful when outputting a ``load address'' instruction, because often the 480assembler syntax for such an instruction requires you to write the operand 481as if it were a memory reference. 482 483@samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump 484instruction. 485 486@samp{%=} outputs a number which is unique to each instruction in the 487entire compilation. This is useful for making local labels to be 488referred to more than once in a single template that generates multiple 489assembler instructions. 490 491@samp{%} followed by a punctuation character specifies a substitution that 492does not use an operand. Only one case is standard: @samp{%%} outputs a 493@samp{%} into the assembler code. Other nonstandard cases can be 494defined in the @code{PRINT_OPERAND} macro. You must also define 495which punctuation characters are valid with the 496@code{PRINT_OPERAND_PUNCT_VALID_P} macro. 497 498@cindex \ 499@cindex backslash 500The template may generate multiple assembler instructions. Write the text 501for the instructions, with @samp{\;} between them. 502 503@cindex matching operands 504When the RTL contains two operands which are required by constraint to match 505each other, the output template must refer only to the lower-numbered operand. 506Matching operands are not always identical, and the rest of the compiler 507arranges to put the proper RTL expression for printing into the lower-numbered 508operand. 509 510One use of nonstandard letters or punctuation following @samp{%} is to 511distinguish between different assembler languages for the same machine; for 512example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax 513requires periods in most opcode names, while MIT syntax does not. For 514example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola 515syntax. The same file of patterns is used for both kinds of output syntax, 516but the character sequence @samp{%.} is used in each place where Motorola 517syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax 518defines the sequence to output a period; the macro for MIT syntax defines 519it to do nothing. 520 521@cindex @code{#} in template 522As a special case, a template consisting of the single character @code{#} 523instructs the compiler to first split the insn, and then output the 524resulting instructions separately. This helps eliminate redundancy in the 525output templates. If you have a @code{define_insn} that needs to emit 526multiple assembler instructions, and there is an matching @code{define_split} 527already defined, then you can simply use @code{#} as the output template 528instead of writing an output template that emits the multiple assembler 529instructions. 530 531If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct 532of the form @samp{@{option0|option1|option2@}} in the templates. These 533describe multiple variants of assembler language syntax. 534@xref{Instruction Output}. 535 536@node Output Statement 537@section C Statements for Assembler Output 538@cindex output statements 539@cindex C statements for assembler output 540@cindex generating assembler output 541 542Often a single fixed template string cannot produce correct and efficient 543assembler code for all the cases that are recognized by a single 544instruction pattern. For example, the opcodes may depend on the kinds of 545operands; or some unfortunate combinations of operands may require extra 546machine instructions. 547 548If the output control string starts with a @samp{@@}, then it is actually 549a series of templates, each on a separate line. (Blank lines and 550leading spaces and tabs are ignored.) The templates correspond to the 551pattern's constraint alternatives (@pxref{Multi-Alternative}). For example, 552if a target machine has a two-address add instruction @samp{addr} to add 553into a register and another @samp{addm} to add a register to memory, you 554might write this pattern: 555 556@smallexample 557(define_insn "addsi3" 558 [(set (match_operand:SI 0 "general_operand" "=r,m") 559 (plus:SI (match_operand:SI 1 "general_operand" "0,0") 560 (match_operand:SI 2 "general_operand" "g,r")))] 561 "" 562 "@@ 563 addr %2,%0 564 addm %2,%0") 565@end smallexample 566 567@cindex @code{*} in template 568@cindex asterisk in template 569If the output control string starts with a @samp{*}, then it is not an 570output template but rather a piece of C program that should compute a 571template. It should execute a @code{return} statement to return the 572template-string you want. Most such templates use C string literals, which 573require doublequote characters to delimit them. To include these 574doublequote characters in the string, prefix each one with @samp{\}. 575 576The operands may be found in the array @code{operands}, whose C data type 577is @code{rtx []}. 578 579It is very common to select different ways of generating assembler code 580based on whether an immediate operand is within a certain range. Be 581careful when doing this, because the result of @code{INTVAL} is an 582integer on the host machine. If the host machine has more bits in an 583@code{int} than the target machine has in the mode in which the constant 584will be used, then some of the bits you get from @code{INTVAL} will be 585superfluous. For proper results, you must carefully disregard the 586values of those bits. 587 588@findex output_asm_insn 589It is possible to output an assembler instruction and then go on to output 590or compute more of them, using the subroutine @code{output_asm_insn}. This 591receives two arguments: a template-string and a vector of operands. The 592vector may be @code{operands}, or it may be another array of @code{rtx} 593that you declare locally and initialize yourself. 594 595@findex which_alternative 596When an insn pattern has multiple alternatives in its constraints, often 597the appearance of the assembler code is determined mostly by which alternative 598was matched. When this is so, the C code can test the variable 599@code{which_alternative}, which is the ordinal number of the alternative 600that was actually satisfied (0 for the first, 1 for the second alternative, 601etc.). 602 603For example, suppose there are two opcodes for storing zero, @samp{clrreg} 604for registers and @samp{clrmem} for memory locations. Here is how 605a pattern could use @code{which_alternative} to choose between them: 606 607@smallexample 608(define_insn "" 609 [(set (match_operand:SI 0 "general_operand" "=r,m") 610 (const_int 0))] 611 "" 612 "* 613 return (which_alternative == 0 614 ? \"clrreg %0\" : \"clrmem %0\"); 615 ") 616@end smallexample 617 618The example above, where the assembler code to generate was 619@emph{solely} determined by the alternative, could also have been specified 620as follows, having the output control string start with a @samp{@@}: 621 622@smallexample 623@group 624(define_insn "" 625 [(set (match_operand:SI 0 "general_operand" "=r,m") 626 (const_int 0))] 627 "" 628 "@@ 629 clrreg %0 630 clrmem %0") 631@end group 632@end smallexample 633@end ifset 634 635@c Most of this node appears by itself (in a different place) even 636@c when the INTERNALS flag is clear. Passages that require the full 637@c manual's context are conditionalized to appear only in the full manual. 638@ifset INTERNALS 639@node Constraints 640@section Operand Constraints 641@cindex operand constraints 642@cindex constraints 643 644Each @code{match_operand} in an instruction pattern can specify a 645constraint for the type of operands allowed. 646@end ifset 647@ifclear INTERNALS 648@node Constraints 649@section Constraints for @code{asm} Operands 650@cindex operand constraints, @code{asm} 651@cindex constraints, @code{asm} 652@cindex @code{asm} constraints 653 654Here are specific details on what constraint letters you can use with 655@code{asm} operands. 656@end ifclear 657Constraints can say whether 658an operand may be in a register, and which kinds of register; whether the 659operand can be a memory reference, and which kinds of address; whether the 660operand may be an immediate constant, and which possible values it may 661have. Constraints can also require two operands to match. 662 663@ifset INTERNALS 664@menu 665* Simple Constraints:: Basic use of constraints. 666* Multi-Alternative:: When an insn has two alternative constraint-patterns. 667* Class Preferences:: Constraints guide which hard register to put things in. 668* Modifiers:: More precise control over effects of constraints. 669* Machine Constraints:: Existing constraints for some particular machines. 670* No Constraints:: Describing a clean machine without constraints. 671@end menu 672@end ifset 673 674@ifclear INTERNALS 675@menu 676* Simple Constraints:: Basic use of constraints. 677* Multi-Alternative:: When an insn has two alternative constraint-patterns. 678* Modifiers:: More precise control over effects of constraints. 679* Machine Constraints:: Special constraints for some particular machines. 680@end menu 681@end ifclear 682 683@node Simple Constraints 684@subsection Simple Constraints 685@cindex simple constraints 686 687The simplest kind of constraint is a string full of letters, each of 688which describes one kind of operand that is permitted. Here are 689the letters that are allowed: 690 691@table @asis 692@cindex @samp{m} in constraint 693@cindex memory references in constraints 694@item @samp{m} 695A memory operand is allowed, with any kind of address that the machine 696supports in general. 697 698@cindex offsettable address 699@cindex @samp{o} in constraint 700@item @samp{o} 701A memory operand is allowed, but only if the address is 702@dfn{offsettable}. This means that adding a small integer (actually, 703the width in bytes of the operand, as determined by its machine mode) 704may be added to the address and the result is also a valid memory 705address. 706 707@cindex autoincrement/decrement addressing 708For example, an address which is constant is offsettable; so is an 709address that is the sum of a register and a constant (as long as a 710slightly larger constant is also within the range of address-offsets 711supported by the machine); but an autoincrement or autodecrement 712address is not offsettable. More complicated indirect/indexed 713addresses may or may not be offsettable depending on the other 714addressing modes that the machine supports. 715 716Note that in an output operand which can be matched by another 717operand, the constraint letter @samp{o} is valid only when accompanied 718by both @samp{<} (if the target machine has predecrement addressing) 719and @samp{>} (if the target machine has preincrement addressing). 720 721@cindex @samp{V} in constraint 722@item @samp{V} 723A memory operand that is not offsettable. In other words, anything that 724would fit the @samp{m} constraint but not the @samp{o} constraint. 725 726@cindex @samp{<} in constraint 727@item @samp{<} 728A memory operand with autodecrement addressing (either predecrement or 729postdecrement) is allowed. 730 731@cindex @samp{>} in constraint 732@item @samp{>} 733A memory operand with autoincrement addressing (either preincrement or 734postincrement) is allowed. 735 736@cindex @samp{r} in constraint 737@cindex registers in constraints 738@item @samp{r} 739A register operand is allowed provided that it is in a general 740register. 741 742@cindex @samp{d} in constraint 743@item @samp{d}, @samp{a}, @samp{f}, @dots{} 744Other letters can be defined in machine-dependent fashion to stand for 745particular classes of registers. @samp{d}, @samp{a} and @samp{f} are 746defined on the 68000/68020 to stand for data, address and floating 747point registers. 748 749@cindex constants in constraints 750@cindex @samp{i} in constraint 751@item @samp{i} 752An immediate integer operand (one with constant value) is allowed. 753This includes symbolic constants whose values will be known only at 754assembly time. 755 756@cindex @samp{n} in constraint 757@item @samp{n} 758An immediate integer operand with a known numeric value is allowed. 759Many systems cannot support assembly-time constants for operands less 760than a word wide. Constraints for these operands should use @samp{n} 761rather than @samp{i}. 762 763@cindex @samp{I} in constraint 764@item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P} 765Other letters in the range @samp{I} through @samp{P} may be defined in 766a machine-dependent fashion to permit immediate integer operands with 767explicit integer values in specified ranges. For example, on the 76868000, @samp{I} is defined to stand for the range of values 1 to 8. 769This is the range permitted as a shift count in the shift 770instructions. 771 772@cindex @samp{E} in constraint 773@item @samp{E} 774An immediate floating operand (expression code @code{const_double}) is 775allowed, but only if the target floating point format is the same as 776that of the host machine (on which the compiler is running). 777 778@cindex @samp{F} in constraint 779@item @samp{F} 780An immediate floating operand (expression code @code{const_double}) is 781allowed. 782 783@cindex @samp{G} in constraint 784@cindex @samp{H} in constraint 785@item @samp{G}, @samp{H} 786@samp{G} and @samp{H} may be defined in a machine-dependent fashion to 787permit immediate floating operands in particular ranges of values. 788 789@cindex @samp{s} in constraint 790@item @samp{s} 791An immediate integer operand whose value is not an explicit integer is 792allowed. 793 794This might appear strange; if an insn allows a constant operand with a 795value not known at compile time, it certainly must allow any known 796value. So why use @samp{s} instead of @samp{i}? Sometimes it allows 797better code to be generated. 798 799For example, on the 68000 in a fullword instruction it is possible to 800use an immediate operand; but if the immediate value is between -128 801and 127, better code results from loading the value into a register and 802using the register. This is because the load into the register can be 803done with a @samp{moveq} instruction. We arrange for this to happen 804by defining the letter @samp{K} to mean ``any integer outside the 805range -128 to 127'', and then specifying @samp{Ks} in the operand 806constraints. 807 808@cindex @samp{g} in constraint 809@item @samp{g} 810Any register, memory or immediate integer operand is allowed, except for 811registers that are not general registers. 812 813@cindex @samp{X} in constraint 814@item @samp{X} 815@ifset INTERNALS 816Any operand whatsoever is allowed, even if it does not satisfy 817@code{general_operand}. This is normally used in the constraint of 818a @code{match_scratch} when certain alternatives will not actually 819require a scratch register. 820@end ifset 821@ifclear INTERNALS 822Any operand whatsoever is allowed. 823@end ifclear 824 825@cindex @samp{0} in constraint 826@cindex digits in constraint 827@item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{9} 828An operand that matches the specified operand number is allowed. If a 829digit is used together with letters within the same alternative, the 830digit should come last. 831 832@cindex matching constraint 833@cindex constraint, matching 834This is called a @dfn{matching constraint} and what it really means is 835that the assembler has only a single operand that fills two roles 836@ifset INTERNALS 837considered separate in the RTL insn. For example, an add insn has two 838input operands and one output operand in the RTL, but on most CISC 839@end ifset 840@ifclear INTERNALS 841which @code{asm} distinguishes. For example, an add instruction uses 842two input operands and an output operand, but on most CISC 843@end ifclear 844machines an add instruction really has only two operands, one of them an 845input-output operand: 846 847@smallexample 848addl #35,r12 849@end smallexample 850 851Matching constraints are used in these circumstances. 852More precisely, the two operands that match must include one input-only 853operand and one output-only operand. Moreover, the digit must be a 854smaller number than the number of the operand that uses it in the 855constraint. 856 857@ifset INTERNALS 858For operands to match in a particular case usually means that they 859are identical-looking RTL expressions. But in a few special cases 860specific kinds of dissimilarity are allowed. For example, @code{*x} 861as an input operand will match @code{*x++} as an output operand. 862For proper results in such cases, the output template should always 863use the output-operand's number when printing the operand. 864@end ifset 865 866@cindex load address instruction 867@cindex push address instruction 868@cindex address constraints 869@cindex @samp{p} in constraint 870@item @samp{p} 871An operand that is a valid memory address is allowed. This is 872for ``load address'' and ``push address'' instructions. 873 874@findex address_operand 875@samp{p} in the constraint must be accompanied by @code{address_operand} 876as the predicate in the @code{match_operand}. This predicate interprets 877the mode specified in the @code{match_operand} as the mode of the memory 878reference for which the address would be valid. 879 880@cindex extensible constraints 881@cindex @samp{Q}, in constraint 882@item @samp{Q}, @samp{R}, @samp{S}, @dots{} @samp{U} 883Letters in the range @samp{Q} through @samp{U} may be defined in a 884machine-dependent fashion to stand for arbitrary operand types. 885@ifset INTERNALS 886The machine description macro @code{EXTRA_CONSTRAINT} is passed the 887operand as its first argument and the constraint letter as its 888second operand. 889 890A typical use for this would be to distinguish certain types of 891memory references that affect other insn operands. 892 893Do not define these constraint letters to accept register references 894(@code{reg}); the reload pass does not expect this and would not handle 895it properly. 896@end ifset 897@end table 898 899@ifset INTERNALS 900In order to have valid assembler code, each operand must satisfy 901its constraint. But a failure to do so does not prevent the pattern 902from applying to an insn. Instead, it directs the compiler to modify 903the code so that the constraint will be satisfied. Usually this is 904done by copying an operand into a register. 905 906Contrast, therefore, the two instruction patterns that follow: 907 908@smallexample 909(define_insn "" 910 [(set (match_operand:SI 0 "general_operand" "=r") 911 (plus:SI (match_dup 0) 912 (match_operand:SI 1 "general_operand" "r")))] 913 "" 914 "@dots{}") 915@end smallexample 916 917@noindent 918which has two operands, one of which must appear in two places, and 919 920@smallexample 921(define_insn "" 922 [(set (match_operand:SI 0 "general_operand" "=r") 923 (plus:SI (match_operand:SI 1 "general_operand" "0") 924 (match_operand:SI 2 "general_operand" "r")))] 925 "" 926 "@dots{}") 927@end smallexample 928 929@noindent 930which has three operands, two of which are required by a constraint to be 931identical. If we are considering an insn of the form 932 933@smallexample 934(insn @var{n} @var{prev} @var{next} 935 (set (reg:SI 3) 936 (plus:SI (reg:SI 6) (reg:SI 109))) 937 @dots{}) 938@end smallexample 939 940@noindent 941the first pattern would not apply at all, because this insn does not 942contain two identical subexpressions in the right place. The pattern would 943say, ``That does not look like an add instruction; try other patterns.'' 944The second pattern would say, ``Yes, that's an add instruction, but there 945is something wrong with it.'' It would direct the reload pass of the 946compiler to generate additional insns to make the constraint true. The 947results might look like this: 948 949@smallexample 950(insn @var{n2} @var{prev} @var{n} 951 (set (reg:SI 3) (reg:SI 6)) 952 @dots{}) 953 954(insn @var{n} @var{n2} @var{next} 955 (set (reg:SI 3) 956 (plus:SI (reg:SI 3) (reg:SI 109))) 957 @dots{}) 958@end smallexample 959 960It is up to you to make sure that each operand, in each pattern, has 961constraints that can handle any RTL expression that could be present for 962that operand. (When multiple alternatives are in use, each pattern must, 963for each possible combination of operand expressions, have at least one 964alternative which can handle that combination of operands.) The 965constraints don't need to @emph{allow} any possible operand---when this is 966the case, they do not constrain---but they must at least point the way to 967reloading any possible operand so that it will fit. 968 969@itemize @bullet 970@item 971If the constraint accepts whatever operands the predicate permits, 972there is no problem: reloading is never necessary for this operand. 973 974For example, an operand whose constraints permit everything except 975registers is safe provided its predicate rejects registers. 976 977An operand whose predicate accepts only constant values is safe 978provided its constraints include the letter @samp{i}. If any possible 979constant value is accepted, then nothing less than @samp{i} will do; 980if the predicate is more selective, then the constraints may also be 981more selective. 982 983@item 984Any operand expression can be reloaded by copying it into a register. 985So if an operand's constraints allow some kind of register, it is 986certain to be safe. It need not permit all classes of registers; the 987compiler knows how to copy a register into another register of the 988proper class in order to make an instruction valid. 989 990@cindex nonoffsettable memory reference 991@cindex memory reference, nonoffsettable 992@item 993A nonoffsettable memory reference can be reloaded by copying the 994address into a register. So if the constraint uses the letter 995@samp{o}, all memory references are taken care of. 996 997@item 998A constant operand can be reloaded by allocating space in memory to 999hold it as preinitialized data. Then the memory reference can be used 1000in place of the constant. So if the constraint uses the letters 1001@samp{o} or @samp{m}, constant operands are not a problem. 1002 1003@item 1004If the constraint permits a constant and a pseudo register used in an insn 1005was not allocated to a hard register and is equivalent to a constant, 1006the register will be replaced with the constant. If the predicate does 1007not permit a constant and the insn is re-recognized for some reason, the 1008compiler will crash. Thus the predicate must always recognize any 1009objects allowed by the constraint. 1010@end itemize 1011 1012If the operand's predicate can recognize registers, but the constraint does 1013not permit them, it can make the compiler crash. When this operand happens 1014to be a register, the reload pass will be stymied, because it does not know 1015how to copy a register temporarily into memory. 1016 1017If the predicate accepts a unary operator, the constraint applies to the 1018operand. For example, the MIPS processor at ISA level 3 supports an 1019instruction which adds two registers in @code{SImode} to produce a 1020@code{DImode} result, but only if the registers are correctly sign 1021extended. This predicate for the input operands accepts a 1022@code{sign_extend} of an @code{SImode} register. Write the constraint 1023to indicate the type of register that is required for the operand of the 1024@code{sign_extend}. 1025@end ifset 1026 1027@node Multi-Alternative 1028@subsection Multiple Alternative Constraints 1029@cindex multiple alternative constraints 1030 1031Sometimes a single instruction has multiple alternative sets of possible 1032operands. For example, on the 68000, a logical-or instruction can combine 1033register or an immediate value into memory, or it can combine any kind of 1034operand into a register; but it cannot combine one memory location into 1035another. 1036 1037These constraints are represented as multiple alternatives. An alternative 1038can be described by a series of letters for each operand. The overall 1039constraint for an operand is made from the letters for this operand 1040from the first alternative, a comma, the letters for this operand from 1041the second alternative, a comma, and so on until the last alternative. 1042@ifset INTERNALS 1043Here is how it is done for fullword logical-or on the 68000: 1044 1045@smallexample 1046(define_insn "iorsi3" 1047 [(set (match_operand:SI 0 "general_operand" "=m,d") 1048 (ior:SI (match_operand:SI 1 "general_operand" "%0,0") 1049 (match_operand:SI 2 "general_operand" "dKs,dmKs")))] 1050 @dots{}) 1051@end smallexample 1052 1053The first alternative has @samp{m} (memory) for operand 0, @samp{0} for 1054operand 1 (meaning it must match operand 0), and @samp{dKs} for operand 10552. The second alternative has @samp{d} (data register) for operand 0, 1056@samp{0} for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and 1057@samp{%} in the constraints apply to all the alternatives; their 1058meaning is explained in the next section (@pxref{Class Preferences}). 1059@end ifset 1060 1061@c FIXME Is this ? and ! stuff of use in asm()? If not, hide unless INTERNAL 1062If all the operands fit any one alternative, the instruction is valid. 1063Otherwise, for each alternative, the compiler counts how many instructions 1064must be added to copy the operands so that that alternative applies. 1065The alternative requiring the least copying is chosen. If two alternatives 1066need the same amount of copying, the one that comes first is chosen. 1067These choices can be altered with the @samp{?} and @samp{!} characters: 1068 1069@table @code 1070@cindex @samp{?} in constraint 1071@cindex question mark 1072@item ? 1073Disparage slightly the alternative that the @samp{?} appears in, 1074as a choice when no alternative applies exactly. The compiler regards 1075this alternative as one unit more costly for each @samp{?} that appears 1076in it. 1077 1078@cindex @samp{!} in constraint 1079@cindex exclamation point 1080@item ! 1081Disparage severely the alternative that the @samp{!} appears in. 1082This alternative can still be used if it fits without reloading, 1083but if reloading is needed, some other alternative will be used. 1084@end table 1085 1086@ifset INTERNALS 1087When an insn pattern has multiple alternatives in its constraints, often 1088the appearance of the assembler code is determined mostly by which 1089alternative was matched. When this is so, the C code for writing the 1090assembler code can use the variable @code{which_alternative}, which is 1091the ordinal number of the alternative that was actually satisfied (0 for 1092the first, 1 for the second alternative, etc.). @xref{Output Statement}. 1093@end ifset 1094 1095@ifset INTERNALS 1096@node Class Preferences 1097@subsection Register Class Preferences 1098@cindex class preference constraints 1099@cindex register class preference constraints 1100 1101@cindex voting between constraint alternatives 1102The operand constraints have another function: they enable the compiler 1103to decide which kind of hardware register a pseudo register is best 1104allocated to. The compiler examines the constraints that apply to the 1105insns that use the pseudo register, looking for the machine-dependent 1106letters such as @samp{d} and @samp{a} that specify classes of registers. 1107The pseudo register is put in whichever class gets the most ``votes''. 1108The constraint letters @samp{g} and @samp{r} also vote: they vote in 1109favor of a general register. The machine description says which registers 1110are considered general. 1111 1112Of course, on some machines all registers are equivalent, and no register 1113classes are defined. Then none of this complexity is relevant. 1114@end ifset 1115 1116@node Modifiers 1117@subsection Constraint Modifier Characters 1118@cindex modifiers in constraints 1119@cindex constraint modifier characters 1120 1121@c prevent bad page break with this line 1122Here are constraint modifier characters. 1123 1124@table @samp 1125@cindex @samp{=} in constraint 1126@item = 1127Means that this operand is write-only for this instruction: the previous 1128value is discarded and replaced by output data. 1129 1130@cindex @samp{+} in constraint 1131@item + 1132Means that this operand is both read and written by the instruction. 1133 1134When the compiler fixes up the operands to satisfy the constraints, 1135it needs to know which operands are inputs to the instruction and 1136which are outputs from it. @samp{=} identifies an output; @samp{+} 1137identifies an operand that is both input and output; all other operands 1138are assumed to be input only. 1139 1140@cindex @samp{&} in constraint 1141@cindex earlyclobber operand 1142@item & 1143Means (in a particular alternative) that this operand is an 1144@dfn{earlyclobber} operand, which is modified before the instruction is 1145finished using the input operands. Therefore, this operand may not lie 1146in a register that is used as an input operand or as part of any memory 1147address. 1148 1149@samp{&} applies only to the alternative in which it is written. In 1150constraints with multiple alternatives, sometimes one alternative 1151requires @samp{&} while others do not. See, for example, the 1152@samp{movdf} insn of the 68000. 1153 1154An input operand can be tied to an earlyclobber operand if its only 1155use as an input occurs before the early result is written. Adding 1156alternatives of this form often allows GCC to produce better code 1157when only some of the inputs can be affected by the earlyclobber. 1158See, for example, the @samp{mulsi3} insn of the ARM. 1159 1160@samp{&} does not obviate the need to write @samp{=}. 1161 1162@cindex @samp{%} in constraint 1163@item % 1164Declares the instruction to be commutative for this operand and the 1165following operand. This means that the compiler may interchange the 1166two operands if that is the cheapest way to make all operands fit the 1167constraints. 1168@ifset INTERNALS 1169This is often used in patterns for addition instructions 1170that really have only two operands: the result must go in one of the 1171arguments. Here for example, is how the 68000 halfword-add 1172instruction is defined: 1173 1174@smallexample 1175(define_insn "addhi3" 1176 [(set (match_operand:HI 0 "general_operand" "=m,r") 1177 (plus:HI (match_operand:HI 1 "general_operand" "%0,0") 1178 (match_operand:HI 2 "general_operand" "di,g")))] 1179 @dots{}) 1180@end smallexample 1181@end ifset 1182 1183@cindex @samp{#} in constraint 1184@item # 1185Says that all following characters, up to the next comma, are to be 1186ignored as a constraint. They are significant only for choosing 1187register preferences. 1188 1189@ifset INTERNALS 1190@cindex @samp{*} in constraint 1191@item * 1192Says that the following character should be ignored when choosing 1193register preferences. @samp{*} has no effect on the meaning of the 1194constraint as a constraint, and no effect on reloading. 1195 1196Here is an example: the 68000 has an instruction to sign-extend a 1197halfword in a data register, and can also sign-extend a value by 1198copying it into an address register. While either kind of register is 1199acceptable, the constraints on an address-register destination are 1200less strict, so it is best if register allocation makes an address 1201register its goal. Therefore, @samp{*} is used so that the @samp{d} 1202constraint letter (for data register) is ignored when computing 1203register preferences. 1204 1205@smallexample 1206(define_insn "extendhisi2" 1207 [(set (match_operand:SI 0 "general_operand" "=*d,a") 1208 (sign_extend:SI 1209 (match_operand:HI 1 "general_operand" "0,g")))] 1210 @dots{}) 1211@end smallexample 1212@end ifset 1213@end table 1214 1215@node Machine Constraints 1216@subsection Constraints for Particular Machines 1217@cindex machine specific constraints 1218@cindex constraints, machine specific 1219 1220Whenever possible, you should use the general-purpose constraint letters 1221in @code{asm} arguments, since they will convey meaning more readily to 1222people reading your code. Failing that, use the constraint letters 1223that usually have very similar meanings across architectures. The most 1224commonly used constraints are @samp{m} and @samp{r} (for memory and 1225general-purpose registers respectively; @pxref{Simple Constraints}), and 1226@samp{I}, usually the letter indicating the most common 1227immediate-constant format. 1228 1229For each machine architecture, the @file{config/@var{machine}.h} file 1230defines additional constraints. These constraints are used by the 1231compiler itself for instruction generation, as well as for @code{asm} 1232statements; therefore, some of the constraints are not particularly 1233interesting for @code{asm}. The constraints are defined through these 1234macros: 1235 1236@table @code 1237@item REG_CLASS_FROM_LETTER 1238Register class constraints (usually lower case). 1239 1240@item CONST_OK_FOR_LETTER_P 1241Immediate constant constraints, for non-floating point constants of 1242word size or smaller precision (usually upper case). 1243 1244@item CONST_DOUBLE_OK_FOR_LETTER_P 1245Immediate constant constraints, for all floating point constants and for 1246constants of greater than word size precision (usually upper case). 1247 1248@item EXTRA_CONSTRAINT 1249Special cases of registers or memory. This macro is not required, and 1250is only defined for some machines. 1251@end table 1252 1253Inspecting these macro definitions in the compiler source for your 1254machine is the best way to be certain you have the right constraints. 1255However, here is a summary of the machine-dependent constraints 1256available on some particular machines. 1257 1258@table @emph 1259@item ARM family---@file{arm.h} 1260@table @code 1261@item f 1262Floating-point register 1263 1264@item F 1265One of the floating-point constants 0.0, 0.5, 1.0, 2.0, 3.0, 4.0, 5.0 1266or 10.0 1267 1268@item G 1269Floating-point constant that would satisfy the constraint @samp{F} if it 1270were negated 1271 1272@item I 1273Integer that is valid as an immediate operand in a data processing 1274instruction. That is, an integer in the range 0 to 255 rotated by a 1275multiple of 2 1276 1277@item J 1278Integer in the range -4095 to 4095 1279 1280@item K 1281Integer that satisfies constraint @samp{I} when inverted (ones complement) 1282 1283@item L 1284Integer that satisfies constraint @samp{I} when negated (twos complement) 1285 1286@item M 1287Integer in the range 0 to 32 1288 1289@item Q 1290A memory reference where the exact address is in a single register 1291(`@samp{m}' is preferable for @code{asm} statements) 1292 1293@item R 1294An item in the constant pool 1295 1296@item S 1297A symbol in the text segment of the current file 1298@end table 1299 1300@item AMD 29000 family---@file{a29k.h} 1301@table @code 1302@item l 1303Local register 0 1304 1305@item b 1306Byte Pointer (@samp{BP}) register 1307 1308@item q 1309@samp{Q} register 1310 1311@item h 1312Special purpose register 1313 1314@item A 1315First accumulator register 1316 1317@item a 1318Other accumulator register 1319 1320@item f 1321Floating point register 1322 1323@item I 1324Constant greater than 0, less than 0x100 1325 1326@item J 1327Constant greater than 0, less than 0x10000 1328 1329@item K 1330Constant whose high 24 bits are on (1) 1331 1332@item L 133316 bit constant whose high 8 bits are on (1) 1334 1335@item M 133632 bit constant whose high 16 bits are on (1) 1337 1338@item N 133932 bit negative constant that fits in 8 bits 1340 1341@item O 1342The constant 0x80000000 or, on the 29050, any 32 bit constant 1343whose low 16 bits are 0. 1344 1345@item P 134616 bit negative constant that fits in 8 bits 1347 1348@item G 1349@itemx H 1350A floating point constant (in @code{asm} statements, use the machine 1351independent @samp{E} or @samp{F} instead) 1352@end table 1353 1354@item IBM RS6000---@file{rs6000.h} 1355@table @code 1356@item b 1357Address base register 1358 1359@item f 1360Floating point register 1361 1362@item h 1363@samp{MQ}, @samp{CTR}, or @samp{LINK} register 1364 1365@item q 1366@samp{MQ} register 1367 1368@item c 1369@samp{CTR} register 1370 1371@item l 1372@samp{LINK} register 1373 1374@item x 1375@samp{CR} register (condition register) number 0 1376 1377@item y 1378@samp{CR} register (condition register) 1379 1380@item z 1381@samp{FPMEM} stack memory for FPR-GPR transfers 1382 1383@item I 1384Signed 16 bit constant 1385 1386@item J 1387Constant whose low 16 bits are 0 1388 1389@item K 1390Constant whose high 16 bits are 0 1391 1392@item L 1393Constant suitable as a mask operand 1394 1395@item M 1396Constant larger than 31 1397 1398@item N 1399Exact power of 2 1400 1401@item O 1402Zero 1403 1404@item P 1405Constant whose negation is a signed 16 bit constant 1406 1407@item G 1408Floating point constant that can be loaded into a register with one 1409instruction per word 1410 1411@item Q 1412Memory operand that is an offset from a register (@samp{m} is preferable 1413for @code{asm} statements) 1414 1415@item R 1416AIX TOC entry 1417 1418@item S 1419Constant suitable as a 64-bit mask operand 1420 1421@item U 1422System V Release 4 small data area reference 1423@end table 1424 1425@item Intel 386---@file{i386.h} 1426@table @code 1427@item q 1428@samp{a}, @code{b}, @code{c}, or @code{d} register 1429 1430@item A 1431@samp{a}, or @code{d} register (for 64-bit ints) 1432 1433@item f 1434Floating point register 1435 1436@item t 1437First (top of stack) floating point register 1438 1439@item u 1440Second floating point register 1441 1442@item a 1443@samp{a} register 1444 1445@item b 1446@samp{b} register 1447 1448@item c 1449@samp{c} register 1450 1451@item d 1452@samp{d} register 1453 1454@item D 1455@samp{di} register 1456 1457@item S 1458@samp{si} register 1459 1460@item I 1461Constant in range 0 to 31 (for 32 bit shifts) 1462 1463@item J 1464Constant in range 0 to 63 (for 64 bit shifts) 1465 1466@item K 1467@samp{0xff} 1468 1469@item L 1470@samp{0xffff} 1471 1472@item M 14730, 1, 2, or 3 (shifts for @code{lea} instruction) 1474 1475@item N 1476Constant in range 0 to 255 (for @code{out} instruction) 1477 1478@item G 1479Standard 80387 floating point constant 1480@end table 1481 1482@item Intel 960---@file{i960.h} 1483@table @code 1484@item f 1485Floating point register (@code{fp0} to @code{fp3}) 1486 1487@item l 1488Local register (@code{r0} to @code{r15}) 1489 1490@item b 1491Global register (@code{g0} to @code{g15}) 1492 1493@item d 1494Any local or global register 1495 1496@item I 1497Integers from 0 to 31 1498 1499@item J 15000 1501 1502@item K 1503Integers from -31 to 0 1504 1505@item G 1506Floating point 0 1507 1508@item H 1509Floating point 1 1510@end table 1511 1512@item MIPS---@file{mips.h} 1513@table @code 1514@item d 1515General-purpose integer register 1516 1517@item f 1518Floating-point register (if available) 1519 1520@item h 1521@samp{Hi} register 1522 1523@item l 1524@samp{Lo} register 1525 1526@item x 1527@samp{Hi} or @samp{Lo} register 1528 1529@item y 1530General-purpose integer register 1531 1532@item z 1533Floating-point status register 1534 1535@item I 1536Signed 16 bit constant (for arithmetic instructions) 1537 1538@item J 1539Zero 1540 1541@item K 1542Zero-extended 16-bit constant (for logic instructions) 1543 1544@item L 1545Constant with low 16 bits zero (can be loaded with @code{lui}) 1546 1547@item M 154832 bit constant which requires two instructions to load (a constant 1549which is not @samp{I}, @samp{K}, or @samp{L}) 1550 1551@item N 1552Negative 16 bit constant 1553 1554@item O 1555Exact power of two 1556 1557@item P 1558Positive 16 bit constant 1559 1560@item G 1561Floating point zero 1562 1563@item Q 1564Memory reference that can be loaded with more than one instruction 1565(@samp{m} is preferable for @code{asm} statements) 1566 1567@item R 1568Memory reference that can be loaded with one instruction 1569(@samp{m} is preferable for @code{asm} statements) 1570 1571@item S 1572Memory reference in external OSF/rose PIC format 1573(@samp{m} is preferable for @code{asm} statements) 1574@end table 1575 1576@item Motorola 680x0---@file{m68k.h} 1577@table @code 1578@item a 1579Address register 1580 1581@item d 1582Data register 1583 1584@item f 158568881 floating-point register, if available 1586 1587@item x 1588Sun FPA (floating-point) register, if available 1589 1590@item y 1591First 16 Sun FPA registers, if available 1592 1593@item I 1594Integer in the range 1 to 8 1595 1596@item J 159716 bit signed number 1598 1599@item K 1600Signed number whose magnitude is greater than 0x80 1601 1602@item L 1603Integer in the range -8 to -1 1604 1605@item M 1606Signed number whose magnitude is greater than 0x100 1607 1608@item G 1609Floating point constant that is not a 68881 constant 1610 1611@item H 1612Floating point constant that can be used by Sun FPA 1613@end table 1614 1615@need 1000 1616@item SPARC---@file{sparc.h} 1617@table @code 1618@item f 1619Floating-point register that can hold 32 or 64 bit values. 1620 1621@item e 1622Floating-point register that can hold 64 or 128 bit values. 1623 1624@item I 1625Signed 13 bit constant 1626 1627@item J 1628Zero 1629 1630@item K 163132 bit constant with the low 12 bits clear (a constant that can be 1632loaded with the @code{sethi} instruction) 1633 1634@item G 1635Floating-point zero 1636 1637@item H 1638Signed 13 bit constant, sign-extended to 32 or 64 bits 1639 1640@item Q 1641Memory reference that can be loaded with one instruction (@samp{m} is 1642more appropriate for @code{asm} statements) 1643 1644@item S 1645Constant, or memory address 1646 1647@item T 1648Memory address aligned to an 8-byte boundary 1649 1650@item U 1651Even register 1652@end table 1653@end table 1654 1655@ifset INTERNALS 1656@node No Constraints 1657@subsection Not Using Constraints 1658@cindex no constraints 1659@cindex not using constraints 1660 1661Some machines are so clean that operand constraints are not required. For 1662example, on the Vax, an operand valid in one context is valid in any other 1663context. On such a machine, every operand constraint would be @samp{g}, 1664excepting only operands of ``load address'' instructions which are 1665written as if they referred to a memory location's contents but actual 1666refer to its address. They would have constraint @samp{p}. 1667 1668@cindex empty constraints 1669For such machines, instead of writing @samp{g} and @samp{p} for all 1670the constraints, you can choose to write a description with empty constraints. 1671Then you write @samp{""} for the constraint in every @code{match_operand}. 1672Address operands are identified by writing an @code{address} expression 1673around the @code{match_operand}, not by their constraints. 1674 1675When the machine description has just empty constraints, certain parts 1676of compilation are skipped, making the compiler faster. However, 1677few machines actually do not need constraints; all machine descriptions 1678now in existence use constraints. 1679@end ifset 1680 1681@ifset INTERNALS 1682@node Standard Names 1683@section Standard Pattern Names For Generation 1684@cindex standard pattern names 1685@cindex pattern names 1686@cindex names, pattern 1687 1688Here is a table of the instruction names that are meaningful in the RTL 1689generation pass of the compiler. Giving one of these names to an 1690instruction pattern tells the RTL generation pass that it can use the 1691pattern to accomplish a certain task. 1692 1693@table @asis 1694@cindex @code{mov@var{m}} instruction pattern 1695@item @samp{mov@var{m}} 1696Here @var{m} stands for a two-letter machine mode name, in lower case. 1697This instruction pattern moves data with that machine mode from operand 16981 to operand 0. For example, @samp{movsi} moves full-word data. 1699 1700If operand 0 is a @code{subreg} with mode @var{m} of a register whose 1701own mode is wider than @var{m}, the effect of this instruction is 1702to store the specified value in the part of the register that corresponds 1703to mode @var{m}. The effect on the rest of the register is undefined. 1704 1705This class of patterns is special in several ways. First of all, each 1706of these names @emph{must} be defined, because there is no other way 1707to copy a datum from one place to another. 1708 1709Second, these patterns are not used solely in the RTL generation pass. 1710Even the reload pass can generate move insns to copy values from stack 1711slots into temporary registers. When it does so, one of the operands is 1712a hard register and the other is an operand that can need to be reloaded 1713into a register. 1714 1715@findex force_reg 1716Therefore, when given such a pair of operands, the pattern must generate 1717RTL which needs no reloading and needs no temporary registers---no 1718registers other than the operands. For example, if you support the 1719pattern with a @code{define_expand}, then in such a case the 1720@code{define_expand} mustn't call @code{force_reg} or any other such 1721function which might generate new pseudo registers. 1722 1723This requirement exists even for subword modes on a RISC machine where 1724fetching those modes from memory normally requires several insns and 1725some temporary registers. Look in @file{spur.md} to see how the 1726requirement can be satisfied. 1727 1728@findex change_address 1729During reload a memory reference with an invalid address may be passed 1730as an operand. Such an address will be replaced with a valid address 1731later in the reload pass. In this case, nothing may be done with the 1732address except to use it as it stands. If it is copied, it will not be 1733replaced with a valid address. No attempt should be made to make such 1734an address into a valid address and no routine (such as 1735@code{change_address}) that will do so may be called. Note that 1736@code{general_operand} will fail when applied to such an address. 1737 1738@findex reload_in_progress 1739The global variable @code{reload_in_progress} (which must be explicitly 1740declared if required) can be used to determine whether such special 1741handling is required. 1742 1743The variety of operands that have reloads depends on the rest of the 1744machine description, but typically on a RISC machine these can only be 1745pseudo registers that did not get hard registers, while on other 1746machines explicit memory references will get optional reloads. 1747 1748If a scratch register is required to move an object to or from memory, 1749it can be allocated using @code{gen_reg_rtx} prior to life analysis. 1750 1751If there are cases needing 1752scratch registers after reload, you must define 1753@code{SECONDARY_INPUT_RELOAD_CLASS} and perhaps also 1754@code{SECONDARY_OUTPUT_RELOAD_CLASS} to detect them, and provide 1755patterns @samp{reload_in@var{m}} or @samp{reload_out@var{m}} to handle 1756them. @xref{Register Classes}. 1757 1758@findex no_new_pseudos 1759The global variable @code{no_new_pseudos} can be used to determine if it 1760is unsafe to create new pseudo registers. If this variable is nonzero, then 1761it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo. 1762 1763The constraints on a @samp{mov@var{m}} must permit moving any hard 1764register to any other hard register provided that 1765@code{HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and 1766@code{REGISTER_MOVE_COST} applied to their classes returns a value of 2. 1767 1768It is obligatory to support floating point @samp{mov@var{m}} 1769instructions into and out of any registers that can hold fixed point 1770values, because unions and structures (which have modes @code{SImode} or 1771@code{DImode}) can be in those registers and they may have floating 1772point members. 1773 1774There may also be a need to support fixed point @samp{mov@var{m}} 1775instructions in and out of floating point registers. Unfortunately, I 1776have forgotten why this was so, and I don't know whether it is still 1777true. If @code{HARD_REGNO_MODE_OK} rejects fixed point values in 1778floating point registers, then the constraints of the fixed point 1779@samp{mov@var{m}} instructions must be designed to avoid ever trying to 1780reload into a floating point register. 1781 1782@cindex @code{reload_in} instruction pattern 1783@cindex @code{reload_out} instruction pattern 1784@item @samp{reload_in@var{m}} 1785@itemx @samp{reload_out@var{m}} 1786Like @samp{mov@var{m}}, but used when a scratch register is required to 1787move between operand 0 and operand 1. Operand 2 describes the scratch 1788register. See the discussion of the @code{SECONDARY_RELOAD_CLASS} 1789macro in @pxref{Register Classes}. 1790 1791@cindex @code{movstrict@var{m}} instruction pattern 1792@item @samp{movstrict@var{m}} 1793Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg} 1794with mode @var{m} of a register whose natural mode is wider, 1795the @samp{movstrict@var{m}} instruction is guaranteed not to alter 1796any of the register except the part which belongs to mode @var{m}. 1797 1798@cindex @code{load_multiple} instruction pattern 1799@item @samp{load_multiple} 1800Load several consecutive memory locations into consecutive registers. 1801Operand 0 is the first of the consecutive registers, operand 1 1802is the first memory location, and operand 2 is a constant: the 1803number of consecutive registers. 1804 1805Define this only if the target machine really has such an instruction; 1806do not define this if the most efficient way of loading consecutive 1807registers from memory is to do them one at a time. 1808 1809On some machines, there are restrictions as to which consecutive 1810registers can be stored into memory, such as particular starting or 1811ending register numbers or only a range of valid counts. For those 1812machines, use a @code{define_expand} (@pxref{Expander Definitions}) 1813and make the pattern fail if the restrictions are not met. 1814 1815Write the generated insn as a @code{parallel} with elements being a 1816@code{set} of one register from the appropriate memory location (you may 1817also need @code{use} or @code{clobber} elements). Use a 1818@code{match_parallel} (@pxref{RTL Template}) to recognize the insn. See 1819@file{a29k.md} and @file{rs6000.md} for examples of the use of this insn 1820pattern. 1821 1822@cindex @samp{store_multiple} instruction pattern 1823@item @samp{store_multiple} 1824Similar to @samp{load_multiple}, but store several consecutive registers 1825into consecutive memory locations. Operand 0 is the first of the 1826consecutive memory locations, operand 1 is the first register, and 1827operand 2 is a constant: the number of consecutive registers. 1828 1829@cindex @code{add@var{m}3} instruction pattern 1830@item @samp{add@var{m}3} 1831Add operand 2 and operand 1, storing the result in operand 0. All operands 1832must have mode @var{m}. This can be used even on two-address machines, by 1833means of constraints requiring operands 1 and 0 to be the same location. 1834 1835@cindex @code{sub@var{m}3} instruction pattern 1836@cindex @code{mul@var{m}3} instruction pattern 1837@cindex @code{div@var{m}3} instruction pattern 1838@cindex @code{udiv@var{m}3} instruction pattern 1839@cindex @code{mod@var{m}3} instruction pattern 1840@cindex @code{umod@var{m}3} instruction pattern 1841@cindex @code{smin@var{m}3} instruction pattern 1842@cindex @code{smax@var{m}3} instruction pattern 1843@cindex @code{umin@var{m}3} instruction pattern 1844@cindex @code{umax@var{m}3} instruction pattern 1845@cindex @code{and@var{m}3} instruction pattern 1846@cindex @code{ior@var{m}3} instruction pattern 1847@cindex @code{xor@var{m}3} instruction pattern 1848@item @samp{sub@var{m}3}, @samp{mul@var{m}3} 1849@itemx @samp{div@var{m}3}, @samp{udiv@var{m}3}, @samp{mod@var{m}3}, @samp{umod@var{m}3} 1850@itemx @samp{smin@var{m}3}, @samp{smax@var{m}3}, @samp{umin@var{m}3}, @samp{umax@var{m}3} 1851@itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3} 1852Similar, for other arithmetic operations. 1853 1854@cindex @code{mulhisi3} instruction pattern 1855@item @samp{mulhisi3} 1856Multiply operands 1 and 2, which have mode @code{HImode}, and store 1857a @code{SImode} product in operand 0. 1858 1859@cindex @code{mulqihi3} instruction pattern 1860@cindex @code{mulsidi3} instruction pattern 1861@item @samp{mulqihi3}, @samp{mulsidi3} 1862Similar widening-multiplication instructions of other widths. 1863 1864@cindex @code{umulqihi3} instruction pattern 1865@cindex @code{umulhisi3} instruction pattern 1866@cindex @code{umulsidi3} instruction pattern 1867@item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3} 1868Similar widening-multiplication instructions that do unsigned 1869multiplication. 1870 1871@cindex @code{smul@var{m}3_highpart} instruction pattern 1872@item @samp{mul@var{m}3_highpart} 1873Perform a signed multiplication of operands 1 and 2, which have mode 1874@var{m}, and store the most significant half of the product in operand 0. 1875The least significant half of the product is discarded. 1876 1877@cindex @code{umul@var{m}3_highpart} instruction pattern 1878@item @samp{umul@var{m}3_highpart} 1879Similar, but the multiplication is unsigned. 1880 1881@cindex @code{divmod@var{m}4} instruction pattern 1882@item @samp{divmod@var{m}4} 1883Signed division that produces both a quotient and a remainder. 1884Operand 1 is divided by operand 2 to produce a quotient stored 1885in operand 0 and a remainder stored in operand 3. 1886 1887For machines with an instruction that produces both a quotient and a 1888remainder, provide a pattern for @samp{divmod@var{m}4} but do not 1889provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}. This 1890allows optimization in the relatively common case when both the quotient 1891and remainder are computed. 1892 1893If an instruction that just produces a quotient or just a remainder 1894exists and is more efficient than the instruction that produces both, 1895write the output routine of @samp{divmod@var{m}4} to call 1896@code{find_reg_note} and look for a @code{REG_UNUSED} note on the 1897quotient or remainder and generate the appropriate instruction. 1898 1899@cindex @code{udivmod@var{m}4} instruction pattern 1900@item @samp{udivmod@var{m}4} 1901Similar, but does unsigned division. 1902 1903@cindex @code{ashl@var{m}3} instruction pattern 1904@item @samp{ashl@var{m}3} 1905Arithmetic-shift operand 1 left by a number of bits specified by operand 19062, and store the result in operand 0. Here @var{m} is the mode of 1907operand 0 and operand 1; operand 2's mode is specified by the 1908instruction pattern, and the compiler will convert the operand to that 1909mode before generating the instruction. 1910 1911@cindex @code{ashr@var{m}3} instruction pattern 1912@cindex @code{lshr@var{m}3} instruction pattern 1913@cindex @code{rotl@var{m}3} instruction pattern 1914@cindex @code{rotr@var{m}3} instruction pattern 1915@item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3} 1916Other shift and rotate instructions, analogous to the 1917@code{ashl@var{m}3} instructions. 1918 1919@cindex @code{neg@var{m}2} instruction pattern 1920@item @samp{neg@var{m}2} 1921Negate operand 1 and store the result in operand 0. 1922 1923@cindex @code{abs@var{m}2} instruction pattern 1924@item @samp{abs@var{m}2} 1925Store the absolute value of operand 1 into operand 0. 1926 1927@cindex @code{sqrt@var{m}2} instruction pattern 1928@item @samp{sqrt@var{m}2} 1929Store the square root of operand 1 into operand 0. 1930 1931The @code{sqrt} built-in function of C always uses the mode which 1932corresponds to the C data type @code{double}. 1933 1934@cindex @code{ffs@var{m}2} instruction pattern 1935@item @samp{ffs@var{m}2} 1936Store into operand 0 one plus the index of the least significant 1-bit 1937of operand 1. If operand 1 is zero, store zero. @var{m} is the mode 1938of operand 0; operand 1's mode is specified by the instruction 1939pattern, and the compiler will convert the operand to that mode before 1940generating the instruction. 1941 1942The @code{ffs} built-in function of C always uses the mode which 1943corresponds to the C data type @code{int}. 1944 1945@cindex @code{one_cmpl@var{m}2} instruction pattern 1946@item @samp{one_cmpl@var{m}2} 1947Store the bitwise-complement of operand 1 into operand 0. 1948 1949@cindex @code{cmp@var{m}} instruction pattern 1950@item @samp{cmp@var{m}} 1951Compare operand 0 and operand 1, and set the condition codes. 1952The RTL pattern should look like this: 1953 1954@smallexample 1955(set (cc0) (compare (match_operand:@var{m} 0 @dots{}) 1956 (match_operand:@var{m} 1 @dots{}))) 1957@end smallexample 1958 1959@cindex @code{tst@var{m}} instruction pattern 1960@item @samp{tst@var{m}} 1961Compare operand 0 against zero, and set the condition codes. 1962The RTL pattern should look like this: 1963 1964@smallexample 1965(set (cc0) (match_operand:@var{m} 0 @dots{})) 1966@end smallexample 1967 1968@samp{tst@var{m}} patterns should not be defined for machines that do 1969not use @code{(cc0)}. Doing so would confuse the optimizer since it 1970would no longer be clear which @code{set} operations were comparisons. 1971The @samp{cmp@var{m}} patterns should be used instead. 1972 1973@cindex @code{movstr@var{m}} instruction pattern 1974@item @samp{movstr@var{m}} 1975Block move instruction. The addresses of the destination and source 1976strings are the first two operands, and both are in mode @code{Pmode}. 1977 1978The number of bytes to move is the third operand, in mode @var{m}. 1979Usually, you specify @code{word_mode} for @var{m}. However, if you can 1980generate better code knowing the range of valid lengths is smaller than 1981those representable in a full word, you should provide a pattern with a 1982mode corresponding to the range of values you can handle efficiently 1983(e.g., @code{QImode} for values in the range 0--127; note we avoid numbers 1984that appear negative) and also a pattern with @code{word_mode}. 1985 1986The fourth operand is the known shared alignment of the source and 1987destination, in the form of a @code{const_int} rtx. Thus, if the 1988compiler knows that both source and destination are word-aligned, 1989it may provide the value 4 for this operand. 1990 1991Descriptions of multiple @code{movstr@var{m}} patterns can only be 1992beneficial if the patterns for smaller modes have fewer restrictions 1993on their first, second and fourth operands. Note that the mode @var{m} 1994in @code{movstr@var{m}} does not impose any restriction on the mode of 1995individually moved data units in the block. 1996 1997These patterns need not give special consideration to the possibility 1998that the source and destination strings might overlap. 1999 2000@cindex @code{clrstr@var{m}} instruction pattern 2001@item @samp{clrstr@var{m}} 2002Block clear instruction. The addresses of the destination string is the 2003first operand, in mode @code{Pmode}. The number of bytes to clear is 2004the second operand, in mode @var{m}. See @samp{movstr@var{m}} for 2005a discussion of the choice of mode. 2006 2007The third operand is the known alignment of the destination, in the form 2008of a @code{const_int} rtx. Thus, if the compiler knows that the 2009destination is word-aligned, it may provide the value 4 for this 2010operand. 2011 2012The use for multiple @code{clrstr@var{m}} is as for @code{movstr@var{m}}. 2013 2014@cindex @code{cmpstr@var{m}} instruction pattern 2015@item @samp{cmpstr@var{m}} 2016Block compare instruction, with five operands. Operand 0 is the output; 2017it has mode @var{m}. The remaining four operands are like the operands 2018of @samp{movstr@var{m}}. The two memory blocks specified are compared 2019byte by byte in lexicographic order. The effect of the instruction is 2020to store a value in operand 0 whose sign indicates the result of the 2021comparison. 2022 2023@cindex @code{strlen@var{m}} instruction pattern 2024@item @samp{strlen@var{m}} 2025Compute the length of a string, with three operands. 2026Operand 0 is the result (of mode @var{m}), operand 1 is 2027a @code{mem} referring to the first character of the string, 2028operand 2 is the character to search for (normally zero), 2029and operand 3 is a constant describing the known alignment 2030of the beginning of the string. 2031 2032@cindex @code{float@var{mn}2} instruction pattern 2033@item @samp{float@var{m}@var{n}2} 2034Convert signed integer operand 1 (valid for fixed point mode @var{m}) to 2035floating point mode @var{n} and store in operand 0 (which has mode 2036@var{n}). 2037 2038@cindex @code{floatuns@var{mn}2} instruction pattern 2039@item @samp{floatuns@var{m}@var{n}2} 2040Convert unsigned integer operand 1 (valid for fixed point mode @var{m}) 2041to floating point mode @var{n} and store in operand 0 (which has mode 2042@var{n}). 2043 2044@cindex @code{fix@var{mn}2} instruction pattern 2045@item @samp{fix@var{m}@var{n}2} 2046Convert operand 1 (valid for floating point mode @var{m}) to fixed 2047point mode @var{n} as a signed number and store in operand 0 (which 2048has mode @var{n}). This instruction's result is defined only when 2049the value of operand 1 is an integer. 2050 2051@cindex @code{fixuns@var{mn}2} instruction pattern 2052@item @samp{fixuns@var{m}@var{n}2} 2053Convert operand 1 (valid for floating point mode @var{m}) to fixed 2054point mode @var{n} as an unsigned number and store in operand 0 (which 2055has mode @var{n}). This instruction's result is defined only when the 2056value of operand 1 is an integer. 2057 2058@cindex @code{ftrunc@var{m}2} instruction pattern 2059@item @samp{ftrunc@var{m}2} 2060Convert operand 1 (valid for floating point mode @var{m}) to an 2061integer value, still represented in floating point mode @var{m}, and 2062store it in operand 0 (valid for floating point mode @var{m}). 2063 2064@cindex @code{fix_trunc@var{mn}2} instruction pattern 2065@item @samp{fix_trunc@var{m}@var{n}2} 2066Like @samp{fix@var{m}@var{n}2} but works for any floating point value 2067of mode @var{m} by converting the value to an integer. 2068 2069@cindex @code{fixuns_trunc@var{mn}2} instruction pattern 2070@item @samp{fixuns_trunc@var{m}@var{n}2} 2071Like @samp{fixuns@var{m}@var{n}2} but works for any floating point 2072value of mode @var{m} by converting the value to an integer. 2073 2074@cindex @code{trunc@var{mn}2} instruction pattern 2075@item @samp{trunc@var{m}@var{n}2} 2076Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and 2077store in operand 0 (which has mode @var{n}). Both modes must be fixed 2078point or both floating point. 2079 2080@cindex @code{extend@var{mn}2} instruction pattern 2081@item @samp{extend@var{m}@var{n}2} 2082Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and 2083store in operand 0 (which has mode @var{n}). Both modes must be fixed 2084point or both floating point. 2085 2086@cindex @code{zero_extend@var{mn}2} instruction pattern 2087@item @samp{zero_extend@var{m}@var{n}2} 2088Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and 2089store in operand 0 (which has mode @var{n}). Both modes must be fixed 2090point. 2091 2092@cindex @code{extv} instruction pattern 2093@item @samp{extv} 2094Extract a bit field from operand 1 (a register or memory operand), where 2095operand 2 specifies the width in bits and operand 3 the starting bit, 2096and store it in operand 0. Operand 0 must have mode @code{word_mode}. 2097Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often 2098@code{word_mode} is allowed only for registers. Operands 2 and 3 must 2099be valid for @code{word_mode}. 2100 2101The RTL generation pass generates this instruction only with constants 2102for operands 2 and 3. 2103 2104The bit-field value is sign-extended to a full word integer 2105before it is stored in operand 0. 2106 2107@cindex @code{extzv} instruction pattern 2108@item @samp{extzv} 2109Like @samp{extv} except that the bit-field value is zero-extended. 2110 2111@cindex @code{insv} instruction pattern 2112@item @samp{insv} 2113Store operand 3 (which must be valid for @code{word_mode}) into a bit 2114field in operand 0, where operand 1 specifies the width in bits and 2115operand 2 the starting bit. Operand 0 may have mode @code{byte_mode} or 2116@code{word_mode}; often @code{word_mode} is allowed only for registers. 2117Operands 1 and 2 must be valid for @code{word_mode}. 2118 2119The RTL generation pass generates this instruction only with constants 2120for operands 1 and 2. 2121 2122@cindex @code{mov@var{mode}cc} instruction pattern 2123@item @samp{mov@var{mode}cc} 2124Conditionally move operand 2 or operand 3 into operand 0 according to the 2125comparison in operand 1. If the comparison is true, operand 2 is moved 2126into operand 0, otherwise operand 3 is moved. 2127 2128The mode of the operands being compared need not be the same as the operands 2129being moved. Some machines, sparc64 for example, have instructions that 2130conditionally move an integer value based on the floating point condition 2131codes and vice versa. 2132 2133If the machine does not have conditional move instructions, do not 2134define these patterns. 2135 2136@cindex @code{s@var{cond}} instruction pattern 2137@item @samp{s@var{cond}} 2138Store zero or nonzero in the operand according to the condition codes. 2139Value stored is nonzero iff the condition @var{cond} is true. 2140@var{cond} is the name of a comparison operation expression code, such 2141as @code{eq}, @code{lt} or @code{leu}. 2142 2143You specify the mode that the operand must have when you write the 2144@code{match_operand} expression. The compiler automatically sees 2145which mode you have used and supplies an operand of that mode. 2146 2147The value stored for a true condition must have 1 as its low bit, or 2148else must be negative. Otherwise the instruction is not suitable and 2149you should omit it from the machine description. You describe to the 2150compiler exactly which value is stored by defining the macro 2151@code{STORE_FLAG_VALUE} (@pxref{Misc}). If a description cannot be 2152found that can be used for all the @samp{s@var{cond}} patterns, you 2153should omit those operations from the machine description. 2154 2155These operations may fail, but should do so only in relatively 2156uncommon cases; if they would fail for common cases involving 2157integer comparisons, it is best to omit these patterns. 2158 2159If these operations are omitted, the compiler will usually generate code 2160that copies the constant one to the target and branches around an 2161assignment of zero to the target. If this code is more efficient than 2162the potential instructions used for the @samp{s@var{cond}} pattern 2163followed by those required to convert the result into a 1 or a zero in 2164@code{SImode}, you should omit the @samp{s@var{cond}} operations from 2165the machine description. 2166 2167@cindex @code{b@var{cond}} instruction pattern 2168@item @samp{b@var{cond}} 2169Conditional branch instruction. Operand 0 is a @code{label_ref} that 2170refers to the label to jump to. Jump if the condition codes meet 2171condition @var{cond}. 2172 2173Some machines do not follow the model assumed here where a comparison 2174instruction is followed by a conditional branch instruction. In that 2175case, the @samp{cmp@var{m}} (and @samp{tst@var{m}}) patterns should 2176simply store the operands away and generate all the required insns in a 2177@code{define_expand} (@pxref{Expander Definitions}) for the conditional 2178branch operations. All calls to expand @samp{b@var{cond}} patterns are 2179immediately preceded by calls to expand either a @samp{cmp@var{m}} 2180pattern or a @samp{tst@var{m}} pattern. 2181 2182Machines that use a pseudo register for the condition code value, or 2183where the mode used for the comparison depends on the condition being 2184tested, should also use the above mechanism. @xref{Jump Patterns}. 2185 2186The above discussion also applies to the @samp{mov@var{mode}cc} and 2187@samp{s@var{cond}} patterns. 2188 2189@cindex @code{call} instruction pattern 2190@item @samp{call} 2191Subroutine call instruction returning no value. Operand 0 is the 2192function to call; operand 1 is the number of bytes of arguments pushed 2193as a @code{const_int}; operand 2 is the number of registers used as 2194operands. 2195 2196On most machines, operand 2 is not actually stored into the RTL 2197pattern. It is supplied for the sake of some RISC machines which need 2198to put this information into the assembler code; they can put it in 2199the RTL instead of operand 1. 2200 2201Operand 0 should be a @code{mem} RTX whose address is the address of the 2202function. Note, however, that this address can be a @code{symbol_ref} 2203expression even if it would not be a legitimate memory address on the 2204target machine. If it is also not a valid argument for a call 2205instruction, the pattern for this operation should be a 2206@code{define_expand} (@pxref{Expander Definitions}) that places the 2207address into a register and uses that register in the call instruction. 2208 2209@cindex @code{call_value} instruction pattern 2210@item @samp{call_value} 2211Subroutine call instruction returning a value. Operand 0 is the hard 2212register in which the value is returned. There are three more 2213operands, the same as the three operands of the @samp{call} 2214instruction (but with numbers increased by one). 2215 2216Subroutines that return @code{BLKmode} objects use the @samp{call} 2217insn. 2218 2219@cindex @code{call_pop} instruction pattern 2220@cindex @code{call_value_pop} instruction pattern 2221@item @samp{call_pop}, @samp{call_value_pop} 2222Similar to @samp{call} and @samp{call_value}, except used if defined and 2223if @code{RETURN_POPS_ARGS} is non-zero. They should emit a @code{parallel} 2224that contains both the function call and a @code{set} to indicate the 2225adjustment made to the frame pointer. 2226 2227For machines where @code{RETURN_POPS_ARGS} can be non-zero, the use of these 2228patterns increases the number of functions for which the frame pointer 2229can be eliminated, if desired. 2230 2231@cindex @code{untyped_call} instruction pattern 2232@item @samp{untyped_call} 2233Subroutine call instruction returning a value of any type. Operand 0 is 2234the function to call; operand 1 is a memory location where the result of 2235calling the function is to be stored; operand 2 is a @code{parallel} 2236expression where each element is a @code{set} expression that indicates 2237the saving of a function return value into the result block. 2238 2239This instruction pattern should be defined to support 2240@code{__builtin_apply} on machines where special instructions are needed 2241to call a subroutine with arbitrary arguments or to save the value 2242returned. This instruction pattern is required on machines that have 2243multiple registers that can hold a return value (i.e. 2244@code{FUNCTION_VALUE_REGNO_P} is true for more than one register). 2245 2246@cindex @code{return} instruction pattern 2247@item @samp{return} 2248Subroutine return instruction. This instruction pattern name should be 2249defined only if a single instruction can do all the work of returning 2250from a function. 2251 2252Like the @samp{mov@var{m}} patterns, this pattern is also used after the 2253RTL generation phase. In this case it is to support machines where 2254multiple instructions are usually needed to return from a function, but 2255some class of functions only requires one instruction to implement a 2256return. Normally, the applicable functions are those which do not need 2257to save any registers or allocate stack space. 2258 2259@findex reload_completed 2260@findex leaf_function_p 2261For such machines, the condition specified in this pattern should only 2262be true when @code{reload_completed} is non-zero and the function's 2263epilogue would only be a single instruction. For machines with register 2264windows, the routine @code{leaf_function_p} may be used to determine if 2265a register window push is required. 2266 2267Machines that have conditional return instructions should define patterns 2268such as 2269 2270@smallexample 2271(define_insn "" 2272 [(set (pc) 2273 (if_then_else (match_operator 2274 0 "comparison_operator" 2275 [(cc0) (const_int 0)]) 2276 (return) 2277 (pc)))] 2278 "@var{condition}" 2279 "@dots{}") 2280@end smallexample 2281 2282where @var{condition} would normally be the same condition specified on the 2283named @samp{return} pattern. 2284 2285@cindex @code{untyped_return} instruction pattern 2286@item @samp{untyped_return} 2287Untyped subroutine return instruction. This instruction pattern should 2288be defined to support @code{__builtin_return} on machines where special 2289instructions are needed to return a value of any type. 2290 2291Operand 0 is a memory location where the result of calling a function 2292with @code{__builtin_apply} is stored; operand 1 is a @code{parallel} 2293expression where each element is a @code{set} expression that indicates 2294the restoring of a function return value from the result block. 2295 2296@cindex @code{nop} instruction pattern 2297@item @samp{nop} 2298No-op instruction. This instruction pattern name should always be defined 2299to output a no-op in assembler code. @code{(const_int 0)} will do as an 2300RTL pattern. 2301 2302@cindex @code{indirect_jump} instruction pattern 2303@item @samp{indirect_jump} 2304An instruction to jump to an address which is operand zero. 2305This pattern name is mandatory on all machines. 2306 2307@cindex @code{casesi} instruction pattern 2308@item @samp{casesi} 2309Instruction to jump through a dispatch table, including bounds checking. 2310This instruction takes five operands: 2311 2312@enumerate 2313@item 2314The index to dispatch on, which has mode @code{SImode}. 2315 2316@item 2317The lower bound for indices in the table, an integer constant. 2318 2319@item 2320The total range of indices in the table---the largest index 2321minus the smallest one (both inclusive). 2322 2323@item 2324A label that precedes the table itself. 2325 2326@item 2327A label to jump to if the index has a value outside the bounds. 2328(If the machine-description macro @code{CASE_DROPS_THROUGH} is defined, 2329then an out-of-bounds index drops through to the code following 2330the jump table instead of jumping to this label. In that case, 2331this label is not actually used by the @samp{casesi} instruction, 2332but it is always provided as an operand.) 2333@end enumerate 2334 2335The table is a @code{addr_vec} or @code{addr_diff_vec} inside of a 2336@code{jump_insn}. The number of elements in the table is one plus the 2337difference between the upper bound and the lower bound. 2338 2339@cindex @code{tablejump} instruction pattern 2340@item @samp{tablejump} 2341Instruction to jump to a variable address. This is a low-level 2342capability which can be used to implement a dispatch table when there 2343is no @samp{casesi} pattern. 2344 2345This pattern requires two operands: the address or offset, and a label 2346which should immediately precede the jump table. If the macro 2347@code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first 2348operand is an offset which counts from the address of the table; otherwise, 2349it is an absolute address to jump to. In either case, the first operand has 2350mode @code{Pmode}. 2351 2352The @samp{tablejump} insn is always the last insn before the jump 2353table it uses. Its assembler code normally has no need to use the 2354second operand, but you should incorporate it in the RTL pattern so 2355that the jump optimizer will not delete the table as unreachable code. 2356 2357@cindex @code{canonicalize_funcptr_for_compare} instruction pattern 2358@item @samp{canonicalize_funcptr_for_compare} 2359Canonicalize the function pointer in operand 1 and store the result 2360into operand 0. 2361 2362Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1 2363may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc 2364and also has mode @code{Pmode}. 2365 2366Canonicalization of a function pointer usually involves computing 2367the address of the function which would be called if the function 2368pointer were used in an indirect call. 2369 2370Only define this pattern if function pointers on the target machine 2371can have different values but still call the same function when 2372used in an indirect call. 2373 2374@cindex @code{save_stack_block} instruction pattern 2375@cindex @code{save_stack_function} instruction pattern 2376@cindex @code{save_stack_nonlocal} instruction pattern 2377@cindex @code{restore_stack_block} instruction pattern 2378@cindex @code{restore_stack_function} instruction pattern 2379@cindex @code{restore_stack_nonlocal} instruction pattern 2380@item @samp{save_stack_block} 2381@itemx @samp{save_stack_function} 2382@itemx @samp{save_stack_nonlocal} 2383@itemx @samp{restore_stack_block} 2384@itemx @samp{restore_stack_function} 2385@itemx @samp{restore_stack_nonlocal} 2386Most machines save and restore the stack pointer by copying it to or 2387from an object of mode @code{Pmode}. Do not define these patterns on 2388such machines. 2389 2390Some machines require special handling for stack pointer saves and 2391restores. On those machines, define the patterns corresponding to the 2392non-standard cases by using a @code{define_expand} (@pxref{Expander 2393Definitions}) that produces the required insns. The three types of 2394saves and restores are: 2395 2396@enumerate 2397@item 2398@samp{save_stack_block} saves the stack pointer at the start of a block 2399that allocates a variable-sized object, and @samp{restore_stack_block} 2400restores the stack pointer when the block is exited. 2401 2402@item 2403@samp{save_stack_function} and @samp{restore_stack_function} do a 2404similar job for the outermost block of a function and are used when the 2405function allocates variable-sized objects or calls @code{alloca}. Only 2406the epilogue uses the restored stack pointer, allowing a simpler save or 2407restore sequence on some machines. 2408 2409@item 2410@samp{save_stack_nonlocal} is used in functions that contain labels 2411branched to by nested functions. It saves the stack pointer in such a 2412way that the inner function can use @samp{restore_stack_nonlocal} to 2413restore the stack pointer. The compiler generates code to restore the 2414frame and argument pointer registers, but some machines require saving 2415and restoring additional data such as register window information or 2416stack backchains. Place insns in these patterns to save and restore any 2417such required data. 2418@end enumerate 2419 2420When saving the stack pointer, operand 0 is the save area and operand 1 2421is the stack pointer. The mode used to allocate the save area defaults 2422to @code{Pmode} but you can override that choice by defining the 2423@code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}). You must 2424specify an integral mode, or @code{VOIDmode} if no save area is needed 2425for a particular type of save (either because no save is needed or 2426because a machine-specific save area can be used). Operand 0 is the 2427stack pointer and operand 1 is the save area for restore operations. If 2428@samp{save_stack_block} is defined, operand 0 must not be 2429@code{VOIDmode} since these saves can be arbitrarily nested. 2430 2431A save area is a @code{mem} that is at a constant offset from 2432@code{virtual_stack_vars_rtx} when the stack pointer is saved for use by 2433nonlocal gotos and a @code{reg} in the other two cases. 2434 2435@cindex @code{allocate_stack} instruction pattern 2436@item @samp{allocate_stack} 2437Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from 2438the stack pointer to create space for dynamically allocated data. 2439 2440Store the resultant pointer to this space into operand 0. If you 2441are allocating space from the main stack, do this by emitting a 2442move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0. 2443If you are allocating the space elsewhere, generate code to copy the 2444location of the space to operand 0. In the latter case, you must 2445ensure this space gets freed when the corresponding space on the main 2446stack is free. 2447 2448Do not define this pattern if all that must be done is the subtraction. 2449Some machines require other operations such as stack probes or 2450maintaining the back chain. Define this pattern to emit those 2451operations in addition to updating the stack pointer. 2452 2453@cindex @code{probe} instruction pattern 2454@item @samp{probe} 2455Some machines require instructions to be executed after space is 2456allocated from the stack, for example to generate a reference at 2457the bottom of the stack. 2458 2459If you need to emit instructions before the stack has been adjusted, 2460put them into the @samp{allocate_stack} pattern. Otherwise, define 2461this pattern to emit the required instructions. 2462 2463No operands are provided. 2464 2465@cindex @code{check_stack} instruction pattern 2466@item @samp{check_stack} 2467If stack checking cannot be done on your system by probing the stack with 2468a load or store instruction (@pxref{Stack Checking}), define this pattern 2469to perform the needed check and signaling an error if the stack 2470has overflowed. The single operand is the location in the stack furthest 2471from the current stack pointer that you need to validate. Normally, 2472on machines where this pattern is needed, you would obtain the stack 2473limit from a global or thread-specific variable or register. 2474 2475@cindex @code{nonlocal_goto} instruction pattern 2476@item @samp{nonlocal_goto} 2477Emit code to generate a non-local goto, e.g., a jump from one function 2478to a label in an outer function. This pattern has four arguments, 2479each representing a value to be used in the jump. The first 2480argument is to be loaded into the frame pointer, the second is 2481the address to branch to (code to dispatch to the actual label), 2482the third is the address of a location where the stack is saved, 2483and the last is the address of the label, to be placed in the 2484location for the incoming static chain. 2485 2486On most machines you need not define this pattern, since GNU CC will 2487already generate the correct code, which is to load the frame pointer 2488and static chain, restore the stack (using the 2489@samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly 2490to the dispatcher. You need only define this pattern if this code will 2491not work on your machine. 2492 2493@cindex @code{nonlocal_goto_receiver} instruction pattern 2494@item @samp{nonlocal_goto_receiver} 2495This pattern, if defined, contains code needed at the target of a 2496nonlocal goto after the code already generated by GNU CC. You will not 2497normally need to define this pattern. A typical reason why you might 2498need this pattern is if some value, such as a pointer to a global table, 2499must be restored when the frame pointer is restored. Note that a nonlocal 2500goto only ocurrs within a unit-of-translation, so a global table pointer 2501that is shared by all functions of a given module need not be restored. 2502There are no arguments. 2503 2504@cindex @code{exception_receiver} instruction pattern 2505@item @samp{exception_receiver} 2506This pattern, if defined, contains code needed at the site of an 2507exception handler that isn't needed at the site of a nonlocal goto. You 2508will not normally need to define this pattern. A typical reason why you 2509might need this pattern is if some value, such as a pointer to a global 2510table, must be restored after control flow is branched to the handler of 2511an exception. There are no arguments. 2512 2513@cindex @code{builtin_setjmp_setup} instruction pattern 2514@item @samp{builtin_setjmp_setup} 2515This pattern, if defined, contains additional code needed to initialize 2516the @code{jmp_buf}. You will not normally need to define this pattern. 2517A typical reason why you might need this pattern is if some value, such 2518as a pointer to a global table, must be restored. Though it is 2519preferred that the pointer value be recalculated if possible (given the 2520address of a label for instance). The single argument is a pointer to 2521the @code{jmp_buf}. Note that the buffer is five words long and that 2522the first three are normally used by the generic mechanism. 2523 2524@cindex @code{builtin_setjmp_receiver} instruction pattern 2525@item @samp{builtin_setjmp_receiver} 2526This pattern, if defined, contains code needed at the site of an 2527builtin setjmp that isn't needed at the site of a nonlocal goto. You 2528will not normally need to define this pattern. A typical reason why you 2529might need this pattern is if some value, such as a pointer to a global 2530table, must be restored. It takes one argument, which is the label 2531to which builtin_longjmp transfered control; this pattern may be emitted 2532at a small offset from that label. 2533 2534@cindex @code{builtin_longjmp} instruction pattern 2535@item @samp{builtin_longjmp} 2536This pattern, if defined, performs the entire action of the longjmp. 2537You will not normally need to define this pattern unless you also define 2538@code{builtin_setjmp_setup}. The single argument is a pointer to the 2539@code{jmp_buf}. 2540 2541@cindex @code{eh_epilogue} instruction pattern 2542@item @samp{eh_epilogue} 2543This pattern, if defined, affects the way @code{__builtin_eh_return}, 2544and thence @code{__throw} are built. It is intended to allow communication 2545between the exception handling machinery and the normal epilogue code 2546for the target. 2547 2548The pattern takes three arguments. The first is the exception context 2549pointer. This will have already been copied to the function return 2550register appropriate for a pointer; normally this can be ignored. The 2551second argument is an offset to be added to the stack pointer. It will 2552have been copied to some arbitrary call-clobbered hard reg so that it 2553will survive until after reload to when the normal epilogue is generated. 2554The final argument is the address of the exception handler to which 2555the function should return. This will normally need to copied by the 2556pattern to some special register. 2557 2558This pattern must be defined if @code{RETURN_ADDR_RTX} does not yield 2559something that can be reliably and permanently modified, i.e. a fixed 2560hard register or a stack memory reference. 2561 2562@cindex @code{prologue} instruction pattern 2563@item @samp{prologue} 2564This pattern, if defined, emits RTL for entry to a function. The function 2565entry is resposible for setting up the stack frame, initializing the frame 2566pointer register, saving callee saved registers, etc. 2567 2568Using a prologue pattern is generally preferred over defining 2569@code{FUNCTION_PROLOGUE} to emit assembly code for the prologue. 2570 2571The @code{prologue} pattern is particularly useful for targets which perform 2572instruction scheduling. 2573 2574@cindex @code{epilogue} instruction pattern 2575@item @samp{epilogue} 2576This pattern, if defined, emits RTL for exit from a function. The function 2577exit is resposible for deallocating the stack frame, restoring callee saved 2578registers and emitting the return instruction. 2579 2580Using an epilogue pattern is generally preferred over defining 2581@code{FUNCTION_EPILOGUE} to emit assembly code for the prologue. 2582 2583The @code{epilogue} pattern is particularly useful for targets which perform 2584instruction scheduling or which have delay slots for their return instruction. 2585 2586@cindex @code{sibcall_epilogue} instruction pattern 2587@item @samp{sibcall_epilogue} 2588This pattern, if defined, emits RTL for exit from a function without the final 2589branch back to the calling function. This pattern will be emitted before any 2590sibling call (aka tail call) sites. 2591 2592The @code{sibcall_epilogue} pattern must not clobber any arguments used for 2593parameter passing or any stack slots for arguments passed to the current 2594function. 2595@end table 2596 2597@node Pattern Ordering 2598@section When the Order of Patterns Matters 2599@cindex Pattern Ordering 2600@cindex Ordering of Patterns 2601 2602Sometimes an insn can match more than one instruction pattern. Then the 2603pattern that appears first in the machine description is the one used. 2604Therefore, more specific patterns (patterns that will match fewer things) 2605and faster instructions (those that will produce better code when they 2606do match) should usually go first in the description. 2607 2608In some cases the effect of ordering the patterns can be used to hide 2609a pattern when it is not valid. For example, the 68000 has an 2610instruction for converting a fullword to floating point and another 2611for converting a byte to floating point. An instruction converting 2612an integer to floating point could match either one. We put the 2613pattern to convert the fullword first to make sure that one will 2614be used rather than the other. (Otherwise a large integer might 2615be generated as a single-byte immediate quantity, which would not work.) 2616Instead of using this pattern ordering it would be possible to make the 2617pattern for convert-a-byte smart enough to deal properly with any 2618constant value. 2619 2620@node Dependent Patterns 2621@section Interdependence of Patterns 2622@cindex Dependent Patterns 2623@cindex Interdependence of Patterns 2624 2625Every machine description must have a named pattern for each of the 2626conditional branch names @samp{b@var{cond}}. The recognition template 2627must always have the form 2628 2629@example 2630(set (pc) 2631 (if_then_else (@var{cond} (cc0) (const_int 0)) 2632 (label_ref (match_operand 0 "" "")) 2633 (pc))) 2634@end example 2635 2636@noindent 2637In addition, every machine description must have an anonymous pattern 2638for each of the possible reverse-conditional branches. Their templates 2639look like 2640 2641@example 2642(set (pc) 2643 (if_then_else (@var{cond} (cc0) (const_int 0)) 2644 (pc) 2645 (label_ref (match_operand 0 "" "")))) 2646@end example 2647 2648@noindent 2649They are necessary because jump optimization can turn direct-conditional 2650branches into reverse-conditional branches. 2651 2652It is often convenient to use the @code{match_operator} construct to 2653reduce the number of patterns that must be specified for branches. For 2654example, 2655 2656@example 2657(define_insn "" 2658 [(set (pc) 2659 (if_then_else (match_operator 0 "comparison_operator" 2660 [(cc0) (const_int 0)]) 2661 (pc) 2662 (label_ref (match_operand 1 "" ""))))] 2663 "@var{condition}" 2664 "@dots{}") 2665@end example 2666 2667In some cases machines support instructions identical except for the 2668machine mode of one or more operands. For example, there may be 2669``sign-extend halfword'' and ``sign-extend byte'' instructions whose 2670patterns are 2671 2672@example 2673(set (match_operand:SI 0 @dots{}) 2674 (extend:SI (match_operand:HI 1 @dots{}))) 2675 2676(set (match_operand:SI 0 @dots{}) 2677 (extend:SI (match_operand:QI 1 @dots{}))) 2678@end example 2679 2680@noindent 2681Constant integers do not specify a machine mode, so an instruction to 2682extend a constant value could match either pattern. The pattern it 2683actually will match is the one that appears first in the file. For correct 2684results, this must be the one for the widest possible mode (@code{HImode}, 2685here). If the pattern matches the @code{QImode} instruction, the results 2686will be incorrect if the constant value does not actually fit that mode. 2687 2688Such instructions to extend constants are rarely generated because they are 2689optimized away, but they do occasionally happen in nonoptimized 2690compilations. 2691 2692If a constraint in a pattern allows a constant, the reload pass may 2693replace a register with a constant permitted by the constraint in some 2694cases. Similarly for memory references. Because of this substitution, 2695you should not provide separate patterns for increment and decrement 2696instructions. Instead, they should be generated from the same pattern 2697that supports register-register add insns by examining the operands and 2698generating the appropriate machine instruction. 2699 2700@node Jump Patterns 2701@section Defining Jump Instruction Patterns 2702@cindex jump instruction patterns 2703@cindex defining jump instruction patterns 2704 2705For most machines, GNU CC assumes that the machine has a condition code. 2706A comparison insn sets the condition code, recording the results of both 2707signed and unsigned comparison of the given operands. A separate branch 2708insn tests the condition code and branches or not according its value. 2709The branch insns come in distinct signed and unsigned flavors. Many 2710common machines, such as the Vax, the 68000 and the 32000, work this 2711way. 2712 2713Some machines have distinct signed and unsigned compare instructions, and 2714only one set of conditional branch instructions. The easiest way to handle 2715these machines is to treat them just like the others until the final stage 2716where assembly code is written. At this time, when outputting code for the 2717compare instruction, peek ahead at the following branch using 2718@code{next_cc0_user (insn)}. (The variable @code{insn} refers to the insn 2719being output, in the output-writing code in an instruction pattern.) If 2720the RTL says that is an unsigned branch, output an unsigned compare; 2721otherwise output a signed compare. When the branch itself is output, you 2722can treat signed and unsigned branches identically. 2723 2724The reason you can do this is that GNU CC always generates a pair of 2725consecutive RTL insns, possibly separated by @code{note} insns, one to 2726set the condition code and one to test it, and keeps the pair inviolate 2727until the end. 2728 2729To go with this technique, you must define the machine-description macro 2730@code{NOTICE_UPDATE_CC} to do @code{CC_STATUS_INIT}; in other words, no 2731compare instruction is superfluous. 2732 2733Some machines have compare-and-branch instructions and no condition code. 2734A similar technique works for them. When it is time to ``output'' a 2735compare instruction, record its operands in two static variables. When 2736outputting the branch-on-condition-code instruction that follows, actually 2737output a compare-and-branch instruction that uses the remembered operands. 2738 2739It also works to define patterns for compare-and-branch instructions. 2740In optimizing compilation, the pair of compare and branch instructions 2741will be combined according to these patterns. But this does not happen 2742if optimization is not requested. So you must use one of the solutions 2743above in addition to any special patterns you define. 2744 2745In many RISC machines, most instructions do not affect the condition 2746code and there may not even be a separate condition code register. On 2747these machines, the restriction that the definition and use of the 2748condition code be adjacent insns is not necessary and can prevent 2749important optimizations. For example, on the IBM RS/6000, there is a 2750delay for taken branches unless the condition code register is set three 2751instructions earlier than the conditional branch. The instruction 2752scheduler cannot perform this optimization if it is not permitted to 2753separate the definition and use of the condition code register. 2754 2755On these machines, do not use @code{(cc0)}, but instead use a register 2756to represent the condition code. If there is a specific condition code 2757register in the machine, use a hard register. If the condition code or 2758comparison result can be placed in any general register, or if there are 2759multiple condition registers, use a pseudo register. 2760 2761@findex prev_cc0_setter 2762@findex next_cc0_user 2763On some machines, the type of branch instruction generated may depend on 2764the way the condition code was produced; for example, on the 68k and 2765Sparc, setting the condition code directly from an add or subtract 2766instruction does not clear the overflow bit the way that a test 2767instruction does, so a different branch instruction must be used for 2768some conditional branches. For machines that use @code{(cc0)}, the set 2769and use of the condition code must be adjacent (separated only by 2770@code{note} insns) allowing flags in @code{cc_status} to be used. 2771(@xref{Condition Code}.) Also, the comparison and branch insns can be 2772located from each other by using the functions @code{prev_cc0_setter} 2773and @code{next_cc0_user}. 2774 2775However, this is not true on machines that do not use @code{(cc0)}. On 2776those machines, no assumptions can be made about the adjacency of the 2777compare and branch insns and the above methods cannot be used. Instead, 2778we use the machine mode of the condition code register to record 2779different formats of the condition code register. 2780 2781Registers used to store the condition code value should have a mode that 2782is in class @code{MODE_CC}. Normally, it will be @code{CCmode}. If 2783additional modes are required (as for the add example mentioned above in 2784the Sparc), define the macro @code{EXTRA_CC_MODES} to list the 2785additional modes required (@pxref{Condition Code}). Also define 2786@code{EXTRA_CC_NAMES} to list the names of those modes and 2787@code{SELECT_CC_MODE} to choose a mode given an operand of a compare. 2788 2789If it is known during RTL generation that a different mode will be 2790required (for example, if the machine has separate compare instructions 2791for signed and unsigned quantities, like most IBM processors), they can 2792be specified at that time. 2793 2794If the cases that require different modes would be made by instruction 2795combination, the macro @code{SELECT_CC_MODE} determines which machine 2796mode should be used for the comparison result. The patterns should be 2797written using that mode. To support the case of the add on the Sparc 2798discussed above, we have the pattern 2799 2800@smallexample 2801(define_insn "" 2802 [(set (reg:CC_NOOV 0) 2803 (compare:CC_NOOV 2804 (plus:SI (match_operand:SI 0 "register_operand" "%r") 2805 (match_operand:SI 1 "arith_operand" "rI")) 2806 (const_int 0)))] 2807 "" 2808 "@dots{}") 2809@end smallexample 2810 2811The @code{SELECT_CC_MODE} macro on the Sparc returns @code{CC_NOOVmode} 2812for comparisons whose argument is a @code{plus}. 2813 2814@node Insn Canonicalizations 2815@section Canonicalization of Instructions 2816@cindex canonicalization of instructions 2817@cindex insn canonicalization 2818 2819There are often cases where multiple RTL expressions could represent an 2820operation performed by a single machine instruction. This situation is 2821most commonly encountered with logical, branch, and multiply-accumulate 2822instructions. In such cases, the compiler attempts to convert these 2823multiple RTL expressions into a single canonical form to reduce the 2824number of insn patterns required. 2825 2826In addition to algebraic simplifications, following canonicalizations 2827are performed: 2828 2829@itemize @bullet 2830@item 2831For commutative and comparison operators, a constant is always made the 2832second operand. If a machine only supports a constant as the second 2833operand, only patterns that match a constant in the second operand need 2834be supplied. 2835 2836@cindex @code{neg}, canonicalization of 2837@cindex @code{not}, canonicalization of 2838@cindex @code{mult}, canonicalization of 2839@cindex @code{plus}, canonicalization of 2840@cindex @code{minus}, canonicalization of 2841For these operators, if only one operand is a @code{neg}, @code{not}, 2842@code{mult}, @code{plus}, or @code{minus} expression, it will be the 2843first operand. 2844 2845@cindex @code{compare}, canonicalization of 2846@item 2847For the @code{compare} operator, a constant is always the second operand 2848on machines where @code{cc0} is used (@pxref{Jump Patterns}). On other 2849machines, there are rare cases where the compiler might want to construct 2850a @code{compare} with a constant as the first operand. However, these 2851cases are not common enough for it to be worthwhile to provide a pattern 2852matching a constant as the first operand unless the machine actually has 2853such an instruction. 2854 2855An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or 2856@code{minus} is made the first operand under the same conditions as 2857above. 2858 2859@item 2860@code{(minus @var{x} (const_int @var{n}))} is converted to 2861@code{(plus @var{x} (const_int @var{-n}))}. 2862 2863@item 2864Within address computations (i.e., inside @code{mem}), a left shift is 2865converted into the appropriate multiplication by a power of two. 2866 2867@cindex @code{ior}, canonicalization of 2868@cindex @code{and}, canonicalization of 2869@cindex De Morgan's law 2870@item 2871De`Morgan's Law is used to move bitwise negation inside a bitwise 2872logical-and or logical-or operation. If this results in only one 2873operand being a @code{not} expression, it will be the first one. 2874 2875A machine that has an instruction that performs a bitwise logical-and of one 2876operand with the bitwise negation of the other should specify the pattern 2877for that instruction as 2878 2879@example 2880(define_insn "" 2881 [(set (match_operand:@var{m} 0 @dots{}) 2882 (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) 2883 (match_operand:@var{m} 2 @dots{})))] 2884 "@dots{}" 2885 "@dots{}") 2886@end example 2887 2888@noindent 2889Similarly, a pattern for a ``NAND'' instruction should be written 2890 2891@example 2892(define_insn "" 2893 [(set (match_operand:@var{m} 0 @dots{}) 2894 (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) 2895 (not:@var{m} (match_operand:@var{m} 2 @dots{}))))] 2896 "@dots{}" 2897 "@dots{}") 2898@end example 2899 2900In both cases, it is not necessary to include patterns for the many 2901logically equivalent RTL expressions. 2902 2903@cindex @code{xor}, canonicalization of 2904@item 2905The only possible RTL expressions involving both bitwise exclusive-or 2906and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})} 2907and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}.@refill 2908 2909@item 2910The sum of three items, one of which is a constant, will only appear in 2911the form 2912 2913@example 2914(plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant}) 2915@end example 2916 2917@item 2918On machines that do not use @code{cc0}, 2919@code{(compare @var{x} (const_int 0))} will be converted to 2920@var{x}.@refill 2921 2922@cindex @code{zero_extract}, canonicalization of 2923@cindex @code{sign_extract}, canonicalization of 2924@item 2925Equality comparisons of a group of bits (usually a single bit) with zero 2926will be written using @code{zero_extract} rather than the equivalent 2927@code{and} or @code{sign_extract} operations. 2928 2929@end itemize 2930 2931@node Peephole Definitions 2932@section Machine-Specific Peephole Optimizers 2933@cindex peephole optimizer definitions 2934@cindex defining peephole optimizers 2935 2936In addition to instruction patterns the @file{md} file may contain 2937definitions of machine-specific peephole optimizations. 2938 2939The combiner does not notice certain peephole optimizations when the data 2940flow in the program does not suggest that it should try them. For example, 2941sometimes two consecutive insns related in purpose can be combined even 2942though the second one does not appear to use a register computed in the 2943first one. A machine-specific peephole optimizer can detect such 2944opportunities. 2945 2946@need 1000 2947A definition looks like this: 2948 2949@smallexample 2950(define_peephole 2951 [@var{insn-pattern-1} 2952 @var{insn-pattern-2} 2953 @dots{}] 2954 "@var{condition}" 2955 "@var{template}" 2956 "@var{optional insn-attributes}") 2957@end smallexample 2958 2959@noindent 2960The last string operand may be omitted if you are not using any 2961machine-specific information in this machine description. If present, 2962it must obey the same rules as in a @code{define_insn}. 2963 2964In this skeleton, @var{insn-pattern-1} and so on are patterns to match 2965consecutive insns. The optimization applies to a sequence of insns when 2966@var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches 2967the next, and so on.@refill 2968 2969Each of the insns matched by a peephole must also match a 2970@code{define_insn}. Peepholes are checked only at the last stage just 2971before code generation, and only optionally. Therefore, any insn which 2972would match a peephole but no @code{define_insn} will cause a crash in code 2973generation in an unoptimized compilation, or at various optimization 2974stages. 2975 2976The operands of the insns are matched with @code{match_operands}, 2977@code{match_operator}, and @code{match_dup}, as usual. What is not 2978usual is that the operand numbers apply to all the insn patterns in the 2979definition. So, you can check for identical operands in two insns by 2980using @code{match_operand} in one insn and @code{match_dup} in the 2981other. 2982 2983The operand constraints used in @code{match_operand} patterns do not have 2984any direct effect on the applicability of the peephole, but they will 2985be validated afterward, so make sure your constraints are general enough 2986to apply whenever the peephole matches. If the peephole matches 2987but the constraints are not satisfied, the compiler will crash. 2988 2989It is safe to omit constraints in all the operands of the peephole; or 2990you can write constraints which serve as a double-check on the criteria 2991previously tested. 2992 2993Once a sequence of insns matches the patterns, the @var{condition} is 2994checked. This is a C expression which makes the final decision whether to 2995perform the optimization (we do so if the expression is nonzero). If 2996@var{condition} is omitted (in other words, the string is empty) then the 2997optimization is applied to every sequence of insns that matches the 2998patterns. 2999 3000The defined peephole optimizations are applied after register allocation 3001is complete. Therefore, the peephole definition can check which 3002operands have ended up in which kinds of registers, just by looking at 3003the operands. 3004 3005@findex prev_active_insn 3006The way to refer to the operands in @var{condition} is to write 3007@code{operands[@var{i}]} for operand number @var{i} (as matched by 3008@code{(match_operand @var{i} @dots{})}). Use the variable @code{insn} 3009to refer to the last of the insns being matched; use 3010@code{prev_active_insn} to find the preceding insns. 3011 3012@findex dead_or_set_p 3013When optimizing computations with intermediate results, you can use 3014@var{condition} to match only when the intermediate results are not used 3015elsewhere. Use the C expression @code{dead_or_set_p (@var{insn}, 3016@var{op})}, where @var{insn} is the insn in which you expect the value 3017to be used for the last time (from the value of @code{insn}, together 3018with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate 3019value (from @code{operands[@var{i}]}).@refill 3020 3021Applying the optimization means replacing the sequence of insns with one 3022new insn. The @var{template} controls ultimate output of assembler code 3023for this combined insn. It works exactly like the template of a 3024@code{define_insn}. Operand numbers in this template are the same ones 3025used in matching the original sequence of insns. 3026 3027The result of a defined peephole optimizer does not need to match any of 3028the insn patterns in the machine description; it does not even have an 3029opportunity to match them. The peephole optimizer definition itself serves 3030as the insn pattern to control how the insn is output. 3031 3032Defined peephole optimizers are run as assembler code is being output, 3033so the insns they produce are never combined or rearranged in any way. 3034 3035Here is an example, taken from the 68000 machine description: 3036 3037@smallexample 3038(define_peephole 3039 [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4))) 3040 (set (match_operand:DF 0 "register_operand" "=f") 3041 (match_operand:DF 1 "register_operand" "ad"))] 3042 "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])" 3043 "* 3044@{ 3045 rtx xoperands[2]; 3046 xoperands[1] = gen_rtx (REG, SImode, REGNO (operands[1]) + 1); 3047#ifdef MOTOROLA 3048 output_asm_insn (\"move.l %1,(sp)\", xoperands); 3049 output_asm_insn (\"move.l %1,-(sp)\", operands); 3050 return \"fmove.d (sp)+,%0\"; 3051#else 3052 output_asm_insn (\"movel %1,sp@@\", xoperands); 3053 output_asm_insn (\"movel %1,sp@@-\", operands); 3054 return \"fmoved sp@@+,%0\"; 3055#endif 3056@} 3057") 3058@end smallexample 3059 3060@need 1000 3061The effect of this optimization is to change 3062 3063@smallexample 3064@group 3065jbsr _foobar 3066addql #4,sp 3067movel d1,sp@@- 3068movel d0,sp@@- 3069fmoved sp@@+,fp0 3070@end group 3071@end smallexample 3072 3073@noindent 3074into 3075 3076@smallexample 3077@group 3078jbsr _foobar 3079movel d1,sp@@ 3080movel d0,sp@@- 3081fmoved sp@@+,fp0 3082@end group 3083@end smallexample 3084 3085@ignore 3086@findex CC_REVERSED 3087If a peephole matches a sequence including one or more jump insns, you must 3088take account of the flags such as @code{CC_REVERSED} which specify that the 3089condition codes are represented in an unusual manner. The compiler 3090automatically alters any ordinary conditional jumps which occur in such 3091situations, but the compiler cannot alter jumps which have been replaced by 3092peephole optimizations. So it is up to you to alter the assembler code 3093that the peephole produces. Supply C code to write the assembler output, 3094and in this C code check the condition code status flags and change the 3095assembler code as appropriate. 3096@end ignore 3097 3098@var{insn-pattern-1} and so on look @emph{almost} like the second 3099operand of @code{define_insn}. There is one important difference: the 3100second operand of @code{define_insn} consists of one or more RTX's 3101enclosed in square brackets. Usually, there is only one: then the same 3102action can be written as an element of a @code{define_peephole}. But 3103when there are multiple actions in a @code{define_insn}, they are 3104implicitly enclosed in a @code{parallel}. Then you must explicitly 3105write the @code{parallel}, and the square brackets within it, in the 3106@code{define_peephole}. Thus, if an insn pattern looks like this, 3107 3108@smallexample 3109(define_insn "divmodsi4" 3110 [(set (match_operand:SI 0 "general_operand" "=d") 3111 (div:SI (match_operand:SI 1 "general_operand" "0") 3112 (match_operand:SI 2 "general_operand" "dmsK"))) 3113 (set (match_operand:SI 3 "general_operand" "=d") 3114 (mod:SI (match_dup 1) (match_dup 2)))] 3115 "TARGET_68020" 3116 "divsl%.l %2,%3:%0") 3117@end smallexample 3118 3119@noindent 3120then the way to mention this insn in a peephole is as follows: 3121 3122@smallexample 3123(define_peephole 3124 [@dots{} 3125 (parallel 3126 [(set (match_operand:SI 0 "general_operand" "=d") 3127 (div:SI (match_operand:SI 1 "general_operand" "0") 3128 (match_operand:SI 2 "general_operand" "dmsK"))) 3129 (set (match_operand:SI 3 "general_operand" "=d") 3130 (mod:SI (match_dup 1) (match_dup 2)))]) 3131 @dots{}] 3132 @dots{}) 3133@end smallexample 3134 3135@node Expander Definitions 3136@section Defining RTL Sequences for Code Generation 3137@cindex expander definitions 3138@cindex code generation RTL sequences 3139@cindex defining RTL sequences for code generation 3140 3141On some target machines, some standard pattern names for RTL generation 3142cannot be handled with single insn, but a sequence of RTL insns can 3143represent them. For these target machines, you can write a 3144@code{define_expand} to specify how to generate the sequence of RTL. 3145 3146@findex define_expand 3147A @code{define_expand} is an RTL expression that looks almost like a 3148@code{define_insn}; but, unlike the latter, a @code{define_expand} is used 3149only for RTL generation and it can produce more than one RTL insn. 3150 3151A @code{define_expand} RTX has four operands: 3152 3153@itemize @bullet 3154@item 3155The name. Each @code{define_expand} must have a name, since the only 3156use for it is to refer to it by name. 3157 3158@findex define_peephole 3159@item 3160The RTL template. This is just like the RTL template for a 3161@code{define_peephole} in that it is a vector of RTL expressions 3162each being one insn. 3163 3164@item 3165The condition, a string containing a C expression. This expression is 3166used to express how the availability of this pattern depends on 3167subclasses of target machine, selected by command-line options when GNU 3168CC is run. This is just like the condition of a @code{define_insn} that 3169has a standard name. Therefore, the condition (if present) may not 3170depend on the data in the insn being matched, but only the 3171target-machine-type flags. The compiler needs to test these conditions 3172during initialization in order to learn exactly which named instructions 3173are available in a particular run. 3174 3175@item 3176The preparation statements, a string containing zero or more C 3177statements which are to be executed before RTL code is generated from 3178the RTL template. 3179 3180Usually these statements prepare temporary registers for use as 3181internal operands in the RTL template, but they can also generate RTL 3182insns directly by calling routines such as @code{emit_insn}, etc. 3183Any such insns precede the ones that come from the RTL template. 3184@end itemize 3185 3186Every RTL insn emitted by a @code{define_expand} must match some 3187@code{define_insn} in the machine description. Otherwise, the compiler 3188will crash when trying to generate code for the insn or trying to optimize 3189it. 3190 3191The RTL template, in addition to controlling generation of RTL insns, 3192also describes the operands that need to be specified when this pattern 3193is used. In particular, it gives a predicate for each operand. 3194 3195A true operand, which needs to be specified in order to generate RTL from 3196the pattern, should be described with a @code{match_operand} in its first 3197occurrence in the RTL template. This enters information on the operand's 3198predicate into the tables that record such things. GNU CC uses the 3199information to preload the operand into a register if that is required for 3200valid RTL code. If the operand is referred to more than once, subsequent 3201references should use @code{match_dup}. 3202 3203The RTL template may also refer to internal ``operands'' which are 3204temporary registers or labels used only within the sequence made by the 3205@code{define_expand}. Internal operands are substituted into the RTL 3206template with @code{match_dup}, never with @code{match_operand}. The 3207values of the internal operands are not passed in as arguments by the 3208compiler when it requests use of this pattern. Instead, they are computed 3209within the pattern, in the preparation statements. These statements 3210compute the values and store them into the appropriate elements of 3211@code{operands} so that @code{match_dup} can find them. 3212 3213There are two special macros defined for use in the preparation statements: 3214@code{DONE} and @code{FAIL}. Use them with a following semicolon, 3215as a statement. 3216 3217@table @code 3218 3219@findex DONE 3220@item DONE 3221Use the @code{DONE} macro to end RTL generation for the pattern. The 3222only RTL insns resulting from the pattern on this occasion will be 3223those already emitted by explicit calls to @code{emit_insn} within the 3224preparation statements; the RTL template will not be generated. 3225 3226@findex FAIL 3227@item FAIL 3228Make the pattern fail on this occasion. When a pattern fails, it means 3229that the pattern was not truly available. The calling routines in the 3230compiler will try other strategies for code generation using other patterns. 3231 3232Failure is currently supported only for binary (addition, multiplication, 3233shifting, etc.) and bitfield (@code{extv}, @code{extzv}, and @code{insv}) 3234operations. 3235@end table 3236 3237Here is an example, the definition of left-shift for the SPUR chip: 3238 3239@smallexample 3240@group 3241(define_expand "ashlsi3" 3242 [(set (match_operand:SI 0 "register_operand" "") 3243 (ashift:SI 3244@end group 3245@group 3246 (match_operand:SI 1 "register_operand" "") 3247 (match_operand:SI 2 "nonmemory_operand" "")))] 3248 "" 3249 " 3250@end group 3251@end smallexample 3252 3253@smallexample 3254@group 3255@{ 3256 if (GET_CODE (operands[2]) != CONST_INT 3257 || (unsigned) INTVAL (operands[2]) > 3) 3258 FAIL; 3259@}") 3260@end group 3261@end smallexample 3262 3263@noindent 3264This example uses @code{define_expand} so that it can generate an RTL insn 3265for shifting when the shift-count is in the supported range of 0 to 3 but 3266fail in other cases where machine insns aren't available. When it fails, 3267the compiler tries another strategy using different patterns (such as, a 3268library call). 3269 3270If the compiler were able to handle nontrivial condition-strings in 3271patterns with names, then it would be possible to use a 3272@code{define_insn} in that case. Here is another case (zero-extension 3273on the 68000) which makes more use of the power of @code{define_expand}: 3274 3275@smallexample 3276(define_expand "zero_extendhisi2" 3277 [(set (match_operand:SI 0 "general_operand" "") 3278 (const_int 0)) 3279 (set (strict_low_part 3280 (subreg:HI 3281 (match_dup 0) 3282 0)) 3283 (match_operand:HI 1 "general_operand" ""))] 3284 "" 3285 "operands[1] = make_safe_from (operands[1], operands[0]);") 3286@end smallexample 3287 3288@noindent 3289@findex make_safe_from 3290Here two RTL insns are generated, one to clear the entire output operand 3291and the other to copy the input operand into its low half. This sequence 3292is incorrect if the input operand refers to [the old value of] the output 3293operand, so the preparation statement makes sure this isn't so. The 3294function @code{make_safe_from} copies the @code{operands[1]} into a 3295temporary register if it refers to @code{operands[0]}. It does this 3296by emitting another RTL insn. 3297 3298Finally, a third example shows the use of an internal operand. 3299Zero-extension on the SPUR chip is done by @code{and}-ing the result 3300against a halfword mask. But this mask cannot be represented by a 3301@code{const_int} because the constant value is too large to be legitimate 3302on this machine. So it must be copied into a register with 3303@code{force_reg} and then the register used in the @code{and}. 3304 3305@smallexample 3306(define_expand "zero_extendhisi2" 3307 [(set (match_operand:SI 0 "register_operand" "") 3308 (and:SI (subreg:SI 3309 (match_operand:HI 1 "register_operand" "") 3310 0) 3311 (match_dup 2)))] 3312 "" 3313 "operands[2] 3314 = force_reg (SImode, GEN_INT (65535)); ") 3315@end smallexample 3316 3317@strong{Note:} If the @code{define_expand} is used to serve a 3318standard binary or unary arithmetic operation or a bitfield operation, 3319then the last insn it generates must not be a @code{code_label}, 3320@code{barrier} or @code{note}. It must be an @code{insn}, 3321@code{jump_insn} or @code{call_insn}. If you don't need a real insn 3322at the end, emit an insn to copy the result of the operation into 3323itself. Such an insn will generate no code, but it can avoid problems 3324in the compiler.@refill 3325 3326@node Insn Splitting 3327@section Defining How to Split Instructions 3328@cindex insn splitting 3329@cindex instruction splitting 3330@cindex splitting instructions 3331 3332There are two cases where you should specify how to split a pattern into 3333multiple insns. On machines that have instructions requiring delay 3334slots (@pxref{Delay Slots}) or that have instructions whose output is 3335not available for multiple cycles (@pxref{Function Units}), the compiler 3336phases that optimize these cases need to be able to move insns into 3337one-instruction delay slots. However, some insns may generate more than one 3338machine instruction. These insns cannot be placed into a delay slot. 3339 3340Often you can rewrite the single insn as a list of individual insns, 3341each corresponding to one machine instruction. The disadvantage of 3342doing so is that it will cause the compilation to be slower and require 3343more space. If the resulting insns are too complex, it may also 3344suppress some optimizations. The compiler splits the insn if there is a 3345reason to believe that it might improve instruction or delay slot 3346scheduling. 3347 3348The insn combiner phase also splits putative insns. If three insns are 3349merged into one insn with a complex expression that cannot be matched by 3350some @code{define_insn} pattern, the combiner phase attempts to split 3351the complex pattern into two insns that are recognized. Usually it can 3352break the complex pattern into two patterns by splitting out some 3353subexpression. However, in some other cases, such as performing an 3354addition of a large constant in two insns on a RISC machine, the way to 3355split the addition into two insns is machine-dependent. 3356 3357@cindex define_split 3358The @code{define_split} definition tells the compiler how to split a 3359complex insn into several simpler insns. It looks like this: 3360 3361@smallexample 3362(define_split 3363 [@var{insn-pattern}] 3364 "@var{condition}" 3365 [@var{new-insn-pattern-1} 3366 @var{new-insn-pattern-2} 3367 @dots{}] 3368 "@var{preparation statements}") 3369@end smallexample 3370 3371@var{insn-pattern} is a pattern that needs to be split and 3372@var{condition} is the final condition to be tested, as in a 3373@code{define_insn}. When an insn matching @var{insn-pattern} and 3374satisfying @var{condition} is found, it is replaced in the insn list 3375with the insns given by @var{new-insn-pattern-1}, 3376@var{new-insn-pattern-2}, etc. 3377 3378The @var{preparation statements} are similar to those statements that 3379are specified for @code{define_expand} (@pxref{Expander Definitions}) 3380and are executed before the new RTL is generated to prepare for the 3381generated code or emit some insns whose pattern is not fixed. Unlike 3382those in @code{define_expand}, however, these statements must not 3383generate any new pseudo-registers. Once reload has completed, they also 3384must not allocate any space in the stack frame. 3385 3386Patterns are matched against @var{insn-pattern} in two different 3387circumstances. If an insn needs to be split for delay slot scheduling 3388or insn scheduling, the insn is already known to be valid, which means 3389that it must have been matched by some @code{define_insn} and, if 3390@code{reload_completed} is non-zero, is known to satisfy the constraints 3391of that @code{define_insn}. In that case, the new insn patterns must 3392also be insns that are matched by some @code{define_insn} and, if 3393@code{reload_completed} is non-zero, must also satisfy the constraints 3394of those definitions. 3395 3396As an example of this usage of @code{define_split}, consider the following 3397example from @file{a29k.md}, which splits a @code{sign_extend} from 3398@code{HImode} to @code{SImode} into a pair of shift insns: 3399 3400@smallexample 3401(define_split 3402 [(set (match_operand:SI 0 "gen_reg_operand" "") 3403 (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))] 3404 "" 3405 [(set (match_dup 0) 3406 (ashift:SI (match_dup 1) 3407 (const_int 16))) 3408 (set (match_dup 0) 3409 (ashiftrt:SI (match_dup 0) 3410 (const_int 16)))] 3411 " 3412@{ operands[1] = gen_lowpart (SImode, operands[1]); @}") 3413@end smallexample 3414 3415When the combiner phase tries to split an insn pattern, it is always the 3416case that the pattern is @emph{not} matched by any @code{define_insn}. 3417The combiner pass first tries to split a single @code{set} expression 3418and then the same @code{set} expression inside a @code{parallel}, but 3419followed by a @code{clobber} of a pseudo-reg to use as a scratch 3420register. In these cases, the combiner expects exactly two new insn 3421patterns to be generated. It will verify that these patterns match some 3422@code{define_insn} definitions, so you need not do this test in the 3423@code{define_split} (of course, there is no point in writing a 3424@code{define_split} that will never produce insns that match). 3425 3426Here is an example of this use of @code{define_split}, taken from 3427@file{rs6000.md}: 3428 3429@smallexample 3430(define_split 3431 [(set (match_operand:SI 0 "gen_reg_operand" "") 3432 (plus:SI (match_operand:SI 1 "gen_reg_operand" "") 3433 (match_operand:SI 2 "non_add_cint_operand" "")))] 3434 "" 3435 [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3))) 3436 (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))] 3437" 3438@{ 3439 int low = INTVAL (operands[2]) & 0xffff; 3440 int high = (unsigned) INTVAL (operands[2]) >> 16; 3441 3442 if (low & 0x8000) 3443 high++, low |= 0xffff0000; 3444 3445 operands[3] = GEN_INT (high << 16); 3446 operands[4] = GEN_INT (low); 3447@}") 3448@end smallexample 3449 3450Here the predicate @code{non_add_cint_operand} matches any 3451@code{const_int} that is @emph{not} a valid operand of a single add 3452insn. The add with the smaller displacement is written so that it 3453can be substituted into the address of a subsequent operation. 3454 3455An example that uses a scratch register, from the same file, generates 3456an equality comparison of a register and a large constant: 3457 3458@smallexample 3459(define_split 3460 [(set (match_operand:CC 0 "cc_reg_operand" "") 3461 (compare:CC (match_operand:SI 1 "gen_reg_operand" "") 3462 (match_operand:SI 2 "non_short_cint_operand" ""))) 3463 (clobber (match_operand:SI 3 "gen_reg_operand" ""))] 3464 "find_single_use (operands[0], insn, 0) 3465 && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ 3466 || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)" 3467 [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4))) 3468 (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))] 3469 " 3470@{ 3471 /* Get the constant we are comparing against, C, and see what it 3472 looks like sign-extended to 16 bits. Then see what constant 3473 could be XOR'ed with C to get the sign-extended value. */ 3474 3475 int c = INTVAL (operands[2]); 3476 int sextc = (c << 16) >> 16; 3477 int xorv = c ^ sextc; 3478 3479 operands[4] = GEN_INT (xorv); 3480 operands[5] = GEN_INT (sextc); 3481@}") 3482@end smallexample 3483 3484To avoid confusion, don't write a single @code{define_split} that 3485accepts some insns that match some @code{define_insn} as well as some 3486insns that don't. Instead, write two separate @code{define_split} 3487definitions, one for the insns that are valid and one for the insns that 3488are not valid. 3489 3490@node Insn Attributes 3491@section Instruction Attributes 3492@cindex insn attributes 3493@cindex instruction attributes 3494 3495In addition to describing the instruction supported by the target machine, 3496the @file{md} file also defines a group of @dfn{attributes} and a set of 3497values for each. Every generated insn is assigned a value for each attribute. 3498One possible attribute would be the effect that the insn has on the machine's 3499condition code. This attribute can then be used by @code{NOTICE_UPDATE_CC} 3500to track the condition codes. 3501 3502@menu 3503* Defining Attributes:: Specifying attributes and their values. 3504* Expressions:: Valid expressions for attribute values. 3505* Tagging Insns:: Assigning attribute values to insns. 3506* Attr Example:: An example of assigning attributes. 3507* Insn Lengths:: Computing the length of insns. 3508* Constant Attributes:: Defining attributes that are constant. 3509* Delay Slots:: Defining delay slots required for a machine. 3510* Function Units:: Specifying information for insn scheduling. 3511@end menu 3512 3513@node Defining Attributes 3514@subsection Defining Attributes and their Values 3515@cindex defining attributes and their values 3516@cindex attributes, defining 3517 3518@findex define_attr 3519The @code{define_attr} expression is used to define each attribute required 3520by the target machine. It looks like: 3521 3522@smallexample 3523(define_attr @var{name} @var{list-of-values} @var{default}) 3524@end smallexample 3525 3526@var{name} is a string specifying the name of the attribute being defined. 3527 3528@var{list-of-values} is either a string that specifies a comma-separated 3529list of values that can be assigned to the attribute, or a null string to 3530indicate that the attribute takes numeric values. 3531 3532@var{default} is an attribute expression that gives the value of this 3533attribute for insns that match patterns whose definition does not include 3534an explicit value for this attribute. @xref{Attr Example}, for more 3535information on the handling of defaults. @xref{Constant Attributes}, 3536for information on attributes that do not depend on any particular insn. 3537 3538@findex insn-attr.h 3539For each defined attribute, a number of definitions are written to the 3540@file{insn-attr.h} file. For cases where an explicit set of values is 3541specified for an attribute, the following are defined: 3542 3543@itemize @bullet 3544@item 3545A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}. 3546 3547@item 3548An enumeral class is defined for @samp{attr_@var{name}} with 3549elements of the form @samp{@var{upper-name}_@var{upper-value}} where 3550the attribute name and value are first converted to upper case. 3551 3552@item 3553A function @samp{get_attr_@var{name}} is defined that is passed an insn and 3554returns the attribute value for that insn. 3555@end itemize 3556 3557For example, if the following is present in the @file{md} file: 3558 3559@smallexample 3560(define_attr "type" "branch,fp,load,store,arith" @dots{}) 3561@end smallexample 3562 3563@noindent 3564the following lines will be written to the file @file{insn-attr.h}. 3565 3566@smallexample 3567#define HAVE_ATTR_type 3568enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD, 3569 TYPE_STORE, TYPE_ARITH@}; 3570extern enum attr_type get_attr_type (); 3571@end smallexample 3572 3573If the attribute takes numeric values, no @code{enum} type will be 3574defined and the function to obtain the attribute's value will return 3575@code{int}. 3576 3577@node Expressions 3578@subsection Attribute Expressions 3579@cindex attribute expressions 3580 3581RTL expressions used to define attributes use the codes described above 3582plus a few specific to attribute definitions, to be discussed below. 3583Attribute value expressions must have one of the following forms: 3584 3585@table @code 3586@cindex @code{const_int} and attributes 3587@item (const_int @var{i}) 3588The integer @var{i} specifies the value of a numeric attribute. @var{i} 3589must be non-negative. 3590 3591The value of a numeric attribute can be specified either with a 3592@code{const_int}, or as an integer represented as a string in 3593@code{const_string}, @code{eq_attr} (see below), @code{attr}, 3594@code{symbol_ref}, simple arithmetic expressions, and @code{set_attr} 3595overrides on specific instructions (@pxref{Tagging Insns}). 3596 3597@cindex @code{const_string} and attributes 3598@item (const_string @var{value}) 3599The string @var{value} specifies a constant attribute value. 3600If @var{value} is specified as @samp{"*"}, it means that the default value of 3601the attribute is to be used for the insn containing this expression. 3602@samp{"*"} obviously cannot be used in the @var{default} expression 3603of a @code{define_attr}.@refill 3604 3605If the attribute whose value is being specified is numeric, @var{value} 3606must be a string containing a non-negative integer (normally 3607@code{const_int} would be used in this case). Otherwise, it must 3608contain one of the valid values for the attribute. 3609 3610@cindex @code{if_then_else} and attributes 3611@item (if_then_else @var{test} @var{true-value} @var{false-value}) 3612@var{test} specifies an attribute test, whose format is defined below. 3613The value of this expression is @var{true-value} if @var{test} is true, 3614otherwise it is @var{false-value}. 3615 3616@cindex @code{cond} and attributes 3617@item (cond [@var{test1} @var{value1} @dots{}] @var{default}) 3618The first operand of this expression is a vector containing an even 3619number of expressions and consisting of pairs of @var{test} and @var{value} 3620expressions. The value of the @code{cond} expression is that of the 3621@var{value} corresponding to the first true @var{test} expression. If 3622none of the @var{test} expressions are true, the value of the @code{cond} 3623expression is that of the @var{default} expression. 3624@end table 3625 3626@var{test} expressions can have one of the following forms: 3627 3628@table @code 3629@cindex @code{const_int} and attribute tests 3630@item (const_int @var{i}) 3631This test is true if @var{i} is non-zero and false otherwise. 3632 3633@cindex @code{not} and attributes 3634@cindex @code{ior} and attributes 3635@cindex @code{and} and attributes 3636@item (not @var{test}) 3637@itemx (ior @var{test1} @var{test2}) 3638@itemx (and @var{test1} @var{test2}) 3639These tests are true if the indicated logical function is true. 3640 3641@cindex @code{match_operand} and attributes 3642@item (match_operand:@var{m} @var{n} @var{pred} @var{constraints}) 3643This test is true if operand @var{n} of the insn whose attribute value 3644is being determined has mode @var{m} (this part of the test is ignored 3645if @var{m} is @code{VOIDmode}) and the function specified by the string 3646@var{pred} returns a non-zero value when passed operand @var{n} and mode 3647@var{m} (this part of the test is ignored if @var{pred} is the null 3648string). 3649 3650The @var{constraints} operand is ignored and should be the null string. 3651 3652@cindex @code{le} and attributes 3653@cindex @code{leu} and attributes 3654@cindex @code{lt} and attributes 3655@cindex @code{gt} and attributes 3656@cindex @code{gtu} and attributes 3657@cindex @code{ge} and attributes 3658@cindex @code{geu} and attributes 3659@cindex @code{ne} and attributes 3660@cindex @code{eq} and attributes 3661@cindex @code{plus} and attributes 3662@cindex @code{minus} and attributes 3663@cindex @code{mult} and attributes 3664@cindex @code{div} and attributes 3665@cindex @code{mod} and attributes 3666@cindex @code{abs} and attributes 3667@cindex @code{neg} and attributes 3668@cindex @code{ashift} and attributes 3669@cindex @code{lshiftrt} and attributes 3670@cindex @code{ashiftrt} and attributes 3671@item (le @var{arith1} @var{arith2}) 3672@itemx (leu @var{arith1} @var{arith2}) 3673@itemx (lt @var{arith1} @var{arith2}) 3674@itemx (ltu @var{arith1} @var{arith2}) 3675@itemx (gt @var{arith1} @var{arith2}) 3676@itemx (gtu @var{arith1} @var{arith2}) 3677@itemx (ge @var{arith1} @var{arith2}) 3678@itemx (geu @var{arith1} @var{arith2}) 3679@itemx (ne @var{arith1} @var{arith2}) 3680@itemx (eq @var{arith1} @var{arith2}) 3681These tests are true if the indicated comparison of the two arithmetic 3682expressions is true. Arithmetic expressions are formed with 3683@code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod}, 3684@code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not}, 3685@code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions.@refill 3686 3687@findex get_attr 3688@code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn 3689Lengths},for additional forms). @code{symbol_ref} is a string 3690denoting a C expression that yields an @code{int} when evaluated by the 3691@samp{get_attr_@dots{}} routine. It should normally be a global 3692variable.@refill 3693 3694@findex eq_attr 3695@item (eq_attr @var{name} @var{value}) 3696@var{name} is a string specifying the name of an attribute. 3697 3698@var{value} is a string that is either a valid value for attribute 3699@var{name}, a comma-separated list of values, or @samp{!} followed by a 3700value or list. If @var{value} does not begin with a @samp{!}, this 3701test is true if the value of the @var{name} attribute of the current 3702insn is in the list specified by @var{value}. If @var{value} begins 3703with a @samp{!}, this test is true if the attribute's value is 3704@emph{not} in the specified list. 3705 3706For example, 3707 3708@smallexample 3709(eq_attr "type" "load,store") 3710@end smallexample 3711 3712@noindent 3713is equivalent to 3714 3715@smallexample 3716(ior (eq_attr "type" "load") (eq_attr "type" "store")) 3717@end smallexample 3718 3719If @var{name} specifies an attribute of @samp{alternative}, it refers to the 3720value of the compiler variable @code{which_alternative} 3721(@pxref{Output Statement}) and the values must be small integers. For 3722example,@refill 3723 3724@smallexample 3725(eq_attr "alternative" "2,3") 3726@end smallexample 3727 3728@noindent 3729is equivalent to 3730 3731@smallexample 3732(ior (eq (symbol_ref "which_alternative") (const_int 2)) 3733 (eq (symbol_ref "which_alternative") (const_int 3))) 3734@end smallexample 3735 3736Note that, for most attributes, an @code{eq_attr} test is simplified in cases 3737where the value of the attribute being tested is known for all insns matching 3738a particular pattern. This is by far the most common case.@refill 3739 3740@findex attr_flag 3741@item (attr_flag @var{name}) 3742The value of an @code{attr_flag} expression is true if the flag 3743specified by @var{name} is true for the @code{insn} currently being 3744scheduled. 3745 3746@var{name} is a string specifying one of a fixed set of flags to test. 3747Test the flags @code{forward} and @code{backward} to determine the 3748direction of a conditional branch. Test the flags @code{very_likely}, 3749@code{likely}, @code{very_unlikely}, and @code{unlikely} to determine 3750if a conditional branch is expected to be taken. 3751 3752If the @code{very_likely} flag is true, then the @code{likely} flag is also 3753true. Likewise for the @code{very_unlikely} and @code{unlikely} flags. 3754 3755This example describes a conditional branch delay slot which 3756can be nullified for forward branches that are taken (annul-true) or 3757for backward branches which are not taken (annul-false). 3758 3759@smallexample 3760(define_delay (eq_attr "type" "cbranch") 3761 [(eq_attr "in_branch_delay" "true") 3762 (and (eq_attr "in_branch_delay" "true") 3763 (attr_flag "forward")) 3764 (and (eq_attr "in_branch_delay" "true") 3765 (attr_flag "backward"))]) 3766@end smallexample 3767 3768The @code{forward} and @code{backward} flags are false if the current 3769@code{insn} being scheduled is not a conditional branch. 3770 3771The @code{very_likely} and @code{likely} flags are true if the 3772@code{insn} being scheduled is not a conditional branch. 3773The @code{very_unlikely} and @code{unlikely} flags are false if the 3774@code{insn} being scheduled is not a conditional branch. 3775 3776@code{attr_flag} is only used during delay slot scheduling and has no 3777meaning to other passes of the compiler. 3778 3779@findex attr 3780@item (attr @var{name}) 3781The value of another attribute is returned. This is most useful 3782for numeric attributes, as @code{eq_attr} and @code{attr_flag} 3783produce more efficient code for non-numeric attributes. 3784@end table 3785 3786@node Tagging Insns 3787@subsection Assigning Attribute Values to Insns 3788@cindex tagging insns 3789@cindex assigning attribute values to insns 3790 3791The value assigned to an attribute of an insn is primarily determined by 3792which pattern is matched by that insn (or which @code{define_peephole} 3793generated it). Every @code{define_insn} and @code{define_peephole} can 3794have an optional last argument to specify the values of attributes for 3795matching insns. The value of any attribute not specified in a particular 3796insn is set to the default value for that attribute, as specified in its 3797@code{define_attr}. Extensive use of default values for attributes 3798permits the specification of the values for only one or two attributes 3799in the definition of most insn patterns, as seen in the example in the 3800next section.@refill 3801 3802The optional last argument of @code{define_insn} and 3803@code{define_peephole} is a vector of expressions, each of which defines 3804the value for a single attribute. The most general way of assigning an 3805attribute's value is to use a @code{set} expression whose first operand is an 3806@code{attr} expression giving the name of the attribute being set. The 3807second operand of the @code{set} is an attribute expression 3808(@pxref{Expressions}) giving the value of the attribute.@refill 3809 3810When the attribute value depends on the @samp{alternative} attribute 3811(i.e., which is the applicable alternative in the constraint of the 3812insn), the @code{set_attr_alternative} expression can be used. It 3813allows the specification of a vector of attribute expressions, one for 3814each alternative. 3815 3816@findex set_attr 3817When the generality of arbitrary attribute expressions is not required, 3818the simpler @code{set_attr} expression can be used, which allows 3819specifying a string giving either a single attribute value or a list 3820of attribute values, one for each alternative. 3821 3822The form of each of the above specifications is shown below. In each case, 3823@var{name} is a string specifying the attribute to be set. 3824 3825@table @code 3826@item (set_attr @var{name} @var{value-string}) 3827@var{value-string} is either a string giving the desired attribute value, 3828or a string containing a comma-separated list giving the values for 3829succeeding alternatives. The number of elements must match the number 3830of alternatives in the constraint of the insn pattern. 3831 3832Note that it may be useful to specify @samp{*} for some alternative, in 3833which case the attribute will assume its default value for insns matching 3834that alternative. 3835 3836@findex set_attr_alternative 3837@item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}]) 3838Depending on the alternative of the insn, the value will be one of the 3839specified values. This is a shorthand for using a @code{cond} with 3840tests on the @samp{alternative} attribute. 3841 3842@findex attr 3843@item (set (attr @var{name}) @var{value}) 3844The first operand of this @code{set} must be the special RTL expression 3845@code{attr}, whose sole operand is a string giving the name of the 3846attribute being set. @var{value} is the value of the attribute. 3847@end table 3848 3849The following shows three different ways of representing the same 3850attribute value specification: 3851 3852@smallexample 3853(set_attr "type" "load,store,arith") 3854 3855(set_attr_alternative "type" 3856 [(const_string "load") (const_string "store") 3857 (const_string "arith")]) 3858 3859(set (attr "type") 3860 (cond [(eq_attr "alternative" "1") (const_string "load") 3861 (eq_attr "alternative" "2") (const_string "store")] 3862 (const_string "arith"))) 3863@end smallexample 3864 3865@need 1000 3866@findex define_asm_attributes 3867The @code{define_asm_attributes} expression provides a mechanism to 3868specify the attributes assigned to insns produced from an @code{asm} 3869statement. It has the form: 3870 3871@smallexample 3872(define_asm_attributes [@var{attr-sets}]) 3873@end smallexample 3874 3875@noindent 3876where @var{attr-sets} is specified the same as for both the 3877@code{define_insn} and the @code{define_peephole} expressions. 3878 3879These values will typically be the ``worst case'' attribute values. For 3880example, they might indicate that the condition code will be clobbered. 3881 3882A specification for a @code{length} attribute is handled specially. The 3883way to compute the length of an @code{asm} insn is to multiply the 3884length specified in the expression @code{define_asm_attributes} by the 3885number of machine instructions specified in the @code{asm} statement, 3886determined by counting the number of semicolons and newlines in the 3887string. Therefore, the value of the @code{length} attribute specified 3888in a @code{define_asm_attributes} should be the maximum possible length 3889of a single machine instruction. 3890 3891@node Attr Example 3892@subsection Example of Attribute Specifications 3893@cindex attribute specifications example 3894@cindex attribute specifications 3895 3896The judicious use of defaulting is important in the efficient use of 3897insn attributes. Typically, insns are divided into @dfn{types} and an 3898attribute, customarily called @code{type}, is used to represent this 3899value. This attribute is normally used only to define the default value 3900for other attributes. An example will clarify this usage. 3901 3902Assume we have a RISC machine with a condition code and in which only 3903full-word operations are performed in registers. Let us assume that we 3904can divide all insns into loads, stores, (integer) arithmetic 3905operations, floating point operations, and branches. 3906 3907Here we will concern ourselves with determining the effect of an insn on 3908the condition code and will limit ourselves to the following possible 3909effects: The condition code can be set unpredictably (clobbered), not 3910be changed, be set to agree with the results of the operation, or only 3911changed if the item previously set into the condition code has been 3912modified. 3913 3914Here is part of a sample @file{md} file for such a machine: 3915 3916@smallexample 3917(define_attr "type" "load,store,arith,fp,branch" (const_string "arith")) 3918 3919(define_attr "cc" "clobber,unchanged,set,change0" 3920 (cond [(eq_attr "type" "load") 3921 (const_string "change0") 3922 (eq_attr "type" "store,branch") 3923 (const_string "unchanged") 3924 (eq_attr "type" "arith") 3925 (if_then_else (match_operand:SI 0 "" "") 3926 (const_string "set") 3927 (const_string "clobber"))] 3928 (const_string "clobber"))) 3929 3930(define_insn "" 3931 [(set (match_operand:SI 0 "general_operand" "=r,r,m") 3932 (match_operand:SI 1 "general_operand" "r,m,r"))] 3933 "" 3934 "@@ 3935 move %0,%1 3936 load %0,%1 3937 store %0,%1" 3938 [(set_attr "type" "arith,load,store")]) 3939@end smallexample 3940 3941Note that we assume in the above example that arithmetic operations 3942performed on quantities smaller than a machine word clobber the condition 3943code since they will set the condition code to a value corresponding to the 3944full-word result. 3945 3946@node Insn Lengths 3947@subsection Computing the Length of an Insn 3948@cindex insn lengths, computing 3949@cindex computing the length of an insn 3950 3951For many machines, multiple types of branch instructions are provided, each 3952for different length branch displacements. In most cases, the assembler 3953will choose the correct instruction to use. However, when the assembler 3954cannot do so, GCC can when a special attribute, the @samp{length} 3955attribute, is defined. This attribute must be defined to have numeric 3956values by specifying a null string in its @code{define_attr}. 3957 3958In the case of the @samp{length} attribute, two additional forms of 3959arithmetic terms are allowed in test expressions: 3960 3961@table @code 3962@cindex @code{match_dup} and attributes 3963@item (match_dup @var{n}) 3964This refers to the address of operand @var{n} of the current insn, which 3965must be a @code{label_ref}. 3966 3967@cindex @code{pc} and attributes 3968@item (pc) 3969This refers to the address of the @emph{current} insn. It might have 3970been more consistent with other usage to make this the address of the 3971@emph{next} insn but this would be confusing because the length of the 3972current insn is to be computed. 3973@end table 3974 3975@cindex @code{addr_vec}, length of 3976@cindex @code{addr_diff_vec}, length of 3977For normal insns, the length will be determined by value of the 3978@samp{length} attribute. In the case of @code{addr_vec} and 3979@code{addr_diff_vec} insn patterns, the length is computed as 3980the number of vectors multiplied by the size of each vector. 3981 3982Lengths are measured in addressable storage units (bytes). 3983 3984The following macros can be used to refine the length computation: 3985 3986@table @code 3987@findex FIRST_INSN_ADDRESS 3988@item FIRST_INSN_ADDRESS 3989When the @code{length} insn attribute is used, this macro specifies the 3990value to be assigned to the address of the first insn in a function. If 3991not specified, 0 is used. 3992 3993@findex ADJUST_INSN_LENGTH 3994@item ADJUST_INSN_LENGTH (@var{insn}, @var{length}) 3995If defined, modifies the length assigned to instruction @var{insn} as a 3996function of the context in which it is used. @var{length} is an lvalue 3997that contains the initially computed length of the insn and should be 3998updated with the correct length of the insn. 3999 4000This macro will normally not be required. A case in which it is 4001required is the ROMP. On this machine, the size of an @code{addr_vec} 4002insn must be increased by two to compensate for the fact that alignment 4003may be required. 4004@end table 4005 4006@findex get_attr_length 4007The routine that returns @code{get_attr_length} (the value of the 4008@code{length} attribute) can be used by the output routine to 4009determine the form of the branch instruction to be written, as the 4010example below illustrates. 4011 4012As an example of the specification of variable-length branches, consider 4013the IBM 360. If we adopt the convention that a register will be set to 4014the starting address of a function, we can jump to labels within 4k of 4015the start using a four-byte instruction. Otherwise, we need a six-byte 4016sequence to load the address from memory and then branch to it. 4017 4018On such a machine, a pattern for a branch instruction might be specified 4019as follows: 4020 4021@smallexample 4022(define_insn "jump" 4023 [(set (pc) 4024 (label_ref (match_operand 0 "" "")))] 4025 "" 4026 "* 4027@{ 4028 return (get_attr_length (insn) == 4 4029 ? \"b %l0\" : \"l r15,=a(%l0); br r15\"); 4030@}" 4031 [(set (attr "length") (if_then_else (lt (match_dup 0) (const_int 4096)) 4032 (const_int 4) 4033 (const_int 6)))]) 4034@end smallexample 4035 4036@node Constant Attributes 4037@subsection Constant Attributes 4038@cindex constant attributes 4039 4040A special form of @code{define_attr}, where the expression for the 4041default value is a @code{const} expression, indicates an attribute that 4042is constant for a given run of the compiler. Constant attributes may be 4043used to specify which variety of processor is used. For example, 4044 4045@smallexample 4046(define_attr "cpu" "m88100,m88110,m88000" 4047 (const 4048 (cond [(symbol_ref "TARGET_88100") (const_string "m88100") 4049 (symbol_ref "TARGET_88110") (const_string "m88110")] 4050 (const_string "m88000")))) 4051 4052(define_attr "memory" "fast,slow" 4053 (const 4054 (if_then_else (symbol_ref "TARGET_FAST_MEM") 4055 (const_string "fast") 4056 (const_string "slow")))) 4057@end smallexample 4058 4059The routine generated for constant attributes has no parameters as it 4060does not depend on any particular insn. RTL expressions used to define 4061the value of a constant attribute may use the @code{symbol_ref} form, 4062but may not use either the @code{match_operand} form or @code{eq_attr} 4063forms involving insn attributes. 4064 4065@node Delay Slots 4066@subsection Delay Slot Scheduling 4067@cindex delay slots, defining 4068 4069The insn attribute mechanism can be used to specify the requirements for 4070delay slots, if any, on a target machine. An instruction is said to 4071require a @dfn{delay slot} if some instructions that are physically 4072after the instruction are executed as if they were located before it. 4073Classic examples are branch and call instructions, which often execute 4074the following instruction before the branch or call is performed. 4075 4076On some machines, conditional branch instructions can optionally 4077@dfn{annul} instructions in the delay slot. This means that the 4078instruction will not be executed for certain branch outcomes. Both 4079instructions that annul if the branch is true and instructions that 4080annul if the branch is false are supported. 4081 4082Delay slot scheduling differs from instruction scheduling in that 4083determining whether an instruction needs a delay slot is dependent only 4084on the type of instruction being generated, not on data flow between the 4085instructions. See the next section for a discussion of data-dependent 4086instruction scheduling. 4087 4088@findex define_delay 4089The requirement of an insn needing one or more delay slots is indicated 4090via the @code{define_delay} expression. It has the following form: 4091 4092@smallexample 4093(define_delay @var{test} 4094 [@var{delay-1} @var{annul-true-1} @var{annul-false-1} 4095 @var{delay-2} @var{annul-true-2} @var{annul-false-2} 4096 @dots{}]) 4097@end smallexample 4098 4099@var{test} is an attribute test that indicates whether this 4100@code{define_delay} applies to a particular insn. If so, the number of 4101required delay slots is determined by the length of the vector specified 4102as the second argument. An insn placed in delay slot @var{n} must 4103satisfy attribute test @var{delay-n}. @var{annul-true-n} is an 4104attribute test that specifies which insns may be annulled if the branch 4105is true. Similarly, @var{annul-false-n} specifies which insns in the 4106delay slot may be annulled if the branch is false. If annulling is not 4107supported for that delay slot, @code{(nil)} should be coded.@refill 4108 4109For example, in the common case where branch and call insns require 4110a single delay slot, which may contain any insn other than a branch or 4111call, the following would be placed in the @file{md} file: 4112 4113@smallexample 4114(define_delay (eq_attr "type" "branch,call") 4115 [(eq_attr "type" "!branch,call") (nil) (nil)]) 4116@end smallexample 4117 4118Multiple @code{define_delay} expressions may be specified. In this 4119case, each such expression specifies different delay slot requirements 4120and there must be no insn for which tests in two @code{define_delay} 4121expressions are both true. 4122 4123For example, if we have a machine that requires one delay slot for branches 4124but two for calls, no delay slot can contain a branch or call insn, 4125and any valid insn in the delay slot for the branch can be annulled if the 4126branch is true, we might represent this as follows: 4127 4128@smallexample 4129(define_delay (eq_attr "type" "branch") 4130 [(eq_attr "type" "!branch,call") 4131 (eq_attr "type" "!branch,call") 4132 (nil)]) 4133 4134(define_delay (eq_attr "type" "call") 4135 [(eq_attr "type" "!branch,call") (nil) (nil) 4136 (eq_attr "type" "!branch,call") (nil) (nil)]) 4137@end smallexample 4138@c the above is *still* too long. --mew 4feb93 4139 4140@node Function Units 4141@subsection Specifying Function Units 4142@cindex function units, for scheduling 4143 4144On most RISC machines, there are instructions whose results are not 4145available for a specific number of cycles. Common cases are instructions 4146that load data from memory. On many machines, a pipeline stall will result 4147if the data is referenced too soon after the load instruction. 4148 4149In addition, many newer microprocessors have multiple function units, usually 4150one for integer and one for floating point, and often will incur pipeline 4151stalls when a result that is needed is not yet ready. 4152 4153The descriptions in this section allow the specification of how much 4154time must elapse between the execution of an instruction and the time 4155when its result is used. It also allows specification of when the 4156execution of an instruction will delay execution of similar instructions 4157due to function unit conflicts. 4158 4159For the purposes of the specifications in this section, a machine is 4160divided into @dfn{function units}, each of which execute a specific 4161class of instructions in first-in-first-out order. Function units that 4162accept one instruction each cycle and allow a result to be used in the 4163succeeding instruction (usually via forwarding) need not be specified. 4164Classic RISC microprocessors will normally have a single function unit, 4165which we can call @samp{memory}. The newer ``superscalar'' processors 4166will often have function units for floating point operations, usually at 4167least a floating point adder and multiplier. 4168 4169@findex define_function_unit 4170Each usage of a function units by a class of insns is specified with a 4171@code{define_function_unit} expression, which looks like this: 4172 4173@smallexample 4174(define_function_unit @var{name} @var{multiplicity} @var{simultaneity} 4175 @var{test} @var{ready-delay} @var{issue-delay} 4176 [@var{conflict-list}]) 4177@end smallexample 4178 4179@var{name} is a string giving the name of the function unit. 4180 4181@var{multiplicity} is an integer specifying the number of identical 4182units in the processor. If more than one unit is specified, they will 4183be scheduled independently. Only truly independent units should be 4184counted; a pipelined unit should be specified as a single unit. (The 4185only common example of a machine that has multiple function units for a 4186single instruction class that are truly independent and not pipelined 4187are the two multiply and two increment units of the CDC 6600.) 4188 4189@var{simultaneity} specifies the maximum number of insns that can be 4190executing in each instance of the function unit simultaneously or zero 4191if the unit is pipelined and has no limit. 4192 4193All @code{define_function_unit} definitions referring to function unit 4194@var{name} must have the same name and values for @var{multiplicity} and 4195@var{simultaneity}. 4196 4197@var{test} is an attribute test that selects the insns we are describing 4198in this definition. Note that an insn may use more than one function 4199unit and a function unit may be specified in more than one 4200@code{define_function_unit}. 4201 4202@var{ready-delay} is an integer that specifies the number of cycles 4203after which the result of the instruction can be used without 4204introducing any stalls. 4205 4206@var{issue-delay} is an integer that specifies the number of cycles 4207after the instruction matching the @var{test} expression begins using 4208this unit until a subsequent instruction can begin. A cost of @var{N} 4209indicates an @var{N-1} cycle delay. A subsequent instruction may also 4210be delayed if an earlier instruction has a longer @var{ready-delay} 4211value. This blocking effect is computed using the @var{simultaneity}, 4212@var{ready-delay}, @var{issue-delay}, and @var{conflict-list} terms. 4213For a normal non-pipelined function unit, @var{simultaneity} is one, the 4214unit is taken to block for the @var{ready-delay} cycles of the executing 4215insn, and smaller values of @var{issue-delay} are ignored. 4216 4217@var{conflict-list} is an optional list giving detailed conflict costs 4218for this unit. If specified, it is a list of condition test expressions 4219to be applied to insns chosen to execute in @var{name} following the 4220particular insn matching @var{test} that is already executing in 4221@var{name}. For each insn in the list, @var{issue-delay} specifies the 4222conflict cost; for insns not in the list, the cost is zero. If not 4223specified, @var{conflict-list} defaults to all instructions that use the 4224function unit. 4225 4226Typical uses of this vector are where a floating point function unit can 4227pipeline either single- or double-precision operations, but not both, or 4228where a memory unit can pipeline loads, but not stores, etc. 4229 4230As an example, consider a classic RISC machine where the result of a 4231load instruction is not available for two cycles (a single ``delay'' 4232instruction is required) and where only one load instruction can be executed 4233simultaneously. This would be specified as: 4234 4235@smallexample 4236(define_function_unit "memory" 1 1 (eq_attr "type" "load") 2 0) 4237@end smallexample 4238 4239For the case of a floating point function unit that can pipeline either 4240single or double precision, but not both, the following could be specified: 4241 4242@smallexample 4243(define_function_unit 4244 "fp" 1 0 (eq_attr "type" "sp_fp") 4 4 [(eq_attr "type" "dp_fp")]) 4245(define_function_unit 4246 "fp" 1 0 (eq_attr "type" "dp_fp") 4 4 [(eq_attr "type" "sp_fp")]) 4247@end smallexample 4248 4249@strong{Note:} The scheduler attempts to avoid function unit conflicts 4250and uses all the specifications in the @code{define_function_unit} 4251expression. It has recently come to our attention that these 4252specifications may not allow modeling of some of the newer 4253``superscalar'' processors that have insns using multiple pipelined 4254units. These insns will cause a potential conflict for the second unit 4255used during their execution and there is no way of representing that 4256conflict. We welcome any examples of how function unit conflicts work 4257in such processors and suggestions for their representation. 4258@end ifset 4259