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