1 @c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002, 2003
2 @c Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
7 @chapter RTL Representation
8 @cindex RTL representation
9 @cindex representation of RTL
10 @cindex Register Transfer Language (RTL)
12 Most of the work of the compiler is done on an intermediate representation
13 called register transfer language. In this language, the instructions to be
14 output are described, pretty much one by one, in an algebraic form that
15 describes what the instruction does.
17 RTL is inspired by Lisp lists. It has both an internal form, made up of
18 structures that point at other structures, and a textual form that is used
19 in the machine description and in printed debugging dumps. The textual
20 form uses nested parentheses to indicate the pointers in the internal form.
23 * RTL Objects:: Expressions vs vectors vs strings vs integers.
24 * RTL Classes:: Categories of RTL expression objects, and their structure.
25 * Accessors:: Macros to access expression operands or vector elts.
26 * Special Accessors:: Macros to access specific annotations on RTL.
27 * Flags:: Other flags in an RTL expression.
28 * Machine Modes:: Describing the size and format of a datum.
29 * Constants:: Expressions with constant values.
30 * Regs and Memory:: Expressions representing register contents or memory.
31 * Arithmetic:: Expressions representing arithmetic on other expressions.
32 * Comparisons:: Expressions representing comparison of expressions.
33 * Bit-Fields:: Expressions representing bit-fields in memory or reg.
34 * Vector Operations:: Expressions involving vector datatypes.
35 * Conversions:: Extending, truncating, floating or fixing.
36 * RTL Declarations:: Declaring volatility, constancy, etc.
37 * Side Effects:: Expressions for storing in registers, etc.
38 * Incdec:: Embedded side-effects for autoincrement addressing.
39 * Assembler:: Representing @code{asm} with operands.
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 upper case) 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 an integer. In
113 an expression of code @code{plus}, there are two operands, both of which
114 are to be regarded as expressions. In a @code{symbol_ref} expression,
115 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 lower case,
122 but when they appear in C code they are written in upper case. 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{rtx.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 Constants and basic transforms on objects (@code{ADDRESSOF},
147 @code{HIGH}, @code{LO_SUM}) are also included. Note that @code{SUBREG}
148 and @code{STRICT_LOW_PART} are not in this class, but in class @code{x}.
151 An RTX code for a comparison, such as @code{NE} or @code{LT}.
154 An RTX code for a unary arithmetic operation, such as @code{NEG},
155 @code{NOT}, or @code{ABS}. This category also includes value extension
156 (sign or zero) and conversions between integer and floating point.
159 An RTX code for a commutative binary operation, such as @code{PLUS} or
160 @code{AND}. @code{NE} and @code{EQ} are comparisons, so they have class
164 An RTX code for a non-commutative binary operation, such as @code{MINUS},
165 @code{DIV}, or @code{ASHIFTRT}.
168 An RTX code for a bit-field operation. Currently only
169 @code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}. These have three inputs
170 and are lvalues (so they can be used for insertion as well).
174 An RTX code for other three input operations. Currently only
178 An RTX code for an entire instruction: @code{INSN}, @code{JUMP_INSN}, and
179 @code{CALL_INSN}. @xref{Insns}.
182 An RTX code for something that matches in insns, such as
183 @code{MATCH_DUP}. These only occur in machine descriptions.
186 An RTX code for an auto-increment addressing mode, such as
190 All other RTX codes. This category includes the remaining codes used
191 only in machine descriptions (@code{DEFINE_*}, etc.). It also includes
192 all the codes describing side effects (@code{SET}, @code{USE},
193 @code{CLOBBER}, etc.) and the non-insns that may appear on an insn
194 chain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}.
198 For each expression code, @file{rtl.def} specifies the number of
199 contained objects and their kinds using a sequence of characters
200 called the @dfn{format} of the expression code. For example,
201 the format of @code{subreg} is @samp{ei}.
203 @cindex RTL format characters
204 These are the most commonly used format characters:
208 An expression (actually a pointer to an expression).
220 A vector of expressions.
223 A few other format characters are used occasionally:
227 @samp{u} is equivalent to @samp{e} except that it is printed differently
228 in debugging dumps. It is used for pointers to insns.
231 @samp{n} is equivalent to @samp{i} except that it is printed differently
232 in debugging dumps. It is used for the line number or code number of a
236 @samp{S} indicates a string which is optional. In the RTL objects in
237 core, @samp{S} is equivalent to @samp{s}, but when the object is read,
238 from an @samp{md} file, the string value of this operand may be omitted.
239 An omitted string is taken to be the null string.
242 @samp{V} indicates a vector which is optional. In the RTL objects in
243 core, @samp{V} is equivalent to @samp{E}, but when the object is read
244 from an @samp{md} file, the vector value of this operand may be omitted.
245 An omitted vector is effectively the same as a vector of no elements.
248 @samp{B} indicates a pointer to basic block structure.
251 @samp{0} means a slot whose contents do not fit any normal category.
252 @samp{0} slots are not printed at all in dumps, and are often used in
253 special ways by small parts of the compiler.
256 There are macros to get the number of operands and the format
257 of an expression code:
260 @findex GET_RTX_LENGTH
261 @item GET_RTX_LENGTH (@var{code})
262 Number of operands of an RTX of code @var{code}.
264 @findex GET_RTX_FORMAT
265 @item GET_RTX_FORMAT (@var{code})
266 The format of an RTX of code @var{code}, as a C string.
269 Some classes of RTX codes always have the same format. For example, it
270 is safe to assume that all comparison operations have format @code{ee}.
274 All codes of this class have format @code{e}.
279 All codes of these classes have format @code{ee}.
283 All codes of these classes have format @code{eee}.
286 All codes of this class have formats that begin with @code{iuueiee}.
287 @xref{Insns}. Note that not all RTL objects linked onto an insn chain
288 are of class @code{i}.
293 You can make no assumptions about the format of these codes.
297 @section Access to Operands
299 @cindex access to operands
300 @cindex operand access
306 Operands of expressions are accessed using the macros @code{XEXP},
307 @code{XINT}, @code{XWINT} and @code{XSTR}. Each of these macros takes
308 two arguments: an expression-pointer (RTX) and an operand number
309 (counting from zero). Thus,
316 accesses operand 2 of expression @var{x}, as an expression.
323 accesses the same operand as an integer. @code{XSTR}, used in the same
324 fashion, would access it as a string.
326 Any operand can be accessed as an integer, as an expression or as a string.
327 You must choose the correct method of access for the kind of value actually
328 stored in the operand. You would do this based on the expression code of
329 the containing expression. That is also how you would know how many
332 For example, if @var{x} is a @code{subreg} expression, you know that it has
333 two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
334 and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you
335 would get the address of the expression operand but cast as an integer;
336 that might occasionally be useful, but it would be cleaner to write
337 @code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also
338 compile without error, and would return the second, integer operand cast as
339 an expression pointer, which would probably result in a crash when
340 accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
341 but this will access memory past the end of the expression with
342 unpredictable results.
344 Access to operands which are vectors is more complicated. You can use the
345 macro @code{XVEC} to get the vector-pointer itself, or the macros
346 @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
351 @item XVEC (@var{exp}, @var{idx})
352 Access the vector-pointer which is operand number @var{idx} in @var{exp}.
355 @item XVECLEN (@var{exp}, @var{idx})
356 Access the length (number of elements) in the vector which is
357 in operand number @var{idx} in @var{exp}. This value is an @code{int}.
360 @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
361 Access element number @var{eltnum} in the vector which is
362 in operand number @var{idx} in @var{exp}. This value is an RTX@.
364 It is up to you to make sure that @var{eltnum} is not negative
365 and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
368 All the macros defined in this section expand into lvalues and therefore
369 can be used to assign the operands, lengths and vector elements as well as
372 @node Special Accessors
373 @section Access to Special Operands
374 @cindex access to special operands
376 Some RTL nodes have special annotations associated with them.
381 @findex MEM_ALIAS_SET
382 @item MEM_ALIAS_SET (@var{x})
383 If 0, @var{x} is not in any alias set, and may alias anything. Otherwise,
384 @var{x} can only alias @code{MEM}s in a conflicting alias set. This value
385 is set in a language-dependent manner in the front-end, and should not be
386 altered in the back-end. In some front-ends, these numbers may correspond
387 in some way to types, or other language-level entities, but they need not,
388 and the back-end makes no such assumptions.
389 These set numbers are tested with @code{alias_sets_conflict_p}.
392 @item MEM_EXPR (@var{x})
393 If this register is known to hold the value of some user-level
394 declaration, this is that tree node. It may also be a
395 @code{COMPONENT_REF}, in which case this is some field reference,
396 and @code{TREE_OPERAND (@var{x}, 0)} contains the declaration,
397 or another @code{COMPONENT_REF}, or null if there is no compile-time
398 object associated with the reference.
401 @item MEM_OFFSET (@var{x})
402 The offset from the start of @code{MEM_EXPR} as a @code{CONST_INT} rtx.
405 @item MEM_SIZE (@var{x})
406 The size in bytes of the memory reference as a @code{CONST_INT} rtx.
407 This is mostly relevant for @code{BLKmode} references as otherwise
408 the size is implied by the mode.
411 @item MEM_ALIGN (@var{x})
412 The known alignment in bits of the memory reference.
417 @findex ORIGINAL_REGNO
418 @item ORIGINAL_REGNO (@var{x})
419 This field holds the number the register ``originally'' had; for a
420 pseudo register turned into a hard reg this will hold the old pseudo
424 @item REG_EXPR (@var{x})
425 If this register is known to hold the value of some user-level
426 declaration, this is that tree node.
429 @item REG_OFFSET (@var{x})
430 If this register is known to hold the value of some user-level
431 declaration, this is the offset into that logical storage.
436 @findex SYMBOL_REF_DECL
437 @item SYMBOL_REF_DECL (@var{x})
438 If the @code{symbol_ref} @var{x} was created for a @code{VAR_DECL} or
439 a @code{FUNCTION_DECL}, that tree is recorded here. If this value is
440 null, then @var{x} was created by back end code generation routines,
441 and so there is no associated front end symbol table entry.
443 @findex SYMBOL_REF_FLAGS
444 @item SYMBOL_REF_FLAGS (@var{x})
445 In a @code{symbol_ref}, this is used to communicate various predicates
446 about the symbol. Some of these are common enough to be computed by
447 common code, some are specific to the target. The common bits are:
450 @findex SYMBOL_REF_FUNCTION_P
451 @findex SYMBOL_FLAG_FUNCTION
452 @item SYMBOL_FLAG_FUNCTION
453 Set if the symbol refers to a function.
455 @findex SYMBOL_REF_LOCAL_P
456 @findex SYMBOL_FLAG_LOCAL
457 @item SYMBOL_FLAG_LOCAL
458 Set if the symbol is local to this ``module''.
459 See @code{TARGET_BINDS_LOCAL_P}.
461 @findex SYMBOL_REF_EXTERNAL_P
462 @findex SYMBOL_FLAG_EXTERNAL
463 @item SYMBOL_FLAG_EXTERNAL
464 Set if this symbol is not defined in this translation unit.
465 Note that this is not the inverse of @code{SYMBOL_FLAG_LOCAL}.
467 @findex SYMBOL_REF_SMALL_P
468 @findex SYMBOL_FLAG_SMALL
469 @item SYMBOL_FLAG_SMALL
470 Set if the symbol is located in the small data section.
471 See @code{TARGET_IN_SMALL_DATA_P}.
473 @findex SYMBOL_FLAG_TLS_SHIFT
474 @findex SYMBOL_REF_TLS_MODEL
475 @item SYMBOL_REF_TLS_MODEL (@var{x})
476 This is a multi-bit field accessor that returns the @code{tls_model}
477 to be used for a thread-local storage symbol. It returns zero for
478 non-thread-local symbols.
481 Bits beginning with @code{SYMBOL_FLAG_MACH_DEP} are available for
487 @section Flags in an RTL Expression
488 @cindex flags in RTL expression
490 RTL expressions contain several flags (one-bit bit-fields)
491 that are used in certain types of expression. Most often they
492 are accessed with the following macros, which expand into lvalues.
495 @findex CONSTANT_POOL_ADDRESS_P
496 @cindex @code{symbol_ref} and @samp{/u}
497 @cindex @code{unchanging}, in @code{symbol_ref}
498 @item CONSTANT_POOL_ADDRESS_P (@var{x})
499 Nonzero in a @code{symbol_ref} if it refers to part of the current
500 function's constant pool. For most targets these addresses are in a
501 @code{.rodata} section entirely separate from the function, but for
502 some targets the addresses are close to the beginning of the function.
503 In either case GCC assumes these addresses can be addressed directly,
504 perhaps with the help of base registers.
505 Stored in the @code{unchanging} field and printed as @samp{/u}.
507 @findex CONST_OR_PURE_CALL_P
508 @cindex @code{call_insn} and @samp{/u}
509 @cindex @code{unchanging}, in @code{call_insn}
510 @item CONST_OR_PURE_CALL_P (@var{x})
511 In a @code{call_insn}, @code{note}, or an @code{expr_list} for notes,
512 indicates that the insn represents a call to a const or pure function.
513 Stored in the @code{unchanging} field and printed as @samp{/u}.
515 @findex INSN_ANNULLED_BRANCH_P
516 @cindex @code{jump_insn} and @samp{/u}
517 @cindex @code{call_insn} and @samp{/u}
518 @cindex @code{insn} and @samp{/u}
519 @cindex @code{unchanging}, in @code{jump_insn}, @code{call_insn} and @code{insn}
520 @item INSN_ANNULLED_BRANCH_P (@var{x})
521 In a @code{jump_insn}, @code{call_insn}, or @code{insn} indicates
522 that the branch is an annulling one. See the discussion under
523 @code{sequence} below. Stored in the @code{unchanging} field and
524 printed as @samp{/u}.
526 @findex INSN_DEAD_CODE_P
527 @cindex @code{insn} and @samp{/s}
528 @cindex @code{in_struct}, in @code{insn}
529 @item INSN_DEAD_CODE_P (@var{x})
530 In an @code{insn} during the dead-code elimination pass, nonzero if the
532 Stored in the @code{in_struct} field and printed as @samp{/s}.
534 @findex INSN_DELETED_P
535 @cindex @code{insn} and @samp{/v}
536 @cindex @code{call_insn} and @samp{/v}
537 @cindex @code{jump_insn} and @samp{/v}
538 @cindex @code{code_label} and @samp{/v}
539 @cindex @code{barrier} and @samp{/v}
540 @cindex @code{note} and @samp{/v}
541 @cindex @code{volatil}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, @code{barrier}, and @code{note}
542 @item INSN_DELETED_P (@var{x})
543 In an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label},
544 @code{barrier}, or @code{note},
545 nonzero if the insn has been deleted. Stored in the
546 @code{volatil} field and printed as @samp{/v}.
548 @findex INSN_FROM_TARGET_P
549 @cindex @code{insn} and @samp{/s}
550 @cindex @code{jump_insn} and @samp{/s}
551 @cindex @code{call_insn} and @samp{/s}
552 @cindex @code{in_struct}, in @code{insn} and @code{jump_insn} and @code{call_insn}
553 @item INSN_FROM_TARGET_P (@var{x})
554 In an @code{insn} or @code{jump_insn} or @code{call_insn} in a delay
555 slot of a branch, indicates that the insn
556 is from the target of the branch. If the branch insn has
557 @code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if
558 the branch is taken. For annulled branches with
559 @code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the
560 branch is not taken. When @code{INSN_ANNULLED_BRANCH_P} is not set,
561 this insn will always be executed. Stored in the @code{in_struct}
562 field and printed as @samp{/s}.
564 @findex LABEL_OUTSIDE_LOOP_P
565 @cindex @code{label_ref} and @samp{/s}
566 @cindex @code{in_struct}, in @code{label_ref}
567 @item LABEL_OUTSIDE_LOOP_P (@var{x})
568 In @code{label_ref} expressions, nonzero if this is a reference to a
569 label that is outside the innermost loop containing the reference to the
570 label. Stored in the @code{in_struct} field and printed as @samp{/s}.
572 @findex LABEL_PRESERVE_P
573 @cindex @code{code_label} and @samp{/i}
574 @cindex @code{note} and @samp{/i}
575 @cindex @code{in_struct}, in @code{code_label} and @code{note}
576 @item LABEL_PRESERVE_P (@var{x})
577 In a @code{code_label} or @code{note}, indicates that the label is referenced by
578 code or data not visible to the RTL of a given function.
579 Labels referenced by a non-local goto will have this bit set. Stored
580 in the @code{in_struct} field and printed as @samp{/s}.
582 @findex LABEL_REF_NONLOCAL_P
583 @cindex @code{label_ref} and @samp{/v}
584 @cindex @code{reg_label} and @samp{/v}
585 @cindex @code{volatil}, in @code{label_ref} and @code{reg_label}
586 @item LABEL_REF_NONLOCAL_P (@var{x})
587 In @code{label_ref} and @code{reg_label} expressions, nonzero if this is
588 a reference to a non-local label.
589 Stored in the @code{volatil} field and printed as @samp{/v}.
591 @findex MEM_IN_STRUCT_P
592 @cindex @code{mem} and @samp{/s}
593 @cindex @code{in_struct}, in @code{mem}
594 @item MEM_IN_STRUCT_P (@var{x})
595 In @code{mem} expressions, nonzero for reference to an entire structure,
596 union or array, or to a component of one. Zero for references to a
597 scalar variable or through a pointer to a scalar. If both this flag and
598 @code{MEM_SCALAR_P} are clear, then we don't know whether this @code{mem}
599 is in a structure or not. Both flags should never be simultaneously set.
600 Stored in the @code{in_struct} field and printed as @samp{/s}.
602 @findex MEM_KEEP_ALIAS_SET_P
603 @cindex @code{mem} and @samp{/j}
604 @cindex @code{jump}, in @code{mem}
605 @item MEM_KEEP_ALIAS_SET_P (@var{x})
606 In @code{mem} expressions, 1 if we should keep the alias set for this
607 mem unchanged when we access a component. Set to 1, for example, when we
608 are already in a non-addressable component of an aggregate.
609 Stored in the @code{jump} field and printed as @samp{/j}.
612 @cindex @code{mem} and @samp{/f}
613 @cindex @code{frame_related}, in @code{mem}
614 @item MEM_SCALAR_P (@var{x})
615 In @code{mem} expressions, nonzero for reference to a scalar known not
616 to be a member of a structure, union, or array. Zero for such
617 references and for indirections through pointers, even pointers pointing
618 to scalar types. If both this flag and @code{MEM_IN_STRUCT_P} are clear,
619 then we don't know whether this @code{mem} is in a structure or not.
620 Both flags should never be simultaneously set.
621 Stored in the @code{frame_related} field and printed as @samp{/f}.
623 @findex MEM_VOLATILE_P
624 @cindex @code{mem} and @samp{/v}
625 @cindex @code{asm_input} and @samp{/v}
626 @cindex @code{asm_operands} and @samp{/v}
627 @cindex @code{volatil}, in @code{mem}, @code{asm_operands}, and @code{asm_input}
628 @item MEM_VOLATILE_P (@var{x})
629 In @code{mem}, @code{asm_operands}, and @code{asm_input} expressions,
630 nonzero for volatile memory references.
631 Stored in the @code{volatil} field and printed as @samp{/v}.
634 @cindex @code{mem} and @samp{/c}
635 @cindex @code{call}, in @code{mem}
636 @item MEM_NOTRAP_P (@var{x})
637 In @code{mem}, nonzero for memory references that will not trap.
638 Stored in the @code{call} field and printed as @samp{/c}.
640 @findex REG_FUNCTION_VALUE_P
641 @cindex @code{reg} and @samp{/i}
642 @cindex @code{integrated}, in @code{reg}
643 @item REG_FUNCTION_VALUE_P (@var{x})
644 Nonzero in a @code{reg} if it is the place in which this function's
645 value is going to be returned. (This happens only in a hard
646 register.) Stored in the @code{integrated} field and printed as
649 @findex REG_LOOP_TEST_P
650 @cindex @code{reg} and @samp{/s}
651 @cindex @code{in_struct}, in @code{reg}
652 @item REG_LOOP_TEST_P (@var{x})
653 In @code{reg} expressions, nonzero if this register's entire life is
654 contained in the exit test code for some loop. Stored in the
655 @code{in_struct} field and printed as @samp{/s}.
658 @cindex @code{reg} and @samp{/f}
659 @cindex @code{frame_related}, in @code{reg}
660 @item REG_POINTER (@var{x})
661 Nonzero in a @code{reg} if the register holds a pointer. Stored in the
662 @code{frame_related} field and printed as @samp{/f}.
664 @findex REG_USERVAR_P
665 @cindex @code{reg} and @samp{/v}
666 @cindex @code{volatil}, in @code{reg}
667 @item REG_USERVAR_P (@var{x})
668 In a @code{reg}, nonzero if it corresponds to a variable present in
669 the user's source code. Zero for temporaries generated internally by
670 the compiler. Stored in the @code{volatil} field and printed as
673 The same hard register may be used also for collecting the values of
674 functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
677 @findex RTX_FRAME_RELATED_P
678 @cindex @code{insn} and @samp{/f}
679 @cindex @code{call_insn} and @samp{/f}
680 @cindex @code{jump_insn} and @samp{/f}
681 @cindex @code{barrier} and @samp{/f}
682 @cindex @code{set} and @samp{/f}
683 @cindex @code{frame_related}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, and @code{set}
684 @item RTX_FRAME_RELATED_P (@var{x})
685 Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn},
686 @code{barrier}, or @code{set} which is part of a function prologue
687 and sets the stack pointer, sets the frame pointer, or saves a register.
688 This flag should also be set on an instruction that sets up a temporary
689 register to use in place of the frame pointer.
690 Stored in the @code{frame_related} field and printed as @samp{/f}.
692 In particular, on RISC targets where there are limits on the sizes of
693 immediate constants, it is sometimes impossible to reach the register
694 save area directly from the stack pointer. In that case, a temporary
695 register is used that is near enough to the register save area, and the
696 Canonical Frame Address, i.e., DWARF2's logical frame pointer, register
697 must (temporarily) be changed to be this temporary register. So, the
698 instruction that sets this temporary register must be marked as
699 @code{RTX_FRAME_RELATED_P}.
701 If the marked instruction is overly complex (defined in terms of what
702 @code{dwarf2out_frame_debug_expr} can handle), you will also have to
703 create a @code{REG_FRAME_RELATED_EXPR} note and attach it to the
704 instruction. This note should contain a simple expression of the
705 computation performed by this instruction, i.e., one that
706 @code{dwarf2out_frame_debug_expr} can handle.
708 This flag is required for exception handling support on targets with RTL
711 @findex RTX_INTEGRATED_P
712 @cindex @code{insn} and @samp{/i}
713 @cindex @code{call_insn} and @samp{/i}
714 @cindex @code{jump_insn} and @samp{/i}
715 @cindex @code{barrier} and @samp{/i}
716 @cindex @code{code_label} and @samp{/i}
717 @cindex @code{insn_list} and @samp{/i}
718 @cindex @code{const} and @samp{/i}
719 @cindex @code{note} and @samp{/i}
720 @cindex @code{integrated}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, @code{code_label}, @code{insn_list}, @code{const}, and @code{note}
721 @item RTX_INTEGRATED_P (@var{x})
722 Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier},
723 @code{code_label}, @code{insn_list}, @code{const}, or @code{note} if it
724 resulted from an in-line function call.
725 Stored in the @code{integrated} field and printed as @samp{/i}.
727 @findex RTX_UNCHANGING_P
728 @cindex @code{reg} and @samp{/u}
729 @cindex @code{mem} and @samp{/u}
730 @cindex @code{concat} and @samp{/u}
731 @cindex @code{unchanging}, in @code{reg} and @code{mem}
732 @item RTX_UNCHANGING_P (@var{x})
733 Nonzero in a @code{reg}, @code{mem}, or @code{concat} if the register or
734 memory is set at most once, anywhere. This does not mean that it is
737 GCC uses this flag to determine whether two references conflict. As
738 implemented by @code{true_dependence} in @file{alias.c} for memory
739 references, unchanging memory can't conflict with non-unchanging memory;
740 a non-unchanging read can conflict with a non-unchanging write; an
741 unchanging read can conflict with an unchanging write (since there may
742 be a single store to this address to initialize it); and an unchanging
743 store can conflict with a non-unchanging read. This means we must make
744 conservative assumptions when chosing the value of this flag for a
745 memory reference to an object containing both unchanging and
746 non-unchanging fields: we must set the flag when writing to the object
747 and clear it when reading from the object.
749 Stored in the @code{unchanging} field and printed as @samp{/u}.
751 @findex SCHED_GROUP_P
752 @cindex @code{insn} and @samp{/s}
753 @cindex @code{call_insn} and @samp{/s}
754 @cindex @code{jump_insn} and @samp{/s}
755 @cindex @code{in_struct}, in @code{insn}, @code{jump_insn} and @code{call_insn}
756 @item SCHED_GROUP_P (@var{x})
757 During instruction scheduling, in an @code{insn}, @code{call_insn} or
758 @code{jump_insn}, indicates that the
759 previous insn must be scheduled together with this insn. This is used to
760 ensure that certain groups of instructions will not be split up by the
761 instruction scheduling pass, for example, @code{use} insns before
762 a @code{call_insn} may not be separated from the @code{call_insn}.
763 Stored in the @code{in_struct} field and printed as @samp{/s}.
765 @findex SET_IS_RETURN_P
766 @cindex @code{insn} and @samp{/j}
767 @cindex @code{jump}, in @code{insn}
768 @item SET_IS_RETURN_P (@var{x})
769 For a @code{set}, nonzero if it is for a return.
770 Stored in the @code{jump} field and printed as @samp{/j}.
772 @findex SIBLING_CALL_P
773 @cindex @code{call_insn} and @samp{/j}
774 @cindex @code{jump}, in @code{call_insn}
775 @item SIBLING_CALL_P (@var{x})
776 For a @code{call_insn}, nonzero if the insn is a sibling call.
777 Stored in the @code{jump} field and printed as @samp{/j}.
779 @findex STRING_POOL_ADDRESS_P
780 @cindex @code{symbol_ref} and @samp{/f}
781 @cindex @code{frame_related}, in @code{symbol_ref}
782 @item STRING_POOL_ADDRESS_P (@var{x})
783 For a @code{symbol_ref} expression, nonzero if it addresses this function's
784 string constant pool.
785 Stored in the @code{frame_related} field and printed as @samp{/f}.
787 @findex SUBREG_PROMOTED_UNSIGNED_P
788 @cindex @code{subreg} and @samp{/u} and @samp{/v}
789 @cindex @code{unchanging}, in @code{subreg}
790 @cindex @code{volatil}, in @code{subreg}
791 @item SUBREG_PROMOTED_UNSIGNED_P (@var{x})
792 Returns a value greater then zero for a @code{subreg} that has
793 @code{SUBREG_PROMOTED_VAR_P} nonzero if the object being referenced is kept
794 zero-extended, zero if it is kept sign-extended, and less then zero if it is
795 extended some other way via the @code{ptr_extend} instruction.
796 Stored in the @code{unchanging}
797 field and @code{volatil} field, printed as @samp{/u} and @samp{/v}.
798 This macro may only be used to get the value it may not be used to change
799 the value. Use @code{SUBREG_PROMOTED_UNSIGNED_SET} to change the value.
801 @findex SUBREG_PROMOTED_UNSIGNED_SET
802 @cindex @code{subreg} and @samp{/u}
803 @cindex @code{unchanging}, in @code{subreg}
804 @cindex @code{volatil}, in @code{subreg}
805 @item SUBREG_PROMOTED_UNSIGNED_SET (@var{x})
806 Set the @code{unchanging} and @code{volatil} fields in a @code{subreg}
807 to reflect zero, sign, or other extension. If @code{volatil} is
808 zero, then @code{unchanging} as nonzero means zero extension and as
809 zero means sign extension. If @code{volatil} is nonzero then some
810 other type of extension was done via the @code{ptr_extend} instruction.
812 @findex SUBREG_PROMOTED_VAR_P
813 @cindex @code{subreg} and @samp{/s}
814 @cindex @code{in_struct}, in @code{subreg}
815 @item SUBREG_PROMOTED_VAR_P (@var{x})
816 Nonzero in a @code{subreg} if it was made when accessing an object that
817 was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine
818 description macro (@pxref{Storage Layout}). In this case, the mode of
819 the @code{subreg} is the declared mode of the object and the mode of
820 @code{SUBREG_REG} is the mode of the register that holds the object.
821 Promoted variables are always either sign- or zero-extended to the wider
822 mode on every assignment. Stored in the @code{in_struct} field and
823 printed as @samp{/s}.
825 @findex SYMBOL_REF_USED
826 @cindex @code{used}, in @code{symbol_ref}
827 @item SYMBOL_REF_USED (@var{x})
828 In a @code{symbol_ref}, indicates that @var{x} has been used. This is
829 normally only used to ensure that @var{x} is only declared external
830 once. Stored in the @code{used} field.
832 @findex SYMBOL_REF_WEAK
833 @cindex @code{symbol_ref} and @samp{/i}
834 @cindex @code{integrated}, in @code{symbol_ref}
835 @item SYMBOL_REF_WEAK (@var{x})
836 In a @code{symbol_ref}, indicates that @var{x} has been declared weak.
837 Stored in the @code{integrated} field and printed as @samp{/i}.
839 @findex SYMBOL_REF_FLAG
840 @cindex @code{symbol_ref} and @samp{/v}
841 @cindex @code{volatil}, in @code{symbol_ref}
842 @item SYMBOL_REF_FLAG (@var{x})
843 In a @code{symbol_ref}, this is used as a flag for machine-specific purposes.
844 Stored in the @code{volatil} field and printed as @samp{/v}.
846 Most uses of @code{SYMBOL_REF_FLAG} are historic and may be subsumed
847 by @code{SYMBOL_REF_FLAGS}. Certainly use of @code{SYMBOL_REF_FLAGS}
848 is mandatory if the target requires more than one bit of storage.
851 These are the fields to which the above macros refer:
855 @cindex @samp{/c} in RTL dump
857 In a @code{mem}, 1 means that the memory reference will not trap.
859 In an RTL dump, this flag is represented as @samp{/c}.
861 @findex frame_related
862 @cindex @samp{/f} in RTL dump
864 In an @code{insn} or @code{set} expression, 1 means that it is part of
865 a function prologue and sets the stack pointer, sets the frame pointer,
866 saves a register, or sets up a temporary register to use in place of the
869 In @code{reg} expressions, 1 means that the register holds a pointer.
871 In @code{symbol_ref} expressions, 1 means that the reference addresses
872 this function's string constant pool.
874 In @code{mem} expressions, 1 means that the reference is to a scalar.
876 In an RTL dump, this flag is represented as @samp{/f}.
879 @cindex @samp{/s} in RTL dump
881 In @code{mem} expressions, it is 1 if the memory datum referred to is
882 all or part of a structure or array; 0 if it is (or might be) a scalar
883 variable. A reference through a C pointer has 0 because the pointer
884 might point to a scalar variable. This information allows the compiler
885 to determine something about possible cases of aliasing.
887 In @code{reg} expressions, it is 1 if the register has its entire life
888 contained within the test expression of some loop.
890 In @code{subreg} expressions, 1 means that the @code{subreg} is accessing
891 an object that has had its mode promoted from a wider mode.
893 In @code{label_ref} expressions, 1 means that the referenced label is
894 outside the innermost loop containing the insn in which the @code{label_ref}
897 In @code{code_label} expressions, it is 1 if the label may never be deleted.
898 This is used for labels which are the target of non-local gotos. Such a
899 label that would have been deleted is replaced with a @code{note} of type
900 @code{NOTE_INSN_DELETED_LABEL}.
902 In an @code{insn} during dead-code elimination, 1 means that the insn is
905 In an @code{insn} or @code{jump_insn} during reorg for an insn in the
906 delay slot of a branch,
907 1 means that this insn is from the target of the branch.
909 In an @code{insn} during instruction scheduling, 1 means that this insn
910 must be scheduled as part of a group together with the previous insn.
912 In an RTL dump, this flag is represented as @samp{/s}.
915 @cindex @samp{/i} in RTL dump
917 In an @code{insn}, @code{insn_list}, or @code{const}, 1 means the RTL was
918 produced by procedure integration.
920 In @code{reg} expressions, 1 means the register contains
921 the value to be returned by the current function. On
922 machines that pass parameters in registers, the same register number
923 may be used for parameters as well, but this flag is not set on such
926 In @code{symbol_ref} expressions, 1 means the referenced symbol is weak.
928 In an RTL dump, this flag is represented as @samp{/i}.
931 @cindex @samp{/j} in RTL dump
933 In a @code{mem} expression, 1 means we should keep the alias set for this
934 mem unchanged when we access a component.
936 In a @code{set}, 1 means it is for a return.
938 In a @code{call_insn}, 1 means it is a sibling call.
940 In an RTL dump, this flag is represented as @samp{/j}.
943 @cindex @samp{/u} in RTL dump
945 In @code{reg} and @code{mem} expressions, 1 means
946 that the value of the expression never changes.
948 In @code{subreg} expressions, it is 1 if the @code{subreg} references an
949 unsigned object whose mode has been promoted to a wider mode.
951 In an @code{insn} or @code{jump_insn} in the delay slot of a branch
952 instruction, 1 means an annulling branch should be used.
954 In a @code{symbol_ref} expression, 1 means that this symbol addresses
955 something in the per-function constant pool.
957 In a @code{call_insn}, @code{note}, or an @code{expr_list} of notes,
958 1 means that this instruction is a call to a const or pure function.
960 In an RTL dump, this flag is represented as @samp{/u}.
964 This flag is used directly (without an access macro) at the end of RTL
965 generation for a function, to count the number of times an expression
966 appears in insns. Expressions that appear more than once are copied,
967 according to the rules for shared structure (@pxref{Sharing}).
969 For a @code{reg}, it is used directly (without an access macro) by the
970 leaf register renumbering code to ensure that each register is only
973 In a @code{symbol_ref}, it indicates that an external declaration for
974 the symbol has already been written.
977 @cindex @samp{/v} in RTL dump
979 @cindex volatile memory references
980 In a @code{mem}, @code{asm_operands}, or @code{asm_input}
981 expression, it is 1 if the memory
982 reference is volatile. Volatile memory references may not be deleted,
983 reordered or combined.
985 In a @code{symbol_ref} expression, it is used for machine-specific
988 In a @code{reg} expression, it is 1 if the value is a user-level variable.
989 0 indicates an internal compiler temporary.
991 In an @code{insn}, 1 means the insn has been deleted.
993 In @code{label_ref} and @code{reg_label} expressions, 1 means a reference
994 to a non-local label.
996 In an RTL dump, this flag is represented as @samp{/v}.
1000 @section Machine Modes
1001 @cindex machine modes
1003 @findex enum machine_mode
1004 A machine mode describes a size of data object and the representation used
1005 for it. In the C code, machine modes are represented by an enumeration
1006 type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL
1007 expression has room for a machine mode and so do certain kinds of tree
1008 expressions (declarations and types, to be precise).
1010 In debugging dumps and machine descriptions, the machine mode of an RTL
1011 expression is written after the expression code with a colon to separate
1012 them. The letters @samp{mode} which appear at the end of each machine mode
1013 name are omitted. For example, @code{(reg:SI 38)} is a @code{reg}
1014 expression with machine mode @code{SImode}. If the mode is
1015 @code{VOIDmode}, it is not written at all.
1017 Here is a table of machine modes. The term ``byte'' below refers to an
1018 object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}).
1023 ``Bit'' mode represents a single bit, for predicate registers.
1027 ``Quarter-Integer'' mode represents a single byte treated as an integer.
1031 ``Half-Integer'' mode represents a two-byte integer.
1035 ``Partial Single Integer'' mode represents an integer which occupies
1036 four bytes but which doesn't really use all four. On some machines,
1037 this is the right mode to use for pointers.
1041 ``Single Integer'' mode represents a four-byte integer.
1045 ``Partial Double Integer'' mode represents an integer which occupies
1046 eight bytes but which doesn't really use all eight. On some machines,
1047 this is the right mode to use for certain pointers.
1051 ``Double Integer'' mode represents an eight-byte integer.
1055 ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
1059 ``Octa Integer'' (?) mode represents a thirty-two-byte integer.
1063 ``Quarter-Floating'' mode represents a quarter-precision (single byte)
1064 floating point number.
1068 ``Half-Floating'' mode represents a half-precision (two byte) floating
1073 ``Three-Quarter-Floating'' (?) mode represents a three-quarter-precision
1074 (three byte) floating point number.
1078 ``Single Floating'' mode represents a four byte floating point number.
1079 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1080 this is a single-precision IEEE floating point number; it can also be
1081 used for double-precision (on processors with 16-bit bytes) and
1082 single-precision VAX and IBM types.
1086 ``Double Floating'' mode represents an eight byte floating point number.
1087 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1088 this is a double-precision IEEE floating point number.
1092 ``Extended Floating'' mode represents a twelve byte floating point
1093 number. This mode is used for IEEE extended floating point. On some
1094 systems not all bits within these bytes will actually be used.
1098 ``Tetra Floating'' mode represents a sixteen byte floating point number.
1099 This gets used for both the 96-bit extended IEEE floating-point types
1100 padded to 128 bits, and true 128-bit extended IEEE floating-point types.
1104 ``Condition Code'' mode represents the value of a condition code, which
1105 is a machine-specific set of bits used to represent the result of a
1106 comparison operation. Other machine-specific modes may also be used for
1107 the condition code. These modes are not used on machines that use
1108 @code{cc0} (see @pxref{Condition Code}).
1112 ``Block'' mode represents values that are aggregates to which none of
1113 the other modes apply. In RTL, only memory references can have this mode,
1114 and only if they appear in string-move or vector instructions. On machines
1115 which have no such instructions, @code{BLKmode} will not appear in RTL@.
1119 Void mode means the absence of a mode or an unspecified mode.
1120 For example, RTL expressions of code @code{const_int} have mode
1121 @code{VOIDmode} because they can be taken to have whatever mode the context
1122 requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by
1123 the absence of any mode.
1131 @item QCmode, HCmode, SCmode, DCmode, XCmode, TCmode
1132 These modes stand for a complex number represented as a pair of floating
1133 point values. The floating point values are in @code{QFmode},
1134 @code{HFmode}, @code{SFmode}, @code{DFmode}, @code{XFmode}, and
1135 @code{TFmode}, respectively.
1143 @item CQImode, CHImode, CSImode, CDImode, CTImode, COImode
1144 These modes stand for a complex number represented as a pair of integer
1145 values. The integer values are in @code{QImode}, @code{HImode},
1146 @code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode},
1150 The machine description defines @code{Pmode} as a C macro which expands
1151 into the machine mode used for addresses. Normally this is the mode
1152 whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines.
1154 The only modes which a machine description @i{must} support are
1155 @code{QImode}, and the modes corresponding to @code{BITS_PER_WORD},
1156 @code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}.
1157 The compiler will attempt to use @code{DImode} for 8-byte structures and
1158 unions, but this can be prevented by overriding the definition of
1159 @code{MAX_FIXED_MODE_SIZE}. Alternatively, you can have the compiler
1160 use @code{TImode} for 16-byte structures and unions. Likewise, you can
1161 arrange for the C type @code{short int} to avoid using @code{HImode}.
1163 @cindex mode classes
1164 Very few explicit references to machine modes remain in the compiler and
1165 these few references will soon be removed. Instead, the machine modes
1166 are divided into mode classes. These are represented by the enumeration
1167 type @code{enum mode_class} defined in @file{machmode.h}. The possible
1173 Integer modes. By default these are @code{BImode}, @code{QImode},
1174 @code{HImode}, @code{SImode}, @code{DImode}, @code{TImode}, and
1177 @findex MODE_PARTIAL_INT
1178 @item MODE_PARTIAL_INT
1179 The ``partial integer'' modes, @code{PQImode}, @code{PHImode},
1180 @code{PSImode} and @code{PDImode}.
1184 Floating point modes. By default these are @code{QFmode},
1185 @code{HFmode}, @code{TQFmode}, @code{SFmode}, @code{DFmode},
1186 @code{XFmode} and @code{TFmode}.
1188 @findex MODE_COMPLEX_INT
1189 @item MODE_COMPLEX_INT
1190 Complex integer modes. (These are not currently implemented).
1192 @findex MODE_COMPLEX_FLOAT
1193 @item MODE_COMPLEX_FLOAT
1194 Complex floating point modes. By default these are @code{QCmode},
1195 @code{HCmode}, @code{SCmode}, @code{DCmode}, @code{XCmode}, and
1198 @findex MODE_FUNCTION
1200 Algol or Pascal function variables including a static chain.
1201 (These are not currently implemented).
1205 Modes representing condition code values. These are @code{CCmode} plus
1206 any modes listed in the @code{EXTRA_CC_MODES} macro. @xref{Jump Patterns},
1207 also see @ref{Condition Code}.
1211 This is a catchall mode class for modes which don't fit into the above
1212 classes. Currently @code{VOIDmode} and @code{BLKmode} are in
1216 Here are some C macros that relate to machine modes:
1220 @item GET_MODE (@var{x})
1221 Returns the machine mode of the RTX @var{x}.
1224 @item PUT_MODE (@var{x}, @var{newmode})
1225 Alters the machine mode of the RTX @var{x} to be @var{newmode}.
1227 @findex NUM_MACHINE_MODES
1228 @item NUM_MACHINE_MODES
1229 Stands for the number of machine modes available on the target
1230 machine. This is one greater than the largest numeric value of any
1233 @findex GET_MODE_NAME
1234 @item GET_MODE_NAME (@var{m})
1235 Returns the name of mode @var{m} as a string.
1237 @findex GET_MODE_CLASS
1238 @item GET_MODE_CLASS (@var{m})
1239 Returns the mode class of mode @var{m}.
1241 @findex GET_MODE_WIDER_MODE
1242 @item GET_MODE_WIDER_MODE (@var{m})
1243 Returns the next wider natural mode. For example, the expression
1244 @code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}.
1246 @findex GET_MODE_SIZE
1247 @item GET_MODE_SIZE (@var{m})
1248 Returns the size in bytes of a datum of mode @var{m}.
1250 @findex GET_MODE_BITSIZE
1251 @item GET_MODE_BITSIZE (@var{m})
1252 Returns the size in bits of a datum of mode @var{m}.
1254 @findex GET_MODE_MASK
1255 @item GET_MODE_MASK (@var{m})
1256 Returns a bitmask containing 1 for all bits in a word that fit within
1257 mode @var{m}. This macro can only be used for modes whose bitsize is
1258 less than or equal to @code{HOST_BITS_PER_INT}.
1260 @findex GET_MODE_ALIGNMENT
1261 @item GET_MODE_ALIGNMENT (@var{m})
1262 Return the required alignment, in bits, for an object of mode @var{m}.
1264 @findex GET_MODE_UNIT_SIZE
1265 @item GET_MODE_UNIT_SIZE (@var{m})
1266 Returns the size in bytes of the subunits of a datum of mode @var{m}.
1267 This is the same as @code{GET_MODE_SIZE} except in the case of complex
1268 modes. For them, the unit size is the size of the real or imaginary
1271 @findex GET_MODE_NUNITS
1272 @item GET_MODE_NUNITS (@var{m})
1273 Returns the number of units contained in a mode, i.e.,
1274 @code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}.
1276 @findex GET_CLASS_NARROWEST_MODE
1277 @item GET_CLASS_NARROWEST_MODE (@var{c})
1278 Returns the narrowest mode in mode class @var{c}.
1283 The global variables @code{byte_mode} and @code{word_mode} contain modes
1284 whose classes are @code{MODE_INT} and whose bitsizes are either
1285 @code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit
1286 machines, these are @code{QImode} and @code{SImode}, respectively.
1289 @section Constant Expression Types
1290 @cindex RTL constants
1291 @cindex RTL constant expression types
1293 The simplest RTL expressions are those that represent constant values.
1297 @item (const_int @var{i})
1298 This type of expression represents the integer value @var{i}. @var{i}
1299 is customarily accessed with the macro @code{INTVAL} as in
1300 @code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}.
1306 There is only one expression object for the integer value zero; it is
1307 the value of the variable @code{const0_rtx}. Likewise, the only
1308 expression for integer value one is found in @code{const1_rtx}, the only
1309 expression for integer value two is found in @code{const2_rtx}, and the
1310 only expression for integer value negative one is found in
1311 @code{constm1_rtx}. Any attempt to create an expression of code
1312 @code{const_int} and value zero, one, two or negative one will return
1313 @code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or
1314 @code{constm1_rtx} as appropriate.
1316 @findex const_true_rtx
1317 Similarly, there is only one object for the integer whose value is
1318 @code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If
1319 @code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and
1320 @code{const1_rtx} will point to the same object. If
1321 @code{STORE_FLAG_VALUE} is @minus{}1, @code{const_true_rtx} and
1322 @code{constm1_rtx} will point to the same object.
1324 @findex const_double
1325 @item (const_double:@var{m} @var{addr} @var{i0} @var{i1} @dots{})
1326 Represents either a floating-point constant of mode @var{m} or an
1327 integer constant too large to fit into @code{HOST_BITS_PER_WIDE_INT}
1328 bits but small enough to fit within twice that number of bits (GCC
1329 does not provide a mechanism to represent even larger constants). In
1330 the latter case, @var{m} will be @code{VOIDmode}.
1332 @findex const_vector
1333 @item (const_vector:@var{m} [@var{x0} @var{x1} @dots{}])
1334 Represents a vector constant. The square brackets stand for the vector
1335 containing the constant elements. @var{x0}, @var{x1} and so on are
1336 the @code{const_int} or @code{const_double} elements.
1338 The number of units in a @code{const_vector} is obtained with the macro
1339 @code{CONST_VECTOR_NUNITS} as in @code{CONST_VECTOR_NUNITS (@var{v})}.
1341 Individual elements in a vector constant are accessed with the macro
1342 @code{CONST_VECTOR_ELT} as in @code{CONST_VECTOR_ELT (@var{v}, @var{n})}
1343 where @var{v} is the vector constant and @var{n} is the element
1346 @findex CONST_DOUBLE_MEM
1347 @findex CONST_DOUBLE_CHAIN
1348 @var{addr} is used to contain the @code{mem} expression that corresponds
1349 to the location in memory that at which the constant can be found. If
1350 it has not been allocated a memory location, but is on the chain of all
1351 @code{const_double} expressions in this compilation (maintained using an
1352 undisplayed field), @var{addr} contains @code{const0_rtx}. If it is not
1353 on the chain, @var{addr} contains @code{cc0_rtx}. @var{addr} is
1354 customarily accessed with the macro @code{CONST_DOUBLE_MEM} and the
1355 chain field via @code{CONST_DOUBLE_CHAIN}.
1357 @findex CONST_DOUBLE_LOW
1358 If @var{m} is @code{VOIDmode}, the bits of the value are stored in
1359 @var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro
1360 @code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}.
1362 If the constant is floating point (regardless of its precision), then
1363 the number of integers used to store the value depends on the size of
1364 @code{REAL_VALUE_TYPE} (@pxref{Floating Point}). The integers
1365 represent a floating point number, but not precisely in the target
1366 machine's or host machine's floating point format. To convert them to
1367 the precise bit pattern used by the target machine, use the macro
1368 @code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}).
1373 The macro @code{CONST0_RTX (@var{mode})} refers to an expression with
1374 value 0 in mode @var{mode}. If mode @var{mode} is of mode class
1375 @code{MODE_INT}, it returns @code{const0_rtx}. If mode @var{mode} is of
1376 mode class @code{MODE_FLOAT}, it returns a @code{CONST_DOUBLE}
1377 expression in mode @var{mode}. Otherwise, it returns a
1378 @code{CONST_VECTOR} expression in mode @var{mode}. Similarly, the macro
1379 @code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in
1380 mode @var{mode} and similarly for @code{CONST2_RTX}. The
1381 @code{CONST1_RTX} and @code{CONST2_RTX} macros are undefined
1384 @findex const_string
1385 @item (const_string @var{str})
1386 Represents a constant string with value @var{str}. Currently this is
1387 used only for insn attributes (@pxref{Insn Attributes}) since constant
1388 strings in C are placed in memory.
1391 @item (symbol_ref:@var{mode} @var{symbol})
1392 Represents the value of an assembler label for data. @var{symbol} is
1393 a string that describes the name of the assembler label. If it starts
1394 with a @samp{*}, the label is the rest of @var{symbol} not including
1395 the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed
1398 The @code{symbol_ref} contains a mode, which is usually @code{Pmode}.
1399 Usually that is the only mode for which a symbol is directly valid.
1402 @item (label_ref @var{label})
1403 Represents the value of an assembler label for code. It contains one
1404 operand, an expression, which must be a @code{code_label} or a @code{note}
1405 of type @code{NOTE_INSN_DELETED_LABEL} that appears in the instruction
1406 sequence to identify the place where the label should go.
1408 The reason for using a distinct expression type for code label
1409 references is so that jump optimization can distinguish them.
1411 @item (const:@var{m} @var{exp})
1412 Represents a constant that is the result of an assembly-time
1413 arithmetic computation. The operand, @var{exp}, is an expression that
1414 contains only constants (@code{const_int}, @code{symbol_ref} and
1415 @code{label_ref} expressions) combined with @code{plus} and
1416 @code{minus}. However, not all combinations are valid, since the
1417 assembler cannot do arbitrary arithmetic on relocatable symbols.
1419 @var{m} should be @code{Pmode}.
1422 @item (high:@var{m} @var{exp})
1423 Represents the high-order bits of @var{exp}, usually a
1424 @code{symbol_ref}. The number of bits is machine-dependent and is
1425 normally the number of bits specified in an instruction that initializes
1426 the high order bits of a register. It is used with @code{lo_sum} to
1427 represent the typical two-instruction sequence used in RISC machines to
1428 reference a global memory location.
1430 @var{m} should be @code{Pmode}.
1433 @node Regs and Memory
1434 @section Registers and Memory
1435 @cindex RTL register expressions
1436 @cindex RTL memory expressions
1438 Here are the RTL expression types for describing access to machine
1439 registers and to main memory.
1443 @cindex hard registers
1444 @cindex pseudo registers
1445 @item (reg:@var{m} @var{n})
1446 For small values of the integer @var{n} (those that are less than
1447 @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
1448 register number @var{n}: a @dfn{hard register}. For larger values of
1449 @var{n}, it stands for a temporary value or @dfn{pseudo register}.
1450 The compiler's strategy is to generate code assuming an unlimited
1451 number of such pseudo registers, and later convert them into hard
1452 registers or into memory references.
1454 @var{m} is the machine mode of the reference. It is necessary because
1455 machines can generally refer to each register in more than one mode.
1456 For example, a register may contain a full word but there may be
1457 instructions to refer to it as a half word or as a single byte, as
1458 well as instructions to refer to it as a floating point number of
1461 Even for a register that the machine can access in only one mode,
1462 the mode must always be specified.
1464 The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
1465 description, since the number of hard registers on the machine is an
1466 invariant characteristic of the machine. Note, however, that not
1467 all of the machine registers must be general registers. All the
1468 machine registers that can be used for storage of data are given
1469 hard register numbers, even those that can be used only in certain
1470 instructions or can hold only certain types of data.
1472 A hard register may be accessed in various modes throughout one
1473 function, but each pseudo register is given a natural mode
1474 and is accessed only in that mode. When it is necessary to describe
1475 an access to a pseudo register using a nonnatural mode, a @code{subreg}
1478 A @code{reg} expression with a machine mode that specifies more than
1479 one word of data may actually stand for several consecutive registers.
1480 If in addition the register number specifies a hardware register, then
1481 it actually represents several consecutive hardware registers starting
1482 with the specified one.
1484 Each pseudo register number used in a function's RTL code is
1485 represented by a unique @code{reg} expression.
1487 @findex FIRST_VIRTUAL_REGISTER
1488 @findex LAST_VIRTUAL_REGISTER
1489 Some pseudo register numbers, those within the range of
1490 @code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only
1491 appear during the RTL generation phase and are eliminated before the
1492 optimization phases. These represent locations in the stack frame that
1493 cannot be determined until RTL generation for the function has been
1494 completed. The following virtual register numbers are defined:
1497 @findex VIRTUAL_INCOMING_ARGS_REGNUM
1498 @item VIRTUAL_INCOMING_ARGS_REGNUM
1499 This points to the first word of the incoming arguments passed on the
1500 stack. Normally these arguments are placed there by the caller, but the
1501 callee may have pushed some arguments that were previously passed in
1504 @cindex @code{FIRST_PARM_OFFSET} and virtual registers
1505 @cindex @code{ARG_POINTER_REGNUM} and virtual registers
1506 When RTL generation is complete, this virtual register is replaced
1507 by the sum of the register given by @code{ARG_POINTER_REGNUM} and the
1508 value of @code{FIRST_PARM_OFFSET}.
1510 @findex VIRTUAL_STACK_VARS_REGNUM
1511 @cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers
1512 @item VIRTUAL_STACK_VARS_REGNUM
1513 If @code{FRAME_GROWS_DOWNWARD} is defined, this points to immediately
1514 above the first variable on the stack. Otherwise, it points to the
1515 first variable on the stack.
1517 @cindex @code{STARTING_FRAME_OFFSET} and virtual registers
1518 @cindex @code{FRAME_POINTER_REGNUM} and virtual registers
1519 @code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the
1520 register given by @code{FRAME_POINTER_REGNUM} and the value
1521 @code{STARTING_FRAME_OFFSET}.
1523 @findex VIRTUAL_STACK_DYNAMIC_REGNUM
1524 @item VIRTUAL_STACK_DYNAMIC_REGNUM
1525 This points to the location of dynamically allocated memory on the stack
1526 immediately after the stack pointer has been adjusted by the amount of
1529 @cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers
1530 @cindex @code{STACK_POINTER_REGNUM} and virtual registers
1531 This virtual register is replaced by the sum of the register given by
1532 @code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}.
1534 @findex VIRTUAL_OUTGOING_ARGS_REGNUM
1535 @item VIRTUAL_OUTGOING_ARGS_REGNUM
1536 This points to the location in the stack at which outgoing arguments
1537 should be written when the stack is pre-pushed (arguments pushed using
1538 push insns should always use @code{STACK_POINTER_REGNUM}).
1540 @cindex @code{STACK_POINTER_OFFSET} and virtual registers
1541 This virtual register is replaced by the sum of the register given by
1542 @code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}.
1546 @item (subreg:@var{m} @var{reg} @var{bytenum})
1547 @code{subreg} expressions are used to refer to a register in a machine
1548 mode other than its natural one, or to refer to one register of
1549 a multi-part @code{reg} that actually refers to several registers.
1551 Each pseudo-register has a natural mode. If it is necessary to
1552 operate on it in a different mode---for example, to perform a fullword
1553 move instruction on a pseudo-register that contains a single
1554 byte---the pseudo-register must be enclosed in a @code{subreg}. In
1555 such a case, @var{bytenum} is zero.
1557 Usually @var{m} is at least as narrow as the mode of @var{reg}, in which
1558 case it is restricting consideration to only the bits of @var{reg} that
1561 Sometimes @var{m} is wider than the mode of @var{reg}. These
1562 @code{subreg} expressions are often called @dfn{paradoxical}. They are
1563 used in cases where we want to refer to an object in a wider mode but do
1564 not care what value the additional bits have. The reload pass ensures
1565 that paradoxical references are only made to hard registers.
1567 The other use of @code{subreg} is to extract the individual registers of
1568 a multi-register value. Machine modes such as @code{DImode} and
1569 @code{TImode} can indicate values longer than a word, values which
1570 usually require two or more consecutive registers. To access one of the
1571 registers, use a @code{subreg} with mode @code{SImode} and a
1572 @var{bytenum} offset that says which register.
1574 Storing in a non-paradoxical @code{subreg} has undefined results for
1575 bits belonging to the same word as the @code{subreg}. This laxity makes
1576 it easier to generate efficient code for such instructions. To
1577 represent an instruction that preserves all the bits outside of those in
1578 the @code{subreg}, use @code{strict_low_part} around the @code{subreg}.
1580 @cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
1581 The compilation parameter @code{WORDS_BIG_ENDIAN}, if set to 1, says
1582 that byte number zero is part of the most significant word; otherwise,
1583 it is part of the least significant word.
1585 @cindex @code{BYTES_BIG_ENDIAN}, effect on @code{subreg}
1586 The compilation parameter @code{BYTES_BIG_ENDIAN}, if set to 1, says
1587 that byte number zero is the most significant byte within a word;
1588 otherwise, it is the least significant byte within a word.
1590 @cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg}
1591 On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with
1592 @code{WORDS_BIG_ENDIAN}.
1593 However, most parts of the compiler treat floating point values as if
1594 they had the same endianness as integer values. This works because
1595 they handle them solely as a collection of integer values, with no
1596 particular numerical value. Only real.c and the runtime libraries
1597 care about @code{FLOAT_WORDS_BIG_ENDIAN}.
1599 @cindex combiner pass
1601 @cindex @code{subreg}, special reload handling
1602 Between the combiner pass and the reload pass, it is possible to have a
1603 paradoxical @code{subreg} which contains a @code{mem} instead of a
1604 @code{reg} as its first operand. After the reload pass, it is also
1605 possible to have a non-paradoxical @code{subreg} which contains a
1606 @code{mem}; this usually occurs when the @code{mem} is a stack slot
1607 which replaced a pseudo register.
1609 Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
1610 using a @code{subreg}. On some machines the most significant part of a
1611 @code{DFmode} value does not have the same format as a single-precision
1614 It is also not valid to access a single word of a multi-word value in a
1615 hard register when less registers can hold the value than would be
1616 expected from its size. For example, some 32-bit machines have
1617 floating-point registers that can hold an entire @code{DFmode} value.
1618 If register 10 were such a register @code{(subreg:SI (reg:DF 10) 1)}
1619 would be invalid because there is no way to convert that reference to
1620 a single machine register. The reload pass prevents @code{subreg}
1621 expressions such as these from being formed.
1625 The first operand of a @code{subreg} expression is customarily accessed
1626 with the @code{SUBREG_REG} macro and the second operand is customarily
1627 accessed with the @code{SUBREG_BYTE} macro.
1630 @cindex scratch operands
1631 @item (scratch:@var{m})
1632 This represents a scratch register that will be required for the
1633 execution of a single instruction and not used subsequently. It is
1634 converted into a @code{reg} by either the local register allocator or
1637 @code{scratch} is usually present inside a @code{clobber} operation
1638 (@pxref{Side Effects}).
1641 @cindex condition code register
1643 This refers to the machine's condition code register. It has no
1644 operands and may not have a machine mode. There are two ways to use it:
1648 To stand for a complete set of condition code flags. This is best on
1649 most machines, where each comparison sets the entire series of flags.
1651 With this technique, @code{(cc0)} may be validly used in only two
1652 contexts: as the destination of an assignment (in test and compare
1653 instructions) and in comparison operators comparing against zero
1654 (@code{const_int} with value zero; that is to say, @code{const0_rtx}).
1657 To stand for a single flag that is the result of a single condition.
1658 This is useful on machines that have only a single flag bit, and in
1659 which comparison instructions must specify the condition to test.
1661 With this technique, @code{(cc0)} may be validly used in only two
1662 contexts: as the destination of an assignment (in test and compare
1663 instructions) where the source is a comparison operator, and as the
1664 first operand of @code{if_then_else} (in a conditional branch).
1668 There is only one expression object of code @code{cc0}; it is the
1669 value of the variable @code{cc0_rtx}. Any attempt to create an
1670 expression of code @code{cc0} will return @code{cc0_rtx}.
1672 Instructions can set the condition code implicitly. On many machines,
1673 nearly all instructions set the condition code based on the value that
1674 they compute or store. It is not necessary to record these actions
1675 explicitly in the RTL because the machine description includes a
1676 prescription for recognizing the instructions that do so (by means of
1677 the macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only
1678 instructions whose sole purpose is to set the condition code, and
1679 instructions that use the condition code, need mention @code{(cc0)}.
1681 On some machines, the condition code register is given a register number
1682 and a @code{reg} is used instead of @code{(cc0)}. This is usually the
1683 preferable approach if only a small subset of instructions modify the
1684 condition code. Other machines store condition codes in general
1685 registers; in such cases a pseudo register should be used.
1687 Some machines, such as the SPARC and RS/6000, have two sets of
1688 arithmetic instructions, one that sets and one that does not set the
1689 condition code. This is best handled by normally generating the
1690 instruction that does not set the condition code, and making a pattern
1691 that both performs the arithmetic and sets the condition code register
1692 (which would not be @code{(cc0)} in this case). For examples, search
1693 for @samp{addcc} and @samp{andcc} in @file{sparc.md}.
1697 @cindex program counter
1698 This represents the machine's program counter. It has no operands and
1699 may not have a machine mode. @code{(pc)} may be validly used only in
1700 certain specific contexts in jump instructions.
1703 There is only one expression object of code @code{pc}; it is the value
1704 of the variable @code{pc_rtx}. Any attempt to create an expression of
1705 code @code{pc} will return @code{pc_rtx}.
1707 All instructions that do not jump alter the program counter implicitly
1708 by incrementing it, but there is no need to mention this in the RTL@.
1711 @item (mem:@var{m} @var{addr} @var{alias})
1712 This RTX represents a reference to main memory at an address
1713 represented by the expression @var{addr}. @var{m} specifies how large
1714 a unit of memory is accessed. @var{alias} specifies an alias set for the
1715 reference. In general two items are in different alias sets if they cannot
1716 reference the same memory address.
1718 The construct @code{(mem:BLK (scratch))} is considered to alias all
1719 other memories. Thus it may be used as a memory barrier in epilogue
1720 stack deallocation patterns.
1723 @item (addressof:@var{m} @var{reg})
1724 This RTX represents a request for the address of register @var{reg}. Its mode
1725 is always @code{Pmode}. If there are any @code{addressof}
1726 expressions left in the function after CSE, @var{reg} is forced into the
1727 stack and the @code{addressof} expression is replaced with a @code{plus}
1728 expression for the address of its stack slot.
1732 @section RTL Expressions for Arithmetic
1733 @cindex arithmetic, in RTL
1734 @cindex math, in RTL
1735 @cindex RTL expressions for arithmetic
1737 Unless otherwise specified, all the operands of arithmetic expressions
1738 must be valid for mode @var{m}. An operand is valid for mode @var{m}
1739 if it has mode @var{m}, or if it is a @code{const_int} or
1740 @code{const_double} and @var{m} is a mode of class @code{MODE_INT}.
1742 For commutative binary operations, constants should be placed in the
1747 @cindex RTL addition
1749 @item (plus:@var{m} @var{x} @var{y})
1750 Represents the sum of the values represented by @var{x} and @var{y}
1751 carried out in machine mode @var{m}.
1754 @item (lo_sum:@var{m} @var{x} @var{y})
1755 Like @code{plus}, except that it represents that sum of @var{x} and the
1756 low-order bits of @var{y}. The number of low order bits is
1757 machine-dependent but is normally the number of bits in a @code{Pmode}
1758 item minus the number of bits set by the @code{high} code
1759 (@pxref{Constants}).
1761 @var{m} should be @code{Pmode}.
1764 @cindex RTL subtraction
1765 @cindex RTL difference
1766 @item (minus:@var{m} @var{x} @var{y})
1767 Like @code{plus} but represents subtraction.
1770 @cindex RTL addition with signed saturation
1771 @item (ss_plus:@var{m} @var{x} @var{y})
1773 Like @code{plus}, but using signed saturation in case of an overflow.
1776 @cindex RTL addition with unsigned saturation
1777 @item (us_plus:@var{m} @var{x} @var{y})
1779 Like @code{plus}, but using unsigned saturation in case of an overflow.
1782 @cindex RTL addition with signed saturation
1783 @item (ss_minus:@var{m} @var{x} @var{y})
1785 Like @code{minus}, but using signed saturation in case of an overflow.
1788 @cindex RTL addition with unsigned saturation
1789 @item (us_minus:@var{m} @var{x} @var{y})
1791 Like @code{minus}, but using unsigned saturation in case of an overflow.
1794 @cindex RTL comparison
1795 @item (compare:@var{m} @var{x} @var{y})
1796 Represents the result of subtracting @var{y} from @var{x} for purposes
1797 of comparison. The result is computed without overflow, as if with
1800 Of course, machines can't really subtract with infinite precision.
1801 However, they can pretend to do so when only the sign of the result will
1802 be used, which is the case when the result is stored in the condition
1803 code. And that is the @emph{only} way this kind of expression may
1804 validly be used: as a value to be stored in the condition codes, either
1805 @code{(cc0)} or a register. @xref{Comparisons}.
1807 The mode @var{m} is not related to the modes of @var{x} and @var{y}, but
1808 instead is the mode of the condition code value. If @code{(cc0)} is
1809 used, it is @code{VOIDmode}. Otherwise it is some mode in class
1810 @code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}. If @var{m}
1811 is @code{VOIDmode} or @code{CCmode}, the operation returns sufficient
1812 information (in an unspecified format) so that any comparison operator
1813 can be applied to the result of the @code{COMPARE} operation. For other
1814 modes in class @code{MODE_CC}, the operation only returns a subset of
1817 Normally, @var{x} and @var{y} must have the same mode. Otherwise,
1818 @code{compare} is valid only if the mode of @var{x} is in class
1819 @code{MODE_INT} and @var{y} is a @code{const_int} or
1820 @code{const_double} with mode @code{VOIDmode}. The mode of @var{x}
1821 determines what mode the comparison is to be done in; thus it must not
1824 If one of the operands is a constant, it should be placed in the
1825 second operand and the comparison code adjusted as appropriate.
1827 A @code{compare} specifying two @code{VOIDmode} constants is not valid
1828 since there is no way to know in what mode the comparison is to be
1829 performed; the comparison must either be folded during the compilation
1830 or the first operand must be loaded into a register while its mode is
1834 @item (neg:@var{m} @var{x})
1835 Represents the negation (subtraction from zero) of the value represented
1836 by @var{x}, carried out in mode @var{m}.
1839 @cindex multiplication
1841 @item (mult:@var{m} @var{x} @var{y})
1842 Represents the signed product of the values represented by @var{x} and
1843 @var{y} carried out in machine mode @var{m}.
1845 Some machines support a multiplication that generates a product wider
1846 than the operands. Write the pattern for this as
1849 (mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
1852 where @var{m} is wider than the modes of @var{x} and @var{y}, which need
1855 For unsigned widening multiplication, use the same idiom, but with
1856 @code{zero_extend} instead of @code{sign_extend}.
1860 @cindex signed division
1862 @item (div:@var{m} @var{x} @var{y})
1863 Represents the quotient in signed division of @var{x} by @var{y},
1864 carried out in machine mode @var{m}. If @var{m} is a floating point
1865 mode, it represents the exact quotient; otherwise, the integerized
1868 Some machines have division instructions in which the operands and
1869 quotient widths are not all the same; you should represent
1870 such instructions using @code{truncate} and @code{sign_extend} as in,
1873 (truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
1877 @cindex unsigned division
1879 @item (udiv:@var{m} @var{x} @var{y})
1880 Like @code{div} but represents unsigned division.
1886 @item (mod:@var{m} @var{x} @var{y})
1887 @itemx (umod:@var{m} @var{x} @var{y})
1888 Like @code{div} and @code{udiv} but represent the remainder instead of
1893 @cindex signed minimum
1894 @cindex signed maximum
1895 @item (smin:@var{m} @var{x} @var{y})
1896 @itemx (smax:@var{m} @var{x} @var{y})
1897 Represents the smaller (for @code{smin}) or larger (for @code{smax}) of
1898 @var{x} and @var{y}, interpreted as signed integers in mode @var{m}.
1902 @cindex unsigned minimum and maximum
1903 @item (umin:@var{m} @var{x} @var{y})
1904 @itemx (umax:@var{m} @var{x} @var{y})
1905 Like @code{smin} and @code{smax}, but the values are interpreted as unsigned
1909 @cindex complement, bitwise
1910 @cindex bitwise complement
1911 @item (not:@var{m} @var{x})
1912 Represents the bitwise complement of the value represented by @var{x},
1913 carried out in mode @var{m}, which must be a fixed-point machine mode.
1916 @cindex logical-and, bitwise
1917 @cindex bitwise logical-and
1918 @item (and:@var{m} @var{x} @var{y})
1919 Represents the bitwise logical-and of the values represented by
1920 @var{x} and @var{y}, carried out in machine mode @var{m}, which must be
1921 a fixed-point machine mode.
1924 @cindex inclusive-or, bitwise
1925 @cindex bitwise inclusive-or
1926 @item (ior:@var{m} @var{x} @var{y})
1927 Represents the bitwise inclusive-or of the values represented by @var{x}
1928 and @var{y}, carried out in machine mode @var{m}, which must be a
1932 @cindex exclusive-or, bitwise
1933 @cindex bitwise exclusive-or
1934 @item (xor:@var{m} @var{x} @var{y})
1935 Represents the bitwise exclusive-or of the values represented by @var{x}
1936 and @var{y}, carried out in machine mode @var{m}, which must be a
1942 @cindex arithmetic shift
1943 @item (ashift:@var{m} @var{x} @var{c})
1944 Represents the result of arithmetically shifting @var{x} left by @var{c}
1945 places. @var{x} have mode @var{m}, a fixed-point machine mode. @var{c}
1946 be a fixed-point mode or be a constant with mode @code{VOIDmode}; which
1947 mode is determined by the mode called for in the machine description
1948 entry for the left-shift instruction. For example, on the VAX, the mode
1949 of @var{c} is @code{QImode} regardless of @var{m}.
1954 @item (lshiftrt:@var{m} @var{x} @var{c})
1955 @itemx (ashiftrt:@var{m} @var{x} @var{c})
1956 Like @code{ashift} but for right shift. Unlike the case for left shift,
1957 these two operations are distinct.
1963 @cindex right rotate
1964 @item (rotate:@var{m} @var{x} @var{c})
1965 @itemx (rotatert:@var{m} @var{x} @var{c})
1966 Similar but represent left and right rotate. If @var{c} is a constant,
1970 @cindex absolute value
1971 @item (abs:@var{m} @var{x})
1972 Represents the absolute value of @var{x}, computed in mode @var{m}.
1976 @item (sqrt:@var{m} @var{x})
1977 Represents the square root of @var{x}, computed in mode @var{m}.
1978 Most often @var{m} will be a floating point mode.
1981 @item (ffs:@var{m} @var{x})
1982 Represents one plus the index of the least significant 1-bit in
1983 @var{x}, represented as an integer of mode @var{m}. (The value is
1984 zero if @var{x} is zero.) The mode of @var{x} need not be @var{m};
1985 depending on the target machine, various mode combinations may be
1989 @item (clz:@var{m} @var{x})
1990 Represents the number of leading 0-bits in @var{x}, represented as an
1991 integer of mode @var{m}, starting at the most significant bit position.
1992 If @var{x} is zero, the value is determined by
1993 @code{CLZ_DEFINED_VALUE_AT_ZERO}. Note that this is one of
1994 the few expressions that is not invariant under widening. The mode of
1995 @var{x} will usually be an integer mode.
1998 @item (ctz:@var{m} @var{x})
1999 Represents the number of trailing 0-bits in @var{x}, represented as an
2000 integer of mode @var{m}, starting at the least significant bit position.
2001 If @var{x} is zero, the value is determined by
2002 @code{CTZ_DEFINED_VALUE_AT_ZERO}. Except for this case,
2003 @code{ctz(x)} is equivalent to @code{ffs(@var{x}) - 1}. The mode of
2004 @var{x} will usually be an integer mode.
2007 @item (popcount:@var{m} @var{x})
2008 Represents the number of 1-bits in @var{x}, represented as an integer of
2009 mode @var{m}. The mode of @var{x} will usually be an integer mode.
2012 @item (parity:@var{m} @var{x})
2013 Represents the number of 1-bits modulo 2 in @var{x}, represented as an
2014 integer of mode @var{m}. The mode of @var{x} will usually be an integer
2019 @section Comparison Operations
2020 @cindex RTL comparison operations
2022 Comparison operators test a relation on two operands and are considered
2023 to represent a machine-dependent nonzero value described by, but not
2024 necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
2025 if the relation holds, or zero if it does not, for comparison operators
2026 whose results have a `MODE_INT' mode, and
2027 @code{FLOAT_STORE_FLAG_VALUE} (@pxref{Misc}) if the relation holds, or
2028 zero if it does not, for comparison operators that return floating-point
2029 values. The mode of the comparison operation is independent of the mode
2030 of the data being compared. If the comparison operation is being tested
2031 (e.g., the first operand of an @code{if_then_else}), the mode must be
2034 @cindex condition codes
2035 There are two ways that comparison operations may be used. The
2036 comparison operators may be used to compare the condition codes
2037 @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such
2038 a construct actually refers to the result of the preceding instruction
2039 in which the condition codes were set. The instruction setting the
2040 condition code must be adjacent to the instruction using the condition
2041 code; only @code{note} insns may separate them.
2043 Alternatively, a comparison operation may directly compare two data
2044 objects. The mode of the comparison is determined by the operands; they
2045 must both be valid for a common machine mode. A comparison with both
2046 operands constant would be invalid as the machine mode could not be
2047 deduced from it, but such a comparison should never exist in RTL due to
2050 In the example above, if @code{(cc0)} were last set to
2051 @code{(compare @var{x} @var{y})}, the comparison operation is
2052 identical to @code{(eq @var{x} @var{y})}. Usually only one style
2053 of comparisons is supported on a particular machine, but the combine
2054 pass will try to merge the operations to produce the @code{eq} shown
2055 in case it exists in the context of the particular insn involved.
2057 Inequality comparisons come in two flavors, signed and unsigned. Thus,
2058 there are distinct expression codes @code{gt} and @code{gtu} for signed and
2059 unsigned greater-than. These can produce different results for the same
2060 pair of integer values: for example, 1 is signed greater-than @minus{}1 but not
2061 unsigned greater-than, because @minus{}1 when regarded as unsigned is actually
2062 @code{0xffffffff} which is greater than 1.
2064 The signed comparisons are also used for floating point values. Floating
2065 point comparisons are distinguished by the machine modes of the operands.
2070 @item (eq:@var{m} @var{x} @var{y})
2071 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2072 are equal, otherwise 0.
2076 @item (ne:@var{m} @var{x} @var{y})
2077 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2078 are not equal, otherwise 0.
2081 @cindex greater than
2082 @item (gt:@var{m} @var{x} @var{y})
2083 @code{STORE_FLAG_VALUE} if the @var{x} is greater than @var{y}. If they
2084 are fixed-point, the comparison is done in a signed sense.
2087 @cindex greater than
2088 @cindex unsigned greater than
2089 @item (gtu:@var{m} @var{x} @var{y})
2090 Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
2095 @cindex unsigned less than
2096 @item (lt:@var{m} @var{x} @var{y})
2097 @itemx (ltu:@var{m} @var{x} @var{y})
2098 Like @code{gt} and @code{gtu} but test for ``less than''.
2101 @cindex greater than
2103 @cindex unsigned greater than
2104 @item (ge:@var{m} @var{x} @var{y})
2105 @itemx (geu:@var{m} @var{x} @var{y})
2106 Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
2109 @cindex less than or equal
2111 @cindex unsigned less than
2112 @item (le:@var{m} @var{x} @var{y})
2113 @itemx (leu:@var{m} @var{x} @var{y})
2114 Like @code{gt} and @code{gtu} but test for ``less than or equal''.
2116 @findex if_then_else
2117 @item (if_then_else @var{cond} @var{then} @var{else})
2118 This is not a comparison operation but is listed here because it is
2119 always used in conjunction with a comparison operation. To be
2120 precise, @var{cond} is a comparison expression. This expression
2121 represents a choice, according to @var{cond}, between the value
2122 represented by @var{then} and the one represented by @var{else}.
2124 On most machines, @code{if_then_else} expressions are valid only
2125 to express conditional jumps.
2128 @item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
2129 Similar to @code{if_then_else}, but more general. Each of @var{test1},
2130 @var{test2}, @dots{} is performed in turn. The result of this expression is
2131 the @var{value} corresponding to the first nonzero test, or @var{default} if
2132 none of the tests are nonzero expressions.
2134 This is currently not valid for instruction patterns and is supported only
2135 for insn attributes. @xref{Insn Attributes}.
2142 Special expression codes exist to represent bit-field instructions.
2143 These types of expressions are lvalues in RTL; they may appear
2144 on the left side of an assignment, indicating insertion of a value
2145 into the specified bit-field.
2148 @findex sign_extract
2149 @cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
2150 @item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
2151 This represents a reference to a sign-extended bit-field contained or
2152 starting in @var{loc} (a memory or register reference). The bit-field
2153 is @var{size} bits wide and starts at bit @var{pos}. The compilation
2154 option @code{BITS_BIG_ENDIAN} says which end of the memory unit
2155 @var{pos} counts from.
2157 If @var{loc} is in memory, its mode must be a single-byte integer mode.
2158 If @var{loc} is in a register, the mode to use is specified by the
2159 operand of the @code{insv} or @code{extv} pattern
2160 (@pxref{Standard Names}) and is usually a full-word integer mode,
2161 which is the default if none is specified.
2163 The mode of @var{pos} is machine-specific and is also specified
2164 in the @code{insv} or @code{extv} pattern.
2166 The mode @var{m} is the same as the mode that would be used for
2167 @var{loc} if it were a register.
2169 @findex zero_extract
2170 @item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
2171 Like @code{sign_extract} but refers to an unsigned or zero-extended
2172 bit-field. The same sequence of bits are extracted, but they
2173 are filled to an entire word with zeros instead of by sign-extension.
2176 @node Vector Operations
2177 @section Vector Operations
2178 @cindex vector operations
2180 All normal RTL expressions can be used with vector modes; they are
2181 interpreted as operating on each part of the vector independently.
2182 Additionally, there are a few new expressions to describe specific vector
2187 @item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items})
2188 This describes a merge operation between two vectors. The result is a vector
2189 of mode @var{m}; its elements are selected from either @var{vec1} or
2190 @var{vec2}. Which elements are selected is described by @var{items}, which
2191 is a bit mask represented by a @code{const_int}; a zero bit indicates the
2192 corresponding element in the result vector is taken from @var{vec2} while
2193 a set bit indicates it is taken from @var{vec1}.
2196 @item (vec_select:@var{m} @var{vec1} @var{selection})
2197 This describes an operation that selects parts of a vector. @var{vec1} is
2198 the source vector, @var{selection} is a @code{parallel} that contains a
2199 @code{const_int} for each of the subparts of the result vector, giving the
2200 number of the source subpart that should be stored into it.
2203 @item (vec_concat:@var{m} @var{vec1} @var{vec2})
2204 Describes a vector concat operation. The result is a concatenation of the
2205 vectors @var{vec1} and @var{vec2}; its length is the sum of the lengths of
2209 @item (vec_const:@var{m} @var{subparts})
2210 This describes a constant vector. @var{subparts} is a @code{parallel} that
2211 contains a constant for each of the subparts of the vector.
2213 @findex vec_duplicate
2214 @item (vec_duplicate:@var{m} @var{vec})
2215 This operation converts a small vector into a larger one by duplicating the
2216 input values. The output vector mode must have the same submodes as the
2217 input vector mode, and the number of output parts must be an integer multiple
2218 of the number of input parts.
2223 @section Conversions
2225 @cindex machine mode conversions
2227 All conversions between machine modes must be represented by
2228 explicit conversion operations. For example, an expression
2229 which is the sum of a byte and a full word cannot be written as
2230 @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
2231 operation requires two operands of the same machine mode.
2232 Therefore, the byte-sized operand is enclosed in a conversion
2236 (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
2239 The conversion operation is not a mere placeholder, because there
2240 may be more than one way of converting from a given starting mode
2241 to the desired final mode. The conversion operation code says how
2244 For all conversion operations, @var{x} must not be @code{VOIDmode}
2245 because the mode in which to do the conversion would not be known.
2246 The conversion must either be done at compile-time or @var{x}
2247 must be placed into a register.
2251 @item (sign_extend:@var{m} @var{x})
2252 Represents the result of sign-extending the value @var{x}
2253 to machine mode @var{m}. @var{m} must be a fixed-point mode
2254 and @var{x} a fixed-point value of a mode narrower than @var{m}.
2257 @item (zero_extend:@var{m} @var{x})
2258 Represents the result of zero-extending the value @var{x}
2259 to machine mode @var{m}. @var{m} must be a fixed-point mode
2260 and @var{x} a fixed-point value of a mode narrower than @var{m}.
2262 @findex float_extend
2263 @item (float_extend:@var{m} @var{x})
2264 Represents the result of extending the value @var{x}
2265 to machine mode @var{m}. @var{m} must be a floating point mode
2266 and @var{x} a floating point value of a mode narrower than @var{m}.
2269 @item (truncate:@var{m} @var{x})
2270 Represents the result of truncating the value @var{x}
2271 to machine mode @var{m}. @var{m} must be a fixed-point mode
2272 and @var{x} a fixed-point value of a mode wider than @var{m}.
2275 @item (ss_truncate:@var{m} @var{x})
2276 Represents the result of truncating the value @var{x}
2277 to machine mode @var{m}, using signed saturation in the case of
2278 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
2282 @item (us_truncate:@var{m} @var{x})
2283 Represents the result of truncating the value @var{x}
2284 to machine mode @var{m}, using unsigned saturation in the case of
2285 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
2288 @findex float_truncate
2289 @item (float_truncate:@var{m} @var{x})
2290 Represents the result of truncating the value @var{x}
2291 to machine mode @var{m}. @var{m} must be a floating point mode
2292 and @var{x} a floating point value of a mode wider than @var{m}.
2295 @item (float:@var{m} @var{x})
2296 Represents the result of converting fixed point value @var{x},
2297 regarded as signed, to floating point mode @var{m}.
2299 @findex unsigned_float
2300 @item (unsigned_float:@var{m} @var{x})
2301 Represents the result of converting fixed point value @var{x},
2302 regarded as unsigned, to floating point mode @var{m}.
2305 @item (fix:@var{m} @var{x})
2306 When @var{m} is a fixed point mode, represents the result of
2307 converting floating point value @var{x} to mode @var{m}, regarded as
2308 signed. How rounding is done is not specified, so this operation may
2309 be used validly in compiling C code only for integer-valued operands.
2311 @findex unsigned_fix
2312 @item (unsigned_fix:@var{m} @var{x})
2313 Represents the result of converting floating point value @var{x} to
2314 fixed point mode @var{m}, regarded as unsigned. How rounding is done
2318 @item (fix:@var{m} @var{x})
2319 When @var{m} is a floating point mode, represents the result of
2320 converting floating point value @var{x} (valid for mode @var{m}) to an
2321 integer, still represented in floating point mode @var{m}, by rounding
2325 @node RTL Declarations
2326 @section Declarations
2327 @cindex RTL declarations
2328 @cindex declarations, RTL
2330 Declaration expression codes do not represent arithmetic operations
2331 but rather state assertions about their operands.
2334 @findex strict_low_part
2335 @cindex @code{subreg}, in @code{strict_low_part}
2336 @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
2337 This expression code is used in only one context: as the destination operand of a
2338 @code{set} expression. In addition, the operand of this expression
2339 must be a non-paradoxical @code{subreg} expression.
2341 The presence of @code{strict_low_part} says that the part of the
2342 register which is meaningful in mode @var{n}, but is not part of
2343 mode @var{m}, is not to be altered. Normally, an assignment to such
2344 a subreg is allowed to have undefined effects on the rest of the
2345 register when @var{m} is less than a word.
2349 @section Side Effect Expressions
2350 @cindex RTL side effect expressions
2352 The expression codes described so far represent values, not actions.
2353 But machine instructions never produce values; they are meaningful
2354 only for their side effects on the state of the machine. Special
2355 expression codes are used to represent side effects.
2357 The body of an instruction is always one of these side effect codes;
2358 the codes described above, which represent values, appear only as
2359 the operands of these.
2363 @item (set @var{lval} @var{x})
2364 Represents the action of storing the value of @var{x} into the place
2365 represented by @var{lval}. @var{lval} must be an expression
2366 representing a place that can be stored in: @code{reg} (or @code{subreg}
2367 or @code{strict_low_part}), @code{mem}, @code{pc}, @code{parallel}, or
2370 If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
2371 machine mode; then @var{x} must be valid for that mode.
2373 If @var{lval} is a @code{reg} whose machine mode is less than the full
2374 width of the register, then it means that the part of the register
2375 specified by the machine mode is given the specified value and the
2376 rest of the register receives an undefined value. Likewise, if
2377 @var{lval} is a @code{subreg} whose machine mode is narrower than
2378 the mode of the register, the rest of the register can be changed in
2381 If @var{lval} is a @code{strict_low_part} of a @code{subreg}, then the
2382 part of the register specified by the machine mode of the
2383 @code{subreg} is given the value @var{x} and the rest of the register
2386 If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
2387 be either a @code{compare} expression or a value that may have any mode.
2388 The latter case represents a ``test'' instruction. The expression
2389 @code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to
2390 @code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}.
2391 Use the former expression to save space during the compilation.
2393 If @var{lval} is a @code{parallel}, it is used to represent the case of
2394 a function returning a structure in multiple registers. Each element
2395 of the @code{parallel} is an @code{expr_list} whose first operand is a
2396 @code{reg} and whose second operand is a @code{const_int} representing the
2397 offset (in bytes) into the structure at which the data in that register
2398 corresponds. The first element may be null to indicate that the structure
2399 is also passed partly in memory.
2401 @cindex jump instructions and @code{set}
2402 @cindex @code{if_then_else} usage
2403 If @var{lval} is @code{(pc)}, we have a jump instruction, and the
2404 possibilities for @var{x} are very limited. It may be a
2405 @code{label_ref} expression (unconditional jump). It may be an
2406 @code{if_then_else} (conditional jump), in which case either the
2407 second or the third operand must be @code{(pc)} (for the case which
2408 does not jump) and the other of the two must be a @code{label_ref}
2409 (for the case which does jump). @var{x} may also be a @code{mem} or
2410 @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
2411 @code{mem}; these unusual patterns are used to represent jumps through
2414 If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of
2415 @var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
2416 valid for the mode of @var{lval}.
2420 @var{lval} is customarily accessed with the @code{SET_DEST} macro and
2421 @var{x} with the @code{SET_SRC} macro.
2425 As the sole expression in a pattern, represents a return from the
2426 current function, on machines where this can be done with one
2427 instruction, such as VAXen. On machines where a multi-instruction
2428 ``epilogue'' must be executed in order to return from the function,
2429 returning is done by jumping to a label which precedes the epilogue, and
2430 the @code{return} expression code is never used.
2432 Inside an @code{if_then_else} expression, represents the value to be
2433 placed in @code{pc} to return to the caller.
2435 Note that an insn pattern of @code{(return)} is logically equivalent to
2436 @code{(set (pc) (return))}, but the latter form is never used.
2439 @item (call @var{function} @var{nargs})
2440 Represents a function call. @var{function} is a @code{mem} expression
2441 whose address is the address of the function to be called.
2442 @var{nargs} is an expression which can be used for two purposes: on
2443 some machines it represents the number of bytes of stack argument; on
2444 others, it represents the number of argument registers.
2446 Each machine has a standard machine mode which @var{function} must
2447 have. The machine description defines macro @code{FUNCTION_MODE} to
2448 expand into the requisite mode name. The purpose of this mode is to
2449 specify what kind of addressing is allowed, on machines where the
2450 allowed kinds of addressing depend on the machine mode being
2454 @item (clobber @var{x})
2455 Represents the storing or possible storing of an unpredictable,
2456 undescribed value into @var{x}, which must be a @code{reg},
2457 @code{scratch}, @code{parallel} or @code{mem} expression.
2459 One place this is used is in string instructions that store standard
2460 values into particular hard registers. It may not be worth the
2461 trouble to describe the values that are stored, but it is essential to
2462 inform the compiler that the registers will be altered, lest it
2463 attempt to keep data in them across the string instruction.
2465 If @var{x} is @code{(mem:BLK (const_int 0))} or
2466 @code{(mem:BLK (scratch))}, it means that all memory
2467 locations must be presumed clobbered. If @var{x} is a @code{parallel},
2468 it has the same meaning as a @code{parallel} in a @code{set} expression.
2470 Note that the machine description classifies certain hard registers as
2471 ``call-clobbered''. All function call instructions are assumed by
2472 default to clobber these registers, so there is no need to use
2473 @code{clobber} expressions to indicate this fact. Also, each function
2474 call is assumed to have the potential to alter any memory location,
2475 unless the function is declared @code{const}.
2477 If the last group of expressions in a @code{parallel} are each a
2478 @code{clobber} expression whose arguments are @code{reg} or
2479 @code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
2480 phase can add the appropriate @code{clobber} expressions to an insn it
2481 has constructed when doing so will cause a pattern to be matched.
2483 This feature can be used, for example, on a machine that whose multiply
2484 and add instructions don't use an MQ register but which has an
2485 add-accumulate instruction that does clobber the MQ register. Similarly,
2486 a combined instruction might require a temporary register while the
2487 constituent instructions might not.
2489 When a @code{clobber} expression for a register appears inside a
2490 @code{parallel} with other side effects, the register allocator
2491 guarantees that the register is unoccupied both before and after that
2492 insn. However, the reload phase may allocate a register used for one of
2493 the inputs unless the @samp{&} constraint is specified for the selected
2494 alternative (@pxref{Modifiers}). You can clobber either a specific hard
2495 register, a pseudo register, or a @code{scratch} expression; in the
2496 latter two cases, GCC will allocate a hard register that is available
2497 there for use as a temporary.
2499 For instructions that require a temporary register, you should use
2500 @code{scratch} instead of a pseudo-register because this will allow the
2501 combiner phase to add the @code{clobber} when required. You do this by
2502 coding (@code{clobber} (@code{match_scratch} @dots{})). If you do
2503 clobber a pseudo register, use one which appears nowhere else---generate
2504 a new one each time. Otherwise, you may confuse CSE@.
2506 There is one other known use for clobbering a pseudo register in a
2507 @code{parallel}: when one of the input operands of the insn is also
2508 clobbered by the insn. In this case, using the same pseudo register in
2509 the clobber and elsewhere in the insn produces the expected results.
2513 Represents the use of the value of @var{x}. It indicates that the
2514 value in @var{x} at this point in the program is needed, even though
2515 it may not be apparent why this is so. Therefore, the compiler will
2516 not attempt to delete previous instructions whose only effect is to
2517 store a value in @var{x}. @var{x} must be a @code{reg} expression.
2519 In some situations, it may be tempting to add a @code{use} of a
2520 register in a @code{parallel} to describe a situation where the value
2521 of a special register will modify the behavior of the instruction.
2522 An hypothetical example might be a pattern for an addition that can
2523 either wrap around or use saturating addition depending on the value
2524 of a special control register:
2527 (parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
2534 This will not work, several of the optimizers only look at expressions
2535 locally; it is very likely that if you have multiple insns with
2536 identical inputs to the @code{unspec}, they will be optimized away even
2537 if register 1 changes in between.
2539 This means that @code{use} can @emph{only} be used to describe
2540 that the register is live. You should think twice before adding
2541 @code{use} statements, more often you will want to use @code{unspec}
2542 instead. The @code{use} RTX is most commonly useful to describe that
2543 a fixed register is implicitly used in an insn. It is also safe to use
2544 in patterns where the compiler knows for other reasons that the result
2545 of the whole pattern is variable, such as @samp{movstr@var{m}} or
2546 @samp{call} patterns.
2548 During the reload phase, an insn that has a @code{use} as pattern
2549 can carry a reg_equal note. These @code{use} insns will be deleted
2550 before the reload phase exits.
2552 During the delayed branch scheduling phase, @var{x} may be an insn.
2553 This indicates that @var{x} previously was located at this place in the
2554 code and its data dependencies need to be taken into account. These
2555 @code{use} insns will be deleted before the delayed branch scheduling
2559 @item (parallel [@var{x0} @var{x1} @dots{}])
2560 Represents several side effects performed in parallel. The square
2561 brackets stand for a vector; the operand of @code{parallel} is a
2562 vector of expressions. @var{x0}, @var{x1} and so on are individual
2563 side effect expressions---expressions of code @code{set}, @code{call},
2564 @code{return}, @code{clobber} or @code{use}.
2566 ``In parallel'' means that first all the values used in the individual
2567 side-effects are computed, and second all the actual side-effects are
2568 performed. For example,
2571 (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
2572 (set (mem:SI (reg:SI 1)) (reg:SI 1))])
2576 says unambiguously that the values of hard register 1 and the memory
2577 location addressed by it are interchanged. In both places where
2578 @code{(reg:SI 1)} appears as a memory address it refers to the value
2579 in register 1 @emph{before} the execution of the insn.
2581 It follows that it is @emph{incorrect} to use @code{parallel} and
2582 expect the result of one @code{set} to be available for the next one.
2583 For example, people sometimes attempt to represent a jump-if-zero
2584 instruction this way:
2587 (parallel [(set (cc0) (reg:SI 34))
2588 (set (pc) (if_then_else
2589 (eq (cc0) (const_int 0))
2595 But this is incorrect, because it says that the jump condition depends
2596 on the condition code value @emph{before} this instruction, not on the
2597 new value that is set by this instruction.
2599 @cindex peephole optimization, RTL representation
2600 Peephole optimization, which takes place together with final assembly
2601 code output, can produce insns whose patterns consist of a @code{parallel}
2602 whose elements are the operands needed to output the resulting
2603 assembler code---often @code{reg}, @code{mem} or constant expressions.
2604 This would not be well-formed RTL at any other stage in compilation,
2605 but it is ok then because no further optimization remains to be done.
2606 However, the definition of the macro @code{NOTICE_UPDATE_CC}, if
2607 any, must deal with such insns if you define any peephole optimizations.
2610 @item (cond_exec [@var{cond} @var{expr}])
2611 Represents a conditionally executed expression. The @var{expr} is
2612 executed only if the @var{cond} is nonzero. The @var{cond} expression
2613 must not have side-effects, but the @var{expr} may very well have
2617 @item (sequence [@var{insns} @dots{}])
2618 Represents a sequence of insns. Each of the @var{insns} that appears
2619 in the vector is suitable for appearing in the chain of insns, so it
2620 must be an @code{insn}, @code{jump_insn}, @code{call_insn},
2621 @code{code_label}, @code{barrier} or @code{note}.
2623 A @code{sequence} RTX is never placed in an actual insn during RTL
2624 generation. It represents the sequence of insns that result from a
2625 @code{define_expand} @emph{before} those insns are passed to
2626 @code{emit_insn} to insert them in the chain of insns. When actually
2627 inserted, the individual sub-insns are separated out and the
2628 @code{sequence} is forgotten.
2630 After delay-slot scheduling is completed, an insn and all the insns that
2631 reside in its delay slots are grouped together into a @code{sequence}.
2632 The insn requiring the delay slot is the first insn in the vector;
2633 subsequent insns are to be placed in the delay slot.
2635 @code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
2636 indicate that a branch insn should be used that will conditionally annul
2637 the effect of the insns in the delay slots. In such a case,
2638 @code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
2639 the branch and should be executed only if the branch is taken; otherwise
2640 the insn should be executed only if the branch is not taken.
2644 These expression codes appear in place of a side effect, as the body of
2645 an insn, though strictly speaking they do not always describe side
2650 @item (asm_input @var{s})
2651 Represents literal assembler code as described by the string @var{s}.
2654 @findex unspec_volatile
2655 @item (unspec [@var{operands} @dots{}] @var{index})
2656 @itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
2657 Represents a machine-specific operation on @var{operands}. @var{index}
2658 selects between multiple machine-specific operations.
2659 @code{unspec_volatile} is used for volatile operations and operations
2660 that may trap; @code{unspec} is used for other operations.
2662 These codes may appear inside a @code{pattern} of an
2663 insn, inside a @code{parallel}, or inside an expression.
2666 @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
2667 Represents a table of jump addresses. The vector elements @var{lr0},
2668 etc., are @code{label_ref} expressions. The mode @var{m} specifies
2669 how much space is given to each address; normally @var{m} would be
2672 @findex addr_diff_vec
2673 @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags})
2674 Represents a table of jump addresses expressed as offsets from
2675 @var{base}. The vector elements @var{lr0}, etc., are @code{label_ref}
2676 expressions and so is @var{base}. The mode @var{m} specifies how much
2677 space is given to each address-difference. @var{min} and @var{max}
2678 are set up by branch shortening and hold a label with a minimum and a
2679 maximum address, respectively. @var{flags} indicates the relative
2680 position of @var{base}, @var{min} and @var{max} to the containing insn
2681 and of @var{min} and @var{max} to @var{base}. See rtl.def for details.
2684 @item (prefetch:@var{m} @var{addr} @var{rw} @var{locality})
2685 Represents prefetch of memory at address @var{addr}.
2686 Operand @var{rw} is 1 if the prefetch is for data to be written, 0 otherwise;
2687 targets that do not support write prefetches should treat this as a normal
2689 Operand @var{locality} specifies the amount of temporal locality; 0 if there
2690 is none or 1, 2, or 3 for increasing levels of temporal locality;
2691 targets that do not support locality hints should ignore this.
2693 This insn is used to minimize cache-miss latency by moving data into a
2694 cache before it is accessed. It should use only non-faulting data prefetch
2699 @section Embedded Side-Effects on Addresses
2700 @cindex RTL preincrement
2701 @cindex RTL postincrement
2702 @cindex RTL predecrement
2703 @cindex RTL postdecrement
2705 Six special side-effect expression codes appear as memory addresses.
2709 @item (pre_dec:@var{m} @var{x})
2710 Represents the side effect of decrementing @var{x} by a standard
2711 amount and represents also the value that @var{x} has after being
2712 decremented. @var{x} must be a @code{reg} or @code{mem}, but most
2713 machines allow only a @code{reg}. @var{m} must be the machine mode
2714 for pointers on the machine in use. The amount @var{x} is decremented
2715 by is the length in bytes of the machine mode of the containing memory
2716 reference of which this expression serves as the address. Here is an
2720 (mem:DF (pre_dec:SI (reg:SI 39)))
2724 This says to decrement pseudo register 39 by the length of a @code{DFmode}
2725 value and use the result to address a @code{DFmode} value.
2728 @item (pre_inc:@var{m} @var{x})
2729 Similar, but specifies incrementing @var{x} instead of decrementing it.
2732 @item (post_dec:@var{m} @var{x})
2733 Represents the same side effect as @code{pre_dec} but a different
2734 value. The value represented here is the value @var{x} has @i{before}
2738 @item (post_inc:@var{m} @var{x})
2739 Similar, but specifies incrementing @var{x} instead of decrementing it.
2742 @item (post_modify:@var{m} @var{x} @var{y})
2744 Represents the side effect of setting @var{x} to @var{y} and
2745 represents @var{x} before @var{x} is modified. @var{x} must be a
2746 @code{reg} or @code{mem}, but most machines allow only a @code{reg}.
2747 @var{m} must be the machine mode for pointers on the machine in use.
2749 The expression @var{y} must be one of three forms:
2751 @code{(plus:@var{m} @var{x} @var{z})},
2752 @code{(minus:@var{m} @var{x} @var{z})}, or
2753 @code{(plus:@var{m} @var{x} @var{i})},
2755 where @var{z} is an index register and @var{i} is a constant.
2757 Here is an example of its use:
2760 (mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
2764 This says to modify pseudo register 42 by adding the contents of pseudo
2765 register 48 to it, after the use of what ever 42 points to.
2768 @item (pre_modify:@var{m} @var{x} @var{expr})
2769 Similar except side effects happen before the use.
2772 These embedded side effect expressions must be used with care. Instruction
2773 patterns may not use them. Until the @samp{flow} pass of the compiler,
2774 they may occur only to represent pushes onto the stack. The @samp{flow}
2775 pass finds cases where registers are incremented or decremented in one
2776 instruction and used as an address shortly before or after; these cases are
2777 then transformed to use pre- or post-increment or -decrement.
2779 If a register used as the operand of these expressions is used in
2780 another address in an insn, the original value of the register is used.
2781 Uses of the register outside of an address are not permitted within the
2782 same insn as a use in an embedded side effect expression because such
2783 insns behave differently on different machines and hence must be treated
2784 as ambiguous and disallowed.
2786 An instruction that can be represented with an embedded side effect
2787 could also be represented using @code{parallel} containing an additional
2788 @code{set} to describe how the address register is altered. This is not
2789 done because machines that allow these operations at all typically
2790 allow them wherever a memory address is called for. Describing them as
2791 additional parallel stores would require doubling the number of entries
2792 in the machine description.
2795 @section Assembler Instructions as Expressions
2796 @cindex assembler instructions in RTL
2798 @cindex @code{asm_operands}, usage
2799 The RTX code @code{asm_operands} represents a value produced by a
2800 user-specified assembler instruction. It is used to represent
2801 an @code{asm} statement with arguments. An @code{asm} statement with
2802 a single output operand, like this:
2805 asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
2809 is represented using a single @code{asm_operands} RTX which represents
2810 the value that is stored in @code{outputvar}:
2813 (set @var{rtx-for-outputvar}
2814 (asm_operands "foo %1,%2,%0" "a" 0
2815 [@var{rtx-for-addition-result} @var{rtx-for-*z}]
2816 [(asm_input:@var{m1} "g")
2817 (asm_input:@var{m2} "di")]))
2821 Here the operands of the @code{asm_operands} RTX are the assembler
2822 template string, the output-operand's constraint, the index-number of the
2823 output operand among the output operands specified, a vector of input
2824 operand RTX's, and a vector of input-operand modes and constraints. The
2825 mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
2828 When an @code{asm} statement has multiple output values, its insn has
2829 several such @code{set} RTX's inside of a @code{parallel}. Each @code{set}
2830 contains a @code{asm_operands}; all of these share the same assembler
2831 template and vectors, but each contains the constraint for the respective
2832 output operand. They are also distinguished by the output-operand index
2833 number, which is 0, 1, @dots{} for successive output operands.
2839 The RTL representation of the code for a function is a doubly-linked
2840 chain of objects called @dfn{insns}. Insns are expressions with
2841 special codes that are used for no other purpose. Some insns are
2842 actual instructions; others represent dispatch tables for @code{switch}
2843 statements; others represent labels to jump to or various sorts of
2844 declarative information.
2846 In addition to its own specific data, each insn must have a unique
2847 id-number that distinguishes it from all other insns in the current
2848 function (after delayed branch scheduling, copies of an insn with the
2849 same id-number may be present in multiple places in a function, but
2850 these copies will always be identical and will only appear inside a
2851 @code{sequence}), and chain pointers to the preceding and following
2852 insns. These three fields occupy the same position in every insn,
2853 independent of the expression code of the insn. They could be accessed
2854 with @code{XEXP} and @code{XINT}, but instead three special macros are
2859 @item INSN_UID (@var{i})
2860 Accesses the unique id of insn @var{i}.
2863 @item PREV_INSN (@var{i})
2864 Accesses the chain pointer to the insn preceding @var{i}.
2865 If @var{i} is the first insn, this is a null pointer.
2868 @item NEXT_INSN (@var{i})
2869 Accesses the chain pointer to the insn following @var{i}.
2870 If @var{i} is the last insn, this is a null pointer.
2874 @findex get_last_insn
2875 The first insn in the chain is obtained by calling @code{get_insns}; the
2876 last insn is the result of calling @code{get_last_insn}. Within the
2877 chain delimited by these insns, the @code{NEXT_INSN} and
2878 @code{PREV_INSN} pointers must always correspond: if @var{insn} is not
2882 NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
2886 is always true and if @var{insn} is not the last insn,
2889 PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
2895 After delay slot scheduling, some of the insns in the chain might be
2896 @code{sequence} expressions, which contain a vector of insns. The value
2897 of @code{NEXT_INSN} in all but the last of these insns is the next insn
2898 in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
2899 is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
2900 which it is contained. Similar rules apply for @code{PREV_INSN}.
2902 This means that the above invariants are not necessarily true for insns
2903 inside @code{sequence} expressions. Specifically, if @var{insn} is the
2904 first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
2905 is the insn containing the @code{sequence} expression, as is the value
2906 of @code{PREV_INSN (NEXT_INSN (@var{insn}))} if @var{insn} is the last
2907 insn in the @code{sequence} expression. You can use these expressions
2908 to find the containing @code{sequence} expression.
2910 Every insn has one of the following six expression codes:
2915 The expression code @code{insn} is used for instructions that do not jump
2916 and do not do function calls. @code{sequence} expressions are always
2917 contained in insns with code @code{insn} even if one of those insns
2918 should jump or do function calls.
2920 Insns with code @code{insn} have four additional fields beyond the three
2921 mandatory ones listed above. These four are described in a table below.
2925 The expression code @code{jump_insn} is used for instructions that may
2926 jump (or, more generally, may contain @code{label_ref} expressions). If
2927 there is an instruction to return from the current function, it is
2928 recorded as a @code{jump_insn}.
2931 @code{jump_insn} insns have the same extra fields as @code{insn} insns,
2932 accessed in the same way and in addition contain a field
2933 @code{JUMP_LABEL} which is defined once jump optimization has completed.
2935 For simple conditional and unconditional jumps, this field contains
2936 the @code{code_label} to which this insn will (possibly conditionally)
2937 branch. In a more complex jump, @code{JUMP_LABEL} records one of the
2938 labels that the insn refers to; the only way to find the others is to
2939 scan the entire body of the insn. In an @code{addr_vec},
2940 @code{JUMP_LABEL} is @code{NULL_RTX}.
2942 Return insns count as jumps, but since they do not refer to any
2943 labels, their @code{JUMP_LABEL} is @code{NULL_RTX}.
2947 The expression code @code{call_insn} is used for instructions that may do
2948 function calls. It is important to distinguish these instructions because
2949 they imply that certain registers and memory locations may be altered
2952 @findex CALL_INSN_FUNCTION_USAGE
2953 @code{call_insn} insns have the same extra fields as @code{insn} insns,
2954 accessed in the same way and in addition contain a field
2955 @code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of
2956 @code{expr_list} expressions) containing @code{use} and @code{clobber}
2957 expressions that denote hard registers and @code{MEM}s used or
2958 clobbered by the called function.
2960 A @code{MEM} generally points to a stack slots in which arguments passed
2961 to the libcall by reference (@pxref{Register Arguments,
2962 FUNCTION_ARG_PASS_BY_REFERENCE}) are stored. If the argument is
2963 caller-copied (@pxref{Register Arguments, FUNCTION_ARG_CALLEE_COPIES}),
2964 the stack slot will be mentioned in @code{CLOBBER} and @code{USE}
2965 entries; if it's callee-copied, only a @code{USE} will appear, and the
2966 @code{MEM} may point to addresses that are not stack slots. These
2967 @code{MEM}s are used only in libcalls, because, unlike regular function
2968 calls, @code{CONST_CALL}s (which libcalls generally are, @pxref{Flags,
2969 CONST_CALL_P}) aren't assumed to read and write all memory, so flow
2970 would consider the stores dead and remove them. Note that, since a
2971 libcall must never return values in memory (@pxref{Aggregate Return,
2972 RETURN_IN_MEMORY}), there will never be a @code{CLOBBER} for a memory
2973 address holding a return value.
2975 @code{CLOBBER}ed registers in this list augment registers specified in
2976 @code{CALL_USED_REGISTERS} (@pxref{Register Basics}).
2979 @findex CODE_LABEL_NUMBER
2981 A @code{code_label} insn represents a label that a jump insn can jump
2982 to. It contains two special fields of data in addition to the three
2983 standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
2984 number}, a number that identifies this label uniquely among all the
2985 labels in the compilation (not just in the current function).
2986 Ultimately, the label is represented in the assembler output as an
2987 assembler label, usually of the form @samp{L@var{n}} where @var{n} is
2990 When a @code{code_label} appears in an RTL expression, it normally
2991 appears within a @code{label_ref} which represents the address of
2992 the label, as a number.
2994 Besides as a @code{code_label}, a label can also be represented as a
2995 @code{note} of type @code{NOTE_INSN_DELETED_LABEL}.
2998 The field @code{LABEL_NUSES} is only defined once the jump optimization
2999 phase is completed. It contains the number of times this label is
3000 referenced in the current function.
3003 @findex SET_LABEL_KIND
3004 @findex LABEL_ALT_ENTRY_P
3005 @cindex alternate entry points
3006 The field @code{LABEL_KIND} differentiates four different types of
3007 labels: @code{LABEL_NORMAL}, @code{LABEL_STATIC_ENTRY},
3008 @code{LABEL_GLOBAL_ENTRY}, and @code{LABEL_WEAK_ENTRY}. The only labels
3009 that do not have type @code{LABEL_NORMAL} are @dfn{alternate entry
3010 points} to the current function. These may be static (visible only in
3011 the containing translation unit), global (exposed to all translation
3012 units), or weak (global, but can be overridden by another symbol with the
3015 Much of the compiler treats all four kinds of label identically. Some
3016 of it needs to know whether or not a label is an alternate entry point;
3017 for this purpose, the macro @code{LABEL_ALT_ENTRY_P} is provided. It is
3018 equivalent to testing whether @samp{LABEL_KIND (label) == LABEL_NORMAL}.
3019 The only place that cares about the distinction between static, global,
3020 and weak alternate entry points, besides the front-end code that creates
3021 them, is the function @code{output_alternate_entry_point}, in
3024 To set the kind of a label, use the @code{SET_LABEL_KIND} macro.
3028 Barriers are placed in the instruction stream when control cannot flow
3029 past them. They are placed after unconditional jump instructions to
3030 indicate that the jumps are unconditional and after calls to
3031 @code{volatile} functions, which do not return (e.g., @code{exit}).
3032 They contain no information beyond the three standard fields.
3035 @findex NOTE_LINE_NUMBER
3036 @findex NOTE_SOURCE_FILE
3038 @code{note} insns are used to represent additional debugging and
3039 declarative information. They contain two nonstandard fields, an
3040 integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
3041 string accessed with @code{NOTE_SOURCE_FILE}.
3043 If @code{NOTE_LINE_NUMBER} is positive, the note represents the
3044 position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
3045 that the line came from. These notes control generation of line
3046 number data in the assembler output.
3048 Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
3049 code with one of the following values (and @code{NOTE_SOURCE_FILE}
3050 must contain a null pointer):
3053 @findex NOTE_INSN_DELETED
3054 @item NOTE_INSN_DELETED
3055 Such a note is completely ignorable. Some passes of the compiler
3056 delete insns by altering them into notes of this kind.
3058 @findex NOTE_INSN_DELETED_LABEL
3059 @item NOTE_INSN_DELETED_LABEL
3060 This marks what used to be a @code{code_label}, but was not used for other
3061 purposes than taking its address and was transformed to mark that no
3064 @findex NOTE_INSN_BLOCK_BEG
3065 @findex NOTE_INSN_BLOCK_END
3066 @item NOTE_INSN_BLOCK_BEG
3067 @itemx NOTE_INSN_BLOCK_END
3068 These types of notes indicate the position of the beginning and end
3069 of a level of scoping of variable names. They control the output
3070 of debugging information.
3072 @findex NOTE_INSN_EH_REGION_BEG
3073 @findex NOTE_INSN_EH_REGION_END
3074 @item NOTE_INSN_EH_REGION_BEG
3075 @itemx NOTE_INSN_EH_REGION_END
3076 These types of notes indicate the position of the beginning and end of a
3077 level of scoping for exception handling. @code{NOTE_BLOCK_NUMBER}
3078 identifies which @code{CODE_LABEL} or @code{note} of type
3079 @code{NOTE_INSN_DELETED_LABEL} is associated with the given region.
3081 @findex NOTE_INSN_LOOP_BEG
3082 @findex NOTE_INSN_LOOP_END
3083 @item NOTE_INSN_LOOP_BEG
3084 @itemx NOTE_INSN_LOOP_END
3085 These types of notes indicate the position of the beginning and end
3086 of a @code{while} or @code{for} loop. They enable the loop optimizer
3087 to find loops quickly.
3089 @findex NOTE_INSN_LOOP_CONT
3090 @item NOTE_INSN_LOOP_CONT
3091 Appears at the place in a loop that @code{continue} statements jump to.
3093 @findex NOTE_INSN_LOOP_VTOP
3094 @item NOTE_INSN_LOOP_VTOP
3095 This note indicates the place in a loop where the exit test begins for
3096 those loops in which the exit test has been duplicated. This position
3097 becomes another virtual start of the loop when considering loop
3100 @findex NOTE_INSN_FUNCTION_END
3101 @item NOTE_INSN_FUNCTION_END
3102 Appears near the end of the function body, just before the label that
3103 @code{return} statements jump to (on machine where a single instruction
3104 does not suffice for returning). This note may be deleted by jump
3107 @findex NOTE_INSN_SETJMP
3108 @item NOTE_INSN_SETJMP
3109 Appears following each call to @code{setjmp} or a related function.
3112 These codes are printed symbolically when they appear in debugging dumps.
3115 @cindex @code{TImode}, in @code{insn}
3116 @cindex @code{HImode}, in @code{insn}
3117 @cindex @code{QImode}, in @code{insn}
3118 The machine mode of an insn is normally @code{VOIDmode}, but some
3119 phases use the mode for various purposes.
3121 The common subexpression elimination pass sets the mode of an insn to
3122 @code{QImode} when it is the first insn in a block that has already
3125 The second Haifa scheduling pass, for targets that can multiple issue,
3126 sets the mode of an insn to @code{TImode} when it is believed that the
3127 instruction begins an issue group. That is, when the instruction
3128 cannot issue simultaneously with the previous. This may be relied on
3129 by later passes, in particular machine-dependent reorg.
3131 Here is a table of the extra fields of @code{insn}, @code{jump_insn}
3132 and @code{call_insn} insns:
3136 @item PATTERN (@var{i})
3137 An expression for the side effect performed by this insn. This must be
3138 one of the following codes: @code{set}, @code{call}, @code{use},
3139 @code{clobber}, @code{return}, @code{asm_input}, @code{asm_output},
3140 @code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec},
3141 @code{unspec_volatile}, @code{parallel}, @code{cond_exec}, or @code{sequence}. If it is a @code{parallel},
3142 each element of the @code{parallel} must be one these codes, except that
3143 @code{parallel} expressions cannot be nested and @code{addr_vec} and
3144 @code{addr_diff_vec} are not permitted inside a @code{parallel} expression.
3147 @item INSN_CODE (@var{i})
3148 An integer that says which pattern in the machine description matches
3149 this insn, or @minus{}1 if the matching has not yet been attempted.
3151 Such matching is never attempted and this field remains @minus{}1 on an insn
3152 whose pattern consists of a single @code{use}, @code{clobber},
3153 @code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.
3155 @findex asm_noperands
3156 Matching is also never attempted on insns that result from an @code{asm}
3157 statement. These contain at least one @code{asm_operands} expression.
3158 The function @code{asm_noperands} returns a non-negative value for
3161 In the debugging output, this field is printed as a number followed by
3162 a symbolic representation that locates the pattern in the @file{md}
3163 file as some small positive or negative offset from a named pattern.
3166 @item LOG_LINKS (@var{i})
3167 A list (chain of @code{insn_list} expressions) giving information about
3168 dependencies between instructions within a basic block. Neither a jump
3169 nor a label may come between the related insns.
3172 @item REG_NOTES (@var{i})
3173 A list (chain of @code{expr_list} and @code{insn_list} expressions)
3174 giving miscellaneous information about the insn. It is often
3175 information pertaining to the registers used in this insn.
3178 The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
3179 expressions. Each of these has two operands: the first is an insn,
3180 and the second is another @code{insn_list} expression (the next one in
3181 the chain). The last @code{insn_list} in the chain has a null pointer
3182 as second operand. The significant thing about the chain is which
3183 insns appear in it (as first operands of @code{insn_list}
3184 expressions). Their order is not significant.
3186 This list is originally set up by the flow analysis pass; it is a null
3187 pointer until then. Flow only adds links for those data dependencies
3188 which can be used for instruction combination. For each insn, the flow
3189 analysis pass adds a link to insns which store into registers values
3190 that are used for the first time in this insn. The instruction
3191 scheduling pass adds extra links so that every dependence will be
3192 represented. Links represent data dependencies, antidependencies and
3193 output dependencies; the machine mode of the link distinguishes these
3194 three types: antidependencies have mode @code{REG_DEP_ANTI}, output
3195 dependencies have mode @code{REG_DEP_OUTPUT}, and data dependencies have
3196 mode @code{VOIDmode}.
3198 The @code{REG_NOTES} field of an insn is a chain similar to the
3199 @code{LOG_LINKS} field but it includes @code{expr_list} expressions in
3200 addition to @code{insn_list} expressions. There are several kinds of
3201 register notes, which are distinguished by the machine mode, which in a
3202 register note is really understood as being an @code{enum reg_note}.
3203 The first operand @var{op} of the note is data whose meaning depends on
3206 @findex REG_NOTE_KIND
3207 @findex PUT_REG_NOTE_KIND
3208 The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of
3209 register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND
3210 (@var{x}, @var{newkind})} sets the register note type of @var{x} to be
3213 Register notes are of three classes: They may say something about an
3214 input to an insn, they may say something about an output of an insn, or
3215 they may create a linkage between two insns. There are also a set
3216 of values that are only used in @code{LOG_LINKS}.
3218 These register notes annotate inputs to an insn:
3223 The value in @var{op} dies in this insn; that is to say, altering the
3224 value immediately after this insn would not affect the future behavior
3227 It does not follow that the register @var{op} has no useful value after
3228 this insn since @var{op} is not necessarily modified by this insn.
3229 Rather, no subsequent instruction uses the contents of @var{op}.
3233 The register @var{op} being set by this insn will not be used in a
3234 subsequent insn. This differs from a @code{REG_DEAD} note, which
3235 indicates that the value in an input will not be used subsequently.
3236 These two notes are independent; both may be present for the same
3241 The register @var{op} is incremented (or decremented; at this level
3242 there is no distinction) by an embedded side effect inside this insn.
3243 This means it appears in a @code{post_inc}, @code{pre_inc},
3244 @code{post_dec} or @code{pre_dec} expression.
3248 The register @var{op} is known to have a nonnegative value when this
3249 insn is reached. This is used so that decrement and branch until zero
3250 instructions, such as the m68k dbra, can be matched.
3252 The @code{REG_NONNEG} note is added to insns only if the machine
3253 description has a @samp{decrement_and_branch_until_zero} pattern.
3255 @findex REG_NO_CONFLICT
3256 @item REG_NO_CONFLICT
3257 This insn does not cause a conflict between @var{op} and the item
3258 being set by this insn even though it might appear that it does.
3259 In other words, if the destination register and @var{op} could
3260 otherwise be assigned the same register, this insn does not
3261 prevent that assignment.
3263 Insns with this note are usually part of a block that begins with a
3264 @code{clobber} insn specifying a multi-word pseudo register (which will
3265 be the output of the block), a group of insns that each set one word of
3266 the value and have the @code{REG_NO_CONFLICT} note attached, and a final
3267 insn that copies the output to itself with an attached @code{REG_EQUAL}
3268 note giving the expression being computed. This block is encapsulated
3269 with @code{REG_LIBCALL} and @code{REG_RETVAL} notes on the first and
3270 last insns, respectively.
3274 This insn uses @var{op}, a @code{code_label} or a @code{note} of type
3275 @code{NOTE_INSN_DELETED_LABEL}, but is not a
3276 @code{jump_insn}, or it is a @code{jump_insn} that required the label to
3277 be held in a register. The presence of this note allows jump
3278 optimization to be aware that @var{op} is, in fact, being used, and flow
3279 optimization to build an accurate flow graph.
3282 The following notes describe attributes of outputs of an insn:
3289 This note is only valid on an insn that sets only one register and
3290 indicates that that register will be equal to @var{op} at run time; the
3291 scope of this equivalence differs between the two types of notes. The
3292 value which the insn explicitly copies into the register may look
3293 different from @var{op}, but they will be equal at run time. If the
3294 output of the single @code{set} is a @code{strict_low_part} expression,
3295 the note refers to the register that is contained in @code{SUBREG_REG}
3296 of the @code{subreg} expression.
3298 For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout
3299 the entire function, and could validly be replaced in all its
3300 occurrences by @var{op}. (``Validly'' here refers to the data flow of
3301 the program; simple replacement may make some insns invalid.) For
3302 example, when a constant is loaded into a register that is never
3303 assigned any other value, this kind of note is used.
3305 When a parameter is copied into a pseudo-register at entry to a function,
3306 a note of this kind records that the register is equivalent to the stack
3307 slot where the parameter was passed. Although in this case the register
3308 may be set by other insns, it is still valid to replace the register
3309 by the stack slot throughout the function.
3311 A @code{REG_EQUIV} note is also used on an instruction which copies a
3312 register parameter into a pseudo-register at entry to a function, if
3313 there is a stack slot where that parameter could be stored. Although
3314 other insns may set the pseudo-register, it is valid for the compiler to
3315 replace the pseudo-register by stack slot throughout the function,
3316 provided the compiler ensures that the stack slot is properly
3317 initialized by making the replacement in the initial copy instruction as
3318 well. This is used on machines for which the calling convention
3319 allocates stack space for register parameters. See
3320 @code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}.
3322 In the case of @code{REG_EQUAL}, the register that is set by this insn
3323 will be equal to @var{op} at run time at the end of this insn but not
3324 necessarily elsewhere in the function. In this case, @var{op}
3325 is typically an arithmetic expression. For example, when a sequence of
3326 insns such as a library call is used to perform an arithmetic operation,
3327 this kind of note is attached to the insn that produces or copies the
3330 These two notes are used in different ways by the compiler passes.
3331 @code{REG_EQUAL} is used by passes prior to register allocation (such as
3332 common subexpression elimination and loop optimization) to tell them how
3333 to think of that value. @code{REG_EQUIV} notes are used by register
3334 allocation to indicate that there is an available substitute expression
3335 (either a constant or a @code{mem} expression for the location of a
3336 parameter on the stack) that may be used in place of a register if
3337 insufficient registers are available.
3339 Except for stack homes for parameters, which are indicated by a
3340 @code{REG_EQUIV} note and are not useful to the early optimization
3341 passes and pseudo registers that are equivalent to a memory location
3342 throughout their entire life, which is not detected until later in
3343 the compilation, all equivalences are initially indicated by an attached
3344 @code{REG_EQUAL} note. In the early stages of register allocation, a
3345 @code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if
3346 @var{op} is a constant and the insn represents the only set of its
3347 destination register.
3349 Thus, compiler passes prior to register allocation need only check for
3350 @code{REG_EQUAL} notes and passes subsequent to register allocation
3351 need only check for @code{REG_EQUIV} notes.
3355 The single output of this insn contained zero before this insn.
3356 @var{op} is the insn that set it to zero. You can rely on this note if
3357 it is present and @var{op} has not been deleted or turned into a @code{note};
3358 its absence implies nothing.
3361 These notes describe linkages between insns. They occur in pairs: one
3362 insn has one of a pair of notes that points to a second insn, which has
3363 the inverse note pointing back to the first insn.
3368 This insn copies the value of a multi-insn sequence (for example, a
3369 library call), and @var{op} is the first insn of the sequence (for a
3370 library call, the first insn that was generated to set up the arguments
3371 for the library call).
3373 Loop optimization uses this note to treat such a sequence as a single
3374 operation for code motion purposes and flow analysis uses this note to
3375 delete such sequences whose results are dead.
3377 A @code{REG_EQUAL} note will also usually be attached to this insn to
3378 provide the expression being computed by the sequence.
3380 These notes will be deleted after reload, since they are no longer
3385 This is the inverse of @code{REG_RETVAL}: it is placed on the first
3386 insn of a multi-insn sequence, and it points to the last one.
3388 These notes are deleted after reload, since they are no longer useful or
3391 @findex REG_CC_SETTER
3395 On machines that use @code{cc0}, the insns which set and use @code{cc0}
3396 set and use @code{cc0} are adjacent. However, when branch delay slot
3397 filling is done, this may no longer be true. In this case a
3398 @code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to
3399 point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will
3400 be placed on the insn using @code{cc0} to point to the insn setting
3404 These values are only used in the @code{LOG_LINKS} field, and indicate
3405 the type of dependency that each link represents. Links which indicate
3406 a data dependence (a read after write dependence) do not use any code,
3407 they simply have mode @code{VOIDmode}, and are printed without any
3411 @findex REG_DEP_ANTI
3413 This indicates an anti dependence (a write after read dependence).
3415 @findex REG_DEP_OUTPUT
3416 @item REG_DEP_OUTPUT
3417 This indicates an output dependence (a write after write dependence).
3420 These notes describe information gathered from gcov profile data. They
3421 are stored in the @code{REG_NOTES} field of an insn as an
3427 This is used to specify the ratio of branches to non-branches of a
3428 branch insn according to the profile data. The value is stored as a
3429 value between 0 and REG_BR_PROB_BASE; larger values indicate a higher
3430 probability that the branch will be taken.
3434 These notes are found in JUMP insns after delayed branch scheduling
3435 has taken place. They indicate both the direction and the likelihood
3436 of the JUMP@. The format is a bitmask of ATTR_FLAG_* values.
3438 @findex REG_FRAME_RELATED_EXPR
3439 @item REG_FRAME_RELATED_EXPR
3440 This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression
3441 is used in place of the actual insn pattern. This is done in cases where
3442 the pattern is either complex or misleading.
3445 For convenience, the machine mode in an @code{insn_list} or
3446 @code{expr_list} is printed using these symbolic codes in debugging dumps.
3450 The only difference between the expression codes @code{insn_list} and
3451 @code{expr_list} is that the first operand of an @code{insn_list} is
3452 assumed to be an insn and is printed in debugging dumps as the insn's
3453 unique id; the first operand of an @code{expr_list} is printed in the
3454 ordinary way as an expression.
3457 @section RTL Representation of Function-Call Insns
3458 @cindex calling functions in RTL
3459 @cindex RTL function-call insns
3460 @cindex function-call insns
3462 Insns that call subroutines have the RTL expression code @code{call_insn}.
3463 These insns must satisfy special rules, and their bodies must use a special
3464 RTL expression code, @code{call}.
3466 @cindex @code{call} usage
3467 A @code{call} expression has two operands, as follows:
3470 (call (mem:@var{fm} @var{addr}) @var{nbytes})
3474 Here @var{nbytes} is an operand that represents the number of bytes of
3475 argument data being passed to the subroutine, @var{fm} is a machine mode
3476 (which must equal as the definition of the @code{FUNCTION_MODE} macro in
3477 the machine description) and @var{addr} represents the address of the
3480 For a subroutine that returns no value, the @code{call} expression as
3481 shown above is the entire body of the insn, except that the insn might
3482 also contain @code{use} or @code{clobber} expressions.
3484 @cindex @code{BLKmode}, and function return values
3485 For a subroutine that returns a value whose mode is not @code{BLKmode},
3486 the value is returned in a hard register. If this register's number is
3487 @var{r}, then the body of the call insn looks like this:
3490 (set (reg:@var{m} @var{r})
3491 (call (mem:@var{fm} @var{addr}) @var{nbytes}))
3495 This RTL expression makes it clear (to the optimizer passes) that the
3496 appropriate register receives a useful value in this insn.
3498 When a subroutine returns a @code{BLKmode} value, it is handled by
3499 passing to the subroutine the address of a place to store the value.
3500 So the call insn itself does not ``return'' any value, and it has the
3501 same RTL form as a call that returns nothing.
3503 On some machines, the call instruction itself clobbers some register,
3504 for example to contain the return address. @code{call_insn} insns
3505 on these machines should have a body which is a @code{parallel}
3506 that contains both the @code{call} expression and @code{clobber}
3507 expressions that indicate which registers are destroyed. Similarly,
3508 if the call instruction requires some register other than the stack
3509 pointer that is not explicitly mentioned it its RTL, a @code{use}
3510 subexpression should mention that register.
3512 Functions that are called are assumed to modify all registers listed in
3513 the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register
3514 Basics}) and, with the exception of @code{const} functions and library
3515 calls, to modify all of memory.
3517 Insns containing just @code{use} expressions directly precede the
3518 @code{call_insn} insn to indicate which registers contain inputs to the
3519 function. Similarly, if registers other than those in
3520 @code{CALL_USED_REGISTERS} are clobbered by the called function, insns
3521 containing a single @code{clobber} follow immediately after the call to
3522 indicate which registers.
3525 @section Structure Sharing Assumptions
3526 @cindex sharing of RTL components
3527 @cindex RTL structure sharing assumptions
3529 The compiler assumes that certain kinds of RTL expressions are unique;
3530 there do not exist two distinct objects representing the same value.
3531 In other cases, it makes an opposite assumption: that no RTL expression
3532 object of a certain kind appears in more than one place in the
3533 containing structure.
3535 These assumptions refer to a single function; except for the RTL
3536 objects that describe global variables and external functions,
3537 and a few standard objects such as small integer constants,
3538 no RTL objects are common to two functions.
3541 @cindex @code{reg}, RTL sharing
3543 Each pseudo-register has only a single @code{reg} object to represent it,
3544 and therefore only a single machine mode.
3546 @cindex symbolic label
3547 @cindex @code{symbol_ref}, RTL sharing
3549 For any symbolic label, there is only one @code{symbol_ref} object
3552 @cindex @code{const_int}, RTL sharing
3554 All @code{const_int} expressions with equal values are shared.
3556 @cindex @code{pc}, RTL sharing
3558 There is only one @code{pc} expression.
3560 @cindex @code{cc0}, RTL sharing
3562 There is only one @code{cc0} expression.
3564 @cindex @code{const_double}, RTL sharing
3566 There is only one @code{const_double} expression with value 0 for
3567 each floating point mode. Likewise for values 1 and 2.
3569 @cindex @code{const_vector}, RTL sharing
3571 There is only one @code{const_vector} expression with value 0 for
3572 each vector mode, be it an integer or a double constant vector.
3574 @cindex @code{label_ref}, RTL sharing
3575 @cindex @code{scratch}, RTL sharing
3577 No @code{label_ref} or @code{scratch} appears in more than one place in
3578 the RTL structure; in other words, it is safe to do a tree-walk of all
3579 the insns in the function and assume that each time a @code{label_ref}
3580 or @code{scratch} is seen it is distinct from all others that are seen.
3582 @cindex @code{mem}, RTL sharing
3584 Only one @code{mem} object is normally created for each static
3585 variable or stack slot, so these objects are frequently shared in all
3586 the places they appear. However, separate but equal objects for these
3587 variables are occasionally made.
3589 @cindex @code{asm_operands}, RTL sharing
3591 When a single @code{asm} statement has multiple output operands, a
3592 distinct @code{asm_operands} expression is made for each output operand.
3593 However, these all share the vector which contains the sequence of input
3594 operands. This sharing is used later on to test whether two
3595 @code{asm_operands} expressions come from the same statement, so all
3596 optimizations must carefully preserve the sharing if they copy the
3600 No RTL object appears in more than one place in the RTL structure
3601 except as described above. Many passes of the compiler rely on this
3602 by assuming that they can modify RTL objects in place without unwanted
3603 side-effects on other insns.
3605 @findex unshare_all_rtl
3607 During initial RTL generation, shared structure is freely introduced.
3608 After all the RTL for a function has been generated, all shared
3609 structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
3610 after which the above rules are guaranteed to be followed.
3612 @findex copy_rtx_if_shared
3614 During the combiner pass, shared structure within an insn can exist
3615 temporarily. However, the shared structure is copied before the
3616 combiner is finished with the insn. This is done by calling
3617 @code{copy_rtx_if_shared}, which is a subroutine of
3618 @code{unshare_all_rtl}.
3622 @section Reading RTL
3624 To read an RTL object from a file, call @code{read_rtx}. It takes one
3625 argument, a stdio stream, and returns a single RTL object. This routine
3626 is defined in @file{read-rtl.c}. It is not available in the compiler
3627 itself, only the various programs that generate the compiler back end
3628 from the machine description.
3630 People frequently have the idea of using RTL stored as text in a file as
3631 an interface between a language front end and the bulk of GCC@. This
3632 idea is not feasible.
3634 GCC was designed to use RTL internally only. Correct RTL for a given
3635 program is very dependent on the particular target machine. And the RTL
3636 does not contain all the information about the program.
3638 The proper way to interface GCC to a new language front end is with
3639 the ``tree'' data structure, described in the files @file{tree.h} and
3640 @file{tree.def}. The documentation for this structure (@pxref{Trees})