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