1 @c Copyright (C) 1988-2024 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
6 @chapter RTL Representation
7 @cindex RTL representation
8 @cindex representation of RTL
9 @cindex Register Transfer Language (RTL)
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.
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.
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.
48 @section RTL Object Types
49 @cindex RTL object types
54 @cindex RTL expression
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
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.
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.
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.
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.
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.
97 @cindex expression codes
98 @cindex codes, RTL expression
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})}.
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.
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).
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}.
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)}.
132 @section RTL Classes and Formats
134 @cindex classes of RTX codes
135 @cindex RTX codes, classes of
136 @findex GET_RTX_CLASS
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:
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
152 An RTX code that represents a constant object. @code{HIGH} is also
153 included in this class.
156 An RTX code for a non-symmetric comparison, such as @code{GEU} or
159 @item RTX_COMM_COMPARE
160 An RTX code for a symmetric (commutative) comparison, such as @code{EQ}
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.
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}.
174 An RTX code for a non-commutative binary operation, such as @code{MINUS},
175 @code{DIV}, or @code{ASHIFTRT}.
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).
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}.
189 An RTX code for an entire instruction: @code{INSN}, @code{JUMP_INSN}, and
190 @code{CALL_INSN}. @xref{Insns}.
193 An RTX code for something that matches in insns, such as
194 @code{MATCH_DUP}. These only occur in machine descriptions.
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
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.
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}.
216 @cindex RTL format characters
217 These are the most commonly used format characters:
221 An expression (actually a pointer to an expression).
233 A vector of expressions.
236 A few other format characters are used occasionally:
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.
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
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.
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.
261 @samp{B} indicates a pointer to basic block structure.
264 A polynomial integer. At present this is used only for @code{SUBREG_BYTE}.
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.
272 There are macros to get the number of operands and the format
273 of an expression code:
276 @findex GET_RTX_LENGTH
277 @item GET_RTX_LENGTH (@var{code})
278 Number of operands of an RTX of code @var{code}.
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.
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}.
290 All codes of this class have format @code{e}.
293 @itemx RTX_COMM_ARITH
294 @itemx RTX_COMM_COMPARE
296 All codes of these classes have format @code{ee}.
298 @item RTX_BITFIELD_OPS
300 All codes of these classes have format @code{eee}.
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}.
311 You can make no assumptions about the format of these codes.
315 @section Access to Operands
317 @cindex access to operands
318 @cindex operand access
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,
334 accesses operand 2 of expression @var{x}, as an expression.
341 accesses the same operand as an integer. @code{XSTR}, used in the same
342 fashion, would access it as a string.
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
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.
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
366 @item XVEC (@var{exp}, @var{idx})
367 Access the vector-pointer which is operand number @var{idx} in @var{exp}.
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}.
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@.
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})}.
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
387 @node Special Accessors
388 @section Access to Special Operands
389 @cindex access to special operands
391 Some RTL nodes have special annotations associated with them.
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}.
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.
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.
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.
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.
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.
438 @item MEM_ALIGN (@var{x})
439 The known alignment in bits of the memory reference.
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.
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
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.
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.
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.
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.
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.
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}.
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:
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.
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}.
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}.
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}.
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.
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.
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}.
542 If this flag is set, then @code{SYMBOL_FLAG_HAS_BLOCK_INFO} will be too.
545 Bits beginning with @code{SYMBOL_FLAG_MACH_DEP} are available for
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.
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.
564 @section Flags in an RTL Expression
565 @cindex flags in RTL expression
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.
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
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}.
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}.
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}.
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}.
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}.
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}.
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}.
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}.
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}.
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}.
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.
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.
701 Stored in the @code{unchanging} field and printed as @samp{/u}.
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}.
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
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}.
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
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
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
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
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.
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.
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}.
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}.
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.
802 This flag is required for exception handling support on targets with RTL
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}.
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}.
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}.
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}.
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.
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.
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}.
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.
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}.
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}.
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.
906 These are the fields to which the above macros refer:
910 @cindex @samp{/c} in RTL dump
912 In a @code{mem}, 1 means that the memory reference will not trap.
914 In a @code{call}, 1 means that this pure or const call may possibly
917 In an RTL dump, this flag is represented as @samp{/c}.
919 @findex frame_related
920 @cindex @samp{/f} in RTL dump
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
927 In @code{reg} expressions, 1 means that the register holds a pointer.
929 In @code{mem} expressions, 1 means that the memory reference holds a pointer.
931 In @code{symbol_ref} expressions, 1 means that the reference addresses
932 this function's string constant pool.
934 In an RTL dump, this flag is represented as @samp{/f}.
937 @cindex @samp{/s} in RTL dump
939 In @code{reg} expressions, it is 1 if the register has its entire life
940 contained within the test expression of some loop.
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.
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}
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}.
954 In an @code{insn} during dead-code elimination, 1 means that the insn is
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.
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.
964 In an RTL dump, this flag is represented as @samp{/s}.
967 @cindex @samp{/i} in RTL dump
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
975 In @code{symbol_ref} expressions, 1 means the referenced symbol is weak.
977 In @code{call} expressions, 1 means the call is pure.
979 In an RTL dump, this flag is represented as @samp{/i}.
982 @cindex @samp{/j} in RTL dump
984 In a @code{mem} expression, 1 means we should keep the alias set for this
985 mem unchanged when we access a component.
987 In a @code{set}, 1 means it is for a return.
989 In a @code{call_insn}, 1 means it is a sibling call.
991 In a @code{jump_insn}, 1 means it is a crossing jump.
993 In an RTL dump, this flag is represented as @samp{/j}.
996 @cindex @samp{/u} in RTL dump
998 In @code{reg} and @code{mem} expressions, 1 means
999 that the value of the expression never changes.
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.
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.
1007 In a @code{symbol_ref} expression, 1 means that this symbol addresses
1008 something in the per-function constant pool.
1010 In a @code{call_insn} 1 means that this instruction is a call to a const
1013 In an RTL dump, this flag is represented as @samp{/u}.
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}).
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
1026 In a @code{symbol_ref}, it indicates that an external declaration for
1027 the symbol has already been written.
1030 @cindex @samp{/v} in RTL dump
1031 @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.
1038 In a @code{symbol_ref} expression, it is used for machine-specific
1041 In a @code{reg} expression, it is 1 if the value is a user-level variable.
1042 0 indicates an internal compiler temporary.
1044 In an @code{insn}, 1 means the insn has been deleted.
1046 In @code{label_ref} and @code{reg_label} expressions, 1 means a reference
1047 to a non-local label.
1049 In @code{prefetch} expressions, 1 means that the containing insn is a
1052 In an RTL dump, this flag is represented as @samp{/v}.
1056 @section Machine Modes
1057 @cindex machine modes
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).
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.
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}).
1079 ``Bit'' mode represents a single bit, for predicate registers.
1083 ``Quarter-Integer'' mode represents a single byte treated as an integer.
1087 ``Half-Integer'' mode represents a two-byte integer.
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.
1097 ``Single Integer'' mode represents a four-byte integer.
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.
1107 ``Double Integer'' mode represents an eight-byte integer.
1111 ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
1115 ``Octa Integer'' (?) mode represents a thirty-two-byte integer.
1119 ``Hexadeca Integer'' (?) mode represents a sixty-four-byte integer.
1123 ``Quarter-Floating'' mode represents a quarter-precision (single byte)
1124 floating point number.
1128 ``Half-Floating'' mode represents a half-precision (two byte) floating
1133 ``Three-Quarter-Floating'' (?) mode represents a three-quarter-precision
1134 (three byte) floating point number.
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.
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.
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.
1159 ``Single Decimal Floating'' mode represents a four byte decimal
1160 floating point number (as distinct from conventional binary floating
1165 ``Double Decimal Floating'' mode represents an eight byte decimal
1166 floating point number.
1170 ``Tetra Decimal Floating'' mode represents a sixteen byte decimal
1171 floating point number all 128 of whose bits are meaningful.
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.
1181 ``Quarter-Fractional'' mode represents a single byte treated as a signed
1182 fractional number. The default format is ``s.7''.
1186 ``Half-Fractional'' mode represents a two-byte signed fractional number.
1187 The default format is ``s.15''.
1191 ``Single Fractional'' mode represents a four-byte signed fractional number.
1192 The default format is ``s.31''.
1196 ``Double Fractional'' mode represents an eight-byte signed fractional number.
1197 The default format is ``s.63''.
1201 ``Tetra Fractional'' mode represents a sixteen-byte signed fractional number.
1202 The default format is ``s.127''.
1206 ``Unsigned Quarter-Fractional'' mode represents a single byte treated as an
1207 unsigned fractional number. The default format is ``.8''.
1211 ``Unsigned Half-Fractional'' mode represents a two-byte unsigned fractional
1212 number. The default format is ``.16''.
1216 ``Unsigned Single Fractional'' mode represents a four-byte unsigned fractional
1217 number. The default format is ``.32''.
1221 ``Unsigned Double Fractional'' mode represents an eight-byte unsigned
1222 fractional number. The default format is ``.64''.
1226 ``Unsigned Tetra Fractional'' mode represents a sixteen-byte unsigned
1227 fractional number. The default format is ``.128''.
1231 ``Half-Accumulator'' mode represents a two-byte signed accumulator.
1232 The default format is ``s8.7''.
1236 ``Single Accumulator'' mode represents a four-byte signed accumulator.
1237 The default format is ``s16.15''.
1241 ``Double Accumulator'' mode represents an eight-byte signed accumulator.
1242 The default format is ``s32.31''.
1246 ``Tetra Accumulator'' mode represents a sixteen-byte signed accumulator.
1247 The default format is ``s64.63''.
1251 ``Unsigned Half-Accumulator'' mode represents a two-byte unsigned accumulator.
1252 The default format is ``8.8''.
1256 ``Unsigned Single Accumulator'' mode represents a four-byte unsigned
1257 accumulator. The default format is ``16.16''.
1261 ``Unsigned Double Accumulator'' mode represents an eight-byte unsigned
1262 accumulator. The default format is ``32.32''.
1266 ``Unsigned Tetra Accumulator'' mode represents a sixteen-byte unsigned
1267 accumulator. The default format is ``64.64''.
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}).
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@.
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.
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.
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},
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.
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.
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}.
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
1346 Integer modes. By default these are @code{BImode}, @code{QImode},
1347 @code{HImode}, @code{SImode}, @code{DImode}, @code{TImode}, and
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}.
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}.
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}.
1368 Signed fractional modes. By default these are @code{QQmode}, @code{HQmode},
1369 @code{SQmode}, @code{DQmode} and @code{TQmode}.
1373 Unsigned fractional modes. By default these are @code{UQQmode}, @code{UHQmode},
1374 @code{USQmode}, @code{UDQmode} and @code{UTQmode}.
1378 Signed accumulator modes. By default these are @code{HAmode},
1379 @code{SAmode}, @code{DAmode} and @code{TAmode}.
1383 Unsigned accumulator modes. By default these are @code{UHAmode},
1384 @code{USAmode}, @code{UDAmode} and @code{UTAmode}.
1386 @findex MODE_COMPLEX_INT
1387 @item MODE_COMPLEX_INT
1388 Complex integer modes. (These are not currently implemented).
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
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}.
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.
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.
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
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:
1428 @findex scalar_int_mode
1429 @item scalar_int_mode
1430 A mode that has class @code{MODE_INT} or @code{MODE_PARTIAL_INT}.
1432 @findex scalar_float_mode
1433 @item scalar_float_mode
1434 A mode that has class @code{MODE_FLOAT} or @code{MODE_DECIMAL_FLOAT}.
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}.
1443 @findex complex_mode
1445 A mode that has class @code{MODE_COMPLEX_INT} or @code{MODE_COMPLEX_FLOAT}.
1447 @findex fixed_size_mode
1448 @item fixed_size_mode
1449 A mode whose size is known at compile time.
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.
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
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:
1476 @item @var{x}.exists ()
1477 Return true if @var{x} holds a mode rather than nothing.
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}.
1483 @item @var{x}.require ()
1484 Assert that @var{x} holds a mode rather than nothing and return that mode.
1486 @item @var{x} = @var{y}
1487 Set @var{x} to @var{y}, where @var{y} is a @var{T} or implicitly converts
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}.
1494 It is possible to use the @file{is-a.h} accessors on a @code{machine_mode}
1495 or machine mode wrapper @var{x}:
1499 @item is_a <@var{T}> (@var{x})
1500 Return true if @var{x} meets the conditions for wrapper class @var{T}.
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
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}.
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.
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.
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}.
1529 Here are some C macros that relate to machine modes:
1533 @item GET_MODE (@var{x})
1534 Returns the machine mode of the RTX @var{x}.
1537 @item PUT_MODE (@var{x}, @var{newmode})
1538 Alters the machine mode of the RTX @var{x} to be @var{newmode}.
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
1546 @findex GET_MODE_NAME
1547 @item GET_MODE_NAME (@var{m})
1548 Returns the name of mode @var{m} as a string.
1550 @findex GET_MODE_CLASS
1551 @item GET_MODE_CLASS (@var{m})
1552 Returns the mode class of mode @var{m}.
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}.
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}.
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}.
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}.
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}.
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}.
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}.
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
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}.
1597 @findex GET_CLASS_NARROWEST_MODE
1598 @item GET_CLASS_NARROWEST_MODE (@var{c})
1599 Returns the narrowest mode in mode class @var{c}.
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.
1610 @findex 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.
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.
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}.
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.
1640 @section Constant Expression Types
1641 @cindex RTL constants
1642 @cindex RTL constant expression types
1644 The simplest RTL expressions are those that represent constant values.
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)}.
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.
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.
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.
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.
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.
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}.
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}).
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
1721 (const_double_zero:@var{m})
1727 (const_double:@var{m} 0 0 @dots{})
1730 for matching the floating-point value zero, possibly the only useful one.
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
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.
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.
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.
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.
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}.
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.
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}
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:
1793 @{ @var{base0}, @var{base1}, @var{base1} + @var{step}, @var{base1} + @var{step} * 2, @dots{} @}
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})}.
1803 For example, the constant:
1806 @{ 0, 1, 2, 6, 3, 8, 4, 10, 5, 12, 6, 14, 7, 16, 8, 18 @}
1809 is interpreted as an interleaving of the sequences:
1812 @{ 0, 2, 3, 4, 5, 6, 7, 8 @}
1813 @{ 1, 6, 8, 10, 12, 14, 16, 18 @}
1816 where the sequences are represented by the following patterns:
1819 @var{base0} == 0, @var{base1} == 2, @var{step} == 1
1820 @var{base0} == 1, @var{base1} == 6, @var{step} == 2
1826 CONST_VECTOR_NPATTERNS (@var{v}) == 2
1827 CONST_VECTOR_NELTS_PER_PATTERN (@var{v}) == 3
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.
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.
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}.
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}.
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}.
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})}.
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}.
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.
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
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.
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.
1893 The reason for using a distinct expression type for code label
1894 references is so that jump optimization can distinguish them.
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.
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.
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}.
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
1934 @node Regs and Memory
1935 @section Registers and Memory
1936 @cindex RTL register expressions
1937 @cindex RTL memory expressions
1939 Here are the RTL expression types for describing access to machine
1940 registers and to main memory.
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.
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
1962 Even for a register that the machine can access in only one mode,
1963 the mode must always be specified.
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.
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}
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.
1985 Each pseudo register number used in a function's RTL code is
1986 represented by a unique @code{reg} expression.
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:
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
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}.
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.
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}.
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
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}.
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}).
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}.
2047 @item (subreg:@var{m1} @var{reg:m2} @var{bytenum})
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.
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}.
2057 There are currently three supported types for the first operand of a
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.
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.
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.
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.
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.
2094 @code{subreg}s come in two distinct flavors, each having its own
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:
2104 paradoxical_subreg_p (@var{m1}, @var{m2})
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
2114 The high-order bits of rvalues are defined in the following circumstances:
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.
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.
2129 @var{bytenum} is always zero for a paradoxical @code{subreg}, even on
2132 For example, the paradoxical @code{subreg}:
2135 (set (subreg:SI (reg:HI @var{x}) 0) @var{y})
2138 stores the lower 2 bytes of @var{y} in @var{x} and discards the upper
2139 2 bytes. A subsequent:
2142 (set @var{z} (subreg:SI (reg:HI @var{x}) 0))
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
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}.
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:
2159 REGMODE_NATURAL_SIZE (@var{m2})
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.
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.
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}
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}.
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}:
2190 @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
2196 @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.
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}.
2214 (subreg:HI (reg:SI @var{x}) 2)
2217 on a @code{BYTES_BIG_ENDIAN}, @samp{UNITS_PER_WORD == 4} target is the same as
2220 (subreg:HI (reg:SI @var{x}) 0)
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}.
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.
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
2240 For example, on a little-endian target which defines @code{PSImode}
2241 to have a precision of 20 bits:
2244 (subreg:PSI (reg:SI 0) 0)
2247 accesses the low 20 bits of @samp{(reg:SI 0)}.
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:
2255 (subreg:PSI (reg:DI 0) 0)
2256 (subreg:PSI (reg:DI 0) 4)
2259 represent accesses to the low 20 bits of the two halves of
2262 If @samp{REGMODE_NATURAL_SIZE (PSImode) <= 2} then these two @code{subreg}s:
2265 (subreg:HI (reg:PSI 0) 0)
2266 (subreg:HI (reg:PSI 0) 2)
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:
2274 (set (subreg:HI (reg:PSI 0) 0) (reg:HI 4))
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.
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:
2290 TARGET_CAN_CHANGE_MODE_CLASS (@var{m2}, @var{m1}, @var{class})
2293 must be false for every class @var{class} that includes @var{reg}.
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.
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.
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.
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
2323 @code{scratch} is usually present inside a @code{clobber} operation
2324 (@pxref{Side Effects}).
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.
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}.
2339 @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.
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}.
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@.
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.
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.
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.
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.
2380 @section RTL Expressions for Arithmetic
2381 @cindex arithmetic, in RTL
2382 @cindex math, in RTL
2383 @cindex RTL expressions for arithmetic
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}.
2390 For commutative binary operations, constants should be placed in the
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})
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.
2412 @c ??? What happens on overflow of floating point modes?
2415 @item (lo_sum:@var{m} @var{x} @var{y})
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}.
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}.
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})
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).
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
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}.
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
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
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.
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
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.
2502 @cindex multiplication
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.
2514 Some machines support a multiplication that generates a product wider
2515 than the operands. Write the pattern for this as
2518 (mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
2521 where @var{m} is wider than the modes of @var{x} and @var{y}, which need
2524 For unsigned widening multiplication, use the same idiom, but with
2525 @code{zero_extend} instead of @code{sign_extend}.
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.
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.
2548 @cindex signed division
2549 @cindex signed division with signed saturation
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
2557 @code{ss_div} ensures that an out-of-bounds result saturates to the maximum
2558 or minimum signed value.
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,
2565 (truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
2569 @cindex unsigned division
2570 @cindex unsigned division with unsigned saturation
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.
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
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.
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
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.
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.
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
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
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.
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}.
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.
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,
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.
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.
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}
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}.
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}.
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}.
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}.
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
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}.
2747 @item (bitreverse:@var{m} @var{x})
2748 Represents the value @var{x} with the order of bits reversed, carried out
2749 in mode @var{m}, which must be a fixed-point machine mode.
2750 The mode of @var{x} must be @var{m} or @code{VOIDmode}.
2753 @item (copysign:@var{m} @var{x} @var{y})
2754 Represents the value @var{x} with the sign of @var{y}.
2755 Both @var{x} and @var{y} must have floating point machine mode @var{m}.
2759 @section Comparison Operations
2760 @cindex RTL comparison operations
2762 Comparison operators test a relation on two operands and are considered
2763 to represent a machine-dependent nonzero value described by, but not
2764 necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
2765 if the relation holds, or zero if it does not, for comparison operators
2766 whose results have a `MODE_INT' mode,
2767 @code{FLOAT_STORE_FLAG_VALUE} (@pxref{Misc}) if the relation holds, or
2768 zero if it does not, for comparison operators that return floating-point
2769 values, and a vector of either @code{VECTOR_STORE_FLAG_VALUE} (@pxref{Misc})
2770 if the relation holds, or of zeros if it does not, for comparison operators
2771 that return vector results.
2772 The mode of the comparison operation is independent of the mode
2773 of the data being compared. If the comparison operation is being tested
2774 (e.g., the first operand of an @code{if_then_else}), the mode must be
2777 @cindex condition codes
2778 A comparison operation compares two data
2779 objects. The mode of the comparison is determined by the operands; they
2780 must both be valid for a common machine mode. A comparison with both
2781 operands constant would be invalid as the machine mode could not be
2782 deduced from it, but such a comparison should never exist in RTL due to
2785 Usually only one style
2786 of comparisons is supported on a particular machine, but the combine
2787 pass will try to merge operations to produce code like
2788 @code{(eq @var{x} @var{y})},
2789 in case it exists in the context of the particular insn involved.
2791 Inequality comparisons come in two flavors, signed and unsigned. Thus,
2792 there are distinct expression codes @code{gt} and @code{gtu} for signed and
2793 unsigned greater-than. These can produce different results for the same
2794 pair of integer values: for example, 1 is signed greater-than @minus{}1 but not
2795 unsigned greater-than, because @minus{}1 when regarded as unsigned is actually
2796 @code{0xffffffff} which is greater than 1.
2798 The signed comparisons are also used for floating point values. Floating
2799 point comparisons are distinguished by the machine modes of the operands.
2804 @item (eq:@var{m} @var{x} @var{y})
2805 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2806 are equal, otherwise 0.
2810 @item (ne:@var{m} @var{x} @var{y})
2811 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2812 are not equal, otherwise 0.
2815 @cindex greater than
2816 @item (gt:@var{m} @var{x} @var{y})
2817 @code{STORE_FLAG_VALUE} if the @var{x} is greater than @var{y}. If they
2818 are fixed-point, the comparison is done in a signed sense.
2821 @cindex greater than
2822 @cindex unsigned greater than
2823 @item (gtu:@var{m} @var{x} @var{y})
2824 Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
2829 @cindex unsigned less than
2830 @item (lt:@var{m} @var{x} @var{y})
2831 @itemx (ltu:@var{m} @var{x} @var{y})
2832 Like @code{gt} and @code{gtu} but test for ``less than''.
2835 @cindex greater than
2837 @cindex unsigned greater than
2838 @item (ge:@var{m} @var{x} @var{y})
2839 @itemx (geu:@var{m} @var{x} @var{y})
2840 Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
2843 @cindex less than or equal
2845 @cindex unsigned less than
2846 @item (le:@var{m} @var{x} @var{y})
2847 @itemx (leu:@var{m} @var{x} @var{y})
2848 Like @code{gt} and @code{gtu} but test for ``less than or equal''.
2850 @findex if_then_else
2851 @item (if_then_else @var{cond} @var{then} @var{else})
2852 This is not a comparison operation but is listed here because it is
2853 always used in conjunction with a comparison operation. To be
2854 precise, @var{cond} is a comparison expression. This expression
2855 represents a choice, according to @var{cond}, between the value
2856 represented by @var{then} and the one represented by @var{else}.
2858 On most machines, @code{if_then_else} expressions are valid only
2859 to express conditional jumps.
2862 @item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
2863 Similar to @code{if_then_else}, but more general. Each of @var{test1},
2864 @var{test2}, @dots{} is performed in turn. The result of this expression is
2865 the @var{value} corresponding to the first nonzero test, or @var{default} if
2866 none of the tests are nonzero expressions.
2868 This is currently not valid for instruction patterns and is supported only
2869 for insn attributes. @xref{Insn Attributes}.
2876 Special expression codes exist to represent bit-field instructions.
2879 @findex sign_extract
2880 @cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
2881 @item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
2882 This represents a reference to a sign-extended bit-field contained or
2883 starting in @var{loc} (a memory or register reference). The bit-field
2884 is @var{size} bits wide and starts at bit @var{pos}. The compilation
2885 option @code{BITS_BIG_ENDIAN} says which end of the memory unit
2886 @var{pos} counts from.
2888 If @var{loc} is in memory, its mode must be a single-byte integer mode.
2889 If @var{loc} is in a register, the mode to use is specified by the
2890 operand of the @code{insv} or @code{extv} pattern
2891 (@pxref{Standard Names}) and is usually a full-word integer mode,
2892 which is the default if none is specified.
2894 The mode of @var{pos} is machine-specific and is also specified
2895 in the @code{insv} or @code{extv} pattern.
2897 The mode @var{m} is the same as the mode that would be used for
2898 @var{loc} if it were a register.
2900 A @code{sign_extract} cannot appear as an lvalue, or part thereof,
2903 @findex zero_extract
2904 @item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
2905 Like @code{sign_extract} but refers to an unsigned or zero-extended
2906 bit-field. The same sequence of bits are extracted, but they
2907 are filled to an entire word with zeros instead of by sign-extension.
2909 Unlike @code{sign_extract}, this type of expressions can be lvalues
2910 in RTL; they may appear on the left side of an assignment, indicating
2911 insertion of a value into the specified bit-field.
2914 @node Vector Operations
2915 @section Vector Operations
2916 @cindex vector operations
2918 All normal RTL expressions can be used with vector modes; they are
2919 interpreted as operating on each part of the vector independently.
2920 Additionally, there are a few new expressions to describe specific vector
2925 @item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items})
2926 This describes a merge operation between two vectors. The result is a vector
2927 of mode @var{m}; its elements are selected from either @var{vec1} or
2928 @var{vec2}. Which elements are selected is described by @var{items}, which
2929 is a bit mask represented by a @code{const_int}; a zero bit indicates the
2930 corresponding element in the result vector is taken from @var{vec2} while
2931 a set bit indicates it is taken from @var{vec1}.
2934 @item (vec_select:@var{m} @var{vec1} @var{selection})
2935 This describes an operation that selects parts of a vector. @var{vec1} is
2936 the source vector, and @var{selection} is a @code{parallel} that contains a
2937 @code{const_int} (or another expression, if the selection can be made at
2938 runtime) for each of the subparts of the result vector, giving the number of
2939 the source subpart that should be stored into it. The result mode @var{m} is
2940 either the submode for a single element of @var{vec1} (if only one subpart is
2941 selected), or another vector mode with that element submode (if multiple
2942 subparts are selected).
2945 @item (vec_concat:@var{m} @var{x1} @var{x2})
2946 Describes a vector concat operation. The result is a concatenation of the
2947 vectors or scalars @var{x1} and @var{x2}; its length is the sum of the
2948 lengths of the two inputs.
2950 @findex vec_duplicate
2951 @item (vec_duplicate:@var{m} @var{x})
2952 This operation converts a scalar into a vector or a small vector into a
2953 larger one by duplicating the input values. The output vector mode must have
2954 the same submodes as the input vector mode or the scalar modes, and the
2955 number of output parts must be an integer multiple of the number of input
2959 @item (vec_series:@var{m} @var{base} @var{step})
2960 This operation creates a vector in which element @var{i} is equal to
2961 @samp{@var{base} + @var{i}*@var{step}}. @var{m} must be a vector integer mode.
2965 @section Conversions
2967 @cindex machine mode conversions
2969 All conversions between machine modes must be represented by
2970 explicit conversion operations. For example, an expression
2971 which is the sum of a byte and a full word cannot be written as
2972 @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
2973 operation requires two operands of the same machine mode.
2974 Therefore, the byte-sized operand is enclosed in a conversion
2978 (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
2981 The conversion operation is not a mere placeholder, because there
2982 may be more than one way of converting from a given starting mode
2983 to the desired final mode. The conversion operation code says how
2986 For all conversion operations, @var{x} must not be @code{VOIDmode}
2987 because the mode in which to do the conversion would not be known.
2988 The conversion must either be done at compile-time or @var{x}
2989 must be placed into a register.
2993 @item (sign_extend:@var{m} @var{x})
2994 Represents the result of sign-extending the value @var{x}
2995 to machine mode @var{m}. @var{m} must be a fixed-point mode
2996 and @var{x} a fixed-point value of a mode narrower than @var{m}.
2999 @item (zero_extend:@var{m} @var{x})
3000 Represents the result of zero-extending the value @var{x}
3001 to machine mode @var{m}. @var{m} must be a fixed-point mode
3002 and @var{x} a fixed-point value of a mode narrower than @var{m}.
3004 @findex float_extend
3005 @item (float_extend:@var{m} @var{x})
3006 Represents the result of extending the value @var{x}
3007 to machine mode @var{m}. @var{m} must be a floating point mode
3008 and @var{x} a floating point value of a mode narrower than @var{m}.
3011 @item (truncate:@var{m} @var{x})
3012 Represents the result of truncating the value @var{x}
3013 to machine mode @var{m}. @var{m} must be a fixed-point mode
3014 and @var{x} a fixed-point value of a mode wider than @var{m}.
3017 @item (ss_truncate:@var{m} @var{x})
3018 Represents the result of truncating the value @var{x}
3019 to machine mode @var{m}, using signed saturation in the case of
3020 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
3024 @item (us_truncate:@var{m} @var{x})
3025 Represents the result of truncating the value @var{x}
3026 to machine mode @var{m}, using unsigned saturation in the case of
3027 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
3030 @findex float_truncate
3031 @item (float_truncate:@var{m} @var{x})
3032 Represents the result of truncating the value @var{x}
3033 to machine mode @var{m}. @var{m} must be a floating point mode
3034 and @var{x} a floating point value of a mode wider than @var{m}.
3037 @item (float:@var{m} @var{x})
3038 Represents the result of converting fixed point value @var{x},
3039 regarded as signed, to floating point mode @var{m}.
3041 @findex unsigned_float
3042 @item (unsigned_float:@var{m} @var{x})
3043 Represents the result of converting fixed point value @var{x},
3044 regarded as unsigned, to floating point mode @var{m}.
3047 @item (fix:@var{m} @var{x})
3048 When @var{m} is a floating-point mode, represents the result of
3049 converting floating point value @var{x} (valid for mode @var{m}) to an
3050 integer, still represented in floating point mode @var{m}, by rounding
3053 When @var{m} is a fixed-point mode, represents the result of
3054 converting floating point value @var{x} to mode @var{m}, regarded as
3055 signed. How rounding is done is not specified, so this operation may
3056 be used validly in compiling C code only for integer-valued operands.
3058 @findex unsigned_fix
3059 @item (unsigned_fix:@var{m} @var{x})
3060 Represents the result of converting floating point value @var{x} to
3061 fixed point mode @var{m}, regarded as unsigned. How rounding is done
3064 @findex fract_convert
3065 @item (fract_convert:@var{m} @var{x})
3066 Represents the result of converting fixed-point value @var{x} to
3067 fixed-point mode @var{m}, signed integer value @var{x} to
3068 fixed-point mode @var{m}, floating-point value @var{x} to
3069 fixed-point mode @var{m}, fixed-point value @var{x} to integer mode @var{m}
3070 regarded as signed, or fixed-point value @var{x} to floating-point mode @var{m}.
3071 When overflows or underflows happen, the results are undefined.
3074 @item (sat_fract:@var{m} @var{x})
3075 Represents the result of converting fixed-point value @var{x} to
3076 fixed-point mode @var{m}, signed integer value @var{x} to
3077 fixed-point mode @var{m}, or floating-point value @var{x} to
3078 fixed-point mode @var{m}.
3079 When overflows or underflows happen, the results are saturated to the
3080 maximum or the minimum.
3082 @findex unsigned_fract_convert
3083 @item (unsigned_fract_convert:@var{m} @var{x})
3084 Represents the result of converting fixed-point value @var{x} to
3085 integer mode @var{m} regarded as unsigned, or unsigned integer value @var{x} to
3086 fixed-point mode @var{m}.
3087 When overflows or underflows happen, the results are undefined.
3089 @findex unsigned_sat_fract
3090 @item (unsigned_sat_fract:@var{m} @var{x})
3091 Represents the result of converting unsigned integer value @var{x} to
3092 fixed-point mode @var{m}.
3093 When overflows or underflows happen, the results are saturated to the
3094 maximum or the minimum.
3097 @node RTL Declarations
3098 @section Declarations
3099 @cindex RTL declarations
3100 @cindex declarations, RTL
3102 Declaration expression codes do not represent arithmetic operations
3103 but rather state assertions about their operands.
3106 @findex strict_low_part
3107 @cindex @code{subreg}, in @code{strict_low_part}
3108 @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
3109 This expression code is used in only one context: as the destination operand of a
3110 @code{set} expression. In addition, the operand of this expression
3111 must be a non-paradoxical @code{subreg} expression.
3113 The presence of @code{strict_low_part} says that the part of the
3114 register which is meaningful in mode @var{n}, but is not part of
3115 mode @var{m}, is not to be altered. Normally, an assignment to such
3116 a subreg is allowed to have undefined effects on the rest of the
3117 register when @var{m} is smaller than @samp{REGMODE_NATURAL_SIZE (@var{n})}.
3121 @section Side Effect Expressions
3122 @cindex RTL side effect expressions
3124 The expression codes described so far represent values, not actions.
3125 But machine instructions never produce values; they are meaningful
3126 only for their side effects on the state of the machine. Special
3127 expression codes are used to represent side effects.
3129 The body of an instruction is always one of these side effect codes;
3130 the codes described above, which represent values, appear only as
3131 the operands of these.
3135 @item (set @var{lval} @var{x})
3136 Represents the action of storing the value of @var{x} into the place
3137 represented by @var{lval}. @var{lval} must be an expression
3138 representing a place that can be stored in: @code{reg} (or @code{subreg},
3139 @code{strict_low_part} or @code{zero_extract}), @code{mem}, @code{pc},
3142 If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
3143 machine mode; then @var{x} must be valid for that mode.
3145 If @var{lval} is a @code{reg} whose machine mode is less than the full
3146 width of the register, then it means that the part of the register
3147 specified by the machine mode is given the specified value and the
3148 rest of the register receives an undefined value. Likewise, if
3149 @var{lval} is a @code{subreg} whose machine mode is narrower than
3150 the mode of the register, the rest of the register can be changed in
3153 If @var{lval} is a @code{strict_low_part} of a subreg, then the part
3154 of the register specified by the machine mode of the @code{subreg} is
3155 given the value @var{x} and the rest of the register is not changed.
3157 If @var{lval} is a @code{zero_extract}, then the referenced part of
3158 the bit-field (a memory or register reference) specified by the
3159 @code{zero_extract} is given the value @var{x} and the rest of the
3160 bit-field is not changed. Note that @code{sign_extract} cannot
3161 appear in @var{lval}.
3163 If @var{lval} is a @code{parallel}, it is used to represent the case of
3164 a function returning a structure in multiple registers. Each element
3165 of the @code{parallel} is an @code{expr_list} whose first operand is a
3166 @code{reg} and whose second operand is a @code{const_int} representing the
3167 offset (in bytes) into the structure at which the data in that register
3168 corresponds. The first element may be null to indicate that the structure
3169 is also passed partly in memory.
3171 @cindex jump instructions and @code{set}
3172 @cindex @code{if_then_else} usage
3173 If @var{lval} is @code{(pc)}, we have a jump instruction, and the
3174 possibilities for @var{x} are very limited. It may be a
3175 @code{label_ref} expression (unconditional jump). It may be an
3176 @code{if_then_else} (conditional jump), in which case either the
3177 second or the third operand must be @code{(pc)} (for the case which
3178 does not jump) and the other of the two must be a @code{label_ref}
3179 (for the case which does jump). @var{x} may also be a @code{mem} or
3180 @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
3181 @code{mem}; these unusual patterns are used to represent jumps through
3184 If @var{lval} is not @code{(pc)}, the mode of
3185 @var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
3186 valid for the mode of @var{lval}.
3190 @var{lval} is customarily accessed with the @code{SET_DEST} macro and
3191 @var{x} with the @code{SET_SRC} macro.
3195 As the sole expression in a pattern, represents a return from the
3196 current function, on machines where this can be done with one
3197 instruction, such as VAXen. On machines where a multi-instruction
3198 ``epilogue'' must be executed in order to return from the function,
3199 returning is done by jumping to a label which precedes the epilogue, and
3200 the @code{return} expression code is never used.
3202 Inside an @code{if_then_else} expression, represents the value to be
3203 placed in @code{pc} to return to the caller.
3205 Note that an insn pattern of @code{(return)} is logically equivalent to
3206 @code{(set (pc) (return))}, but the latter form is never used.
3208 @findex simple_return
3209 @item (simple_return)
3210 Like @code{(return)}, but truly represents only a function return, while
3211 @code{(return)} may represent an insn that also performs other functions
3212 of the function epilogue. Like @code{(return)}, this may also occur in
3216 @item (call @var{function} @var{nargs})
3217 Represents a function call. @var{function} is a @code{mem} expression
3218 whose address is the address of the function to be called.
3219 @var{nargs} is an expression which can be used for two purposes: on
3220 some machines it represents the number of bytes of stack argument; on
3221 others, it represents the number of argument registers.
3223 Each machine has a standard machine mode which @var{function} must
3224 have. The machine description defines macro @code{FUNCTION_MODE} to
3225 expand into the requisite mode name. The purpose of this mode is to
3226 specify what kind of addressing is allowed, on machines where the
3227 allowed kinds of addressing depend on the machine mode being
3231 @item (clobber @var{x})
3232 Represents the storing or possible storing of an unpredictable,
3233 undescribed value into @var{x}, which must be a @code{reg},
3234 @code{scratch}, @code{parallel} or @code{mem} expression.
3236 One place this is used is in string instructions that store standard
3237 values into particular hard registers. It may not be worth the
3238 trouble to describe the values that are stored, but it is essential to
3239 inform the compiler that the registers will be altered, lest it
3240 attempt to keep data in them across the string instruction.
3242 If @var{x} is @code{(mem:BLK (const_int 0))} or
3243 @code{(mem:BLK (scratch))}, it means that all memory
3244 locations must be presumed clobbered. If @var{x} is a @code{parallel},
3245 it has the same meaning as a @code{parallel} in a @code{set} expression.
3247 Note that the machine description classifies certain hard registers as
3248 ``call-clobbered''. All function call instructions are assumed by
3249 default to clobber these registers, so there is no need to use
3250 @code{clobber} expressions to indicate this fact. Also, each function
3251 call is assumed to have the potential to alter any memory location,
3252 unless the function is declared @code{const}.
3254 If the last group of expressions in a @code{parallel} are each a
3255 @code{clobber} expression whose arguments are @code{reg} or
3256 @code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
3257 phase can add the appropriate @code{clobber} expressions to an insn it
3258 has constructed when doing so will cause a pattern to be matched.
3260 This feature can be used, for example, on a machine that whose multiply
3261 and add instructions don't use an MQ register but which has an
3262 add-accumulate instruction that does clobber the MQ register. Similarly,
3263 a combined instruction might require a temporary register while the
3264 constituent instructions might not.
3266 When a @code{clobber} expression for a register appears inside a
3267 @code{parallel} with other side effects, the register allocator
3268 guarantees that the register is unoccupied both before and after that
3269 insn if it is a hard register clobber. For pseudo-register clobber,
3270 the register allocator and the reload pass do not assign the same hard
3271 register to the clobber and the input operands if there is an insn
3272 alternative containing the @samp{&} constraint (@pxref{Modifiers}) for
3273 the clobber and the hard register is in register classes of the
3274 clobber in the alternative. You can clobber either a specific hard
3275 register, a pseudo register, or a @code{scratch} expression; in the
3276 latter two cases, GCC will allocate a hard register that is available
3277 there for use as a temporary.
3279 For instructions that require a temporary register, you should use
3280 @code{scratch} instead of a pseudo-register because this will allow the
3281 combiner phase to add the @code{clobber} when required. You do this by
3282 coding (@code{clobber} (@code{match_scratch} @dots{})). If you do
3283 clobber a pseudo register, use one which appears nowhere else---generate
3284 a new one each time. Otherwise, you may confuse CSE@.
3286 There is one other known use for clobbering a pseudo register in a
3287 @code{parallel}: when one of the input operands of the insn is also
3288 clobbered by the insn. In this case, using the same pseudo register in
3289 the clobber and elsewhere in the insn produces the expected results.
3293 Represents the use of the value of @var{x}. It indicates that the
3294 value in @var{x} at this point in the program is needed, even though
3295 it may not be apparent why this is so. Therefore, the compiler will
3296 not attempt to delete previous instructions whose only effect is to
3297 store a value in @var{x}. @var{x} must be a @code{reg} expression.
3299 In some situations, it may be tempting to add a @code{use} of a
3300 register in a @code{parallel} to describe a situation where the value
3301 of a special register will modify the behavior of the instruction.
3302 A hypothetical example might be a pattern for an addition that can
3303 either wrap around or use saturating addition depending on the value
3304 of a special control register:
3307 (parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
3314 This will not work, several of the optimizers only look at expressions
3315 locally; it is very likely that if you have multiple insns with
3316 identical inputs to the @code{unspec}, they will be optimized away even
3317 if register 1 changes in between.
3319 This means that @code{use} can @emph{only} be used to describe
3320 that the register is live. You should think twice before adding
3321 @code{use} statements, more often you will want to use @code{unspec}
3322 instead. The @code{use} RTX is most commonly useful to describe that
3323 a fixed register is implicitly used in an insn. It is also safe to use
3324 in patterns where the compiler knows for other reasons that the result
3325 of the whole pattern is variable, such as @samp{cpymem@var{m}} or
3326 @samp{call} patterns.
3328 During the reload phase, an insn that has a @code{use} as pattern
3329 can carry a reg_equal note. These @code{use} insns will be deleted
3330 before the reload phase exits.
3332 During the delayed branch scheduling phase, @var{x} may be an insn.
3333 This indicates that @var{x} previously was located at this place in the
3334 code and its data dependencies need to be taken into account. These
3335 @code{use} insns will be deleted before the delayed branch scheduling
3339 @item (parallel [@var{x0} @var{x1} @dots{}])
3340 Represents several side effects performed in parallel. The square
3341 brackets stand for a vector; the operand of @code{parallel} is a
3342 vector of expressions. @var{x0}, @var{x1} and so on are individual
3343 side effect expressions---expressions of code @code{set}, @code{call},
3344 @code{return}, @code{simple_return}, @code{clobber} or @code{use}.
3346 ``In parallel'' means that first all the values used in the individual
3347 side-effects are computed, and second all the actual side-effects are
3348 performed. For example,
3351 (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
3352 (set (mem:SI (reg:SI 1)) (reg:SI 1))])
3356 says unambiguously that the values of hard register 1 and the memory
3357 location addressed by it are interchanged. In both places where
3358 @code{(reg:SI 1)} appears as a memory address it refers to the value
3359 in register 1 @emph{before} the execution of the insn.
3361 It follows that it is @emph{incorrect} to use @code{parallel} and
3362 expect the result of one @code{set} to be available for the next one.
3363 For example, people sometimes attempt to represent a jump-if-zero
3364 instruction this way:
3367 (parallel [(set (reg:CC CC_REG) (reg:SI 34))
3368 (set (pc) (if_then_else
3369 (eq (reg:CC CC_REG) (const_int 0))
3375 But this is incorrect, because it says that the jump condition depends
3376 on the condition code value @emph{before} this instruction, not on the
3377 new value that is set by this instruction.
3379 @cindex peephole optimization, RTL representation
3380 Peephole optimization, which takes place together with final assembly
3381 code output, can produce insns whose patterns consist of a @code{parallel}
3382 whose elements are the operands needed to output the resulting
3383 assembler code---often @code{reg}, @code{mem} or constant expressions.
3384 This would not be well-formed RTL at any other stage in compilation,
3385 but it is OK then because no further optimization remains to be done.
3388 @item (cond_exec [@var{cond} @var{expr}])
3389 Represents a conditionally executed expression. The @var{expr} is
3390 executed only if the @var{cond} is nonzero. The @var{cond} expression
3391 must not have side-effects, but the @var{expr} may very well have
3395 @item (sequence [@var{insns} @dots{}])
3396 Represents a sequence of insns. If a @code{sequence} appears in the
3397 chain of insns, then each of the @var{insns} that appears in the sequence
3398 must be suitable for appearing in the chain of insns, i.e.@: must satisfy
3399 the @code{INSN_P} predicate.
3401 After delay-slot scheduling is completed, an insn and all the insns that
3402 reside in its delay slots are grouped together into a @code{sequence}.
3403 The insn requiring the delay slot is the first insn in the vector;
3404 subsequent insns are to be placed in the delay slot.
3406 @code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
3407 indicate that a branch insn should be used that will conditionally annul
3408 the effect of the insns in the delay slots. In such a case,
3409 @code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
3410 the branch and should be executed only if the branch is taken; otherwise
3411 the insn should be executed only if the branch is not taken.
3414 Some back ends also use @code{sequence} objects for purposes other than
3415 delay-slot groups. This is not supported in the common parts of the
3416 compiler, which treat such sequences as delay-slot groups.
3418 DWARF2 Call Frame Address (CFA) adjustments are sometimes also expressed
3419 using @code{sequence} objects as the value of a @code{RTX_FRAME_RELATED_P}
3420 note. This only happens if the CFA adjustments cannot be easily derived
3421 from the pattern of the instruction to which the note is attached. In
3422 such cases, the value of the note is used instead of best-guesing the
3423 semantics of the instruction. The back end can attach notes containing
3424 a @code{sequence} of @code{set} patterns that express the effect of the
3428 These expression codes appear in place of a side effect, as the body of
3429 an insn, though strictly speaking they do not always describe side
3434 @item (asm_input @var{s})
3435 Represents literal assembler code as described by the string @var{s}.
3438 @findex unspec_volatile
3439 @item (unspec [@var{operands} @dots{}] @var{index})
3440 @itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
3441 Represents a machine-specific operation on @var{operands}. @var{index}
3442 selects between multiple machine-specific operations.
3443 @code{unspec_volatile} is used for volatile operations and operations
3444 that may trap; @code{unspec} is used for other operations.
3446 These codes may appear inside a @code{pattern} of an
3447 insn, inside a @code{parallel}, or inside an expression.
3450 @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
3451 Represents a table of jump addresses. The vector elements @var{lr0},
3452 etc., are @code{label_ref} expressions. The mode @var{m} specifies
3453 how much space is given to each address; normally @var{m} would be
3456 @findex addr_diff_vec
3457 @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags})
3458 Represents a table of jump addresses expressed as offsets from
3459 @var{base}. The vector elements @var{lr0}, etc., are @code{label_ref}
3460 expressions and so is @var{base}. The mode @var{m} specifies how much
3461 space is given to each address-difference. @var{min} and @var{max}
3462 are set up by branch shortening and hold a label with a minimum and a
3463 maximum address, respectively. @var{flags} indicates the relative
3464 position of @var{base}, @var{min} and @var{max} to the containing insn
3465 and of @var{min} and @var{max} to @var{base}. See rtl.def for details.
3468 @item (prefetch:@var{m} @var{addr} @var{rw} @var{locality})
3469 Represents prefetch of memory at address @var{addr}.
3470 Operand @var{rw} is 1 if the prefetch is for data to be written, 0 otherwise;
3471 targets that do not support write prefetches should treat this as a normal
3473 Operand @var{locality} specifies the amount of temporal locality; 0 if there
3474 is none or 1, 2, or 3 for increasing levels of temporal locality;
3475 targets that do not support locality hints should ignore this.
3477 This insn is used to minimize cache-miss latency by moving data into a
3478 cache before it is accessed. It should use only non-faulting data prefetch
3483 @section Embedded Side-Effects on Addresses
3484 @cindex RTL preincrement
3485 @cindex RTL postincrement
3486 @cindex RTL predecrement
3487 @cindex RTL postdecrement
3489 Six special side-effect expression codes appear as memory addresses.
3493 @item (pre_dec:@var{m} @var{x})
3494 Represents the side effect of decrementing @var{x} by a standard
3495 amount and represents also the value that @var{x} has after being
3496 decremented. @var{x} must be a @code{reg} or @code{mem}, but most
3497 machines allow only a @code{reg}. @var{m} must be the machine mode
3498 for pointers on the machine in use. The amount @var{x} is decremented
3499 by is the length in bytes of the machine mode of the containing memory
3500 reference of which this expression serves as the address. Here is an
3504 (mem:DF (pre_dec:SI (reg:SI 39)))
3508 This says to decrement pseudo register 39 by the length of a @code{DFmode}
3509 value and use the result to address a @code{DFmode} value.
3512 @item (pre_inc:@var{m} @var{x})
3513 Similar, but specifies incrementing @var{x} instead of decrementing it.
3516 @item (post_dec:@var{m} @var{x})
3517 Represents the same side effect as @code{pre_dec} but a different
3518 value. The value represented here is the value @var{x} has @i{before}
3522 @item (post_inc:@var{m} @var{x})
3523 Similar, but specifies incrementing @var{x} instead of decrementing it.
3526 @item (post_modify:@var{m} @var{x} @var{y})
3528 Represents the side effect of setting @var{x} to @var{y} and
3529 represents @var{x} before @var{x} is modified. @var{x} must be a
3530 @code{reg} or @code{mem}, but most machines allow only a @code{reg}.
3531 @var{m} must be the machine mode for pointers on the machine in use.
3533 The expression @var{y} must be one of three forms:
3534 @code{(plus:@var{m} @var{x} @var{z})},
3535 @code{(minus:@var{m} @var{x} @var{z})}, or
3536 @code{(plus:@var{m} @var{x} @var{i})},
3537 where @var{z} is an index register and @var{i} is a constant.
3539 Here is an example of its use:
3542 (mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
3546 This says to modify pseudo register 42 by adding the contents of pseudo
3547 register 48 to it, after the use of what ever 42 points to.
3550 @item (pre_modify:@var{m} @var{x} @var{expr})
3551 Similar except side effects happen before the use.
3554 These embedded side effect expressions must be used with care. Instruction
3555 patterns may not use them. Until the @samp{flow} pass of the compiler,
3556 they may occur only to represent pushes onto the stack. The @samp{flow}
3557 pass finds cases where registers are incremented or decremented in one
3558 instruction and used as an address shortly before or after; these cases are
3559 then transformed to use pre- or post-increment or -decrement.
3561 If a register used as the operand of these expressions is used in
3562 another address in an insn, the original value of the register is used.
3563 Uses of the register outside of an address are not permitted within the
3564 same insn as a use in an embedded side effect expression because such
3565 insns behave differently on different machines and hence must be treated
3566 as ambiguous and disallowed.
3568 An instruction that can be represented with an embedded side effect
3569 could also be represented using @code{parallel} containing an additional
3570 @code{set} to describe how the address register is altered. This is not
3571 done because machines that allow these operations at all typically
3572 allow them wherever a memory address is called for. Describing them as
3573 additional parallel stores would require doubling the number of entries
3574 in the machine description.
3577 @section Assembler Instructions as Expressions
3578 @cindex assembler instructions in RTL
3580 @cindex @code{asm_operands}, usage
3581 The RTX code @code{asm_operands} represents a value produced by a
3582 user-specified assembler instruction. It is used to represent
3583 an @code{asm} statement with arguments. An @code{asm} statement with
3584 a single output operand, like this:
3587 asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
3591 is represented using a single @code{asm_operands} RTX which represents
3592 the value that is stored in @code{outputvar}:
3595 (set @var{rtx-for-outputvar}
3596 (asm_operands "foo %1,%2,%0" "a" 0
3597 [@var{rtx-for-addition-result} @var{rtx-for-*z}]
3598 [(asm_input:@var{m1} "g")
3599 (asm_input:@var{m2} "di")]))
3603 Here the operands of the @code{asm_operands} RTX are the assembler
3604 template string, the output-operand's constraint, the index-number of the
3605 output operand among the output operands specified, a vector of input
3606 operand RTX's, and a vector of input-operand modes and constraints. The
3607 mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
3610 When an @code{asm} statement has multiple output values, its insn has
3611 several such @code{set} RTX's inside of a @code{parallel}. Each @code{set}
3612 contains an @code{asm_operands}; all of these share the same assembler
3613 template and vectors, but each contains the constraint for the respective
3614 output operand. They are also distinguished by the output-operand index
3615 number, which is 0, 1, @dots{} for successive output operands.
3617 @node Debug Information
3618 @section Variable Location Debug Information in RTL
3619 @cindex Variable Location Debug Information in RTL
3621 Variable tracking relies on @code{MEM_EXPR} and @code{REG_EXPR}
3622 annotations to determine what user variables memory and register
3623 references refer to.
3625 Variable tracking at assignments uses these notes only when they refer
3626 to variables that live at fixed locations (e.g., addressable
3627 variables, global non-automatic variables). For variables whose
3628 location may vary, it relies on the following types of notes.
3631 @findex var_location
3632 @item (var_location:@var{mode} @var{var} @var{exp} @var{stat})
3633 Binds variable @code{var}, a tree, to value @var{exp}, an RTL
3634 expression. It appears only in @code{NOTE_INSN_VAR_LOCATION} and
3635 @code{DEBUG_INSN}s, with slightly different meanings. @var{mode}, if
3636 present, represents the mode of @var{exp}, which is useful if it is a
3637 modeless expression. @var{stat} is only meaningful in notes,
3638 indicating whether the variable is known to be initialized or
3642 @item (debug_expr:@var{mode} @var{decl})
3643 Stands for the value bound to the @code{DEBUG_EXPR_DECL} @var{decl},
3644 that points back to it, within value expressions in
3645 @code{VAR_LOCATION} nodes.
3647 @findex debug_implicit_ptr
3648 @item (debug_implicit_ptr:@var{mode} @var{decl})
3649 Stands for the location of a @var{decl} that is no longer addressable.
3652 @item (entry_value:@var{mode} @var{decl})
3653 Stands for the value a @var{decl} had at the entry point of the
3654 containing function.
3656 @findex debug_parameter_ref
3657 @item (debug_parameter_ref:@var{mode} @var{decl})
3658 Refers to a parameter that was completely optimized out.
3660 @findex debug_marker
3661 @item (debug_marker:@var{mode})
3662 Marks a program location. With @code{VOIDmode}, it stands for the
3663 beginning of a statement, a recommended inspection point logically after
3664 all prior side effects, and before any subsequent side effects. With
3665 @code{BLKmode}, it indicates an inline entry point: the lexical block
3666 encoded in the @code{INSN_LOCATION} is the enclosing block that encloses
3667 the inlined function.
3675 The RTL representation of the code for a function is a doubly-linked
3676 chain of objects called @dfn{insns}. Insns are expressions with
3677 special codes that are used for no other purpose. Some insns are
3678 actual instructions; others represent dispatch tables for @code{switch}
3679 statements; others represent labels to jump to or various sorts of
3680 declarative information.
3682 In addition to its own specific data, each insn must have a unique
3683 id-number that distinguishes it from all other insns in the current
3684 function (after delayed branch scheduling, copies of an insn with the
3685 same id-number may be present in multiple places in a function, but
3686 these copies will always be identical and will only appear inside a
3687 @code{sequence}), and chain pointers to the preceding and following
3688 insns. These three fields occupy the same position in every insn,
3689 independent of the expression code of the insn. They could be accessed
3690 with @code{XEXP} and @code{XINT}, but instead three special macros are
3695 @item INSN_UID (@var{i})
3696 Accesses the unique id of insn @var{i}.
3699 @item PREV_INSN (@var{i})
3700 Accesses the chain pointer to the insn preceding @var{i}.
3701 If @var{i} is the first insn, this is a null pointer.
3704 @item NEXT_INSN (@var{i})
3705 Accesses the chain pointer to the insn following @var{i}.
3706 If @var{i} is the last insn, this is a null pointer.
3710 @findex get_last_insn
3711 The first insn in the chain is obtained by calling @code{get_insns}; the
3712 last insn is the result of calling @code{get_last_insn}. Within the
3713 chain delimited by these insns, the @code{NEXT_INSN} and
3714 @code{PREV_INSN} pointers must always correspond: if @var{insn} is not
3718 NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
3722 is always true and if @var{insn} is not the last insn,
3725 PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
3731 After delay slot scheduling, some of the insns in the chain might be
3732 @code{sequence} expressions, which contain a vector of insns. The value
3733 of @code{NEXT_INSN} in all but the last of these insns is the next insn
3734 in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
3735 is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
3736 which it is contained. Similar rules apply for @code{PREV_INSN}.
3738 This means that the above invariants are not necessarily true for insns
3739 inside @code{sequence} expressions. Specifically, if @var{insn} is the
3740 first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
3741 is the insn containing the @code{sequence} expression, as is the value
3742 of @code{PREV_INSN (NEXT_INSN (@var{insn}))} if @var{insn} is the last
3743 insn in the @code{sequence} expression. You can use these expressions
3744 to find the containing @code{sequence} expression.
3746 Every insn has one of the following expression codes:
3751 The expression code @code{insn} is used for instructions that do not jump
3752 and do not do function calls. @code{sequence} expressions are always
3753 contained in insns with code @code{insn} even if one of those insns
3754 should jump or do function calls.
3756 Insns with code @code{insn} have four additional fields beyond the three
3757 mandatory ones listed above. These four are described in a table below.
3761 The expression code @code{jump_insn} is used for instructions that may
3762 jump (or, more generally, may contain @code{label_ref} expressions to
3763 which @code{pc} can be set in that instruction). If there is an
3764 instruction to return from the current function, it is recorded as a
3768 @code{jump_insn} insns have the same extra fields as @code{insn} insns,
3769 accessed in the same way and in addition contain a field
3770 @code{JUMP_LABEL} which is defined once jump optimization has completed.
3772 For simple conditional and unconditional jumps, this field contains
3773 the @code{code_label} to which this insn will (possibly conditionally)
3774 branch. In a more complex jump, @code{JUMP_LABEL} records one of the
3775 labels that the insn refers to; other jump target labels are recorded
3776 as @code{REG_LABEL_TARGET} notes. The exception is @code{addr_vec}
3777 and @code{addr_diff_vec}, where @code{JUMP_LABEL} is @code{NULL_RTX}
3778 and the only way to find the labels is to scan the entire body of the
3781 Return insns count as jumps, but their @code{JUMP_LABEL} is @code{RETURN}
3782 or @code{SIMPLE_RETURN}.
3786 The expression code @code{call_insn} is used for instructions that may do
3787 function calls. It is important to distinguish these instructions because
3788 they imply that certain registers and memory locations may be altered
3791 @findex CALL_INSN_FUNCTION_USAGE
3792 @code{call_insn} insns have the same extra fields as @code{insn} insns,
3793 accessed in the same way and in addition contain a field
3794 @code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of
3795 @code{expr_list} expressions) containing @code{use}, @code{clobber} and
3796 sometimes @code{set} expressions that denote hard registers and
3797 @code{mem}s used or clobbered by the called function.
3799 A @code{mem} generally points to a stack slot in which arguments passed
3800 to the libcall by reference (@pxref{Register Arguments,
3801 TARGET_PASS_BY_REFERENCE}) are stored. If the argument is
3802 caller-copied (@pxref{Register Arguments, TARGET_CALLEE_COPIES}),
3803 the stack slot will be mentioned in @code{clobber} and @code{use}
3804 entries; if it's callee-copied, only a @code{use} will appear, and the
3805 @code{mem} may point to addresses that are not stack slots.
3807 Registers occurring inside a @code{clobber} in this list augment
3808 registers specified in @code{CALL_USED_REGISTERS} (@pxref{Register
3811 If the list contains a @code{set} involving two registers, it indicates
3812 that the function returns one of its arguments. Such a @code{set} may
3813 look like a no-op if the same register holds the argument and the return
3817 @findex CODE_LABEL_NUMBER
3819 A @code{code_label} insn represents a label that a jump insn can jump
3820 to. It contains two special fields of data in addition to the three
3821 standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
3822 number}, a number that identifies this label uniquely among all the
3823 labels in the compilation (not just in the current function).
3824 Ultimately, the label is represented in the assembler output as an
3825 assembler label, usually of the form @samp{L@var{n}} where @var{n} is
3828 When a @code{code_label} appears in an RTL expression, it normally
3829 appears within a @code{label_ref} which represents the address of
3830 the label, as a number.
3832 Besides as a @code{code_label}, a label can also be represented as a
3833 @code{note} of type @code{NOTE_INSN_DELETED_LABEL}.
3836 The field @code{LABEL_NUSES} is only defined once the jump optimization
3837 phase is completed. It contains the number of times this label is
3838 referenced in the current function.
3841 @findex SET_LABEL_KIND
3842 @findex LABEL_ALT_ENTRY_P
3843 @cindex alternate entry points
3844 The field @code{LABEL_KIND} differentiates four different types of
3845 labels: @code{LABEL_NORMAL}, @code{LABEL_STATIC_ENTRY},
3846 @code{LABEL_GLOBAL_ENTRY}, and @code{LABEL_WEAK_ENTRY}. The only labels
3847 that do not have type @code{LABEL_NORMAL} are @dfn{alternate entry
3848 points} to the current function. These may be static (visible only in
3849 the containing translation unit), global (exposed to all translation
3850 units), or weak (global, but can be overridden by another symbol with the
3853 Much of the compiler treats all four kinds of label identically. Some
3854 of it needs to know whether or not a label is an alternate entry point;
3855 for this purpose, the macro @code{LABEL_ALT_ENTRY_P} is provided. It is
3856 equivalent to testing whether @samp{LABEL_KIND (label) == LABEL_NORMAL}.
3857 The only place that cares about the distinction between static, global,
3858 and weak alternate entry points, besides the front-end code that creates
3859 them, is the function @code{output_alternate_entry_point}, in
3862 To set the kind of a label, use the @code{SET_LABEL_KIND} macro.
3864 @findex jump_table_data
3865 @item jump_table_data
3866 A @code{jump_table_data} insn is a placeholder for the jump-table data
3867 of a @code{casesi} or @code{tablejump} insn. They are placed after
3868 a @code{tablejump_p} insn. A @code{jump_table_data} insn is not part o
3869 a basic blockm but it is associated with the basic block that ends with
3870 the @code{tablejump_p} insn. The @code{PATTERN} of a @code{jump_table_data}
3871 is always either an @code{addr_vec} or an @code{addr_diff_vec}, and a
3872 @code{jump_table_data} insn is always preceded by a @code{code_label}.
3873 The @code{tablejump_p} insn refers to that @code{code_label} via its
3878 Barriers are placed in the instruction stream when control cannot flow
3879 past them. They are placed after unconditional jump instructions to
3880 indicate that the jumps are unconditional and after calls to
3881 @code{volatile} functions, which do not return (e.g., @code{exit}).
3882 They contain no information beyond the three standard fields.
3885 @findex NOTE_LINE_NUMBER
3886 @findex NOTE_SOURCE_FILE
3888 @code{note} insns are used to represent additional debugging and
3889 declarative information. They contain two nonstandard fields, an
3890 integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
3891 string accessed with @code{NOTE_SOURCE_FILE}.
3893 If @code{NOTE_LINE_NUMBER} is positive, the note represents the
3894 position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
3895 that the line came from. These notes control generation of line
3896 number data in the assembler output.
3898 Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
3899 code with one of the following values (and @code{NOTE_SOURCE_FILE}
3900 must contain a null pointer):
3903 @findex NOTE_INSN_DELETED
3904 @item NOTE_INSN_DELETED
3905 Such a note is completely ignorable. Some passes of the compiler
3906 delete insns by altering them into notes of this kind.
3908 @findex NOTE_INSN_DELETED_LABEL
3909 @item NOTE_INSN_DELETED_LABEL
3910 This marks what used to be a @code{code_label}, but was not used for other
3911 purposes than taking its address and was transformed to mark that no
3914 @findex NOTE_INSN_BLOCK_BEG
3915 @findex NOTE_INSN_BLOCK_END
3916 @item NOTE_INSN_BLOCK_BEG
3917 @itemx NOTE_INSN_BLOCK_END
3918 These types of notes indicate the position of the beginning and end
3919 of a level of scoping of variable names. They control the output
3920 of debugging information.
3922 @findex NOTE_INSN_EH_REGION_BEG
3923 @findex NOTE_INSN_EH_REGION_END
3924 @item NOTE_INSN_EH_REGION_BEG
3925 @itemx NOTE_INSN_EH_REGION_END
3926 These types of notes indicate the position of the beginning and end of a
3927 level of scoping for exception handling. @code{NOTE_EH_HANDLER}
3928 identifies which region is associated with these notes.
3930 @findex NOTE_INSN_FUNCTION_BEG
3931 @item NOTE_INSN_FUNCTION_BEG
3932 Appears at the start of the function body, after the function
3935 @findex NOTE_INSN_VAR_LOCATION
3936 @findex NOTE_VAR_LOCATION
3937 @item NOTE_INSN_VAR_LOCATION
3938 This note is used to generate variable location debugging information.
3939 It indicates that the user variable in its @code{VAR_LOCATION} operand
3940 is at the location given in the RTL expression, or holds a value that
3941 can be computed by evaluating the RTL expression from that static
3942 point in the program up to the next such note for the same user
3945 @findex NOTE_INSN_BEGIN_STMT
3946 @item NOTE_INSN_BEGIN_STMT
3947 This note is used to generate @code{is_stmt} markers in line number
3948 debugging information. It indicates the beginning of a user
3951 @findex NOTE_INSN_INLINE_ENTRY
3952 @item NOTE_INSN_INLINE_ENTRY
3953 This note is used to generate @code{entry_pc} for inlined subroutines in
3954 debugging information. It indicates an inspection point at which all
3955 arguments for the inlined function have been bound, and before its first
3960 These codes are printed symbolically when they appear in debugging dumps.
3963 @findex INSN_VAR_LOCATION
3965 The expression code @code{debug_insn} is used for pseudo-instructions
3966 that hold debugging information for variable tracking at assignments
3967 (see @option{-fvar-tracking-assignments} option). They are the RTL
3968 representation of @code{GIMPLE_DEBUG} statements
3969 (@ref{@code{GIMPLE_DEBUG}}), with a @code{VAR_LOCATION} operand that
3970 binds a user variable tree to an RTL representation of the
3971 @code{value} in the corresponding statement. A @code{DEBUG_EXPR} in
3972 it stands for the value bound to the corresponding
3973 @code{DEBUG_EXPR_DECL}.
3975 @code{GIMPLE_DEBUG_BEGIN_STMT} and @code{GIMPLE_DEBUG_INLINE_ENTRY} are
3976 expanded to RTL as a @code{DEBUG_INSN} with a @code{DEBUG_MARKER}
3977 @code{PATTERN}; the difference is the RTL mode: the former's
3978 @code{DEBUG_MARKER} is @code{VOIDmode}, whereas the latter is
3979 @code{BLKmode}; information about the inlined function can be taken from
3980 the lexical block encoded in the @code{INSN_LOCATION}. These
3981 @code{DEBUG_INSN}s, that do not carry @code{VAR_LOCATION} information,
3982 just @code{DEBUG_MARKER}s, can be detected by testing
3983 @code{DEBUG_MARKER_INSN_P}, whereas those that do can be recognized as
3984 @code{DEBUG_BIND_INSN_P}.
3986 Throughout optimization passes, @code{DEBUG_INSN}s are not reordered
3987 with respect to each other, particularly during scheduling. Binding
3988 information is kept in pseudo-instruction form, so that, unlike notes,
3989 it gets the same treatment and adjustments that regular instructions
3990 would. It is the variable tracking pass that turns these
3991 pseudo-instructions into @code{NOTE_INSN_VAR_LOCATION},
3992 @code{NOTE_INSN_BEGIN_STMT} and @code{NOTE_INSN_INLINE_ENTRY} notes,
3993 analyzing control flow, value equivalences and changes to registers and
3994 memory referenced in value expressions, propagating the values of debug
3995 temporaries and determining expressions that can be used to compute the
3996 value of each user variable at as many points (ranges, actually) in the
3997 program as possible.
3999 Unlike @code{NOTE_INSN_VAR_LOCATION}, the value expression in an
4000 @code{INSN_VAR_LOCATION} denotes a value at that specific point in the
4001 program, rather than an expression that can be evaluated at any later
4002 point before an overriding @code{VAR_LOCATION} is encountered. E.g.,
4003 if a user variable is bound to a @code{REG} and then a subsequent insn
4004 modifies the @code{REG}, the note location would keep mapping the user
4005 variable to the register across the insn, whereas the insn location
4006 would keep the variable bound to the value, so that the variable
4007 tracking pass would emit another location note for the variable at the
4008 point in which the register is modified.
4012 @cindex @code{TImode}, in @code{insn}
4013 @cindex @code{HImode}, in @code{insn}
4014 @cindex @code{QImode}, in @code{insn}
4015 The machine mode of an insn is normally @code{VOIDmode}, but some
4016 phases use the mode for various purposes.
4018 The common subexpression elimination pass sets the mode of an insn to
4019 @code{QImode} when it is the first insn in a block that has already
4022 The second Haifa scheduling pass, for targets that can multiple issue,
4023 sets the mode of an insn to @code{TImode} when it is believed that the
4024 instruction begins an issue group. That is, when the instruction
4025 cannot issue simultaneously with the previous. This may be relied on
4026 by later passes, in particular machine-dependent reorg.
4028 Here is a table of the extra fields of @code{insn}, @code{jump_insn}
4029 and @code{call_insn} insns:
4033 @item PATTERN (@var{i})
4034 An expression for the side effect performed by this insn. This must
4035 be one of the following codes: @code{set}, @code{call}, @code{use},
4036 @code{clobber}, @code{return}, @code{simple_return}, @code{asm_input},
4037 @code{asm_output}, @code{addr_vec}, @code{addr_diff_vec},
4038 @code{trap_if}, @code{unspec}, @code{unspec_volatile},
4039 @code{parallel}, @code{cond_exec}, or @code{sequence}. If it is a
4040 @code{parallel}, each element of the @code{parallel} must be one these
4041 codes, except that @code{parallel} expressions cannot be nested and
4042 @code{addr_vec} and @code{addr_diff_vec} are not permitted inside a
4043 @code{parallel} expression.
4046 @item INSN_CODE (@var{i})
4047 An integer that says which pattern in the machine description matches
4048 this insn, or @minus{}1 if the matching has not yet been attempted.
4050 Such matching is never attempted and this field remains @minus{}1 on an insn
4051 whose pattern consists of a single @code{use}, @code{clobber},
4052 @code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.
4054 @findex asm_noperands
4055 Matching is also never attempted on insns that result from an @code{asm}
4056 statement. These contain at least one @code{asm_operands} expression.
4057 The function @code{asm_noperands} returns a non-negative value for
4060 In the debugging output, this field is printed as a number followed by
4061 a symbolic representation that locates the pattern in the @file{md}
4062 file as some small positive or negative offset from a named pattern.
4065 @item REG_NOTES (@var{i})
4066 A list (chain of @code{expr_list}, @code{insn_list} and @code{int_list}
4067 expressions) giving miscellaneous information about the insn. It is often
4068 information pertaining to the registers used in this insn.
4071 The @code{REG_NOTES} field of an insn is a chain that includes
4072 @code{expr_list} and @code{int_list} expressions as well as @code{insn_list}
4073 expressions. There are several
4074 kinds of register notes, which are distinguished by the machine mode, which
4075 in a register note is really understood as being an @code{enum reg_note}.
4076 The first operand @var{op} of the note is data whose meaning depends on
4079 @findex REG_NOTE_KIND
4080 @findex PUT_REG_NOTE_KIND
4081 The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of
4082 register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND
4083 (@var{x}, @var{newkind})} sets the register note type of @var{x} to be
4086 Register notes are of three classes: They may say something about an
4087 input to an insn, they may say something about an output of an insn, or
4088 they may create a linkage between two insns.
4090 These register notes annotate inputs to an insn:
4095 The value in @var{op} dies in this insn; that is to say, altering the
4096 value immediately after this insn would not affect the future behavior
4099 It does not follow that the register @var{op} has no useful value after
4100 this insn since @var{op} is not necessarily modified by this insn.
4101 Rather, no subsequent instruction uses the contents of @var{op}.
4105 The register @var{op} being set by this insn will not be used in a
4106 subsequent insn. This differs from a @code{REG_DEAD} note, which
4107 indicates that the value in an input will not be used subsequently.
4108 These two notes are independent; both may be present for the same
4113 The register @var{op} is incremented (or decremented; at this level
4114 there is no distinction) by an embedded side effect inside this insn.
4115 This means it appears in a @code{post_inc}, @code{pre_inc},
4116 @code{post_dec} or @code{pre_dec} expression.
4120 The register @var{op} is known to have a nonnegative value when this
4121 insn is reached. This is used by special looping instructions
4122 that terminate when the register goes negative.
4124 The @code{REG_NONNEG} note is added only to @samp{doloop_end}
4125 insns, if its pattern uses a @code{ge} condition.
4127 @findex REG_LABEL_OPERAND
4128 @item REG_LABEL_OPERAND
4129 This insn uses @var{op}, a @code{code_label} or a @code{note} of type
4130 @code{NOTE_INSN_DELETED_LABEL}, but is not a @code{jump_insn}, or it
4131 is a @code{jump_insn} that refers to the operand as an ordinary
4132 operand. The label may still eventually be a jump target, but if so
4133 in an indirect jump in a subsequent insn. The presence of this note
4134 allows jump optimization to be aware that @var{op} is, in fact, being
4135 used, and flow optimization to build an accurate flow graph.
4137 @findex REG_LABEL_TARGET
4138 @item REG_LABEL_TARGET
4139 This insn is a @code{jump_insn} but not an @code{addr_vec} or
4140 @code{addr_diff_vec}. It uses @var{op}, a @code{code_label} as a
4141 direct or indirect jump target. Its purpose is similar to that of
4142 @code{REG_LABEL_OPERAND}. This note is only present if the insn has
4143 multiple targets; the last label in the insn (in the highest numbered
4144 insn-field) goes into the @code{JUMP_LABEL} field and does not have a
4145 @code{REG_LABEL_TARGET} note. @xref{Insns, JUMP_LABEL}.
4149 Appears attached to each @code{CALL_INSN} to @code{setjmp} or a
4153 The following notes describe attributes of outputs of an insn:
4160 This note is only valid on an insn that sets only one register and
4161 indicates that that register will be equal to @var{op} at run time; the
4162 scope of this equivalence differs between the two types of notes. The
4163 value which the insn explicitly copies into the register may look
4164 different from @var{op}, but they will be equal at run time. If the
4165 output of the single @code{set} is a @code{strict_low_part} or
4166 @code{zero_extract} expression, the note refers to the register that
4167 is contained in its first operand.
4169 For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout
4170 the entire function, and could validly be replaced in all its
4171 occurrences by @var{op}. (``Validly'' here refers to the data flow of
4172 the program; simple replacement may make some insns invalid.) For
4173 example, when a constant is loaded into a register that is never
4174 assigned any other value, this kind of note is used.
4176 When a parameter is copied into a pseudo-register at entry to a function,
4177 a note of this kind records that the register is equivalent to the stack
4178 slot where the parameter was passed. Although in this case the register
4179 may be set by other insns, it is still valid to replace the register
4180 by the stack slot throughout the function.
4182 A @code{REG_EQUIV} note is also used on an instruction which copies a
4183 register parameter into a pseudo-register at entry to a function, if
4184 there is a stack slot where that parameter could be stored. Although
4185 other insns may set the pseudo-register, it is valid for the compiler to
4186 replace the pseudo-register by stack slot throughout the function,
4187 provided the compiler ensures that the stack slot is properly
4188 initialized by making the replacement in the initial copy instruction as
4189 well. This is used on machines for which the calling convention
4190 allocates stack space for register parameters. See
4191 @code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}.
4193 In the case of @code{REG_EQUAL}, the register that is set by this insn
4194 will be equal to @var{op} at run time at the end of this insn but not
4195 necessarily elsewhere in the function. In this case, @var{op}
4196 is typically an arithmetic expression. For example, when a sequence of
4197 insns such as a library call is used to perform an arithmetic operation,
4198 this kind of note is attached to the insn that produces or copies the
4201 These two notes are used in different ways by the compiler passes.
4202 @code{REG_EQUAL} is used by passes prior to register allocation (such as
4203 common subexpression elimination and loop optimization) to tell them how
4204 to think of that value. @code{REG_EQUIV} notes are used by register
4205 allocation to indicate that there is an available substitute expression
4206 (either a constant or a @code{mem} expression for the location of a
4207 parameter on the stack) that may be used in place of a register if
4208 insufficient registers are available.
4210 Except for stack homes for parameters, which are indicated by a
4211 @code{REG_EQUIV} note and are not useful to the early optimization
4212 passes and pseudo registers that are equivalent to a memory location
4213 throughout their entire life, which is not detected until later in
4214 the compilation, all equivalences are initially indicated by an attached
4215 @code{REG_EQUAL} note. In the early stages of register allocation, a
4216 @code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if
4217 @var{op} is a constant and the insn represents the only set of its
4218 destination register.
4220 Thus, compiler passes prior to register allocation need only check for
4221 @code{REG_EQUAL} notes and passes subsequent to register allocation
4222 need only check for @code{REG_EQUIV} notes.
4225 These notes describe linkages between insns. They occur in pairs: one
4226 insn has one of a pair of notes that points to a second insn, which has
4227 the inverse note pointing back to the first insn.
4230 @findex REG_DEP_TRUE
4232 This indicates a true dependence (a read after write dependence).
4234 @findex REG_DEP_OUTPUT
4235 @item REG_DEP_OUTPUT
4236 This indicates an output dependence (a write after write dependence).
4238 @findex REG_DEP_ANTI
4240 This indicates an anti dependence (a write after read dependence).
4244 These notes describe information gathered from gcov profile data. They
4245 are stored in the @code{REG_NOTES} field of an insn.
4250 This is used to specify the ratio of branches to non-branches of a
4251 branch insn according to the profile data. The note is represented
4252 as an @code{int_list} expression whose integer value is an encoding
4253 of @code{profile_probability} type. @code{profile_probability} provide
4254 member function @code{from_reg_br_prob_note} and @code{to_reg_br_prob_note}
4255 to extract and store the probability into the RTL encoding.
4259 These notes are found in JUMP insns after delayed branch scheduling
4260 has taken place. They indicate both the direction and the likelihood
4261 of the JUMP@. The format is a bitmask of ATTR_FLAG_* values.
4263 @findex REG_FRAME_RELATED_EXPR
4264 @item REG_FRAME_RELATED_EXPR
4265 This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression
4266 is used in place of the actual insn pattern. This is done in cases where
4267 the pattern is either complex or misleading.
4270 The note @code{REG_CALL_NOCF_CHECK} is used in conjunction with the
4271 @option{-fcf-protection=branch} option. The note is set if a
4272 @code{nocf_check} attribute is specified for a function type or a
4273 pointer to function type. The note is stored in the @code{REG_NOTES}
4277 @findex REG_CALL_NOCF_CHECK
4278 @item REG_CALL_NOCF_CHECK
4279 Users have control through the @code{nocf_check} attribute to identify
4280 which calls to a function should be skipped from control-flow instrumentation
4281 when the option @option{-fcf-protection=branch} is specified. The compiler
4282 puts a @code{REG_CALL_NOCF_CHECK} note on each @code{CALL_INSN} instruction
4283 that has a function type marked with a @code{nocf_check} attribute.
4286 For convenience, the machine mode in an @code{insn_list} or
4287 @code{expr_list} is printed using these symbolic codes in debugging dumps.
4291 The only difference between the expression codes @code{insn_list} and
4292 @code{expr_list} is that the first operand of an @code{insn_list} is
4293 assumed to be an insn and is printed in debugging dumps as the insn's
4294 unique id; the first operand of an @code{expr_list} is printed in the
4295 ordinary way as an expression.
4298 @section RTL Representation of Function-Call Insns
4299 @cindex calling functions in RTL
4300 @cindex RTL function-call insns
4301 @cindex function-call insns
4303 Insns that call subroutines have the RTL expression code @code{call_insn}.
4304 These insns must satisfy special rules, and their bodies must use a special
4305 RTL expression code, @code{call}.
4307 @cindex @code{call} usage
4308 A @code{call} expression has two operands, as follows:
4311 (call (mem:@var{fm} @var{addr}) @var{nbytes})
4315 Here @var{nbytes} is an operand that represents the number of bytes of
4316 argument data being passed to the subroutine, @var{fm} is a machine mode
4317 (which must equal as the definition of the @code{FUNCTION_MODE} macro in
4318 the machine description) and @var{addr} represents the address of the
4321 For a subroutine that returns no value, the @code{call} expression as
4322 shown above is the entire body of the insn, except that the insn might
4323 also contain @code{use} or @code{clobber} expressions.
4325 @cindex @code{BLKmode}, and function return values
4326 For a subroutine that returns a value whose mode is not @code{BLKmode},
4327 the value is returned in a hard register. If this register's number is
4328 @var{r}, then the body of the call insn looks like this:
4331 (set (reg:@var{m} @var{r})
4332 (call (mem:@var{fm} @var{addr}) @var{nbytes}))
4336 This RTL expression makes it clear (to the optimizer passes) that the
4337 appropriate register receives a useful value in this insn.
4339 When a subroutine returns a @code{BLKmode} value, it is handled by
4340 passing to the subroutine the address of a place to store the value.
4341 So the call insn itself does not ``return'' any value, and it has the
4342 same RTL form as a call that returns nothing.
4344 On some machines, the call instruction itself clobbers some register,
4345 for example to contain the return address. @code{call_insn} insns
4346 on these machines should have a body which is a @code{parallel}
4347 that contains both the @code{call} expression and @code{clobber}
4348 expressions that indicate which registers are destroyed. Similarly,
4349 if the call instruction requires some register other than the stack
4350 pointer that is not explicitly mentioned in its RTL, a @code{use}
4351 subexpression should mention that register.
4353 Functions that are called are assumed to modify all registers listed in
4354 the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register
4355 Basics}) and, with the exception of @code{const} functions and library
4356 calls, to modify all of memory.
4358 Insns containing just @code{use} expressions directly precede the
4359 @code{call_insn} insn to indicate which registers contain inputs to the
4360 function. Similarly, if registers other than those in
4361 @code{CALL_USED_REGISTERS} are clobbered by the called function, insns
4362 containing a single @code{clobber} follow immediately after the call to
4363 indicate which registers.
4366 @section On-the-Side SSA Form for RTL
4367 @cindex SSA, RTL form
4370 The patterns of an individual RTL instruction describe which registers
4371 are inputs to that instruction and which registers are outputs from
4372 that instruction. However, it is often useful to know where the
4373 definition of a register input comes from and where the result of
4374 a register output is used. One way of obtaining this information
4375 is to use the RTL SSA form, which provides a Static Single Assignment
4376 representation of the RTL instructions.
4378 The RTL SSA code is located in the @file{rtl-ssa} subdirectory of the GCC
4379 source tree. This section only gives a brief overview of it; please
4380 see the comments in the source code for more details.
4383 * Using RTL SSA:: What a pass needs to do to use the RTL SSA form
4384 * RTL SSA Instructions:: How instructions are represented and organized
4385 * RTL SSA Basic Blocks:: How instructions are grouped into blocks
4386 * RTL SSA Resources:: How registers and memory are represented
4387 * RTL SSA Accesses:: How register and memory accesses are represented
4388 * RTL SSA Phi Nodes:: How multiple sources are combined into one
4389 * RTL SSA Access Lists:: How accesses are chained together
4390 * Changing RTL Instructions:: How to use the RTL SSA framework to change insns
4394 @subsection Using RTL SSA in a pass
4396 A pass that wants to use the RTL SSA form should start with the following:
4399 #define INCLUDE_ALGORITHM
4400 #define INCLUDE_FUNCTIONAL
4403 #include "coretypes.h"
4404 #include "backend.h"
4407 #include "rtl-ssa.h"
4410 All the RTL SSA code is contained in the @code{rtl_ssa} namespace,
4411 so most passes will then want to do:
4414 using namespace rtl_ssa;
4417 However, this is purely a matter of taste, and the examples in the rest of
4418 this section do not require it.
4420 The RTL SSA represention is an optional on-the-side feature that applies
4421 on top of the normal RTL instructions. It is currently local to individual
4422 RTL passes and is not maintained across passes.
4424 However, in order to allow the RTL SSA information to be preserved across
4425 passes in future, @samp{crtl->ssa} points to the current function's
4426 SSA form (if any). Passes that want to use the RTL SSA form should
4430 crtl->ssa = new rtl_ssa::function_info (@var{fn});
4433 where @var{fn} is the function that the pass is processing.
4434 (Passes that are @code{using namespace rtl_ssa} do not need
4435 the @samp{rtl_ssa::}.)
4437 Once the pass has finished with the SSA form, it should do the following:
4440 free_dominance_info (CDI_DOMINATORS);
4441 if (crtl->ssa->perform_pending_updates ())
4445 crtl->ssa = nullptr;
4448 The @code{free_dominance_info} call is necessary because
4449 dominance information is not currently maintained between RTL passes.
4450 The next two lines commit any changes to the RTL instructions that
4451 were queued for later; see the comment above the declaration of
4452 @code{perform_pending_updates} for details. The final two lines
4453 discard the RTL SSA form and free the associated memory.
4455 @node RTL SSA Instructions
4456 @subsection RTL SSA Instructions
4459 @cindex reverse postorder
4460 @cindex instructions, RTL SSA
4461 @findex rtl_ssa::insn_info
4462 RTL SSA instructions are represented by an @code{rtl_ssa::insn_info}.
4463 These instructions are chained together in a single list that follows
4464 a reverse postorder (RPO) traversal of the function. This means that
4465 if any path through the function can execute an instruction @var{I1}
4466 and then later execute an instruction @var{I2} for the first time,
4467 @var{I1} appears before @var{I2} in the list@footnote{Note that this
4468 order is different from the order of the underlying RTL instructions,
4469 which follow machine code order instead.}.
4471 Two RTL SSA instructions can be compared to find which instruction
4472 occurs earlier than the other in the RPO@. One way to do this is
4473 to use the C++ comparison operators, such as:
4476 *@var{insn1} < *@var{insn2}
4479 Another way is to use the @code{compare_with} function:
4482 @var{insn1}->compare_with (@var{insn2})
4485 This expression is greater than zero if @var{insn1} comes after @var{insn2}
4486 in the RPO, less than zero if @var{insn1} comes before @var{insn2} in the
4487 RPO, or zero if @var{insn1} and @var{insn2} are the same. This order is
4488 maintained even if instructions are added to the function or moved around.
4490 The main purpose of @code{rtl_ssa::insn_info} is to hold
4491 SSA information about an instruction. However, it also caches
4492 certain properties of the instruction, such as whether it is an
4493 inline assembly instruction, whether it has volatile accesses, and so on.
4495 @node RTL SSA Basic Blocks
4496 @subsection RTL SSA Basic Blocks
4498 @cindex basic blocks, RTL SSA
4500 @findex rtl_ssa::bb_info
4501 RTL SSA instructions (@pxref{RTL SSA Instructions}) are organized into
4502 basic blocks, with each block being represented by an @code{rtl_ssa:bb_info}.
4503 There is a one-to-one mapping between these @code{rtl_ssa:bb_info}
4504 structures and the underlying CFG @code{basic_block} structures
4505 (@pxref{Basic Blocks}).
4507 @cindex ``real'' instructions, RTL SSA
4508 @anchor{real RTL SSA insns}
4509 If a CFG basic block @var{bb} contains an RTL instruction @var{insn},
4510 the RTL SSA represenation of @var{bb} also contains an RTL SSA representation
4511 of @var{insn}@footnote{Note that this excludes non-instruction things like
4512 @code{note}s and @code{barrier}s that also appear in the chain of RTL
4513 instructions.}. Within RTL SSA, these instructions are referred to as
4514 ``real'' instructions. These real instructions fall into two groups:
4515 debug instructions and nondebug instructions. Only nondebug instructions
4516 should affect code generation decisions.
4518 In addition, each RTL SSA basic block has two ``artificial''
4519 instructions: a ``head'' instruction that comes before all the real
4520 instructions and an ``end'' instruction that comes after all real
4521 instructions. These instructions exist to represent things that
4522 are conceptually defined or used at the start and end of a basic block.
4523 The instructions always exist, even if they do not currently do anything.
4525 Like instructions, these blocks are chained together in a reverse
4526 postorder. This list includes the entry block (which always comes
4527 first) and the exit block (which always comes last).
4529 @cindex extended basic blocks, RTL SSA
4530 @findex rtl_ssa::ebb_info
4531 RTL SSA basic blocks are chained together into ``extended basic blocks''
4532 (EBBs), represented by an @code{rtl_ssa::ebb_info}. Extended basic
4533 blocks contain one or more basic blocks. They have the property
4534 that if a block @var{bby} comes immediately after a block @var{bbx}
4535 in an EBB, then @var{bby} can only be reached by @var{bbx}; in other words,
4536 @var{bbx} is the sole predecessor of @var{bby}.
4538 Each extended basic block starts with an artificial ``phi node''
4539 instruction. This instruction defines all phi nodes for the EBB
4540 (@pxref{RTL SSA Phi Nodes}). (Individual blocks in an EBB do not
4541 need phi nodes because their live values can only come from one source.)
4543 The contents of a function are therefore represented using a
4544 four-level hierarchy:
4548 functions (@code{rtl_ssa::function_info}), which contain @dots{}
4551 extended basic blocks (@code{rtl_ssa::ebb_info}), which contain @dots{}
4554 basic blocks (@code{rtl_ssa::bb_info}), which contain @dots{}
4557 instructions (@code{rtl_ssa::insn_info})
4560 In dumps, a basic block is identified as @code{bb@var{n}}, where @var{n}
4561 is the index of the associated CFG @code{basic_block} structure.
4562 An EBB is in turn identified by the index of its first block.
4563 For example, an EBB that contains @samp{bb10}, @code{bb5}, @code{bb6}
4564 and @code{bb9} is identified as @var{ebb10}.
4566 @node RTL SSA Resources
4567 @subsection RTL SSA Resources
4569 The RTL SSA form tracks two types of ``resource'': registers and memory.
4570 Each hard and pseudo register is a separate resource. Memory is a
4571 single unified resource, like it is in GIMPLE (@pxref{GIMPLE}).
4573 Each resource has a unique identifier. The unique identifier for a
4574 register is simply its register number. The unique identifier for
4575 memory is a special register number called @code{MEM_REGNO}.
4577 Since resource numbers so closely match register numbers, it is sometimes
4578 convenient to refer to them simply as register numbers, or ``regnos''
4579 for short. However, the RTL SSA form also provides an abstraction
4580 of resources in the form of @code{rtl_ssa::resource_info}.
4581 This is a lightweight class that records both the regno of a resource
4582 and the @code{machine_mode} that the resource has (@pxref{Machine Modes}).
4583 It has functions for testing whether a resource is a register or memory.
4584 In principle it could be extended to other kinds of resource in future.
4586 @node RTL SSA Accesses
4587 @subsection RTL SSA Register and Memory Accesses
4589 In the RTL SSA form, most reads or writes of a resource are
4590 represented as a @code{rtl_ssa::access_info}@footnote{The exceptions
4591 are call clobbers, which are generally represented separately.
4592 See the comment above @code{rtl_ssa::insn_info} for details.}.
4593 These @code{rtl_ssa::access_info}s are organized into the following
4596 @findex rtl_ssa::access_info
4597 @findex rtl_ssa::use_info
4598 @findex rtl_ssa::def_info
4599 @findex rtl_ssa::clobber_info
4600 @findex rtl_ssa::set_info
4601 @findex rtl_ssa::phi_info
4603 rtl_ssa::access_info
4605 +-- rtl_ssa::use_info
4607 +-- rtl_ssa::def_info
4609 +-- rtl_ssa::clobber_info
4611 +-- rtl_ssa::set_info
4613 +-- rtl_ssa::phi_info
4616 A @code{rtl_ssa::use_info} represents a read or use of a resource and
4617 a @code{rtl_ssa::def_info} represents a write or definition of a resource.
4618 As in the main RTL representation, there are two basic types of
4619 definition: clobbers and sets. The difference is that a clobber
4620 leaves the register with an unspecified value that cannot be used
4621 or relied on by later instructions, while a set leaves the register
4622 with a known value that later instructions could use if they wanted to.
4623 A @code{rtl_ssa::clobber_info} represents a clobber and
4624 a @code{rtl_ssa::set_info} represent a set.
4626 Each @code{rtl_ssa::use_info} records which single @code{rtl_ssa::set_info}
4627 provides the value of the resource; this is null if the resource is
4628 completely undefined at the point of use. Each @code{rtl_ssa::set_info}
4629 in turn records all the @code{rtl_ssa::use_info}s that use its value.
4631 If a value of a resource can come from multiple sources,
4632 a @code{rtl_ssa::phi_info} brings those multiple sources together
4633 into a single definition (@pxref{RTL SSA Phi Nodes}).
4635 @node RTL SSA Phi Nodes
4636 @subsection RTL SSA Phi Nodes
4638 @cindex phi nodes, RTL SSA
4639 @findex rtl_ssa::phi_info
4640 If a resource is live on entry to an extended basic block and if the
4641 resource's value can come from multiple sources, the extended basic block
4642 has a ``phi node'' that collects together these multiple sources.
4643 The phi node conceptually has one input for each incoming edge of
4644 the extended basic block, with the input specifying the value of
4645 the resource on that edge. For example, suppose a function contains
4651 (set (reg:SI R1) (const_int 0)) ;; A
4652 (set (pc) (label_ref bb5))
4656 (set (reg:SI R1) (const_int 1)) ;; B
4661 ;; live in: R1 @dots{}
4664 (set (reg:SI @var{R2})
4665 (plus:SI (reg:SI R1) @dots{})) ;; C
4668 The value of R1 on entry to block 5 can come from either A or B@.
4669 The extended basic block that contains block 5 would therefore have a
4670 phi node with two inputs: the first input would have the value of
4671 R1 defined by A and the second input would have the value of
4672 R1 defined by B@. This phi node would then provide the value of
4673 R1 for C (assuming that R1 does not change again between
4674 the start of block 5 and C).
4676 Since RTL is not a ``native'' SSA representation, these phi nodes
4677 simply collect together definitions that already exist. Each input
4678 to a phi node for a resource @var{R} is itself a definition of
4679 resource @var{R} (or is null if the resource is completely
4680 undefined for a particular incoming edge). This is in contrast
4681 to a native SSA representation like GIMPLE, where the phi inputs
4682 can be arbitrary expressions. As a result, RTL SSA phi nodes
4683 never involve ``hidden'' moves: all moves are instead explicit.
4685 Phi nodes are represented as a @code{rtl_ssa::phi_node}.
4686 Each input to a phi node is represented as an @code{rtl_ssa::use_info}.
4688 @node RTL SSA Access Lists
4689 @subsection RTL SSA Access Lists
4691 All the definitions of a resource are chained together in reverse postorder.
4692 In general, this list can contain an arbitrary mix of both sets
4693 (@code{rtl_ssa::set_info}) and clobbers (@code{rtl_ssa::clobber_info}).
4694 However, it is often useful to skip over all intervening clobbers
4695 of a resource in order to find the next set. The list is constructed
4696 in such a way that this can be done in amortized constant time.
4698 All uses (@code{rtl_ssa::use_info}) of a given set are also chained
4699 together into a list. This list of uses is divided into three parts:
4703 uses by ``real'' nondebug instructions (@pxref{real RTL SSA insns})
4706 uses by real debug instructions
4709 uses by phi nodes (@pxref{RTL SSA Phi Nodes})
4712 The first and second parts individually follow reverse postorder.
4713 The third part has no particular order.
4715 @cindex degenerate phi node, RTL SSA
4716 The last use by a real nondebug instruction always comes earlier in
4717 the reverse postorder than the next definition of the resource (if any).
4718 This means that the accesses follow a linear sequence of the form:
4722 first definition of resource R
4726 first use by a real nondebug instruction of the first definition of resource R
4732 last use by a real nondebug instruction of the first definition of resource R
4736 second definition of resource R
4740 first use by a real nondebug instruction of the second definition of resource R
4746 last use by a real nondebug instruction of the second definition of resource R
4753 last definition of resource R
4757 first use by a real nondebug instruction of the last definition of resource R
4763 last use by a real nondebug instruction of the last definition of resource R
4767 (Note that clobbers never have uses; only sets do.)
4769 This linear view is easy to achieve when there is only a single definition
4770 of a resource, which is commonly true for pseudo registers. However,
4771 things are more complex if code has a structure like the following:
4790 The list of accesses would begin as follows:
4794 definition of R by A
4798 use of A's definition of R by B
4802 definition of R by C
4805 The next access to R is in D, but the value of R that D uses comes from
4808 This is resolved by adding a phi node for @code{ebb4}. All inputs to this
4809 phi node have the same value, which in the example above is A's definition
4810 of R@. In other circumstances, it would not be necessary to create a phi
4811 node when all inputs are equal, so these phi nodes are referred to as
4812 ``degenerate'' phi nodes.
4814 The full list of accesses to R is therefore:
4818 definition of R by A
4822 use of A's definition of R by B
4826 definition of R by C
4829 definition of R by ebb4's phi instruction, with the input coming from A
4833 use of the ebb4's R phi definition of R by B
4837 Note that A's definition is also used by ebb4's phi node, but this
4838 use belongs to the third part of the use list described above and
4839 so does not form part of the linear sequence.
4841 It is possible to ``look through'' any degenerate phi to the ultimate
4842 definition using the function @code{look_through_degenerate_phi}.
4843 Note that the input to a degenerate phi is never itself provided
4844 by a degenerate phi.
4846 At present, the SSA form takes this principle one step further
4847 and guarantees that, for any given resource @var{res}, one of the
4852 The resource has a single definition @var{def}, which is not a phi node.
4853 Excluding uses of undefined registers, all uses of @var{res} by real
4854 nondebug instructions use the value provided by @var{def}.
4857 Excluding uses of undefined registers, all uses of @var{res} use
4858 values provided by definitions that occur earlier in the same
4859 extended basic block. These definitions might come from phi nodes
4860 or from real instructions.
4863 @node Changing RTL Instructions
4864 @subsection Using the RTL SSA framework to change instructions
4866 @findex rtl_ssa::insn_change
4867 There are various routines that help to change a single RTL instruction
4868 or a group of RTL instructions while keeping the RTL SSA form up-to-date.
4869 This section first describes the process for changing a single instruction,
4870 then goes on to describe the differences when changing multiple instructions.
4873 * Changing One RTL SSA Instruction::
4874 * Changing Multiple RTL SSA Instructions::
4877 @node Changing One RTL SSA Instruction
4878 @subsubsection Changing One RTL SSA Instruction
4880 Before making a change, passes should first use a statement like the
4884 auto attempt = crtl->ssa->new_change_attempt ();
4887 Here, @code{attempt} is an RAII object that should remain in scope
4888 for the entire change attempt. It automatically frees temporary
4889 memory related to the changes when it goes out of scope.
4891 Next, the pass should create an @code{rtl_ssa::insn_change} object
4892 for the instruction that it wants to change. This object specifies
4897 what the instruction's new list of uses should be (@code{new_uses}).
4898 By default this is the same as the instruction's current list of uses.
4901 what the instruction's new list of definitions should be (@code{new_defs}).
4902 By default this is the same as the instruction's current list of
4906 where the instruction should be located (@code{move_range}).
4907 This is a range of instructions after which the instruction could
4908 be placed, represented as an @code{rtl_ssa::insn_range}.
4909 By default the instruction must remain at its current position.
4912 If a pass was attempting to change all these properties of an instruction
4913 @code{insn}, it might do something like this:
4916 rtl_ssa::insn_change change (insn);
4917 change.new_defs = @dots{};
4918 change.new_uses = @dots{};
4919 change.move_range = @dots{};
4922 This @code{rtl_ssa::insn_change} only describes something that the
4923 pass @emph{might} do; at this stage, nothing has actually changed.
4925 As noted above, the default @code{move_range} requires the instruction
4926 to remain where it is. At the other extreme, it is possible to allow
4927 the instruction to move anywhere within its extended basic block,
4928 provided that all the new uses and definitions can be performed
4929 at the new location. The way to do this is:
4932 change.move_range = insn->ebb ()->insn_range ();
4935 In either case, the next step is to make sure that move range is
4936 consistent with the new uses and definitions. The way to do this is:
4939 if (!rtl_ssa::restrict_movement (change))
4943 This function tries to limit @code{move_range} to a range of instructions
4944 at which @code{new_uses} and @code{new_defs} can be correctly performed.
4945 It returns true on success or false if no suitable location exists.
4947 The pass should also tentatively change the pattern of the instruction
4948 to whatever form the pass wants the instruction to have. This should use
4949 the facilities provided by @file{recog.cc}. For example:
4952 rtl_insn *rtl = insn->rtl ();
4953 insn_change_watermark watermark;
4954 validate_change (rtl, &PATTERN (rtl), new_pat, 1);
4957 will tentatively replace @code{insn}'s pattern with @code{new_pat}.
4959 These changes and the construction of the @code{rtl_ssa::insn_change}
4960 can happen in either order or be interleaved.
4962 After the tentative changes to the instruction are complete,
4963 the pass should check whether the new pattern matches a target
4964 instruction or satisfies the requirements of an inline asm:
4967 if (!rtl_ssa::recog (attempt, change))
4971 This step might change the instruction pattern further in order to
4972 make it match. It might also add new definitions or restrict the range
4973 of the move. For example, if the new pattern did not match in its original
4974 form, but could be made to match by adding a clobber of the flags
4975 register, @code{rtl_ssa::recog} will check whether the flags register
4976 is free at an appropriate point. If so, it will add a clobber of the
4977 flags register to @code{new_defs} and restrict @code{move_range} to
4978 the locations at which the flags register can be safely clobbered.
4980 Even if the proposed new instruction is valid according to
4981 @code{rtl_ssa::recog}, the change might not be worthwhile.
4982 For example, when optimizing for speed, the new instruction might
4983 turn out to be slower than the original one. When optimizing for
4984 size, the new instruction might turn out to be bigger than the
4987 Passes should check for this case using @code{change_is_worthwhile}.
4991 if (!rtl_ssa::change_is_worthwhile (change))
4995 If the change passes this test too then the pass can perform the change using:
4998 confirm_change_group ();
4999 crtl->ssa->change_insn (change);
5002 Putting all this together, the change has the following form:
5005 auto attempt = crtl->ssa->new_change_attempt ();
5007 rtl_ssa::insn_change change (insn);
5008 change.new_defs = @dots{};
5009 change.new_uses = @dots{};
5010 change.move_range = @dots{};
5012 if (!rtl_ssa::restrict_movement (change))
5015 insn_change_watermark watermark;
5016 // Use validate_change etc. to change INSN's pattern.
5018 if (!rtl_ssa::recog (attempt, change)
5019 || !rtl_ssa::change_is_worthwhile (change))
5022 confirm_change_group ();
5023 crtl->ssa->change_insn (change);
5026 @node Changing Multiple RTL SSA Instructions
5027 @subsubsection Changing Multiple RTL SSA Instructions
5029 The process for changing multiple instructions is similar
5030 to the process for changing single instructions
5031 (@pxref{Changing One RTL SSA Instruction}). The pass should
5032 again start the change attempt with:
5035 auto attempt = crtl->ssa->new_change_attempt ();
5038 and keep @code{attempt} in scope for the duration of the change
5039 attempt. It should then construct an @code{rtl_ssa::insn_change}
5040 for each change that it wants to make.
5042 After this, it should combine the changes into a sequence of
5043 @code{rtl_ssa::insn_change} pointers. This sequence must be in
5044 reverse postorder; the instructions will remain strictly in the
5045 order that the sequence specifies.
5047 For example, if a pass is changing exactly two instructions,
5051 rtl_ssa::insn_change *changes[] = @{ &change1, &change2 @};
5054 where @code{change1}'s instruction must come before @code{change2}'s.
5055 Alternatively, if the pass is changing a variable number of
5056 instructions, it might build up the sequence in a
5057 @code{vec<rtl_ssa::insn_change *>}.
5059 By default, @code{rtl_ssa::restrict_movement} assumes that all
5060 instructions other than the one passed to it will remain in their
5061 current positions and will retain their current uses and definitions.
5062 When changing multiple instructions, it is usually more effective
5063 to ignore the other instructions that are changing. The sequencing
5064 described above ensures that the changing instructions remain
5065 in the correct order with respect to each other.
5066 The way to do this is:
5069 if (!rtl_ssa::restrict_movement_ignoring (change, insn_is_changing (changes)))
5073 Similarly, when @code{rtl_ssa::restrict_movement} is detecting
5074 whether a register can be clobbered, it by default assumes that
5075 all other instructions will remain in their current positions and
5076 retain their current form. It is again more effective to ignore
5077 changing instructions (which might, for example, no longer need
5078 to clobber the flags register). The way to do this is:
5081 if (!rtl_ssa::recog_ignoring (attempt, change, insn_is_changing (changes)))
5085 When changing multiple instructions, the important question is usually
5086 not whether each individual change is worthwhile, but whether the changes
5087 as a whole are worthwhile. The way to test this is:
5090 if (!rtl_ssa::changes_are_worthwhile (changes))
5094 The process for changing single instructions makes sure that one
5095 @code{rtl_ssa::insn_change} in isolation is valid. But when changing
5096 multiple instructions, it is also necessary to test whether the
5097 sequence as a whole is valid. For example, it might be impossible
5098 to satisfy all of the @code{move_range}s at once.
5100 Therefore, once the pass has a sequence of changes that are
5101 individually correct, it should use:
5104 if (!crtl->ssa->verify_insn_changes (changes))
5108 to check whether the sequence as a whole is valid. If all checks pass,
5112 confirm_change_group ();
5113 crtl->ssa->change_insns (changes);
5116 Putting all this together, the process for a two-instruction change is:
5119 auto attempt = crtl->ssa->new_change_attempt ();
5121 rtl_ssa::insn_change change1 (insn1);
5122 change1.new_defs = @dots{};
5123 change1.new_uses = @dots{};
5124 change1.move_range = @dots{};
5126 rtl_ssa::insn_change change2 (insn2);
5127 change2.new_defs = @dots{};
5128 change2.new_uses = @dots{};
5129 change2.move_range = @dots{};
5131 rtl_ssa::insn_change *changes[] = @{ &change1, &change2 @};
5133 auto is_changing = insn_is_changing (changes);
5134 if (!rtl_ssa::restrict_movement_ignoring (change1, is_changing)
5135 || !rtl_ssa::restrict_movement_ignoring (change2, is_changing))
5138 insn_change_watermark watermark;
5139 // Use validate_change etc. to change INSN1's and INSN2's patterns.
5141 if (!rtl_ssa::recog_ignoring (attempt, change1, is_changing)
5142 || !rtl_ssa::recog_ignoring (attempt, change2, is_changing)
5143 || !rtl_ssa::changes_are_worthwhile (changes)
5144 || !crtl->ssa->verify_insn_changes (changes))
5147 confirm_change_group ();
5148 crtl->ssa->change_insns (changes);
5152 @section Structure Sharing Assumptions
5153 @cindex sharing of RTL components
5154 @cindex RTL structure sharing assumptions
5156 The compiler assumes that certain kinds of RTL expressions are unique;
5157 there do not exist two distinct objects representing the same value.
5158 In other cases, it makes an opposite assumption: that no RTL expression
5159 object of a certain kind appears in more than one place in the
5160 containing structure.
5162 These assumptions refer to a single function; except for the RTL
5163 objects that describe global variables and external functions,
5164 and a few standard objects such as small integer constants,
5165 no RTL objects are common to two functions.
5168 @cindex @code{reg}, RTL sharing
5170 Each pseudo-register has only a single @code{reg} object to represent it,
5171 and therefore only a single machine mode.
5173 @cindex symbolic label
5174 @cindex @code{symbol_ref}, RTL sharing
5176 For any symbolic label, there is only one @code{symbol_ref} object
5179 @cindex @code{const_int}, RTL sharing
5181 All @code{const_int} expressions with equal values are shared.
5183 @cindex @code{const_poly_int}, RTL sharing
5185 All @code{const_poly_int} expressions with equal modes and values
5188 @cindex @code{pc}, RTL sharing
5190 There is only one @code{pc} expression.
5192 @cindex @code{const_double}, RTL sharing
5194 There is only one @code{const_double} expression with value 0 for
5195 each floating point mode. Likewise for values 1 and 2.
5197 @cindex @code{const_vector}, RTL sharing
5199 There is only one @code{const_vector} expression with value 0 for
5200 each vector mode, be it an integer or a double constant vector.
5202 @cindex @code{label_ref}, RTL sharing
5203 @cindex @code{scratch}, RTL sharing
5205 No @code{label_ref} or @code{scratch} appears in more than one place in
5206 the RTL structure; in other words, it is safe to do a tree-walk of all
5207 the insns in the function and assume that each time a @code{label_ref}
5208 or @code{scratch} is seen it is distinct from all others that are seen.
5210 @cindex @code{mem}, RTL sharing
5212 Only one @code{mem} object is normally created for each static
5213 variable or stack slot, so these objects are frequently shared in all
5214 the places they appear. However, separate but equal objects for these
5215 variables are occasionally made.
5217 @cindex @code{asm_operands}, RTL sharing
5219 When a single @code{asm} statement has multiple output operands, a
5220 distinct @code{asm_operands} expression is made for each output operand.
5221 However, these all share the vector which contains the sequence of input
5222 operands. This sharing is used later on to test whether two
5223 @code{asm_operands} expressions come from the same statement, so all
5224 optimizations must carefully preserve the sharing if they copy the
5228 No RTL object appears in more than one place in the RTL structure
5229 except as described above. Many passes of the compiler rely on this
5230 by assuming that they can modify RTL objects in place without unwanted
5231 side-effects on other insns.
5233 @findex unshare_all_rtl
5235 During initial RTL generation, shared structure is freely introduced.
5236 After all the RTL for a function has been generated, all shared
5237 structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.cc},
5238 after which the above rules are guaranteed to be followed.
5240 @findex copy_rtx_if_shared
5242 During the combiner pass, shared structure within an insn can exist
5243 temporarily. However, the shared structure is copied before the
5244 combiner is finished with the insn. This is done by calling
5245 @code{copy_rtx_if_shared}, which is a subroutine of
5246 @code{unshare_all_rtl}.
5250 @section Reading RTL
5252 To read an RTL object from a file, call @code{read_rtx}. It takes one
5253 argument, a stdio stream, and returns a single RTL object. This routine
5254 is defined in @file{read-rtl.cc}. It is not available in the compiler
5255 itself, only the various programs that generate the compiler back end
5256 from the machine description.
5258 People frequently have the idea of using RTL stored as text in a file as
5259 an interface between a language front end and the bulk of GCC@. This
5260 idea is not feasible.
5262 GCC was designed to use RTL internally only. Correct RTL for a given
5263 program is very dependent on the particular target machine. And the RTL
5264 does not contain all the information about the program.
5266 The proper way to interface GCC to a new language front end is with
5267 the ``tree'' data structure, described in the files @file{tree.h} and
5268 @file{tree.def}. The documentation for this structure (@pxref{GENERIC})