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