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