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