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