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