rtl.texi revision 103445
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_IN_STRUCT_P} are clear, 505then we don't know whether this @code{mem} is in a structure or not. 506Both flags should never 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_vector 1160@item (const_vector:@var{m} [@var{x0} @var{x1} @dots{}]) 1161Represents a vector constant. The square brackets stand for the vector 1162containing the constant elements. @var{x0}, @var{x1} and so on are 1163the @code{const_int} or @code{const_double} elements. 1164 1165The number of units in a @code{const_vector} is obtained with the macro 1166@code{CONST_VECTOR_NUNITS} as in @code{CONST_VECTOR_NUNITS (@var{v})}. 1167 1168Individual elements in a vector constant are accessed with the macro 1169@code{CONST_VECTOR_ELT} as in @code{CONST_VECTOR_ELT (@var{v}, @var{n})} 1170where @var{v} is the vector constant and @var{n} is the element 1171desired. 1172 1173@findex CONST_DOUBLE_MEM 1174@findex CONST_DOUBLE_CHAIN 1175@var{addr} is used to contain the @code{mem} expression that corresponds 1176to the location in memory that at which the constant can be found. If 1177it has not been allocated a memory location, but is on the chain of all 1178@code{const_double} expressions in this compilation (maintained using an 1179undisplayed field), @var{addr} contains @code{const0_rtx}. If it is not 1180on the chain, @var{addr} contains @code{cc0_rtx}. @var{addr} is 1181customarily accessed with the macro @code{CONST_DOUBLE_MEM} and the 1182chain field via @code{CONST_DOUBLE_CHAIN}. 1183 1184@findex CONST_DOUBLE_LOW 1185If @var{m} is @code{VOIDmode}, the bits of the value are stored in 1186@var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro 1187@code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}. 1188 1189If the constant is floating point (regardless of its precision), then 1190the number of integers used to store the value depends on the size of 1191@code{REAL_VALUE_TYPE} (@pxref{Cross-compilation}). The integers 1192represent a floating point number, but not precisely in the target 1193machine's or host machine's floating point format. To convert them to 1194the precise bit pattern used by the target machine, use the macro 1195@code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}). 1196 1197@findex CONST0_RTX 1198@findex CONST1_RTX 1199@findex CONST2_RTX 1200The macro @code{CONST0_RTX (@var{mode})} refers to an expression with 1201value 0 in mode @var{mode}. If mode @var{mode} is of mode class 1202@code{MODE_INT}, it returns @code{const0_rtx}. If mode @var{mode} is of 1203mode class @code{MODE_FLOAT}, it returns a @code{CONST_DOUBLE} 1204expression in mode @var{mode}. Otherwise, it returns a 1205@code{CONST_VECTOR} expression in mode @var{mode}. Similarly, the macro 1206@code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in 1207mode @var{mode} and similarly for @code{CONST2_RTX}. The 1208@code{CONST1_RTX} and @code{CONST2_RTX} macros are undefined 1209for vector modes. 1210 1211@findex const_string 1212@item (const_string @var{str}) 1213Represents a constant string with value @var{str}. Currently this is 1214used only for insn attributes (@pxref{Insn Attributes}) since constant 1215strings in C are placed in memory. 1216 1217@findex symbol_ref 1218@item (symbol_ref:@var{mode} @var{symbol}) 1219Represents the value of an assembler label for data. @var{symbol} is 1220a string that describes the name of the assembler label. If it starts 1221with a @samp{*}, the label is the rest of @var{symbol} not including 1222the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed 1223with @samp{_}. 1224 1225The @code{symbol_ref} contains a mode, which is usually @code{Pmode}. 1226Usually that is the only mode for which a symbol is directly valid. 1227 1228@findex label_ref 1229@item (label_ref @var{label}) 1230Represents the value of an assembler label for code. It contains one 1231operand, an expression, which must be a @code{code_label} or a @code{note} 1232of type @code{NOTE_INSN_DELETED_LABEL} that appears in the instruction 1233sequence to identify the place where the label should go. 1234 1235The reason for using a distinct expression type for code label 1236references is so that jump optimization can distinguish them. 1237 1238@item (const:@var{m} @var{exp}) 1239Represents a constant that is the result of an assembly-time 1240arithmetic computation. The operand, @var{exp}, is an expression that 1241contains only constants (@code{const_int}, @code{symbol_ref} and 1242@code{label_ref} expressions) combined with @code{plus} and 1243@code{minus}. However, not all combinations are valid, since the 1244assembler cannot do arbitrary arithmetic on relocatable symbols. 1245 1246@var{m} should be @code{Pmode}. 1247 1248@findex high 1249@item (high:@var{m} @var{exp}) 1250Represents the high-order bits of @var{exp}, usually a 1251@code{symbol_ref}. The number of bits is machine-dependent and is 1252normally the number of bits specified in an instruction that initializes 1253the high order bits of a register. It is used with @code{lo_sum} to 1254represent the typical two-instruction sequence used in RISC machines to 1255reference a global memory location. 1256 1257@var{m} should be @code{Pmode}. 1258@end table 1259 1260@node Regs and Memory 1261@section Registers and Memory 1262@cindex RTL register expressions 1263@cindex RTL memory expressions 1264 1265Here are the RTL expression types for describing access to machine 1266registers and to main memory. 1267 1268@table @code 1269@findex reg 1270@cindex hard registers 1271@cindex pseudo registers 1272@item (reg:@var{m} @var{n}) 1273For small values of the integer @var{n} (those that are less than 1274@code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine 1275register number @var{n}: a @dfn{hard register}. For larger values of 1276@var{n}, it stands for a temporary value or @dfn{pseudo register}. 1277The compiler's strategy is to generate code assuming an unlimited 1278number of such pseudo registers, and later convert them into hard 1279registers or into memory references. 1280 1281@var{m} is the machine mode of the reference. It is necessary because 1282machines can generally refer to each register in more than one mode. 1283For example, a register may contain a full word but there may be 1284instructions to refer to it as a half word or as a single byte, as 1285well as instructions to refer to it as a floating point number of 1286various precisions. 1287 1288Even for a register that the machine can access in only one mode, 1289the mode must always be specified. 1290 1291The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine 1292description, since the number of hard registers on the machine is an 1293invariant characteristic of the machine. Note, however, that not 1294all of the machine registers must be general registers. All the 1295machine registers that can be used for storage of data are given 1296hard register numbers, even those that can be used only in certain 1297instructions or can hold only certain types of data. 1298 1299A hard register may be accessed in various modes throughout one 1300function, but each pseudo register is given a natural mode 1301and is accessed only in that mode. When it is necessary to describe 1302an access to a pseudo register using a nonnatural mode, a @code{subreg} 1303expression is used. 1304 1305A @code{reg} expression with a machine mode that specifies more than 1306one word of data may actually stand for several consecutive registers. 1307If in addition the register number specifies a hardware register, then 1308it actually represents several consecutive hardware registers starting 1309with the specified one. 1310 1311Each pseudo register number used in a function's RTL code is 1312represented by a unique @code{reg} expression. 1313 1314@findex FIRST_VIRTUAL_REGISTER 1315@findex LAST_VIRTUAL_REGISTER 1316Some pseudo register numbers, those within the range of 1317@code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only 1318appear during the RTL generation phase and are eliminated before the 1319optimization phases. These represent locations in the stack frame that 1320cannot be determined until RTL generation for the function has been 1321completed. The following virtual register numbers are defined: 1322 1323@table @code 1324@findex VIRTUAL_INCOMING_ARGS_REGNUM 1325@item VIRTUAL_INCOMING_ARGS_REGNUM 1326This points to the first word of the incoming arguments passed on the 1327stack. Normally these arguments are placed there by the caller, but the 1328callee may have pushed some arguments that were previously passed in 1329registers. 1330 1331@cindex @code{FIRST_PARM_OFFSET} and virtual registers 1332@cindex @code{ARG_POINTER_REGNUM} and virtual registers 1333When RTL generation is complete, this virtual register is replaced 1334by the sum of the register given by @code{ARG_POINTER_REGNUM} and the 1335value of @code{FIRST_PARM_OFFSET}. 1336 1337@findex VIRTUAL_STACK_VARS_REGNUM 1338@cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers 1339@item VIRTUAL_STACK_VARS_REGNUM 1340If @code{FRAME_GROWS_DOWNWARD} is defined, this points to immediately 1341above the first variable on the stack. Otherwise, it points to the 1342first variable on the stack. 1343 1344@cindex @code{STARTING_FRAME_OFFSET} and virtual registers 1345@cindex @code{FRAME_POINTER_REGNUM} and virtual registers 1346@code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the 1347register given by @code{FRAME_POINTER_REGNUM} and the value 1348@code{STARTING_FRAME_OFFSET}. 1349 1350@findex VIRTUAL_STACK_DYNAMIC_REGNUM 1351@item VIRTUAL_STACK_DYNAMIC_REGNUM 1352This points to the location of dynamically allocated memory on the stack 1353immediately after the stack pointer has been adjusted by the amount of 1354memory desired. 1355 1356@cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers 1357@cindex @code{STACK_POINTER_REGNUM} and virtual registers 1358This virtual register is replaced by the sum of the register given by 1359@code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}. 1360 1361@findex VIRTUAL_OUTGOING_ARGS_REGNUM 1362@item VIRTUAL_OUTGOING_ARGS_REGNUM 1363This points to the location in the stack at which outgoing arguments 1364should be written when the stack is pre-pushed (arguments pushed using 1365push insns should always use @code{STACK_POINTER_REGNUM}). 1366 1367@cindex @code{STACK_POINTER_OFFSET} and virtual registers 1368This virtual register is replaced by the sum of the register given by 1369@code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}. 1370@end table 1371 1372@findex subreg 1373@item (subreg:@var{m} @var{reg} @var{bytenum}) 1374@code{subreg} expressions are used to refer to a register in a machine 1375mode other than its natural one, or to refer to one register of 1376a multi-part @code{reg} that actually refers to several registers. 1377 1378Each pseudo-register has a natural mode. If it is necessary to 1379operate on it in a different mode---for example, to perform a fullword 1380move instruction on a pseudo-register that contains a single 1381byte---the pseudo-register must be enclosed in a @code{subreg}. In 1382such a case, @var{bytenum} is zero. 1383 1384Usually @var{m} is at least as narrow as the mode of @var{reg}, in which 1385case it is restricting consideration to only the bits of @var{reg} that 1386are in @var{m}. 1387 1388Sometimes @var{m} is wider than the mode of @var{reg}. These 1389@code{subreg} expressions are often called @dfn{paradoxical}. They are 1390used in cases where we want to refer to an object in a wider mode but do 1391not care what value the additional bits have. The reload pass ensures 1392that paradoxical references are only made to hard registers. 1393 1394The other use of @code{subreg} is to extract the individual registers of 1395a multi-register value. Machine modes such as @code{DImode} and 1396@code{TImode} can indicate values longer than a word, values which 1397usually require two or more consecutive registers. To access one of the 1398registers, use a @code{subreg} with mode @code{SImode} and a 1399@var{bytenum} offset that says which register. 1400 1401Storing in a non-paradoxical @code{subreg} has undefined results for 1402bits belonging to the same word as the @code{subreg}. This laxity makes 1403it easier to generate efficient code for such instructions. To 1404represent an instruction that preserves all the bits outside of those in 1405the @code{subreg}, use @code{strict_low_part} around the @code{subreg}. 1406 1407@cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg} 1408The compilation parameter @code{WORDS_BIG_ENDIAN}, if set to 1, says 1409that byte number zero is part of the most significant word; otherwise, 1410it is part of the least significant word. 1411 1412@cindex @code{BYTES_BIG_ENDIAN}, effect on @code{subreg} 1413The compilation parameter @code{BYTES_BIG_ENDIAN}, if set to 1, says 1414that byte number zero is the most significant byte within a word; 1415otherwise, it is the least significant byte within a word. 1416 1417@cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg} 1418On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with 1419@code{WORDS_BIG_ENDIAN}. 1420However, most parts of the compiler treat floating point values as if 1421they had the same endianness as integer values. This works because 1422they handle them solely as a collection of integer values, with no 1423particular numerical value. Only real.c and the runtime libraries 1424care about @code{FLOAT_WORDS_BIG_ENDIAN}. 1425 1426@cindex combiner pass 1427@cindex reload pass 1428@cindex @code{subreg}, special reload handling 1429Between the combiner pass and the reload pass, it is possible to have a 1430paradoxical @code{subreg} which contains a @code{mem} instead of a 1431@code{reg} as its first operand. After the reload pass, it is also 1432possible to have a non-paradoxical @code{subreg} which contains a 1433@code{mem}; this usually occurs when the @code{mem} is a stack slot 1434which replaced a pseudo register. 1435 1436Note that it is not valid to access a @code{DFmode} value in @code{SFmode} 1437using a @code{subreg}. On some machines the most significant part of a 1438@code{DFmode} value does not have the same format as a single-precision 1439floating value. 1440 1441It is also not valid to access a single word of a multi-word value in a 1442hard register when less registers can hold the value than would be 1443expected from its size. For example, some 32-bit machines have 1444floating-point registers that can hold an entire @code{DFmode} value. 1445If register 10 were such a register @code{(subreg:SI (reg:DF 10) 1)} 1446would be invalid because there is no way to convert that reference to 1447a single machine register. The reload pass prevents @code{subreg} 1448expressions such as these from being formed. 1449 1450@findex SUBREG_REG 1451@findex SUBREG_BYTE 1452The first operand of a @code{subreg} expression is customarily accessed 1453with the @code{SUBREG_REG} macro and the second operand is customarily 1454accessed with the @code{SUBREG_BYTE} macro. 1455 1456@findex scratch 1457@cindex scratch operands 1458@item (scratch:@var{m}) 1459This represents a scratch register that will be required for the 1460execution of a single instruction and not used subsequently. It is 1461converted into a @code{reg} by either the local register allocator or 1462the reload pass. 1463 1464@code{scratch} is usually present inside a @code{clobber} operation 1465(@pxref{Side Effects}). 1466 1467@findex cc0 1468@cindex condition code register 1469@item (cc0) 1470This refers to the machine's condition code register. It has no 1471operands and may not have a machine mode. There are two ways to use it: 1472 1473@itemize @bullet 1474@item 1475To stand for a complete set of condition code flags. This is best on 1476most machines, where each comparison sets the entire series of flags. 1477 1478With this technique, @code{(cc0)} may be validly used in only two 1479contexts: as the destination of an assignment (in test and compare 1480instructions) and in comparison operators comparing against zero 1481(@code{const_int} with value zero; that is to say, @code{const0_rtx}). 1482 1483@item 1484To stand for a single flag that is the result of a single condition. 1485This is useful on machines that have only a single flag bit, and in 1486which comparison instructions must specify the condition to test. 1487 1488With this technique, @code{(cc0)} may be validly used in only two 1489contexts: as the destination of an assignment (in test and compare 1490instructions) where the source is a comparison operator, and as the 1491first operand of @code{if_then_else} (in a conditional branch). 1492@end itemize 1493 1494@findex cc0_rtx 1495There is only one expression object of code @code{cc0}; it is the 1496value of the variable @code{cc0_rtx}. Any attempt to create an 1497expression of code @code{cc0} will return @code{cc0_rtx}. 1498 1499Instructions can set the condition code implicitly. On many machines, 1500nearly all instructions set the condition code based on the value that 1501they compute or store. It is not necessary to record these actions 1502explicitly in the RTL because the machine description includes a 1503prescription for recognizing the instructions that do so (by means of 1504the macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only 1505instructions whose sole purpose is to set the condition code, and 1506instructions that use the condition code, need mention @code{(cc0)}. 1507 1508On some machines, the condition code register is given a register number 1509and a @code{reg} is used instead of @code{(cc0)}. This is usually the 1510preferable approach if only a small subset of instructions modify the 1511condition code. Other machines store condition codes in general 1512registers; in such cases a pseudo register should be used. 1513 1514Some machines, such as the Sparc and RS/6000, have two sets of 1515arithmetic instructions, one that sets and one that does not set the 1516condition code. This is best handled by normally generating the 1517instruction that does not set the condition code, and making a pattern 1518that both performs the arithmetic and sets the condition code register 1519(which would not be @code{(cc0)} in this case). For examples, search 1520for @samp{addcc} and @samp{andcc} in @file{sparc.md}. 1521 1522@findex pc 1523@item (pc) 1524@cindex program counter 1525This represents the machine's program counter. It has no operands and 1526may not have a machine mode. @code{(pc)} may be validly used only in 1527certain specific contexts in jump instructions. 1528 1529@findex pc_rtx 1530There is only one expression object of code @code{pc}; it is the value 1531of the variable @code{pc_rtx}. Any attempt to create an expression of 1532code @code{pc} will return @code{pc_rtx}. 1533 1534All instructions that do not jump alter the program counter implicitly 1535by incrementing it, but there is no need to mention this in the RTL@. 1536 1537@findex mem 1538@item (mem:@var{m} @var{addr} @var{alias}) 1539This RTX represents a reference to main memory at an address 1540represented by the expression @var{addr}. @var{m} specifies how large 1541a unit of memory is accessed. @var{alias} specifies an alias set for the 1542reference. In general two items are in different alias sets if they cannot 1543reference the same memory address. 1544 1545@findex addressof 1546@item (addressof:@var{m} @var{reg}) 1547This RTX represents a request for the address of register @var{reg}. Its mode 1548is always @code{Pmode}. If there are any @code{addressof} 1549expressions left in the function after CSE, @var{reg} is forced into the 1550stack and the @code{addressof} expression is replaced with a @code{plus} 1551expression for the address of its stack slot. 1552@end table 1553 1554@node Arithmetic 1555@section RTL Expressions for Arithmetic 1556@cindex arithmetic, in RTL 1557@cindex math, in RTL 1558@cindex RTL expressions for arithmetic 1559 1560Unless otherwise specified, all the operands of arithmetic expressions 1561must be valid for mode @var{m}. An operand is valid for mode @var{m} 1562if it has mode @var{m}, or if it is a @code{const_int} or 1563@code{const_double} and @var{m} is a mode of class @code{MODE_INT}. 1564 1565For commutative binary operations, constants should be placed in the 1566second operand. 1567 1568@table @code 1569@findex plus 1570@cindex RTL addition 1571@cindex RTL sum 1572@item (plus:@var{m} @var{x} @var{y}) 1573Represents the sum of the values represented by @var{x} and @var{y} 1574carried out in machine mode @var{m}. 1575 1576@findex lo_sum 1577@item (lo_sum:@var{m} @var{x} @var{y}) 1578Like @code{plus}, except that it represents that sum of @var{x} and the 1579low-order bits of @var{y}. The number of low order bits is 1580machine-dependent but is normally the number of bits in a @code{Pmode} 1581item minus the number of bits set by the @code{high} code 1582(@pxref{Constants}). 1583 1584@var{m} should be @code{Pmode}. 1585 1586@findex minus 1587@cindex RTL subtraction 1588@cindex RTL difference 1589@item (minus:@var{m} @var{x} @var{y}) 1590Like @code{plus} but represents subtraction. 1591 1592@findex ss_plus 1593@cindex RTL addition with signed saturation 1594@item (ss_plus:@var{m} @var{x} @var{y}) 1595 1596Like @code{plus}, but using signed saturation in case of an overflow. 1597 1598@findex us_plus 1599@cindex RTL addition with unsigned saturation 1600@item (us_plus:@var{m} @var{x} @var{y}) 1601 1602Like @code{plus}, but using unsigned saturation in case of an overflow. 1603 1604@findex ss_minus 1605@cindex RTL addition with signed saturation 1606@item (ss_minus:@var{m} @var{x} @var{y}) 1607 1608Like @code{minus}, but using signed saturation in case of an overflow. 1609 1610@findex us_minus 1611@cindex RTL addition with unsigned saturation 1612@item (us_minus:@var{m} @var{x} @var{y}) 1613 1614Like @code{minus}, but using unsigned saturation in case of an overflow. 1615 1616@findex compare 1617@cindex RTL comparison 1618@item (compare:@var{m} @var{x} @var{y}) 1619Represents the result of subtracting @var{y} from @var{x} for purposes 1620of comparison. The result is computed without overflow, as if with 1621infinite precision. 1622 1623Of course, machines can't really subtract with infinite precision. 1624However, they can pretend to do so when only the sign of the result will 1625be used, which is the case when the result is stored in the condition 1626code. And that is the @emph{only} way this kind of expression may 1627validly be used: as a value to be stored in the condition codes, either 1628@code{(cc0)} or a register. @xref{Comparisons}. 1629 1630The mode @var{m} is not related to the modes of @var{x} and @var{y}, but 1631instead is the mode of the condition code value. If @code{(cc0)} is 1632used, it is @code{VOIDmode}. Otherwise it is some mode in class 1633@code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}. If @var{m} 1634is @code{VOIDmode} or @code{CCmode}, the operation returns sufficient 1635information (in an unspecified format) so that any comparison operator 1636can be applied to the result of the @code{COMPARE} operation. For other 1637modes in class @code{MODE_CC}, the operation only returns a subset of 1638this information. 1639 1640Normally, @var{x} and @var{y} must have the same mode. Otherwise, 1641@code{compare} is valid only if the mode of @var{x} is in class 1642@code{MODE_INT} and @var{y} is a @code{const_int} or 1643@code{const_double} with mode @code{VOIDmode}. The mode of @var{x} 1644determines what mode the comparison is to be done in; thus it must not 1645be @code{VOIDmode}. 1646 1647If one of the operands is a constant, it should be placed in the 1648second operand and the comparison code adjusted as appropriate. 1649 1650A @code{compare} specifying two @code{VOIDmode} constants is not valid 1651since there is no way to know in what mode the comparison is to be 1652performed; the comparison must either be folded during the compilation 1653or the first operand must be loaded into a register while its mode is 1654still known. 1655 1656@findex neg 1657@item (neg:@var{m} @var{x}) 1658Represents the negation (subtraction from zero) of the value represented 1659by @var{x}, carried out in mode @var{m}. 1660 1661@findex mult 1662@cindex multiplication 1663@cindex product 1664@item (mult:@var{m} @var{x} @var{y}) 1665Represents the signed product of the values represented by @var{x} and 1666@var{y} carried out in machine mode @var{m}. 1667 1668Some machines support a multiplication that generates a product wider 1669than the operands. Write the pattern for this as 1670 1671@example 1672(mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y})) 1673@end example 1674 1675where @var{m} is wider than the modes of @var{x} and @var{y}, which need 1676not be the same. 1677 1678For unsigned widening multiplication, use the same idiom, but with 1679@code{zero_extend} instead of @code{sign_extend}. 1680 1681@findex div 1682@cindex division 1683@cindex signed division 1684@cindex quotient 1685@item (div:@var{m} @var{x} @var{y}) 1686Represents the quotient in signed division of @var{x} by @var{y}, 1687carried out in machine mode @var{m}. If @var{m} is a floating point 1688mode, it represents the exact quotient; otherwise, the integerized 1689quotient. 1690 1691Some machines have division instructions in which the operands and 1692quotient widths are not all the same; you should represent 1693such instructions using @code{truncate} and @code{sign_extend} as in, 1694 1695@example 1696(truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y}))) 1697@end example 1698 1699@findex udiv 1700@cindex unsigned division 1701@cindex division 1702@item (udiv:@var{m} @var{x} @var{y}) 1703Like @code{div} but represents unsigned division. 1704 1705@findex mod 1706@findex umod 1707@cindex remainder 1708@cindex division 1709@item (mod:@var{m} @var{x} @var{y}) 1710@itemx (umod:@var{m} @var{x} @var{y}) 1711Like @code{div} and @code{udiv} but represent the remainder instead of 1712the quotient. 1713 1714@findex smin 1715@findex smax 1716@cindex signed minimum 1717@cindex signed maximum 1718@item (smin:@var{m} @var{x} @var{y}) 1719@itemx (smax:@var{m} @var{x} @var{y}) 1720Represents the smaller (for @code{smin}) or larger (for @code{smax}) of 1721@var{x} and @var{y}, interpreted as signed integers in mode @var{m}. 1722 1723@findex umin 1724@findex umax 1725@cindex unsigned minimum and maximum 1726@item (umin:@var{m} @var{x} @var{y}) 1727@itemx (umax:@var{m} @var{x} @var{y}) 1728Like @code{smin} and @code{smax}, but the values are interpreted as unsigned 1729integers. 1730 1731@findex not 1732@cindex complement, bitwise 1733@cindex bitwise complement 1734@item (not:@var{m} @var{x}) 1735Represents the bitwise complement of the value represented by @var{x}, 1736carried out in mode @var{m}, which must be a fixed-point machine mode. 1737 1738@findex and 1739@cindex logical-and, bitwise 1740@cindex bitwise logical-and 1741@item (and:@var{m} @var{x} @var{y}) 1742Represents the bitwise logical-and of the values represented by 1743@var{x} and @var{y}, carried out in machine mode @var{m}, which must be 1744a fixed-point machine mode. 1745 1746@findex ior 1747@cindex inclusive-or, bitwise 1748@cindex bitwise inclusive-or 1749@item (ior:@var{m} @var{x} @var{y}) 1750Represents the bitwise inclusive-or of the values represented by @var{x} 1751and @var{y}, carried out in machine mode @var{m}, which must be a 1752fixed-point mode. 1753 1754@findex xor 1755@cindex exclusive-or, bitwise 1756@cindex bitwise exclusive-or 1757@item (xor:@var{m} @var{x} @var{y}) 1758Represents the bitwise exclusive-or of the values represented by @var{x} 1759and @var{y}, carried out in machine mode @var{m}, which must be a 1760fixed-point mode. 1761 1762@findex ashift 1763@cindex left shift 1764@cindex shift 1765@cindex arithmetic shift 1766@item (ashift:@var{m} @var{x} @var{c}) 1767Represents the result of arithmetically shifting @var{x} left by @var{c} 1768places. @var{x} have mode @var{m}, a fixed-point machine mode. @var{c} 1769be a fixed-point mode or be a constant with mode @code{VOIDmode}; which 1770mode is determined by the mode called for in the machine description 1771entry for the left-shift instruction. For example, on the VAX, the mode 1772of @var{c} is @code{QImode} regardless of @var{m}. 1773 1774@findex lshiftrt 1775@cindex right shift 1776@findex ashiftrt 1777@item (lshiftrt:@var{m} @var{x} @var{c}) 1778@itemx (ashiftrt:@var{m} @var{x} @var{c}) 1779Like @code{ashift} but for right shift. Unlike the case for left shift, 1780these two operations are distinct. 1781 1782@findex rotate 1783@cindex rotate 1784@cindex left rotate 1785@findex rotatert 1786@cindex right rotate 1787@item (rotate:@var{m} @var{x} @var{c}) 1788@itemx (rotatert:@var{m} @var{x} @var{c}) 1789Similar but represent left and right rotate. If @var{c} is a constant, 1790use @code{rotate}. 1791 1792@findex abs 1793@cindex absolute value 1794@item (abs:@var{m} @var{x}) 1795Represents the absolute value of @var{x}, computed in mode @var{m}. 1796 1797@findex sqrt 1798@cindex square root 1799@item (sqrt:@var{m} @var{x}) 1800Represents the square root of @var{x}, computed in mode @var{m}. 1801Most often @var{m} will be a floating point mode. 1802 1803@findex ffs 1804@item (ffs:@var{m} @var{x}) 1805Represents one plus the index of the least significant 1-bit in 1806@var{x}, represented as an integer of mode @var{m}. (The value is 1807zero if @var{x} is zero.) The mode of @var{x} need not be @var{m}; 1808depending on the target machine, various mode combinations may be 1809valid. 1810@end table 1811 1812@node Comparisons 1813@section Comparison Operations 1814@cindex RTL comparison operations 1815 1816Comparison operators test a relation on two operands and are considered 1817to represent a machine-dependent nonzero value described by, but not 1818necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc}) 1819if the relation holds, or zero if it does not. The mode of the 1820comparison operation is independent of the mode of the data being 1821compared. If the comparison operation is being tested (e.g., the first 1822operand of an @code{if_then_else}), the mode must be @code{VOIDmode}. 1823If the comparison operation is producing data to be stored in some 1824variable, the mode must be in class @code{MODE_INT}. All comparison 1825operations producing data must use the same mode, which is 1826machine-specific. 1827 1828@cindex condition codes 1829There are two ways that comparison operations may be used. The 1830comparison operators may be used to compare the condition codes 1831@code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such 1832a construct actually refers to the result of the preceding instruction 1833in which the condition codes were set. The instruction setting the 1834condition code must be adjacent to the instruction using the condition 1835code; only @code{note} insns may separate them. 1836 1837Alternatively, a comparison operation may directly compare two data 1838objects. The mode of the comparison is determined by the operands; they 1839must both be valid for a common machine mode. A comparison with both 1840operands constant would be invalid as the machine mode could not be 1841deduced from it, but such a comparison should never exist in RTL due to 1842constant folding. 1843 1844In the example above, if @code{(cc0)} were last set to 1845@code{(compare @var{x} @var{y})}, the comparison operation is 1846identical to @code{(eq @var{x} @var{y})}. Usually only one style 1847of comparisons is supported on a particular machine, but the combine 1848pass will try to merge the operations to produce the @code{eq} shown 1849in case it exists in the context of the particular insn involved. 1850 1851Inequality comparisons come in two flavors, signed and unsigned. Thus, 1852there are distinct expression codes @code{gt} and @code{gtu} for signed and 1853unsigned greater-than. These can produce different results for the same 1854pair of integer values: for example, 1 is signed greater-than @minus{}1 but not 1855unsigned greater-than, because @minus{}1 when regarded as unsigned is actually 1856@code{0xffffffff} which is greater than 1. 1857 1858The signed comparisons are also used for floating point values. Floating 1859point comparisons are distinguished by the machine modes of the operands. 1860 1861@table @code 1862@findex eq 1863@cindex equal 1864@item (eq:@var{m} @var{x} @var{y}) 1865@code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y} 1866are equal, otherwise 0. 1867 1868@findex ne 1869@cindex not equal 1870@item (ne:@var{m} @var{x} @var{y}) 1871@code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y} 1872are not equal, otherwise 0. 1873 1874@findex gt 1875@cindex greater than 1876@item (gt:@var{m} @var{x} @var{y}) 1877@code{STORE_FLAG_VALUE} if the @var{x} is greater than @var{y}. If they 1878are fixed-point, the comparison is done in a signed sense. 1879 1880@findex gtu 1881@cindex greater than 1882@cindex unsigned greater than 1883@item (gtu:@var{m} @var{x} @var{y}) 1884Like @code{gt} but does unsigned comparison, on fixed-point numbers only. 1885 1886@findex lt 1887@cindex less than 1888@findex ltu 1889@cindex unsigned less than 1890@item (lt:@var{m} @var{x} @var{y}) 1891@itemx (ltu:@var{m} @var{x} @var{y}) 1892Like @code{gt} and @code{gtu} but test for ``less than''. 1893 1894@findex ge 1895@cindex greater than 1896@findex geu 1897@cindex unsigned greater than 1898@item (ge:@var{m} @var{x} @var{y}) 1899@itemx (geu:@var{m} @var{x} @var{y}) 1900Like @code{gt} and @code{gtu} but test for ``greater than or equal''. 1901 1902@findex le 1903@cindex less than or equal 1904@findex leu 1905@cindex unsigned less than 1906@item (le:@var{m} @var{x} @var{y}) 1907@itemx (leu:@var{m} @var{x} @var{y}) 1908Like @code{gt} and @code{gtu} but test for ``less than or equal''. 1909 1910@findex if_then_else 1911@item (if_then_else @var{cond} @var{then} @var{else}) 1912This is not a comparison operation but is listed here because it is 1913always used in conjunction with a comparison operation. To be 1914precise, @var{cond} is a comparison expression. This expression 1915represents a choice, according to @var{cond}, between the value 1916represented by @var{then} and the one represented by @var{else}. 1917 1918On most machines, @code{if_then_else} expressions are valid only 1919to express conditional jumps. 1920 1921@findex cond 1922@item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default}) 1923Similar to @code{if_then_else}, but more general. Each of @var{test1}, 1924@var{test2}, @dots{} is performed in turn. The result of this expression is 1925the @var{value} corresponding to the first nonzero test, or @var{default} if 1926none of the tests are nonzero expressions. 1927 1928This is currently not valid for instruction patterns and is supported only 1929for insn attributes. @xref{Insn Attributes}. 1930@end table 1931 1932@node Bit-Fields 1933@section Bit-Fields 1934@cindex bit-fields 1935 1936Special expression codes exist to represent bit-field instructions. 1937These types of expressions are lvalues in RTL; they may appear 1938on the left side of an assignment, indicating insertion of a value 1939into the specified bit-field. 1940 1941@table @code 1942@findex sign_extract 1943@cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract} 1944@item (sign_extract:@var{m} @var{loc} @var{size} @var{pos}) 1945This represents a reference to a sign-extended bit-field contained or 1946starting in @var{loc} (a memory or register reference). The bit-field 1947is @var{size} bits wide and starts at bit @var{pos}. The compilation 1948option @code{BITS_BIG_ENDIAN} says which end of the memory unit 1949@var{pos} counts from. 1950 1951If @var{loc} is in memory, its mode must be a single-byte integer mode. 1952If @var{loc} is in a register, the mode to use is specified by the 1953operand of the @code{insv} or @code{extv} pattern 1954(@pxref{Standard Names}) and is usually a full-word integer mode, 1955which is the default if none is specified. 1956 1957The mode of @var{pos} is machine-specific and is also specified 1958in the @code{insv} or @code{extv} pattern. 1959 1960The mode @var{m} is the same as the mode that would be used for 1961@var{loc} if it were a register. 1962 1963@findex zero_extract 1964@item (zero_extract:@var{m} @var{loc} @var{size} @var{pos}) 1965Like @code{sign_extract} but refers to an unsigned or zero-extended 1966bit-field. The same sequence of bits are extracted, but they 1967are filled to an entire word with zeros instead of by sign-extension. 1968@end table 1969 1970@node Vector Operations 1971@section Vector Operations 1972@cindex vector operations 1973 1974All normal RTL expressions can be used with vector modes; they are 1975interpreted as operating on each part of the vector independently. 1976Additionally, there are a few new expressions to describe specific vector 1977operations. 1978 1979@table @code 1980@findex vec_merge 1981@item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items}) 1982This describes a merge operation between two vectors. The result is a vector 1983of mode @var{m}; its elements are selected from either @var{vec1} or 1984@var{vec2}. Which elements are selected is described by @var{items}, which 1985is a bit mask represented by a @code{const_int}; a zero bit indicates the 1986corresponding element in the result vector is taken from @var{vec2} while 1987a set bit indicates it is taken from @var{vec1}. 1988 1989@findex vec_select 1990@item (vec_select:@var{m} @var{vec1} @var{selection}) 1991This describes an operation that selects parts of a vector. @var{vec1} is 1992the source vector, @var{selection} is a @code{parallel} that contains a 1993@code{const_int} for each of the subparts of the result vector, giving the 1994number of the source subpart that should be stored into it. 1995 1996@findex vec_concat 1997@item (vec_concat:@var{m} @var{vec1} @var{vec2}) 1998Describes a vector concat operation. The result is a concatenation of the 1999vectors @var{vec1} and @var{vec2}; its length is the sum of the lengths of 2000the two inputs. 2001 2002@findex vec_const 2003@item (vec_const:@var{m} @var{subparts}) 2004This describes a constant vector. @var{subparts} is a @code{parallel} that 2005contains a constant for each of the subparts of the vector. 2006 2007@findex vec_duplicate 2008@item (vec_duplicate:@var{m} @var{vec}) 2009This operation converts a small vector into a larger one by duplicating the 2010input values. The output vector mode must have the same submodes as the 2011input vector mode, and the number of output parts must be an integer multiple 2012of the number of input parts. 2013 2014@end table 2015 2016@node Conversions 2017@section Conversions 2018@cindex conversions 2019@cindex machine mode conversions 2020 2021All conversions between machine modes must be represented by 2022explicit conversion operations. For example, an expression 2023which is the sum of a byte and a full word cannot be written as 2024@code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus} 2025operation requires two operands of the same machine mode. 2026Therefore, the byte-sized operand is enclosed in a conversion 2027operation, as in 2028 2029@example 2030(plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80)) 2031@end example 2032 2033The conversion operation is not a mere placeholder, because there 2034may be more than one way of converting from a given starting mode 2035to the desired final mode. The conversion operation code says how 2036to do it. 2037 2038For all conversion operations, @var{x} must not be @code{VOIDmode} 2039because the mode in which to do the conversion would not be known. 2040The conversion must either be done at compile-time or @var{x} 2041must be placed into a register. 2042 2043@table @code 2044@findex sign_extend 2045@item (sign_extend:@var{m} @var{x}) 2046Represents the result of sign-extending 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 narrower than @var{m}. 2049 2050@findex zero_extend 2051@item (zero_extend:@var{m} @var{x}) 2052Represents the result of zero-extending the value @var{x} 2053to machine mode @var{m}. @var{m} must be a fixed-point mode 2054and @var{x} a fixed-point value of a mode narrower than @var{m}. 2055 2056@findex float_extend 2057@item (float_extend:@var{m} @var{x}) 2058Represents the result of extending the value @var{x} 2059to machine mode @var{m}. @var{m} must be a floating point mode 2060and @var{x} a floating point value of a mode narrower than @var{m}. 2061 2062@findex truncate 2063@item (truncate:@var{m} @var{x}) 2064Represents the result of truncating the value @var{x} 2065to machine mode @var{m}. @var{m} must be a fixed-point mode 2066and @var{x} a fixed-point value of a mode wider than @var{m}. 2067 2068@findex ss_truncate 2069@item (ss_truncate:@var{m} @var{x}) 2070Represents the result of truncating the value @var{x} 2071to machine mode @var{m}, using signed saturation in the case of 2072overflow. Both @var{m} and the mode of @var{x} must be fixed-point 2073modes. 2074 2075@findex us_truncate 2076@item (us_truncate:@var{m} @var{x}) 2077Represents the result of truncating the value @var{x} 2078to machine mode @var{m}, using unsigned saturation in the case of 2079overflow. Both @var{m} and the mode of @var{x} must be fixed-point 2080modes. 2081 2082@findex float_truncate 2083@item (float_truncate:@var{m} @var{x}) 2084Represents the result of truncating the value @var{x} 2085to machine mode @var{m}. @var{m} must be a floating point mode 2086and @var{x} a floating point value of a mode wider than @var{m}. 2087 2088@findex float 2089@item (float:@var{m} @var{x}) 2090Represents the result of converting fixed point value @var{x}, 2091regarded as signed, to floating point mode @var{m}. 2092 2093@findex unsigned_float 2094@item (unsigned_float:@var{m} @var{x}) 2095Represents the result of converting fixed point value @var{x}, 2096regarded as unsigned, to floating point mode @var{m}. 2097 2098@findex fix 2099@item (fix:@var{m} @var{x}) 2100When @var{m} is a fixed point mode, represents the result of 2101converting floating point value @var{x} to mode @var{m}, regarded as 2102signed. How rounding is done is not specified, so this operation may 2103be used validly in compiling C code only for integer-valued operands. 2104 2105@findex unsigned_fix 2106@item (unsigned_fix:@var{m} @var{x}) 2107Represents the result of converting floating point value @var{x} to 2108fixed point mode @var{m}, regarded as unsigned. How rounding is done 2109is not specified. 2110 2111@findex fix 2112@item (fix:@var{m} @var{x}) 2113When @var{m} is a floating point mode, represents the result of 2114converting floating point value @var{x} (valid for mode @var{m}) to an 2115integer, still represented in floating point mode @var{m}, by rounding 2116towards zero. 2117@end table 2118 2119@node RTL Declarations 2120@section Declarations 2121@cindex RTL declarations 2122@cindex declarations, RTL 2123 2124Declaration expression codes do not represent arithmetic operations 2125but rather state assertions about their operands. 2126 2127@table @code 2128@findex strict_low_part 2129@cindex @code{subreg}, in @code{strict_low_part} 2130@item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0)) 2131This expression code is used in only one context: as the destination operand of a 2132@code{set} expression. In addition, the operand of this expression 2133must be a non-paradoxical @code{subreg} expression. 2134 2135The presence of @code{strict_low_part} says that the part of the 2136register which is meaningful in mode @var{n}, but is not part of 2137mode @var{m}, is not to be altered. Normally, an assignment to such 2138a subreg is allowed to have undefined effects on the rest of the 2139register when @var{m} is less than a word. 2140@end table 2141 2142@node Side Effects 2143@section Side Effect Expressions 2144@cindex RTL side effect expressions 2145 2146The expression codes described so far represent values, not actions. 2147But machine instructions never produce values; they are meaningful 2148only for their side effects on the state of the machine. Special 2149expression codes are used to represent side effects. 2150 2151The body of an instruction is always one of these side effect codes; 2152the codes described above, which represent values, appear only as 2153the operands of these. 2154 2155@table @code 2156@findex set 2157@item (set @var{lval} @var{x}) 2158Represents the action of storing the value of @var{x} into the place 2159represented by @var{lval}. @var{lval} must be an expression 2160representing a place that can be stored in: @code{reg} (or @code{subreg} 2161or @code{strict_low_part}), @code{mem}, @code{pc}, @code{parallel}, or 2162@code{cc0}. 2163 2164If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a 2165machine mode; then @var{x} must be valid for that mode. 2166 2167If @var{lval} is a @code{reg} whose machine mode is less than the full 2168width of the register, then it means that the part of the register 2169specified by the machine mode is given the specified value and the 2170rest of the register receives an undefined value. Likewise, if 2171@var{lval} is a @code{subreg} whose machine mode is narrower than 2172the mode of the register, the rest of the register can be changed in 2173an undefined way. 2174 2175If @var{lval} is a @code{strict_low_part} of a @code{subreg}, then the 2176part of the register specified by the machine mode of the 2177@code{subreg} is given the value @var{x} and the rest of the register 2178is not changed. 2179 2180If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may 2181be either a @code{compare} expression or a value that may have any mode. 2182The latter case represents a ``test'' instruction. The expression 2183@code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to 2184@code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}. 2185Use the former expression to save space during the compilation. 2186 2187If @var{lval} is a @code{parallel}, it is used to represent the case of 2188a function returning a structure in multiple registers. Each element 2189of the @code{parallel} is an @code{expr_list} whose first operand is a 2190@code{reg} and whose second operand is a @code{const_int} representing the 2191offset (in bytes) into the structure at which the data in that register 2192corresponds. The first element may be null to indicate that the structure 2193is also passed partly in memory. 2194 2195@cindex jump instructions and @code{set} 2196@cindex @code{if_then_else} usage 2197If @var{lval} is @code{(pc)}, we have a jump instruction, and the 2198possibilities for @var{x} are very limited. It may be a 2199@code{label_ref} expression (unconditional jump). It may be an 2200@code{if_then_else} (conditional jump), in which case either the 2201second or the third operand must be @code{(pc)} (for the case which 2202does not jump) and the other of the two must be a @code{label_ref} 2203(for the case which does jump). @var{x} may also be a @code{mem} or 2204@code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a 2205@code{mem}; these unusual patterns are used to represent jumps through 2206branch tables. 2207 2208If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of 2209@var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be 2210valid for the mode of @var{lval}. 2211 2212@findex SET_DEST 2213@findex SET_SRC 2214@var{lval} is customarily accessed with the @code{SET_DEST} macro and 2215@var{x} with the @code{SET_SRC} macro. 2216 2217@findex return 2218@item (return) 2219As the sole expression in a pattern, represents a return from the 2220current function, on machines where this can be done with one 2221instruction, such as VAXen. On machines where a multi-instruction 2222``epilogue'' must be executed in order to return from the function, 2223returning is done by jumping to a label which precedes the epilogue, and 2224the @code{return} expression code is never used. 2225 2226Inside an @code{if_then_else} expression, represents the value to be 2227placed in @code{pc} to return to the caller. 2228 2229Note that an insn pattern of @code{(return)} is logically equivalent to 2230@code{(set (pc) (return))}, but the latter form is never used. 2231 2232@findex call 2233@item (call @var{function} @var{nargs}) 2234Represents a function call. @var{function} is a @code{mem} expression 2235whose address is the address of the function to be called. 2236@var{nargs} is an expression which can be used for two purposes: on 2237some machines it represents the number of bytes of stack argument; on 2238others, it represents the number of argument registers. 2239 2240Each machine has a standard machine mode which @var{function} must 2241have. The machine description defines macro @code{FUNCTION_MODE} to 2242expand into the requisite mode name. The purpose of this mode is to 2243specify what kind of addressing is allowed, on machines where the 2244allowed kinds of addressing depend on the machine mode being 2245addressed. 2246 2247@findex clobber 2248@item (clobber @var{x}) 2249Represents the storing or possible storing of an unpredictable, 2250undescribed value into @var{x}, which must be a @code{reg}, 2251@code{scratch}, @code{parallel} or @code{mem} expression. 2252 2253One place this is used is in string instructions that store standard 2254values into particular hard registers. It may not be worth the 2255trouble to describe the values that are stored, but it is essential to 2256inform the compiler that the registers will be altered, lest it 2257attempt to keep data in them across the string instruction. 2258 2259If @var{x} is @code{(mem:BLK (const_int 0))}, it means that all memory 2260locations must be presumed clobbered. If @var{x} is a @code{parallel}, 2261it has the same meaning as a @code{parallel} in a @code{set} expression. 2262 2263Note that the machine description classifies certain hard registers as 2264``call-clobbered''. All function call instructions are assumed by 2265default to clobber these registers, so there is no need to use 2266@code{clobber} expressions to indicate this fact. Also, each function 2267call is assumed to have the potential to alter any memory location, 2268unless the function is declared @code{const}. 2269 2270If the last group of expressions in a @code{parallel} are each a 2271@code{clobber} expression whose arguments are @code{reg} or 2272@code{match_scratch} (@pxref{RTL Template}) expressions, the combiner 2273phase can add the appropriate @code{clobber} expressions to an insn it 2274has constructed when doing so will cause a pattern to be matched. 2275 2276This feature can be used, for example, on a machine that whose multiply 2277and add instructions don't use an MQ register but which has an 2278add-accumulate instruction that does clobber the MQ register. Similarly, 2279a combined instruction might require a temporary register while the 2280constituent instructions might not. 2281 2282When a @code{clobber} expression for a register appears inside a 2283@code{parallel} with other side effects, the register allocator 2284guarantees that the register is unoccupied both before and after that 2285insn. However, the reload phase may allocate a register used for one of 2286the inputs unless the @samp{&} constraint is specified for the selected 2287alternative (@pxref{Modifiers}). You can clobber either a specific hard 2288register, a pseudo register, or a @code{scratch} expression; in the 2289latter two cases, GCC will allocate a hard register that is available 2290there for use as a temporary. 2291 2292For instructions that require a temporary register, you should use 2293@code{scratch} instead of a pseudo-register because this will allow the 2294combiner phase to add the @code{clobber} when required. You do this by 2295coding (@code{clobber} (@code{match_scratch} @dots{})). If you do 2296clobber a pseudo register, use one which appears nowhere else---generate 2297a new one each time. Otherwise, you may confuse CSE@. 2298 2299There is one other known use for clobbering a pseudo register in a 2300@code{parallel}: when one of the input operands of the insn is also 2301clobbered by the insn. In this case, using the same pseudo register in 2302the clobber and elsewhere in the insn produces the expected results. 2303 2304@findex use 2305@item (use @var{x}) 2306Represents the use of the value of @var{x}. It indicates that the 2307value in @var{x} at this point in the program is needed, even though 2308it may not be apparent why this is so. Therefore, the compiler will 2309not attempt to delete previous instructions whose only effect is to 2310store a value in @var{x}. @var{x} must be a @code{reg} expression. 2311 2312In some situations, it may be tempting to add a @code{use} of a 2313register in a @code{parallel} to describe a situation where the value 2314of a special register will modify the behavior of the instruction. 2315An hypothetical example might be a pattern for an addition that can 2316either wrap around or use saturating addition depending on the value 2317of a special control register: 2318 2319@smallexample 2320(parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3) 2321 (reg:SI 4)] 0)) 2322 (use (reg:SI 1))]) 2323@end smallexample 2324 2325@noindent 2326 2327This will not work, several of the optimizers only look at expressions 2328locally; it is very likely that if you have multiple insns with 2329identical inputs to the @code{unspec}, they will be optimized away even 2330if register 1 changes in between. 2331 2332This means that @code{use} can @emph{only} be used to describe 2333that the register is live. You should think twice before adding 2334@code{use} statements, more often you will want to use @code{unspec} 2335instead. The @code{use} RTX is most commonly useful to describe that 2336a fixed register is implicitly used in an insn. It is also safe to use 2337in patterns where the compiler knows for other reasons that the result 2338of the whole pattern is variable, such as @samp{movstr@var{m}} or 2339@samp{call} patterns. 2340 2341During the reload phase, an insn that has a @code{use} as pattern 2342can carry a reg_equal note. These @code{use} insns will be deleted 2343before the reload phase exits. 2344 2345During the delayed branch scheduling phase, @var{x} may be an insn. 2346This indicates that @var{x} previously was located at this place in the 2347code and its data dependencies need to be taken into account. These 2348@code{use} insns will be deleted before the delayed branch scheduling 2349phase exits. 2350 2351@findex parallel 2352@item (parallel [@var{x0} @var{x1} @dots{}]) 2353Represents several side effects performed in parallel. The square 2354brackets stand for a vector; the operand of @code{parallel} is a 2355vector of expressions. @var{x0}, @var{x1} and so on are individual 2356side effect expressions---expressions of code @code{set}, @code{call}, 2357@code{return}, @code{clobber} or @code{use}. 2358 2359``In parallel'' means that first all the values used in the individual 2360side-effects are computed, and second all the actual side-effects are 2361performed. For example, 2362 2363@example 2364(parallel [(set (reg:SI 1) (mem:SI (reg:SI 1))) 2365 (set (mem:SI (reg:SI 1)) (reg:SI 1))]) 2366@end example 2367 2368@noindent 2369says unambiguously that the values of hard register 1 and the memory 2370location addressed by it are interchanged. In both places where 2371@code{(reg:SI 1)} appears as a memory address it refers to the value 2372in register 1 @emph{before} the execution of the insn. 2373 2374It follows that it is @emph{incorrect} to use @code{parallel} and 2375expect the result of one @code{set} to be available for the next one. 2376For example, people sometimes attempt to represent a jump-if-zero 2377instruction this way: 2378 2379@example 2380(parallel [(set (cc0) (reg:SI 34)) 2381 (set (pc) (if_then_else 2382 (eq (cc0) (const_int 0)) 2383 (label_ref @dots{}) 2384 (pc)))]) 2385@end example 2386 2387@noindent 2388But this is incorrect, because it says that the jump condition depends 2389on the condition code value @emph{before} this instruction, not on the 2390new value that is set by this instruction. 2391 2392@cindex peephole optimization, RTL representation 2393Peephole optimization, which takes place together with final assembly 2394code output, can produce insns whose patterns consist of a @code{parallel} 2395whose elements are the operands needed to output the resulting 2396assembler code---often @code{reg}, @code{mem} or constant expressions. 2397This would not be well-formed RTL at any other stage in compilation, 2398but it is ok then because no further optimization remains to be done. 2399However, the definition of the macro @code{NOTICE_UPDATE_CC}, if 2400any, must deal with such insns if you define any peephole optimizations. 2401 2402@findex cond_exec 2403@item (cond_exec [@var{cond} @var{expr}]) 2404Represents a conditionally executed expression. The @var{expr} is 2405executed only if the @var{cond} is nonzero. The @var{cond} expression 2406must not have side-effects, but the @var{expr} may very well have 2407side-effects. 2408 2409@findex sequence 2410@item (sequence [@var{insns} @dots{}]) 2411Represents a sequence of insns. Each of the @var{insns} that appears 2412in the vector is suitable for appearing in the chain of insns, so it 2413must be an @code{insn}, @code{jump_insn}, @code{call_insn}, 2414@code{code_label}, @code{barrier} or @code{note}. 2415 2416A @code{sequence} RTX is never placed in an actual insn during RTL 2417generation. It represents the sequence of insns that result from a 2418@code{define_expand} @emph{before} those insns are passed to 2419@code{emit_insn} to insert them in the chain of insns. When actually 2420inserted, the individual sub-insns are separated out and the 2421@code{sequence} is forgotten. 2422 2423After delay-slot scheduling is completed, an insn and all the insns that 2424reside in its delay slots are grouped together into a @code{sequence}. 2425The insn requiring the delay slot is the first insn in the vector; 2426subsequent insns are to be placed in the delay slot. 2427 2428@code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to 2429indicate that a branch insn should be used that will conditionally annul 2430the effect of the insns in the delay slots. In such a case, 2431@code{INSN_FROM_TARGET_P} indicates that the insn is from the target of 2432the branch and should be executed only if the branch is taken; otherwise 2433the insn should be executed only if the branch is not taken. 2434@xref{Delay Slots}. 2435@end table 2436 2437These expression codes appear in place of a side effect, as the body of 2438an insn, though strictly speaking they do not always describe side 2439effects as such: 2440 2441@table @code 2442@findex asm_input 2443@item (asm_input @var{s}) 2444Represents literal assembler code as described by the string @var{s}. 2445 2446@findex unspec 2447@findex unspec_volatile 2448@item (unspec [@var{operands} @dots{}] @var{index}) 2449@itemx (unspec_volatile [@var{operands} @dots{}] @var{index}) 2450Represents a machine-specific operation on @var{operands}. @var{index} 2451selects between multiple machine-specific operations. 2452@code{unspec_volatile} is used for volatile operations and operations 2453that may trap; @code{unspec} is used for other operations. 2454 2455These codes may appear inside a @code{pattern} of an 2456insn, inside a @code{parallel}, or inside an expression. 2457 2458@findex addr_vec 2459@item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}]) 2460Represents a table of jump addresses. The vector elements @var{lr0}, 2461etc., are @code{label_ref} expressions. The mode @var{m} specifies 2462how much space is given to each address; normally @var{m} would be 2463@code{Pmode}. 2464 2465@findex addr_diff_vec 2466@item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags}) 2467Represents a table of jump addresses expressed as offsets from 2468@var{base}. The vector elements @var{lr0}, etc., are @code{label_ref} 2469expressions and so is @var{base}. The mode @var{m} specifies how much 2470space is given to each address-difference. @var{min} and @var{max} 2471are set up by branch shortening and hold a label with a minimum and a 2472maximum address, respectively. @var{flags} indicates the relative 2473position of @var{base}, @var{min} and @var{max} to the containing insn 2474and of @var{min} and @var{max} to @var{base}. See rtl.def for details. 2475 2476@findex prefetch 2477@item (prefetch:@var{m} @var{addr} @var{rw} @var{locality}) 2478Represents prefetch of memory at address @var{addr}. 2479Operand @var{rw} is 1 if the prefetch is for data to be written, 0 otherwise; 2480targets that do not support write prefetches should treat this as a normal 2481prefetch. 2482Operand @var{locality} specifies the amount of temporal locality; 0 if there 2483is none or 1, 2, or 3 for increasing levels of temporal locality; 2484targets that do not support locality hints should ignore this. 2485 2486This insn is used to minimize cache-miss latency by moving data into a 2487cache before it is accessed. It should use only non-faulting data prefetch 2488instructions. 2489@end table 2490 2491@node Incdec 2492@section Embedded Side-Effects on Addresses 2493@cindex RTL preincrement 2494@cindex RTL postincrement 2495@cindex RTL predecrement 2496@cindex RTL postdecrement 2497 2498Six special side-effect expression codes appear as memory addresses. 2499 2500@table @code 2501@findex pre_dec 2502@item (pre_dec:@var{m} @var{x}) 2503Represents the side effect of decrementing @var{x} by a standard 2504amount and represents also the value that @var{x} has after being 2505decremented. @var{x} must be a @code{reg} or @code{mem}, but most 2506machines allow only a @code{reg}. @var{m} must be the machine mode 2507for pointers on the machine in use. The amount @var{x} is decremented 2508by is the length in bytes of the machine mode of the containing memory 2509reference of which this expression serves as the address. Here is an 2510example of its use: 2511 2512@example 2513(mem:DF (pre_dec:SI (reg:SI 39))) 2514@end example 2515 2516@noindent 2517This says to decrement pseudo register 39 by the length of a @code{DFmode} 2518value and use the result to address a @code{DFmode} value. 2519 2520@findex pre_inc 2521@item (pre_inc:@var{m} @var{x}) 2522Similar, but specifies incrementing @var{x} instead of decrementing it. 2523 2524@findex post_dec 2525@item (post_dec:@var{m} @var{x}) 2526Represents the same side effect as @code{pre_dec} but a different 2527value. The value represented here is the value @var{x} has @i{before} 2528being decremented. 2529 2530@findex post_inc 2531@item (post_inc:@var{m} @var{x}) 2532Similar, but specifies incrementing @var{x} instead of decrementing it. 2533 2534@findex post_modify 2535@item (post_modify:@var{m} @var{x} @var{y}) 2536 2537Represents the side effect of setting @var{x} to @var{y} and 2538represents @var{x} before @var{x} is modified. @var{x} must be a 2539@code{reg} or @code{mem}, but most machines allow only a @code{reg}. 2540@var{m} must be the machine mode for pointers on the machine in use. 2541The amount @var{x} is decremented by is the length in bytes of the 2542machine mode of the containing memory reference of which this expression 2543serves as the address. Note that this is not currently implemented. 2544 2545The expression @var{y} must be one of three forms: 2546@table @code 2547@code{(plus:@var{m} @var{x} @var{z})}, 2548@code{(minus:@var{m} @var{x} @var{z})}, or 2549@code{(plus:@var{m} @var{x} @var{i})}, 2550@end table 2551where @var{z} is an index register and @var{i} is a constant. 2552 2553Here is an example of its use: 2554 2555@smallexample 2556(mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42) 2557 (reg:SI 48)))) 2558@end smallexample 2559 2560This says to modify pseudo register 42 by adding the contents of pseudo 2561register 48 to it, after the use of what ever 42 points to. 2562 2563@findex post_modify 2564@item (pre_modify:@var{m} @var{x} @var{expr}) 2565Similar except side effects happen before the use. 2566@end table 2567 2568These embedded side effect expressions must be used with care. Instruction 2569patterns may not use them. Until the @samp{flow} pass of the compiler, 2570they may occur only to represent pushes onto the stack. The @samp{flow} 2571pass finds cases where registers are incremented or decremented in one 2572instruction and used as an address shortly before or after; these cases are 2573then transformed to use pre- or post-increment or -decrement. 2574 2575If a register used as the operand of these expressions is used in 2576another address in an insn, the original value of the register is used. 2577Uses of the register outside of an address are not permitted within the 2578same insn as a use in an embedded side effect expression because such 2579insns behave differently on different machines and hence must be treated 2580as ambiguous and disallowed. 2581 2582An instruction that can be represented with an embedded side effect 2583could also be represented using @code{parallel} containing an additional 2584@code{set} to describe how the address register is altered. This is not 2585done because machines that allow these operations at all typically 2586allow them wherever a memory address is called for. Describing them as 2587additional parallel stores would require doubling the number of entries 2588in the machine description. 2589 2590@node Assembler 2591@section Assembler Instructions as Expressions 2592@cindex assembler instructions in RTL 2593 2594@cindex @code{asm_operands}, usage 2595The RTX code @code{asm_operands} represents a value produced by a 2596user-specified assembler instruction. It is used to represent 2597an @code{asm} statement with arguments. An @code{asm} statement with 2598a single output operand, like this: 2599 2600@smallexample 2601asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z)); 2602@end smallexample 2603 2604@noindent 2605is represented using a single @code{asm_operands} RTX which represents 2606the value that is stored in @code{outputvar}: 2607 2608@smallexample 2609(set @var{rtx-for-outputvar} 2610 (asm_operands "foo %1,%2,%0" "a" 0 2611 [@var{rtx-for-addition-result} @var{rtx-for-*z}] 2612 [(asm_input:@var{m1} "g") 2613 (asm_input:@var{m2} "di")])) 2614@end smallexample 2615 2616@noindent 2617Here the operands of the @code{asm_operands} RTX are the assembler 2618template string, the output-operand's constraint, the index-number of the 2619output operand among the output operands specified, a vector of input 2620operand RTX's, and a vector of input-operand modes and constraints. The 2621mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of 2622@code{*z}. 2623 2624When an @code{asm} statement has multiple output values, its insn has 2625several such @code{set} RTX's inside of a @code{parallel}. Each @code{set} 2626contains a @code{asm_operands}; all of these share the same assembler 2627template and vectors, but each contains the constraint for the respective 2628output operand. They are also distinguished by the output-operand index 2629number, which is 0, 1, @dots{} for successive output operands. 2630 2631@node Insns 2632@section Insns 2633@cindex insns 2634 2635The RTL representation of the code for a function is a doubly-linked 2636chain of objects called @dfn{insns}. Insns are expressions with 2637special codes that are used for no other purpose. Some insns are 2638actual instructions; others represent dispatch tables for @code{switch} 2639statements; others represent labels to jump to or various sorts of 2640declarative information. 2641 2642In addition to its own specific data, each insn must have a unique 2643id-number that distinguishes it from all other insns in the current 2644function (after delayed branch scheduling, copies of an insn with the 2645same id-number may be present in multiple places in a function, but 2646these copies will always be identical and will only appear inside a 2647@code{sequence}), and chain pointers to the preceding and following 2648insns. These three fields occupy the same position in every insn, 2649independent of the expression code of the insn. They could be accessed 2650with @code{XEXP} and @code{XINT}, but instead three special macros are 2651always used: 2652 2653@table @code 2654@findex INSN_UID 2655@item INSN_UID (@var{i}) 2656Accesses the unique id of insn @var{i}. 2657 2658@findex PREV_INSN 2659@item PREV_INSN (@var{i}) 2660Accesses the chain pointer to the insn preceding @var{i}. 2661If @var{i} is the first insn, this is a null pointer. 2662 2663@findex NEXT_INSN 2664@item NEXT_INSN (@var{i}) 2665Accesses the chain pointer to the insn following @var{i}. 2666If @var{i} is the last insn, this is a null pointer. 2667@end table 2668 2669@findex get_insns 2670@findex get_last_insn 2671The first insn in the chain is obtained by calling @code{get_insns}; the 2672last insn is the result of calling @code{get_last_insn}. Within the 2673chain delimited by these insns, the @code{NEXT_INSN} and 2674@code{PREV_INSN} pointers must always correspond: if @var{insn} is not 2675the first insn, 2676 2677@example 2678NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn} 2679@end example 2680 2681@noindent 2682is always true and if @var{insn} is not the last insn, 2683 2684@example 2685PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn} 2686@end example 2687 2688@noindent 2689is always true. 2690 2691After delay slot scheduling, some of the insns in the chain might be 2692@code{sequence} expressions, which contain a vector of insns. The value 2693of @code{NEXT_INSN} in all but the last of these insns is the next insn 2694in the vector; the value of @code{NEXT_INSN} of the last insn in the vector 2695is the same as the value of @code{NEXT_INSN} for the @code{sequence} in 2696which it is contained. Similar rules apply for @code{PREV_INSN}. 2697 2698This means that the above invariants are not necessarily true for insns 2699inside @code{sequence} expressions. Specifically, if @var{insn} is the 2700first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))} 2701is the insn containing the @code{sequence} expression, as is the value 2702of @code{PREV_INSN (NEXT_INSN (@var{insn}))} if @var{insn} is the last 2703insn in the @code{sequence} expression. You can use these expressions 2704to find the containing @code{sequence} expression. 2705 2706Every insn has one of the following six expression codes: 2707 2708@table @code 2709@findex insn 2710@item insn 2711The expression code @code{insn} is used for instructions that do not jump 2712and do not do function calls. @code{sequence} expressions are always 2713contained in insns with code @code{insn} even if one of those insns 2714should jump or do function calls. 2715 2716Insns with code @code{insn} have four additional fields beyond the three 2717mandatory ones listed above. These four are described in a table below. 2718 2719@findex jump_insn 2720@item jump_insn 2721The expression code @code{jump_insn} is used for instructions that may 2722jump (or, more generally, may contain @code{label_ref} expressions). If 2723there is an instruction to return from the current function, it is 2724recorded as a @code{jump_insn}. 2725 2726@findex JUMP_LABEL 2727@code{jump_insn} insns have the same extra fields as @code{insn} insns, 2728accessed in the same way and in addition contain a field 2729@code{JUMP_LABEL} which is defined once jump optimization has completed. 2730 2731For simple conditional and unconditional jumps, this field contains 2732the @code{code_label} to which this insn will (possibly conditionally) 2733branch. In a more complex jump, @code{JUMP_LABEL} records one of the 2734labels that the insn refers to; the only way to find the others is to 2735scan the entire body of the insn. In an @code{addr_vec}, 2736@code{JUMP_LABEL} is @code{NULL_RTX}. 2737 2738Return insns count as jumps, but since they do not refer to any 2739labels, their @code{JUMP_LABEL} is @code{NULL_RTX}. 2740 2741@findex call_insn 2742@item call_insn 2743The expression code @code{call_insn} is used for instructions that may do 2744function calls. It is important to distinguish these instructions because 2745they imply that certain registers and memory locations may be altered 2746unpredictably. 2747 2748@findex CALL_INSN_FUNCTION_USAGE 2749@code{call_insn} insns have the same extra fields as @code{insn} insns, 2750accessed in the same way and in addition contain a field 2751@code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of 2752@code{expr_list} expressions) containing @code{use} and @code{clobber} 2753expressions that denote hard registers and @code{MEM}s used or 2754clobbered by the called function. 2755 2756A @code{MEM} generally points to a stack slots in which arguments passed 2757to the libcall by reference (@pxref{Register Arguments, 2758FUNCTION_ARG_PASS_BY_REFERENCE}) are stored. If the argument is 2759caller-copied (@pxref{Register Arguments, FUNCTION_ARG_CALLEE_COPIES}), 2760the stack slot will be mentioned in @code{CLOBBER} and @code{USE} 2761entries; if it's callee-copied, only a @code{USE} will appear, and the 2762@code{MEM} may point to addresses that are not stack slots. These 2763@code{MEM}s are used only in libcalls, because, unlike regular function 2764calls, @code{CONST_CALL}s (which libcalls generally are, @pxref{Flags, 2765CONST_CALL_P}) aren't assumed to read and write all memory, so flow 2766would consider the stores dead and remove them. Note that, since a 2767libcall must never return values in memory (@pxref{Aggregate Return, 2768RETURN_IN_MEMORY}), there will never be a @code{CLOBBER} for a memory 2769address holding a return value. 2770 2771@code{CLOBBER}ed registers in this list augment registers specified in 2772@code{CALL_USED_REGISTERS} (@pxref{Register Basics}). 2773 2774@findex code_label 2775@findex CODE_LABEL_NUMBER 2776@item code_label 2777A @code{code_label} insn represents a label that a jump insn can jump 2778to. It contains two special fields of data in addition to the three 2779standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label 2780number}, a number that identifies this label uniquely among all the 2781labels in the compilation (not just in the current function). 2782Ultimately, the label is represented in the assembler output as an 2783assembler label, usually of the form @samp{L@var{n}} where @var{n} is 2784the label number. 2785 2786When a @code{code_label} appears in an RTL expression, it normally 2787appears within a @code{label_ref} which represents the address of 2788the label, as a number. 2789 2790Besides as a @code{code_label}, a label can also be represented as a 2791@code{note} of type @code{NOTE_INSN_DELETED_LABEL}. 2792 2793@findex LABEL_NUSES 2794The field @code{LABEL_NUSES} is only defined once the jump optimization 2795phase is completed and contains the number of times this label is 2796referenced in the current function. 2797 2798@findex LABEL_ALTERNATE_NAME 2799The field @code{LABEL_ALTERNATE_NAME} is used to associate a name with 2800a @code{code_label}. If this field is defined, the alternate name will 2801be emitted instead of an internally generated label name. 2802 2803@findex barrier 2804@item barrier 2805Barriers are placed in the instruction stream when control cannot flow 2806past them. They are placed after unconditional jump instructions to 2807indicate that the jumps are unconditional and after calls to 2808@code{volatile} functions, which do not return (e.g., @code{exit}). 2809They contain no information beyond the three standard fields. 2810 2811@findex note 2812@findex NOTE_LINE_NUMBER 2813@findex NOTE_SOURCE_FILE 2814@item note 2815@code{note} insns are used to represent additional debugging and 2816declarative information. They contain two nonstandard fields, an 2817integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a 2818string accessed with @code{NOTE_SOURCE_FILE}. 2819 2820If @code{NOTE_LINE_NUMBER} is positive, the note represents the 2821position of a source line and @code{NOTE_SOURCE_FILE} is the source file name 2822that the line came from. These notes control generation of line 2823number data in the assembler output. 2824 2825Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a 2826code with one of the following values (and @code{NOTE_SOURCE_FILE} 2827must contain a null pointer): 2828 2829@table @code 2830@findex NOTE_INSN_DELETED 2831@item NOTE_INSN_DELETED 2832Such a note is completely ignorable. Some passes of the compiler 2833delete insns by altering them into notes of this kind. 2834 2835@findex NOTE_INSN_DELETED_LABEL 2836@item NOTE_INSN_DELETED_LABEL 2837This marks what used to be a @code{code_label}, but was not used for other 2838purposes than taking its address and was transformed to mark that no 2839code jumps to it. 2840 2841@findex NOTE_INSN_BLOCK_BEG 2842@findex NOTE_INSN_BLOCK_END 2843@item NOTE_INSN_BLOCK_BEG 2844@itemx NOTE_INSN_BLOCK_END 2845These types of notes indicate the position of the beginning and end 2846of a level of scoping of variable names. They control the output 2847of debugging information. 2848 2849@findex NOTE_INSN_EH_REGION_BEG 2850@findex NOTE_INSN_EH_REGION_END 2851@item NOTE_INSN_EH_REGION_BEG 2852@itemx NOTE_INSN_EH_REGION_END 2853These types of notes indicate the position of the beginning and end of a 2854level of scoping for exception handling. @code{NOTE_BLOCK_NUMBER} 2855identifies which @code{CODE_LABEL} or @code{note} of type 2856@code{NOTE_INSN_DELETED_LABEL} is associated with the given region. 2857 2858@findex NOTE_INSN_LOOP_BEG 2859@findex NOTE_INSN_LOOP_END 2860@item NOTE_INSN_LOOP_BEG 2861@itemx NOTE_INSN_LOOP_END 2862These types of notes indicate the position of the beginning and end 2863of a @code{while} or @code{for} loop. They enable the loop optimizer 2864to find loops quickly. 2865 2866@findex NOTE_INSN_LOOP_CONT 2867@item NOTE_INSN_LOOP_CONT 2868Appears at the place in a loop that @code{continue} statements jump to. 2869 2870@findex NOTE_INSN_LOOP_VTOP 2871@item NOTE_INSN_LOOP_VTOP 2872This note indicates the place in a loop where the exit test begins for 2873those loops in which the exit test has been duplicated. This position 2874becomes another virtual start of the loop when considering loop 2875invariants. 2876 2877@findex NOTE_INSN_FUNCTION_END 2878@item NOTE_INSN_FUNCTION_END 2879Appears near the end of the function body, just before the label that 2880@code{return} statements jump to (on machine where a single instruction 2881does not suffice for returning). This note may be deleted by jump 2882optimization. 2883 2884@findex NOTE_INSN_SETJMP 2885@item NOTE_INSN_SETJMP 2886Appears following each call to @code{setjmp} or a related function. 2887@end table 2888 2889These codes are printed symbolically when they appear in debugging dumps. 2890@end table 2891 2892@cindex @code{TImode}, in @code{insn} 2893@cindex @code{HImode}, in @code{insn} 2894@cindex @code{QImode}, in @code{insn} 2895The machine mode of an insn is normally @code{VOIDmode}, but some 2896phases use the mode for various purposes. 2897 2898The common subexpression elimination pass sets the mode of an insn to 2899@code{QImode} when it is the first insn in a block that has already 2900been processed. 2901 2902The second Haifa scheduling pass, for targets that can multiple issue, 2903sets the mode of an insn to @code{TImode} when it is believed that the 2904instruction begins an issue group. That is, when the instruction 2905cannot issue simultaneously with the previous. This may be relied on 2906by later passes, in particular machine-dependent reorg. 2907 2908Here is a table of the extra fields of @code{insn}, @code{jump_insn} 2909and @code{call_insn} insns: 2910 2911@table @code 2912@findex PATTERN 2913@item PATTERN (@var{i}) 2914An expression for the side effect performed by this insn. This must be 2915one of the following codes: @code{set}, @code{call}, @code{use}, 2916@code{clobber}, @code{return}, @code{asm_input}, @code{asm_output}, 2917@code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec}, 2918@code{unspec_volatile}, @code{parallel}, @code{cond_exec}, or @code{sequence}. If it is a @code{parallel}, 2919each element of the @code{parallel} must be one these codes, except that 2920@code{parallel} expressions cannot be nested and @code{addr_vec} and 2921@code{addr_diff_vec} are not permitted inside a @code{parallel} expression. 2922 2923@findex INSN_CODE 2924@item INSN_CODE (@var{i}) 2925An integer that says which pattern in the machine description matches 2926this insn, or @minus{}1 if the matching has not yet been attempted. 2927 2928Such matching is never attempted and this field remains @minus{}1 on an insn 2929whose pattern consists of a single @code{use}, @code{clobber}, 2930@code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression. 2931 2932@findex asm_noperands 2933Matching is also never attempted on insns that result from an @code{asm} 2934statement. These contain at least one @code{asm_operands} expression. 2935The function @code{asm_noperands} returns a non-negative value for 2936such insns. 2937 2938In the debugging output, this field is printed as a number followed by 2939a symbolic representation that locates the pattern in the @file{md} 2940file as some small positive or negative offset from a named pattern. 2941 2942@findex LOG_LINKS 2943@item LOG_LINKS (@var{i}) 2944A list (chain of @code{insn_list} expressions) giving information about 2945dependencies between instructions within a basic block. Neither a jump 2946nor a label may come between the related insns. 2947 2948@findex REG_NOTES 2949@item REG_NOTES (@var{i}) 2950A list (chain of @code{expr_list} and @code{insn_list} expressions) 2951giving miscellaneous information about the insn. It is often 2952information pertaining to the registers used in this insn. 2953@end table 2954 2955The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list} 2956expressions. Each of these has two operands: the first is an insn, 2957and the second is another @code{insn_list} expression (the next one in 2958the chain). The last @code{insn_list} in the chain has a null pointer 2959as second operand. The significant thing about the chain is which 2960insns appear in it (as first operands of @code{insn_list} 2961expressions). Their order is not significant. 2962 2963This list is originally set up by the flow analysis pass; it is a null 2964pointer until then. Flow only adds links for those data dependencies 2965which can be used for instruction combination. For each insn, the flow 2966analysis pass adds a link to insns which store into registers values 2967that are used for the first time in this insn. The instruction 2968scheduling pass adds extra links so that every dependence will be 2969represented. Links represent data dependencies, antidependencies and 2970output dependencies; the machine mode of the link distinguishes these 2971three types: antidependencies have mode @code{REG_DEP_ANTI}, output 2972dependencies have mode @code{REG_DEP_OUTPUT}, and data dependencies have 2973mode @code{VOIDmode}. 2974 2975The @code{REG_NOTES} field of an insn is a chain similar to the 2976@code{LOG_LINKS} field but it includes @code{expr_list} expressions in 2977addition to @code{insn_list} expressions. There are several kinds of 2978register notes, which are distinguished by the machine mode, which in a 2979register note is really understood as being an @code{enum reg_note}. 2980The first operand @var{op} of the note is data whose meaning depends on 2981the kind of note. 2982 2983@findex REG_NOTE_KIND 2984@findex PUT_REG_NOTE_KIND 2985The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of 2986register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND 2987(@var{x}, @var{newkind})} sets the register note type of @var{x} to be 2988@var{newkind}. 2989 2990Register notes are of three classes: They may say something about an 2991input to an insn, they may say something about an output of an insn, or 2992they may create a linkage between two insns. There are also a set 2993of values that are only used in @code{LOG_LINKS}. 2994 2995These register notes annotate inputs to an insn: 2996 2997@table @code 2998@findex REG_DEAD 2999@item REG_DEAD 3000The value in @var{op} dies in this insn; that is to say, altering the 3001value immediately after this insn would not affect the future behavior 3002of the program. 3003 3004It does not follow that the register @var{op} has no useful value after 3005this insn since @var{op} is not necessarily modified by this insn. 3006Rather, no subsequent instruction uses the contents of @var{op}. 3007 3008@findex REG_UNUSED 3009@item REG_UNUSED 3010The register @var{op} being set by this insn will not be used in a 3011subsequent insn. This differs from a @code{REG_DEAD} note, which 3012indicates that the value in an input will not be used subsequently. 3013These two notes are independent; both may be present for the same 3014register. 3015 3016@findex REG_INC 3017@item REG_INC 3018The register @var{op} is incremented (or decremented; at this level 3019there is no distinction) by an embedded side effect inside this insn. 3020This means it appears in a @code{post_inc}, @code{pre_inc}, 3021@code{post_dec} or @code{pre_dec} expression. 3022 3023@findex REG_NONNEG 3024@item REG_NONNEG 3025The register @var{op} is known to have a nonnegative value when this 3026insn is reached. This is used so that decrement and branch until zero 3027instructions, such as the m68k dbra, can be matched. 3028 3029The @code{REG_NONNEG} note is added to insns only if the machine 3030description has a @samp{decrement_and_branch_until_zero} pattern. 3031 3032@findex REG_NO_CONFLICT 3033@item REG_NO_CONFLICT 3034This insn does not cause a conflict between @var{op} and the item 3035being set by this insn even though it might appear that it does. 3036In other words, if the destination register and @var{op} could 3037otherwise be assigned the same register, this insn does not 3038prevent that assignment. 3039 3040Insns with this note are usually part of a block that begins with a 3041@code{clobber} insn specifying a multi-word pseudo register (which will 3042be the output of the block), a group of insns that each set one word of 3043the value and have the @code{REG_NO_CONFLICT} note attached, and a final 3044insn that copies the output to itself with an attached @code{REG_EQUAL} 3045note giving the expression being computed. This block is encapsulated 3046with @code{REG_LIBCALL} and @code{REG_RETVAL} notes on the first and 3047last insns, respectively. 3048 3049@findex REG_LABEL 3050@item REG_LABEL 3051This insn uses @var{op}, a @code{code_label} or a @code{note} of type 3052@code{NOTE_INSN_DELETED_LABEL}, but is not a 3053@code{jump_insn}, or it is a @code{jump_insn} that required the label to 3054be held in a register. The presence of this note allows jump 3055optimization to be aware that @var{op} is, in fact, being used, and flow 3056optimization to build an accurate flow graph. 3057@end table 3058 3059The following notes describe attributes of outputs of an insn: 3060 3061@table @code 3062@findex REG_EQUIV 3063@findex REG_EQUAL 3064@item REG_EQUIV 3065@itemx REG_EQUAL 3066This note is only valid on an insn that sets only one register and 3067indicates that that register will be equal to @var{op} at run time; the 3068scope of this equivalence differs between the two types of notes. The 3069value which the insn explicitly copies into the register may look 3070different from @var{op}, but they will be equal at run time. If the 3071output of the single @code{set} is a @code{strict_low_part} expression, 3072the note refers to the register that is contained in @code{SUBREG_REG} 3073of the @code{subreg} expression. 3074 3075For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout 3076the entire function, and could validly be replaced in all its 3077occurrences by @var{op}. (``Validly'' here refers to the data flow of 3078the program; simple replacement may make some insns invalid.) For 3079example, when a constant is loaded into a register that is never 3080assigned any other value, this kind of note is used. 3081 3082When a parameter is copied into a pseudo-register at entry to a function, 3083a note of this kind records that the register is equivalent to the stack 3084slot where the parameter was passed. Although in this case the register 3085may be set by other insns, it is still valid to replace the register 3086by the stack slot throughout the function. 3087 3088A @code{REG_EQUIV} note is also used on an instruction which copies a 3089register parameter into a pseudo-register at entry to a function, if 3090there is a stack slot where that parameter could be stored. Although 3091other insns may set the pseudo-register, it is valid for the compiler to 3092replace the pseudo-register by stack slot throughout the function, 3093provided the compiler ensures that the stack slot is properly 3094initialized by making the replacement in the initial copy instruction as 3095well. This is used on machines for which the calling convention 3096allocates stack space for register parameters. See 3097@code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}. 3098 3099In the case of @code{REG_EQUAL}, the register that is set by this insn 3100will be equal to @var{op} at run time at the end of this insn but not 3101necessarily elsewhere in the function. In this case, @var{op} 3102is typically an arithmetic expression. For example, when a sequence of 3103insns such as a library call is used to perform an arithmetic operation, 3104this kind of note is attached to the insn that produces or copies the 3105final value. 3106 3107These two notes are used in different ways by the compiler passes. 3108@code{REG_EQUAL} is used by passes prior to register allocation (such as 3109common subexpression elimination and loop optimization) to tell them how 3110to think of that value. @code{REG_EQUIV} notes are used by register 3111allocation to indicate that there is an available substitute expression 3112(either a constant or a @code{mem} expression for the location of a 3113parameter on the stack) that may be used in place of a register if 3114insufficient registers are available. 3115 3116Except for stack homes for parameters, which are indicated by a 3117@code{REG_EQUIV} note and are not useful to the early optimization 3118passes and pseudo registers that are equivalent to a memory location 3119throughout their entire life, which is not detected until later in 3120the compilation, all equivalences are initially indicated by an attached 3121@code{REG_EQUAL} note. In the early stages of register allocation, a 3122@code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if 3123@var{op} is a constant and the insn represents the only set of its 3124destination register. 3125 3126Thus, compiler passes prior to register allocation need only check for 3127@code{REG_EQUAL} notes and passes subsequent to register allocation 3128need only check for @code{REG_EQUIV} notes. 3129 3130@findex REG_WAS_0 3131@item REG_WAS_0 3132The single output of this insn contained zero before this insn. 3133@var{op} is the insn that set it to zero. You can rely on this note if 3134it is present and @var{op} has not been deleted or turned into a @code{note}; 3135its absence implies nothing. 3136@end table 3137 3138These notes describe linkages between insns. They occur in pairs: one 3139insn has one of a pair of notes that points to a second insn, which has 3140the inverse note pointing back to the first insn. 3141 3142@table @code 3143@findex REG_RETVAL 3144@item REG_RETVAL 3145This insn copies the value of a multi-insn sequence (for example, a 3146library call), and @var{op} is the first insn of the sequence (for a 3147library call, the first insn that was generated to set up the arguments 3148for the library call). 3149 3150Loop optimization uses this note to treat such a sequence as a single 3151operation for code motion purposes and flow analysis uses this note to 3152delete such sequences whose results are dead. 3153 3154A @code{REG_EQUAL} note will also usually be attached to this insn to 3155provide the expression being computed by the sequence. 3156 3157These notes will be deleted after reload, since they are no longer 3158accurate or useful. 3159 3160@findex REG_LIBCALL 3161@item REG_LIBCALL 3162This is the inverse of @code{REG_RETVAL}: it is placed on the first 3163insn of a multi-insn sequence, and it points to the last one. 3164 3165These notes are deleted after reload, since they are no longer useful or 3166accurate. 3167 3168@findex REG_CC_SETTER 3169@findex REG_CC_USER 3170@item REG_CC_SETTER 3171@itemx REG_CC_USER 3172On machines that use @code{cc0}, the insns which set and use @code{cc0} 3173set and use @code{cc0} are adjacent. However, when branch delay slot 3174filling is done, this may no longer be true. In this case a 3175@code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to 3176point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will 3177be placed on the insn using @code{cc0} to point to the insn setting 3178@code{cc0}. 3179@end table 3180 3181These values are only used in the @code{LOG_LINKS} field, and indicate 3182the type of dependency that each link represents. Links which indicate 3183a data dependence (a read after write dependence) do not use any code, 3184they simply have mode @code{VOIDmode}, and are printed without any 3185descriptive text. 3186 3187@table @code 3188@findex REG_DEP_ANTI 3189@item REG_DEP_ANTI 3190This indicates an anti dependence (a write after read dependence). 3191 3192@findex REG_DEP_OUTPUT 3193@item REG_DEP_OUTPUT 3194This indicates an output dependence (a write after write dependence). 3195@end table 3196 3197These notes describe information gathered from gcov profile data. They 3198are stored in the @code{REG_NOTES} field of an insn as an 3199@code{expr_list}. 3200 3201@table @code 3202@findex REG_EXEC_COUNT 3203@item REG_EXEC_COUNT 3204This is used to indicate the number of times a basic block was executed 3205according to the profile data. The note is attached to the first insn in 3206the basic block. 3207 3208@findex REG_BR_PROB 3209@item REG_BR_PROB 3210This is used to specify the ratio of branches to non-branches of a 3211branch insn according to the profile data. The value is stored as a 3212value between 0 and REG_BR_PROB_BASE; larger values indicate a higher 3213probability that the branch will be taken. 3214 3215@findex REG_BR_PRED 3216@item REG_BR_PRED 3217These notes are found in JUMP insns after delayed branch scheduling 3218has taken place. They indicate both the direction and the likelihood 3219of the JUMP@. The format is a bitmask of ATTR_FLAG_* values. 3220 3221@findex REG_FRAME_RELATED_EXPR 3222@item REG_FRAME_RELATED_EXPR 3223This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression 3224is used in place of the actual insn pattern. This is done in cases where 3225the pattern is either complex or misleading. 3226@end table 3227 3228For convenience, the machine mode in an @code{insn_list} or 3229@code{expr_list} is printed using these symbolic codes in debugging dumps. 3230 3231@findex insn_list 3232@findex expr_list 3233The only difference between the expression codes @code{insn_list} and 3234@code{expr_list} is that the first operand of an @code{insn_list} is 3235assumed to be an insn and is printed in debugging dumps as the insn's 3236unique id; the first operand of an @code{expr_list} is printed in the 3237ordinary way as an expression. 3238 3239@node Calls 3240@section RTL Representation of Function-Call Insns 3241@cindex calling functions in RTL 3242@cindex RTL function-call insns 3243@cindex function-call insns 3244 3245Insns that call subroutines have the RTL expression code @code{call_insn}. 3246These insns must satisfy special rules, and their bodies must use a special 3247RTL expression code, @code{call}. 3248 3249@cindex @code{call} usage 3250A @code{call} expression has two operands, as follows: 3251 3252@example 3253(call (mem:@var{fm} @var{addr}) @var{nbytes}) 3254@end example 3255 3256@noindent 3257Here @var{nbytes} is an operand that represents the number of bytes of 3258argument data being passed to the subroutine, @var{fm} is a machine mode 3259(which must equal as the definition of the @code{FUNCTION_MODE} macro in 3260the machine description) and @var{addr} represents the address of the 3261subroutine. 3262 3263For a subroutine that returns no value, the @code{call} expression as 3264shown above is the entire body of the insn, except that the insn might 3265also contain @code{use} or @code{clobber} expressions. 3266 3267@cindex @code{BLKmode}, and function return values 3268For a subroutine that returns a value whose mode is not @code{BLKmode}, 3269the value is returned in a hard register. If this register's number is 3270@var{r}, then the body of the call insn looks like this: 3271 3272@example 3273(set (reg:@var{m} @var{r}) 3274 (call (mem:@var{fm} @var{addr}) @var{nbytes})) 3275@end example 3276 3277@noindent 3278This RTL expression makes it clear (to the optimizer passes) that the 3279appropriate register receives a useful value in this insn. 3280 3281When a subroutine returns a @code{BLKmode} value, it is handled by 3282passing to the subroutine the address of a place to store the value. 3283So the call insn itself does not ``return'' any value, and it has the 3284same RTL form as a call that returns nothing. 3285 3286On some machines, the call instruction itself clobbers some register, 3287for example to contain the return address. @code{call_insn} insns 3288on these machines should have a body which is a @code{parallel} 3289that contains both the @code{call} expression and @code{clobber} 3290expressions that indicate which registers are destroyed. Similarly, 3291if the call instruction requires some register other than the stack 3292pointer that is not explicitly mentioned it its RTL, a @code{use} 3293subexpression should mention that register. 3294 3295Functions that are called are assumed to modify all registers listed in 3296the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register 3297Basics}) and, with the exception of @code{const} functions and library 3298calls, to modify all of memory. 3299 3300Insns containing just @code{use} expressions directly precede the 3301@code{call_insn} insn to indicate which registers contain inputs to the 3302function. Similarly, if registers other than those in 3303@code{CALL_USED_REGISTERS} are clobbered by the called function, insns 3304containing a single @code{clobber} follow immediately after the call to 3305indicate which registers. 3306 3307@node Sharing 3308@section Structure Sharing Assumptions 3309@cindex sharing of RTL components 3310@cindex RTL structure sharing assumptions 3311 3312The compiler assumes that certain kinds of RTL expressions are unique; 3313there do not exist two distinct objects representing the same value. 3314In other cases, it makes an opposite assumption: that no RTL expression 3315object of a certain kind appears in more than one place in the 3316containing structure. 3317 3318These assumptions refer to a single function; except for the RTL 3319objects that describe global variables and external functions, 3320and a few standard objects such as small integer constants, 3321no RTL objects are common to two functions. 3322 3323@itemize @bullet 3324@cindex @code{reg}, RTL sharing 3325@item 3326Each pseudo-register has only a single @code{reg} object to represent it, 3327and therefore only a single machine mode. 3328 3329@cindex symbolic label 3330@cindex @code{symbol_ref}, RTL sharing 3331@item 3332For any symbolic label, there is only one @code{symbol_ref} object 3333referring to it. 3334 3335@cindex @code{const_int}, RTL sharing 3336@item 3337All @code{const_int} expressions with equal values are shared. 3338 3339@cindex @code{pc}, RTL sharing 3340@item 3341There is only one @code{pc} expression. 3342 3343@cindex @code{cc0}, RTL sharing 3344@item 3345There is only one @code{cc0} expression. 3346 3347@cindex @code{const_double}, RTL sharing 3348@item 3349There is only one @code{const_double} expression with value 0 for 3350each floating point mode. Likewise for values 1 and 2. 3351 3352@cindex @code{const_vector}, RTL sharing 3353@item 3354There is only one @code{const_vector} expression with value 0 for 3355each vector mode, be it an integer or a double constant vector. 3356 3357@cindex @code{label_ref}, RTL sharing 3358@cindex @code{scratch}, RTL sharing 3359@item 3360No @code{label_ref} or @code{scratch} appears in more than one place in 3361the RTL structure; in other words, it is safe to do a tree-walk of all 3362the insns in the function and assume that each time a @code{label_ref} 3363or @code{scratch} is seen it is distinct from all others that are seen. 3364 3365@cindex @code{mem}, RTL sharing 3366@item 3367Only one @code{mem} object is normally created for each static 3368variable or stack slot, so these objects are frequently shared in all 3369the places they appear. However, separate but equal objects for these 3370variables are occasionally made. 3371 3372@cindex @code{asm_operands}, RTL sharing 3373@item 3374When a single @code{asm} statement has multiple output operands, a 3375distinct @code{asm_operands} expression is made for each output operand. 3376However, these all share the vector which contains the sequence of input 3377operands. This sharing is used later on to test whether two 3378@code{asm_operands} expressions come from the same statement, so all 3379optimizations must carefully preserve the sharing if they copy the 3380vector at all. 3381 3382@item 3383No RTL object appears in more than one place in the RTL structure 3384except as described above. Many passes of the compiler rely on this 3385by assuming that they can modify RTL objects in place without unwanted 3386side-effects on other insns. 3387 3388@findex unshare_all_rtl 3389@item 3390During initial RTL generation, shared structure is freely introduced. 3391After all the RTL for a function has been generated, all shared 3392structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c}, 3393after which the above rules are guaranteed to be followed. 3394 3395@findex copy_rtx_if_shared 3396@item 3397During the combiner pass, shared structure within an insn can exist 3398temporarily. However, the shared structure is copied before the 3399combiner is finished with the insn. This is done by calling 3400@code{copy_rtx_if_shared}, which is a subroutine of 3401@code{unshare_all_rtl}. 3402@end itemize 3403 3404@node Reading RTL 3405@section Reading RTL 3406 3407To read an RTL object from a file, call @code{read_rtx}. It takes one 3408argument, a stdio stream, and returns a single RTL object. This routine 3409is defined in @file{read-rtl.c}. It is not available in the compiler 3410itself, only the various programs that generate the compiler back end 3411from the machine description. 3412 3413People frequently have the idea of using RTL stored as text in a file as 3414an interface between a language front end and the bulk of GCC@. This 3415idea is not feasible. 3416 3417GCC was designed to use RTL internally only. Correct RTL for a given 3418program is very dependent on the particular target machine. And the RTL 3419does not contain all the information about the program. 3420 3421The proper way to interface GCC to a new language front end is with 3422the ``tree'' data structure, described in the files @file{tree.h} and 3423@file{tree.def}. The documentation for this structure (@pxref{Trees}) 3424is incomplete. 3425