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