rtl.texi revision 132718
1@c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 2@c Free Software Foundation, Inc. 3@c This is part of the GCC manual. 4@c For copying conditions, see the file gcc.texi. 5 6@node RTL 7@chapter RTL Representation 8@cindex RTL representation 9@cindex representation of RTL 10@cindex Register Transfer Language (RTL) 11 12Most of the work of the compiler is done on an intermediate representation 13called register transfer language. In this language, the instructions to be 14output are described, pretty much one by one, in an algebraic form that 15describes what the instruction does. 16 17RTL is inspired by Lisp lists. It has both an internal form, made up of 18structures that point at other structures, and a textual form that is used 19in the machine description and in printed debugging dumps. The textual 20form uses nested parentheses to indicate the pointers in the internal form. 21 22@menu 23* RTL Objects:: Expressions vs vectors vs strings vs integers. 24* RTL Classes:: Categories of RTL expression objects, and their structure. 25* Accessors:: Macros to access expression operands or vector elts. 26* Special Accessors:: Macros to access specific annotations on RTL. 27* Flags:: Other flags in an RTL expression. 28* Machine Modes:: Describing the size and format of a datum. 29* Constants:: Expressions with constant values. 30* Regs and Memory:: Expressions representing register contents or memory. 31* Arithmetic:: Expressions representing arithmetic on other expressions. 32* Comparisons:: Expressions representing comparison of expressions. 33* Bit-Fields:: Expressions representing bit-fields in memory or reg. 34* Vector Operations:: Expressions involving vector datatypes. 35* Conversions:: Extending, truncating, floating or fixing. 36* RTL Declarations:: Declaring volatility, constancy, etc. 37* Side Effects:: Expressions for storing in registers, etc. 38* Incdec:: Embedded side-effects for autoincrement addressing. 39* Assembler:: Representing @code{asm} with operands. 40* Insns:: Expression types for entire insns. 41* Calls:: RTL representation of function call insns. 42* Sharing:: Some expressions are unique; others *must* be copied. 43* Reading RTL:: Reading textual RTL from a file. 44@end menu 45 46@node RTL Objects 47@section RTL Object Types 48@cindex RTL object types 49 50@cindex RTL integers 51@cindex RTL strings 52@cindex RTL vectors 53@cindex RTL expression 54@cindex RTX (See RTL) 55RTL uses five kinds of objects: expressions, integers, wide integers, 56strings and vectors. Expressions are the most important ones. An RTL 57expression (``RTX'', for short) is a C structure, but it is usually 58referred to with a pointer; a type that is given the typedef name 59@code{rtx}. 60 61An integer is simply an @code{int}; their written form uses decimal 62digits. A wide integer is an integral object whose type is 63@code{HOST_WIDE_INT}; their written form uses decimal digits. 64 65A string is a sequence of characters. In core it is represented as a 66@code{char *} in usual C fashion, and it is written in C syntax as well. 67However, strings in RTL may never be null. If you write an empty string in 68a machine description, it is represented in core as a null pointer rather 69than as a pointer to a null character. In certain contexts, these null 70pointers instead of strings are valid. Within RTL code, strings are most 71commonly found inside @code{symbol_ref} expressions, but they appear in 72other contexts in the RTL expressions that make up machine descriptions. 73 74In a machine description, strings are normally written with double 75quotes, as you would in C. However, strings in machine descriptions may 76extend over many lines, which is invalid C, and adjacent string 77constants are not concatenated as they are in C. Any string constant 78may be surrounded with a single set of parentheses. Sometimes this 79makes the machine description easier to read. 80 81There is also a special syntax for strings, which can be useful when C 82code is embedded in a machine description. Wherever a string can 83appear, it is also valid to write a C-style brace block. The entire 84brace block, including the outermost pair of braces, is considered to be 85the string constant. Double quote characters inside the braces are not 86special. Therefore, if you write string constants in the C code, you 87need not escape each quote character with a backslash. 88 89A vector contains an arbitrary number of pointers to expressions. The 90number of elements in the vector is explicitly present in the vector. 91The written form of a vector consists of square brackets 92(@samp{[@dots{}]}) surrounding the elements, in sequence and with 93whitespace separating them. Vectors of length zero are not created; 94null pointers are used instead. 95 96@cindex expression codes 97@cindex codes, RTL expression 98@findex GET_CODE 99@findex PUT_CODE 100Expressions are classified by @dfn{expression codes} (also called RTX 101codes). The expression code is a name defined in @file{rtl.def}, which is 102also (in uppercase) a C enumeration constant. The possible expression 103codes and their meanings are machine-independent. The code of an RTX can 104be extracted with the macro @code{GET_CODE (@var{x})} and altered with 105@code{PUT_CODE (@var{x}, @var{newcode})}. 106 107The expression code determines how many operands the expression contains, 108and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell 109by looking at an operand what kind of object it is. Instead, you must know 110from its context---from the expression code of the containing expression. 111For example, in an expression of code @code{subreg}, the first operand is 112to be regarded as an expression and the second operand as an integer. In 113an expression of code @code{plus}, there are two operands, both of which 114are to be regarded as expressions. In a @code{symbol_ref} expression, 115there is one operand, which is to be regarded as a string. 116 117Expressions are written as parentheses containing the name of the 118expression type, its flags and machine mode if any, and then the operands 119of the expression (separated by spaces). 120 121Expression code names in the @samp{md} file are written in lowercase, 122but when they appear in C code they are written in uppercase. In this 123manual, they are shown as follows: @code{const_int}. 124 125@cindex (nil) 126@cindex nil 127In a few contexts a null pointer is valid where an expression is normally 128wanted. The written form of this is @code{(nil)}. 129 130@node RTL Classes 131@section RTL Classes and Formats 132@cindex RTL classes 133@cindex classes of RTX codes 134@cindex RTX codes, classes of 135@findex GET_RTX_CLASS 136 137The various expression codes are divided into several @dfn{classes}, 138which are represented by single characters. You can determine the class 139of an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}. 140Currently, @file{rtx.def} defines these classes: 141 142@table @code 143@item o 144An RTX code that represents an actual object, such as a register 145(@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}). 146Constants and basic transforms on objects (@code{ADDRESSOF}, 147@code{HIGH}, @code{LO_SUM}) are also included. Note that @code{SUBREG} 148and @code{STRICT_LOW_PART} are not in this class, but in class @code{x}. 149 150@item < 151An RTX code for a comparison, such as @code{NE} or @code{LT}. 152 153@item 1 154An RTX code for a unary arithmetic operation, such as @code{NEG}, 155@code{NOT}, or @code{ABS}. This category also includes value extension 156(sign or zero) and conversions between integer and floating point. 157 158@item c 159An RTX code for a commutative binary operation, such as @code{PLUS} or 160@code{AND}. @code{NE} and @code{EQ} are comparisons, so they have class 161@code{<}. 162 163@item 2 164An RTX code for a non-commutative binary operation, such as @code{MINUS}, 165@code{DIV}, or @code{ASHIFTRT}. 166 167@item b 168An RTX code for a bit-field operation. Currently only 169@code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}. These have three inputs 170and are lvalues (so they can be used for insertion as well). 171@xref{Bit-Fields}. 172 173@item 3 174An RTX code for other three input operations. Currently only 175@code{IF_THEN_ELSE}. 176 177@item i 178An RTX code for an entire instruction: @code{INSN}, @code{JUMP_INSN}, and 179@code{CALL_INSN}. @xref{Insns}. 180 181@item m 182An RTX code for something that matches in insns, such as 183@code{MATCH_DUP}. These only occur in machine descriptions. 184 185@item a 186An RTX code for an auto-increment addressing mode, such as 187@code{POST_INC}. 188 189@item x 190All other RTX codes. This category includes the remaining codes used 191only in machine descriptions (@code{DEFINE_*}, etc.). It also includes 192all the codes describing side effects (@code{SET}, @code{USE}, 193@code{CLOBBER}, etc.) and the non-insns that may appear on an insn 194chain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}. 195@end table 196 197@cindex RTL format 198For each expression code, @file{rtl.def} specifies the number of 199contained objects and their kinds using a sequence of characters 200called the @dfn{format} of the expression code. For example, 201the format of @code{subreg} is @samp{ei}. 202 203@cindex RTL format characters 204These are the most commonly used format characters: 205 206@table @code 207@item e 208An expression (actually a pointer to an expression). 209 210@item i 211An integer. 212 213@item w 214A wide integer. 215 216@item s 217A string. 218 219@item E 220A vector of expressions. 221@end table 222 223A few other format characters are used occasionally: 224 225@table @code 226@item u 227@samp{u} is equivalent to @samp{e} except that it is printed differently 228in debugging dumps. It is used for pointers to insns. 229 230@item n 231@samp{n} is equivalent to @samp{i} except that it is printed differently 232in debugging dumps. It is used for the line number or code number of a 233@code{note} insn. 234 235@item S 236@samp{S} indicates a string which is optional. In the RTL objects in 237core, @samp{S} is equivalent to @samp{s}, but when the object is read, 238from an @samp{md} file, the string value of this operand may be omitted. 239An omitted string is taken to be the null string. 240 241@item V 242@samp{V} indicates a vector which is optional. In the RTL objects in 243core, @samp{V} is equivalent to @samp{E}, but when the object is read 244from an @samp{md} file, the vector value of this operand may be omitted. 245An omitted vector is effectively the same as a vector of no elements. 246 247@item B 248@samp{B} indicates a pointer to basic block structure. 249 250@item 0 251@samp{0} means a slot whose contents do not fit any normal category. 252@samp{0} slots are not printed at all in dumps, and are often used in 253special ways by small parts of the compiler. 254@end table 255 256There are macros to get the number of operands and the format 257of an expression code: 258 259@table @code 260@findex GET_RTX_LENGTH 261@item GET_RTX_LENGTH (@var{code}) 262Number of operands of an RTX of code @var{code}. 263 264@findex GET_RTX_FORMAT 265@item GET_RTX_FORMAT (@var{code}) 266The format of an RTX of code @var{code}, as a C string. 267@end table 268 269Some classes of RTX codes always have the same format. For example, it 270is safe to assume that all comparison operations have format @code{ee}. 271 272@table @code 273@item 1 274All codes of this class have format @code{e}. 275 276@item < 277@itemx c 278@itemx 2 279All codes of these classes have format @code{ee}. 280 281@item b 282@itemx 3 283All codes of these classes have format @code{eee}. 284 285@item i 286All codes of this class have formats that begin with @code{iuueiee}. 287@xref{Insns}. Note that not all RTL objects linked onto an insn chain 288are of class @code{i}. 289 290@item o 291@itemx m 292@itemx x 293You can make no assumptions about the format of these codes. 294@end table 295 296@node Accessors 297@section Access to Operands 298@cindex accessors 299@cindex access to operands 300@cindex operand access 301 302@findex XEXP 303@findex XINT 304@findex XWINT 305@findex XSTR 306Operands of expressions are accessed using the macros @code{XEXP}, 307@code{XINT}, @code{XWINT} and @code{XSTR}. Each of these macros takes 308two arguments: an expression-pointer (RTX) and an operand number 309(counting from zero). Thus, 310 311@smallexample 312XEXP (@var{x}, 2) 313@end smallexample 314 315@noindent 316accesses operand 2 of expression @var{x}, as an expression. 317 318@smallexample 319XINT (@var{x}, 2) 320@end smallexample 321 322@noindent 323accesses the same operand as an integer. @code{XSTR}, used in the same 324fashion, would access it as a string. 325 326Any operand can be accessed as an integer, as an expression or as a string. 327You must choose the correct method of access for the kind of value actually 328stored in the operand. You would do this based on the expression code of 329the containing expression. That is also how you would know how many 330operands there are. 331 332For example, if @var{x} is a @code{subreg} expression, you know that it has 333two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)} 334and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you 335would get the address of the expression operand but cast as an integer; 336that might occasionally be useful, but it would be cleaner to write 337@code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also 338compile without error, and would return the second, integer operand cast as 339an expression pointer, which would probably result in a crash when 340accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either, 341but this will access memory past the end of the expression with 342unpredictable results. 343 344Access to operands which are vectors is more complicated. You can use the 345macro @code{XVEC} to get the vector-pointer itself, or the macros 346@code{XVECEXP} and @code{XVECLEN} to access the elements and length of a 347vector. 348 349@table @code 350@findex XVEC 351@item XVEC (@var{exp}, @var{idx}) 352Access the vector-pointer which is operand number @var{idx} in @var{exp}. 353 354@findex XVECLEN 355@item XVECLEN (@var{exp}, @var{idx}) 356Access the length (number of elements) in the vector which is 357in operand number @var{idx} in @var{exp}. This value is an @code{int}. 358 359@findex XVECEXP 360@item XVECEXP (@var{exp}, @var{idx}, @var{eltnum}) 361Access element number @var{eltnum} in the vector which is 362in operand number @var{idx} in @var{exp}. This value is an RTX@. 363 364It is up to you to make sure that @var{eltnum} is not negative 365and is less than @code{XVECLEN (@var{exp}, @var{idx})}. 366@end table 367 368All the macros defined in this section expand into lvalues and therefore 369can be used to assign the operands, lengths and vector elements as well as 370to access them. 371 372@node Special Accessors 373@section Access to Special Operands 374@cindex access to special operands 375 376Some RTL nodes have special annotations associated with them. 377 378@table @code 379@item MEM 380@table @code 381@findex MEM_ALIAS_SET 382@item MEM_ALIAS_SET (@var{x}) 383If 0, @var{x} is not in any alias set, and may alias anything. Otherwise, 384@var{x} can only alias @code{MEM}s in a conflicting alias set. This value 385is set in a language-dependent manner in the front-end, and should not be 386altered in the back-end. In some front-ends, these numbers may correspond 387in some way to types, or other language-level entities, but they need not, 388and the back-end makes no such assumptions. 389These set numbers are tested with @code{alias_sets_conflict_p}. 390 391@findex MEM_EXPR 392@item MEM_EXPR (@var{x}) 393If this register is known to hold the value of some user-level 394declaration, this is that tree node. It may also be a 395@code{COMPONENT_REF}, in which case this is some field reference, 396and @code{TREE_OPERAND (@var{x}, 0)} contains the declaration, 397or another @code{COMPONENT_REF}, or null if there is no compile-time 398object associated with the reference. 399 400@findex MEM_OFFSET 401@item MEM_OFFSET (@var{x}) 402The offset from the start of @code{MEM_EXPR} as a @code{CONST_INT} rtx. 403 404@findex MEM_SIZE 405@item MEM_SIZE (@var{x}) 406The size in bytes of the memory reference as a @code{CONST_INT} rtx. 407This is mostly relevant for @code{BLKmode} references as otherwise 408the size is implied by the mode. 409 410@findex MEM_ALIGN 411@item MEM_ALIGN (@var{x}) 412The known alignment in bits of the memory reference. 413@end table 414 415@item REG 416@table @code 417@findex ORIGINAL_REGNO 418@item ORIGINAL_REGNO (@var{x}) 419This field holds the number the register ``originally'' had; for a 420pseudo register turned into a hard reg this will hold the old pseudo 421register number. 422 423@findex REG_EXPR 424@item REG_EXPR (@var{x}) 425If this register is known to hold the value of some user-level 426declaration, this is that tree node. 427 428@findex REG_OFFSET 429@item REG_OFFSET (@var{x}) 430If this register is known to hold the value of some user-level 431declaration, this is the offset into that logical storage. 432@end table 433 434@item SYMBOL_REF 435@table @code 436@findex SYMBOL_REF_DECL 437@item SYMBOL_REF_DECL (@var{x}) 438If the @code{symbol_ref} @var{x} was created for a @code{VAR_DECL} or 439a @code{FUNCTION_DECL}, that tree is recorded here. If this value is 440null, then @var{x} was created by back end code generation routines, 441and there is no associated front end symbol table entry. 442 443@code{SYMBOL_REF_DECL} may also point to a tree of class @code{'c'}, 444that is, some sort of constant. In this case, the @code{symbol_ref} 445is an entry in the per-file constant pool; again, there is no associated 446front end symbol table entry. 447 448@findex SYMBOL_REF_FLAGS 449@item SYMBOL_REF_FLAGS (@var{x}) 450In a @code{symbol_ref}, this is used to communicate various predicates 451about the symbol. Some of these are common enough to be computed by 452common code, some are specific to the target. The common bits are: 453 454@table @code 455@findex SYMBOL_REF_FUNCTION_P 456@findex SYMBOL_FLAG_FUNCTION 457@item SYMBOL_FLAG_FUNCTION 458Set if the symbol refers to a function. 459 460@findex SYMBOL_REF_LOCAL_P 461@findex SYMBOL_FLAG_LOCAL 462@item SYMBOL_FLAG_LOCAL 463Set if the symbol is local to this ``module''. 464See @code{TARGET_BINDS_LOCAL_P}. 465 466@findex SYMBOL_REF_EXTERNAL_P 467@findex SYMBOL_FLAG_EXTERNAL 468@item SYMBOL_FLAG_EXTERNAL 469Set if this symbol is not defined in this translation unit. 470Note that this is not the inverse of @code{SYMBOL_FLAG_LOCAL}. 471 472@findex SYMBOL_REF_SMALL_P 473@findex SYMBOL_FLAG_SMALL 474@item SYMBOL_FLAG_SMALL 475Set if the symbol is located in the small data section. 476See @code{TARGET_IN_SMALL_DATA_P}. 477 478@findex SYMBOL_FLAG_TLS_SHIFT 479@findex SYMBOL_REF_TLS_MODEL 480@item SYMBOL_REF_TLS_MODEL (@var{x}) 481This is a multi-bit field accessor that returns the @code{tls_model} 482to be used for a thread-local storage symbol. It returns zero for 483non-thread-local symbols. 484@end table 485 486Bits beginning with @code{SYMBOL_FLAG_MACH_DEP} are available for 487the target's use. 488@end table 489@end table 490 491@node Flags 492@section Flags in an RTL Expression 493@cindex flags in RTL expression 494 495RTL expressions contain several flags (one-bit bit-fields) 496that are used in certain types of expression. Most often they 497are accessed with the following macros, which expand into lvalues. 498 499@table @code 500@findex CONSTANT_POOL_ADDRESS_P 501@cindex @code{symbol_ref} and @samp{/u} 502@cindex @code{unchanging}, in @code{symbol_ref} 503@item CONSTANT_POOL_ADDRESS_P (@var{x}) 504Nonzero in a @code{symbol_ref} if it refers to part of the current 505function's constant pool. For most targets these addresses are in a 506@code{.rodata} section entirely separate from the function, but for 507some targets the addresses are close to the beginning of the function. 508In either case GCC assumes these addresses can be addressed directly, 509perhaps with the help of base registers. 510Stored in the @code{unchanging} field and printed as @samp{/u}. 511 512@findex CONST_OR_PURE_CALL_P 513@cindex @code{call_insn} and @samp{/u} 514@cindex @code{unchanging}, in @code{call_insn} 515@item CONST_OR_PURE_CALL_P (@var{x}) 516In a @code{call_insn}, @code{note}, or an @code{expr_list} for notes, 517indicates that the insn represents a call to a const or pure function. 518Stored in the @code{unchanging} field and printed as @samp{/u}. 519 520@findex INSN_ANNULLED_BRANCH_P 521@cindex @code{jump_insn} and @samp{/u} 522@cindex @code{call_insn} and @samp{/u} 523@cindex @code{insn} and @samp{/u} 524@cindex @code{unchanging}, in @code{jump_insn}, @code{call_insn} and @code{insn} 525@item INSN_ANNULLED_BRANCH_P (@var{x}) 526In a @code{jump_insn}, @code{call_insn}, or @code{insn} indicates 527that the branch is an annulling one. See the discussion under 528@code{sequence} below. Stored in the @code{unchanging} field and 529printed as @samp{/u}. 530 531@findex INSN_DEAD_CODE_P 532@cindex @code{insn} and @samp{/s} 533@cindex @code{in_struct}, in @code{insn} 534@item INSN_DEAD_CODE_P (@var{x}) 535In an @code{insn} during the dead-code elimination pass, nonzero if the 536insn is dead. 537Stored in the @code{in_struct} field and printed as @samp{/s}. 538 539@findex INSN_DELETED_P 540@cindex @code{insn} and @samp{/v} 541@cindex @code{call_insn} and @samp{/v} 542@cindex @code{jump_insn} and @samp{/v} 543@cindex @code{code_label} and @samp{/v} 544@cindex @code{barrier} and @samp{/v} 545@cindex @code{note} and @samp{/v} 546@cindex @code{volatil}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, @code{barrier}, and @code{note} 547@item INSN_DELETED_P (@var{x}) 548In an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, 549@code{barrier}, or @code{note}, 550nonzero if the insn has been deleted. Stored in the 551@code{volatil} field and printed as @samp{/v}. 552 553@findex INSN_FROM_TARGET_P 554@cindex @code{insn} and @samp{/s} 555@cindex @code{jump_insn} and @samp{/s} 556@cindex @code{call_insn} and @samp{/s} 557@cindex @code{in_struct}, in @code{insn} and @code{jump_insn} and @code{call_insn} 558@item INSN_FROM_TARGET_P (@var{x}) 559In an @code{insn} or @code{jump_insn} or @code{call_insn} in a delay 560slot of a branch, indicates that the insn 561is from the target of the branch. If the branch insn has 562@code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if 563the branch is taken. For annulled branches with 564@code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the 565branch is not taken. When @code{INSN_ANNULLED_BRANCH_P} is not set, 566this insn will always be executed. Stored in the @code{in_struct} 567field and printed as @samp{/s}. 568 569@findex LABEL_OUTSIDE_LOOP_P 570@cindex @code{label_ref} and @samp{/s} 571@cindex @code{in_struct}, in @code{label_ref} 572@item LABEL_OUTSIDE_LOOP_P (@var{x}) 573In @code{label_ref} expressions, nonzero if this is a reference to a 574label that is outside the innermost loop containing the reference to the 575label. Stored in the @code{in_struct} field and printed as @samp{/s}. 576 577@findex LABEL_PRESERVE_P 578@cindex @code{code_label} and @samp{/i} 579@cindex @code{note} and @samp{/i} 580@cindex @code{in_struct}, in @code{code_label} and @code{note} 581@item LABEL_PRESERVE_P (@var{x}) 582In a @code{code_label} or @code{note}, indicates that the label is referenced by 583code or data not visible to the RTL of a given function. 584Labels referenced by a non-local goto will have this bit set. Stored 585in the @code{in_struct} field and printed as @samp{/s}. 586 587@findex LABEL_REF_NONLOCAL_P 588@cindex @code{label_ref} and @samp{/v} 589@cindex @code{reg_label} and @samp{/v} 590@cindex @code{volatil}, in @code{label_ref} and @code{reg_label} 591@item LABEL_REF_NONLOCAL_P (@var{x}) 592In @code{label_ref} and @code{reg_label} expressions, nonzero if this is 593a reference to a non-local label. 594Stored in the @code{volatil} field and printed as @samp{/v}. 595 596@findex MEM_IN_STRUCT_P 597@cindex @code{mem} and @samp{/s} 598@cindex @code{in_struct}, in @code{mem} 599@item MEM_IN_STRUCT_P (@var{x}) 600In @code{mem} expressions, nonzero for reference to an entire structure, 601union or array, or to a component of one. Zero for references to a 602scalar variable or through a pointer to a scalar. If both this flag and 603@code{MEM_SCALAR_P} are clear, then we don't know whether this @code{mem} 604is in a structure or not. Both flags should never be simultaneously set. 605Stored in the @code{in_struct} field and printed as @samp{/s}. 606 607@findex MEM_KEEP_ALIAS_SET_P 608@cindex @code{mem} and @samp{/j} 609@cindex @code{jump}, in @code{mem} 610@item MEM_KEEP_ALIAS_SET_P (@var{x}) 611In @code{mem} expressions, 1 if we should keep the alias set for this 612mem unchanged when we access a component. Set to 1, for example, when we 613are already in a non-addressable component of an aggregate. 614Stored in the @code{jump} field and printed as @samp{/j}. 615 616@findex MEM_SCALAR_P 617@cindex @code{mem} and @samp{/f} 618@cindex @code{frame_related}, in @code{mem} 619@item MEM_SCALAR_P (@var{x}) 620In @code{mem} expressions, nonzero for reference to a scalar known not 621to be a member of a structure, union, or array. Zero for such 622references and for indirections through pointers, even pointers pointing 623to scalar types. If both this flag and @code{MEM_IN_STRUCT_P} are clear, 624then we don't know whether this @code{mem} is in a structure or not. 625Both flags should never be simultaneously set. 626Stored in the @code{frame_related} field and printed as @samp{/f}. 627 628@findex MEM_VOLATILE_P 629@cindex @code{mem} and @samp{/v} 630@cindex @code{asm_input} and @samp{/v} 631@cindex @code{asm_operands} and @samp{/v} 632@cindex @code{volatil}, in @code{mem}, @code{asm_operands}, and @code{asm_input} 633@item MEM_VOLATILE_P (@var{x}) 634In @code{mem}, @code{asm_operands}, and @code{asm_input} expressions, 635nonzero for volatile memory references. 636Stored in the @code{volatil} field and printed as @samp{/v}. 637 638@findex MEM_NOTRAP_P 639@cindex @code{mem} and @samp{/c} 640@cindex @code{call}, in @code{mem} 641@item MEM_NOTRAP_P (@var{x}) 642In @code{mem}, nonzero for memory references that will not trap. 643Stored in the @code{call} field and printed as @samp{/c}. 644 645@findex REG_FUNCTION_VALUE_P 646@cindex @code{reg} and @samp{/i} 647@cindex @code{integrated}, in @code{reg} 648@item REG_FUNCTION_VALUE_P (@var{x}) 649Nonzero in a @code{reg} if it is the place in which this function's 650value is going to be returned. (This happens only in a hard 651register.) Stored in the @code{integrated} field and printed as 652@samp{/i}. 653 654@findex REG_LOOP_TEST_P 655@cindex @code{reg} and @samp{/s} 656@cindex @code{in_struct}, in @code{reg} 657@item REG_LOOP_TEST_P (@var{x}) 658In @code{reg} expressions, nonzero if this register's entire life is 659contained in the exit test code for some loop. Stored in the 660@code{in_struct} field and printed as @samp{/s}. 661 662@findex REG_POINTER 663@cindex @code{reg} and @samp{/f} 664@cindex @code{frame_related}, in @code{reg} 665@item REG_POINTER (@var{x}) 666Nonzero in a @code{reg} if the register holds a pointer. Stored in the 667@code{frame_related} field and printed as @samp{/f}. 668 669@findex REG_USERVAR_P 670@cindex @code{reg} and @samp{/v} 671@cindex @code{volatil}, in @code{reg} 672@item REG_USERVAR_P (@var{x}) 673In a @code{reg}, nonzero if it corresponds to a variable present in 674the user's source code. Zero for temporaries generated internally by 675the compiler. Stored in the @code{volatil} field and printed as 676@samp{/v}. 677 678The same hard register may be used also for collecting the values of 679functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero 680in this kind of use. 681 682@findex RTX_FRAME_RELATED_P 683@cindex @code{insn} and @samp{/f} 684@cindex @code{call_insn} and @samp{/f} 685@cindex @code{jump_insn} and @samp{/f} 686@cindex @code{barrier} and @samp{/f} 687@cindex @code{set} and @samp{/f} 688@cindex @code{frame_related}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, and @code{set} 689@item RTX_FRAME_RELATED_P (@var{x}) 690Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn}, 691@code{barrier}, or @code{set} which is part of a function prologue 692and sets the stack pointer, sets the frame pointer, or saves a register. 693This flag should also be set on an instruction that sets up a temporary 694register to use in place of the frame pointer. 695Stored in the @code{frame_related} field and printed as @samp{/f}. 696 697In particular, on RISC targets where there are limits on the sizes of 698immediate constants, it is sometimes impossible to reach the register 699save area directly from the stack pointer. In that case, a temporary 700register is used that is near enough to the register save area, and the 701Canonical Frame Address, i.e., DWARF2's logical frame pointer, register 702must (temporarily) be changed to be this temporary register. So, the 703instruction that sets this temporary register must be marked as 704@code{RTX_FRAME_RELATED_P}. 705 706If the marked instruction is overly complex (defined in terms of what 707@code{dwarf2out_frame_debug_expr} can handle), you will also have to 708create a @code{REG_FRAME_RELATED_EXPR} note and attach it to the 709instruction. This note should contain a simple expression of the 710computation performed by this instruction, i.e., one that 711@code{dwarf2out_frame_debug_expr} can handle. 712 713This flag is required for exception handling support on targets with RTL 714prologues. 715 716@findex RTX_INTEGRATED_P 717@cindex @code{insn} and @samp{/i} 718@cindex @code{call_insn} and @samp{/i} 719@cindex @code{jump_insn} and @samp{/i} 720@cindex @code{barrier} and @samp{/i} 721@cindex @code{code_label} and @samp{/i} 722@cindex @code{insn_list} and @samp{/i} 723@cindex @code{const} and @samp{/i} 724@cindex @code{note} and @samp{/i} 725@cindex @code{integrated}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, @code{code_label}, @code{insn_list}, @code{const}, and @code{note} 726@item RTX_INTEGRATED_P (@var{x}) 727Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, 728@code{code_label}, @code{insn_list}, @code{const}, or @code{note} if it 729resulted from an in-line function call. 730Stored in the @code{integrated} field and printed as @samp{/i}. 731 732@findex RTX_UNCHANGING_P 733@cindex @code{reg} and @samp{/u} 734@cindex @code{mem} and @samp{/u} 735@cindex @code{concat} and @samp{/u} 736@cindex @code{unchanging}, in @code{reg} and @code{mem} 737@item RTX_UNCHANGING_P (@var{x}) 738Nonzero in a @code{reg}, @code{mem}, or @code{concat} if the register or 739memory is set at most once, anywhere. This does not mean that it is 740function invariant. 741 742GCC uses this flag to determine whether two references conflict. As 743implemented by @code{true_dependence} in @file{alias.c} for memory 744references, unchanging memory can't conflict with non-unchanging memory; 745a non-unchanging read can conflict with a non-unchanging write; an 746unchanging read can conflict with an unchanging write (since there may 747be a single store to this address to initialize it); and an unchanging 748store can conflict with a non-unchanging read. This means we must make 749conservative assumptions when choosing the value of this flag for a 750memory reference to an object containing both unchanging and 751non-unchanging fields: we must set the flag when writing to the object 752and clear it when reading from the object. 753 754Stored in the @code{unchanging} field and printed as @samp{/u}. 755 756@findex SCHED_GROUP_P 757@cindex @code{insn} and @samp{/s} 758@cindex @code{call_insn} and @samp{/s} 759@cindex @code{jump_insn} and @samp{/s} 760@cindex @code{in_struct}, in @code{insn}, @code{jump_insn} and @code{call_insn} 761@item SCHED_GROUP_P (@var{x}) 762During instruction scheduling, in an @code{insn}, @code{call_insn} or 763@code{jump_insn}, indicates that the 764previous insn must be scheduled together with this insn. This is used to 765ensure that certain groups of instructions will not be split up by the 766instruction scheduling pass, for example, @code{use} insns before 767a @code{call_insn} may not be separated from the @code{call_insn}. 768Stored in the @code{in_struct} field and printed as @samp{/s}. 769 770@findex SET_IS_RETURN_P 771@cindex @code{insn} and @samp{/j} 772@cindex @code{jump}, in @code{insn} 773@item SET_IS_RETURN_P (@var{x}) 774For a @code{set}, nonzero if it is for a return. 775Stored in the @code{jump} field and printed as @samp{/j}. 776 777@findex SIBLING_CALL_P 778@cindex @code{call_insn} and @samp{/j} 779@cindex @code{jump}, in @code{call_insn} 780@item SIBLING_CALL_P (@var{x}) 781For a @code{call_insn}, nonzero if the insn is a sibling call. 782Stored in the @code{jump} field and printed as @samp{/j}. 783 784@findex STRING_POOL_ADDRESS_P 785@cindex @code{symbol_ref} and @samp{/f} 786@cindex @code{frame_related}, in @code{symbol_ref} 787@item STRING_POOL_ADDRESS_P (@var{x}) 788For a @code{symbol_ref} expression, nonzero if it addresses this function's 789string constant pool. 790Stored in the @code{frame_related} field and printed as @samp{/f}. 791 792@findex SUBREG_PROMOTED_UNSIGNED_P 793@cindex @code{subreg} and @samp{/u} and @samp{/v} 794@cindex @code{unchanging}, in @code{subreg} 795@cindex @code{volatil}, in @code{subreg} 796@item SUBREG_PROMOTED_UNSIGNED_P (@var{x}) 797Returns a value greater then zero for a @code{subreg} that has 798@code{SUBREG_PROMOTED_VAR_P} nonzero if the object being referenced is kept 799zero-extended, zero if it is kept sign-extended, and less then zero if it is 800extended some other way via the @code{ptr_extend} instruction. 801Stored in the @code{unchanging} 802field and @code{volatil} field, printed as @samp{/u} and @samp{/v}. 803This macro may only be used to get the value it may not be used to change 804the value. Use @code{SUBREG_PROMOTED_UNSIGNED_SET} to change the value. 805 806@findex SUBREG_PROMOTED_UNSIGNED_SET 807@cindex @code{subreg} and @samp{/u} 808@cindex @code{unchanging}, in @code{subreg} 809@cindex @code{volatil}, in @code{subreg} 810@item SUBREG_PROMOTED_UNSIGNED_SET (@var{x}) 811Set the @code{unchanging} and @code{volatil} fields in a @code{subreg} 812to reflect zero, sign, or other extension. If @code{volatil} is 813zero, then @code{unchanging} as nonzero means zero extension and as 814zero means sign extension. If @code{volatil} is nonzero then some 815other type of extension was done via the @code{ptr_extend} instruction. 816 817@findex SUBREG_PROMOTED_VAR_P 818@cindex @code{subreg} and @samp{/s} 819@cindex @code{in_struct}, in @code{subreg} 820@item SUBREG_PROMOTED_VAR_P (@var{x}) 821Nonzero in a @code{subreg} if it was made when accessing an object that 822was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine 823description macro (@pxref{Storage Layout}). In this case, the mode of 824the @code{subreg} is the declared mode of the object and the mode of 825@code{SUBREG_REG} is the mode of the register that holds the object. 826Promoted variables are always either sign- or zero-extended to the wider 827mode on every assignment. Stored in the @code{in_struct} field and 828printed as @samp{/s}. 829 830@findex SYMBOL_REF_USED 831@cindex @code{used}, in @code{symbol_ref} 832@item SYMBOL_REF_USED (@var{x}) 833In a @code{symbol_ref}, indicates that @var{x} has been used. This is 834normally only used to ensure that @var{x} is only declared external 835once. Stored in the @code{used} field. 836 837@findex SYMBOL_REF_WEAK 838@cindex @code{symbol_ref} and @samp{/i} 839@cindex @code{integrated}, in @code{symbol_ref} 840@item SYMBOL_REF_WEAK (@var{x}) 841In a @code{symbol_ref}, indicates that @var{x} has been declared weak. 842Stored in the @code{integrated} field and printed as @samp{/i}. 843 844@findex SYMBOL_REF_FLAG 845@cindex @code{symbol_ref} and @samp{/v} 846@cindex @code{volatil}, in @code{symbol_ref} 847@item SYMBOL_REF_FLAG (@var{x}) 848In a @code{symbol_ref}, this is used as a flag for machine-specific purposes. 849Stored in the @code{volatil} field and printed as @samp{/v}. 850 851Most uses of @code{SYMBOL_REF_FLAG} are historic and may be subsumed 852by @code{SYMBOL_REF_FLAGS}. Certainly use of @code{SYMBOL_REF_FLAGS} 853is mandatory if the target requires more than one bit of storage. 854@end table 855 856These are the fields to which the above macros refer: 857 858@table @code 859@findex call 860@cindex @samp{/c} in RTL dump 861@item call 862In a @code{mem}, 1 means that the memory reference will not trap. 863 864In an RTL dump, this flag is represented as @samp{/c}. 865 866@findex frame_related 867@cindex @samp{/f} in RTL dump 868@item frame_related 869In an @code{insn} or @code{set} expression, 1 means that it is part of 870a function prologue and sets the stack pointer, sets the frame pointer, 871saves a register, or sets up a temporary register to use in place of the 872frame pointer. 873 874In @code{reg} expressions, 1 means that the register holds a pointer. 875 876In @code{symbol_ref} expressions, 1 means that the reference addresses 877this function's string constant pool. 878 879In @code{mem} expressions, 1 means that the reference is to a scalar. 880 881In an RTL dump, this flag is represented as @samp{/f}. 882 883@findex in_struct 884@cindex @samp{/s} in RTL dump 885@item in_struct 886In @code{mem} expressions, it is 1 if the memory datum referred to is 887all or part of a structure or array; 0 if it is (or might be) a scalar 888variable. A reference through a C pointer has 0 because the pointer 889might point to a scalar variable. This information allows the compiler 890to determine something about possible cases of aliasing. 891 892In @code{reg} expressions, it is 1 if the register has its entire life 893contained within the test expression of some loop. 894 895In @code{subreg} expressions, 1 means that the @code{subreg} is accessing 896an object that has had its mode promoted from a wider mode. 897 898In @code{label_ref} expressions, 1 means that the referenced label is 899outside the innermost loop containing the insn in which the @code{label_ref} 900was found. 901 902In @code{code_label} expressions, it is 1 if the label may never be deleted. 903This is used for labels which are the target of non-local gotos. Such a 904label that would have been deleted is replaced with a @code{note} of type 905@code{NOTE_INSN_DELETED_LABEL}. 906 907In an @code{insn} during dead-code elimination, 1 means that the insn is 908dead code. 909 910In an @code{insn} or @code{jump_insn} during reorg for an insn in the 911delay slot of a branch, 9121 means that this insn is from the target of the branch. 913 914In an @code{insn} during instruction scheduling, 1 means that this insn 915must be scheduled as part of a group together with the previous insn. 916 917In an RTL dump, this flag is represented as @samp{/s}. 918 919@findex integrated 920@cindex @samp{/i} in RTL dump 921@item integrated 922In an @code{insn}, @code{insn_list}, or @code{const}, 1 means the RTL was 923produced by procedure integration. 924 925In @code{reg} expressions, 1 means the register contains 926the value to be returned by the current function. On 927machines that pass parameters in registers, the same register number 928may be used for parameters as well, but this flag is not set on such 929uses. 930 931In @code{symbol_ref} expressions, 1 means the referenced symbol is weak. 932 933In an RTL dump, this flag is represented as @samp{/i}. 934 935@findex jump 936@cindex @samp{/j} in RTL dump 937@item jump 938In a @code{mem} expression, 1 means we should keep the alias set for this 939mem unchanged when we access a component. 940 941In a @code{set}, 1 means it is for a return. 942 943In a @code{call_insn}, 1 means it is a sibling call. 944 945In an RTL dump, this flag is represented as @samp{/j}. 946 947@findex unchanging 948@cindex @samp{/u} in RTL dump 949@item unchanging 950In @code{reg} and @code{mem} expressions, 1 means 951that the value of the expression never changes. 952 953In @code{subreg} expressions, it is 1 if the @code{subreg} references an 954unsigned object whose mode has been promoted to a wider mode. 955 956In an @code{insn} or @code{jump_insn} in the delay slot of a branch 957instruction, 1 means an annulling branch should be used. 958 959In a @code{symbol_ref} expression, 1 means that this symbol addresses 960something in the per-function constant pool. 961 962In a @code{call_insn}, @code{note}, or an @code{expr_list} of notes, 9631 means that this instruction is a call to a const or pure function. 964 965In an RTL dump, this flag is represented as @samp{/u}. 966 967@findex used 968@item used 969This flag is used directly (without an access macro) at the end of RTL 970generation for a function, to count the number of times an expression 971appears in insns. Expressions that appear more than once are copied, 972according to the rules for shared structure (@pxref{Sharing}). 973 974For a @code{reg}, it is used directly (without an access macro) by the 975leaf register renumbering code to ensure that each register is only 976renumbered once. 977 978In a @code{symbol_ref}, it indicates that an external declaration for 979the symbol has already been written. 980 981@findex volatil 982@cindex @samp{/v} in RTL dump 983@item volatil 984@cindex volatile memory references 985In a @code{mem}, @code{asm_operands}, or @code{asm_input} 986expression, it is 1 if the memory 987reference is volatile. Volatile memory references may not be deleted, 988reordered or combined. 989 990In a @code{symbol_ref} expression, it is used for machine-specific 991purposes. 992 993In a @code{reg} expression, it is 1 if the value is a user-level variable. 9940 indicates an internal compiler temporary. 995 996In an @code{insn}, 1 means the insn has been deleted. 997 998In @code{label_ref} and @code{reg_label} expressions, 1 means a reference 999to a non-local label. 1000 1001In an RTL dump, this flag is represented as @samp{/v}. 1002@end table 1003 1004@node Machine Modes 1005@section Machine Modes 1006@cindex machine modes 1007 1008@findex enum machine_mode 1009A machine mode describes a size of data object and the representation used 1010for it. In the C code, machine modes are represented by an enumeration 1011type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL 1012expression has room for a machine mode and so do certain kinds of tree 1013expressions (declarations and types, to be precise). 1014 1015In debugging dumps and machine descriptions, the machine mode of an RTL 1016expression is written after the expression code with a colon to separate 1017them. The letters @samp{mode} which appear at the end of each machine mode 1018name are omitted. For example, @code{(reg:SI 38)} is a @code{reg} 1019expression with machine mode @code{SImode}. If the mode is 1020@code{VOIDmode}, it is not written at all. 1021 1022Here is a table of machine modes. The term ``byte'' below refers to an 1023object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}). 1024 1025@table @code 1026@findex BImode 1027@item BImode 1028``Bit'' mode represents a single bit, for predicate registers. 1029 1030@findex QImode 1031@item QImode 1032``Quarter-Integer'' mode represents a single byte treated as an integer. 1033 1034@findex HImode 1035@item HImode 1036``Half-Integer'' mode represents a two-byte integer. 1037 1038@findex PSImode 1039@item PSImode 1040``Partial Single Integer'' mode represents an integer which occupies 1041four bytes but which doesn't really use all four. On some machines, 1042this is the right mode to use for pointers. 1043 1044@findex SImode 1045@item SImode 1046``Single Integer'' mode represents a four-byte integer. 1047 1048@findex PDImode 1049@item PDImode 1050``Partial Double Integer'' mode represents an integer which occupies 1051eight bytes but which doesn't really use all eight. On some machines, 1052this is the right mode to use for certain pointers. 1053 1054@findex DImode 1055@item DImode 1056``Double Integer'' mode represents an eight-byte integer. 1057 1058@findex TImode 1059@item TImode 1060``Tetra Integer'' (?) mode represents a sixteen-byte integer. 1061 1062@findex OImode 1063@item OImode 1064``Octa Integer'' (?) mode represents a thirty-two-byte integer. 1065 1066@findex QFmode 1067@item QFmode 1068``Quarter-Floating'' mode represents a quarter-precision (single byte) 1069floating point number. 1070 1071@findex HFmode 1072@item HFmode 1073``Half-Floating'' mode represents a half-precision (two byte) floating 1074point number. 1075 1076@findex TQFmode 1077@item TQFmode 1078``Three-Quarter-Floating'' (?) mode represents a three-quarter-precision 1079(three byte) floating point number. 1080 1081@findex SFmode 1082@item SFmode 1083``Single Floating'' mode represents a four byte floating point number. 1084In the common case, of a processor with IEEE arithmetic and 8-bit bytes, 1085this is a single-precision IEEE floating point number; it can also be 1086used for double-precision (on processors with 16-bit bytes) and 1087single-precision VAX and IBM types. 1088 1089@findex DFmode 1090@item DFmode 1091``Double Floating'' mode represents an eight byte floating point number. 1092In the common case, of a processor with IEEE arithmetic and 8-bit bytes, 1093this is a double-precision IEEE floating point number. 1094 1095@findex XFmode 1096@item XFmode 1097``Extended Floating'' mode represents a twelve byte floating point 1098number. This mode is used for IEEE extended floating point. On some 1099systems not all bits within these bytes will actually be used. 1100 1101@findex TFmode 1102@item TFmode 1103``Tetra Floating'' mode represents a sixteen byte floating point number. 1104This gets used for both the 96-bit extended IEEE floating-point types 1105padded to 128 bits, and true 128-bit extended IEEE floating-point types. 1106 1107@findex CCmode 1108@item CCmode 1109``Condition Code'' mode represents the value of a condition code, which 1110is a machine-specific set of bits used to represent the result of a 1111comparison operation. Other machine-specific modes may also be used for 1112the condition code. These modes are not used on machines that use 1113@code{cc0} (see @pxref{Condition Code}). 1114 1115@findex BLKmode 1116@item BLKmode 1117``Block'' mode represents values that are aggregates to which none of 1118the other modes apply. In RTL, only memory references can have this mode, 1119and only if they appear in string-move or vector instructions. On machines 1120which have no such instructions, @code{BLKmode} will not appear in RTL@. 1121 1122@findex VOIDmode 1123@item VOIDmode 1124Void mode means the absence of a mode or an unspecified mode. 1125For example, RTL expressions of code @code{const_int} have mode 1126@code{VOIDmode} because they can be taken to have whatever mode the context 1127requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by 1128the absence of any mode. 1129 1130@findex QCmode 1131@findex HCmode 1132@findex SCmode 1133@findex DCmode 1134@findex XCmode 1135@findex TCmode 1136@item QCmode, HCmode, SCmode, DCmode, XCmode, TCmode 1137These modes stand for a complex number represented as a pair of floating 1138point values. The floating point values are in @code{QFmode}, 1139@code{HFmode}, @code{SFmode}, @code{DFmode}, @code{XFmode}, and 1140@code{TFmode}, respectively. 1141 1142@findex CQImode 1143@findex CHImode 1144@findex CSImode 1145@findex CDImode 1146@findex CTImode 1147@findex COImode 1148@item CQImode, CHImode, CSImode, CDImode, CTImode, COImode 1149These modes stand for a complex number represented as a pair of integer 1150values. The integer values are in @code{QImode}, @code{HImode}, 1151@code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode}, 1152respectively. 1153@end table 1154 1155The machine description defines @code{Pmode} as a C macro which expands 1156into the machine mode used for addresses. Normally this is the mode 1157whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines. 1158 1159The only modes which a machine description @i{must} support are 1160@code{QImode}, and the modes corresponding to @code{BITS_PER_WORD}, 1161@code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}. 1162The compiler will attempt to use @code{DImode} for 8-byte structures and 1163unions, but this can be prevented by overriding the definition of 1164@code{MAX_FIXED_MODE_SIZE}. Alternatively, you can have the compiler 1165use @code{TImode} for 16-byte structures and unions. Likewise, you can 1166arrange for the C type @code{short int} to avoid using @code{HImode}. 1167 1168@cindex mode classes 1169Very few explicit references to machine modes remain in the compiler and 1170these few references will soon be removed. Instead, the machine modes 1171are divided into mode classes. These are represented by the enumeration 1172type @code{enum mode_class} defined in @file{machmode.h}. The possible 1173mode classes are: 1174 1175@table @code 1176@findex MODE_INT 1177@item MODE_INT 1178Integer modes. By default these are @code{BImode}, @code{QImode}, 1179@code{HImode}, @code{SImode}, @code{DImode}, @code{TImode}, and 1180@code{OImode}. 1181 1182@findex MODE_PARTIAL_INT 1183@item MODE_PARTIAL_INT 1184The ``partial integer'' modes, @code{PQImode}, @code{PHImode}, 1185@code{PSImode} and @code{PDImode}. 1186 1187@findex MODE_FLOAT 1188@item MODE_FLOAT 1189Floating point modes. By default these are @code{QFmode}, 1190@code{HFmode}, @code{TQFmode}, @code{SFmode}, @code{DFmode}, 1191@code{XFmode} and @code{TFmode}. 1192 1193@findex MODE_COMPLEX_INT 1194@item MODE_COMPLEX_INT 1195Complex integer modes. (These are not currently implemented). 1196 1197@findex MODE_COMPLEX_FLOAT 1198@item MODE_COMPLEX_FLOAT 1199Complex floating point modes. By default these are @code{QCmode}, 1200@code{HCmode}, @code{SCmode}, @code{DCmode}, @code{XCmode}, and 1201@code{TCmode}. 1202 1203@findex MODE_FUNCTION 1204@item MODE_FUNCTION 1205Algol or Pascal function variables including a static chain. 1206(These are not currently implemented). 1207 1208@findex MODE_CC 1209@item MODE_CC 1210Modes representing condition code values. These are @code{CCmode} plus 1211any modes listed in the @code{EXTRA_CC_MODES} macro. @xref{Jump Patterns}, 1212also see @ref{Condition Code}. 1213 1214@findex MODE_RANDOM 1215@item MODE_RANDOM 1216This is a catchall mode class for modes which don't fit into the above 1217classes. Currently @code{VOIDmode} and @code{BLKmode} are in 1218@code{MODE_RANDOM}. 1219@end table 1220 1221Here are some C macros that relate to machine modes: 1222 1223@table @code 1224@findex GET_MODE 1225@item GET_MODE (@var{x}) 1226Returns the machine mode of the RTX @var{x}. 1227 1228@findex PUT_MODE 1229@item PUT_MODE (@var{x}, @var{newmode}) 1230Alters the machine mode of the RTX @var{x} to be @var{newmode}. 1231 1232@findex NUM_MACHINE_MODES 1233@item NUM_MACHINE_MODES 1234Stands for the number of machine modes available on the target 1235machine. This is one greater than the largest numeric value of any 1236machine mode. 1237 1238@findex GET_MODE_NAME 1239@item GET_MODE_NAME (@var{m}) 1240Returns the name of mode @var{m} as a string. 1241 1242@findex GET_MODE_CLASS 1243@item GET_MODE_CLASS (@var{m}) 1244Returns the mode class of mode @var{m}. 1245 1246@findex GET_MODE_WIDER_MODE 1247@item GET_MODE_WIDER_MODE (@var{m}) 1248Returns the next wider natural mode. For example, the expression 1249@code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}. 1250 1251@findex GET_MODE_SIZE 1252@item GET_MODE_SIZE (@var{m}) 1253Returns the size in bytes of a datum of mode @var{m}. 1254 1255@findex GET_MODE_BITSIZE 1256@item GET_MODE_BITSIZE (@var{m}) 1257Returns the size in bits of a datum of mode @var{m}. 1258 1259@findex GET_MODE_MASK 1260@item GET_MODE_MASK (@var{m}) 1261Returns a bitmask containing 1 for all bits in a word that fit within 1262mode @var{m}. This macro can only be used for modes whose bitsize is 1263less than or equal to @code{HOST_BITS_PER_INT}. 1264 1265@findex GET_MODE_ALIGNMENT 1266@item GET_MODE_ALIGNMENT (@var{m}) 1267Return the required alignment, in bits, for an object of mode @var{m}. 1268 1269@findex GET_MODE_UNIT_SIZE 1270@item GET_MODE_UNIT_SIZE (@var{m}) 1271Returns the size in bytes of the subunits of a datum of mode @var{m}. 1272This is the same as @code{GET_MODE_SIZE} except in the case of complex 1273modes. For them, the unit size is the size of the real or imaginary 1274part. 1275 1276@findex GET_MODE_NUNITS 1277@item GET_MODE_NUNITS (@var{m}) 1278Returns the number of units contained in a mode, i.e., 1279@code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}. 1280 1281@findex GET_CLASS_NARROWEST_MODE 1282@item GET_CLASS_NARROWEST_MODE (@var{c}) 1283Returns the narrowest mode in mode class @var{c}. 1284@end table 1285 1286@findex byte_mode 1287@findex word_mode 1288The global variables @code{byte_mode} and @code{word_mode} contain modes 1289whose classes are @code{MODE_INT} and whose bitsizes are either 1290@code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit 1291machines, these are @code{QImode} and @code{SImode}, respectively. 1292 1293@node Constants 1294@section Constant Expression Types 1295@cindex RTL constants 1296@cindex RTL constant expression types 1297 1298The simplest RTL expressions are those that represent constant values. 1299 1300@table @code 1301@findex const_int 1302@item (const_int @var{i}) 1303This type of expression represents the integer value @var{i}. @var{i} 1304is customarily accessed with the macro @code{INTVAL} as in 1305@code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}. 1306 1307@findex const0_rtx 1308@findex const1_rtx 1309@findex const2_rtx 1310@findex constm1_rtx 1311There is only one expression object for the integer value zero; it is 1312the value of the variable @code{const0_rtx}. Likewise, the only 1313expression for integer value one is found in @code{const1_rtx}, the only 1314expression for integer value two is found in @code{const2_rtx}, and the 1315only expression for integer value negative one is found in 1316@code{constm1_rtx}. Any attempt to create an expression of code 1317@code{const_int} and value zero, one, two or negative one will return 1318@code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or 1319@code{constm1_rtx} as appropriate. 1320 1321@findex const_true_rtx 1322Similarly, there is only one object for the integer whose value is 1323@code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If 1324@code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and 1325@code{const1_rtx} will point to the same object. If 1326@code{STORE_FLAG_VALUE} is @minus{}1, @code{const_true_rtx} and 1327@code{constm1_rtx} will point to the same object. 1328 1329@findex const_double 1330@item (const_double:@var{m} @var{addr} @var{i0} @var{i1} @dots{}) 1331Represents either a floating-point constant of mode @var{m} or an 1332integer constant too large to fit into @code{HOST_BITS_PER_WIDE_INT} 1333bits but small enough to fit within twice that number of bits (GCC 1334does not provide a mechanism to represent even larger constants). In 1335the latter case, @var{m} will be @code{VOIDmode}. 1336 1337@findex const_vector 1338@item (const_vector:@var{m} [@var{x0} @var{x1} @dots{}]) 1339Represents a vector constant. The square brackets stand for the vector 1340containing the constant elements. @var{x0}, @var{x1} and so on are 1341the @code{const_int} or @code{const_double} elements. 1342 1343The number of units in a @code{const_vector} is obtained with the macro 1344@code{CONST_VECTOR_NUNITS} as in @code{CONST_VECTOR_NUNITS (@var{v})}. 1345 1346Individual elements in a vector constant are accessed with the macro 1347@code{CONST_VECTOR_ELT} as in @code{CONST_VECTOR_ELT (@var{v}, @var{n})} 1348where @var{v} is the vector constant and @var{n} is the element 1349desired. 1350 1351@findex CONST_DOUBLE_MEM 1352@findex CONST_DOUBLE_CHAIN 1353@var{addr} is used to contain the @code{mem} expression that corresponds 1354to the location in memory that at which the constant can be found. If 1355it has not been allocated a memory location, but is on the chain of all 1356@code{const_double} expressions in this compilation (maintained using an 1357undisplayed field), @var{addr} contains @code{const0_rtx}. If it is not 1358on the chain, @var{addr} contains @code{cc0_rtx}. @var{addr} is 1359customarily accessed with the macro @code{CONST_DOUBLE_MEM} and the 1360chain field via @code{CONST_DOUBLE_CHAIN}. 1361 1362@findex CONST_DOUBLE_LOW 1363If @var{m} is @code{VOIDmode}, the bits of the value are stored in 1364@var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro 1365@code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}. 1366 1367If the constant is floating point (regardless of its precision), then 1368the number of integers used to store the value depends on the size of 1369@code{REAL_VALUE_TYPE} (@pxref{Floating Point}). The integers 1370represent a floating point number, but not precisely in the target 1371machine's or host machine's floating point format. To convert them to 1372the precise bit pattern used by the target machine, use the macro 1373@code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}). 1374 1375@findex CONST0_RTX 1376@findex CONST1_RTX 1377@findex CONST2_RTX 1378The macro @code{CONST0_RTX (@var{mode})} refers to an expression with 1379value 0 in mode @var{mode}. If mode @var{mode} is of mode class 1380@code{MODE_INT}, it returns @code{const0_rtx}. If mode @var{mode} is of 1381mode class @code{MODE_FLOAT}, it returns a @code{CONST_DOUBLE} 1382expression in mode @var{mode}. Otherwise, it returns a 1383@code{CONST_VECTOR} expression in mode @var{mode}. Similarly, the macro 1384@code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in 1385mode @var{mode} and similarly for @code{CONST2_RTX}. The 1386@code{CONST1_RTX} and @code{CONST2_RTX} macros are undefined 1387for vector modes. 1388 1389@findex const_string 1390@item (const_string @var{str}) 1391Represents a constant string with value @var{str}. Currently this is 1392used only for insn attributes (@pxref{Insn Attributes}) since constant 1393strings in C are placed in memory. 1394 1395@findex symbol_ref 1396@item (symbol_ref:@var{mode} @var{symbol}) 1397Represents the value of an assembler label for data. @var{symbol} is 1398a string that describes the name of the assembler label. If it starts 1399with a @samp{*}, the label is the rest of @var{symbol} not including 1400the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed 1401with @samp{_}. 1402 1403The @code{symbol_ref} contains a mode, which is usually @code{Pmode}. 1404Usually that is the only mode for which a symbol is directly valid. 1405 1406@findex label_ref 1407@item (label_ref @var{label}) 1408Represents the value of an assembler label for code. It contains one 1409operand, an expression, which must be a @code{code_label} or a @code{note} 1410of type @code{NOTE_INSN_DELETED_LABEL} that appears in the instruction 1411sequence to identify the place where the label should go. 1412 1413The reason for using a distinct expression type for code label 1414references is so that jump optimization can distinguish them. 1415 1416@item (const:@var{m} @var{exp}) 1417Represents a constant that is the result of an assembly-time 1418arithmetic computation. The operand, @var{exp}, is an expression that 1419contains only constants (@code{const_int}, @code{symbol_ref} and 1420@code{label_ref} expressions) combined with @code{plus} and 1421@code{minus}. However, not all combinations are valid, since the 1422assembler cannot do arbitrary arithmetic on relocatable symbols. 1423 1424@var{m} should be @code{Pmode}. 1425 1426@findex high 1427@item (high:@var{m} @var{exp}) 1428Represents the high-order bits of @var{exp}, usually a 1429@code{symbol_ref}. The number of bits is machine-dependent and is 1430normally the number of bits specified in an instruction that initializes 1431the high order bits of a register. It is used with @code{lo_sum} to 1432represent the typical two-instruction sequence used in RISC machines to 1433reference a global memory location. 1434 1435@var{m} should be @code{Pmode}. 1436@end table 1437 1438@node Regs and Memory 1439@section Registers and Memory 1440@cindex RTL register expressions 1441@cindex RTL memory expressions 1442 1443Here are the RTL expression types for describing access to machine 1444registers and to main memory. 1445 1446@table @code 1447@findex reg 1448@cindex hard registers 1449@cindex pseudo registers 1450@item (reg:@var{m} @var{n}) 1451For small values of the integer @var{n} (those that are less than 1452@code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine 1453register number @var{n}: a @dfn{hard register}. For larger values of 1454@var{n}, it stands for a temporary value or @dfn{pseudo register}. 1455The compiler's strategy is to generate code assuming an unlimited 1456number of such pseudo registers, and later convert them into hard 1457registers or into memory references. 1458 1459@var{m} is the machine mode of the reference. It is necessary because 1460machines can generally refer to each register in more than one mode. 1461For example, a register may contain a full word but there may be 1462instructions to refer to it as a half word or as a single byte, as 1463well as instructions to refer to it as a floating point number of 1464various precisions. 1465 1466Even for a register that the machine can access in only one mode, 1467the mode must always be specified. 1468 1469The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine 1470description, since the number of hard registers on the machine is an 1471invariant characteristic of the machine. Note, however, that not 1472all of the machine registers must be general registers. All the 1473machine registers that can be used for storage of data are given 1474hard register numbers, even those that can be used only in certain 1475instructions or can hold only certain types of data. 1476 1477A hard register may be accessed in various modes throughout one 1478function, but each pseudo register is given a natural mode 1479and is accessed only in that mode. When it is necessary to describe 1480an access to a pseudo register using a nonnatural mode, a @code{subreg} 1481expression is used. 1482 1483A @code{reg} expression with a machine mode that specifies more than 1484one word of data may actually stand for several consecutive registers. 1485If in addition the register number specifies a hardware register, then 1486it actually represents several consecutive hardware registers starting 1487with the specified one. 1488 1489Each pseudo register number used in a function's RTL code is 1490represented by a unique @code{reg} expression. 1491 1492@findex FIRST_VIRTUAL_REGISTER 1493@findex LAST_VIRTUAL_REGISTER 1494Some pseudo register numbers, those within the range of 1495@code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only 1496appear during the RTL generation phase and are eliminated before the 1497optimization phases. These represent locations in the stack frame that 1498cannot be determined until RTL generation for the function has been 1499completed. The following virtual register numbers are defined: 1500 1501@table @code 1502@findex VIRTUAL_INCOMING_ARGS_REGNUM 1503@item VIRTUAL_INCOMING_ARGS_REGNUM 1504This points to the first word of the incoming arguments passed on the 1505stack. Normally these arguments are placed there by the caller, but the 1506callee may have pushed some arguments that were previously passed in 1507registers. 1508 1509@cindex @code{FIRST_PARM_OFFSET} and virtual registers 1510@cindex @code{ARG_POINTER_REGNUM} and virtual registers 1511When RTL generation is complete, this virtual register is replaced 1512by the sum of the register given by @code{ARG_POINTER_REGNUM} and the 1513value of @code{FIRST_PARM_OFFSET}. 1514 1515@findex VIRTUAL_STACK_VARS_REGNUM 1516@cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers 1517@item VIRTUAL_STACK_VARS_REGNUM 1518If @code{FRAME_GROWS_DOWNWARD} is defined, this points to immediately 1519above the first variable on the stack. Otherwise, it points to the 1520first variable on the stack. 1521 1522@cindex @code{STARTING_FRAME_OFFSET} and virtual registers 1523@cindex @code{FRAME_POINTER_REGNUM} and virtual registers 1524@code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the 1525register given by @code{FRAME_POINTER_REGNUM} and the value 1526@code{STARTING_FRAME_OFFSET}. 1527 1528@findex VIRTUAL_STACK_DYNAMIC_REGNUM 1529@item VIRTUAL_STACK_DYNAMIC_REGNUM 1530This points to the location of dynamically allocated memory on the stack 1531immediately after the stack pointer has been adjusted by the amount of 1532memory desired. 1533 1534@cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers 1535@cindex @code{STACK_POINTER_REGNUM} and virtual registers 1536This virtual register is replaced by the sum of the register given by 1537@code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}. 1538 1539@findex VIRTUAL_OUTGOING_ARGS_REGNUM 1540@item VIRTUAL_OUTGOING_ARGS_REGNUM 1541This points to the location in the stack at which outgoing arguments 1542should be written when the stack is pre-pushed (arguments pushed using 1543push insns should always use @code{STACK_POINTER_REGNUM}). 1544 1545@cindex @code{STACK_POINTER_OFFSET} and virtual registers 1546This virtual register is replaced by the sum of the register given by 1547@code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}. 1548@end table 1549 1550@findex subreg 1551@item (subreg:@var{m} @var{reg} @var{bytenum}) 1552@code{subreg} expressions are used to refer to a register in a machine 1553mode other than its natural one, or to refer to one register of 1554a multi-part @code{reg} that actually refers to several registers. 1555 1556Each pseudo-register has a natural mode. If it is necessary to 1557operate on it in a different mode---for example, to perform a fullword 1558move instruction on a pseudo-register that contains a single 1559byte---the pseudo-register must be enclosed in a @code{subreg}. In 1560such a case, @var{bytenum} is zero. 1561 1562Usually @var{m} is at least as narrow as the mode of @var{reg}, in which 1563case it is restricting consideration to only the bits of @var{reg} that 1564are in @var{m}. 1565 1566Sometimes @var{m} is wider than the mode of @var{reg}. These 1567@code{subreg} expressions are often called @dfn{paradoxical}. They are 1568used in cases where we want to refer to an object in a wider mode but do 1569not care what value the additional bits have. The reload pass ensures 1570that paradoxical references are only made to hard registers. 1571 1572The other use of @code{subreg} is to extract the individual registers of 1573a multi-register value. Machine modes such as @code{DImode} and 1574@code{TImode} can indicate values longer than a word, values which 1575usually require two or more consecutive registers. To access one of the 1576registers, use a @code{subreg} with mode @code{SImode} and a 1577@var{bytenum} offset that says which register. 1578 1579Storing in a non-paradoxical @code{subreg} has undefined results for 1580bits belonging to the same word as the @code{subreg}. This laxity makes 1581it easier to generate efficient code for such instructions. To 1582represent an instruction that preserves all the bits outside of those in 1583the @code{subreg}, use @code{strict_low_part} around the @code{subreg}. 1584 1585@cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg} 1586The compilation parameter @code{WORDS_BIG_ENDIAN}, if set to 1, says 1587that byte number zero is part of the most significant word; otherwise, 1588it is part of the least significant word. 1589 1590@cindex @code{BYTES_BIG_ENDIAN}, effect on @code{subreg} 1591The compilation parameter @code{BYTES_BIG_ENDIAN}, if set to 1, says 1592that byte number zero is the most significant byte within a word; 1593otherwise, it is the least significant byte within a word. 1594 1595@cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg} 1596On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with 1597@code{WORDS_BIG_ENDIAN}. 1598However, most parts of the compiler treat floating point values as if 1599they had the same endianness as integer values. This works because 1600they handle them solely as a collection of integer values, with no 1601particular numerical value. Only real.c and the runtime libraries 1602care about @code{FLOAT_WORDS_BIG_ENDIAN}. 1603 1604@cindex combiner pass 1605@cindex reload pass 1606@cindex @code{subreg}, special reload handling 1607Between the combiner pass and the reload pass, it is possible to have a 1608paradoxical @code{subreg} which contains a @code{mem} instead of a 1609@code{reg} as its first operand. After the reload pass, it is also 1610possible to have a non-paradoxical @code{subreg} which contains a 1611@code{mem}; this usually occurs when the @code{mem} is a stack slot 1612which replaced a pseudo register. 1613 1614Note that it is not valid to access a @code{DFmode} value in @code{SFmode} 1615using a @code{subreg}. On some machines the most significant part of a 1616@code{DFmode} value does not have the same format as a single-precision 1617floating value. 1618 1619It is also not valid to access a single word of a multi-word value in a 1620hard register when less registers can hold the value than would be 1621expected from its size. For example, some 32-bit machines have 1622floating-point registers that can hold an entire @code{DFmode} value. 1623If register 10 were such a register @code{(subreg:SI (reg:DF 10) 1)} 1624would be invalid because there is no way to convert that reference to 1625a single machine register. The reload pass prevents @code{subreg} 1626expressions such as these from being formed. 1627 1628@findex SUBREG_REG 1629@findex SUBREG_BYTE 1630The first operand of a @code{subreg} expression is customarily accessed 1631with the @code{SUBREG_REG} macro and the second operand is customarily 1632accessed with the @code{SUBREG_BYTE} macro. 1633 1634@findex scratch 1635@cindex scratch operands 1636@item (scratch:@var{m}) 1637This represents a scratch register that will be required for the 1638execution of a single instruction and not used subsequently. It is 1639converted into a @code{reg} by either the local register allocator or 1640the reload pass. 1641 1642@code{scratch} is usually present inside a @code{clobber} operation 1643(@pxref{Side Effects}). 1644 1645@findex cc0 1646@cindex condition code register 1647@item (cc0) 1648This refers to the machine's condition code register. It has no 1649operands and may not have a machine mode. There are two ways to use it: 1650 1651@itemize @bullet 1652@item 1653To stand for a complete set of condition code flags. This is best on 1654most machines, where each comparison sets the entire series of flags. 1655 1656With this technique, @code{(cc0)} may be validly used in only two 1657contexts: as the destination of an assignment (in test and compare 1658instructions) and in comparison operators comparing against zero 1659(@code{const_int} with value zero; that is to say, @code{const0_rtx}). 1660 1661@item 1662To stand for a single flag that is the result of a single condition. 1663This is useful on machines that have only a single flag bit, and in 1664which comparison instructions must specify the condition to test. 1665 1666With this technique, @code{(cc0)} may be validly used in only two 1667contexts: as the destination of an assignment (in test and compare 1668instructions) where the source is a comparison operator, and as the 1669first operand of @code{if_then_else} (in a conditional branch). 1670@end itemize 1671 1672@findex cc0_rtx 1673There is only one expression object of code @code{cc0}; it is the 1674value of the variable @code{cc0_rtx}. Any attempt to create an 1675expression of code @code{cc0} will return @code{cc0_rtx}. 1676 1677Instructions can set the condition code implicitly. On many machines, 1678nearly all instructions set the condition code based on the value that 1679they compute or store. It is not necessary to record these actions 1680explicitly in the RTL because the machine description includes a 1681prescription for recognizing the instructions that do so (by means of 1682the macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only 1683instructions whose sole purpose is to set the condition code, and 1684instructions that use the condition code, need mention @code{(cc0)}. 1685 1686On some machines, the condition code register is given a register number 1687and a @code{reg} is used instead of @code{(cc0)}. This is usually the 1688preferable approach if only a small subset of instructions modify the 1689condition code. Other machines store condition codes in general 1690registers; in such cases a pseudo register should be used. 1691 1692Some machines, such as the SPARC and RS/6000, have two sets of 1693arithmetic instructions, one that sets and one that does not set the 1694condition code. This is best handled by normally generating the 1695instruction that does not set the condition code, and making a pattern 1696that both performs the arithmetic and sets the condition code register 1697(which would not be @code{(cc0)} in this case). For examples, search 1698for @samp{addcc} and @samp{andcc} in @file{sparc.md}. 1699 1700@findex pc 1701@item (pc) 1702@cindex program counter 1703This represents the machine's program counter. It has no operands and 1704may not have a machine mode. @code{(pc)} may be validly used only in 1705certain specific contexts in jump instructions. 1706 1707@findex pc_rtx 1708There is only one expression object of code @code{pc}; it is the value 1709of the variable @code{pc_rtx}. Any attempt to create an expression of 1710code @code{pc} will return @code{pc_rtx}. 1711 1712All instructions that do not jump alter the program counter implicitly 1713by incrementing it, but there is no need to mention this in the RTL@. 1714 1715@findex mem 1716@item (mem:@var{m} @var{addr} @var{alias}) 1717This RTX represents a reference to main memory at an address 1718represented by the expression @var{addr}. @var{m} specifies how large 1719a unit of memory is accessed. @var{alias} specifies an alias set for the 1720reference. In general two items are in different alias sets if they cannot 1721reference the same memory address. 1722 1723The construct @code{(mem:BLK (scratch))} is considered to alias all 1724other memories. Thus it may be used as a memory barrier in epilogue 1725stack deallocation patterns. 1726 1727@findex addressof 1728@item (addressof:@var{m} @var{reg}) 1729This RTX represents a request for the address of register @var{reg}. Its mode 1730is always @code{Pmode}. If there are any @code{addressof} 1731expressions left in the function after CSE, @var{reg} is forced into the 1732stack and the @code{addressof} expression is replaced with a @code{plus} 1733expression for the address of its stack slot. 1734@end table 1735 1736@node Arithmetic 1737@section RTL Expressions for Arithmetic 1738@cindex arithmetic, in RTL 1739@cindex math, in RTL 1740@cindex RTL expressions for arithmetic 1741 1742Unless otherwise specified, all the operands of arithmetic expressions 1743must be valid for mode @var{m}. An operand is valid for mode @var{m} 1744if it has mode @var{m}, or if it is a @code{const_int} or 1745@code{const_double} and @var{m} is a mode of class @code{MODE_INT}. 1746 1747For commutative binary operations, constants should be placed in the 1748second operand. 1749 1750@table @code 1751@findex plus 1752@cindex RTL addition 1753@cindex RTL sum 1754@item (plus:@var{m} @var{x} @var{y}) 1755Represents the sum of the values represented by @var{x} and @var{y} 1756carried out in machine mode @var{m}. 1757 1758@findex lo_sum 1759@item (lo_sum:@var{m} @var{x} @var{y}) 1760Like @code{plus}, except that it represents that sum of @var{x} and the 1761low-order bits of @var{y}. The number of low order bits is 1762machine-dependent but is normally the number of bits in a @code{Pmode} 1763item minus the number of bits set by the @code{high} code 1764(@pxref{Constants}). 1765 1766@var{m} should be @code{Pmode}. 1767 1768@findex minus 1769@cindex RTL subtraction 1770@cindex RTL difference 1771@item (minus:@var{m} @var{x} @var{y}) 1772Like @code{plus} but represents subtraction. 1773 1774@findex ss_plus 1775@cindex RTL addition with signed saturation 1776@item (ss_plus:@var{m} @var{x} @var{y}) 1777 1778Like @code{plus}, but using signed saturation in case of an overflow. 1779 1780@findex us_plus 1781@cindex RTL addition with unsigned saturation 1782@item (us_plus:@var{m} @var{x} @var{y}) 1783 1784Like @code{plus}, but using unsigned saturation in case of an overflow. 1785 1786@findex ss_minus 1787@cindex RTL addition with signed saturation 1788@item (ss_minus:@var{m} @var{x} @var{y}) 1789 1790Like @code{minus}, but using signed saturation in case of an overflow. 1791 1792@findex us_minus 1793@cindex RTL addition with unsigned saturation 1794@item (us_minus:@var{m} @var{x} @var{y}) 1795 1796Like @code{minus}, but using unsigned saturation in case of an overflow. 1797 1798@findex compare 1799@cindex RTL comparison 1800@item (compare:@var{m} @var{x} @var{y}) 1801Represents the result of subtracting @var{y} from @var{x} for purposes 1802of comparison. The result is computed without overflow, as if with 1803infinite precision. 1804 1805Of course, machines can't really subtract with infinite precision. 1806However, they can pretend to do so when only the sign of the result will 1807be used, which is the case when the result is stored in the condition 1808code. And that is the @emph{only} way this kind of expression may 1809validly be used: as a value to be stored in the condition codes, either 1810@code{(cc0)} or a register. @xref{Comparisons}. 1811 1812The mode @var{m} is not related to the modes of @var{x} and @var{y}, but 1813instead is the mode of the condition code value. If @code{(cc0)} is 1814used, it is @code{VOIDmode}. Otherwise it is some mode in class 1815@code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}. If @var{m} 1816is @code{VOIDmode} or @code{CCmode}, the operation returns sufficient 1817information (in an unspecified format) so that any comparison operator 1818can be applied to the result of the @code{COMPARE} operation. For other 1819modes in class @code{MODE_CC}, the operation only returns a subset of 1820this information. 1821 1822Normally, @var{x} and @var{y} must have the same mode. Otherwise, 1823@code{compare} is valid only if the mode of @var{x} is in class 1824@code{MODE_INT} and @var{y} is a @code{const_int} or 1825@code{const_double} with mode @code{VOIDmode}. The mode of @var{x} 1826determines what mode the comparison is to be done in; thus it must not 1827be @code{VOIDmode}. 1828 1829If one of the operands is a constant, it should be placed in the 1830second operand and the comparison code adjusted as appropriate. 1831 1832A @code{compare} specifying two @code{VOIDmode} constants is not valid 1833since there is no way to know in what mode the comparison is to be 1834performed; the comparison must either be folded during the compilation 1835or the first operand must be loaded into a register while its mode is 1836still known. 1837 1838@findex neg 1839@item (neg:@var{m} @var{x}) 1840Represents the negation (subtraction from zero) of the value represented 1841by @var{x}, carried out in mode @var{m}. 1842 1843@findex mult 1844@cindex multiplication 1845@cindex product 1846@item (mult:@var{m} @var{x} @var{y}) 1847Represents the signed product of the values represented by @var{x} and 1848@var{y} carried out in machine mode @var{m}. 1849 1850Some machines support a multiplication that generates a product wider 1851than the operands. Write the pattern for this as 1852 1853@smallexample 1854(mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y})) 1855@end smallexample 1856 1857where @var{m} is wider than the modes of @var{x} and @var{y}, which need 1858not be the same. 1859 1860For unsigned widening multiplication, use the same idiom, but with 1861@code{zero_extend} instead of @code{sign_extend}. 1862 1863@findex div 1864@cindex division 1865@cindex signed division 1866@cindex quotient 1867@item (div:@var{m} @var{x} @var{y}) 1868Represents the quotient in signed division of @var{x} by @var{y}, 1869carried out in machine mode @var{m}. If @var{m} is a floating point 1870mode, it represents the exact quotient; otherwise, the integerized 1871quotient. 1872 1873Some machines have division instructions in which the operands and 1874quotient widths are not all the same; you should represent 1875such instructions using @code{truncate} and @code{sign_extend} as in, 1876 1877@smallexample 1878(truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y}))) 1879@end smallexample 1880 1881@findex udiv 1882@cindex unsigned division 1883@cindex division 1884@item (udiv:@var{m} @var{x} @var{y}) 1885Like @code{div} but represents unsigned division. 1886 1887@findex mod 1888@findex umod 1889@cindex remainder 1890@cindex division 1891@item (mod:@var{m} @var{x} @var{y}) 1892@itemx (umod:@var{m} @var{x} @var{y}) 1893Like @code{div} and @code{udiv} but represent the remainder instead of 1894the quotient. 1895 1896@findex smin 1897@findex smax 1898@cindex signed minimum 1899@cindex signed maximum 1900@item (smin:@var{m} @var{x} @var{y}) 1901@itemx (smax:@var{m} @var{x} @var{y}) 1902Represents the smaller (for @code{smin}) or larger (for @code{smax}) of 1903@var{x} and @var{y}, interpreted as signed integers in mode @var{m}. 1904 1905@findex umin 1906@findex umax 1907@cindex unsigned minimum and maximum 1908@item (umin:@var{m} @var{x} @var{y}) 1909@itemx (umax:@var{m} @var{x} @var{y}) 1910Like @code{smin} and @code{smax}, but the values are interpreted as unsigned 1911integers. 1912 1913@findex not 1914@cindex complement, bitwise 1915@cindex bitwise complement 1916@item (not:@var{m} @var{x}) 1917Represents the bitwise complement of the value represented by @var{x}, 1918carried out in mode @var{m}, which must be a fixed-point machine mode. 1919 1920@findex and 1921@cindex logical-and, bitwise 1922@cindex bitwise logical-and 1923@item (and:@var{m} @var{x} @var{y}) 1924Represents the bitwise logical-and of the values represented by 1925@var{x} and @var{y}, carried out in machine mode @var{m}, which must be 1926a fixed-point machine mode. 1927 1928@findex ior 1929@cindex inclusive-or, bitwise 1930@cindex bitwise inclusive-or 1931@item (ior:@var{m} @var{x} @var{y}) 1932Represents the bitwise inclusive-or of the values represented by @var{x} 1933and @var{y}, carried out in machine mode @var{m}, which must be a 1934fixed-point mode. 1935 1936@findex xor 1937@cindex exclusive-or, bitwise 1938@cindex bitwise exclusive-or 1939@item (xor:@var{m} @var{x} @var{y}) 1940Represents the bitwise exclusive-or of the values represented by @var{x} 1941and @var{y}, carried out in machine mode @var{m}, which must be a 1942fixed-point mode. 1943 1944@findex ashift 1945@cindex left shift 1946@cindex shift 1947@cindex arithmetic shift 1948@item (ashift:@var{m} @var{x} @var{c}) 1949Represents the result of arithmetically shifting @var{x} left by @var{c} 1950places. @var{x} have mode @var{m}, a fixed-point machine mode. @var{c} 1951be a fixed-point mode or be a constant with mode @code{VOIDmode}; which 1952mode is determined by the mode called for in the machine description 1953entry for the left-shift instruction. For example, on the VAX, the mode 1954of @var{c} is @code{QImode} regardless of @var{m}. 1955 1956@findex lshiftrt 1957@cindex right shift 1958@findex ashiftrt 1959@item (lshiftrt:@var{m} @var{x} @var{c}) 1960@itemx (ashiftrt:@var{m} @var{x} @var{c}) 1961Like @code{ashift} but for right shift. Unlike the case for left shift, 1962these two operations are distinct. 1963 1964@findex rotate 1965@cindex rotate 1966@cindex left rotate 1967@findex rotatert 1968@cindex right rotate 1969@item (rotate:@var{m} @var{x} @var{c}) 1970@itemx (rotatert:@var{m} @var{x} @var{c}) 1971Similar but represent left and right rotate. If @var{c} is a constant, 1972use @code{rotate}. 1973 1974@findex abs 1975@cindex absolute value 1976@item (abs:@var{m} @var{x}) 1977Represents the absolute value of @var{x}, computed in mode @var{m}. 1978 1979@findex sqrt 1980@cindex square root 1981@item (sqrt:@var{m} @var{x}) 1982Represents the square root of @var{x}, computed in mode @var{m}. 1983Most often @var{m} will be a floating point mode. 1984 1985@findex ffs 1986@item (ffs:@var{m} @var{x}) 1987Represents one plus the index of the least significant 1-bit in 1988@var{x}, represented as an integer of mode @var{m}. (The value is 1989zero if @var{x} is zero.) The mode of @var{x} need not be @var{m}; 1990depending on the target machine, various mode combinations may be 1991valid. 1992 1993@findex clz 1994@item (clz:@var{m} @var{x}) 1995Represents the number of leading 0-bits in @var{x}, represented as an 1996integer of mode @var{m}, starting at the most significant bit position. 1997If @var{x} is zero, the value is determined by 1998@code{CLZ_DEFINED_VALUE_AT_ZERO}. Note that this is one of 1999the few expressions that is not invariant under widening. The mode of 2000@var{x} will usually be an integer mode. 2001 2002@findex ctz 2003@item (ctz:@var{m} @var{x}) 2004Represents the number of trailing 0-bits in @var{x}, represented as an 2005integer of mode @var{m}, starting at the least significant bit position. 2006If @var{x} is zero, the value is determined by 2007@code{CTZ_DEFINED_VALUE_AT_ZERO}. Except for this case, 2008@code{ctz(x)} is equivalent to @code{ffs(@var{x}) - 1}. The mode of 2009@var{x} will usually be an integer mode. 2010 2011@findex popcount 2012@item (popcount:@var{m} @var{x}) 2013Represents the number of 1-bits in @var{x}, represented as an integer of 2014mode @var{m}. The mode of @var{x} will usually be an integer mode. 2015 2016@findex parity 2017@item (parity:@var{m} @var{x}) 2018Represents the number of 1-bits modulo 2 in @var{x}, represented as an 2019integer of mode @var{m}. The mode of @var{x} will usually be an integer 2020mode. 2021@end table 2022 2023@node Comparisons 2024@section Comparison Operations 2025@cindex RTL comparison operations 2026 2027Comparison operators test a relation on two operands and are considered 2028to represent a machine-dependent nonzero value described by, but not 2029necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc}) 2030if the relation holds, or zero if it does not, for comparison operators 2031whose results have a `MODE_INT' mode, and 2032@code{FLOAT_STORE_FLAG_VALUE} (@pxref{Misc}) if the relation holds, or 2033zero if it does not, for comparison operators that return floating-point 2034values. The mode of the comparison operation is independent of the mode 2035of the data being compared. If the comparison operation is being tested 2036(e.g., the first operand of an @code{if_then_else}), the mode must be 2037@code{VOIDmode}. 2038 2039@cindex condition codes 2040There are two ways that comparison operations may be used. The 2041comparison operators may be used to compare the condition codes 2042@code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such 2043a construct actually refers to the result of the preceding instruction 2044in which the condition codes were set. The instruction setting the 2045condition code must be adjacent to the instruction using the condition 2046code; only @code{note} insns may separate them. 2047 2048Alternatively, a comparison operation may directly compare two data 2049objects. The mode of the comparison is determined by the operands; they 2050must both be valid for a common machine mode. A comparison with both 2051operands constant would be invalid as the machine mode could not be 2052deduced from it, but such a comparison should never exist in RTL due to 2053constant folding. 2054 2055In the example above, if @code{(cc0)} were last set to 2056@code{(compare @var{x} @var{y})}, the comparison operation is 2057identical to @code{(eq @var{x} @var{y})}. Usually only one style 2058of comparisons is supported on a particular machine, but the combine 2059pass will try to merge the operations to produce the @code{eq} shown 2060in case it exists in the context of the particular insn involved. 2061 2062Inequality comparisons come in two flavors, signed and unsigned. Thus, 2063there are distinct expression codes @code{gt} and @code{gtu} for signed and 2064unsigned greater-than. These can produce different results for the same 2065pair of integer values: for example, 1 is signed greater-than @minus{}1 but not 2066unsigned greater-than, because @minus{}1 when regarded as unsigned is actually 2067@code{0xffffffff} which is greater than 1. 2068 2069The signed comparisons are also used for floating point values. Floating 2070point comparisons are distinguished by the machine modes of the operands. 2071 2072@table @code 2073@findex eq 2074@cindex equal 2075@item (eq:@var{m} @var{x} @var{y}) 2076@code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y} 2077are equal, otherwise 0. 2078 2079@findex ne 2080@cindex not equal 2081@item (ne:@var{m} @var{x} @var{y}) 2082@code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y} 2083are not equal, otherwise 0. 2084 2085@findex gt 2086@cindex greater than 2087@item (gt:@var{m} @var{x} @var{y}) 2088@code{STORE_FLAG_VALUE} if the @var{x} is greater than @var{y}. If they 2089are fixed-point, the comparison is done in a signed sense. 2090 2091@findex gtu 2092@cindex greater than 2093@cindex unsigned greater than 2094@item (gtu:@var{m} @var{x} @var{y}) 2095Like @code{gt} but does unsigned comparison, on fixed-point numbers only. 2096 2097@findex lt 2098@cindex less than 2099@findex ltu 2100@cindex unsigned less than 2101@item (lt:@var{m} @var{x} @var{y}) 2102@itemx (ltu:@var{m} @var{x} @var{y}) 2103Like @code{gt} and @code{gtu} but test for ``less than''. 2104 2105@findex ge 2106@cindex greater than 2107@findex geu 2108@cindex unsigned greater than 2109@item (ge:@var{m} @var{x} @var{y}) 2110@itemx (geu:@var{m} @var{x} @var{y}) 2111Like @code{gt} and @code{gtu} but test for ``greater than or equal''. 2112 2113@findex le 2114@cindex less than or equal 2115@findex leu 2116@cindex unsigned less than 2117@item (le:@var{m} @var{x} @var{y}) 2118@itemx (leu:@var{m} @var{x} @var{y}) 2119Like @code{gt} and @code{gtu} but test for ``less than or equal''. 2120 2121@findex if_then_else 2122@item (if_then_else @var{cond} @var{then} @var{else}) 2123This is not a comparison operation but is listed here because it is 2124always used in conjunction with a comparison operation. To be 2125precise, @var{cond} is a comparison expression. This expression 2126represents a choice, according to @var{cond}, between the value 2127represented by @var{then} and the one represented by @var{else}. 2128 2129On most machines, @code{if_then_else} expressions are valid only 2130to express conditional jumps. 2131 2132@findex cond 2133@item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default}) 2134Similar to @code{if_then_else}, but more general. Each of @var{test1}, 2135@var{test2}, @dots{} is performed in turn. The result of this expression is 2136the @var{value} corresponding to the first nonzero test, or @var{default} if 2137none of the tests are nonzero expressions. 2138 2139This is currently not valid for instruction patterns and is supported only 2140for insn attributes. @xref{Insn Attributes}. 2141@end table 2142 2143@node Bit-Fields 2144@section Bit-Fields 2145@cindex bit-fields 2146 2147Special expression codes exist to represent bit-field instructions. 2148These types of expressions are lvalues in RTL; they may appear 2149on the left side of an assignment, indicating insertion of a value 2150into the specified bit-field. 2151 2152@table @code 2153@findex sign_extract 2154@cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract} 2155@item (sign_extract:@var{m} @var{loc} @var{size} @var{pos}) 2156This represents a reference to a sign-extended bit-field contained or 2157starting in @var{loc} (a memory or register reference). The bit-field 2158is @var{size} bits wide and starts at bit @var{pos}. The compilation 2159option @code{BITS_BIG_ENDIAN} says which end of the memory unit 2160@var{pos} counts from. 2161 2162If @var{loc} is in memory, its mode must be a single-byte integer mode. 2163If @var{loc} is in a register, the mode to use is specified by the 2164operand of the @code{insv} or @code{extv} pattern 2165(@pxref{Standard Names}) and is usually a full-word integer mode, 2166which is the default if none is specified. 2167 2168The mode of @var{pos} is machine-specific and is also specified 2169in the @code{insv} or @code{extv} pattern. 2170 2171The mode @var{m} is the same as the mode that would be used for 2172@var{loc} if it were a register. 2173 2174@findex zero_extract 2175@item (zero_extract:@var{m} @var{loc} @var{size} @var{pos}) 2176Like @code{sign_extract} but refers to an unsigned or zero-extended 2177bit-field. The same sequence of bits are extracted, but they 2178are filled to an entire word with zeros instead of by sign-extension. 2179@end table 2180 2181@node Vector Operations 2182@section Vector Operations 2183@cindex vector operations 2184 2185All normal RTL expressions can be used with vector modes; they are 2186interpreted as operating on each part of the vector independently. 2187Additionally, there are a few new expressions to describe specific vector 2188operations. 2189 2190@table @code 2191@findex vec_merge 2192@item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items}) 2193This describes a merge operation between two vectors. The result is a vector 2194of mode @var{m}; its elements are selected from either @var{vec1} or 2195@var{vec2}. Which elements are selected is described by @var{items}, which 2196is a bit mask represented by a @code{const_int}; a zero bit indicates the 2197corresponding element in the result vector is taken from @var{vec2} while 2198a set bit indicates it is taken from @var{vec1}. 2199 2200@findex vec_select 2201@item (vec_select:@var{m} @var{vec1} @var{selection}) 2202This describes an operation that selects parts of a vector. @var{vec1} is 2203the source vector, @var{selection} is a @code{parallel} that contains a 2204@code{const_int} for each of the subparts of the result vector, giving the 2205number of the source subpart that should be stored into it. 2206 2207@findex vec_concat 2208@item (vec_concat:@var{m} @var{vec1} @var{vec2}) 2209Describes a vector concat operation. The result is a concatenation of the 2210vectors @var{vec1} and @var{vec2}; its length is the sum of the lengths of 2211the two inputs. 2212 2213@findex vec_duplicate 2214@item (vec_duplicate:@var{m} @var{vec}) 2215This operation converts a small vector into a larger one by duplicating the 2216input values. The output vector mode must have the same submodes as the 2217input vector mode, and the number of output parts must be an integer multiple 2218of the number of input parts. 2219 2220@end table 2221 2222@node Conversions 2223@section Conversions 2224@cindex conversions 2225@cindex machine mode conversions 2226 2227All conversions between machine modes must be represented by 2228explicit conversion operations. For example, an expression 2229which is the sum of a byte and a full word cannot be written as 2230@code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus} 2231operation requires two operands of the same machine mode. 2232Therefore, the byte-sized operand is enclosed in a conversion 2233operation, as in 2234 2235@smallexample 2236(plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80)) 2237@end smallexample 2238 2239The conversion operation is not a mere placeholder, because there 2240may be more than one way of converting from a given starting mode 2241to the desired final mode. The conversion operation code says how 2242to do it. 2243 2244For all conversion operations, @var{x} must not be @code{VOIDmode} 2245because the mode in which to do the conversion would not be known. 2246The conversion must either be done at compile-time or @var{x} 2247must be placed into a register. 2248 2249@table @code 2250@findex sign_extend 2251@item (sign_extend:@var{m} @var{x}) 2252Represents the result of sign-extending the value @var{x} 2253to machine mode @var{m}. @var{m} must be a fixed-point mode 2254and @var{x} a fixed-point value of a mode narrower than @var{m}. 2255 2256@findex zero_extend 2257@item (zero_extend:@var{m} @var{x}) 2258Represents the result of zero-extending the value @var{x} 2259to machine mode @var{m}. @var{m} must be a fixed-point mode 2260and @var{x} a fixed-point value of a mode narrower than @var{m}. 2261 2262@findex float_extend 2263@item (float_extend:@var{m} @var{x}) 2264Represents the result of extending the value @var{x} 2265to machine mode @var{m}. @var{m} must be a floating point mode 2266and @var{x} a floating point value of a mode narrower than @var{m}. 2267 2268@findex truncate 2269@item (truncate:@var{m} @var{x}) 2270Represents the result of truncating the value @var{x} 2271to machine mode @var{m}. @var{m} must be a fixed-point mode 2272and @var{x} a fixed-point value of a mode wider than @var{m}. 2273 2274@findex ss_truncate 2275@item (ss_truncate:@var{m} @var{x}) 2276Represents the result of truncating the value @var{x} 2277to machine mode @var{m}, using signed saturation in the case of 2278overflow. Both @var{m} and the mode of @var{x} must be fixed-point 2279modes. 2280 2281@findex us_truncate 2282@item (us_truncate:@var{m} @var{x}) 2283Represents the result of truncating the value @var{x} 2284to machine mode @var{m}, using unsigned saturation in the case of 2285overflow. Both @var{m} and the mode of @var{x} must be fixed-point 2286modes. 2287 2288@findex float_truncate 2289@item (float_truncate:@var{m} @var{x}) 2290Represents the result of truncating the value @var{x} 2291to machine mode @var{m}. @var{m} must be a floating point mode 2292and @var{x} a floating point value of a mode wider than @var{m}. 2293 2294@findex float 2295@item (float:@var{m} @var{x}) 2296Represents the result of converting fixed point value @var{x}, 2297regarded as signed, to floating point mode @var{m}. 2298 2299@findex unsigned_float 2300@item (unsigned_float:@var{m} @var{x}) 2301Represents the result of converting fixed point value @var{x}, 2302regarded as unsigned, to floating point mode @var{m}. 2303 2304@findex fix 2305@item (fix:@var{m} @var{x}) 2306When @var{m} is a fixed point mode, represents the result of 2307converting floating point value @var{x} to mode @var{m}, regarded as 2308signed. How rounding is done is not specified, so this operation may 2309be used validly in compiling C code only for integer-valued operands. 2310 2311@findex unsigned_fix 2312@item (unsigned_fix:@var{m} @var{x}) 2313Represents the result of converting floating point value @var{x} to 2314fixed point mode @var{m}, regarded as unsigned. How rounding is done 2315is not specified. 2316 2317@findex fix 2318@item (fix:@var{m} @var{x}) 2319When @var{m} is a floating point mode, represents the result of 2320converting floating point value @var{x} (valid for mode @var{m}) to an 2321integer, still represented in floating point mode @var{m}, by rounding 2322towards zero. 2323@end table 2324 2325@node RTL Declarations 2326@section Declarations 2327@cindex RTL declarations 2328@cindex declarations, RTL 2329 2330Declaration expression codes do not represent arithmetic operations 2331but rather state assertions about their operands. 2332 2333@table @code 2334@findex strict_low_part 2335@cindex @code{subreg}, in @code{strict_low_part} 2336@item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0)) 2337This expression code is used in only one context: as the destination operand of a 2338@code{set} expression. In addition, the operand of this expression 2339must be a non-paradoxical @code{subreg} expression. 2340 2341The presence of @code{strict_low_part} says that the part of the 2342register which is meaningful in mode @var{n}, but is not part of 2343mode @var{m}, is not to be altered. Normally, an assignment to such 2344a subreg is allowed to have undefined effects on the rest of the 2345register when @var{m} is less than a word. 2346@end table 2347 2348@node Side Effects 2349@section Side Effect Expressions 2350@cindex RTL side effect expressions 2351 2352The expression codes described so far represent values, not actions. 2353But machine instructions never produce values; they are meaningful 2354only for their side effects on the state of the machine. Special 2355expression codes are used to represent side effects. 2356 2357The body of an instruction is always one of these side effect codes; 2358the codes described above, which represent values, appear only as 2359the operands of these. 2360 2361@table @code 2362@findex set 2363@item (set @var{lval} @var{x}) 2364Represents the action of storing the value of @var{x} into the place 2365represented by @var{lval}. @var{lval} must be an expression 2366representing a place that can be stored in: @code{reg} (or @code{subreg}, 2367@code{strict_low_part} or @code{zero_extract}), @code{mem}, @code{pc}, 2368@code{parallel}, or @code{cc0}. 2369 2370If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a 2371machine mode; then @var{x} must be valid for that mode. 2372 2373If @var{lval} is a @code{reg} whose machine mode is less than the full 2374width of the register, then it means that the part of the register 2375specified by the machine mode is given the specified value and the 2376rest of the register receives an undefined value. Likewise, if 2377@var{lval} is a @code{subreg} whose machine mode is narrower than 2378the mode of the register, the rest of the register can be changed in 2379an undefined way. 2380 2381If @var{lval} is a @code{strict_low_part} or @code{zero_extract} 2382of a @code{subreg}, then the part of the register specified by the 2383machine mode of the @code{subreg} is given the value @var{x} and 2384the rest of the register is not changed. 2385 2386If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may 2387be either a @code{compare} expression or a value that may have any mode. 2388The latter case represents a ``test'' instruction. The expression 2389@code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to 2390@code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}. 2391Use the former expression to save space during the compilation. 2392 2393If @var{lval} is a @code{parallel}, it is used to represent the case of 2394a function returning a structure in multiple registers. Each element 2395of the @code{parallel} is an @code{expr_list} whose first operand is a 2396@code{reg} and whose second operand is a @code{const_int} representing the 2397offset (in bytes) into the structure at which the data in that register 2398corresponds. The first element may be null to indicate that the structure 2399is also passed partly in memory. 2400 2401@cindex jump instructions and @code{set} 2402@cindex @code{if_then_else} usage 2403If @var{lval} is @code{(pc)}, we have a jump instruction, and the 2404possibilities for @var{x} are very limited. It may be a 2405@code{label_ref} expression (unconditional jump). It may be an 2406@code{if_then_else} (conditional jump), in which case either the 2407second or the third operand must be @code{(pc)} (for the case which 2408does not jump) and the other of the two must be a @code{label_ref} 2409(for the case which does jump). @var{x} may also be a @code{mem} or 2410@code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a 2411@code{mem}; these unusual patterns are used to represent jumps through 2412branch tables. 2413 2414If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of 2415@var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be 2416valid for the mode of @var{lval}. 2417 2418@findex SET_DEST 2419@findex SET_SRC 2420@var{lval} is customarily accessed with the @code{SET_DEST} macro and 2421@var{x} with the @code{SET_SRC} macro. 2422 2423@findex return 2424@item (return) 2425As the sole expression in a pattern, represents a return from the 2426current function, on machines where this can be done with one 2427instruction, such as VAXen. On machines where a multi-instruction 2428``epilogue'' must be executed in order to return from the function, 2429returning is done by jumping to a label which precedes the epilogue, and 2430the @code{return} expression code is never used. 2431 2432Inside an @code{if_then_else} expression, represents the value to be 2433placed in @code{pc} to return to the caller. 2434 2435Note that an insn pattern of @code{(return)} is logically equivalent to 2436@code{(set (pc) (return))}, but the latter form is never used. 2437 2438@findex call 2439@item (call @var{function} @var{nargs}) 2440Represents a function call. @var{function} is a @code{mem} expression 2441whose address is the address of the function to be called. 2442@var{nargs} is an expression which can be used for two purposes: on 2443some machines it represents the number of bytes of stack argument; on 2444others, it represents the number of argument registers. 2445 2446Each machine has a standard machine mode which @var{function} must 2447have. The machine description defines macro @code{FUNCTION_MODE} to 2448expand into the requisite mode name. The purpose of this mode is to 2449specify what kind of addressing is allowed, on machines where the 2450allowed kinds of addressing depend on the machine mode being 2451addressed. 2452 2453@findex clobber 2454@item (clobber @var{x}) 2455Represents the storing or possible storing of an unpredictable, 2456undescribed value into @var{x}, which must be a @code{reg}, 2457@code{scratch}, @code{parallel} or @code{mem} expression. 2458 2459One place this is used is in string instructions that store standard 2460values into particular hard registers. It may not be worth the 2461trouble to describe the values that are stored, but it is essential to 2462inform the compiler that the registers will be altered, lest it 2463attempt to keep data in them across the string instruction. 2464 2465If @var{x} is @code{(mem:BLK (const_int 0))} or 2466@code{(mem:BLK (scratch))}, it means that all memory 2467locations must be presumed clobbered. If @var{x} is a @code{parallel}, 2468it has the same meaning as a @code{parallel} in a @code{set} expression. 2469 2470Note that the machine description classifies certain hard registers as 2471``call-clobbered''. All function call instructions are assumed by 2472default to clobber these registers, so there is no need to use 2473@code{clobber} expressions to indicate this fact. Also, each function 2474call is assumed to have the potential to alter any memory location, 2475unless the function is declared @code{const}. 2476 2477If the last group of expressions in a @code{parallel} are each a 2478@code{clobber} expression whose arguments are @code{reg} or 2479@code{match_scratch} (@pxref{RTL Template}) expressions, the combiner 2480phase can add the appropriate @code{clobber} expressions to an insn it 2481has constructed when doing so will cause a pattern to be matched. 2482 2483This feature can be used, for example, on a machine that whose multiply 2484and add instructions don't use an MQ register but which has an 2485add-accumulate instruction that does clobber the MQ register. Similarly, 2486a combined instruction might require a temporary register while the 2487constituent instructions might not. 2488 2489When a @code{clobber} expression for a register appears inside a 2490@code{parallel} with other side effects, the register allocator 2491guarantees that the register is unoccupied both before and after that 2492insn. However, the reload phase may allocate a register used for one of 2493the inputs unless the @samp{&} constraint is specified for the selected 2494alternative (@pxref{Modifiers}). You can clobber either a specific hard 2495register, a pseudo register, or a @code{scratch} expression; in the 2496latter two cases, GCC will allocate a hard register that is available 2497there for use as a temporary. 2498 2499For instructions that require a temporary register, you should use 2500@code{scratch} instead of a pseudo-register because this will allow the 2501combiner phase to add the @code{clobber} when required. You do this by 2502coding (@code{clobber} (@code{match_scratch} @dots{})). If you do 2503clobber a pseudo register, use one which appears nowhere else---generate 2504a new one each time. Otherwise, you may confuse CSE@. 2505 2506There is one other known use for clobbering a pseudo register in a 2507@code{parallel}: when one of the input operands of the insn is also 2508clobbered by the insn. In this case, using the same pseudo register in 2509the clobber and elsewhere in the insn produces the expected results. 2510 2511@findex use 2512@item (use @var{x}) 2513Represents the use of the value of @var{x}. It indicates that the 2514value in @var{x} at this point in the program is needed, even though 2515it may not be apparent why this is so. Therefore, the compiler will 2516not attempt to delete previous instructions whose only effect is to 2517store a value in @var{x}. @var{x} must be a @code{reg} expression. 2518 2519In some situations, it may be tempting to add a @code{use} of a 2520register in a @code{parallel} to describe a situation where the value 2521of a special register will modify the behavior of the instruction. 2522An hypothetical example might be a pattern for an addition that can 2523either wrap around or use saturating addition depending on the value 2524of a special control register: 2525 2526@smallexample 2527(parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3) 2528 (reg:SI 4)] 0)) 2529 (use (reg:SI 1))]) 2530@end smallexample 2531 2532@noindent 2533 2534This will not work, several of the optimizers only look at expressions 2535locally; it is very likely that if you have multiple insns with 2536identical inputs to the @code{unspec}, they will be optimized away even 2537if register 1 changes in between. 2538 2539This means that @code{use} can @emph{only} be used to describe 2540that the register is live. You should think twice before adding 2541@code{use} statements, more often you will want to use @code{unspec} 2542instead. The @code{use} RTX is most commonly useful to describe that 2543a fixed register is implicitly used in an insn. It is also safe to use 2544in patterns where the compiler knows for other reasons that the result 2545of the whole pattern is variable, such as @samp{movstr@var{m}} or 2546@samp{call} patterns. 2547 2548During the reload phase, an insn that has a @code{use} as pattern 2549can carry a reg_equal note. These @code{use} insns will be deleted 2550before the reload phase exits. 2551 2552During the delayed branch scheduling phase, @var{x} may be an insn. 2553This indicates that @var{x} previously was located at this place in the 2554code and its data dependencies need to be taken into account. These 2555@code{use} insns will be deleted before the delayed branch scheduling 2556phase exits. 2557 2558@findex parallel 2559@item (parallel [@var{x0} @var{x1} @dots{}]) 2560Represents several side effects performed in parallel. The square 2561brackets stand for a vector; the operand of @code{parallel} is a 2562vector of expressions. @var{x0}, @var{x1} and so on are individual 2563side effect expressions---expressions of code @code{set}, @code{call}, 2564@code{return}, @code{clobber} or @code{use}. 2565 2566``In parallel'' means that first all the values used in the individual 2567side-effects are computed, and second all the actual side-effects are 2568performed. For example, 2569 2570@smallexample 2571(parallel [(set (reg:SI 1) (mem:SI (reg:SI 1))) 2572 (set (mem:SI (reg:SI 1)) (reg:SI 1))]) 2573@end smallexample 2574 2575@noindent 2576says unambiguously that the values of hard register 1 and the memory 2577location addressed by it are interchanged. In both places where 2578@code{(reg:SI 1)} appears as a memory address it refers to the value 2579in register 1 @emph{before} the execution of the insn. 2580 2581It follows that it is @emph{incorrect} to use @code{parallel} and 2582expect the result of one @code{set} to be available for the next one. 2583For example, people sometimes attempt to represent a jump-if-zero 2584instruction this way: 2585 2586@smallexample 2587(parallel [(set (cc0) (reg:SI 34)) 2588 (set (pc) (if_then_else 2589 (eq (cc0) (const_int 0)) 2590 (label_ref @dots{}) 2591 (pc)))]) 2592@end smallexample 2593 2594@noindent 2595But this is incorrect, because it says that the jump condition depends 2596on the condition code value @emph{before} this instruction, not on the 2597new value that is set by this instruction. 2598 2599@cindex peephole optimization, RTL representation 2600Peephole optimization, which takes place together with final assembly 2601code output, can produce insns whose patterns consist of a @code{parallel} 2602whose elements are the operands needed to output the resulting 2603assembler code---often @code{reg}, @code{mem} or constant expressions. 2604This would not be well-formed RTL at any other stage in compilation, 2605but it is ok then because no further optimization remains to be done. 2606However, the definition of the macro @code{NOTICE_UPDATE_CC}, if 2607any, must deal with such insns if you define any peephole optimizations. 2608 2609@findex cond_exec 2610@item (cond_exec [@var{cond} @var{expr}]) 2611Represents a conditionally executed expression. The @var{expr} is 2612executed only if the @var{cond} is nonzero. The @var{cond} expression 2613must not have side-effects, but the @var{expr} may very well have 2614side-effects. 2615 2616@findex sequence 2617@item (sequence [@var{insns} @dots{}]) 2618Represents a sequence of insns. Each of the @var{insns} that appears 2619in the vector is suitable for appearing in the chain of insns, so it 2620must be an @code{insn}, @code{jump_insn}, @code{call_insn}, 2621@code{code_label}, @code{barrier} or @code{note}. 2622 2623A @code{sequence} RTX is never placed in an actual insn during RTL 2624generation. It represents the sequence of insns that result from a 2625@code{define_expand} @emph{before} those insns are passed to 2626@code{emit_insn} to insert them in the chain of insns. When actually 2627inserted, the individual sub-insns are separated out and the 2628@code{sequence} is forgotten. 2629 2630After delay-slot scheduling is completed, an insn and all the insns that 2631reside in its delay slots are grouped together into a @code{sequence}. 2632The insn requiring the delay slot is the first insn in the vector; 2633subsequent insns are to be placed in the delay slot. 2634 2635@code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to 2636indicate that a branch insn should be used that will conditionally annul 2637the effect of the insns in the delay slots. In such a case, 2638@code{INSN_FROM_TARGET_P} indicates that the insn is from the target of 2639the branch and should be executed only if the branch is taken; otherwise 2640the insn should be executed only if the branch is not taken. 2641@xref{Delay Slots}. 2642@end table 2643 2644These expression codes appear in place of a side effect, as the body of 2645an insn, though strictly speaking they do not always describe side 2646effects as such: 2647 2648@table @code 2649@findex asm_input 2650@item (asm_input @var{s}) 2651Represents literal assembler code as described by the string @var{s}. 2652 2653@findex unspec 2654@findex unspec_volatile 2655@item (unspec [@var{operands} @dots{}] @var{index}) 2656@itemx (unspec_volatile [@var{operands} @dots{}] @var{index}) 2657Represents a machine-specific operation on @var{operands}. @var{index} 2658selects between multiple machine-specific operations. 2659@code{unspec_volatile} is used for volatile operations and operations 2660that may trap; @code{unspec} is used for other operations. 2661 2662These codes may appear inside a @code{pattern} of an 2663insn, inside a @code{parallel}, or inside an expression. 2664 2665@findex addr_vec 2666@item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}]) 2667Represents a table of jump addresses. The vector elements @var{lr0}, 2668etc., are @code{label_ref} expressions. The mode @var{m} specifies 2669how much space is given to each address; normally @var{m} would be 2670@code{Pmode}. 2671 2672@findex addr_diff_vec 2673@item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags}) 2674Represents a table of jump addresses expressed as offsets from 2675@var{base}. The vector elements @var{lr0}, etc., are @code{label_ref} 2676expressions and so is @var{base}. The mode @var{m} specifies how much 2677space is given to each address-difference. @var{min} and @var{max} 2678are set up by branch shortening and hold a label with a minimum and a 2679maximum address, respectively. @var{flags} indicates the relative 2680position of @var{base}, @var{min} and @var{max} to the containing insn 2681and of @var{min} and @var{max} to @var{base}. See rtl.def for details. 2682 2683@findex prefetch 2684@item (prefetch:@var{m} @var{addr} @var{rw} @var{locality}) 2685Represents prefetch of memory at address @var{addr}. 2686Operand @var{rw} is 1 if the prefetch is for data to be written, 0 otherwise; 2687targets that do not support write prefetches should treat this as a normal 2688prefetch. 2689Operand @var{locality} specifies the amount of temporal locality; 0 if there 2690is none or 1, 2, or 3 for increasing levels of temporal locality; 2691targets that do not support locality hints should ignore this. 2692 2693This insn is used to minimize cache-miss latency by moving data into a 2694cache before it is accessed. It should use only non-faulting data prefetch 2695instructions. 2696@end table 2697 2698@node Incdec 2699@section Embedded Side-Effects on Addresses 2700@cindex RTL preincrement 2701@cindex RTL postincrement 2702@cindex RTL predecrement 2703@cindex RTL postdecrement 2704 2705Six special side-effect expression codes appear as memory addresses. 2706 2707@table @code 2708@findex pre_dec 2709@item (pre_dec:@var{m} @var{x}) 2710Represents the side effect of decrementing @var{x} by a standard 2711amount and represents also the value that @var{x} has after being 2712decremented. @var{x} must be a @code{reg} or @code{mem}, but most 2713machines allow only a @code{reg}. @var{m} must be the machine mode 2714for pointers on the machine in use. The amount @var{x} is decremented 2715by is the length in bytes of the machine mode of the containing memory 2716reference of which this expression serves as the address. Here is an 2717example of its use: 2718 2719@smallexample 2720(mem:DF (pre_dec:SI (reg:SI 39))) 2721@end smallexample 2722 2723@noindent 2724This says to decrement pseudo register 39 by the length of a @code{DFmode} 2725value and use the result to address a @code{DFmode} value. 2726 2727@findex pre_inc 2728@item (pre_inc:@var{m} @var{x}) 2729Similar, but specifies incrementing @var{x} instead of decrementing it. 2730 2731@findex post_dec 2732@item (post_dec:@var{m} @var{x}) 2733Represents the same side effect as @code{pre_dec} but a different 2734value. The value represented here is the value @var{x} has @i{before} 2735being decremented. 2736 2737@findex post_inc 2738@item (post_inc:@var{m} @var{x}) 2739Similar, but specifies incrementing @var{x} instead of decrementing it. 2740 2741@findex post_modify 2742@item (post_modify:@var{m} @var{x} @var{y}) 2743 2744Represents the side effect of setting @var{x} to @var{y} and 2745represents @var{x} before @var{x} is modified. @var{x} must be a 2746@code{reg} or @code{mem}, but most machines allow only a @code{reg}. 2747@var{m} must be the machine mode for pointers on the machine in use. 2748 2749The expression @var{y} must be one of three forms: 2750@table @code 2751@code{(plus:@var{m} @var{x} @var{z})}, 2752@code{(minus:@var{m} @var{x} @var{z})}, or 2753@code{(plus:@var{m} @var{x} @var{i})}, 2754@end table 2755where @var{z} is an index register and @var{i} is a constant. 2756 2757Here is an example of its use: 2758 2759@smallexample 2760(mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42) 2761 (reg:SI 48)))) 2762@end smallexample 2763 2764This says to modify pseudo register 42 by adding the contents of pseudo 2765register 48 to it, after the use of what ever 42 points to. 2766 2767@findex pre_modify 2768@item (pre_modify:@var{m} @var{x} @var{expr}) 2769Similar except side effects happen before the use. 2770@end table 2771 2772These embedded side effect expressions must be used with care. Instruction 2773patterns may not use them. Until the @samp{flow} pass of the compiler, 2774they may occur only to represent pushes onto the stack. The @samp{flow} 2775pass finds cases where registers are incremented or decremented in one 2776instruction and used as an address shortly before or after; these cases are 2777then transformed to use pre- or post-increment or -decrement. 2778 2779If a register used as the operand of these expressions is used in 2780another address in an insn, the original value of the register is used. 2781Uses of the register outside of an address are not permitted within the 2782same insn as a use in an embedded side effect expression because such 2783insns behave differently on different machines and hence must be treated 2784as ambiguous and disallowed. 2785 2786An instruction that can be represented with an embedded side effect 2787could also be represented using @code{parallel} containing an additional 2788@code{set} to describe how the address register is altered. This is not 2789done because machines that allow these operations at all typically 2790allow them wherever a memory address is called for. Describing them as 2791additional parallel stores would require doubling the number of entries 2792in the machine description. 2793 2794@node Assembler 2795@section Assembler Instructions as Expressions 2796@cindex assembler instructions in RTL 2797 2798@cindex @code{asm_operands}, usage 2799The RTX code @code{asm_operands} represents a value produced by a 2800user-specified assembler instruction. It is used to represent 2801an @code{asm} statement with arguments. An @code{asm} statement with 2802a single output operand, like this: 2803 2804@smallexample 2805asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z)); 2806@end smallexample 2807 2808@noindent 2809is represented using a single @code{asm_operands} RTX which represents 2810the value that is stored in @code{outputvar}: 2811 2812@smallexample 2813(set @var{rtx-for-outputvar} 2814 (asm_operands "foo %1,%2,%0" "a" 0 2815 [@var{rtx-for-addition-result} @var{rtx-for-*z}] 2816 [(asm_input:@var{m1} "g") 2817 (asm_input:@var{m2} "di")])) 2818@end smallexample 2819 2820@noindent 2821Here the operands of the @code{asm_operands} RTX are the assembler 2822template string, the output-operand's constraint, the index-number of the 2823output operand among the output operands specified, a vector of input 2824operand RTX's, and a vector of input-operand modes and constraints. The 2825mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of 2826@code{*z}. 2827 2828When an @code{asm} statement has multiple output values, its insn has 2829several such @code{set} RTX's inside of a @code{parallel}. Each @code{set} 2830contains a @code{asm_operands}; all of these share the same assembler 2831template and vectors, but each contains the constraint for the respective 2832output operand. They are also distinguished by the output-operand index 2833number, which is 0, 1, @dots{} for successive output operands. 2834 2835@node Insns 2836@section Insns 2837@cindex insns 2838 2839The RTL representation of the code for a function is a doubly-linked 2840chain of objects called @dfn{insns}. Insns are expressions with 2841special codes that are used for no other purpose. Some insns are 2842actual instructions; others represent dispatch tables for @code{switch} 2843statements; others represent labels to jump to or various sorts of 2844declarative information. 2845 2846In addition to its own specific data, each insn must have a unique 2847id-number that distinguishes it from all other insns in the current 2848function (after delayed branch scheduling, copies of an insn with the 2849same id-number may be present in multiple places in a function, but 2850these copies will always be identical and will only appear inside a 2851@code{sequence}), and chain pointers to the preceding and following 2852insns. These three fields occupy the same position in every insn, 2853independent of the expression code of the insn. They could be accessed 2854with @code{XEXP} and @code{XINT}, but instead three special macros are 2855always used: 2856 2857@table @code 2858@findex INSN_UID 2859@item INSN_UID (@var{i}) 2860Accesses the unique id of insn @var{i}. 2861 2862@findex PREV_INSN 2863@item PREV_INSN (@var{i}) 2864Accesses the chain pointer to the insn preceding @var{i}. 2865If @var{i} is the first insn, this is a null pointer. 2866 2867@findex NEXT_INSN 2868@item NEXT_INSN (@var{i}) 2869Accesses the chain pointer to the insn following @var{i}. 2870If @var{i} is the last insn, this is a null pointer. 2871@end table 2872 2873@findex get_insns 2874@findex get_last_insn 2875The first insn in the chain is obtained by calling @code{get_insns}; the 2876last insn is the result of calling @code{get_last_insn}. Within the 2877chain delimited by these insns, the @code{NEXT_INSN} and 2878@code{PREV_INSN} pointers must always correspond: if @var{insn} is not 2879the first insn, 2880 2881@smallexample 2882NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn} 2883@end smallexample 2884 2885@noindent 2886is always true and if @var{insn} is not the last insn, 2887 2888@smallexample 2889PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn} 2890@end smallexample 2891 2892@noindent 2893is always true. 2894 2895After delay slot scheduling, some of the insns in the chain might be 2896@code{sequence} expressions, which contain a vector of insns. The value 2897of @code{NEXT_INSN} in all but the last of these insns is the next insn 2898in the vector; the value of @code{NEXT_INSN} of the last insn in the vector 2899is the same as the value of @code{NEXT_INSN} for the @code{sequence} in 2900which it is contained. Similar rules apply for @code{PREV_INSN}. 2901 2902This means that the above invariants are not necessarily true for insns 2903inside @code{sequence} expressions. Specifically, if @var{insn} is the 2904first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))} 2905is the insn containing the @code{sequence} expression, as is the value 2906of @code{PREV_INSN (NEXT_INSN (@var{insn}))} if @var{insn} is the last 2907insn in the @code{sequence} expression. You can use these expressions 2908to find the containing @code{sequence} expression. 2909 2910Every insn has one of the following six expression codes: 2911 2912@table @code 2913@findex insn 2914@item insn 2915The expression code @code{insn} is used for instructions that do not jump 2916and do not do function calls. @code{sequence} expressions are always 2917contained in insns with code @code{insn} even if one of those insns 2918should jump or do function calls. 2919 2920Insns with code @code{insn} have four additional fields beyond the three 2921mandatory ones listed above. These four are described in a table below. 2922 2923@findex jump_insn 2924@item jump_insn 2925The expression code @code{jump_insn} is used for instructions that may 2926jump (or, more generally, may contain @code{label_ref} expressions). If 2927there is an instruction to return from the current function, it is 2928recorded as a @code{jump_insn}. 2929 2930@findex JUMP_LABEL 2931@code{jump_insn} insns have the same extra fields as @code{insn} insns, 2932accessed in the same way and in addition contain a field 2933@code{JUMP_LABEL} which is defined once jump optimization has completed. 2934 2935For simple conditional and unconditional jumps, this field contains 2936the @code{code_label} to which this insn will (possibly conditionally) 2937branch. In a more complex jump, @code{JUMP_LABEL} records one of the 2938labels that the insn refers to; the only way to find the others is to 2939scan the entire body of the insn. In an @code{addr_vec}, 2940@code{JUMP_LABEL} is @code{NULL_RTX}. 2941 2942Return insns count as jumps, but since they do not refer to any 2943labels, their @code{JUMP_LABEL} is @code{NULL_RTX}. 2944 2945@findex call_insn 2946@item call_insn 2947The expression code @code{call_insn} is used for instructions that may do 2948function calls. It is important to distinguish these instructions because 2949they imply that certain registers and memory locations may be altered 2950unpredictably. 2951 2952@findex CALL_INSN_FUNCTION_USAGE 2953@code{call_insn} insns have the same extra fields as @code{insn} insns, 2954accessed in the same way and in addition contain a field 2955@code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of 2956@code{expr_list} expressions) containing @code{use} and @code{clobber} 2957expressions that denote hard registers and @code{MEM}s used or 2958clobbered by the called function. 2959 2960A @code{MEM} generally points to a stack slots in which arguments passed 2961to the libcall by reference (@pxref{Register Arguments, 2962FUNCTION_ARG_PASS_BY_REFERENCE}) are stored. If the argument is 2963caller-copied (@pxref{Register Arguments, FUNCTION_ARG_CALLEE_COPIES}), 2964the stack slot will be mentioned in @code{CLOBBER} and @code{USE} 2965entries; if it's callee-copied, only a @code{USE} will appear, and the 2966@code{MEM} may point to addresses that are not stack slots. These 2967@code{MEM}s are used only in libcalls, because, unlike regular function 2968calls, @code{CONST_CALL}s (which libcalls generally are, @pxref{Flags, 2969CONST_CALL_P}) aren't assumed to read and write all memory, so flow 2970would consider the stores dead and remove them. Note that, since a 2971libcall must never return values in memory (@pxref{Aggregate Return, 2972RETURN_IN_MEMORY}), there will never be a @code{CLOBBER} for a memory 2973address holding a return value. 2974 2975@code{CLOBBER}ed registers in this list augment registers specified in 2976@code{CALL_USED_REGISTERS} (@pxref{Register Basics}). 2977 2978@findex code_label 2979@findex CODE_LABEL_NUMBER 2980@item code_label 2981A @code{code_label} insn represents a label that a jump insn can jump 2982to. It contains two special fields of data in addition to the three 2983standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label 2984number}, a number that identifies this label uniquely among all the 2985labels in the compilation (not just in the current function). 2986Ultimately, the label is represented in the assembler output as an 2987assembler label, usually of the form @samp{L@var{n}} where @var{n} is 2988the label number. 2989 2990When a @code{code_label} appears in an RTL expression, it normally 2991appears within a @code{label_ref} which represents the address of 2992the label, as a number. 2993 2994Besides as a @code{code_label}, a label can also be represented as a 2995@code{note} of type @code{NOTE_INSN_DELETED_LABEL}. 2996 2997@findex LABEL_NUSES 2998The field @code{LABEL_NUSES} is only defined once the jump optimization 2999phase is completed. It contains the number of times this label is 3000referenced in the current function. 3001 3002@findex LABEL_KIND 3003@findex SET_LABEL_KIND 3004@findex LABEL_ALT_ENTRY_P 3005@cindex alternate entry points 3006The field @code{LABEL_KIND} differentiates four different types of 3007labels: @code{LABEL_NORMAL}, @code{LABEL_STATIC_ENTRY}, 3008@code{LABEL_GLOBAL_ENTRY}, and @code{LABEL_WEAK_ENTRY}. The only labels 3009that do not have type @code{LABEL_NORMAL} are @dfn{alternate entry 3010points} to the current function. These may be static (visible only in 3011the containing translation unit), global (exposed to all translation 3012units), or weak (global, but can be overridden by another symbol with the 3013same name). 3014 3015Much of the compiler treats all four kinds of label identically. Some 3016of it needs to know whether or not a label is an alternate entry point; 3017for this purpose, the macro @code{LABEL_ALT_ENTRY_P} is provided. It is 3018equivalent to testing whether @samp{LABEL_KIND (label) == LABEL_NORMAL}. 3019The only place that cares about the distinction between static, global, 3020and weak alternate entry points, besides the front-end code that creates 3021them, is the function @code{output_alternate_entry_point}, in 3022@file{final.c}. 3023 3024To set the kind of a label, use the @code{SET_LABEL_KIND} macro. 3025 3026@findex barrier 3027@item barrier 3028Barriers are placed in the instruction stream when control cannot flow 3029past them. They are placed after unconditional jump instructions to 3030indicate that the jumps are unconditional and after calls to 3031@code{volatile} functions, which do not return (e.g., @code{exit}). 3032They contain no information beyond the three standard fields. 3033 3034@findex note 3035@findex NOTE_LINE_NUMBER 3036@findex NOTE_SOURCE_FILE 3037@item note 3038@code{note} insns are used to represent additional debugging and 3039declarative information. They contain two nonstandard fields, an 3040integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a 3041string accessed with @code{NOTE_SOURCE_FILE}. 3042 3043If @code{NOTE_LINE_NUMBER} is positive, the note represents the 3044position of a source line and @code{NOTE_SOURCE_FILE} is the source file name 3045that the line came from. These notes control generation of line 3046number data in the assembler output. 3047 3048Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a 3049code with one of the following values (and @code{NOTE_SOURCE_FILE} 3050must contain a null pointer): 3051 3052@table @code 3053@findex NOTE_INSN_DELETED 3054@item NOTE_INSN_DELETED 3055Such a note is completely ignorable. Some passes of the compiler 3056delete insns by altering them into notes of this kind. 3057 3058@findex NOTE_INSN_DELETED_LABEL 3059@item NOTE_INSN_DELETED_LABEL 3060This marks what used to be a @code{code_label}, but was not used for other 3061purposes than taking its address and was transformed to mark that no 3062code jumps to it. 3063 3064@findex NOTE_INSN_BLOCK_BEG 3065@findex NOTE_INSN_BLOCK_END 3066@item NOTE_INSN_BLOCK_BEG 3067@itemx NOTE_INSN_BLOCK_END 3068These types of notes indicate the position of the beginning and end 3069of a level of scoping of variable names. They control the output 3070of debugging information. 3071 3072@findex NOTE_INSN_EH_REGION_BEG 3073@findex NOTE_INSN_EH_REGION_END 3074@item NOTE_INSN_EH_REGION_BEG 3075@itemx NOTE_INSN_EH_REGION_END 3076These types of notes indicate the position of the beginning and end of a 3077level of scoping for exception handling. @code{NOTE_BLOCK_NUMBER} 3078identifies which @code{CODE_LABEL} or @code{note} of type 3079@code{NOTE_INSN_DELETED_LABEL} is associated with the given region. 3080 3081@findex NOTE_INSN_LOOP_BEG 3082@findex NOTE_INSN_LOOP_END 3083@item NOTE_INSN_LOOP_BEG 3084@itemx NOTE_INSN_LOOP_END 3085These types of notes indicate the position of the beginning and end 3086of a @code{while} or @code{for} loop. They enable the loop optimizer 3087to find loops quickly. 3088 3089@findex NOTE_INSN_LOOP_CONT 3090@item NOTE_INSN_LOOP_CONT 3091Appears at the place in a loop that @code{continue} statements jump to. 3092 3093@findex NOTE_INSN_LOOP_VTOP 3094@item NOTE_INSN_LOOP_VTOP 3095This note indicates the place in a loop where the exit test begins for 3096those loops in which the exit test has been duplicated. This position 3097becomes another virtual start of the loop when considering loop 3098invariants. 3099 3100@findex NOTE_INSN_FUNCTION_END 3101@item NOTE_INSN_FUNCTION_END 3102Appears near the end of the function body, just before the label that 3103@code{return} statements jump to (on machine where a single instruction 3104does not suffice for returning). This note may be deleted by jump 3105optimization. 3106 3107@findex NOTE_INSN_SETJMP 3108@item NOTE_INSN_SETJMP 3109Appears following each call to @code{setjmp} or a related function. 3110@end table 3111 3112These codes are printed symbolically when they appear in debugging dumps. 3113@end table 3114 3115@cindex @code{TImode}, in @code{insn} 3116@cindex @code{HImode}, in @code{insn} 3117@cindex @code{QImode}, in @code{insn} 3118The machine mode of an insn is normally @code{VOIDmode}, but some 3119phases use the mode for various purposes. 3120 3121The common subexpression elimination pass sets the mode of an insn to 3122@code{QImode} when it is the first insn in a block that has already 3123been processed. 3124 3125The second Haifa scheduling pass, for targets that can multiple issue, 3126sets the mode of an insn to @code{TImode} when it is believed that the 3127instruction begins an issue group. That is, when the instruction 3128cannot issue simultaneously with the previous. This may be relied on 3129by later passes, in particular machine-dependent reorg. 3130 3131Here is a table of the extra fields of @code{insn}, @code{jump_insn} 3132and @code{call_insn} insns: 3133 3134@table @code 3135@findex PATTERN 3136@item PATTERN (@var{i}) 3137An expression for the side effect performed by this insn. This must be 3138one of the following codes: @code{set}, @code{call}, @code{use}, 3139@code{clobber}, @code{return}, @code{asm_input}, @code{asm_output}, 3140@code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec}, 3141@code{unspec_volatile}, @code{parallel}, @code{cond_exec}, or @code{sequence}. If it is a @code{parallel}, 3142each element of the @code{parallel} must be one these codes, except that 3143@code{parallel} expressions cannot be nested and @code{addr_vec} and 3144@code{addr_diff_vec} are not permitted inside a @code{parallel} expression. 3145 3146@findex INSN_CODE 3147@item INSN_CODE (@var{i}) 3148An integer that says which pattern in the machine description matches 3149this insn, or @minus{}1 if the matching has not yet been attempted. 3150 3151Such matching is never attempted and this field remains @minus{}1 on an insn 3152whose pattern consists of a single @code{use}, @code{clobber}, 3153@code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression. 3154 3155@findex asm_noperands 3156Matching is also never attempted on insns that result from an @code{asm} 3157statement. These contain at least one @code{asm_operands} expression. 3158The function @code{asm_noperands} returns a non-negative value for 3159such insns. 3160 3161In the debugging output, this field is printed as a number followed by 3162a symbolic representation that locates the pattern in the @file{md} 3163file as some small positive or negative offset from a named pattern. 3164 3165@findex LOG_LINKS 3166@item LOG_LINKS (@var{i}) 3167A list (chain of @code{insn_list} expressions) giving information about 3168dependencies between instructions within a basic block. Neither a jump 3169nor a label may come between the related insns. 3170 3171@findex REG_NOTES 3172@item REG_NOTES (@var{i}) 3173A list (chain of @code{expr_list} and @code{insn_list} expressions) 3174giving miscellaneous information about the insn. It is often 3175information pertaining to the registers used in this insn. 3176@end table 3177 3178The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list} 3179expressions. Each of these has two operands: the first is an insn, 3180and the second is another @code{insn_list} expression (the next one in 3181the chain). The last @code{insn_list} in the chain has a null pointer 3182as second operand. The significant thing about the chain is which 3183insns appear in it (as first operands of @code{insn_list} 3184expressions). Their order is not significant. 3185 3186This list is originally set up by the flow analysis pass; it is a null 3187pointer until then. Flow only adds links for those data dependencies 3188which can be used for instruction combination. For each insn, the flow 3189analysis pass adds a link to insns which store into registers values 3190that are used for the first time in this insn. The instruction 3191scheduling pass adds extra links so that every dependence will be 3192represented. Links represent data dependencies, antidependencies and 3193output dependencies; the machine mode of the link distinguishes these 3194three types: antidependencies have mode @code{REG_DEP_ANTI}, output 3195dependencies have mode @code{REG_DEP_OUTPUT}, and data dependencies have 3196mode @code{VOIDmode}. 3197 3198The @code{REG_NOTES} field of an insn is a chain similar to the 3199@code{LOG_LINKS} field but it includes @code{expr_list} expressions in 3200addition to @code{insn_list} expressions. There are several kinds of 3201register notes, which are distinguished by the machine mode, which in a 3202register note is really understood as being an @code{enum reg_note}. 3203The first operand @var{op} of the note is data whose meaning depends on 3204the kind of note. 3205 3206@findex REG_NOTE_KIND 3207@findex PUT_REG_NOTE_KIND 3208The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of 3209register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND 3210(@var{x}, @var{newkind})} sets the register note type of @var{x} to be 3211@var{newkind}. 3212 3213Register notes are of three classes: They may say something about an 3214input to an insn, they may say something about an output of an insn, or 3215they may create a linkage between two insns. There are also a set 3216of values that are only used in @code{LOG_LINKS}. 3217 3218These register notes annotate inputs to an insn: 3219 3220@table @code 3221@findex REG_DEAD 3222@item REG_DEAD 3223The value in @var{op} dies in this insn; that is to say, altering the 3224value immediately after this insn would not affect the future behavior 3225of the program. 3226 3227It does not follow that the register @var{op} has no useful value after 3228this insn since @var{op} is not necessarily modified by this insn. 3229Rather, no subsequent instruction uses the contents of @var{op}. 3230 3231@findex REG_UNUSED 3232@item REG_UNUSED 3233The register @var{op} being set by this insn will not be used in a 3234subsequent insn. This differs from a @code{REG_DEAD} note, which 3235indicates that the value in an input will not be used subsequently. 3236These two notes are independent; both may be present for the same 3237register. 3238 3239@findex REG_INC 3240@item REG_INC 3241The register @var{op} is incremented (or decremented; at this level 3242there is no distinction) by an embedded side effect inside this insn. 3243This means it appears in a @code{post_inc}, @code{pre_inc}, 3244@code{post_dec} or @code{pre_dec} expression. 3245 3246@findex REG_NONNEG 3247@item REG_NONNEG 3248The register @var{op} is known to have a nonnegative value when this 3249insn is reached. This is used so that decrement and branch until zero 3250instructions, such as the m68k dbra, can be matched. 3251 3252The @code{REG_NONNEG} note is added to insns only if the machine 3253description has a @samp{decrement_and_branch_until_zero} pattern. 3254 3255@findex REG_NO_CONFLICT 3256@item REG_NO_CONFLICT 3257This insn does not cause a conflict between @var{op} and the item 3258being set by this insn even though it might appear that it does. 3259In other words, if the destination register and @var{op} could 3260otherwise be assigned the same register, this insn does not 3261prevent that assignment. 3262 3263Insns with this note are usually part of a block that begins with a 3264@code{clobber} insn specifying a multi-word pseudo register (which will 3265be the output of the block), a group of insns that each set one word of 3266the value and have the @code{REG_NO_CONFLICT} note attached, and a final 3267insn that copies the output to itself with an attached @code{REG_EQUAL} 3268note giving the expression being computed. This block is encapsulated 3269with @code{REG_LIBCALL} and @code{REG_RETVAL} notes on the first and 3270last insns, respectively. 3271 3272@findex REG_LABEL 3273@item REG_LABEL 3274This insn uses @var{op}, a @code{code_label} or a @code{note} of type 3275@code{NOTE_INSN_DELETED_LABEL}, but is not a 3276@code{jump_insn}, or it is a @code{jump_insn} that required the label to 3277be held in a register. The presence of this note allows jump 3278optimization to be aware that @var{op} is, in fact, being used, and flow 3279optimization to build an accurate flow graph. 3280@end table 3281 3282The following notes describe attributes of outputs of an insn: 3283 3284@table @code 3285@findex REG_EQUIV 3286@findex REG_EQUAL 3287@item REG_EQUIV 3288@itemx REG_EQUAL 3289This note is only valid on an insn that sets only one register and 3290indicates that that register will be equal to @var{op} at run time; the 3291scope of this equivalence differs between the two types of notes. The 3292value which the insn explicitly copies into the register may look 3293different from @var{op}, but they will be equal at run time. If the 3294output of the single @code{set} is a @code{strict_low_part} expression, 3295the note refers to the register that is contained in @code{SUBREG_REG} 3296of the @code{subreg} expression. 3297 3298For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout 3299the entire function, and could validly be replaced in all its 3300occurrences by @var{op}. (``Validly'' here refers to the data flow of 3301the program; simple replacement may make some insns invalid.) For 3302example, when a constant is loaded into a register that is never 3303assigned any other value, this kind of note is used. 3304 3305When a parameter is copied into a pseudo-register at entry to a function, 3306a note of this kind records that the register is equivalent to the stack 3307slot where the parameter was passed. Although in this case the register 3308may be set by other insns, it is still valid to replace the register 3309by the stack slot throughout the function. 3310 3311A @code{REG_EQUIV} note is also used on an instruction which copies a 3312register parameter into a pseudo-register at entry to a function, if 3313there is a stack slot where that parameter could be stored. Although 3314other insns may set the pseudo-register, it is valid for the compiler to 3315replace the pseudo-register by stack slot throughout the function, 3316provided the compiler ensures that the stack slot is properly 3317initialized by making the replacement in the initial copy instruction as 3318well. This is used on machines for which the calling convention 3319allocates stack space for register parameters. See 3320@code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}. 3321 3322In the case of @code{REG_EQUAL}, the register that is set by this insn 3323will be equal to @var{op} at run time at the end of this insn but not 3324necessarily elsewhere in the function. In this case, @var{op} 3325is typically an arithmetic expression. For example, when a sequence of 3326insns such as a library call is used to perform an arithmetic operation, 3327this kind of note is attached to the insn that produces or copies the 3328final value. 3329 3330These two notes are used in different ways by the compiler passes. 3331@code{REG_EQUAL} is used by passes prior to register allocation (such as 3332common subexpression elimination and loop optimization) to tell them how 3333to think of that value. @code{REG_EQUIV} notes are used by register 3334allocation to indicate that there is an available substitute expression 3335(either a constant or a @code{mem} expression for the location of a 3336parameter on the stack) that may be used in place of a register if 3337insufficient registers are available. 3338 3339Except for stack homes for parameters, which are indicated by a 3340@code{REG_EQUIV} note and are not useful to the early optimization 3341passes and pseudo registers that are equivalent to a memory location 3342throughout their entire life, which is not detected until later in 3343the compilation, all equivalences are initially indicated by an attached 3344@code{REG_EQUAL} note. In the early stages of register allocation, a 3345@code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if 3346@var{op} is a constant and the insn represents the only set of its 3347destination register. 3348 3349Thus, compiler passes prior to register allocation need only check for 3350@code{REG_EQUAL} notes and passes subsequent to register allocation 3351need only check for @code{REG_EQUIV} notes. 3352@end table 3353 3354These notes describe linkages between insns. They occur in pairs: one 3355insn has one of a pair of notes that points to a second insn, which has 3356the inverse note pointing back to the first insn. 3357 3358@table @code 3359@findex REG_RETVAL 3360@item REG_RETVAL 3361This insn copies the value of a multi-insn sequence (for example, a 3362library call), and @var{op} is the first insn of the sequence (for a 3363library call, the first insn that was generated to set up the arguments 3364for the library call). 3365 3366Loop optimization uses this note to treat such a sequence as a single 3367operation for code motion purposes and flow analysis uses this note to 3368delete such sequences whose results are dead. 3369 3370A @code{REG_EQUAL} note will also usually be attached to this insn to 3371provide the expression being computed by the sequence. 3372 3373These notes will be deleted after reload, since they are no longer 3374accurate or useful. 3375 3376@findex REG_LIBCALL 3377@item REG_LIBCALL 3378This is the inverse of @code{REG_RETVAL}: it is placed on the first 3379insn of a multi-insn sequence, and it points to the last one. 3380 3381These notes are deleted after reload, since they are no longer useful or 3382accurate. 3383 3384@findex REG_CC_SETTER 3385@findex REG_CC_USER 3386@item REG_CC_SETTER 3387@itemx REG_CC_USER 3388On machines that use @code{cc0}, the insns which set and use @code{cc0} 3389set and use @code{cc0} are adjacent. However, when branch delay slot 3390filling is done, this may no longer be true. In this case a 3391@code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to 3392point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will 3393be placed on the insn using @code{cc0} to point to the insn setting 3394@code{cc0}. 3395@end table 3396 3397These values are only used in the @code{LOG_LINKS} field, and indicate 3398the type of dependency that each link represents. Links which indicate 3399a data dependence (a read after write dependence) do not use any code, 3400they simply have mode @code{VOIDmode}, and are printed without any 3401descriptive text. 3402 3403@table @code 3404@findex REG_DEP_ANTI 3405@item REG_DEP_ANTI 3406This indicates an anti dependence (a write after read dependence). 3407 3408@findex REG_DEP_OUTPUT 3409@item REG_DEP_OUTPUT 3410This indicates an output dependence (a write after write dependence). 3411@end table 3412 3413These notes describe information gathered from gcov profile data. They 3414are stored in the @code{REG_NOTES} field of an insn as an 3415@code{expr_list}. 3416 3417@table @code 3418@findex REG_BR_PROB 3419@item REG_BR_PROB 3420This is used to specify the ratio of branches to non-branches of a 3421branch insn according to the profile data. The value is stored as a 3422value between 0 and REG_BR_PROB_BASE; larger values indicate a higher 3423probability that the branch will be taken. 3424 3425@findex REG_BR_PRED 3426@item REG_BR_PRED 3427These notes are found in JUMP insns after delayed branch scheduling 3428has taken place. They indicate both the direction and the likelihood 3429of the JUMP@. The format is a bitmask of ATTR_FLAG_* values. 3430 3431@findex REG_FRAME_RELATED_EXPR 3432@item REG_FRAME_RELATED_EXPR 3433This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression 3434is used in place of the actual insn pattern. This is done in cases where 3435the pattern is either complex or misleading. 3436@end table 3437 3438For convenience, the machine mode in an @code{insn_list} or 3439@code{expr_list} is printed using these symbolic codes in debugging dumps. 3440 3441@findex insn_list 3442@findex expr_list 3443The only difference between the expression codes @code{insn_list} and 3444@code{expr_list} is that the first operand of an @code{insn_list} is 3445assumed to be an insn and is printed in debugging dumps as the insn's 3446unique id; the first operand of an @code{expr_list} is printed in the 3447ordinary way as an expression. 3448 3449@node Calls 3450@section RTL Representation of Function-Call Insns 3451@cindex calling functions in RTL 3452@cindex RTL function-call insns 3453@cindex function-call insns 3454 3455Insns that call subroutines have the RTL expression code @code{call_insn}. 3456These insns must satisfy special rules, and their bodies must use a special 3457RTL expression code, @code{call}. 3458 3459@cindex @code{call} usage 3460A @code{call} expression has two operands, as follows: 3461 3462@smallexample 3463(call (mem:@var{fm} @var{addr}) @var{nbytes}) 3464@end smallexample 3465 3466@noindent 3467Here @var{nbytes} is an operand that represents the number of bytes of 3468argument data being passed to the subroutine, @var{fm} is a machine mode 3469(which must equal as the definition of the @code{FUNCTION_MODE} macro in 3470the machine description) and @var{addr} represents the address of the 3471subroutine. 3472 3473For a subroutine that returns no value, the @code{call} expression as 3474shown above is the entire body of the insn, except that the insn might 3475also contain @code{use} or @code{clobber} expressions. 3476 3477@cindex @code{BLKmode}, and function return values 3478For a subroutine that returns a value whose mode is not @code{BLKmode}, 3479the value is returned in a hard register. If this register's number is 3480@var{r}, then the body of the call insn looks like this: 3481 3482@smallexample 3483(set (reg:@var{m} @var{r}) 3484 (call (mem:@var{fm} @var{addr}) @var{nbytes})) 3485@end smallexample 3486 3487@noindent 3488This RTL expression makes it clear (to the optimizer passes) that the 3489appropriate register receives a useful value in this insn. 3490 3491When a subroutine returns a @code{BLKmode} value, it is handled by 3492passing to the subroutine the address of a place to store the value. 3493So the call insn itself does not ``return'' any value, and it has the 3494same RTL form as a call that returns nothing. 3495 3496On some machines, the call instruction itself clobbers some register, 3497for example to contain the return address. @code{call_insn} insns 3498on these machines should have a body which is a @code{parallel} 3499that contains both the @code{call} expression and @code{clobber} 3500expressions that indicate which registers are destroyed. Similarly, 3501if the call instruction requires some register other than the stack 3502pointer that is not explicitly mentioned it its RTL, a @code{use} 3503subexpression should mention that register. 3504 3505Functions that are called are assumed to modify all registers listed in 3506the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register 3507Basics}) and, with the exception of @code{const} functions and library 3508calls, to modify all of memory. 3509 3510Insns containing just @code{use} expressions directly precede the 3511@code{call_insn} insn to indicate which registers contain inputs to the 3512function. Similarly, if registers other than those in 3513@code{CALL_USED_REGISTERS} are clobbered by the called function, insns 3514containing a single @code{clobber} follow immediately after the call to 3515indicate which registers. 3516 3517@node Sharing 3518@section Structure Sharing Assumptions 3519@cindex sharing of RTL components 3520@cindex RTL structure sharing assumptions 3521 3522The compiler assumes that certain kinds of RTL expressions are unique; 3523there do not exist two distinct objects representing the same value. 3524In other cases, it makes an opposite assumption: that no RTL expression 3525object of a certain kind appears in more than one place in the 3526containing structure. 3527 3528These assumptions refer to a single function; except for the RTL 3529objects that describe global variables and external functions, 3530and a few standard objects such as small integer constants, 3531no RTL objects are common to two functions. 3532 3533@itemize @bullet 3534@cindex @code{reg}, RTL sharing 3535@item 3536Each pseudo-register has only a single @code{reg} object to represent it, 3537and therefore only a single machine mode. 3538 3539@cindex symbolic label 3540@cindex @code{symbol_ref}, RTL sharing 3541@item 3542For any symbolic label, there is only one @code{symbol_ref} object 3543referring to it. 3544 3545@cindex @code{const_int}, RTL sharing 3546@item 3547All @code{const_int} expressions with equal values are shared. 3548 3549@cindex @code{pc}, RTL sharing 3550@item 3551There is only one @code{pc} expression. 3552 3553@cindex @code{cc0}, RTL sharing 3554@item 3555There is only one @code{cc0} expression. 3556 3557@cindex @code{const_double}, RTL sharing 3558@item 3559There is only one @code{const_double} expression with value 0 for 3560each floating point mode. Likewise for values 1 and 2. 3561 3562@cindex @code{const_vector}, RTL sharing 3563@item 3564There is only one @code{const_vector} expression with value 0 for 3565each vector mode, be it an integer or a double constant vector. 3566 3567@cindex @code{label_ref}, RTL sharing 3568@cindex @code{scratch}, RTL sharing 3569@item 3570No @code{label_ref} or @code{scratch} appears in more than one place in 3571the RTL structure; in other words, it is safe to do a tree-walk of all 3572the insns in the function and assume that each time a @code{label_ref} 3573or @code{scratch} is seen it is distinct from all others that are seen. 3574 3575@cindex @code{mem}, RTL sharing 3576@item 3577Only one @code{mem} object is normally created for each static 3578variable or stack slot, so these objects are frequently shared in all 3579the places they appear. However, separate but equal objects for these 3580variables are occasionally made. 3581 3582@cindex @code{asm_operands}, RTL sharing 3583@item 3584When a single @code{asm} statement has multiple output operands, a 3585distinct @code{asm_operands} expression is made for each output operand. 3586However, these all share the vector which contains the sequence of input 3587operands. This sharing is used later on to test whether two 3588@code{asm_operands} expressions come from the same statement, so all 3589optimizations must carefully preserve the sharing if they copy the 3590vector at all. 3591 3592@item 3593No RTL object appears in more than one place in the RTL structure 3594except as described above. Many passes of the compiler rely on this 3595by assuming that they can modify RTL objects in place without unwanted 3596side-effects on other insns. 3597 3598@findex unshare_all_rtl 3599@item 3600During initial RTL generation, shared structure is freely introduced. 3601After all the RTL for a function has been generated, all shared 3602structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c}, 3603after which the above rules are guaranteed to be followed. 3604 3605@findex copy_rtx_if_shared 3606@item 3607During the combiner pass, shared structure within an insn can exist 3608temporarily. However, the shared structure is copied before the 3609combiner is finished with the insn. This is done by calling 3610@code{copy_rtx_if_shared}, which is a subroutine of 3611@code{unshare_all_rtl}. 3612@end itemize 3613 3614@node Reading RTL 3615@section Reading RTL 3616 3617To read an RTL object from a file, call @code{read_rtx}. It takes one 3618argument, a stdio stream, and returns a single RTL object. This routine 3619is defined in @file{read-rtl.c}. It is not available in the compiler 3620itself, only the various programs that generate the compiler back end 3621from the machine description. 3622 3623People frequently have the idea of using RTL stored as text in a file as 3624an interface between a language front end and the bulk of GCC@. This 3625idea is not feasible. 3626 3627GCC was designed to use RTL internally only. Correct RTL for a given 3628program is very dependent on the particular target machine. And the RTL 3629does not contain all the information about the program. 3630 3631The proper way to interface GCC to a new language front end is with 3632the ``tree'' data structure, described in the files @file{tree.h} and 3633@file{tree.def}. The documentation for this structure (@pxref{Trees}) 3634is incomplete. 3635