1 @c Copyright (C) 1988-2018 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 * Sharing:: Some expressions are unique; others *must* be copied.
43 * Reading RTL:: Reading textual RTL from a file.
47 @section RTL Object Types
48 @cindex RTL object types
53 @cindex RTL expression
55 RTL uses five kinds of objects: expressions, integers, wide integers,
56 strings and vectors. Expressions are the most important ones. An RTL
57 expression (``RTX'', for short) is a C structure, but it is usually
58 referred to with a pointer; a type that is given the typedef name
61 An integer is simply an @code{int}; their written form uses decimal
62 digits. A wide integer is an integral object whose type is
63 @code{HOST_WIDE_INT}; their written form uses decimal digits.
65 A string is a sequence of characters. In core it is represented as a
66 @code{char *} in usual C fashion, and it is written in C syntax as well.
67 However, strings in RTL may never be null. If you write an empty string in
68 a machine description, it is represented in core as a null pointer rather
69 than as a pointer to a null character. In certain contexts, these null
70 pointers instead of strings are valid. Within RTL code, strings are most
71 commonly found inside @code{symbol_ref} expressions, but they appear in
72 other contexts in the RTL expressions that make up machine descriptions.
74 In a machine description, strings are normally written with double
75 quotes, as you would in C@. However, strings in machine descriptions may
76 extend over many lines, which is invalid C, and adjacent string
77 constants are not concatenated as they are in C@. Any string constant
78 may be surrounded with a single set of parentheses. Sometimes this
79 makes the machine description easier to read.
81 There is also a special syntax for strings, which can be useful when C
82 code is embedded in a machine description. Wherever a string can
83 appear, it is also valid to write a C-style brace block. The entire
84 brace block, including the outermost pair of braces, is considered to be
85 the string constant. Double quote characters inside the braces are not
86 special. Therefore, if you write string constants in the C code, you
87 need not escape each quote character with a backslash.
89 A vector contains an arbitrary number of pointers to expressions. The
90 number of elements in the vector is explicitly present in the vector.
91 The written form of a vector consists of square brackets
92 (@samp{[@dots{}]}) surrounding the elements, in sequence and with
93 whitespace separating them. Vectors of length zero are not created;
94 null pointers are used instead.
96 @cindex expression codes
97 @cindex codes, RTL expression
100 Expressions are classified by @dfn{expression codes} (also called RTX
101 codes). The expression code is a name defined in @file{rtl.def}, which is
102 also (in uppercase) a C enumeration constant. The possible expression
103 codes and their meanings are machine-independent. The code of an RTX can
104 be extracted with the macro @code{GET_CODE (@var{x})} and altered with
105 @code{PUT_CODE (@var{x}, @var{newcode})}.
107 The expression code determines how many operands the expression contains,
108 and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell
109 by looking at an operand what kind of object it is. Instead, you must know
110 from its context---from the expression code of the containing expression.
111 For example, in an expression of code @code{subreg}, the first operand is
112 to be regarded as an expression and the second operand as a polynomial
113 integer. In an expression of code @code{plus}, there are two operands,
114 both of which are to be regarded as expressions. In a @code{symbol_ref}
115 expression, there is one operand, which is to be regarded as a string.
117 Expressions are written as parentheses containing the name of the
118 expression type, its flags and machine mode if any, and then the operands
119 of the expression (separated by spaces).
121 Expression code names in the @samp{md} file are written in lowercase,
122 but when they appear in C code they are written in uppercase. In this
123 manual, they are shown as follows: @code{const_int}.
127 In a few contexts a null pointer is valid where an expression is normally
128 wanted. The written form of this is @code{(nil)}.
131 @section RTL Classes and Formats
133 @cindex classes of RTX codes
134 @cindex RTX codes, classes of
135 @findex GET_RTX_CLASS
137 The various expression codes are divided into several @dfn{classes},
138 which are represented by single characters. You can determine the class
139 of an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}.
140 Currently, @file{rtl.def} defines these classes:
144 An RTX code that represents an actual object, such as a register
145 (@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}).
146 @code{LO_SUM}) is also included; instead, @code{SUBREG} and
147 @code{STRICT_LOW_PART} are not in this class, but in class
151 An RTX code that represents a constant object. @code{HIGH} is also
152 included in this class.
155 An RTX code for a non-symmetric comparison, such as @code{GEU} or
158 @item RTX_COMM_COMPARE
159 An RTX code for a symmetric (commutative) comparison, such as @code{EQ}
163 An RTX code for a unary arithmetic operation, such as @code{NEG},
164 @code{NOT}, or @code{ABS}. This category also includes value extension
165 (sign or zero) and conversions between integer and floating point.
168 An RTX code for a commutative binary operation, such as @code{PLUS} or
169 @code{AND}. @code{NE} and @code{EQ} are comparisons, so they have class
170 @code{RTX_COMM_COMPARE}.
173 An RTX code for a non-commutative binary operation, such as @code{MINUS},
174 @code{DIV}, or @code{ASHIFTRT}.
176 @item RTX_BITFIELD_OPS
177 An RTX code for a bit-field operation. Currently only
178 @code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}. These have three inputs
179 and are lvalues (so they can be used for insertion as well).
183 An RTX code for other three input operations. Currently only
184 @code{IF_THEN_ELSE}, @code{VEC_MERGE}, @code{SIGN_EXTRACT},
185 @code{ZERO_EXTRACT}, and @code{FMA}.
188 An RTX code for an entire instruction: @code{INSN}, @code{JUMP_INSN}, and
189 @code{CALL_INSN}. @xref{Insns}.
192 An RTX code for something that matches in insns, such as
193 @code{MATCH_DUP}. These only occur in machine descriptions.
196 An RTX code for an auto-increment addressing mode, such as
197 @code{POST_INC}. @samp{XEXP (@var{x}, 0)} gives the auto-modified
201 All other RTX codes. This category includes the remaining codes used
202 only in machine descriptions (@code{DEFINE_*}, etc.). It also includes
203 all the codes describing side effects (@code{SET}, @code{USE},
204 @code{CLOBBER}, etc.) and the non-insns that may appear on an insn
205 chain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}.
206 @code{SUBREG} is also part of this class.
210 For each expression code, @file{rtl.def} specifies the number of
211 contained objects and their kinds using a sequence of characters
212 called the @dfn{format} of the expression code. For example,
213 the format of @code{subreg} is @samp{ep}.
215 @cindex RTL format characters
216 These are the most commonly used format characters:
220 An expression (actually a pointer to an expression).
232 A vector of expressions.
235 A few other format characters are used occasionally:
239 @samp{u} is equivalent to @samp{e} except that it is printed differently
240 in debugging dumps. It is used for pointers to insns.
243 @samp{n} is equivalent to @samp{i} except that it is printed differently
244 in debugging dumps. It is used for the line number or code number of a
248 @samp{S} indicates a string which is optional. In the RTL objects in
249 core, @samp{S} is equivalent to @samp{s}, but when the object is read,
250 from an @samp{md} file, the string value of this operand may be omitted.
251 An omitted string is taken to be the null string.
254 @samp{V} indicates a vector which is optional. In the RTL objects in
255 core, @samp{V} is equivalent to @samp{E}, but when the object is read
256 from an @samp{md} file, the vector value of this operand may be omitted.
257 An omitted vector is effectively the same as a vector of no elements.
260 @samp{B} indicates a pointer to basic block structure.
263 A polynomial integer. At present this is used only for @code{SUBREG_BYTE}.
266 @samp{0} means a slot whose contents do not fit any normal category.
267 @samp{0} slots are not printed at all in dumps, and are often used in
268 special ways by small parts of the compiler.
271 There are macros to get the number of operands and the format
272 of an expression code:
275 @findex GET_RTX_LENGTH
276 @item GET_RTX_LENGTH (@var{code})
277 Number of operands of an RTX of code @var{code}.
279 @findex GET_RTX_FORMAT
280 @item GET_RTX_FORMAT (@var{code})
281 The format of an RTX of code @var{code}, as a C string.
284 Some classes of RTX codes always have the same format. For example, it
285 is safe to assume that all comparison operations have format @code{ee}.
289 All codes of this class have format @code{e}.
292 @itemx RTX_COMM_ARITH
293 @itemx RTX_COMM_COMPARE
295 All codes of these classes have format @code{ee}.
297 @item RTX_BITFIELD_OPS
299 All codes of these classes have format @code{eee}.
302 All codes of this class have formats that begin with @code{iuueiee}.
303 @xref{Insns}. Note that not all RTL objects linked onto an insn chain
304 are of class @code{RTX_INSN}.
310 You can make no assumptions about the format of these codes.
314 @section Access to Operands
316 @cindex access to operands
317 @cindex operand access
323 Operands of expressions are accessed using the macros @code{XEXP},
324 @code{XINT}, @code{XWINT} and @code{XSTR}. Each of these macros takes
325 two arguments: an expression-pointer (RTX) and an operand number
326 (counting from zero). Thus,
333 accesses operand 2 of expression @var{x}, as an expression.
340 accesses the same operand as an integer. @code{XSTR}, used in the same
341 fashion, would access it as a string.
343 Any operand can be accessed as an integer, as an expression or as a string.
344 You must choose the correct method of access for the kind of value actually
345 stored in the operand. You would do this based on the expression code of
346 the containing expression. That is also how you would know how many
349 For example, if @var{x} is an @code{int_list} expression, you know that it has
350 two operands which can be correctly accessed as @code{XINT (@var{x}, 0)}
351 and @code{XEXP (@var{x}, 1)}. Incorrect accesses like
352 @code{XEXP (@var{x}, 0)} and @code{XINT (@var{x}, 1)} would compile,
353 but would trigger an internal compiler error when rtl checking is enabled.
354 Nothing stops you from writing @code{XEXP (@var{x}, 28)} either, but
355 this will access memory past the end of the expression with
356 unpredictable results.
358 Access to operands which are vectors is more complicated. You can use the
359 macro @code{XVEC} to get the vector-pointer itself, or the macros
360 @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
365 @item XVEC (@var{exp}, @var{idx})
366 Access the vector-pointer which is operand number @var{idx} in @var{exp}.
369 @item XVECLEN (@var{exp}, @var{idx})
370 Access the length (number of elements) in the vector which is
371 in operand number @var{idx} in @var{exp}. This value is an @code{int}.
374 @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
375 Access element number @var{eltnum} in the vector which is
376 in operand number @var{idx} in @var{exp}. This value is an RTX@.
378 It is up to you to make sure that @var{eltnum} is not negative
379 and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
382 All the macros defined in this section expand into lvalues and therefore
383 can be used to assign the operands, lengths and vector elements as well as
386 @node Special Accessors
387 @section Access to Special Operands
388 @cindex access to special operands
390 Some RTL nodes have special annotations associated with them.
395 @findex MEM_ALIAS_SET
396 @item MEM_ALIAS_SET (@var{x})
397 If 0, @var{x} is not in any alias set, and may alias anything. Otherwise,
398 @var{x} can only alias @code{MEM}s in a conflicting alias set. This value
399 is set in a language-dependent manner in the front-end, and should not be
400 altered in the back-end. In some front-ends, these numbers may correspond
401 in some way to types, or other language-level entities, but they need not,
402 and the back-end makes no such assumptions.
403 These set numbers are tested with @code{alias_sets_conflict_p}.
406 @item MEM_EXPR (@var{x})
407 If this register is known to hold the value of some user-level
408 declaration, this is that tree node. It may also be a
409 @code{COMPONENT_REF}, in which case this is some field reference,
410 and @code{TREE_OPERAND (@var{x}, 0)} contains the declaration,
411 or another @code{COMPONENT_REF}, or null if there is no compile-time
412 object associated with the reference.
414 @findex MEM_OFFSET_KNOWN_P
415 @item MEM_OFFSET_KNOWN_P (@var{x})
416 True if the offset of the memory reference from @code{MEM_EXPR} is known.
417 @samp{MEM_OFFSET (@var{x})} provides the offset if so.
420 @item MEM_OFFSET (@var{x})
421 The offset from the start of @code{MEM_EXPR}. The value is only valid if
422 @samp{MEM_OFFSET_KNOWN_P (@var{x})} is true.
424 @findex MEM_SIZE_KNOWN_P
425 @item MEM_SIZE_KNOWN_P (@var{x})
426 True if the size of the memory reference is known.
427 @samp{MEM_SIZE (@var{x})} provides its size if so.
430 @item MEM_SIZE (@var{x})
431 The size in bytes of the memory reference.
432 This is mostly relevant for @code{BLKmode} references as otherwise
433 the size is implied by the mode. The value is only valid if
434 @samp{MEM_SIZE_KNOWN_P (@var{x})} is true.
437 @item MEM_ALIGN (@var{x})
438 The known alignment in bits of the memory reference.
440 @findex MEM_ADDR_SPACE
441 @item MEM_ADDR_SPACE (@var{x})
442 The address space of the memory reference. This will commonly be zero
443 for the generic address space.
448 @findex ORIGINAL_REGNO
449 @item ORIGINAL_REGNO (@var{x})
450 This field holds the number the register ``originally'' had; for a
451 pseudo register turned into a hard reg this will hold the old pseudo
455 @item REG_EXPR (@var{x})
456 If this register is known to hold the value of some user-level
457 declaration, this is that tree node.
460 @item REG_OFFSET (@var{x})
461 If this register is known to hold the value of some user-level
462 declaration, this is the offset into that logical storage.
467 @findex SYMBOL_REF_DECL
468 @item SYMBOL_REF_DECL (@var{x})
469 If the @code{symbol_ref} @var{x} was created for a @code{VAR_DECL} or
470 a @code{FUNCTION_DECL}, that tree is recorded here. If this value is
471 null, then @var{x} was created by back end code generation routines,
472 and there is no associated front end symbol table entry.
474 @code{SYMBOL_REF_DECL} may also point to a tree of class @code{'c'},
475 that is, some sort of constant. In this case, the @code{symbol_ref}
476 is an entry in the per-file constant pool; again, there is no associated
477 front end symbol table entry.
479 @findex SYMBOL_REF_CONSTANT
480 @item SYMBOL_REF_CONSTANT (@var{x})
481 If @samp{CONSTANT_POOL_ADDRESS_P (@var{x})} is true, this is the constant
482 pool entry for @var{x}. It is null otherwise.
484 @findex SYMBOL_REF_DATA
485 @item SYMBOL_REF_DATA (@var{x})
486 A field of opaque type used to store @code{SYMBOL_REF_DECL} or
487 @code{SYMBOL_REF_CONSTANT}.
489 @findex SYMBOL_REF_FLAGS
490 @item SYMBOL_REF_FLAGS (@var{x})
491 In a @code{symbol_ref}, this is used to communicate various predicates
492 about the symbol. Some of these are common enough to be computed by
493 common code, some are specific to the target. The common bits are:
496 @findex SYMBOL_REF_FUNCTION_P
497 @findex SYMBOL_FLAG_FUNCTION
498 @item SYMBOL_FLAG_FUNCTION
499 Set if the symbol refers to a function.
501 @findex SYMBOL_REF_LOCAL_P
502 @findex SYMBOL_FLAG_LOCAL
503 @item SYMBOL_FLAG_LOCAL
504 Set if the symbol is local to this ``module''.
505 See @code{TARGET_BINDS_LOCAL_P}.
507 @findex SYMBOL_REF_EXTERNAL_P
508 @findex SYMBOL_FLAG_EXTERNAL
509 @item SYMBOL_FLAG_EXTERNAL
510 Set if this symbol is not defined in this translation unit.
511 Note that this is not the inverse of @code{SYMBOL_FLAG_LOCAL}.
513 @findex SYMBOL_REF_SMALL_P
514 @findex SYMBOL_FLAG_SMALL
515 @item SYMBOL_FLAG_SMALL
516 Set if the symbol is located in the small data section.
517 See @code{TARGET_IN_SMALL_DATA_P}.
519 @findex SYMBOL_FLAG_TLS_SHIFT
520 @findex SYMBOL_REF_TLS_MODEL
521 @item SYMBOL_REF_TLS_MODEL (@var{x})
522 This is a multi-bit field accessor that returns the @code{tls_model}
523 to be used for a thread-local storage symbol. It returns zero for
524 non-thread-local symbols.
526 @findex SYMBOL_REF_HAS_BLOCK_INFO_P
527 @findex SYMBOL_FLAG_HAS_BLOCK_INFO
528 @item SYMBOL_FLAG_HAS_BLOCK_INFO
529 Set if the symbol has @code{SYMBOL_REF_BLOCK} and
530 @code{SYMBOL_REF_BLOCK_OFFSET} fields.
532 @findex SYMBOL_REF_ANCHOR_P
533 @findex SYMBOL_FLAG_ANCHOR
534 @cindex @option{-fsection-anchors}
535 @item SYMBOL_FLAG_ANCHOR
536 Set if the symbol is used as a section anchor. ``Section anchors''
537 are symbols that have a known position within an @code{object_block}
538 and that can be used to access nearby members of that block.
539 They are used to implement @option{-fsection-anchors}.
541 If this flag is set, then @code{SYMBOL_FLAG_HAS_BLOCK_INFO} will be too.
544 Bits beginning with @code{SYMBOL_FLAG_MACH_DEP} are available for
548 @findex SYMBOL_REF_BLOCK
549 @item SYMBOL_REF_BLOCK (@var{x})
550 If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the
551 @samp{object_block} structure to which the symbol belongs,
552 or @code{NULL} if it has not been assigned a block.
554 @findex SYMBOL_REF_BLOCK_OFFSET
555 @item SYMBOL_REF_BLOCK_OFFSET (@var{x})
556 If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the offset of @var{x}
557 from the first object in @samp{SYMBOL_REF_BLOCK (@var{x})}. The value is
558 negative if @var{x} has not yet been assigned to a block, or it has not
559 been given an offset within that block.
563 @section Flags in an RTL Expression
564 @cindex flags in RTL expression
566 RTL expressions contain several flags (one-bit bit-fields)
567 that are used in certain types of expression. Most often they
568 are accessed with the following macros, which expand into lvalues.
571 @findex CROSSING_JUMP_P
572 @cindex @code{jump_insn} and @samp{/j}
573 @item CROSSING_JUMP_P (@var{x})
574 Nonzero in a @code{jump_insn} if it crosses between hot and cold sections,
575 which could potentially be very far apart in the executable. The presence
576 of this flag indicates to other optimizations that this branching instruction
577 should not be ``collapsed'' into a simpler branching construct. It is used
578 when the optimization to partition basic blocks into hot and cold sections
581 @findex CONSTANT_POOL_ADDRESS_P
582 @cindex @code{symbol_ref} and @samp{/u}
583 @cindex @code{unchanging}, in @code{symbol_ref}
584 @item CONSTANT_POOL_ADDRESS_P (@var{x})
585 Nonzero in a @code{symbol_ref} if it refers to part of the current
586 function's constant pool. For most targets these addresses are in a
587 @code{.rodata} section entirely separate from the function, but for
588 some targets the addresses are close to the beginning of the function.
589 In either case GCC assumes these addresses can be addressed directly,
590 perhaps with the help of base registers.
591 Stored in the @code{unchanging} field and printed as @samp{/u}.
593 @findex INSN_ANNULLED_BRANCH_P
594 @cindex @code{jump_insn} and @samp{/u}
595 @cindex @code{call_insn} and @samp{/u}
596 @cindex @code{insn} and @samp{/u}
597 @cindex @code{unchanging}, in @code{jump_insn}, @code{call_insn} and @code{insn}
598 @item INSN_ANNULLED_BRANCH_P (@var{x})
599 In a @code{jump_insn}, @code{call_insn}, or @code{insn} indicates
600 that the branch is an annulling one. See the discussion under
601 @code{sequence} below. Stored in the @code{unchanging} field and
602 printed as @samp{/u}.
604 @findex INSN_DELETED_P
605 @cindex @code{insn} and @samp{/v}
606 @cindex @code{call_insn} and @samp{/v}
607 @cindex @code{jump_insn} and @samp{/v}
608 @cindex @code{code_label} and @samp{/v}
609 @cindex @code{jump_table_data} and @samp{/v}
610 @cindex @code{barrier} and @samp{/v}
611 @cindex @code{note} and @samp{/v}
612 @cindex @code{volatil}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, @code{jump_table_data}, @code{barrier}, and @code{note}
613 @item INSN_DELETED_P (@var{x})
614 In an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label},
615 @code{jump_table_data}, @code{barrier}, or @code{note},
616 nonzero if the insn has been deleted. Stored in the
617 @code{volatil} field and printed as @samp{/v}.
619 @findex INSN_FROM_TARGET_P
620 @cindex @code{insn} and @samp{/s}
621 @cindex @code{jump_insn} and @samp{/s}
622 @cindex @code{call_insn} and @samp{/s}
623 @cindex @code{in_struct}, in @code{insn} and @code{jump_insn} and @code{call_insn}
624 @item INSN_FROM_TARGET_P (@var{x})
625 In an @code{insn} or @code{jump_insn} or @code{call_insn} in a delay
626 slot of a branch, indicates that the insn
627 is from the target of the branch. If the branch insn has
628 @code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if
629 the branch is taken. For annulled branches with
630 @code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the
631 branch is not taken. When @code{INSN_ANNULLED_BRANCH_P} is not set,
632 this insn will always be executed. Stored in the @code{in_struct}
633 field and printed as @samp{/s}.
635 @findex LABEL_PRESERVE_P
636 @cindex @code{code_label} and @samp{/i}
637 @cindex @code{note} and @samp{/i}
638 @cindex @code{in_struct}, in @code{code_label} and @code{note}
639 @item LABEL_PRESERVE_P (@var{x})
640 In a @code{code_label} or @code{note}, indicates that the label is referenced by
641 code or data not visible to the RTL of a given function.
642 Labels referenced by a non-local goto will have this bit set. Stored
643 in the @code{in_struct} field and printed as @samp{/s}.
645 @findex LABEL_REF_NONLOCAL_P
646 @cindex @code{label_ref} and @samp{/v}
647 @cindex @code{reg_label} and @samp{/v}
648 @cindex @code{volatil}, in @code{label_ref} and @code{reg_label}
649 @item LABEL_REF_NONLOCAL_P (@var{x})
650 In @code{label_ref} and @code{reg_label} expressions, nonzero if this is
651 a reference to a non-local label.
652 Stored in the @code{volatil} field and printed as @samp{/v}.
654 @findex MEM_KEEP_ALIAS_SET_P
655 @cindex @code{mem} and @samp{/j}
656 @cindex @code{jump}, in @code{mem}
657 @item MEM_KEEP_ALIAS_SET_P (@var{x})
658 In @code{mem} expressions, 1 if we should keep the alias set for this
659 mem unchanged when we access a component. Set to 1, for example, when we
660 are already in a non-addressable component of an aggregate.
661 Stored in the @code{jump} field and printed as @samp{/j}.
663 @findex MEM_VOLATILE_P
664 @cindex @code{mem} and @samp{/v}
665 @cindex @code{asm_input} and @samp{/v}
666 @cindex @code{asm_operands} and @samp{/v}
667 @cindex @code{volatil}, in @code{mem}, @code{asm_operands}, and @code{asm_input}
668 @item MEM_VOLATILE_P (@var{x})
669 In @code{mem}, @code{asm_operands}, and @code{asm_input} expressions,
670 nonzero for volatile memory references.
671 Stored in the @code{volatil} field and printed as @samp{/v}.
674 @cindex @code{mem} and @samp{/c}
675 @cindex @code{call}, in @code{mem}
676 @item MEM_NOTRAP_P (@var{x})
677 In @code{mem}, nonzero for memory references that will not trap.
678 Stored in the @code{call} field and printed as @samp{/c}.
681 @cindex @code{mem} and @samp{/f}
682 @cindex @code{frame_related}, in @code{mem}
683 @item MEM_POINTER (@var{x})
684 Nonzero in a @code{mem} if the memory reference holds a pointer.
685 Stored in the @code{frame_related} field and printed as @samp{/f}.
687 @findex MEM_READONLY_P
688 @cindex @code{mem} and @samp{/u}
689 @cindex @code{unchanging}, in @code{mem}
690 @item MEM_READONLY_P (@var{x})
691 Nonzero in a @code{mem}, if the memory is statically allocated and read-only.
693 Read-only in this context means never modified during the lifetime of the
694 program, not necessarily in ROM or in write-disabled pages. A common
695 example of the later is a shared library's global offset table. This
696 table is initialized by the runtime loader, so the memory is technically
697 writable, but after control is transferred from the runtime loader to the
698 application, this memory will never be subsequently modified.
700 Stored in the @code{unchanging} field and printed as @samp{/u}.
702 @findex PREFETCH_SCHEDULE_BARRIER_P
703 @cindex @code{prefetch} and @samp{/v}
704 @cindex @code{volatile}, in @code{prefetch}
705 @item PREFETCH_SCHEDULE_BARRIER_P (@var{x})
706 In a @code{prefetch}, indicates that the prefetch is a scheduling barrier.
707 No other INSNs will be moved over it.
708 Stored in the @code{volatil} field and printed as @samp{/v}.
710 @findex REG_FUNCTION_VALUE_P
711 @cindex @code{reg} and @samp{/i}
712 @cindex @code{return_val}, in @code{reg}
713 @item REG_FUNCTION_VALUE_P (@var{x})
714 Nonzero in a @code{reg} if it is the place in which this function's
715 value is going to be returned. (This happens only in a hard
716 register.) Stored in the @code{return_val} field and printed as
720 @cindex @code{reg} and @samp{/f}
721 @cindex @code{frame_related}, in @code{reg}
722 @item REG_POINTER (@var{x})
723 Nonzero in a @code{reg} if the register holds a pointer. Stored in the
724 @code{frame_related} field and printed as @samp{/f}.
726 @findex REG_USERVAR_P
727 @cindex @code{reg} and @samp{/v}
728 @cindex @code{volatil}, in @code{reg}
729 @item REG_USERVAR_P (@var{x})
730 In a @code{reg}, nonzero if it corresponds to a variable present in
731 the user's source code. Zero for temporaries generated internally by
732 the compiler. Stored in the @code{volatil} field and printed as
735 The same hard register may be used also for collecting the values of
736 functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
739 @findex RTL_CONST_CALL_P
740 @cindex @code{call_insn} and @samp{/u}
741 @cindex @code{unchanging}, in @code{call_insn}
742 @item RTL_CONST_CALL_P (@var{x})
743 In a @code{call_insn} indicates that the insn represents a call to a
744 const function. Stored in the @code{unchanging} field and printed as
747 @findex RTL_PURE_CALL_P
748 @cindex @code{call_insn} and @samp{/i}
749 @cindex @code{return_val}, in @code{call_insn}
750 @item RTL_PURE_CALL_P (@var{x})
751 In a @code{call_insn} indicates that the insn represents a call to a
752 pure function. Stored in the @code{return_val} field and printed as
755 @findex RTL_CONST_OR_PURE_CALL_P
756 @cindex @code{call_insn} and @samp{/u} or @samp{/i}
757 @item RTL_CONST_OR_PURE_CALL_P (@var{x})
758 In a @code{call_insn}, true if @code{RTL_CONST_CALL_P} or
759 @code{RTL_PURE_CALL_P} is true.
761 @findex RTL_LOOPING_CONST_OR_PURE_CALL_P
762 @cindex @code{call_insn} and @samp{/c}
763 @cindex @code{call}, in @code{call_insn}
764 @item RTL_LOOPING_CONST_OR_PURE_CALL_P (@var{x})
765 In a @code{call_insn} indicates that the insn represents a possibly
766 infinite looping call to a const or pure function. Stored in the
767 @code{call} field and printed as @samp{/c}. Only true if one of
768 @code{RTL_CONST_CALL_P} or @code{RTL_PURE_CALL_P} is true.
770 @findex RTX_FRAME_RELATED_P
771 @cindex @code{insn} and @samp{/f}
772 @cindex @code{call_insn} and @samp{/f}
773 @cindex @code{jump_insn} and @samp{/f}
774 @cindex @code{barrier} and @samp{/f}
775 @cindex @code{set} and @samp{/f}
776 @cindex @code{frame_related}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, and @code{set}
777 @item RTX_FRAME_RELATED_P (@var{x})
778 Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn},
779 @code{barrier}, or @code{set} which is part of a function prologue
780 and sets the stack pointer, sets the frame pointer, or saves a register.
781 This flag should also be set on an instruction that sets up a temporary
782 register to use in place of the frame pointer.
783 Stored in the @code{frame_related} field and printed as @samp{/f}.
785 In particular, on RISC targets where there are limits on the sizes of
786 immediate constants, it is sometimes impossible to reach the register
787 save area directly from the stack pointer. In that case, a temporary
788 register is used that is near enough to the register save area, and the
789 Canonical Frame Address, i.e., DWARF2's logical frame pointer, register
790 must (temporarily) be changed to be this temporary register. So, the
791 instruction that sets this temporary register must be marked as
792 @code{RTX_FRAME_RELATED_P}.
794 If the marked instruction is overly complex (defined in terms of what
795 @code{dwarf2out_frame_debug_expr} can handle), you will also have to
796 create a @code{REG_FRAME_RELATED_EXPR} note and attach it to the
797 instruction. This note should contain a simple expression of the
798 computation performed by this instruction, i.e., one that
799 @code{dwarf2out_frame_debug_expr} can handle.
801 This flag is required for exception handling support on targets with RTL
804 @findex SCHED_GROUP_P
805 @cindex @code{insn} and @samp{/s}
806 @cindex @code{call_insn} and @samp{/s}
807 @cindex @code{jump_insn} and @samp{/s}
808 @cindex @code{jump_table_data} and @samp{/s}
809 @cindex @code{in_struct}, in @code{insn}, @code{call_insn}, @code{jump_insn} and @code{jump_table_data}
810 @item SCHED_GROUP_P (@var{x})
811 During instruction scheduling, in an @code{insn}, @code{call_insn},
812 @code{jump_insn} or @code{jump_table_data}, indicates that the
813 previous insn must be scheduled together with this insn. This is used to
814 ensure that certain groups of instructions will not be split up by the
815 instruction scheduling pass, for example, @code{use} insns before
816 a @code{call_insn} may not be separated from the @code{call_insn}.
817 Stored in the @code{in_struct} field and printed as @samp{/s}.
819 @findex SET_IS_RETURN_P
820 @cindex @code{insn} and @samp{/j}
821 @cindex @code{jump}, in @code{insn}
822 @item SET_IS_RETURN_P (@var{x})
823 For a @code{set}, nonzero if it is for a return.
824 Stored in the @code{jump} field and printed as @samp{/j}.
826 @findex SIBLING_CALL_P
827 @cindex @code{call_insn} and @samp{/j}
828 @cindex @code{jump}, in @code{call_insn}
829 @item SIBLING_CALL_P (@var{x})
830 For a @code{call_insn}, nonzero if the insn is a sibling call.
831 Stored in the @code{jump} field and printed as @samp{/j}.
833 @findex STRING_POOL_ADDRESS_P
834 @cindex @code{symbol_ref} and @samp{/f}
835 @cindex @code{frame_related}, in @code{symbol_ref}
836 @item STRING_POOL_ADDRESS_P (@var{x})
837 For a @code{symbol_ref} expression, nonzero if it addresses this function's
838 string constant pool.
839 Stored in the @code{frame_related} field and printed as @samp{/f}.
841 @findex SUBREG_PROMOTED_UNSIGNED_P
842 @cindex @code{subreg} and @samp{/u} and @samp{/v}
843 @cindex @code{unchanging}, in @code{subreg}
844 @cindex @code{volatil}, in @code{subreg}
845 @item SUBREG_PROMOTED_UNSIGNED_P (@var{x})
846 Returns a value greater then zero for a @code{subreg} that has
847 @code{SUBREG_PROMOTED_VAR_P} nonzero if the object being referenced is kept
848 zero-extended, zero if it is kept sign-extended, and less then zero if it is
849 extended some other way via the @code{ptr_extend} instruction.
850 Stored in the @code{unchanging}
851 field and @code{volatil} field, printed as @samp{/u} and @samp{/v}.
852 This macro may only be used to get the value it may not be used to change
853 the value. Use @code{SUBREG_PROMOTED_UNSIGNED_SET} to change the value.
855 @findex SUBREG_PROMOTED_UNSIGNED_SET
856 @cindex @code{subreg} and @samp{/u}
857 @cindex @code{unchanging}, in @code{subreg}
858 @cindex @code{volatil}, in @code{subreg}
859 @item SUBREG_PROMOTED_UNSIGNED_SET (@var{x})
860 Set the @code{unchanging} and @code{volatil} fields in a @code{subreg}
861 to reflect zero, sign, or other extension. If @code{volatil} is
862 zero, then @code{unchanging} as nonzero means zero extension and as
863 zero means sign extension. If @code{volatil} is nonzero then some
864 other type of extension was done via the @code{ptr_extend} instruction.
866 @findex SUBREG_PROMOTED_VAR_P
867 @cindex @code{subreg} and @samp{/s}
868 @cindex @code{in_struct}, in @code{subreg}
869 @item SUBREG_PROMOTED_VAR_P (@var{x})
870 Nonzero in a @code{subreg} if it was made when accessing an object that
871 was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine
872 description macro (@pxref{Storage Layout}). In this case, the mode of
873 the @code{subreg} is the declared mode of the object and the mode of
874 @code{SUBREG_REG} is the mode of the register that holds the object.
875 Promoted variables are always either sign- or zero-extended to the wider
876 mode on every assignment. Stored in the @code{in_struct} field and
877 printed as @samp{/s}.
879 @findex SYMBOL_REF_USED
880 @cindex @code{used}, in @code{symbol_ref}
881 @item SYMBOL_REF_USED (@var{x})
882 In a @code{symbol_ref}, indicates that @var{x} has been used. This is
883 normally only used to ensure that @var{x} is only declared external
884 once. Stored in the @code{used} field.
886 @findex SYMBOL_REF_WEAK
887 @cindex @code{symbol_ref} and @samp{/i}
888 @cindex @code{return_val}, in @code{symbol_ref}
889 @item SYMBOL_REF_WEAK (@var{x})
890 In a @code{symbol_ref}, indicates that @var{x} has been declared weak.
891 Stored in the @code{return_val} field and printed as @samp{/i}.
893 @findex SYMBOL_REF_FLAG
894 @cindex @code{symbol_ref} and @samp{/v}
895 @cindex @code{volatil}, in @code{symbol_ref}
896 @item SYMBOL_REF_FLAG (@var{x})
897 In a @code{symbol_ref}, this is used as a flag for machine-specific purposes.
898 Stored in the @code{volatil} field and printed as @samp{/v}.
900 Most uses of @code{SYMBOL_REF_FLAG} are historic and may be subsumed
901 by @code{SYMBOL_REF_FLAGS}. Certainly use of @code{SYMBOL_REF_FLAGS}
902 is mandatory if the target requires more than one bit of storage.
905 These are the fields to which the above macros refer:
909 @cindex @samp{/c} in RTL dump
911 In a @code{mem}, 1 means that the memory reference will not trap.
913 In a @code{call}, 1 means that this pure or const call may possibly
916 In an RTL dump, this flag is represented as @samp{/c}.
918 @findex frame_related
919 @cindex @samp{/f} in RTL dump
921 In an @code{insn} or @code{set} expression, 1 means that it is part of
922 a function prologue and sets the stack pointer, sets the frame pointer,
923 saves a register, or sets up a temporary register to use in place of the
926 In @code{reg} expressions, 1 means that the register holds a pointer.
928 In @code{mem} expressions, 1 means that the memory reference holds a pointer.
930 In @code{symbol_ref} expressions, 1 means that the reference addresses
931 this function's string constant pool.
933 In an RTL dump, this flag is represented as @samp{/f}.
936 @cindex @samp{/s} in RTL dump
938 In @code{reg} expressions, it is 1 if the register has its entire life
939 contained within the test expression of some loop.
941 In @code{subreg} expressions, 1 means that the @code{subreg} is accessing
942 an object that has had its mode promoted from a wider mode.
944 In @code{label_ref} expressions, 1 means that the referenced label is
945 outside the innermost loop containing the insn in which the @code{label_ref}
948 In @code{code_label} expressions, it is 1 if the label may never be deleted.
949 This is used for labels which are the target of non-local gotos. Such a
950 label that would have been deleted is replaced with a @code{note} of type
951 @code{NOTE_INSN_DELETED_LABEL}.
953 In an @code{insn} during dead-code elimination, 1 means that the insn is
956 In an @code{insn} or @code{jump_insn} during reorg for an insn in the
957 delay slot of a branch,
958 1 means that this insn is from the target of the branch.
960 In an @code{insn} during instruction scheduling, 1 means that this insn
961 must be scheduled as part of a group together with the previous insn.
963 In an RTL dump, this flag is represented as @samp{/s}.
966 @cindex @samp{/i} in RTL dump
968 In @code{reg} expressions, 1 means the register contains
969 the value to be returned by the current function. On
970 machines that pass parameters in registers, the same register number
971 may be used for parameters as well, but this flag is not set on such
974 In @code{symbol_ref} expressions, 1 means the referenced symbol is weak.
976 In @code{call} expressions, 1 means the call is pure.
978 In an RTL dump, this flag is represented as @samp{/i}.
981 @cindex @samp{/j} in RTL dump
983 In a @code{mem} expression, 1 means we should keep the alias set for this
984 mem unchanged when we access a component.
986 In a @code{set}, 1 means it is for a return.
988 In a @code{call_insn}, 1 means it is a sibling call.
990 In a @code{jump_insn}, 1 means it is a crossing jump.
992 In an RTL dump, this flag is represented as @samp{/j}.
995 @cindex @samp{/u} in RTL dump
997 In @code{reg} and @code{mem} expressions, 1 means
998 that the value of the expression never changes.
1000 In @code{subreg} expressions, it is 1 if the @code{subreg} references an
1001 unsigned object whose mode has been promoted to a wider mode.
1003 In an @code{insn} or @code{jump_insn} in the delay slot of a branch
1004 instruction, 1 means an annulling branch should be used.
1006 In a @code{symbol_ref} expression, 1 means that this symbol addresses
1007 something in the per-function constant pool.
1009 In a @code{call_insn} 1 means that this instruction is a call to a const
1012 In an RTL dump, this flag is represented as @samp{/u}.
1016 This flag is used directly (without an access macro) at the end of RTL
1017 generation for a function, to count the number of times an expression
1018 appears in insns. Expressions that appear more than once are copied,
1019 according to the rules for shared structure (@pxref{Sharing}).
1021 For a @code{reg}, it is used directly (without an access macro) by the
1022 leaf register renumbering code to ensure that each register is only
1025 In a @code{symbol_ref}, it indicates that an external declaration for
1026 the symbol has already been written.
1029 @cindex @samp{/v} in RTL dump
1031 @cindex volatile memory references
1032 In a @code{mem}, @code{asm_operands}, or @code{asm_input}
1033 expression, it is 1 if the memory
1034 reference is volatile. Volatile memory references may not be deleted,
1035 reordered or combined.
1037 In a @code{symbol_ref} expression, it is used for machine-specific
1040 In a @code{reg} expression, it is 1 if the value is a user-level variable.
1041 0 indicates an internal compiler temporary.
1043 In an @code{insn}, 1 means the insn has been deleted.
1045 In @code{label_ref} and @code{reg_label} expressions, 1 means a reference
1046 to a non-local label.
1048 In @code{prefetch} expressions, 1 means that the containing insn is a
1051 In an RTL dump, this flag is represented as @samp{/v}.
1055 @section Machine Modes
1056 @cindex machine modes
1058 @findex machine_mode
1059 A machine mode describes a size of data object and the representation used
1060 for it. In the C code, machine modes are represented by an enumeration
1061 type, @code{machine_mode}, defined in @file{machmode.def}. Each RTL
1062 expression has room for a machine mode and so do certain kinds of tree
1063 expressions (declarations and types, to be precise).
1065 In debugging dumps and machine descriptions, the machine mode of an RTL
1066 expression is written after the expression code with a colon to separate
1067 them. The letters @samp{mode} which appear at the end of each machine mode
1068 name are omitted. For example, @code{(reg:SI 38)} is a @code{reg}
1069 expression with machine mode @code{SImode}. If the mode is
1070 @code{VOIDmode}, it is not written at all.
1072 Here is a table of machine modes. The term ``byte'' below refers to an
1073 object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}).
1078 ``Bit'' mode represents a single bit, for predicate registers.
1082 ``Quarter-Integer'' mode represents a single byte treated as an integer.
1086 ``Half-Integer'' mode represents a two-byte integer.
1090 ``Partial Single Integer'' mode represents an integer which occupies
1091 four bytes but which doesn't really use all four. On some machines,
1092 this is the right mode to use for pointers.
1096 ``Single Integer'' mode represents a four-byte integer.
1100 ``Partial Double Integer'' mode represents an integer which occupies
1101 eight bytes but which doesn't really use all eight. On some machines,
1102 this is the right mode to use for certain pointers.
1106 ``Double Integer'' mode represents an eight-byte integer.
1110 ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
1114 ``Octa Integer'' (?) mode represents a thirty-two-byte integer.
1118 ``Hexadeca Integer'' (?) mode represents a sixty-four-byte integer.
1122 ``Quarter-Floating'' mode represents a quarter-precision (single byte)
1123 floating point number.
1127 ``Half-Floating'' mode represents a half-precision (two byte) floating
1132 ``Three-Quarter-Floating'' (?) mode represents a three-quarter-precision
1133 (three byte) floating point number.
1137 ``Single Floating'' mode represents a four byte floating point number.
1138 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1139 this is a single-precision IEEE floating point number; it can also be
1140 used for double-precision (on processors with 16-bit bytes) and
1141 single-precision VAX and IBM types.
1145 ``Double Floating'' mode represents an eight byte floating point number.
1146 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1147 this is a double-precision IEEE floating point number.
1151 ``Extended Floating'' mode represents an IEEE extended floating point
1152 number. This mode only has 80 meaningful bits (ten bytes). Some
1153 processors require such numbers to be padded to twelve bytes, others
1154 to sixteen; this mode is used for either.
1158 ``Single Decimal Floating'' mode represents a four byte decimal
1159 floating point number (as distinct from conventional binary floating
1164 ``Double Decimal Floating'' mode represents an eight byte decimal
1165 floating point number.
1169 ``Tetra Decimal Floating'' mode represents a sixteen byte decimal
1170 floating point number all 128 of whose bits are meaningful.
1174 ``Tetra Floating'' mode represents a sixteen byte floating point number
1175 all 128 of whose bits are meaningful. One common use is the
1176 IEEE quad-precision format.
1180 ``Quarter-Fractional'' mode represents a single byte treated as a signed
1181 fractional number. The default format is ``s.7''.
1185 ``Half-Fractional'' mode represents a two-byte signed fractional number.
1186 The default format is ``s.15''.
1190 ``Single Fractional'' mode represents a four-byte signed fractional number.
1191 The default format is ``s.31''.
1195 ``Double Fractional'' mode represents an eight-byte signed fractional number.
1196 The default format is ``s.63''.
1200 ``Tetra Fractional'' mode represents a sixteen-byte signed fractional number.
1201 The default format is ``s.127''.
1205 ``Unsigned Quarter-Fractional'' mode represents a single byte treated as an
1206 unsigned fractional number. The default format is ``.8''.
1210 ``Unsigned Half-Fractional'' mode represents a two-byte unsigned fractional
1211 number. The default format is ``.16''.
1215 ``Unsigned Single Fractional'' mode represents a four-byte unsigned fractional
1216 number. The default format is ``.32''.
1220 ``Unsigned Double Fractional'' mode represents an eight-byte unsigned
1221 fractional number. The default format is ``.64''.
1225 ``Unsigned Tetra Fractional'' mode represents a sixteen-byte unsigned
1226 fractional number. The default format is ``.128''.
1230 ``Half-Accumulator'' mode represents a two-byte signed accumulator.
1231 The default format is ``s8.7''.
1235 ``Single Accumulator'' mode represents a four-byte signed accumulator.
1236 The default format is ``s16.15''.
1240 ``Double Accumulator'' mode represents an eight-byte signed accumulator.
1241 The default format is ``s32.31''.
1245 ``Tetra Accumulator'' mode represents a sixteen-byte signed accumulator.
1246 The default format is ``s64.63''.
1250 ``Unsigned Half-Accumulator'' mode represents a two-byte unsigned accumulator.
1251 The default format is ``8.8''.
1255 ``Unsigned Single Accumulator'' mode represents a four-byte unsigned
1256 accumulator. The default format is ``16.16''.
1260 ``Unsigned Double Accumulator'' mode represents an eight-byte unsigned
1261 accumulator. The default format is ``32.32''.
1265 ``Unsigned Tetra Accumulator'' mode represents a sixteen-byte unsigned
1266 accumulator. The default format is ``64.64''.
1270 ``Condition Code'' mode represents the value of a condition code, which
1271 is a machine-specific set of bits used to represent the result of a
1272 comparison operation. Other machine-specific modes may also be used for
1273 the condition code. These modes are not used on machines that use
1274 @code{cc0} (@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
1396 @findex MODE_FUNCTION
1398 Algol or Pascal function variables including a static chain.
1399 (These are not currently implemented).
1403 Modes representing condition code values. These are @code{CCmode} plus
1404 any @code{CC_MODE} modes listed in the @file{@var{machine}-modes.def}.
1405 @xref{Jump Patterns},
1406 also see @ref{Condition Code}.
1408 @findex MODE_POINTER_BOUNDS
1409 @item MODE_POINTER_BOUNDS
1410 Pointer bounds modes. Used to represent values of pointer bounds type.
1411 Operations in these modes may be executed as NOPs depending on hardware
1412 features and environment setup.
1416 This is a catchall mode class for modes which don't fit into the above
1417 classes. Currently @code{VOIDmode} and @code{BLKmode} are in
1421 @cindex machine mode wrapper classes
1422 @code{machmode.h} also defines various wrapper classes that combine a
1423 @code{machine_mode} with a static assertion that a particular
1424 condition holds. The classes are:
1427 @findex scalar_int_mode
1428 @item scalar_int_mode
1429 A mode that has class @code{MODE_INT} or @code{MODE_PARTIAL_INT}.
1431 @findex scalar_float_mode
1432 @item scalar_float_mode
1433 A mode that has class @code{MODE_FLOAT} or @code{MODE_DECIMAL_FLOAT}.
1437 A mode that holds a single numerical value. In practice this means
1438 that the mode is a @code{scalar_int_mode}, is a @code{scalar_float_mode},
1439 or has class @code{MODE_FRACT}, @code{MODE_UFRACT}, @code{MODE_ACCUM},
1440 @code{MODE_UACCUM} or @code{MODE_POINTER_BOUNDS}.
1442 @findex complex_mode
1444 A mode that has class @code{MODE_COMPLEX_INT} or @code{MODE_COMPLEX_FLOAT}.
1446 @findex fixed_size_mode
1447 @item fixed_size_mode
1448 A mode whose size is known at compile time.
1451 Named modes use the most constrained of the available wrapper classes,
1452 if one exists, otherwise they use @code{machine_mode}. For example,
1453 @code{QImode} is a @code{scalar_int_mode}, @code{SFmode} is a
1454 @code{scalar_float_mode} and @code{BLKmode} is a plain
1455 @code{machine_mode}. It is possible to refer to any mode as a raw
1456 @code{machine_mode} by adding the @code{E_} prefix, where @code{E}
1457 stands for ``enumeration''. For example, the raw @code{machine_mode}
1458 names of the modes just mentioned are @code{E_QImode}, @code{E_SFmode}
1459 and @code{E_BLKmode} respectively.
1461 The wrapper classes implicitly convert to @code{machine_mode} and to any
1462 wrapper class that represents a more general condition; for example
1463 @code{scalar_int_mode} and @code{scalar_float_mode} both convert
1464 to @code{scalar_mode} and all three convert to @code{fixed_size_mode}.
1465 The classes act like @code{machine_mode}s that accept only certain
1469 @file{machmode.h} also defines a template class @code{opt_mode<@var{T}>}
1470 that holds a @code{T} or nothing, where @code{T} can be either
1471 @code{machine_mode} or one of the wrapper classes above. The main
1472 operations on an @code{opt_mode<@var{T}>} @var{x} are as follows:
1475 @item @var{x}.exists ()
1476 Return true if @var{x} holds a mode rather than nothing.
1478 @item @var{x}.exists (&@var{y})
1479 Return true if @var{x} holds a mode rather than nothing, storing the
1480 mode in @var{y} if so. @var{y} must be assignment-compatible with @var{T}.
1482 @item @var{x}.require ()
1483 Assert that @var{x} holds a mode rather than nothing and return that mode.
1485 @item @var{x} = @var{y}
1486 Set @var{x} to @var{y}, where @var{y} is a @var{T} or implicitly converts
1490 The default constructor sets an @code{opt_mode<@var{T}>} to nothing.
1491 There is also a constructor that takes an initial value of type @var{T}.
1493 It is possible to use the @file{is-a.h} accessors on a @code{machine_mode}
1494 or machine mode wrapper @var{x}:
1498 @item is_a <@var{T}> (@var{x})
1499 Return true if @var{x} meets the conditions for wrapper class @var{T}.
1501 @item is_a <@var{T}> (@var{x}, &@var{y})
1502 Return true if @var{x} meets the conditions for wrapper class @var{T},
1503 storing it in @var{y} if so. @var{y} must be assignment-compatible with
1506 @item as_a <@var{T}> (@var{x})
1507 Assert that @var{x} meets the conditions for wrapper class @var{T}
1508 and return it as a @var{T}.
1510 @item dyn_cast <@var{T}> (@var{x})
1511 Return an @code{opt_mode<@var{T}>} that holds @var{x} if @var{x} meets
1512 the conditions for wrapper class @var{T} and that holds nothing otherwise.
1515 The purpose of these wrapper classes is to give stronger static type
1516 checking. For example, if a function takes a @code{scalar_int_mode},
1517 a caller that has a general @code{machine_mode} must either check or
1518 assert that the code is indeed a scalar integer first, using one of
1519 the functions above.
1521 The wrapper classes are normal C++ classes, with user-defined
1522 constructors. Sometimes it is useful to have a POD version of
1523 the same type, particularly if the type appears in a @code{union}.
1524 The template class @code{pod_mode<@var{T}>} provides a POD version
1525 of wrapper class @var{T}. It is assignment-compatible with @var{T}
1526 and implicitly converts to both @code{machine_mode} and @var{T}.
1528 Here are some C macros that relate to machine modes:
1532 @item GET_MODE (@var{x})
1533 Returns the machine mode of the RTX @var{x}.
1536 @item PUT_MODE (@var{x}, @var{newmode})
1537 Alters the machine mode of the RTX @var{x} to be @var{newmode}.
1539 @findex NUM_MACHINE_MODES
1540 @item NUM_MACHINE_MODES
1541 Stands for the number of machine modes available on the target
1542 machine. This is one greater than the largest numeric value of any
1545 @findex GET_MODE_NAME
1546 @item GET_MODE_NAME (@var{m})
1547 Returns the name of mode @var{m} as a string.
1549 @findex GET_MODE_CLASS
1550 @item GET_MODE_CLASS (@var{m})
1551 Returns the mode class of mode @var{m}.
1553 @findex GET_MODE_WIDER_MODE
1554 @item GET_MODE_WIDER_MODE (@var{m})
1555 Returns the next wider natural mode. For example, the expression
1556 @code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}.
1558 @findex GET_MODE_SIZE
1559 @item GET_MODE_SIZE (@var{m})
1560 Returns the size in bytes of a datum of mode @var{m}.
1562 @findex GET_MODE_BITSIZE
1563 @item GET_MODE_BITSIZE (@var{m})
1564 Returns the size in bits of a datum of mode @var{m}.
1566 @findex GET_MODE_IBIT
1567 @item GET_MODE_IBIT (@var{m})
1568 Returns the number of integral bits of a datum of fixed-point mode @var{m}.
1570 @findex GET_MODE_FBIT
1571 @item GET_MODE_FBIT (@var{m})
1572 Returns the number of fractional bits of a datum of fixed-point mode @var{m}.
1574 @findex GET_MODE_MASK
1575 @item GET_MODE_MASK (@var{m})
1576 Returns a bitmask containing 1 for all bits in a word that fit within
1577 mode @var{m}. This macro can only be used for modes whose bitsize is
1578 less than or equal to @code{HOST_BITS_PER_INT}.
1580 @findex GET_MODE_ALIGNMENT
1581 @item GET_MODE_ALIGNMENT (@var{m})
1582 Return the required alignment, in bits, for an object of mode @var{m}.
1584 @findex GET_MODE_UNIT_SIZE
1585 @item GET_MODE_UNIT_SIZE (@var{m})
1586 Returns the size in bytes of the subunits of a datum of mode @var{m}.
1587 This is the same as @code{GET_MODE_SIZE} except in the case of complex
1588 modes. For them, the unit size is the size of the real or imaginary
1591 @findex GET_MODE_NUNITS
1592 @item GET_MODE_NUNITS (@var{m})
1593 Returns the number of units contained in a mode, i.e.,
1594 @code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}.
1596 @findex GET_CLASS_NARROWEST_MODE
1597 @item GET_CLASS_NARROWEST_MODE (@var{c})
1598 Returns the narrowest mode in mode class @var{c}.
1601 The following 3 variables are defined on every target. They can be
1602 used to allocate buffers that are guaranteed to be large enough to
1603 hold any value that can be represented on the target. The first two
1604 can be overridden by defining them in the target's mode.def file,
1605 however, the value must be a constant that can determined very early
1606 in the compilation process. The third symbol cannot be overridden.
1609 @findex BITS_PER_UNIT
1611 The number of bits in an addressable storage unit (byte). If you do
1612 not define this, the default is 8.
1614 @findex MAX_BITSIZE_MODE_ANY_INT
1615 @item MAX_BITSIZE_MODE_ANY_INT
1616 The maximum bitsize of any mode that is used in integer math. This
1617 should be overridden by the target if it uses large integers as
1618 containers for larger vectors but otherwise never uses the contents to
1619 compute integer values.
1621 @findex MAX_BITSIZE_MODE_ANY_MODE
1622 @item MAX_BITSIZE_MODE_ANY_MODE
1623 The bitsize of the largest mode on the target. The default value is
1624 the largest mode size given in the mode definition file, which is
1625 always correct for targets whose modes have a fixed size. Targets
1626 that might increase the size of a mode beyond this default should define
1627 @code{MAX_BITSIZE_MODE_ANY_MODE} to the actual upper limit in
1628 @file{@var{machine}-modes.def}.
1633 The global variables @code{byte_mode} and @code{word_mode} contain modes
1634 whose classes are @code{MODE_INT} and whose bitsizes are either
1635 @code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit
1636 machines, these are @code{QImode} and @code{SImode}, respectively.
1639 @section Constant Expression Types
1640 @cindex RTL constants
1641 @cindex RTL constant expression types
1643 The simplest RTL expressions are those that represent constant values.
1647 @item (const_int @var{i})
1648 This type of expression represents the integer value @var{i}. @var{i}
1649 is customarily accessed with the macro @code{INTVAL} as in
1650 @code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}.
1652 Constants generated for modes with fewer bits than in
1653 @code{HOST_WIDE_INT} must be sign extended to full width (e.g., with
1654 @code{gen_int_mode}). For constants for modes with more bits than in
1655 @code{HOST_WIDE_INT} the implied high order bits of that constant are
1656 copies of the top bit. Note however that values are neither
1657 inherently signed nor inherently unsigned; where necessary, signedness
1658 is determined by the rtl operation instead.
1664 There is only one expression object for the integer value zero; it is
1665 the value of the variable @code{const0_rtx}. Likewise, the only
1666 expression for integer value one is found in @code{const1_rtx}, the only
1667 expression for integer value two is found in @code{const2_rtx}, and the
1668 only expression for integer value negative one is found in
1669 @code{constm1_rtx}. Any attempt to create an expression of code
1670 @code{const_int} and value zero, one, two or negative one will return
1671 @code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or
1672 @code{constm1_rtx} as appropriate.
1674 @findex const_true_rtx
1675 Similarly, there is only one object for the integer whose value is
1676 @code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If
1677 @code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and
1678 @code{const1_rtx} will point to the same object. If
1679 @code{STORE_FLAG_VALUE} is @minus{}1, @code{const_true_rtx} and
1680 @code{constm1_rtx} will point to the same object.
1682 @findex const_double
1683 @item (const_double:@var{m} @var{i0} @var{i1} @dots{})
1684 This represents either a floating-point constant of mode @var{m} or
1685 (on older ports that do not define
1686 @code{TARGET_SUPPORTS_WIDE_INT}) an integer constant too large to fit
1687 into @code{HOST_BITS_PER_WIDE_INT} bits but small enough to fit within
1688 twice that number of bits. In the latter case, @var{m} will be
1689 @code{VOIDmode}. For integral values constants for modes with more
1690 bits than twice the number in @code{HOST_WIDE_INT} the implied high
1691 order bits of that constant are copies of the top bit of
1692 @code{CONST_DOUBLE_HIGH}. Note however that integral values are
1693 neither inherently signed nor inherently unsigned; where necessary,
1694 signedness is determined by the rtl operation instead.
1696 On more modern ports, @code{CONST_DOUBLE} only represents floating
1697 point values. New ports define @code{TARGET_SUPPORTS_WIDE_INT} to
1698 make this designation.
1700 @findex CONST_DOUBLE_LOW
1701 If @var{m} is @code{VOIDmode}, the bits of the value are stored in
1702 @var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro
1703 @code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}.
1705 If the constant is floating point (regardless of its precision), then
1706 the number of integers used to store the value depends on the size of
1707 @code{REAL_VALUE_TYPE} (@pxref{Floating Point}). The integers
1708 represent a floating point number, but not precisely in the target
1709 machine's or host machine's floating point format. To convert them to
1710 the precise bit pattern used by the target machine, use the macro
1711 @code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}).
1713 @findex CONST_WIDE_INT
1714 @item (const_wide_int:@var{m} @var{nunits} @var{elt0} @dots{})
1715 This contains an array of @code{HOST_WIDE_INT}s that is large enough
1716 to hold any constant that can be represented on the target. This form
1717 of rtl is only used on targets that define
1718 @code{TARGET_SUPPORTS_WIDE_INT} to be nonzero and then
1719 @code{CONST_DOUBLE}s are only used to hold floating-point values. If
1720 the target leaves @code{TARGET_SUPPORTS_WIDE_INT} defined as 0,
1721 @code{CONST_WIDE_INT}s are not used and @code{CONST_DOUBLE}s are as
1724 The values are stored in a compressed format. The higher-order
1725 0s or -1s are not represented if they are just the logical sign
1726 extension of the number that is represented.
1728 @findex CONST_WIDE_INT_VEC
1729 @item CONST_WIDE_INT_VEC (@var{code})
1730 Returns the entire array of @code{HOST_WIDE_INT}s that are used to
1731 store the value. This macro should be rarely used.
1733 @findex CONST_WIDE_INT_NUNITS
1734 @item CONST_WIDE_INT_NUNITS (@var{code})
1735 The number of @code{HOST_WIDE_INT}s used to represent the number.
1736 Note that this generally is smaller than the number of
1737 @code{HOST_WIDE_INT}s implied by the mode size.
1739 @findex CONST_WIDE_INT_ELT
1740 @item CONST_WIDE_INT_NUNITS (@var{code},@var{i})
1741 Returns the @code{i}th element of the array. Element 0 is contains
1742 the low order bits of the constant.
1745 @item (const_fixed:@var{m} @dots{})
1746 Represents a fixed-point constant of mode @var{m}.
1747 The operand is a data structure of type @code{struct fixed_value} and
1748 is accessed with the macro @code{CONST_FIXED_VALUE}. The high part of
1749 data is accessed with @code{CONST_FIXED_VALUE_HIGH}; the low part is
1750 accessed with @code{CONST_FIXED_VALUE_LOW}.
1752 @findex const_poly_int
1753 @item (const_poly_int:@var{m} [@var{c0} @var{c1} @dots{}])
1754 Represents a @code{poly_int}-style polynomial integer with coefficients
1755 @var{c0}, @var{c1}, @dots{}. The coefficients are @code{wide_int}-based
1756 integers rather than rtxes. @code{CONST_POLY_INT_COEFFS} gives the
1757 values of individual coefficients (which is mostly only useful in
1758 low-level routines) and @code{const_poly_int_value} gives the full
1759 @code{poly_int} value.
1761 @findex const_vector
1762 @item (const_vector:@var{m} [@var{x0} @var{x1} @dots{}])
1763 Represents a vector constant. The values in square brackets are
1764 elements of the vector, which are always @code{const_int},
1765 @code{const_wide_int}, @code{const_double} or @code{const_fixed}
1768 Each vector constant @var{v} is treated as a specific instance of an
1769 arbitrary-length sequence that itself contains
1770 @samp{CONST_VECTOR_NPATTERNS (@var{v})} interleaved patterns. Each
1771 pattern has the form:
1774 @{ @var{base0}, @var{base1}, @var{base1} + @var{step}, @var{base1} + @var{step} * 2, @dots{} @}
1777 The first three elements in each pattern are enough to determine the
1778 values of the other elements. However, if all @var{step}s are zero,
1779 only the first two elements are needed. If in addition each @var{base1}
1780 is equal to the corresponding @var{base0}, only the first element in
1781 each pattern is needed. The number of determining elements per pattern
1782 is given by @samp{CONST_VECTOR_NELTS_PER_PATTERN (@var{v})}.
1784 For example, the constant:
1787 @{ 0, 1, 2, 6, 3, 8, 4, 10, 5, 12, 6, 14, 7, 16, 8, 18 @}
1790 is interpreted as an interleaving of the sequences:
1793 @{ 0, 2, 3, 4, 5, 6, 7, 8 @}
1794 @{ 1, 6, 8, 10, 12, 14, 16, 18 @}
1797 where the sequences are represented by the following patterns:
1800 @var{base0} == 0, @var{base1} == 2, @var{step} == 1
1801 @var{base0} == 1, @var{base1} == 6, @var{step} == 2
1807 CONST_VECTOR_NPATTERNS (@var{v}) == 2
1808 CONST_VECTOR_NELTS_PER_PATTERN (@var{v}) == 3
1811 Thus the first 6 elements (@samp{@{ 0, 1, 2, 6, 3, 8 @}}) are enough
1812 to determine the whole sequence; we refer to them as the ``encoded''
1813 elements. They are the only elements present in the square brackets
1814 for variable-length @code{const_vector}s (i.e. for
1815 @code{const_vector}s whose mode @var{m} has a variable number of
1816 elements). However, as a convenience to code that needs to handle
1817 both @code{const_vector}s and @code{parallel}s, all elements are
1818 present in the square brackets for fixed-length @code{const_vector}s;
1819 the encoding scheme simply reduces the amount of work involved in
1820 processing constants that follow a regular pattern.
1822 Sometimes this scheme can create two possible encodings of the same
1823 vector. For example @{ 0, 1 @} could be seen as two patterns with
1824 one element each or one pattern with two elements (@var{base0} and
1825 @var{base1}). The canonical encoding is always the one with the
1826 fewest patterns or (if both encodings have the same number of
1827 petterns) the one with the fewest encoded elements.
1829 @samp{const_vector_encoding_nelts (@var{v})} gives the total number of
1830 encoded elements in @var{v}, which is 6 in the example above.
1831 @code{CONST_VECTOR_ENCODED_ELT (@var{v}, @var{i})} accesses the value
1832 of encoded element @var{i}.
1834 @samp{CONST_VECTOR_DUPLICATE_P (@var{v})} is true if @var{v} simply contains
1835 repeated instances of @samp{CONST_VECTOR_NPATTERNS (@var{v})} values. This is
1836 a shorthand for testing @samp{CONST_VECTOR_NELTS_PER_PATTERN (@var{v}) == 1}.
1838 @samp{CONST_VECTOR_STEPPED_P (@var{v})} is true if at least one
1839 pattern in @var{v} has a nonzero step. This is a shorthand for
1840 testing @samp{CONST_VECTOR_NELTS_PER_PATTERN (@var{v}) == 3}.
1842 @code{CONST_VECTOR_NUNITS (@var{v})} gives the total number of elements
1843 in @var{v}; it is a shorthand for getting the number of units in
1844 @samp{GET_MODE (@var{v})}.
1846 The utility function @code{const_vector_elt} gives the value of an
1847 arbitrary element as an @code{rtx}. @code{const_vector_int_elt} gives
1848 the same value as a @code{wide_int}.
1850 @findex const_string
1851 @item (const_string @var{str})
1852 Represents a constant string with value @var{str}. Currently this is
1853 used only for insn attributes (@pxref{Insn Attributes}) since constant
1854 strings in C are placed in memory.
1857 @item (symbol_ref:@var{mode} @var{symbol})
1858 Represents the value of an assembler label for data. @var{symbol} is
1859 a string that describes the name of the assembler label. If it starts
1860 with a @samp{*}, the label is the rest of @var{symbol} not including
1861 the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed
1864 The @code{symbol_ref} contains a mode, which is usually @code{Pmode}.
1865 Usually that is the only mode for which a symbol is directly valid.
1868 @item (label_ref:@var{mode} @var{label})
1869 Represents the value of an assembler label for code. It contains one
1870 operand, an expression, which must be a @code{code_label} or a @code{note}
1871 of type @code{NOTE_INSN_DELETED_LABEL} that appears in the instruction
1872 sequence to identify the place where the label should go.
1874 The reason for using a distinct expression type for code label
1875 references is so that jump optimization can distinguish them.
1877 The @code{label_ref} contains a mode, which is usually @code{Pmode}.
1878 Usually that is the only mode for which a label is directly valid.
1881 @item (const:@var{m} @var{exp})
1882 Represents a constant that is the result of an assembly-time
1883 arithmetic computation. The operand, @var{exp}, contains only
1884 @code{const_int}, @code{symbol_ref}, @code{label_ref} or @code{unspec}
1885 expressions, combined with @code{plus} and @code{minus}. Any such
1886 @code{unspec}s are target-specific and typically represent some form
1887 of relocation operator. @var{m} should be a valid address mode.
1890 @item (high:@var{m} @var{exp})
1891 Represents the high-order bits of @var{exp}, usually a
1892 @code{symbol_ref}. The number of bits is machine-dependent and is
1893 normally the number of bits specified in an instruction that initializes
1894 the high order bits of a register. It is used with @code{lo_sum} to
1895 represent the typical two-instruction sequence used in RISC machines to
1896 reference a global memory location.
1898 @var{m} should be @code{Pmode}.
1904 The macro @code{CONST0_RTX (@var{mode})} refers to an expression with
1905 value 0 in mode @var{mode}. If mode @var{mode} is of mode class
1906 @code{MODE_INT}, it returns @code{const0_rtx}. If mode @var{mode} is of
1907 mode class @code{MODE_FLOAT}, it returns a @code{CONST_DOUBLE}
1908 expression in mode @var{mode}. Otherwise, it returns a
1909 @code{CONST_VECTOR} expression in mode @var{mode}. Similarly, the macro
1910 @code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in
1911 mode @var{mode} and similarly for @code{CONST2_RTX}. The
1912 @code{CONST1_RTX} and @code{CONST2_RTX} macros are undefined
1915 @node Regs and Memory
1916 @section Registers and Memory
1917 @cindex RTL register expressions
1918 @cindex RTL memory expressions
1920 Here are the RTL expression types for describing access to machine
1921 registers and to main memory.
1925 @cindex hard registers
1926 @cindex pseudo registers
1927 @item (reg:@var{m} @var{n})
1928 For small values of the integer @var{n} (those that are less than
1929 @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
1930 register number @var{n}: a @dfn{hard register}. For larger values of
1931 @var{n}, it stands for a temporary value or @dfn{pseudo register}.
1932 The compiler's strategy is to generate code assuming an unlimited
1933 number of such pseudo registers, and later convert them into hard
1934 registers or into memory references.
1936 @var{m} is the machine mode of the reference. It is necessary because
1937 machines can generally refer to each register in more than one mode.
1938 For example, a register may contain a full word but there may be
1939 instructions to refer to it as a half word or as a single byte, as
1940 well as instructions to refer to it as a floating point number of
1943 Even for a register that the machine can access in only one mode,
1944 the mode must always be specified.
1946 The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
1947 description, since the number of hard registers on the machine is an
1948 invariant characteristic of the machine. Note, however, that not
1949 all of the machine registers must be general registers. All the
1950 machine registers that can be used for storage of data are given
1951 hard register numbers, even those that can be used only in certain
1952 instructions or can hold only certain types of data.
1954 A hard register may be accessed in various modes throughout one
1955 function, but each pseudo register is given a natural mode
1956 and is accessed only in that mode. When it is necessary to describe
1957 an access to a pseudo register using a nonnatural mode, a @code{subreg}
1960 A @code{reg} expression with a machine mode that specifies more than
1961 one word of data may actually stand for several consecutive registers.
1962 If in addition the register number specifies a hardware register, then
1963 it actually represents several consecutive hardware registers starting
1964 with the specified one.
1966 Each pseudo register number used in a function's RTL code is
1967 represented by a unique @code{reg} expression.
1969 @findex FIRST_VIRTUAL_REGISTER
1970 @findex LAST_VIRTUAL_REGISTER
1971 Some pseudo register numbers, those within the range of
1972 @code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only
1973 appear during the RTL generation phase and are eliminated before the
1974 optimization phases. These represent locations in the stack frame that
1975 cannot be determined until RTL generation for the function has been
1976 completed. The following virtual register numbers are defined:
1979 @findex VIRTUAL_INCOMING_ARGS_REGNUM
1980 @item VIRTUAL_INCOMING_ARGS_REGNUM
1981 This points to the first word of the incoming arguments passed on the
1982 stack. Normally these arguments are placed there by the caller, but the
1983 callee may have pushed some arguments that were previously passed in
1986 @cindex @code{FIRST_PARM_OFFSET} and virtual registers
1987 @cindex @code{ARG_POINTER_REGNUM} and virtual registers
1988 When RTL generation is complete, this virtual register is replaced
1989 by the sum of the register given by @code{ARG_POINTER_REGNUM} and the
1990 value of @code{FIRST_PARM_OFFSET}.
1992 @findex VIRTUAL_STACK_VARS_REGNUM
1993 @cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers
1994 @item VIRTUAL_STACK_VARS_REGNUM
1995 If @code{FRAME_GROWS_DOWNWARD} is defined to a nonzero value, this points
1996 to immediately above the first variable on the stack. Otherwise, it points
1997 to the first variable on the stack.
1999 @cindex @code{TARGET_STARTING_FRAME_OFFSET} and virtual registers
2000 @cindex @code{FRAME_POINTER_REGNUM} and virtual registers
2001 @code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the
2002 register given by @code{FRAME_POINTER_REGNUM} and the value
2003 @code{TARGET_STARTING_FRAME_OFFSET}.
2005 @findex VIRTUAL_STACK_DYNAMIC_REGNUM
2006 @item VIRTUAL_STACK_DYNAMIC_REGNUM
2007 This points to the location of dynamically allocated memory on the stack
2008 immediately after the stack pointer has been adjusted by the amount of
2011 @cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers
2012 @cindex @code{STACK_POINTER_REGNUM} and virtual registers
2013 This virtual register is replaced by the sum of the register given by
2014 @code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}.
2016 @findex VIRTUAL_OUTGOING_ARGS_REGNUM
2017 @item VIRTUAL_OUTGOING_ARGS_REGNUM
2018 This points to the location in the stack at which outgoing arguments
2019 should be written when the stack is pre-pushed (arguments pushed using
2020 push insns should always use @code{STACK_POINTER_REGNUM}).
2022 @cindex @code{STACK_POINTER_OFFSET} and virtual registers
2023 This virtual register is replaced by the sum of the register given by
2024 @code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}.
2028 @item (subreg:@var{m1} @var{reg:m2} @var{bytenum})
2030 @code{subreg} expressions are used to refer to a register in a machine
2031 mode other than its natural one, or to refer to one register of
2032 a multi-part @code{reg} that actually refers to several registers.
2034 Each pseudo register has a natural mode. If it is necessary to
2035 operate on it in a different mode, the register must be
2036 enclosed in a @code{subreg}.
2038 There are currently three supported types for the first operand of a
2041 @item pseudo registers
2042 This is the most common case. Most @code{subreg}s have pseudo
2043 @code{reg}s as their first operand.
2046 @code{subreg}s of @code{mem} were common in earlier versions of GCC and
2047 are still supported. During the reload pass these are replaced by plain
2048 @code{mem}s. On machines that do not do instruction scheduling, use of
2049 @code{subreg}s of @code{mem} are still used, but this is no longer
2050 recommended. Such @code{subreg}s are considered to be
2051 @code{register_operand}s rather than @code{memory_operand}s before and
2052 during reload. Because of this, the scheduling passes cannot properly
2053 schedule instructions with @code{subreg}s of @code{mem}, so for machines
2054 that do scheduling, @code{subreg}s of @code{mem} should never be used.
2055 To support this, the combine and recog passes have explicit code to
2056 inhibit the creation of @code{subreg}s of @code{mem} when
2057 @code{INSN_SCHEDULING} is defined.
2059 The use of @code{subreg}s of @code{mem} after the reload pass is an area
2060 that is not well understood and should be avoided. There is still some
2061 code in the compiler to support this, but this code has possibly rotted.
2062 This use of @code{subreg}s is discouraged and will most likely not be
2063 supported in the future.
2065 @item hard registers
2066 It is seldom necessary to wrap hard registers in @code{subreg}s; such
2067 registers would normally reduce to a single @code{reg} rtx. This use of
2068 @code{subreg}s is discouraged and may not be supported in the future.
2072 @code{subreg}s of @code{subreg}s are not supported. Using
2073 @code{simplify_gen_subreg} is the recommended way to avoid this problem.
2075 @code{subreg}s come in two distinct flavors, each having its own
2079 @item Paradoxical subregs
2080 When @var{m1} is strictly wider than @var{m2}, the @code{subreg}
2081 expression is called @dfn{paradoxical}. The canonical test for this
2082 class of @code{subreg} is:
2085 paradoxical_subreg_p (@var{m1}, @var{m2})
2088 Paradoxical @code{subreg}s can be used as both lvalues and rvalues.
2089 When used as an lvalue, the low-order bits of the source value
2090 are stored in @var{reg} and the high-order bits are discarded.
2091 When used as an rvalue, the low-order bits of the @code{subreg} are
2092 taken from @var{reg} while the high-order bits may or may not be
2095 The high-order bits of rvalues are defined in the following circumstances:
2098 @item @code{subreg}s of @code{mem}
2099 When @var{m2} is smaller than a word, the macro @code{LOAD_EXTEND_OP},
2100 can control how the high-order bits are defined.
2102 @item @code{subreg} of @code{reg}s
2103 The upper bits are defined when @code{SUBREG_PROMOTED_VAR_P} is true.
2104 @code{SUBREG_PROMOTED_UNSIGNED_P} describes what the upper bits hold.
2105 Such subregs usually represent local variables, register variables
2106 and parameter pseudo variables that have been promoted to a wider mode.
2110 @var{bytenum} is always zero for a paradoxical @code{subreg}, even on
2113 For example, the paradoxical @code{subreg}:
2116 (set (subreg:SI (reg:HI @var{x}) 0) @var{y})
2119 stores the lower 2 bytes of @var{y} in @var{x} and discards the upper
2120 2 bytes. A subsequent:
2123 (set @var{z} (subreg:SI (reg:HI @var{x}) 0))
2126 would set the lower two bytes of @var{z} to @var{y} and set the upper
2127 two bytes to an unknown value assuming @code{SUBREG_PROMOTED_VAR_P} is
2130 @item Normal subregs
2131 When @var{m1} is at least as narrow as @var{m2} the @code{subreg}
2132 expression is called @dfn{normal}.
2134 @findex REGMODE_NATURAL_SIZE
2135 Normal @code{subreg}s restrict consideration to certain bits of
2136 @var{reg}. For this purpose, @var{reg} is divided into
2137 individually-addressable blocks in which each block has:
2140 REGMODE_NATURAL_SIZE (@var{m2})
2143 bytes. Usually the value is @code{UNITS_PER_WORD}; that is,
2144 most targets usually treat each word of a register as being
2145 independently addressable.
2147 There are two types of normal @code{subreg}. If @var{m1} is known
2148 to be no bigger than a block, the @code{subreg} refers to the
2149 least-significant part (or @dfn{lowpart}) of one block of @var{reg}.
2150 If @var{m1} is known to be larger than a block, the @code{subreg} refers
2151 to two or more complete blocks.
2153 When used as an lvalue, @code{subreg} is a block-based accessor.
2154 Storing to a @code{subreg} modifies all the blocks of @var{reg} that
2155 overlap the @code{subreg}, but it leaves the other blocks of @var{reg}
2158 When storing to a normal @code{subreg} that is smaller than a block,
2159 the other bits of the referenced block are usually left in an undefined
2160 state. This laxity makes it easier to generate efficient code for
2161 such instructions. To represent an instruction that preserves all the
2162 bits outside of those in the @code{subreg}, use @code{strict_low_part}
2163 or @code{zero_extract} around the @code{subreg}.
2165 @var{bytenum} must identify the offset of the first byte of the
2166 @code{subreg} from the start of @var{reg}, assuming that @var{reg} is
2167 laid out in memory order. The memory order of bytes is defined by
2168 two target macros, @code{WORDS_BIG_ENDIAN} and @code{BYTES_BIG_ENDIAN}:
2172 @cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
2173 @code{WORDS_BIG_ENDIAN}, if set to 1, says that byte number zero is
2174 part of the most significant word; otherwise, it is part of the least
2178 @cindex @code{BYTES_BIG_ENDIAN}, effect on @code{subreg}
2179 @code{BYTES_BIG_ENDIAN}, if set to 1, says that byte number zero is
2180 the most significant byte within a word; otherwise, it is the least
2181 significant byte within a word.
2184 @cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg}
2185 On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with
2186 @code{WORDS_BIG_ENDIAN}. However, most parts of the compiler treat
2187 floating point values as if they had the same endianness as integer
2188 values. This works because they handle them solely as a collection of
2189 integer values, with no particular numerical value. Only real.c and
2190 the runtime libraries care about @code{FLOAT_WORDS_BIG_ENDIAN}.
2195 (subreg:HI (reg:SI @var{x}) 2)
2198 on a @code{BYTES_BIG_ENDIAN}, @samp{UNITS_PER_WORD == 4} target is the same as
2201 (subreg:HI (reg:SI @var{x}) 0)
2204 on a little-endian, @samp{UNITS_PER_WORD == 4} target. Both
2205 @code{subreg}s access the lower two bytes of register @var{x}.
2207 Note that the byte offset is a polynomial integer; it may not be a
2208 compile-time constant on targets with variable-sized modes. However,
2209 the restrictions above mean that there are only a certain set of
2210 acceptable offsets for a given combination of @var{m1} and @var{m2}.
2211 The compiler can always tell which blocks a valid subreg occupies, and
2212 whether the subreg is a lowpart of a block.
2216 A @code{MODE_PARTIAL_INT} mode behaves as if it were as wide as the
2217 corresponding @code{MODE_INT} mode, except that it has an unknown
2218 number of undefined bits. For example:
2221 (subreg:PSI (reg:SI 0) 0)
2224 @findex REGMODE_NATURAL_SIZE
2225 accesses the whole of @samp{(reg:SI 0)}, but the exact relationship
2226 between the @code{PSImode} value and the @code{SImode} value is not
2227 defined. If we assume @samp{REGMODE_NATURAL_SIZE (DImode) <= 4},
2228 then the following two @code{subreg}s:
2231 (subreg:PSI (reg:DI 0) 0)
2232 (subreg:PSI (reg:DI 0) 4)
2235 represent independent 4-byte accesses to the two halves of
2236 @samp{(reg:DI 0)}. Both @code{subreg}s have an unknown number
2239 If @samp{REGMODE_NATURAL_SIZE (PSImode) <= 2} then these two @code{subreg}s:
2242 (subreg:HI (reg:PSI 0) 0)
2243 (subreg:HI (reg:PSI 0) 2)
2246 represent independent 2-byte accesses that together span the whole
2247 of @samp{(reg:PSI 0)}. Storing to the first @code{subreg} does not
2248 affect the value of the second, and vice versa. @samp{(reg:PSI 0)}
2249 has an unknown number of undefined bits, so the assignment:
2252 (set (subreg:HI (reg:PSI 0) 0) (reg:HI 4))
2255 does not guarantee that @samp{(subreg:HI (reg:PSI 0) 0)} has the
2256 value @samp{(reg:HI 4)}.
2258 @cindex @code{TARGET_CAN_CHANGE_MODE_CLASS} and subreg semantics
2259 The rules above apply to both pseudo @var{reg}s and hard @var{reg}s.
2260 If the semantics are not correct for particular combinations of
2261 @var{m1}, @var{m2} and hard @var{reg}, the target-specific code
2262 must ensure that those combinations are never used. For example:
2265 TARGET_CAN_CHANGE_MODE_CLASS (@var{m2}, @var{m1}, @var{class})
2268 must be false for every class @var{class} that includes @var{reg}.
2270 GCC must be able to determine at compile time whether a subreg is
2271 paradoxical, whether it occupies a whole number of blocks, or whether
2272 it is a lowpart of a block. This means that certain combinations of
2273 variable-sized mode are not permitted. For example, if @var{m2}
2274 holds @var{n} @code{SI} values, where @var{n} is greater than zero,
2275 it is not possible to form a @code{DI} @code{subreg} of it; such a
2276 @code{subreg} would be paradoxical when @var{n} is 1 but not when
2277 @var{n} is greater than 1.
2281 The first operand of a @code{subreg} expression is customarily accessed
2282 with the @code{SUBREG_REG} macro and the second operand is customarily
2283 accessed with the @code{SUBREG_BYTE} macro.
2285 It has been several years since a platform in which
2286 @code{BYTES_BIG_ENDIAN} not equal to @code{WORDS_BIG_ENDIAN} has
2287 been tested. Anyone wishing to support such a platform in the future
2288 may be confronted with code rot.
2291 @cindex scratch operands
2292 @item (scratch:@var{m})
2293 This represents a scratch register that will be required for the
2294 execution of a single instruction and not used subsequently. It is
2295 converted into a @code{reg} by either the local register allocator or
2298 @code{scratch} is usually present inside a @code{clobber} operation
2299 (@pxref{Side Effects}).
2302 @cindex condition code register
2304 This refers to the machine's condition code register. It has no
2305 operands and may not have a machine mode. There are two ways to use it:
2309 To stand for a complete set of condition code flags. This is best on
2310 most machines, where each comparison sets the entire series of flags.
2312 With this technique, @code{(cc0)} may be validly used in only two
2313 contexts: as the destination of an assignment (in test and compare
2314 instructions) and in comparison operators comparing against zero
2315 (@code{const_int} with value zero; that is to say, @code{const0_rtx}).
2318 To stand for a single flag that is the result of a single condition.
2319 This is useful on machines that have only a single flag bit, and in
2320 which comparison instructions must specify the condition to test.
2322 With this technique, @code{(cc0)} may be validly used in only two
2323 contexts: as the destination of an assignment (in test and compare
2324 instructions) where the source is a comparison operator, and as the
2325 first operand of @code{if_then_else} (in a conditional branch).
2329 There is only one expression object of code @code{cc0}; it is the
2330 value of the variable @code{cc0_rtx}. Any attempt to create an
2331 expression of code @code{cc0} will return @code{cc0_rtx}.
2333 Instructions can set the condition code implicitly. On many machines,
2334 nearly all instructions set the condition code based on the value that
2335 they compute or store. It is not necessary to record these actions
2336 explicitly in the RTL because the machine description includes a
2337 prescription for recognizing the instructions that do so (by means of
2338 the macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only
2339 instructions whose sole purpose is to set the condition code, and
2340 instructions that use the condition code, need mention @code{(cc0)}.
2342 On some machines, the condition code register is given a register number
2343 and a @code{reg} is used instead of @code{(cc0)}. This is usually the
2344 preferable approach if only a small subset of instructions modify the
2345 condition code. Other machines store condition codes in general
2346 registers; in such cases a pseudo register should be used.
2348 Some machines, such as the SPARC and RS/6000, have two sets of
2349 arithmetic instructions, one that sets and one that does not set the
2350 condition code. This is best handled by normally generating the
2351 instruction that does not set the condition code, and making a pattern
2352 that both performs the arithmetic and sets the condition code register
2353 (which would not be @code{(cc0)} in this case). For examples, search
2354 for @samp{addcc} and @samp{andcc} in @file{sparc.md}.
2358 @cindex program counter
2359 This represents the machine's program counter. It has no operands and
2360 may not have a machine mode. @code{(pc)} may be validly used only in
2361 certain specific contexts in jump instructions.
2364 There is only one expression object of code @code{pc}; it is the value
2365 of the variable @code{pc_rtx}. Any attempt to create an expression of
2366 code @code{pc} will return @code{pc_rtx}.
2368 All instructions that do not jump alter the program counter implicitly
2369 by incrementing it, but there is no need to mention this in the RTL@.
2372 @item (mem:@var{m} @var{addr} @var{alias})
2373 This RTX represents a reference to main memory at an address
2374 represented by the expression @var{addr}. @var{m} specifies how large
2375 a unit of memory is accessed. @var{alias} specifies an alias set for the
2376 reference. In general two items are in different alias sets if they cannot
2377 reference the same memory address.
2379 The construct @code{(mem:BLK (scratch))} is considered to alias all
2380 other memories. Thus it may be used as a memory barrier in epilogue
2381 stack deallocation patterns.
2384 @item (concat@var{m} @var{rtx} @var{rtx})
2385 This RTX represents the concatenation of two other RTXs. This is used
2386 for complex values. It should only appear in the RTL attached to
2387 declarations and during RTL generation. It should not appear in the
2388 ordinary insn chain.
2391 @item (concatn@var{m} [@var{rtx} @dots{}])
2392 This RTX represents the concatenation of all the @var{rtx} to make a
2393 single value. Like @code{concat}, this should only appear in
2394 declarations, and not in the insn chain.
2398 @section RTL Expressions for Arithmetic
2399 @cindex arithmetic, in RTL
2400 @cindex math, in RTL
2401 @cindex RTL expressions for arithmetic
2403 Unless otherwise specified, all the operands of arithmetic expressions
2404 must be valid for mode @var{m}. An operand is valid for mode @var{m}
2405 if it has mode @var{m}, or if it is a @code{const_int} or
2406 @code{const_double} and @var{m} is a mode of class @code{MODE_INT}.
2408 For commutative binary operations, constants should be placed in the
2416 @cindex RTL addition
2417 @cindex RTL addition with signed saturation
2418 @cindex RTL addition with unsigned saturation
2419 @item (plus:@var{m} @var{x} @var{y})
2420 @itemx (ss_plus:@var{m} @var{x} @var{y})
2421 @itemx (us_plus:@var{m} @var{x} @var{y})
2423 These three expressions all represent the sum of the values
2424 represented by @var{x} and @var{y} carried out in machine mode
2425 @var{m}. They differ in their behavior on overflow of integer modes.
2426 @code{plus} wraps round modulo the width of @var{m}; @code{ss_plus}
2427 saturates at the maximum signed value representable in @var{m};
2428 @code{us_plus} saturates at the maximum unsigned value.
2430 @c ??? What happens on overflow of floating point modes?
2433 @item (lo_sum:@var{m} @var{x} @var{y})
2435 This expression represents the sum of @var{x} and the low-order bits
2436 of @var{y}. It is used with @code{high} (@pxref{Constants}) to
2437 represent the typical two-instruction sequence used in RISC machines
2438 to reference a global memory location.
2440 The number of low order bits is machine-dependent but is
2441 normally the number of bits in a @code{Pmode} item minus the number of
2442 bits set by @code{high}.
2444 @var{m} should be @code{Pmode}.
2449 @cindex RTL difference
2450 @cindex RTL subtraction
2451 @cindex RTL subtraction with signed saturation
2452 @cindex RTL subtraction with unsigned saturation
2453 @item (minus:@var{m} @var{x} @var{y})
2454 @itemx (ss_minus:@var{m} @var{x} @var{y})
2455 @itemx (us_minus:@var{m} @var{x} @var{y})
2457 These three expressions represent the result of subtracting @var{y}
2458 from @var{x}, carried out in mode @var{M}. Behavior on overflow is
2459 the same as for the three variants of @code{plus} (see above).
2462 @cindex RTL comparison
2463 @item (compare:@var{m} @var{x} @var{y})
2464 Represents the result of subtracting @var{y} from @var{x} for purposes
2465 of comparison. The result is computed without overflow, as if with
2468 Of course, machines cannot really subtract with infinite precision.
2469 However, they can pretend to do so when only the sign of the result will
2470 be used, which is the case when the result is stored in the condition
2471 code. And that is the @emph{only} way this kind of expression may
2472 validly be used: as a value to be stored in the condition codes, either
2473 @code{(cc0)} or a register. @xref{Comparisons}.
2475 The mode @var{m} is not related to the modes of @var{x} and @var{y}, but
2476 instead is the mode of the condition code value. If @code{(cc0)} is
2477 used, it is @code{VOIDmode}. Otherwise it is some mode in class
2478 @code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}. If @var{m}
2479 is @code{VOIDmode} or @code{CCmode}, the operation returns sufficient
2480 information (in an unspecified format) so that any comparison operator
2481 can be applied to the result of the @code{COMPARE} operation. For other
2482 modes in class @code{MODE_CC}, the operation only returns a subset of
2485 Normally, @var{x} and @var{y} must have the same mode. Otherwise,
2486 @code{compare} is valid only if the mode of @var{x} is in class
2487 @code{MODE_INT} and @var{y} is a @code{const_int} or
2488 @code{const_double} with mode @code{VOIDmode}. The mode of @var{x}
2489 determines what mode the comparison is to be done in; thus it must not
2492 If one of the operands is a constant, it should be placed in the
2493 second operand and the comparison code adjusted as appropriate.
2495 A @code{compare} specifying two @code{VOIDmode} constants is not valid
2496 since there is no way to know in what mode the comparison is to be
2497 performed; the comparison must either be folded during the compilation
2498 or the first operand must be loaded into a register while its mode is
2505 @cindex negation with signed saturation
2506 @cindex negation with unsigned saturation
2507 @item (neg:@var{m} @var{x})
2508 @itemx (ss_neg:@var{m} @var{x})
2509 @itemx (us_neg:@var{m} @var{x})
2510 These two expressions represent the negation (subtraction from zero) of
2511 the value represented by @var{x}, carried out in mode @var{m}. They
2512 differ in the behavior on overflow of integer modes. In the case of
2513 @code{neg}, the negation of the operand may be a number not representable
2514 in mode @var{m}, in which case it is truncated to @var{m}. @code{ss_neg}
2515 and @code{us_neg} ensure that an out-of-bounds result saturates to the
2516 maximum or minimum signed or unsigned value.
2521 @cindex multiplication
2523 @cindex multiplication with signed saturation
2524 @cindex multiplication with unsigned saturation
2525 @item (mult:@var{m} @var{x} @var{y})
2526 @itemx (ss_mult:@var{m} @var{x} @var{y})
2527 @itemx (us_mult:@var{m} @var{x} @var{y})
2528 Represents the signed product of the values represented by @var{x} and
2529 @var{y} carried out in machine mode @var{m}.
2530 @code{ss_mult} and @code{us_mult} ensure that an out-of-bounds result
2531 saturates to the maximum or minimum signed or unsigned value.
2533 Some machines support a multiplication that generates a product wider
2534 than the operands. Write the pattern for this as
2537 (mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
2540 where @var{m} is wider than the modes of @var{x} and @var{y}, which need
2543 For unsigned widening multiplication, use the same idiom, but with
2544 @code{zero_extend} instead of @code{sign_extend}.
2547 @item (fma:@var{m} @var{x} @var{y} @var{z})
2548 Represents the @code{fma}, @code{fmaf}, and @code{fmal} builtin
2549 functions, which compute @samp{@var{x} * @var{y} + @var{z}}
2550 without doing an intermediate rounding step.
2555 @cindex signed division
2556 @cindex signed division with signed saturation
2558 @item (div:@var{m} @var{x} @var{y})
2559 @itemx (ss_div:@var{m} @var{x} @var{y})
2560 Represents the quotient in signed division of @var{x} by @var{y},
2561 carried out in machine mode @var{m}. If @var{m} is a floating point
2562 mode, it represents the exact quotient; otherwise, the integerized
2564 @code{ss_div} ensures that an out-of-bounds result saturates to the maximum
2565 or minimum signed value.
2567 Some machines have division instructions in which the operands and
2568 quotient widths are not all the same; you should represent
2569 such instructions using @code{truncate} and @code{sign_extend} as in,
2572 (truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
2576 @cindex unsigned division
2577 @cindex unsigned division with unsigned saturation
2579 @item (udiv:@var{m} @var{x} @var{y})
2580 @itemx (us_div:@var{m} @var{x} @var{y})
2581 Like @code{div} but represents unsigned division.
2582 @code{us_div} ensures that an out-of-bounds result saturates to the maximum
2583 or minimum unsigned value.
2589 @item (mod:@var{m} @var{x} @var{y})
2590 @itemx (umod:@var{m} @var{x} @var{y})
2591 Like @code{div} and @code{udiv} but represent the remainder instead of
2596 @cindex signed minimum
2597 @cindex signed maximum
2598 @item (smin:@var{m} @var{x} @var{y})
2599 @itemx (smax:@var{m} @var{x} @var{y})
2600 Represents the smaller (for @code{smin}) or larger (for @code{smax}) of
2601 @var{x} and @var{y}, interpreted as signed values in mode @var{m}.
2602 When used with floating point, if both operands are zeros, or if either
2603 operand is @code{NaN}, then it is unspecified which of the two operands
2604 is returned as the result.
2608 @cindex unsigned minimum and maximum
2609 @item (umin:@var{m} @var{x} @var{y})
2610 @itemx (umax:@var{m} @var{x} @var{y})
2611 Like @code{smin} and @code{smax}, but the values are interpreted as unsigned
2615 @cindex complement, bitwise
2616 @cindex bitwise complement
2617 @item (not:@var{m} @var{x})
2618 Represents the bitwise complement of the value represented by @var{x},
2619 carried out in mode @var{m}, which must be a fixed-point machine mode.
2622 @cindex logical-and, bitwise
2623 @cindex bitwise logical-and
2624 @item (and:@var{m} @var{x} @var{y})
2625 Represents the bitwise logical-and of the values represented by
2626 @var{x} and @var{y}, carried out in machine mode @var{m}, which must be
2627 a fixed-point machine mode.
2630 @cindex inclusive-or, bitwise
2631 @cindex bitwise inclusive-or
2632 @item (ior:@var{m} @var{x} @var{y})
2633 Represents the bitwise inclusive-or of the values represented by @var{x}
2634 and @var{y}, carried out in machine mode @var{m}, which must be a
2638 @cindex exclusive-or, bitwise
2639 @cindex bitwise exclusive-or
2640 @item (xor:@var{m} @var{x} @var{y})
2641 Represents the bitwise exclusive-or of the values represented by @var{x}
2642 and @var{y}, carried out in machine mode @var{m}, which must be a
2650 @cindex arithmetic shift
2651 @cindex arithmetic shift with signed saturation
2652 @cindex arithmetic shift with unsigned saturation
2653 @item (ashift:@var{m} @var{x} @var{c})
2654 @itemx (ss_ashift:@var{m} @var{x} @var{c})
2655 @itemx (us_ashift:@var{m} @var{x} @var{c})
2656 These three expressions represent the result of arithmetically shifting @var{x}
2657 left by @var{c} places. They differ in their behavior on overflow of integer
2658 modes. An @code{ashift} operation is a plain shift with no special behavior
2659 in case of a change in the sign bit; @code{ss_ashift} and @code{us_ashift}
2660 saturates to the minimum or maximum representable value if any of the bits
2661 shifted out differs from the final sign bit.
2663 @var{x} have mode @var{m}, a fixed-point machine mode. @var{c}
2664 be a fixed-point mode or be a constant with mode @code{VOIDmode}; which
2665 mode is determined by the mode called for in the machine description
2666 entry for the left-shift instruction. For example, on the VAX, the mode
2667 of @var{c} is @code{QImode} regardless of @var{m}.
2672 @item (lshiftrt:@var{m} @var{x} @var{c})
2673 @itemx (ashiftrt:@var{m} @var{x} @var{c})
2674 Like @code{ashift} but for right shift. Unlike the case for left shift,
2675 these two operations are distinct.
2681 @cindex right rotate
2682 @item (rotate:@var{m} @var{x} @var{c})
2683 @itemx (rotatert:@var{m} @var{x} @var{c})
2684 Similar but represent left and right rotate. If @var{c} is a constant,
2689 @cindex absolute value
2690 @item (abs:@var{m} @var{x})
2691 @item (ss_abs:@var{m} @var{x})
2692 Represents the absolute value of @var{x}, computed in mode @var{m}.
2693 @code{ss_abs} ensures that an out-of-bounds result saturates to the
2694 maximum signed value.
2699 @item (sqrt:@var{m} @var{x})
2700 Represents the square root of @var{x}, computed in mode @var{m}.
2701 Most often @var{m} will be a floating point mode.
2704 @item (ffs:@var{m} @var{x})
2705 Represents one plus the index of the least significant 1-bit in
2706 @var{x}, represented as an integer of mode @var{m}. (The value is
2707 zero if @var{x} is zero.) The mode of @var{x} must be @var{m}
2711 @item (clrsb:@var{m} @var{x})
2712 Represents the number of redundant leading sign bits in @var{x},
2713 represented as an integer of mode @var{m}, starting at the most
2714 significant bit position. This is one less than the number of leading
2715 sign bits (either 0 or 1), with no special cases. The mode of @var{x}
2716 must be @var{m} or @code{VOIDmode}.
2719 @item (clz:@var{m} @var{x})
2720 Represents the number of leading 0-bits in @var{x}, represented as an
2721 integer of mode @var{m}, starting at the most significant bit position.
2722 If @var{x} is zero, the value is determined by
2723 @code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}). Note that this is one of
2724 the few expressions that is not invariant under widening. The mode of
2725 @var{x} must be @var{m} or @code{VOIDmode}.
2728 @item (ctz:@var{m} @var{x})
2729 Represents the number of trailing 0-bits in @var{x}, represented as an
2730 integer of mode @var{m}, starting at the least significant bit position.
2731 If @var{x} is zero, the value is determined by
2732 @code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}). Except for this case,
2733 @code{ctz(x)} is equivalent to @code{ffs(@var{x}) - 1}. The mode of
2734 @var{x} must be @var{m} or @code{VOIDmode}.
2737 @item (popcount:@var{m} @var{x})
2738 Represents the number of 1-bits in @var{x}, represented as an integer of
2739 mode @var{m}. The mode of @var{x} must be @var{m} or @code{VOIDmode}.
2742 @item (parity:@var{m} @var{x})
2743 Represents the number of 1-bits modulo 2 in @var{x}, represented as an
2744 integer of mode @var{m}. The mode of @var{x} must be @var{m} or
2748 @item (bswap:@var{m} @var{x})
2749 Represents the value @var{x} with the order of bytes reversed, carried out
2750 in mode @var{m}, which must be a fixed-point machine mode.
2751 The mode of @var{x} must be @var{m} or @code{VOIDmode}.
2755 @section Comparison Operations
2756 @cindex RTL comparison operations
2758 Comparison operators test a relation on two operands and are considered
2759 to represent a machine-dependent nonzero value described by, but not
2760 necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
2761 if the relation holds, or zero if it does not, for comparison operators
2762 whose results have a `MODE_INT' mode,
2763 @code{FLOAT_STORE_FLAG_VALUE} (@pxref{Misc}) if the relation holds, or
2764 zero if it does not, for comparison operators that return floating-point
2765 values, and a vector of either @code{VECTOR_STORE_FLAG_VALUE} (@pxref{Misc})
2766 if the relation holds, or of zeros if it does not, for comparison operators
2767 that return vector results.
2768 The mode of the comparison operation is independent of the mode
2769 of the data being compared. If the comparison operation is being tested
2770 (e.g., the first operand of an @code{if_then_else}), the mode must be
2773 @cindex condition codes
2774 There are two ways that comparison operations may be used. The
2775 comparison operators may be used to compare the condition codes
2776 @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such
2777 a construct actually refers to the result of the preceding instruction
2778 in which the condition codes were set. The instruction setting the
2779 condition code must be adjacent to the instruction using the condition
2780 code; only @code{note} insns may separate them.
2782 Alternatively, a comparison operation may directly compare two data
2783 objects. The mode of the comparison is determined by the operands; they
2784 must both be valid for a common machine mode. A comparison with both
2785 operands constant would be invalid as the machine mode could not be
2786 deduced from it, but such a comparison should never exist in RTL due to
2789 In the example above, if @code{(cc0)} were last set to
2790 @code{(compare @var{x} @var{y})}, the comparison operation is
2791 identical to @code{(eq @var{x} @var{y})}. Usually only one style
2792 of comparisons is supported on a particular machine, but the combine
2793 pass will try to merge the operations to produce the @code{eq} shown
2794 in case it exists in the context of the particular insn involved.
2796 Inequality comparisons come in two flavors, signed and unsigned. Thus,
2797 there are distinct expression codes @code{gt} and @code{gtu} for signed and
2798 unsigned greater-than. These can produce different results for the same
2799 pair of integer values: for example, 1 is signed greater-than @minus{}1 but not
2800 unsigned greater-than, because @minus{}1 when regarded as unsigned is actually
2801 @code{0xffffffff} which is greater than 1.
2803 The signed comparisons are also used for floating point values. Floating
2804 point comparisons are distinguished by the machine modes of the operands.
2809 @item (eq:@var{m} @var{x} @var{y})
2810 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2811 are equal, otherwise 0.
2815 @item (ne:@var{m} @var{x} @var{y})
2816 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2817 are not equal, otherwise 0.
2820 @cindex greater than
2821 @item (gt:@var{m} @var{x} @var{y})
2822 @code{STORE_FLAG_VALUE} if the @var{x} is greater than @var{y}. If they
2823 are fixed-point, the comparison is done in a signed sense.
2826 @cindex greater than
2827 @cindex unsigned greater than
2828 @item (gtu:@var{m} @var{x} @var{y})
2829 Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
2834 @cindex unsigned less than
2835 @item (lt:@var{m} @var{x} @var{y})
2836 @itemx (ltu:@var{m} @var{x} @var{y})
2837 Like @code{gt} and @code{gtu} but test for ``less than''.
2840 @cindex greater than
2842 @cindex unsigned greater than
2843 @item (ge:@var{m} @var{x} @var{y})
2844 @itemx (geu:@var{m} @var{x} @var{y})
2845 Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
2848 @cindex less than or equal
2850 @cindex unsigned less than
2851 @item (le:@var{m} @var{x} @var{y})
2852 @itemx (leu:@var{m} @var{x} @var{y})
2853 Like @code{gt} and @code{gtu} but test for ``less than or equal''.
2855 @findex if_then_else
2856 @item (if_then_else @var{cond} @var{then} @var{else})
2857 This is not a comparison operation but is listed here because it is
2858 always used in conjunction with a comparison operation. To be
2859 precise, @var{cond} is a comparison expression. This expression
2860 represents a choice, according to @var{cond}, between the value
2861 represented by @var{then} and the one represented by @var{else}.
2863 On most machines, @code{if_then_else} expressions are valid only
2864 to express conditional jumps.
2867 @item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
2868 Similar to @code{if_then_else}, but more general. Each of @var{test1},
2869 @var{test2}, @dots{} is performed in turn. The result of this expression is
2870 the @var{value} corresponding to the first nonzero test, or @var{default} if
2871 none of the tests are nonzero expressions.
2873 This is currently not valid for instruction patterns and is supported only
2874 for insn attributes. @xref{Insn Attributes}.
2881 Special expression codes exist to represent bit-field instructions.
2884 @findex sign_extract
2885 @cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
2886 @item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
2887 This represents a reference to a sign-extended bit-field contained or
2888 starting in @var{loc} (a memory or register reference). The bit-field
2889 is @var{size} bits wide and starts at bit @var{pos}. The compilation
2890 option @code{BITS_BIG_ENDIAN} says which end of the memory unit
2891 @var{pos} counts from.
2893 If @var{loc} is in memory, its mode must be a single-byte integer mode.
2894 If @var{loc} is in a register, the mode to use is specified by the
2895 operand of the @code{insv} or @code{extv} pattern
2896 (@pxref{Standard Names}) and is usually a full-word integer mode,
2897 which is the default if none is specified.
2899 The mode of @var{pos} is machine-specific and is also specified
2900 in the @code{insv} or @code{extv} pattern.
2902 The mode @var{m} is the same as the mode that would be used for
2903 @var{loc} if it were a register.
2905 A @code{sign_extract} can not appear as an lvalue, or part thereof,
2908 @findex zero_extract
2909 @item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
2910 Like @code{sign_extract} but refers to an unsigned or zero-extended
2911 bit-field. The same sequence of bits are extracted, but they
2912 are filled to an entire word with zeros instead of by sign-extension.
2914 Unlike @code{sign_extract}, this type of expressions can be lvalues
2915 in RTL; they may appear on the left side of an assignment, indicating
2916 insertion of a value into the specified bit-field.
2919 @node Vector Operations
2920 @section Vector Operations
2921 @cindex vector operations
2923 All normal RTL expressions can be used with vector modes; they are
2924 interpreted as operating on each part of the vector independently.
2925 Additionally, there are a few new expressions to describe specific vector
2930 @item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items})
2931 This describes a merge operation between two vectors. The result is a vector
2932 of mode @var{m}; its elements are selected from either @var{vec1} or
2933 @var{vec2}. Which elements are selected is described by @var{items}, which
2934 is a bit mask represented by a @code{const_int}; a zero bit indicates the
2935 corresponding element in the result vector is taken from @var{vec2} while
2936 a set bit indicates it is taken from @var{vec1}.
2939 @item (vec_select:@var{m} @var{vec1} @var{selection})
2940 This describes an operation that selects parts of a vector. @var{vec1} is
2941 the source vector, and @var{selection} is a @code{parallel} that contains a
2942 @code{const_int} (or another expression, if the selection can be made at
2943 runtime) for each of the subparts of the result vector, giving the number of
2944 the source subpart that should be stored into it. The result mode @var{m} is
2945 either the submode for a single element of @var{vec1} (if only one subpart is
2946 selected), or another vector mode with that element submode (if multiple
2947 subparts are selected).
2950 @item (vec_concat:@var{m} @var{x1} @var{x2})
2951 Describes a vector concat operation. The result is a concatenation of the
2952 vectors or scalars @var{x1} and @var{x2}; its length is the sum of the
2953 lengths of the two inputs.
2955 @findex vec_duplicate
2956 @item (vec_duplicate:@var{m} @var{x})
2957 This operation converts a scalar into a vector or a small vector into a
2958 larger one by duplicating the input values. The output vector mode must have
2959 the same submodes as the input vector mode or the scalar modes, and the
2960 number of output parts must be an integer multiple of the number of input
2964 @item (vec_series:@var{m} @var{base} @var{step})
2965 This operation creates a vector in which element @var{i} is equal to
2966 @samp{@var{base} + @var{i}*@var{step}}. @var{m} must be a vector integer mode.
2970 @section Conversions
2972 @cindex machine mode conversions
2974 All conversions between machine modes must be represented by
2975 explicit conversion operations. For example, an expression
2976 which is the sum of a byte and a full word cannot be written as
2977 @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
2978 operation requires two operands of the same machine mode.
2979 Therefore, the byte-sized operand is enclosed in a conversion
2983 (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
2986 The conversion operation is not a mere placeholder, because there
2987 may be more than one way of converting from a given starting mode
2988 to the desired final mode. The conversion operation code says how
2991 For all conversion operations, @var{x} must not be @code{VOIDmode}
2992 because the mode in which to do the conversion would not be known.
2993 The conversion must either be done at compile-time or @var{x}
2994 must be placed into a register.
2998 @item (sign_extend:@var{m} @var{x})
2999 Represents the result of sign-extending the value @var{x}
3000 to machine mode @var{m}. @var{m} must be a fixed-point mode
3001 and @var{x} a fixed-point value of a mode narrower than @var{m}.
3004 @item (zero_extend:@var{m} @var{x})
3005 Represents the result of zero-extending the value @var{x}
3006 to machine mode @var{m}. @var{m} must be a fixed-point mode
3007 and @var{x} a fixed-point value of a mode narrower than @var{m}.
3009 @findex float_extend
3010 @item (float_extend:@var{m} @var{x})
3011 Represents the result of extending the value @var{x}
3012 to machine mode @var{m}. @var{m} must be a floating point mode
3013 and @var{x} a floating point value of a mode narrower than @var{m}.
3016 @item (truncate:@var{m} @var{x})
3017 Represents the result of truncating the value @var{x}
3018 to machine mode @var{m}. @var{m} must be a fixed-point mode
3019 and @var{x} a fixed-point value of a mode wider than @var{m}.
3022 @item (ss_truncate:@var{m} @var{x})
3023 Represents the result of truncating the value @var{x}
3024 to machine mode @var{m}, using signed saturation in the case of
3025 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
3029 @item (us_truncate:@var{m} @var{x})
3030 Represents the result of truncating the value @var{x}
3031 to machine mode @var{m}, using unsigned saturation in the case of
3032 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
3035 @findex float_truncate
3036 @item (float_truncate:@var{m} @var{x})
3037 Represents the result of truncating the value @var{x}
3038 to machine mode @var{m}. @var{m} must be a floating point mode
3039 and @var{x} a floating point value of a mode wider than @var{m}.
3042 @item (float:@var{m} @var{x})
3043 Represents the result of converting fixed point value @var{x},
3044 regarded as signed, to floating point mode @var{m}.
3046 @findex unsigned_float
3047 @item (unsigned_float:@var{m} @var{x})
3048 Represents the result of converting fixed point value @var{x},
3049 regarded as unsigned, to floating point mode @var{m}.
3052 @item (fix:@var{m} @var{x})
3053 When @var{m} is a floating-point mode, represents the result of
3054 converting floating point value @var{x} (valid for mode @var{m}) to an
3055 integer, still represented in floating point mode @var{m}, by rounding
3058 When @var{m} is a fixed-point mode, represents the result of
3059 converting floating point value @var{x} to mode @var{m}, regarded as
3060 signed. How rounding is done is not specified, so this operation may
3061 be used validly in compiling C code only for integer-valued operands.
3063 @findex unsigned_fix
3064 @item (unsigned_fix:@var{m} @var{x})
3065 Represents the result of converting floating point value @var{x} to
3066 fixed point mode @var{m}, regarded as unsigned. How rounding is done
3069 @findex fract_convert
3070 @item (fract_convert:@var{m} @var{x})
3071 Represents the result of converting fixed-point value @var{x} to
3072 fixed-point mode @var{m}, signed integer value @var{x} to
3073 fixed-point mode @var{m}, floating-point value @var{x} to
3074 fixed-point mode @var{m}, fixed-point value @var{x} to integer mode @var{m}
3075 regarded as signed, or fixed-point value @var{x} to floating-point mode @var{m}.
3076 When overflows or underflows happen, the results are undefined.
3079 @item (sat_fract:@var{m} @var{x})
3080 Represents the result of converting fixed-point value @var{x} to
3081 fixed-point mode @var{m}, signed integer value @var{x} to
3082 fixed-point mode @var{m}, or floating-point value @var{x} to
3083 fixed-point mode @var{m}.
3084 When overflows or underflows happen, the results are saturated to the
3085 maximum or the minimum.
3087 @findex unsigned_fract_convert
3088 @item (unsigned_fract_convert:@var{m} @var{x})
3089 Represents the result of converting fixed-point value @var{x} to
3090 integer mode @var{m} regarded as unsigned, or unsigned integer value @var{x} to
3091 fixed-point mode @var{m}.
3092 When overflows or underflows happen, the results are undefined.
3094 @findex unsigned_sat_fract
3095 @item (unsigned_sat_fract:@var{m} @var{x})
3096 Represents the result of converting unsigned integer value @var{x} to
3097 fixed-point mode @var{m}.
3098 When overflows or underflows happen, the results are saturated to the
3099 maximum or the minimum.
3102 @node RTL Declarations
3103 @section Declarations
3104 @cindex RTL declarations
3105 @cindex declarations, RTL
3107 Declaration expression codes do not represent arithmetic operations
3108 but rather state assertions about their operands.
3111 @findex strict_low_part
3112 @cindex @code{subreg}, in @code{strict_low_part}
3113 @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
3114 This expression code is used in only one context: as the destination operand of a
3115 @code{set} expression. In addition, the operand of this expression
3116 must be a non-paradoxical @code{subreg} expression.
3118 The presence of @code{strict_low_part} says that the part of the
3119 register which is meaningful in mode @var{n}, but is not part of
3120 mode @var{m}, is not to be altered. Normally, an assignment to such
3121 a subreg is allowed to have undefined effects on the rest of the
3122 register when @var{m} is smaller than @samp{REGMODE_NATURAL_SIZE (@var{n})}.
3126 @section Side Effect Expressions
3127 @cindex RTL side effect expressions
3129 The expression codes described so far represent values, not actions.
3130 But machine instructions never produce values; they are meaningful
3131 only for their side effects on the state of the machine. Special
3132 expression codes are used to represent side effects.
3134 The body of an instruction is always one of these side effect codes;
3135 the codes described above, which represent values, appear only as
3136 the operands of these.
3140 @item (set @var{lval} @var{x})
3141 Represents the action of storing the value of @var{x} into the place
3142 represented by @var{lval}. @var{lval} must be an expression
3143 representing a place that can be stored in: @code{reg} (or @code{subreg},
3144 @code{strict_low_part} or @code{zero_extract}), @code{mem}, @code{pc},
3145 @code{parallel}, or @code{cc0}.
3147 If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
3148 machine mode; then @var{x} must be valid for that mode.
3150 If @var{lval} is a @code{reg} whose machine mode is less than the full
3151 width of the register, then it means that the part of the register
3152 specified by the machine mode is given the specified value and the
3153 rest of the register receives an undefined value. Likewise, if
3154 @var{lval} is a @code{subreg} whose machine mode is narrower than
3155 the mode of the register, the rest of the register can be changed in
3158 If @var{lval} is a @code{strict_low_part} of a subreg, then the part
3159 of the register specified by the machine mode of the @code{subreg} is
3160 given the value @var{x} and the rest of the register is not changed.
3162 If @var{lval} is a @code{zero_extract}, then the referenced part of
3163 the bit-field (a memory or register reference) specified by the
3164 @code{zero_extract} is given the value @var{x} and the rest of the
3165 bit-field is not changed. Note that @code{sign_extract} can not
3166 appear in @var{lval}.
3168 If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
3169 be either a @code{compare} expression or a value that may have any mode.
3170 The latter case represents a ``test'' instruction. The expression
3171 @code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to
3172 @code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}.
3173 Use the former expression to save space during the compilation.
3175 If @var{lval} is a @code{parallel}, it is used to represent the case of
3176 a function returning a structure in multiple registers. Each element
3177 of the @code{parallel} is an @code{expr_list} whose first operand is a
3178 @code{reg} and whose second operand is a @code{const_int} representing the
3179 offset (in bytes) into the structure at which the data in that register
3180 corresponds. The first element may be null to indicate that the structure
3181 is also passed partly in memory.
3183 @cindex jump instructions and @code{set}
3184 @cindex @code{if_then_else} usage
3185 If @var{lval} is @code{(pc)}, we have a jump instruction, and the
3186 possibilities for @var{x} are very limited. It may be a
3187 @code{label_ref} expression (unconditional jump). It may be an
3188 @code{if_then_else} (conditional jump), in which case either the
3189 second or the third operand must be @code{(pc)} (for the case which
3190 does not jump) and the other of the two must be a @code{label_ref}
3191 (for the case which does jump). @var{x} may also be a @code{mem} or
3192 @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
3193 @code{mem}; these unusual patterns are used to represent jumps through
3196 If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of
3197 @var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
3198 valid for the mode of @var{lval}.
3202 @var{lval} is customarily accessed with the @code{SET_DEST} macro and
3203 @var{x} with the @code{SET_SRC} macro.
3207 As the sole expression in a pattern, represents a return from the
3208 current function, on machines where this can be done with one
3209 instruction, such as VAXen. On machines where a multi-instruction
3210 ``epilogue'' must be executed in order to return from the function,
3211 returning is done by jumping to a label which precedes the epilogue, and
3212 the @code{return} expression code is never used.
3214 Inside an @code{if_then_else} expression, represents the value to be
3215 placed in @code{pc} to return to the caller.
3217 Note that an insn pattern of @code{(return)} is logically equivalent to
3218 @code{(set (pc) (return))}, but the latter form is never used.
3220 @findex simple_return
3221 @item (simple_return)
3222 Like @code{(return)}, but truly represents only a function return, while
3223 @code{(return)} may represent an insn that also performs other functions
3224 of the function epilogue. Like @code{(return)}, this may also occur in
3228 @item (call @var{function} @var{nargs})
3229 Represents a function call. @var{function} is a @code{mem} expression
3230 whose address is the address of the function to be called.
3231 @var{nargs} is an expression which can be used for two purposes: on
3232 some machines it represents the number of bytes of stack argument; on
3233 others, it represents the number of argument registers.
3235 Each machine has a standard machine mode which @var{function} must
3236 have. The machine description defines macro @code{FUNCTION_MODE} to
3237 expand into the requisite mode name. The purpose of this mode is to
3238 specify what kind of addressing is allowed, on machines where the
3239 allowed kinds of addressing depend on the machine mode being
3243 @item (clobber @var{x})
3244 Represents the storing or possible storing of an unpredictable,
3245 undescribed value into @var{x}, which must be a @code{reg},
3246 @code{scratch}, @code{parallel} or @code{mem} expression.
3248 One place this is used is in string instructions that store standard
3249 values into particular hard registers. It may not be worth the
3250 trouble to describe the values that are stored, but it is essential to
3251 inform the compiler that the registers will be altered, lest it
3252 attempt to keep data in them across the string instruction.
3254 If @var{x} is @code{(mem:BLK (const_int 0))} or
3255 @code{(mem:BLK (scratch))}, it means that all memory
3256 locations must be presumed clobbered. If @var{x} is a @code{parallel},
3257 it has the same meaning as a @code{parallel} in a @code{set} expression.
3259 Note that the machine description classifies certain hard registers as
3260 ``call-clobbered''. All function call instructions are assumed by
3261 default to clobber these registers, so there is no need to use
3262 @code{clobber} expressions to indicate this fact. Also, each function
3263 call is assumed to have the potential to alter any memory location,
3264 unless the function is declared @code{const}.
3266 If the last group of expressions in a @code{parallel} are each a
3267 @code{clobber} expression whose arguments are @code{reg} or
3268 @code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
3269 phase can add the appropriate @code{clobber} expressions to an insn it
3270 has constructed when doing so will cause a pattern to be matched.
3272 This feature can be used, for example, on a machine that whose multiply
3273 and add instructions don't use an MQ register but which has an
3274 add-accumulate instruction that does clobber the MQ register. Similarly,
3275 a combined instruction might require a temporary register while the
3276 constituent instructions might not.
3278 When a @code{clobber} expression for a register appears inside a
3279 @code{parallel} with other side effects, the register allocator
3280 guarantees that the register is unoccupied both before and after that
3281 insn if it is a hard register clobber. For pseudo-register clobber,
3282 the register allocator and the reload pass do not assign the same hard
3283 register to the clobber and the input operands if there is an insn
3284 alternative containing the @samp{&} constraint (@pxref{Modifiers}) for
3285 the clobber and the hard register is in register classes of the
3286 clobber in the alternative. You can clobber either a specific hard
3287 register, a pseudo register, or a @code{scratch} expression; in the
3288 latter two cases, GCC will allocate a hard register that is available
3289 there for use as a temporary.
3291 For instructions that require a temporary register, you should use
3292 @code{scratch} instead of a pseudo-register because this will allow the
3293 combiner phase to add the @code{clobber} when required. You do this by
3294 coding (@code{clobber} (@code{match_scratch} @dots{})). If you do
3295 clobber a pseudo register, use one which appears nowhere else---generate
3296 a new one each time. Otherwise, you may confuse CSE@.
3298 There is one other known use for clobbering a pseudo register in a
3299 @code{parallel}: when one of the input operands of the insn is also
3300 clobbered by the insn. In this case, using the same pseudo register in
3301 the clobber and elsewhere in the insn produces the expected results.
3303 @findex clobber_high
3304 @item (clobber_high @var{x})
3305 Represents the storing or possible storing of an unpredictable,
3306 undescribed value into the upper parts of @var{x}. The mode of the expression
3307 represents the lower parts of the register which will not be overwritten.
3308 @code{reg} must be a reg expression.
3310 One place this is used is when calling into functions where the registers are
3311 preserved, but only up to a given number of bits. For example when using
3312 Aarch64 SVE, calling a TLS descriptor will cause only the lower 128 bits of
3313 each of the vector registers to be preserved.
3317 Represents the use of the value of @var{x}. It indicates that the
3318 value in @var{x} at this point in the program is needed, even though
3319 it may not be apparent why this is so. Therefore, the compiler will
3320 not attempt to delete previous instructions whose only effect is to
3321 store a value in @var{x}. @var{x} must be a @code{reg} expression.
3323 In some situations, it may be tempting to add a @code{use} of a
3324 register in a @code{parallel} to describe a situation where the value
3325 of a special register will modify the behavior of the instruction.
3326 A hypothetical example might be a pattern for an addition that can
3327 either wrap around or use saturating addition depending on the value
3328 of a special control register:
3331 (parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
3338 This will not work, several of the optimizers only look at expressions
3339 locally; it is very likely that if you have multiple insns with
3340 identical inputs to the @code{unspec}, they will be optimized away even
3341 if register 1 changes in between.
3343 This means that @code{use} can @emph{only} be used to describe
3344 that the register is live. You should think twice before adding
3345 @code{use} statements, more often you will want to use @code{unspec}
3346 instead. The @code{use} RTX is most commonly useful to describe that
3347 a fixed register is implicitly used in an insn. It is also safe to use
3348 in patterns where the compiler knows for other reasons that the result
3349 of the whole pattern is variable, such as @samp{movmem@var{m}} or
3350 @samp{call} patterns.
3352 During the reload phase, an insn that has a @code{use} as pattern
3353 can carry a reg_equal note. These @code{use} insns will be deleted
3354 before the reload phase exits.
3356 During the delayed branch scheduling phase, @var{x} may be an insn.
3357 This indicates that @var{x} previously was located at this place in the
3358 code and its data dependencies need to be taken into account. These
3359 @code{use} insns will be deleted before the delayed branch scheduling
3363 @item (parallel [@var{x0} @var{x1} @dots{}])
3364 Represents several side effects performed in parallel. The square
3365 brackets stand for a vector; the operand of @code{parallel} is a
3366 vector of expressions. @var{x0}, @var{x1} and so on are individual
3367 side effect expressions---expressions of code @code{set}, @code{call},
3368 @code{return}, @code{simple_return}, @code{clobber} @code{use} or
3369 @code{clobber_high}.
3371 ``In parallel'' means that first all the values used in the individual
3372 side-effects are computed, and second all the actual side-effects are
3373 performed. For example,
3376 (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
3377 (set (mem:SI (reg:SI 1)) (reg:SI 1))])
3381 says unambiguously that the values of hard register 1 and the memory
3382 location addressed by it are interchanged. In both places where
3383 @code{(reg:SI 1)} appears as a memory address it refers to the value
3384 in register 1 @emph{before} the execution of the insn.
3386 It follows that it is @emph{incorrect} to use @code{parallel} and
3387 expect the result of one @code{set} to be available for the next one.
3388 For example, people sometimes attempt to represent a jump-if-zero
3389 instruction this way:
3392 (parallel [(set (cc0) (reg:SI 34))
3393 (set (pc) (if_then_else
3394 (eq (cc0) (const_int 0))
3400 But this is incorrect, because it says that the jump condition depends
3401 on the condition code value @emph{before} this instruction, not on the
3402 new value that is set by this instruction.
3404 @cindex peephole optimization, RTL representation
3405 Peephole optimization, which takes place together with final assembly
3406 code output, can produce insns whose patterns consist of a @code{parallel}
3407 whose elements are the operands needed to output the resulting
3408 assembler code---often @code{reg}, @code{mem} or constant expressions.
3409 This would not be well-formed RTL at any other stage in compilation,
3410 but it is OK then because no further optimization remains to be done.
3411 However, the definition of the macro @code{NOTICE_UPDATE_CC}, if
3412 any, must deal with such insns if you define any peephole optimizations.
3415 @item (cond_exec [@var{cond} @var{expr}])
3416 Represents a conditionally executed expression. The @var{expr} is
3417 executed only if the @var{cond} is nonzero. The @var{cond} expression
3418 must not have side-effects, but the @var{expr} may very well have
3422 @item (sequence [@var{insns} @dots{}])
3423 Represents a sequence of insns. If a @code{sequence} appears in the
3424 chain of insns, then each of the @var{insns} that appears in the sequence
3425 must be suitable for appearing in the chain of insns, i.e. must satisfy
3426 the @code{INSN_P} predicate.
3428 After delay-slot scheduling is completed, an insn and all the insns that
3429 reside in its delay slots are grouped together into a @code{sequence}.
3430 The insn requiring the delay slot is the first insn in the vector;
3431 subsequent insns are to be placed in the delay slot.
3433 @code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
3434 indicate that a branch insn should be used that will conditionally annul
3435 the effect of the insns in the delay slots. In such a case,
3436 @code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
3437 the branch and should be executed only if the branch is taken; otherwise
3438 the insn should be executed only if the branch is not taken.
3441 Some back ends also use @code{sequence} objects for purposes other than
3442 delay-slot groups. This is not supported in the common parts of the
3443 compiler, which treat such sequences as delay-slot groups.
3445 DWARF2 Call Frame Address (CFA) adjustments are sometimes also expressed
3446 using @code{sequence} objects as the value of a @code{RTX_FRAME_RELATED_P}
3447 note. This only happens if the CFA adjustments cannot be easily derived
3448 from the pattern of the instruction to which the note is attached. In
3449 such cases, the value of the note is used instead of best-guesing the
3450 semantics of the instruction. The back end can attach notes containing
3451 a @code{sequence} of @code{set} patterns that express the effect of the
3455 These expression codes appear in place of a side effect, as the body of
3456 an insn, though strictly speaking they do not always describe side
3461 @item (asm_input @var{s})
3462 Represents literal assembler code as described by the string @var{s}.
3465 @findex unspec_volatile
3466 @item (unspec [@var{operands} @dots{}] @var{index})
3467 @itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
3468 Represents a machine-specific operation on @var{operands}. @var{index}
3469 selects between multiple machine-specific operations.
3470 @code{unspec_volatile} is used for volatile operations and operations
3471 that may trap; @code{unspec} is used for other operations.
3473 These codes may appear inside a @code{pattern} of an
3474 insn, inside a @code{parallel}, or inside an expression.
3477 @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
3478 Represents a table of jump addresses. The vector elements @var{lr0},
3479 etc., are @code{label_ref} expressions. The mode @var{m} specifies
3480 how much space is given to each address; normally @var{m} would be
3483 @findex addr_diff_vec
3484 @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags})
3485 Represents a table of jump addresses expressed as offsets from
3486 @var{base}. The vector elements @var{lr0}, etc., are @code{label_ref}
3487 expressions and so is @var{base}. The mode @var{m} specifies how much
3488 space is given to each address-difference. @var{min} and @var{max}
3489 are set up by branch shortening and hold a label with a minimum and a
3490 maximum address, respectively. @var{flags} indicates the relative
3491 position of @var{base}, @var{min} and @var{max} to the containing insn
3492 and of @var{min} and @var{max} to @var{base}. See rtl.def for details.
3495 @item (prefetch:@var{m} @var{addr} @var{rw} @var{locality})
3496 Represents prefetch of memory at address @var{addr}.
3497 Operand @var{rw} is 1 if the prefetch is for data to be written, 0 otherwise;
3498 targets that do not support write prefetches should treat this as a normal
3500 Operand @var{locality} specifies the amount of temporal locality; 0 if there
3501 is none or 1, 2, or 3 for increasing levels of temporal locality;
3502 targets that do not support locality hints should ignore this.
3504 This insn is used to minimize cache-miss latency by moving data into a
3505 cache before it is accessed. It should use only non-faulting data prefetch
3510 @section Embedded Side-Effects on Addresses
3511 @cindex RTL preincrement
3512 @cindex RTL postincrement
3513 @cindex RTL predecrement
3514 @cindex RTL postdecrement
3516 Six special side-effect expression codes appear as memory addresses.
3520 @item (pre_dec:@var{m} @var{x})
3521 Represents the side effect of decrementing @var{x} by a standard
3522 amount and represents also the value that @var{x} has after being
3523 decremented. @var{x} must be a @code{reg} or @code{mem}, but most
3524 machines allow only a @code{reg}. @var{m} must be the machine mode
3525 for pointers on the machine in use. The amount @var{x} is decremented
3526 by is the length in bytes of the machine mode of the containing memory
3527 reference of which this expression serves as the address. Here is an
3531 (mem:DF (pre_dec:SI (reg:SI 39)))
3535 This says to decrement pseudo register 39 by the length of a @code{DFmode}
3536 value and use the result to address a @code{DFmode} value.
3539 @item (pre_inc:@var{m} @var{x})
3540 Similar, but specifies incrementing @var{x} instead of decrementing it.
3543 @item (post_dec:@var{m} @var{x})
3544 Represents the same side effect as @code{pre_dec} but a different
3545 value. The value represented here is the value @var{x} has @i{before}
3549 @item (post_inc:@var{m} @var{x})
3550 Similar, but specifies incrementing @var{x} instead of decrementing it.
3553 @item (post_modify:@var{m} @var{x} @var{y})
3555 Represents the side effect of setting @var{x} to @var{y} and
3556 represents @var{x} before @var{x} is modified. @var{x} must be a
3557 @code{reg} or @code{mem}, but most machines allow only a @code{reg}.
3558 @var{m} must be the machine mode for pointers on the machine in use.
3560 The expression @var{y} must be one of three forms:
3561 @code{(plus:@var{m} @var{x} @var{z})},
3562 @code{(minus:@var{m} @var{x} @var{z})}, or
3563 @code{(plus:@var{m} @var{x} @var{i})},
3564 where @var{z} is an index register and @var{i} is a constant.
3566 Here is an example of its use:
3569 (mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
3573 This says to modify pseudo register 42 by adding the contents of pseudo
3574 register 48 to it, after the use of what ever 42 points to.
3577 @item (pre_modify:@var{m} @var{x} @var{expr})
3578 Similar except side effects happen before the use.
3581 These embedded side effect expressions must be used with care. Instruction
3582 patterns may not use them. Until the @samp{flow} pass of the compiler,
3583 they may occur only to represent pushes onto the stack. The @samp{flow}
3584 pass finds cases where registers are incremented or decremented in one
3585 instruction and used as an address shortly before or after; these cases are
3586 then transformed to use pre- or post-increment or -decrement.
3588 If a register used as the operand of these expressions is used in
3589 another address in an insn, the original value of the register is used.
3590 Uses of the register outside of an address are not permitted within the
3591 same insn as a use in an embedded side effect expression because such
3592 insns behave differently on different machines and hence must be treated
3593 as ambiguous and disallowed.
3595 An instruction that can be represented with an embedded side effect
3596 could also be represented using @code{parallel} containing an additional
3597 @code{set} to describe how the address register is altered. This is not
3598 done because machines that allow these operations at all typically
3599 allow them wherever a memory address is called for. Describing them as
3600 additional parallel stores would require doubling the number of entries
3601 in the machine description.
3604 @section Assembler Instructions as Expressions
3605 @cindex assembler instructions in RTL
3607 @cindex @code{asm_operands}, usage
3608 The RTX code @code{asm_operands} represents a value produced by a
3609 user-specified assembler instruction. It is used to represent
3610 an @code{asm} statement with arguments. An @code{asm} statement with
3611 a single output operand, like this:
3614 asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
3618 is represented using a single @code{asm_operands} RTX which represents
3619 the value that is stored in @code{outputvar}:
3622 (set @var{rtx-for-outputvar}
3623 (asm_operands "foo %1,%2,%0" "a" 0
3624 [@var{rtx-for-addition-result} @var{rtx-for-*z}]
3625 [(asm_input:@var{m1} "g")
3626 (asm_input:@var{m2} "di")]))
3630 Here the operands of the @code{asm_operands} RTX are the assembler
3631 template string, the output-operand's constraint, the index-number of the
3632 output operand among the output operands specified, a vector of input
3633 operand RTX's, and a vector of input-operand modes and constraints. The
3634 mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
3637 When an @code{asm} statement has multiple output values, its insn has
3638 several such @code{set} RTX's inside of a @code{parallel}. Each @code{set}
3639 contains an @code{asm_operands}; all of these share the same assembler
3640 template and vectors, but each contains the constraint for the respective
3641 output operand. They are also distinguished by the output-operand index
3642 number, which is 0, 1, @dots{} for successive output operands.
3644 @node Debug Information
3645 @section Variable Location Debug Information in RTL
3646 @cindex Variable Location Debug Information in RTL
3648 Variable tracking relies on @code{MEM_EXPR} and @code{REG_EXPR}
3649 annotations to determine what user variables memory and register
3650 references refer to.
3652 Variable tracking at assignments uses these notes only when they refer
3653 to variables that live at fixed locations (e.g., addressable
3654 variables, global non-automatic variables). For variables whose
3655 location may vary, it relies on the following types of notes.
3658 @findex var_location
3659 @item (var_location:@var{mode} @var{var} @var{exp} @var{stat})
3660 Binds variable @code{var}, a tree, to value @var{exp}, an RTL
3661 expression. It appears only in @code{NOTE_INSN_VAR_LOCATION} and
3662 @code{DEBUG_INSN}s, with slightly different meanings. @var{mode}, if
3663 present, represents the mode of @var{exp}, which is useful if it is a
3664 modeless expression. @var{stat} is only meaningful in notes,
3665 indicating whether the variable is known to be initialized or
3669 @item (debug_expr:@var{mode} @var{decl})
3670 Stands for the value bound to the @code{DEBUG_EXPR_DECL} @var{decl},
3671 that points back to it, within value expressions in
3672 @code{VAR_LOCATION} nodes.
3674 @findex debug_implicit_ptr
3675 @item (debug_implicit_ptr:@var{mode} @var{decl})
3676 Stands for the location of a @var{decl} that is no longer addressable.
3679 @item (entry_value:@var{mode} @var{decl})
3680 Stands for the value a @var{decl} had at the entry point of the
3681 containing function.
3683 @findex debug_parameter_ref
3684 @item (debug_parameter_ref:@var{mode} @var{decl})
3685 Refers to a parameter that was completely optimized out.
3687 @findex debug_marker
3688 @item (debug_marker:@var{mode})
3689 Marks a program location. With @code{VOIDmode}, it stands for the
3690 beginning of a statement, a recommended inspection point logically after
3691 all prior side effects, and before any subsequent side effects. With
3692 @code{BLKmode}, it indicates an inline entry point: the lexical block
3693 encoded in the @code{INSN_LOCATION} is the enclosing block that encloses
3694 the inlined function.
3702 The RTL representation of the code for a function is a doubly-linked
3703 chain of objects called @dfn{insns}. Insns are expressions with
3704 special codes that are used for no other purpose. Some insns are
3705 actual instructions; others represent dispatch tables for @code{switch}
3706 statements; others represent labels to jump to or various sorts of
3707 declarative information.
3709 In addition to its own specific data, each insn must have a unique
3710 id-number that distinguishes it from all other insns in the current
3711 function (after delayed branch scheduling, copies of an insn with the
3712 same id-number may be present in multiple places in a function, but
3713 these copies will always be identical and will only appear inside a
3714 @code{sequence}), and chain pointers to the preceding and following
3715 insns. These three fields occupy the same position in every insn,
3716 independent of the expression code of the insn. They could be accessed
3717 with @code{XEXP} and @code{XINT}, but instead three special macros are
3722 @item INSN_UID (@var{i})
3723 Accesses the unique id of insn @var{i}.
3726 @item PREV_INSN (@var{i})
3727 Accesses the chain pointer to the insn preceding @var{i}.
3728 If @var{i} is the first insn, this is a null pointer.
3731 @item NEXT_INSN (@var{i})
3732 Accesses the chain pointer to the insn following @var{i}.
3733 If @var{i} is the last insn, this is a null pointer.
3737 @findex get_last_insn
3738 The first insn in the chain is obtained by calling @code{get_insns}; the
3739 last insn is the result of calling @code{get_last_insn}. Within the
3740 chain delimited by these insns, the @code{NEXT_INSN} and
3741 @code{PREV_INSN} pointers must always correspond: if @var{insn} is not
3745 NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
3749 is always true and if @var{insn} is not the last insn,
3752 PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
3758 After delay slot scheduling, some of the insns in the chain might be
3759 @code{sequence} expressions, which contain a vector of insns. The value
3760 of @code{NEXT_INSN} in all but the last of these insns is the next insn
3761 in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
3762 is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
3763 which it is contained. Similar rules apply for @code{PREV_INSN}.
3765 This means that the above invariants are not necessarily true for insns
3766 inside @code{sequence} expressions. Specifically, if @var{insn} is the
3767 first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
3768 is the insn containing the @code{sequence} expression, as is the value
3769 of @code{PREV_INSN (NEXT_INSN (@var{insn}))} if @var{insn} is the last
3770 insn in the @code{sequence} expression. You can use these expressions
3771 to find the containing @code{sequence} expression.
3773 Every insn has one of the following expression codes:
3778 The expression code @code{insn} is used for instructions that do not jump
3779 and do not do function calls. @code{sequence} expressions are always
3780 contained in insns with code @code{insn} even if one of those insns
3781 should jump or do function calls.
3783 Insns with code @code{insn} have four additional fields beyond the three
3784 mandatory ones listed above. These four are described in a table below.
3788 The expression code @code{jump_insn} is used for instructions that may
3789 jump (or, more generally, may contain @code{label_ref} expressions to
3790 which @code{pc} can be set in that instruction). If there is an
3791 instruction to return from the current function, it is recorded as a
3795 @code{jump_insn} insns have the same extra fields as @code{insn} insns,
3796 accessed in the same way and in addition contain a field
3797 @code{JUMP_LABEL} which is defined once jump optimization has completed.
3799 For simple conditional and unconditional jumps, this field contains
3800 the @code{code_label} to which this insn will (possibly conditionally)
3801 branch. In a more complex jump, @code{JUMP_LABEL} records one of the
3802 labels that the insn refers to; other jump target labels are recorded
3803 as @code{REG_LABEL_TARGET} notes. The exception is @code{addr_vec}
3804 and @code{addr_diff_vec}, where @code{JUMP_LABEL} is @code{NULL_RTX}
3805 and the only way to find the labels is to scan the entire body of the
3808 Return insns count as jumps, but their @code{JUMP_LABEL} is @code{RETURN}
3809 or @code{SIMPLE_RETURN}.
3813 The expression code @code{call_insn} is used for instructions that may do
3814 function calls. It is important to distinguish these instructions because
3815 they imply that certain registers and memory locations may be altered
3818 @findex CALL_INSN_FUNCTION_USAGE
3819 @code{call_insn} insns have the same extra fields as @code{insn} insns,
3820 accessed in the same way and in addition contain a field
3821 @code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of
3822 @code{expr_list} expressions) containing @code{use}, @code{clobber} and
3823 sometimes @code{set} expressions that denote hard registers and
3824 @code{mem}s used or clobbered by the called function.
3826 A @code{mem} generally points to a stack slot in which arguments passed
3827 to the libcall by reference (@pxref{Register Arguments,
3828 TARGET_PASS_BY_REFERENCE}) are stored. If the argument is
3829 caller-copied (@pxref{Register Arguments, TARGET_CALLEE_COPIES}),
3830 the stack slot will be mentioned in @code{clobber} and @code{use}
3831 entries; if it's callee-copied, only a @code{use} will appear, and the
3832 @code{mem} may point to addresses that are not stack slots.
3834 Registers occurring inside a @code{clobber} in this list augment
3835 registers specified in @code{CALL_USED_REGISTERS} (@pxref{Register
3838 If the list contains a @code{set} involving two registers, it indicates
3839 that the function returns one of its arguments. Such a @code{set} may
3840 look like a no-op if the same register holds the argument and the return
3844 @findex CODE_LABEL_NUMBER
3846 A @code{code_label} insn represents a label that a jump insn can jump
3847 to. It contains two special fields of data in addition to the three
3848 standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
3849 number}, a number that identifies this label uniquely among all the
3850 labels in the compilation (not just in the current function).
3851 Ultimately, the label is represented in the assembler output as an
3852 assembler label, usually of the form @samp{L@var{n}} where @var{n} is
3855 When a @code{code_label} appears in an RTL expression, it normally
3856 appears within a @code{label_ref} which represents the address of
3857 the label, as a number.
3859 Besides as a @code{code_label}, a label can also be represented as a
3860 @code{note} of type @code{NOTE_INSN_DELETED_LABEL}.
3863 The field @code{LABEL_NUSES} is only defined once the jump optimization
3864 phase is completed. It contains the number of times this label is
3865 referenced in the current function.
3868 @findex SET_LABEL_KIND
3869 @findex LABEL_ALT_ENTRY_P
3870 @cindex alternate entry points
3871 The field @code{LABEL_KIND} differentiates four different types of
3872 labels: @code{LABEL_NORMAL}, @code{LABEL_STATIC_ENTRY},
3873 @code{LABEL_GLOBAL_ENTRY}, and @code{LABEL_WEAK_ENTRY}. The only labels
3874 that do not have type @code{LABEL_NORMAL} are @dfn{alternate entry
3875 points} to the current function. These may be static (visible only in
3876 the containing translation unit), global (exposed to all translation
3877 units), or weak (global, but can be overridden by another symbol with the
3880 Much of the compiler treats all four kinds of label identically. Some
3881 of it needs to know whether or not a label is an alternate entry point;
3882 for this purpose, the macro @code{LABEL_ALT_ENTRY_P} is provided. It is
3883 equivalent to testing whether @samp{LABEL_KIND (label) == LABEL_NORMAL}.
3884 The only place that cares about the distinction between static, global,
3885 and weak alternate entry points, besides the front-end code that creates
3886 them, is the function @code{output_alternate_entry_point}, in
3889 To set the kind of a label, use the @code{SET_LABEL_KIND} macro.
3891 @findex jump_table_data
3892 @item jump_table_data
3893 A @code{jump_table_data} insn is a placeholder for the jump-table data
3894 of a @code{casesi} or @code{tablejump} insn. They are placed after
3895 a @code{tablejump_p} insn. A @code{jump_table_data} insn is not part o
3896 a basic blockm but it is associated with the basic block that ends with
3897 the @code{tablejump_p} insn. The @code{PATTERN} of a @code{jump_table_data}
3898 is always either an @code{addr_vec} or an @code{addr_diff_vec}, and a
3899 @code{jump_table_data} insn is always preceded by a @code{code_label}.
3900 The @code{tablejump_p} insn refers to that @code{code_label} via its
3905 Barriers are placed in the instruction stream when control cannot flow
3906 past them. They are placed after unconditional jump instructions to
3907 indicate that the jumps are unconditional and after calls to
3908 @code{volatile} functions, which do not return (e.g., @code{exit}).
3909 They contain no information beyond the three standard fields.
3912 @findex NOTE_LINE_NUMBER
3913 @findex NOTE_SOURCE_FILE
3915 @code{note} insns are used to represent additional debugging and
3916 declarative information. They contain two nonstandard fields, an
3917 integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
3918 string accessed with @code{NOTE_SOURCE_FILE}.
3920 If @code{NOTE_LINE_NUMBER} is positive, the note represents the
3921 position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
3922 that the line came from. These notes control generation of line
3923 number data in the assembler output.
3925 Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
3926 code with one of the following values (and @code{NOTE_SOURCE_FILE}
3927 must contain a null pointer):
3930 @findex NOTE_INSN_DELETED
3931 @item NOTE_INSN_DELETED
3932 Such a note is completely ignorable. Some passes of the compiler
3933 delete insns by altering them into notes of this kind.
3935 @findex NOTE_INSN_DELETED_LABEL
3936 @item NOTE_INSN_DELETED_LABEL
3937 This marks what used to be a @code{code_label}, but was not used for other
3938 purposes than taking its address and was transformed to mark that no
3941 @findex NOTE_INSN_BLOCK_BEG
3942 @findex NOTE_INSN_BLOCK_END
3943 @item NOTE_INSN_BLOCK_BEG
3944 @itemx NOTE_INSN_BLOCK_END
3945 These types of notes indicate the position of the beginning and end
3946 of a level of scoping of variable names. They control the output
3947 of debugging information.
3949 @findex NOTE_INSN_EH_REGION_BEG
3950 @findex NOTE_INSN_EH_REGION_END
3951 @item NOTE_INSN_EH_REGION_BEG
3952 @itemx NOTE_INSN_EH_REGION_END
3953 These types of notes indicate the position of the beginning and end of a
3954 level of scoping for exception handling. @code{NOTE_EH_HANDLER}
3955 identifies which region is associated with these notes.
3957 @findex NOTE_INSN_FUNCTION_BEG
3958 @item NOTE_INSN_FUNCTION_BEG
3959 Appears at the start of the function body, after the function
3962 @findex NOTE_INSN_VAR_LOCATION
3963 @findex NOTE_VAR_LOCATION
3964 @item NOTE_INSN_VAR_LOCATION
3965 This note is used to generate variable location debugging information.
3966 It indicates that the user variable in its @code{VAR_LOCATION} operand
3967 is at the location given in the RTL expression, or holds a value that
3968 can be computed by evaluating the RTL expression from that static
3969 point in the program up to the next such note for the same user
3972 @findex NOTE_INSN_BEGIN_STMT
3973 @item NOTE_INSN_BEGIN_STMT
3974 This note is used to generate @code{is_stmt} markers in line number
3975 debuggign information. It indicates the beginning of a user
3978 @findex NOTE_INSN_INLINE_ENTRY
3979 @item NOTE_INSN_INLINE_ENTRY
3980 This note is used to generate @code{entry_pc} for inlined subroutines in
3981 debugging information. It indicates an inspection point at which all
3982 arguments for the inlined function have been bound, and before its first
3987 These codes are printed symbolically when they appear in debugging dumps.
3990 @findex INSN_VAR_LOCATION
3992 The expression code @code{debug_insn} is used for pseudo-instructions
3993 that hold debugging information for variable tracking at assignments
3994 (see @option{-fvar-tracking-assignments} option). They are the RTL
3995 representation of @code{GIMPLE_DEBUG} statements
3996 (@ref{@code{GIMPLE_DEBUG}}), with a @code{VAR_LOCATION} operand that
3997 binds a user variable tree to an RTL representation of the
3998 @code{value} in the corresponding statement. A @code{DEBUG_EXPR} in
3999 it stands for the value bound to the corresponding
4000 @code{DEBUG_EXPR_DECL}.
4002 @code{GIMPLE_DEBUG_BEGIN_STMT} and @code{GIMPLE_DEBUG_INLINE_ENTRY} are
4003 expanded to RTL as a @code{DEBUG_INSN} with a @code{DEBUG_MARKER}
4004 @code{PATTERN}; the difference is the RTL mode: the former's
4005 @code{DEBUG_MARKER} is @code{VOIDmode}, whereas the latter is
4006 @code{BLKmode}; information about the inlined function can be taken from
4007 the lexical block encoded in the @code{INSN_LOCATION}. These
4008 @code{DEBUG_INSN}s, that do not carry @code{VAR_LOCATION} information,
4009 just @code{DEBUG_MARKER}s, can be detected by testing
4010 @code{DEBUG_MARKER_INSN_P}, whereas those that do can be recognized as
4011 @code{DEBUG_BIND_INSN_P}.
4013 Throughout optimization passes, @code{DEBUG_INSN}s are not reordered
4014 with respect to each other, particularly during scheduling. Binding
4015 information is kept in pseudo-instruction form, so that, unlike notes,
4016 it gets the same treatment and adjustments that regular instructions
4017 would. It is the variable tracking pass that turns these
4018 pseudo-instructions into @code{NOTE_INSN_VAR_LOCATION},
4019 @code{NOTE_INSN_BEGIN_STMT} and @code{NOTE_INSN_INLINE_ENTRY} notes,
4020 analyzing control flow, value equivalences and changes to registers and
4021 memory referenced in value expressions, propagating the values of debug
4022 temporaries and determining expressions that can be used to compute the
4023 value of each user variable at as many points (ranges, actually) in the
4024 program as possible.
4026 Unlike @code{NOTE_INSN_VAR_LOCATION}, the value expression in an
4027 @code{INSN_VAR_LOCATION} denotes a value at that specific point in the
4028 program, rather than an expression that can be evaluated at any later
4029 point before an overriding @code{VAR_LOCATION} is encountered. E.g.,
4030 if a user variable is bound to a @code{REG} and then a subsequent insn
4031 modifies the @code{REG}, the note location would keep mapping the user
4032 variable to the register across the insn, whereas the insn location
4033 would keep the variable bound to the value, so that the variable
4034 tracking pass would emit another location note for the variable at the
4035 point in which the register is modified.
4039 @cindex @code{TImode}, in @code{insn}
4040 @cindex @code{HImode}, in @code{insn}
4041 @cindex @code{QImode}, in @code{insn}
4042 The machine mode of an insn is normally @code{VOIDmode}, but some
4043 phases use the mode for various purposes.
4045 The common subexpression elimination pass sets the mode of an insn to
4046 @code{QImode} when it is the first insn in a block that has already
4049 The second Haifa scheduling pass, for targets that can multiple issue,
4050 sets the mode of an insn to @code{TImode} when it is believed that the
4051 instruction begins an issue group. That is, when the instruction
4052 cannot issue simultaneously with the previous. This may be relied on
4053 by later passes, in particular machine-dependent reorg.
4055 Here is a table of the extra fields of @code{insn}, @code{jump_insn}
4056 and @code{call_insn} insns:
4060 @item PATTERN (@var{i})
4061 An expression for the side effect performed by this insn. This must
4062 be one of the following codes: @code{set}, @code{call}, @code{use},
4063 @code{clobber}, @code{return}, @code{simple_return}, @code{asm_input},
4064 @code{asm_output}, @code{addr_vec}, @code{addr_diff_vec},
4065 @code{trap_if}, @code{unspec}, @code{unspec_volatile},
4066 @code{parallel}, @code{cond_exec}, or @code{sequence}. If it is a
4067 @code{parallel}, each element of the @code{parallel} must be one these
4068 codes, except that @code{parallel} expressions cannot be nested and
4069 @code{addr_vec} and @code{addr_diff_vec} are not permitted inside a
4070 @code{parallel} expression.
4073 @item INSN_CODE (@var{i})
4074 An integer that says which pattern in the machine description matches
4075 this insn, or @minus{}1 if the matching has not yet been attempted.
4077 Such matching is never attempted and this field remains @minus{}1 on an insn
4078 whose pattern consists of a single @code{use}, @code{clobber},
4079 @code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.
4081 @findex asm_noperands
4082 Matching is also never attempted on insns that result from an @code{asm}
4083 statement. These contain at least one @code{asm_operands} expression.
4084 The function @code{asm_noperands} returns a non-negative value for
4087 In the debugging output, this field is printed as a number followed by
4088 a symbolic representation that locates the pattern in the @file{md}
4089 file as some small positive or negative offset from a named pattern.
4092 @item LOG_LINKS (@var{i})
4093 A list (chain of @code{insn_list} expressions) giving information about
4094 dependencies between instructions within a basic block. Neither a jump
4095 nor a label may come between the related insns. These are only used by
4096 the schedulers and by combine. This is a deprecated data structure.
4097 Def-use and use-def chains are now preferred.
4100 @item REG_NOTES (@var{i})
4101 A list (chain of @code{expr_list}, @code{insn_list} and @code{int_list}
4102 expressions) giving miscellaneous information about the insn. It is often
4103 information pertaining to the registers used in this insn.
4106 The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
4107 expressions. Each of these has two operands: the first is an insn,
4108 and the second is another @code{insn_list} expression (the next one in
4109 the chain). The last @code{insn_list} in the chain has a null pointer
4110 as second operand. The significant thing about the chain is which
4111 insns appear in it (as first operands of @code{insn_list}
4112 expressions). Their order is not significant.
4114 This list is originally set up by the flow analysis pass; it is a null
4115 pointer until then. Flow only adds links for those data dependencies
4116 which can be used for instruction combination. For each insn, the flow
4117 analysis pass adds a link to insns which store into registers values
4118 that are used for the first time in this insn.
4120 The @code{REG_NOTES} field of an insn is a chain similar to the
4121 @code{LOG_LINKS} field but it includes @code{expr_list} and @code{int_list}
4122 expressions in addition to @code{insn_list} expressions. There are several
4123 kinds of register notes, which are distinguished by the machine mode, which
4124 in a register note is really understood as being an @code{enum reg_note}.
4125 The first operand @var{op} of the note is data whose meaning depends on
4128 @findex REG_NOTE_KIND
4129 @findex PUT_REG_NOTE_KIND
4130 The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of
4131 register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND
4132 (@var{x}, @var{newkind})} sets the register note type of @var{x} to be
4135 Register notes are of three classes: They may say something about an
4136 input to an insn, they may say something about an output of an insn, or
4137 they may create a linkage between two insns. There are also a set
4138 of values that are only used in @code{LOG_LINKS}.
4140 These register notes annotate inputs to an insn:
4145 The value in @var{op} dies in this insn; that is to say, altering the
4146 value immediately after this insn would not affect the future behavior
4149 It does not follow that the register @var{op} has no useful value after
4150 this insn since @var{op} is not necessarily modified by this insn.
4151 Rather, no subsequent instruction uses the contents of @var{op}.
4155 The register @var{op} being set by this insn will not be used in a
4156 subsequent insn. This differs from a @code{REG_DEAD} note, which
4157 indicates that the value in an input will not be used subsequently.
4158 These two notes are independent; both may be present for the same
4163 The register @var{op} is incremented (or decremented; at this level
4164 there is no distinction) by an embedded side effect inside this insn.
4165 This means it appears in a @code{post_inc}, @code{pre_inc},
4166 @code{post_dec} or @code{pre_dec} expression.
4170 The register @var{op} is known to have a nonnegative value when this
4171 insn is reached. This is used by special looping instructions
4172 that terminate when the register goes negative.
4174 The @code{REG_NONNEG} note is added only to @samp{doloop_end}
4175 insns, if its pattern uses a @code{ge} condition.
4177 @findex REG_LABEL_OPERAND
4178 @item REG_LABEL_OPERAND
4179 This insn uses @var{op}, a @code{code_label} or a @code{note} of type
4180 @code{NOTE_INSN_DELETED_LABEL}, but is not a @code{jump_insn}, or it
4181 is a @code{jump_insn} that refers to the operand as an ordinary
4182 operand. The label may still eventually be a jump target, but if so
4183 in an indirect jump in a subsequent insn. The presence of this note
4184 allows jump optimization to be aware that @var{op} is, in fact, being
4185 used, and flow optimization to build an accurate flow graph.
4187 @findex REG_LABEL_TARGET
4188 @item REG_LABEL_TARGET
4189 This insn is a @code{jump_insn} but not an @code{addr_vec} or
4190 @code{addr_diff_vec}. It uses @var{op}, a @code{code_label} as a
4191 direct or indirect jump target. Its purpose is similar to that of
4192 @code{REG_LABEL_OPERAND}. This note is only present if the insn has
4193 multiple targets; the last label in the insn (in the highest numbered
4194 insn-field) goes into the @code{JUMP_LABEL} field and does not have a
4195 @code{REG_LABEL_TARGET} note. @xref{Insns, JUMP_LABEL}.
4199 Appears attached to each @code{CALL_INSN} to @code{setjmp} or a
4203 The following notes describe attributes of outputs of an insn:
4210 This note is only valid on an insn that sets only one register and
4211 indicates that that register will be equal to @var{op} at run time; the
4212 scope of this equivalence differs between the two types of notes. The
4213 value which the insn explicitly copies into the register may look
4214 different from @var{op}, but they will be equal at run time. If the
4215 output of the single @code{set} is a @code{strict_low_part} or
4216 @code{zero_extract} expression, the note refers to the register that
4217 is contained in its first operand.
4219 For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout
4220 the entire function, and could validly be replaced in all its
4221 occurrences by @var{op}. (``Validly'' here refers to the data flow of
4222 the program; simple replacement may make some insns invalid.) For
4223 example, when a constant is loaded into a register that is never
4224 assigned any other value, this kind of note is used.
4226 When a parameter is copied into a pseudo-register at entry to a function,
4227 a note of this kind records that the register is equivalent to the stack
4228 slot where the parameter was passed. Although in this case the register
4229 may be set by other insns, it is still valid to replace the register
4230 by the stack slot throughout the function.
4232 A @code{REG_EQUIV} note is also used on an instruction which copies a
4233 register parameter into a pseudo-register at entry to a function, if
4234 there is a stack slot where that parameter could be stored. Although
4235 other insns may set the pseudo-register, it is valid for the compiler to
4236 replace the pseudo-register by stack slot throughout the function,
4237 provided the compiler ensures that the stack slot is properly
4238 initialized by making the replacement in the initial copy instruction as
4239 well. This is used on machines for which the calling convention
4240 allocates stack space for register parameters. See
4241 @code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}.
4243 In the case of @code{REG_EQUAL}, the register that is set by this insn
4244 will be equal to @var{op} at run time at the end of this insn but not
4245 necessarily elsewhere in the function. In this case, @var{op}
4246 is typically an arithmetic expression. For example, when a sequence of
4247 insns such as a library call is used to perform an arithmetic operation,
4248 this kind of note is attached to the insn that produces or copies the
4251 These two notes are used in different ways by the compiler passes.
4252 @code{REG_EQUAL} is used by passes prior to register allocation (such as
4253 common subexpression elimination and loop optimization) to tell them how
4254 to think of that value. @code{REG_EQUIV} notes are used by register
4255 allocation to indicate that there is an available substitute expression
4256 (either a constant or a @code{mem} expression for the location of a
4257 parameter on the stack) that may be used in place of a register if
4258 insufficient registers are available.
4260 Except for stack homes for parameters, which are indicated by a
4261 @code{REG_EQUIV} note and are not useful to the early optimization
4262 passes and pseudo registers that are equivalent to a memory location
4263 throughout their entire life, which is not detected until later in
4264 the compilation, all equivalences are initially indicated by an attached
4265 @code{REG_EQUAL} note. In the early stages of register allocation, a
4266 @code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if
4267 @var{op} is a constant and the insn represents the only set of its
4268 destination register.
4270 Thus, compiler passes prior to register allocation need only check for
4271 @code{REG_EQUAL} notes and passes subsequent to register allocation
4272 need only check for @code{REG_EQUIV} notes.
4275 These notes describe linkages between insns. They occur in pairs: one
4276 insn has one of a pair of notes that points to a second insn, which has
4277 the inverse note pointing back to the first insn.
4280 @findex REG_CC_SETTER
4284 On machines that use @code{cc0}, the insns which set and use @code{cc0}
4285 set and use @code{cc0} are adjacent. However, when branch delay slot
4286 filling is done, this may no longer be true. In this case a
4287 @code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to
4288 point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will
4289 be placed on the insn using @code{cc0} to point to the insn setting
4293 These values are only used in the @code{LOG_LINKS} field, and indicate
4294 the type of dependency that each link represents. Links which indicate
4295 a data dependence (a read after write dependence) do not use any code,
4296 they simply have mode @code{VOIDmode}, and are printed without any
4300 @findex REG_DEP_TRUE
4302 This indicates a true dependence (a read after write dependence).
4304 @findex REG_DEP_OUTPUT
4305 @item REG_DEP_OUTPUT
4306 This indicates an output dependence (a write after write dependence).
4308 @findex REG_DEP_ANTI
4310 This indicates an anti dependence (a write after read dependence).
4314 These notes describe information gathered from gcov profile data. They
4315 are stored in the @code{REG_NOTES} field of an insn.
4320 This is used to specify the ratio of branches to non-branches of a
4321 branch insn according to the profile data. The note is represented
4322 as an @code{int_list} expression whose integer value is an encoding
4323 of @code{profile_probability} type. @code{profile_probability} provide
4324 member function @code{from_reg_br_prob_note} and @code{to_reg_br_prob_note}
4325 to extract and store the probability into the RTL encoding.
4329 These notes are found in JUMP insns after delayed branch scheduling
4330 has taken place. They indicate both the direction and the likelihood
4331 of the JUMP@. The format is a bitmask of ATTR_FLAG_* values.
4333 @findex REG_FRAME_RELATED_EXPR
4334 @item REG_FRAME_RELATED_EXPR
4335 This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression
4336 is used in place of the actual insn pattern. This is done in cases where
4337 the pattern is either complex or misleading.
4340 The note @code{REG_CALL_NOCF_CHECK} is used in conjunction with the
4341 @option{-fcf-protection=branch} option. The note is set if a
4342 @code{nocf_check} attribute is specified for a function type or a
4343 pointer to function type. The note is stored in the @code{REG_NOTES}
4347 @findex REG_CALL_NOCF_CHECK
4348 @item REG_CALL_NOCF_CHECK
4349 Users have control through the @code{nocf_check} attribute to identify
4350 which calls to a function should be skipped from control-flow instrumentation
4351 when the option @option{-fcf-protection=branch} is specified. The compiler
4352 puts a @code{REG_CALL_NOCF_CHECK} note on each @code{CALL_INSN} instruction
4353 that has a function type marked with a @code{nocf_check} attribute.
4356 For convenience, the machine mode in an @code{insn_list} or
4357 @code{expr_list} is printed using these symbolic codes in debugging dumps.
4361 The only difference between the expression codes @code{insn_list} and
4362 @code{expr_list} is that the first operand of an @code{insn_list} is
4363 assumed to be an insn and is printed in debugging dumps as the insn's
4364 unique id; the first operand of an @code{expr_list} is printed in the
4365 ordinary way as an expression.
4368 @section RTL Representation of Function-Call Insns
4369 @cindex calling functions in RTL
4370 @cindex RTL function-call insns
4371 @cindex function-call insns
4373 Insns that call subroutines have the RTL expression code @code{call_insn}.
4374 These insns must satisfy special rules, and their bodies must use a special
4375 RTL expression code, @code{call}.
4377 @cindex @code{call} usage
4378 A @code{call} expression has two operands, as follows:
4381 (call (mem:@var{fm} @var{addr}) @var{nbytes})
4385 Here @var{nbytes} is an operand that represents the number of bytes of
4386 argument data being passed to the subroutine, @var{fm} is a machine mode
4387 (which must equal as the definition of the @code{FUNCTION_MODE} macro in
4388 the machine description) and @var{addr} represents the address of the
4391 For a subroutine that returns no value, the @code{call} expression as
4392 shown above is the entire body of the insn, except that the insn might
4393 also contain @code{use} or @code{clobber} expressions.
4395 @cindex @code{BLKmode}, and function return values
4396 For a subroutine that returns a value whose mode is not @code{BLKmode},
4397 the value is returned in a hard register. If this register's number is
4398 @var{r}, then the body of the call insn looks like this:
4401 (set (reg:@var{m} @var{r})
4402 (call (mem:@var{fm} @var{addr}) @var{nbytes}))
4406 This RTL expression makes it clear (to the optimizer passes) that the
4407 appropriate register receives a useful value in this insn.
4409 When a subroutine returns a @code{BLKmode} value, it is handled by
4410 passing to the subroutine the address of a place to store the value.
4411 So the call insn itself does not ``return'' any value, and it has the
4412 same RTL form as a call that returns nothing.
4414 On some machines, the call instruction itself clobbers some register,
4415 for example to contain the return address. @code{call_insn} insns
4416 on these machines should have a body which is a @code{parallel}
4417 that contains both the @code{call} expression and @code{clobber}
4418 expressions that indicate which registers are destroyed. Similarly,
4419 if the call instruction requires some register other than the stack
4420 pointer that is not explicitly mentioned in its RTL, a @code{use}
4421 subexpression should mention that register.
4423 Functions that are called are assumed to modify all registers listed in
4424 the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register
4425 Basics}) and, with the exception of @code{const} functions and library
4426 calls, to modify all of memory.
4428 Insns containing just @code{use} expressions directly precede the
4429 @code{call_insn} insn to indicate which registers contain inputs to the
4430 function. Similarly, if registers other than those in
4431 @code{CALL_USED_REGISTERS} are clobbered by the called function, insns
4432 containing a single @code{clobber} follow immediately after the call to
4433 indicate which registers.
4436 @section Structure Sharing Assumptions
4437 @cindex sharing of RTL components
4438 @cindex RTL structure sharing assumptions
4440 The compiler assumes that certain kinds of RTL expressions are unique;
4441 there do not exist two distinct objects representing the same value.
4442 In other cases, it makes an opposite assumption: that no RTL expression
4443 object of a certain kind appears in more than one place in the
4444 containing structure.
4446 These assumptions refer to a single function; except for the RTL
4447 objects that describe global variables and external functions,
4448 and a few standard objects such as small integer constants,
4449 no RTL objects are common to two functions.
4452 @cindex @code{reg}, RTL sharing
4454 Each pseudo-register has only a single @code{reg} object to represent it,
4455 and therefore only a single machine mode.
4457 @cindex symbolic label
4458 @cindex @code{symbol_ref}, RTL sharing
4460 For any symbolic label, there is only one @code{symbol_ref} object
4463 @cindex @code{const_int}, RTL sharing
4465 All @code{const_int} expressions with equal values are shared.
4467 @cindex @code{const_poly_int}, RTL sharing
4469 All @code{const_poly_int} expressions with equal modes and values
4472 @cindex @code{pc}, RTL sharing
4474 There is only one @code{pc} expression.
4476 @cindex @code{cc0}, RTL sharing
4478 There is only one @code{cc0} expression.
4480 @cindex @code{const_double}, RTL sharing
4482 There is only one @code{const_double} expression with value 0 for
4483 each floating point mode. Likewise for values 1 and 2.
4485 @cindex @code{const_vector}, RTL sharing
4487 There is only one @code{const_vector} expression with value 0 for
4488 each vector mode, be it an integer or a double constant vector.
4490 @cindex @code{label_ref}, RTL sharing
4491 @cindex @code{scratch}, RTL sharing
4493 No @code{label_ref} or @code{scratch} appears in more than one place in
4494 the RTL structure; in other words, it is safe to do a tree-walk of all
4495 the insns in the function and assume that each time a @code{label_ref}
4496 or @code{scratch} is seen it is distinct from all others that are seen.
4498 @cindex @code{mem}, RTL sharing
4500 Only one @code{mem} object is normally created for each static
4501 variable or stack slot, so these objects are frequently shared in all
4502 the places they appear. However, separate but equal objects for these
4503 variables are occasionally made.
4505 @cindex @code{asm_operands}, RTL sharing
4507 When a single @code{asm} statement has multiple output operands, a
4508 distinct @code{asm_operands} expression is made for each output operand.
4509 However, these all share the vector which contains the sequence of input
4510 operands. This sharing is used later on to test whether two
4511 @code{asm_operands} expressions come from the same statement, so all
4512 optimizations must carefully preserve the sharing if they copy the
4516 No RTL object appears in more than one place in the RTL structure
4517 except as described above. Many passes of the compiler rely on this
4518 by assuming that they can modify RTL objects in place without unwanted
4519 side-effects on other insns.
4521 @findex unshare_all_rtl
4523 During initial RTL generation, shared structure is freely introduced.
4524 After all the RTL for a function has been generated, all shared
4525 structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
4526 after which the above rules are guaranteed to be followed.
4528 @findex copy_rtx_if_shared
4530 During the combiner pass, shared structure within an insn can exist
4531 temporarily. However, the shared structure is copied before the
4532 combiner is finished with the insn. This is done by calling
4533 @code{copy_rtx_if_shared}, which is a subroutine of
4534 @code{unshare_all_rtl}.
4538 @section Reading RTL
4540 To read an RTL object from a file, call @code{read_rtx}. It takes one
4541 argument, a stdio stream, and returns a single RTL object. This routine
4542 is defined in @file{read-rtl.c}. It is not available in the compiler
4543 itself, only the various programs that generate the compiler back end
4544 from the machine description.
4546 People frequently have the idea of using RTL stored as text in a file as
4547 an interface between a language front end and the bulk of GCC@. This
4548 idea is not feasible.
4550 GCC was designed to use RTL internally only. Correct RTL for a given
4551 program is very dependent on the particular target machine. And the RTL
4552 does not contain all the information about the program.
4554 The proper way to interface GCC to a new language front end is with
4555 the ``tree'' data structure, described in the files @file{tree.h} and
4556 @file{tree.def}. The documentation for this structure (@pxref{GENERIC})