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