1 @c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002,
3 @c Free Software Foundation, Inc.
4 @c This is part of the GCC manual.
5 @c For copying conditions, see the file gcc.texi.
8 @chapter RTL Representation
9 @cindex RTL representation
10 @cindex representation of RTL
11 @cindex Register Transfer Language (RTL)
13 Most of the work of the compiler is done on an intermediate representation
14 called register transfer language. In this language, the instructions to be
15 output are described, pretty much one by one, in an algebraic form that
16 describes what the instruction does.
18 RTL is inspired by Lisp lists. It has both an internal form, made up of
19 structures that point at other structures, and a textual form that is used
20 in the machine description and in printed debugging dumps. The textual
21 form uses nested parentheses to indicate the pointers in the internal form.
24 * RTL Objects:: Expressions vs vectors vs strings vs integers.
25 * RTL Classes:: Categories of RTL expression objects, and their structure.
26 * Accessors:: Macros to access expression operands or vector elts.
27 * Special Accessors:: Macros to access specific annotations on RTL.
28 * Flags:: Other flags in an RTL expression.
29 * Machine Modes:: Describing the size and format of a datum.
30 * Constants:: Expressions with constant values.
31 * Regs and Memory:: Expressions representing register contents or memory.
32 * Arithmetic:: Expressions representing arithmetic on other expressions.
33 * Comparisons:: Expressions representing comparison of expressions.
34 * Bit-Fields:: Expressions representing bit-fields in memory or reg.
35 * Vector Operations:: Expressions involving vector datatypes.
36 * Conversions:: Extending, truncating, floating or fixing.
37 * RTL Declarations:: Declaring volatility, constancy, etc.
38 * Side Effects:: Expressions for storing in registers, etc.
39 * Incdec:: Embedded side-effects for autoincrement addressing.
40 * Assembler:: Representing @code{asm} with operands.
41 * Insns:: Expression types for entire insns.
42 * Calls:: RTL representation of function call insns.
43 * Sharing:: Some expressions are unique; others *must* be copied.
44 * Reading RTL:: Reading textual RTL from a file.
48 @section RTL Object Types
49 @cindex RTL object types
54 @cindex RTL expression
56 RTL uses five kinds of objects: expressions, integers, wide integers,
57 strings and vectors. Expressions are the most important ones. An RTL
58 expression (``RTX'', for short) is a C structure, but it is usually
59 referred to with a pointer; a type that is given the typedef name
62 An integer is simply an @code{int}; their written form uses decimal
63 digits. A wide integer is an integral object whose type is
64 @code{HOST_WIDE_INT}; their written form uses decimal digits.
66 A string is a sequence of characters. In core it is represented as a
67 @code{char *} in usual C fashion, and it is written in C syntax as well.
68 However, strings in RTL may never be null. If you write an empty string in
69 a machine description, it is represented in core as a null pointer rather
70 than as a pointer to a null character. In certain contexts, these null
71 pointers instead of strings are valid. Within RTL code, strings are most
72 commonly found inside @code{symbol_ref} expressions, but they appear in
73 other contexts in the RTL expressions that make up machine descriptions.
75 In a machine description, strings are normally written with double
76 quotes, as you would in C@. However, strings in machine descriptions may
77 extend over many lines, which is invalid C, and adjacent string
78 constants are not concatenated as they are in C@. Any string constant
79 may be surrounded with a single set of parentheses. Sometimes this
80 makes the machine description easier to read.
82 There is also a special syntax for strings, which can be useful when C
83 code is embedded in a machine description. Wherever a string can
84 appear, it is also valid to write a C-style brace block. The entire
85 brace block, including the outermost pair of braces, is considered to be
86 the string constant. Double quote characters inside the braces are not
87 special. Therefore, if you write string constants in the C code, you
88 need not escape each quote character with a backslash.
90 A vector contains an arbitrary number of pointers to expressions. The
91 number of elements in the vector is explicitly present in the vector.
92 The written form of a vector consists of square brackets
93 (@samp{[@dots{}]}) surrounding the elements, in sequence and with
94 whitespace separating them. Vectors of length zero are not created;
95 null pointers are used instead.
97 @cindex expression codes
98 @cindex codes, RTL expression
101 Expressions are classified by @dfn{expression codes} (also called RTX
102 codes). The expression code is a name defined in @file{rtl.def}, which is
103 also (in uppercase) a C enumeration constant. The possible expression
104 codes and their meanings are machine-independent. The code of an RTX can
105 be extracted with the macro @code{GET_CODE (@var{x})} and altered with
106 @code{PUT_CODE (@var{x}, @var{newcode})}.
108 The expression code determines how many operands the expression contains,
109 and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell
110 by looking at an operand what kind of object it is. Instead, you must know
111 from its context---from the expression code of the containing expression.
112 For example, in an expression of code @code{subreg}, the first operand is
113 to be regarded as an expression and the second operand as an integer. In
114 an expression of code @code{plus}, there are two operands, both of which
115 are to be regarded as expressions. In a @code{symbol_ref} expression,
116 there is one operand, which is to be regarded as a string.
118 Expressions are written as parentheses containing the name of the
119 expression type, its flags and machine mode if any, and then the operands
120 of the expression (separated by spaces).
122 Expression code names in the @samp{md} file are written in lowercase,
123 but when they appear in C code they are written in uppercase. In this
124 manual, they are shown as follows: @code{const_int}.
128 In a few contexts a null pointer is valid where an expression is normally
129 wanted. The written form of this is @code{(nil)}.
132 @section RTL Classes and Formats
134 @cindex classes of RTX codes
135 @cindex RTX codes, classes of
136 @findex GET_RTX_CLASS
138 The various expression codes are divided into several @dfn{classes},
139 which are represented by single characters. You can determine the class
140 of an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}.
141 Currently, @file{rtl.def} defines these classes:
145 An RTX code that represents an actual object, such as a register
146 (@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}).
147 @code{LO_SUM}) is also included; instead, @code{SUBREG} and
148 @code{STRICT_LOW_PART} are not in this class, but in class @code{x}.
151 An RTX code that represents a constant object. @code{HIGH} is also
152 included in this class.
155 An RTX code for a non-symmetric comparison, such as @code{GEU} or
158 @item RTX_COMM_COMPARE
159 An RTX code for a symmetric (commutative) comparison, such as @code{EQ}
163 An RTX code for a unary arithmetic operation, such as @code{NEG},
164 @code{NOT}, or @code{ABS}. This category also includes value extension
165 (sign or zero) and conversions between integer and floating point.
168 An RTX code for a commutative binary operation, such as @code{PLUS} or
169 @code{AND}. @code{NE} and @code{EQ} are comparisons, so they have class
173 An RTX code for a non-commutative binary operation, such as @code{MINUS},
174 @code{DIV}, or @code{ASHIFTRT}.
176 @item RTX_BITFIELD_OPS
177 An RTX code for a bit-field operation. Currently only
178 @code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}. These have three inputs
179 and are lvalues (so they can be used for insertion as well).
183 An RTX code for other three input operations. Currently only
184 @code{IF_THEN_ELSE} and @code{VEC_MERGE}.
187 An RTX code for an entire instruction: @code{INSN}, @code{JUMP_INSN}, and
188 @code{CALL_INSN}. @xref{Insns}.
191 An RTX code for something that matches in insns, such as
192 @code{MATCH_DUP}. These only occur in machine descriptions.
195 An RTX code for an auto-increment addressing mode, such as
199 All other RTX codes. This category includes the remaining codes used
200 only in machine descriptions (@code{DEFINE_*}, etc.). It also includes
201 all the codes describing side effects (@code{SET}, @code{USE},
202 @code{CLOBBER}, etc.) and the non-insns that may appear on an insn
203 chain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}.
204 @code{SUBREG} is also part of this class.
208 For each expression code, @file{rtl.def} specifies the number of
209 contained objects and their kinds using a sequence of characters
210 called the @dfn{format} of the expression code. For example,
211 the format of @code{subreg} is @samp{ei}.
213 @cindex RTL format characters
214 These are the most commonly used format characters:
218 An expression (actually a pointer to an expression).
230 A vector of expressions.
233 A few other format characters are used occasionally:
237 @samp{u} is equivalent to @samp{e} except that it is printed differently
238 in debugging dumps. It is used for pointers to insns.
241 @samp{n} is equivalent to @samp{i} except that it is printed differently
242 in debugging dumps. It is used for the line number or code number of a
246 @samp{S} indicates a string which is optional. In the RTL objects in
247 core, @samp{S} is equivalent to @samp{s}, but when the object is read,
248 from an @samp{md} file, the string value of this operand may be omitted.
249 An omitted string is taken to be the null string.
252 @samp{V} indicates a vector which is optional. In the RTL objects in
253 core, @samp{V} is equivalent to @samp{E}, but when the object is read
254 from an @samp{md} file, the vector value of this operand may be omitted.
255 An omitted vector is effectively the same as a vector of no elements.
258 @samp{B} indicates a pointer to basic block structure.
261 @samp{0} means a slot whose contents do not fit any normal category.
262 @samp{0} slots are not printed at all in dumps, and are often used in
263 special ways by small parts of the compiler.
266 There are macros to get the number of operands and the format
267 of an expression code:
270 @findex GET_RTX_LENGTH
271 @item GET_RTX_LENGTH (@var{code})
272 Number of operands of an RTX of code @var{code}.
274 @findex GET_RTX_FORMAT
275 @item GET_RTX_FORMAT (@var{code})
276 The format of an RTX of code @var{code}, as a C string.
279 Some classes of RTX codes always have the same format. For example, it
280 is safe to assume that all comparison operations have format @code{ee}.
284 All codes of this class have format @code{e}.
289 All codes of these classes have format @code{ee}.
293 All codes of these classes have format @code{eee}.
296 All codes of this class have formats that begin with @code{iuueiee}.
297 @xref{Insns}. Note that not all RTL objects linked onto an insn chain
298 are of class @code{i}.
303 You can make no assumptions about the format of these codes.
307 @section Access to Operands
309 @cindex access to operands
310 @cindex operand access
316 Operands of expressions are accessed using the macros @code{XEXP},
317 @code{XINT}, @code{XWINT} and @code{XSTR}. Each of these macros takes
318 two arguments: an expression-pointer (RTX) and an operand number
319 (counting from zero). Thus,
326 accesses operand 2 of expression @var{x}, as an expression.
333 accesses the same operand as an integer. @code{XSTR}, used in the same
334 fashion, would access it as a string.
336 Any operand can be accessed as an integer, as an expression or as a string.
337 You must choose the correct method of access for the kind of value actually
338 stored in the operand. You would do this based on the expression code of
339 the containing expression. That is also how you would know how many
342 For example, if @var{x} is a @code{subreg} expression, you know that it has
343 two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
344 and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you
345 would get the address of the expression operand but cast as an integer;
346 that might occasionally be useful, but it would be cleaner to write
347 @code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also
348 compile without error, and would return the second, integer operand cast as
349 an expression pointer, which would probably result in a crash when
350 accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
351 but this will access memory past the end of the expression with
352 unpredictable results.
354 Access to operands which are vectors is more complicated. You can use the
355 macro @code{XVEC} to get the vector-pointer itself, or the macros
356 @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
361 @item XVEC (@var{exp}, @var{idx})
362 Access the vector-pointer which is operand number @var{idx} in @var{exp}.
365 @item XVECLEN (@var{exp}, @var{idx})
366 Access the length (number of elements) in the vector which is
367 in operand number @var{idx} in @var{exp}. This value is an @code{int}.
370 @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
371 Access element number @var{eltnum} in the vector which is
372 in operand number @var{idx} in @var{exp}. This value is an RTX@.
374 It is up to you to make sure that @var{eltnum} is not negative
375 and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
378 All the macros defined in this section expand into lvalues and therefore
379 can be used to assign the operands, lengths and vector elements as well as
382 @node Special Accessors
383 @section Access to Special Operands
384 @cindex access to special operands
386 Some RTL nodes have special annotations associated with them.
391 @findex MEM_ALIAS_SET
392 @item MEM_ALIAS_SET (@var{x})
393 If 0, @var{x} is not in any alias set, and may alias anything. Otherwise,
394 @var{x} can only alias @code{MEM}s in a conflicting alias set. This value
395 is set in a language-dependent manner in the front-end, and should not be
396 altered in the back-end. In some front-ends, these numbers may correspond
397 in some way to types, or other language-level entities, but they need not,
398 and the back-end makes no such assumptions.
399 These set numbers are tested with @code{alias_sets_conflict_p}.
402 @item MEM_EXPR (@var{x})
403 If this register is known to hold the value of some user-level
404 declaration, this is that tree node. It may also be a
405 @code{COMPONENT_REF}, in which case this is some field reference,
406 and @code{TREE_OPERAND (@var{x}, 0)} contains the declaration,
407 or another @code{COMPONENT_REF}, or null if there is no compile-time
408 object associated with the reference.
411 @item MEM_OFFSET (@var{x})
412 The offset from the start of @code{MEM_EXPR} as a @code{CONST_INT} rtx.
415 @item MEM_SIZE (@var{x})
416 The size in bytes of the memory reference as a @code{CONST_INT} rtx.
417 This is mostly relevant for @code{BLKmode} references as otherwise
418 the size is implied by the mode.
421 @item MEM_ALIGN (@var{x})
422 The known alignment in bits of the memory reference.
427 @findex ORIGINAL_REGNO
428 @item ORIGINAL_REGNO (@var{x})
429 This field holds the number the register ``originally'' had; for a
430 pseudo register turned into a hard reg this will hold the old pseudo
434 @item REG_EXPR (@var{x})
435 If this register is known to hold the value of some user-level
436 declaration, this is that tree node.
439 @item REG_OFFSET (@var{x})
440 If this register is known to hold the value of some user-level
441 declaration, this is the offset into that logical storage.
446 @findex SYMBOL_REF_DECL
447 @item SYMBOL_REF_DECL (@var{x})
448 If the @code{symbol_ref} @var{x} was created for a @code{VAR_DECL} or
449 a @code{FUNCTION_DECL}, that tree is recorded here. If this value is
450 null, then @var{x} was created by back end code generation routines,
451 and there is no associated front end symbol table entry.
453 @code{SYMBOL_REF_DECL} may also point to a tree of class @code{'c'},
454 that is, some sort of constant. In this case, the @code{symbol_ref}
455 is an entry in the per-file constant pool; again, there is no associated
456 front end symbol table entry.
458 @findex SYMBOL_REF_FLAGS
459 @item SYMBOL_REF_FLAGS (@var{x})
460 In a @code{symbol_ref}, this is used to communicate various predicates
461 about the symbol. Some of these are common enough to be computed by
462 common code, some are specific to the target. The common bits are:
465 @findex SYMBOL_REF_FUNCTION_P
466 @findex SYMBOL_FLAG_FUNCTION
467 @item SYMBOL_FLAG_FUNCTION
468 Set if the symbol refers to a function.
470 @findex SYMBOL_REF_LOCAL_P
471 @findex SYMBOL_FLAG_LOCAL
472 @item SYMBOL_FLAG_LOCAL
473 Set if the symbol is local to this ``module''.
474 See @code{TARGET_BINDS_LOCAL_P}.
476 @findex SYMBOL_REF_EXTERNAL_P
477 @findex SYMBOL_FLAG_EXTERNAL
478 @item SYMBOL_FLAG_EXTERNAL
479 Set if this symbol is not defined in this translation unit.
480 Note that this is not the inverse of @code{SYMBOL_FLAG_LOCAL}.
482 @findex SYMBOL_REF_SMALL_P
483 @findex SYMBOL_FLAG_SMALL
484 @item SYMBOL_FLAG_SMALL
485 Set if the symbol is located in the small data section.
486 See @code{TARGET_IN_SMALL_DATA_P}.
488 @findex SYMBOL_FLAG_TLS_SHIFT
489 @findex SYMBOL_REF_TLS_MODEL
490 @item SYMBOL_REF_TLS_MODEL (@var{x})
491 This is a multi-bit field accessor that returns the @code{tls_model}
492 to be used for a thread-local storage symbol. It returns zero for
493 non-thread-local symbols.
496 Bits beginning with @code{SYMBOL_FLAG_MACH_DEP} are available for
502 @section Flags in an RTL Expression
503 @cindex flags in RTL expression
505 RTL expressions contain several flags (one-bit bit-fields)
506 that are used in certain types of expression. Most often they
507 are accessed with the following macros, which expand into lvalues.
510 @findex CONSTANT_POOL_ADDRESS_P
511 @cindex @code{symbol_ref} and @samp{/u}
512 @cindex @code{unchanging}, in @code{symbol_ref}
513 @item CONSTANT_POOL_ADDRESS_P (@var{x})
514 Nonzero in a @code{symbol_ref} if it refers to part of the current
515 function's constant pool. For most targets these addresses are in a
516 @code{.rodata} section entirely separate from the function, but for
517 some targets the addresses are close to the beginning of the function.
518 In either case GCC assumes these addresses can be addressed directly,
519 perhaps with the help of base registers.
520 Stored in the @code{unchanging} field and printed as @samp{/u}.
522 @findex CONST_OR_PURE_CALL_P
523 @cindex @code{call_insn} and @samp{/u}
524 @cindex @code{unchanging}, in @code{call_insn}
525 @item CONST_OR_PURE_CALL_P (@var{x})
526 In a @code{call_insn}, @code{note}, or an @code{expr_list} for notes,
527 indicates that the insn represents a call to a const or pure function.
528 Stored in the @code{unchanging} field and printed as @samp{/u}.
530 @findex INSN_ANNULLED_BRANCH_P
531 @cindex @code{jump_insn} and @samp{/u}
532 @cindex @code{call_insn} and @samp{/u}
533 @cindex @code{insn} and @samp{/u}
534 @cindex @code{unchanging}, in @code{jump_insn}, @code{call_insn} and @code{insn}
535 @item INSN_ANNULLED_BRANCH_P (@var{x})
536 In a @code{jump_insn}, @code{call_insn}, or @code{insn} indicates
537 that the branch is an annulling one. See the discussion under
538 @code{sequence} below. Stored in the @code{unchanging} field and
539 printed as @samp{/u}.
541 @findex INSN_DELETED_P
542 @cindex @code{insn} and @samp{/v}
543 @cindex @code{call_insn} and @samp{/v}
544 @cindex @code{jump_insn} and @samp{/v}
545 @cindex @code{code_label} and @samp{/v}
546 @cindex @code{barrier} and @samp{/v}
547 @cindex @code{note} and @samp{/v}
548 @cindex @code{volatil}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, @code{barrier}, and @code{note}
549 @item INSN_DELETED_P (@var{x})
550 In an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label},
551 @code{barrier}, or @code{note},
552 nonzero if the insn has been deleted. Stored in the
553 @code{volatil} field and printed as @samp{/v}.
555 @findex INSN_FROM_TARGET_P
556 @cindex @code{insn} and @samp{/s}
557 @cindex @code{jump_insn} and @samp{/s}
558 @cindex @code{call_insn} and @samp{/s}
559 @cindex @code{in_struct}, in @code{insn} and @code{jump_insn} and @code{call_insn}
560 @item INSN_FROM_TARGET_P (@var{x})
561 In an @code{insn} or @code{jump_insn} or @code{call_insn} in a delay
562 slot of a branch, indicates that the insn
563 is from the target of the branch. If the branch insn has
564 @code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if
565 the branch is taken. For annulled branches with
566 @code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the
567 branch is not taken. When @code{INSN_ANNULLED_BRANCH_P} is not set,
568 this insn will always be executed. Stored in the @code{in_struct}
569 field and printed as @samp{/s}.
571 @findex LABEL_OUTSIDE_LOOP_P
572 @cindex @code{label_ref} and @samp{/s}
573 @cindex @code{in_struct}, in @code{label_ref}
574 @item LABEL_OUTSIDE_LOOP_P (@var{x})
575 In @code{label_ref} expressions, nonzero if this is a reference to a
576 label that is outside the innermost loop containing the reference to the
577 label. Stored in the @code{in_struct} field and printed as @samp{/s}.
579 @findex LABEL_PRESERVE_P
580 @cindex @code{code_label} and @samp{/i}
581 @cindex @code{note} and @samp{/i}
582 @cindex @code{in_struct}, in @code{code_label} and @code{note}
583 @item LABEL_PRESERVE_P (@var{x})
584 In a @code{code_label} or @code{note}, indicates that the label is referenced by
585 code or data not visible to the RTL of a given function.
586 Labels referenced by a non-local goto will have this bit set. Stored
587 in the @code{in_struct} field and printed as @samp{/s}.
589 @findex LABEL_REF_NONLOCAL_P
590 @cindex @code{label_ref} and @samp{/v}
591 @cindex @code{reg_label} and @samp{/v}
592 @cindex @code{volatil}, in @code{label_ref} and @code{reg_label}
593 @item LABEL_REF_NONLOCAL_P (@var{x})
594 In @code{label_ref} and @code{reg_label} expressions, nonzero if this is
595 a reference to a non-local label.
596 Stored in the @code{volatil} field and printed as @samp{/v}.
598 @findex MEM_IN_STRUCT_P
599 @cindex @code{mem} and @samp{/s}
600 @cindex @code{in_struct}, in @code{mem}
601 @item MEM_IN_STRUCT_P (@var{x})
602 In @code{mem} expressions, nonzero for reference to an entire structure,
603 union or array, or to a component of one. Zero for references to a
604 scalar variable or through a pointer to a scalar. If both this flag and
605 @code{MEM_SCALAR_P} are clear, then we don't know whether this @code{mem}
606 is in a structure or not. Both flags should never be simultaneously set.
607 Stored in the @code{in_struct} field and printed as @samp{/s}.
609 @findex MEM_KEEP_ALIAS_SET_P
610 @cindex @code{mem} and @samp{/j}
611 @cindex @code{jump}, in @code{mem}
612 @item MEM_KEEP_ALIAS_SET_P (@var{x})
613 In @code{mem} expressions, 1 if we should keep the alias set for this
614 mem unchanged when we access a component. Set to 1, for example, when we
615 are already in a non-addressable component of an aggregate.
616 Stored in the @code{jump} field and printed as @samp{/j}.
619 @cindex @code{mem} and @samp{/f}
620 @cindex @code{frame_related}, in @code{mem}
621 @item MEM_SCALAR_P (@var{x})
622 In @code{mem} expressions, nonzero for reference to a scalar known not
623 to be a member of a structure, union, or array. Zero for such
624 references and for indirections through pointers, even pointers pointing
625 to scalar types. If both this flag and @code{MEM_IN_STRUCT_P} are clear,
626 then we don't know whether this @code{mem} is in a structure or not.
627 Both flags should never be simultaneously set.
628 Stored in the @code{frame_related} field and printed as @samp{/f}.
630 @findex MEM_VOLATILE_P
631 @cindex @code{mem} and @samp{/v}
632 @cindex @code{asm_input} and @samp{/v}
633 @cindex @code{asm_operands} and @samp{/v}
634 @cindex @code{volatil}, in @code{mem}, @code{asm_operands}, and @code{asm_input}
635 @item MEM_VOLATILE_P (@var{x})
636 In @code{mem}, @code{asm_operands}, and @code{asm_input} expressions,
637 nonzero for volatile memory references.
638 Stored in the @code{volatil} field and printed as @samp{/v}.
641 @cindex @code{mem} and @samp{/c}
642 @cindex @code{call}, in @code{mem}
643 @item MEM_NOTRAP_P (@var{x})
644 In @code{mem}, nonzero for memory references that will not trap.
645 Stored in the @code{call} field and printed as @samp{/c}.
647 @findex REG_FUNCTION_VALUE_P
648 @cindex @code{reg} and @samp{/i}
649 @cindex @code{integrated}, in @code{reg}
650 @item REG_FUNCTION_VALUE_P (@var{x})
651 Nonzero in a @code{reg} if it is the place in which this function's
652 value is going to be returned. (This happens only in a hard
653 register.) Stored in the @code{integrated} field and printed as
657 @cindex @code{reg} and @samp{/f}
658 @cindex @code{frame_related}, in @code{reg}
659 @item REG_POINTER (@var{x})
660 Nonzero in a @code{reg} if the register holds a pointer. Stored in the
661 @code{frame_related} field and printed as @samp{/f}.
663 @findex REG_USERVAR_P
664 @cindex @code{reg} and @samp{/v}
665 @cindex @code{volatil}, in @code{reg}
666 @item REG_USERVAR_P (@var{x})
667 In a @code{reg}, nonzero if it corresponds to a variable present in
668 the user's source code. Zero for temporaries generated internally by
669 the compiler. Stored in the @code{volatil} field and printed as
672 The same hard register may be used also for collecting the values of
673 functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
676 @findex RTX_FRAME_RELATED_P
677 @cindex @code{insn} and @samp{/f}
678 @cindex @code{call_insn} and @samp{/f}
679 @cindex @code{jump_insn} and @samp{/f}
680 @cindex @code{barrier} and @samp{/f}
681 @cindex @code{set} and @samp{/f}
682 @cindex @code{frame_related}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, and @code{set}
683 @item RTX_FRAME_RELATED_P (@var{x})
684 Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn},
685 @code{barrier}, or @code{set} which is part of a function prologue
686 and sets the stack pointer, sets the frame pointer, or saves a register.
687 This flag should also be set on an instruction that sets up a temporary
688 register to use in place of the frame pointer.
689 Stored in the @code{frame_related} field and printed as @samp{/f}.
691 In particular, on RISC targets where there are limits on the sizes of
692 immediate constants, it is sometimes impossible to reach the register
693 save area directly from the stack pointer. In that case, a temporary
694 register is used that is near enough to the register save area, and the
695 Canonical Frame Address, i.e., DWARF2's logical frame pointer, register
696 must (temporarily) be changed to be this temporary register. So, the
697 instruction that sets this temporary register must be marked as
698 @code{RTX_FRAME_RELATED_P}.
700 If the marked instruction is overly complex (defined in terms of what
701 @code{dwarf2out_frame_debug_expr} can handle), you will also have to
702 create a @code{REG_FRAME_RELATED_EXPR} note and attach it to the
703 instruction. This note should contain a simple expression of the
704 computation performed by this instruction, i.e., one that
705 @code{dwarf2out_frame_debug_expr} can handle.
707 This flag is required for exception handling support on targets with RTL
710 @cindex @code{insn} and @samp{/i}
711 @cindex @code{call_insn} and @samp{/i}
712 @cindex @code{jump_insn} and @samp{/i}
713 @cindex @code{barrier} and @samp{/i}
714 @cindex @code{code_label} and @samp{/i}
715 @cindex @code{insn_list} and @samp{/i}
716 @cindex @code{const} and @samp{/i}
717 @cindex @code{note} and @samp{/i}
718 @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}
719 @code{code_label}, @code{insn_list}, @code{const}, or @code{note} if it
720 resulted from an in-line function call.
721 Stored in the @code{integrated} field and printed as @samp{/i}.
723 @findex MEM_READONLY_P
724 @cindex @code{mem} and @samp{/u}
725 @cindex @code{unchanging}, in @code{mem}
726 @item MEM_READONLY_P (@var{x})
727 Nonzero in a @code{mem}, if the memory is statically allocated and read-only.
729 Read-only in this context means never modified during the lifetime of the
730 program, not necessarily in ROM or in write-disabled pages. A common
731 example of the later is a shared library's global offset table. This
732 table is initialized by the runtime loader, so the memory is technically
733 writable, but after control is transfered from the runtime loader to the
734 application, this memory will never be subsequently modified.
736 Stored in the @code{unchanging} field and printed as @samp{/u}.
738 @findex SCHED_GROUP_P
739 @cindex @code{insn} and @samp{/s}
740 @cindex @code{call_insn} and @samp{/s}
741 @cindex @code{jump_insn} and @samp{/s}
742 @cindex @code{in_struct}, in @code{insn}, @code{jump_insn} and @code{call_insn}
743 @item SCHED_GROUP_P (@var{x})
744 During instruction scheduling, in an @code{insn}, @code{call_insn} or
745 @code{jump_insn}, indicates that the
746 previous insn must be scheduled together with this insn. This is used to
747 ensure that certain groups of instructions will not be split up by the
748 instruction scheduling pass, for example, @code{use} insns before
749 a @code{call_insn} may not be separated from the @code{call_insn}.
750 Stored in the @code{in_struct} field and printed as @samp{/s}.
752 @findex SET_IS_RETURN_P
753 @cindex @code{insn} and @samp{/j}
754 @cindex @code{jump}, in @code{insn}
755 @item SET_IS_RETURN_P (@var{x})
756 For a @code{set}, nonzero if it is for a return.
757 Stored in the @code{jump} field and printed as @samp{/j}.
759 @findex SIBLING_CALL_P
760 @cindex @code{call_insn} and @samp{/j}
761 @cindex @code{jump}, in @code{call_insn}
762 @item SIBLING_CALL_P (@var{x})
763 For a @code{call_insn}, nonzero if the insn is a sibling call.
764 Stored in the @code{jump} field and printed as @samp{/j}.
766 @findex STRING_POOL_ADDRESS_P
767 @cindex @code{symbol_ref} and @samp{/f}
768 @cindex @code{frame_related}, in @code{symbol_ref}
769 @item STRING_POOL_ADDRESS_P (@var{x})
770 For a @code{symbol_ref} expression, nonzero if it addresses this function's
771 string constant pool.
772 Stored in the @code{frame_related} field and printed as @samp{/f}.
774 @findex SUBREG_PROMOTED_UNSIGNED_P
775 @cindex @code{subreg} and @samp{/u} and @samp{/v}
776 @cindex @code{unchanging}, in @code{subreg}
777 @cindex @code{volatil}, in @code{subreg}
778 @item SUBREG_PROMOTED_UNSIGNED_P (@var{x})
779 Returns a value greater then zero for a @code{subreg} that has
780 @code{SUBREG_PROMOTED_VAR_P} nonzero if the object being referenced is kept
781 zero-extended, zero if it is kept sign-extended, and less then zero if it is
782 extended some other way via the @code{ptr_extend} instruction.
783 Stored in the @code{unchanging}
784 field and @code{volatil} field, printed as @samp{/u} and @samp{/v}.
785 This macro may only be used to get the value it may not be used to change
786 the value. Use @code{SUBREG_PROMOTED_UNSIGNED_SET} to change the value.
788 @findex SUBREG_PROMOTED_UNSIGNED_SET
789 @cindex @code{subreg} and @samp{/u}
790 @cindex @code{unchanging}, in @code{subreg}
791 @cindex @code{volatil}, in @code{subreg}
792 @item SUBREG_PROMOTED_UNSIGNED_SET (@var{x})
793 Set the @code{unchanging} and @code{volatil} fields in a @code{subreg}
794 to reflect zero, sign, or other extension. If @code{volatil} is
795 zero, then @code{unchanging} as nonzero means zero extension and as
796 zero means sign extension. If @code{volatil} is nonzero then some
797 other type of extension was done via the @code{ptr_extend} instruction.
799 @findex SUBREG_PROMOTED_VAR_P
800 @cindex @code{subreg} and @samp{/s}
801 @cindex @code{in_struct}, in @code{subreg}
802 @item SUBREG_PROMOTED_VAR_P (@var{x})
803 Nonzero in a @code{subreg} if it was made when accessing an object that
804 was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine
805 description macro (@pxref{Storage Layout}). In this case, the mode of
806 the @code{subreg} is the declared mode of the object and the mode of
807 @code{SUBREG_REG} is the mode of the register that holds the object.
808 Promoted variables are always either sign- or zero-extended to the wider
809 mode on every assignment. Stored in the @code{in_struct} field and
810 printed as @samp{/s}.
812 @findex SYMBOL_REF_USED
813 @cindex @code{used}, in @code{symbol_ref}
814 @item SYMBOL_REF_USED (@var{x})
815 In a @code{symbol_ref}, indicates that @var{x} has been used. This is
816 normally only used to ensure that @var{x} is only declared external
817 once. Stored in the @code{used} field.
819 @findex SYMBOL_REF_WEAK
820 @cindex @code{symbol_ref} and @samp{/i}
821 @cindex @code{integrated}, in @code{symbol_ref}
822 @item SYMBOL_REF_WEAK (@var{x})
823 In a @code{symbol_ref}, indicates that @var{x} has been declared weak.
824 Stored in the @code{integrated} field and printed as @samp{/i}.
826 @findex SYMBOL_REF_FLAG
827 @cindex @code{symbol_ref} and @samp{/v}
828 @cindex @code{volatil}, in @code{symbol_ref}
829 @item SYMBOL_REF_FLAG (@var{x})
830 In a @code{symbol_ref}, this is used as a flag for machine-specific purposes.
831 Stored in the @code{volatil} field and printed as @samp{/v}.
833 Most uses of @code{SYMBOL_REF_FLAG} are historic and may be subsumed
834 by @code{SYMBOL_REF_FLAGS}. Certainly use of @code{SYMBOL_REF_FLAGS}
835 is mandatory if the target requires more than one bit of storage.
838 These are the fields to which the above macros refer:
842 @cindex @samp{/c} in RTL dump
844 In a @code{mem}, 1 means that the memory reference will not trap.
846 In an RTL dump, this flag is represented as @samp{/c}.
848 @findex frame_related
849 @cindex @samp{/f} in RTL dump
851 In an @code{insn} or @code{set} expression, 1 means that it is part of
852 a function prologue and sets the stack pointer, sets the frame pointer,
853 saves a register, or sets up a temporary register to use in place of the
856 In @code{reg} expressions, 1 means that the register holds a pointer.
858 In @code{symbol_ref} expressions, 1 means that the reference addresses
859 this function's string constant pool.
861 In @code{mem} expressions, 1 means that the reference is to a scalar.
863 In an RTL dump, this flag is represented as @samp{/f}.
866 @cindex @samp{/s} in RTL dump
868 In @code{mem} expressions, it is 1 if the memory datum referred to is
869 all or part of a structure or array; 0 if it is (or might be) a scalar
870 variable. A reference through a C pointer has 0 because the pointer
871 might point to a scalar variable. This information allows the compiler
872 to determine something about possible cases of aliasing.
874 In @code{reg} expressions, it is 1 if the register has its entire life
875 contained within the test expression of some loop.
877 In @code{subreg} expressions, 1 means that the @code{subreg} is accessing
878 an object that has had its mode promoted from a wider mode.
880 In @code{label_ref} expressions, 1 means that the referenced label is
881 outside the innermost loop containing the insn in which the @code{label_ref}
884 In @code{code_label} expressions, it is 1 if the label may never be deleted.
885 This is used for labels which are the target of non-local gotos. Such a
886 label that would have been deleted is replaced with a @code{note} of type
887 @code{NOTE_INSN_DELETED_LABEL}.
889 In an @code{insn} during dead-code elimination, 1 means that the insn is
892 In an @code{insn} or @code{jump_insn} during reorg for an insn in the
893 delay slot of a branch,
894 1 means that this insn is from the target of the branch.
896 In an @code{insn} during instruction scheduling, 1 means that this insn
897 must be scheduled as part of a group together with the previous insn.
899 In an RTL dump, this flag is represented as @samp{/s}.
902 @cindex @samp{/i} in RTL dump
904 In an @code{insn}, @code{insn_list}, or @code{const}, 1 means the RTL was
905 produced by procedure integration.
907 In @code{reg} expressions, 1 means the register contains
908 the value to be returned by the current function. On
909 machines that pass parameters in registers, the same register number
910 may be used for parameters as well, but this flag is not set on such
913 In @code{symbol_ref} expressions, 1 means the referenced symbol is weak.
915 In an RTL dump, this flag is represented as @samp{/i}.
918 @cindex @samp{/j} in RTL dump
920 In a @code{mem} expression, 1 means we should keep the alias set for this
921 mem unchanged when we access a component.
923 In a @code{set}, 1 means it is for a return.
925 In a @code{call_insn}, 1 means it is a sibling call.
927 In an RTL dump, this flag is represented as @samp{/j}.
930 @cindex @samp{/u} in RTL dump
932 In @code{reg} and @code{mem} expressions, 1 means
933 that the value of the expression never changes.
935 In @code{subreg} expressions, it is 1 if the @code{subreg} references an
936 unsigned object whose mode has been promoted to a wider mode.
938 In an @code{insn} or @code{jump_insn} in the delay slot of a branch
939 instruction, 1 means an annulling branch should be used.
941 In a @code{symbol_ref} expression, 1 means that this symbol addresses
942 something in the per-function constant pool.
944 In a @code{call_insn}, @code{note}, or an @code{expr_list} of notes,
945 1 means that this instruction is a call to a const or pure function.
947 In an RTL dump, this flag is represented as @samp{/u}.
951 This flag is used directly (without an access macro) at the end of RTL
952 generation for a function, to count the number of times an expression
953 appears in insns. Expressions that appear more than once are copied,
954 according to the rules for shared structure (@pxref{Sharing}).
956 For a @code{reg}, it is used directly (without an access macro) by the
957 leaf register renumbering code to ensure that each register is only
960 In a @code{symbol_ref}, it indicates that an external declaration for
961 the symbol has already been written.
964 @cindex @samp{/v} in RTL dump
966 @cindex volatile memory references
967 In a @code{mem}, @code{asm_operands}, or @code{asm_input}
968 expression, it is 1 if the memory
969 reference is volatile. Volatile memory references may not be deleted,
970 reordered or combined.
972 In a @code{symbol_ref} expression, it is used for machine-specific
975 In a @code{reg} expression, it is 1 if the value is a user-level variable.
976 0 indicates an internal compiler temporary.
978 In an @code{insn}, 1 means the insn has been deleted.
980 In @code{label_ref} and @code{reg_label} expressions, 1 means a reference
981 to a non-local label.
983 In an RTL dump, this flag is represented as @samp{/v}.
987 @section Machine Modes
988 @cindex machine modes
990 @findex enum machine_mode
991 A machine mode describes a size of data object and the representation used
992 for it. In the C code, machine modes are represented by an enumeration
993 type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL
994 expression has room for a machine mode and so do certain kinds of tree
995 expressions (declarations and types, to be precise).
997 In debugging dumps and machine descriptions, the machine mode of an RTL
998 expression is written after the expression code with a colon to separate
999 them. The letters @samp{mode} which appear at the end of each machine mode
1000 name are omitted. For example, @code{(reg:SI 38)} is a @code{reg}
1001 expression with machine mode @code{SImode}. If the mode is
1002 @code{VOIDmode}, it is not written at all.
1004 Here is a table of machine modes. The term ``byte'' below refers to an
1005 object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}).
1010 ``Bit'' mode represents a single bit, for predicate registers.
1014 ``Quarter-Integer'' mode represents a single byte treated as an integer.
1018 ``Half-Integer'' mode represents a two-byte integer.
1022 ``Partial Single Integer'' mode represents an integer which occupies
1023 four bytes but which doesn't really use all four. On some machines,
1024 this is the right mode to use for pointers.
1028 ``Single Integer'' mode represents a four-byte integer.
1032 ``Partial Double Integer'' mode represents an integer which occupies
1033 eight bytes but which doesn't really use all eight. On some machines,
1034 this is the right mode to use for certain pointers.
1038 ``Double Integer'' mode represents an eight-byte integer.
1042 ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
1046 ``Octa Integer'' (?) mode represents a thirty-two-byte integer.
1050 ``Quarter-Floating'' mode represents a quarter-precision (single byte)
1051 floating point number.
1055 ``Half-Floating'' mode represents a half-precision (two byte) floating
1060 ``Three-Quarter-Floating'' (?) mode represents a three-quarter-precision
1061 (three byte) floating point number.
1065 ``Single Floating'' mode represents a four byte floating point number.
1066 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1067 this is a single-precision IEEE floating point number; it can also be
1068 used for double-precision (on processors with 16-bit bytes) and
1069 single-precision VAX and IBM types.
1073 ``Double Floating'' mode represents an eight byte floating point number.
1074 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1075 this is a double-precision IEEE floating point number.
1079 ``Extended Floating'' mode represents an IEEE extended floating point
1080 number. This mode only has 80 meaningful bits (ten bytes). Some
1081 processors require such numbers to be padded to twelve bytes, others
1082 to sixteen; this mode is used for either.
1086 ``Single Decimal Floating'' mode represents a four byte decimal
1087 floating point number (as distinct from conventional binary floating
1092 ``Double Decimal Floating'' mode represents an eight byte decimal
1093 floating point number.
1097 ``Tetra Decimal Floating'' mode represents a sixteen byte decimal
1098 floating point number all 128 of whose bits are meaningful.
1102 ``Tetra Floating'' mode represents a sixteen byte floating point number
1103 all 128 of whose bits are meaningful. One common use is the
1104 IEEE quad-precision format.
1108 ``Condition Code'' mode represents the value of a condition code, which
1109 is a machine-specific set of bits used to represent the result of a
1110 comparison operation. Other machine-specific modes may also be used for
1111 the condition code. These modes are not used on machines that use
1112 @code{cc0} (see @pxref{Condition Code}).
1116 ``Block'' mode represents values that are aggregates to which none of
1117 the other modes apply. In RTL, only memory references can have this mode,
1118 and only if they appear in string-move or vector instructions. On machines
1119 which have no such instructions, @code{BLKmode} will not appear in RTL@.
1123 Void mode means the absence of a mode or an unspecified mode.
1124 For example, RTL expressions of code @code{const_int} have mode
1125 @code{VOIDmode} because they can be taken to have whatever mode the context
1126 requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by
1127 the absence of any mode.
1135 @item QCmode, HCmode, SCmode, DCmode, XCmode, TCmode
1136 These modes stand for a complex number represented as a pair of floating
1137 point values. The floating point values are in @code{QFmode},
1138 @code{HFmode}, @code{SFmode}, @code{DFmode}, @code{XFmode}, and
1139 @code{TFmode}, respectively.
1147 @item CQImode, CHImode, CSImode, CDImode, CTImode, COImode
1148 These modes stand for a complex number represented as a pair of integer
1149 values. The integer values are in @code{QImode}, @code{HImode},
1150 @code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode},
1154 The machine description defines @code{Pmode} as a C macro which expands
1155 into the machine mode used for addresses. Normally this is the mode
1156 whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines.
1158 The only modes which a machine description @i{must} support are
1159 @code{QImode}, and the modes corresponding to @code{BITS_PER_WORD},
1160 @code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}.
1161 The compiler will attempt to use @code{DImode} for 8-byte structures and
1162 unions, but this can be prevented by overriding the definition of
1163 @code{MAX_FIXED_MODE_SIZE}. Alternatively, you can have the compiler
1164 use @code{TImode} for 16-byte structures and unions. Likewise, you can
1165 arrange for the C type @code{short int} to avoid using @code{HImode}.
1167 @cindex mode classes
1168 Very few explicit references to machine modes remain in the compiler and
1169 these few references will soon be removed. Instead, the machine modes
1170 are divided into mode classes. These are represented by the enumeration
1171 type @code{enum mode_class} defined in @file{machmode.h}. The possible
1177 Integer modes. By default these are @code{BImode}, @code{QImode},
1178 @code{HImode}, @code{SImode}, @code{DImode}, @code{TImode}, and
1181 @findex MODE_PARTIAL_INT
1182 @item MODE_PARTIAL_INT
1183 The ``partial integer'' modes, @code{PQImode}, @code{PHImode},
1184 @code{PSImode} and @code{PDImode}.
1188 Floating point modes. By default these are @code{QFmode},
1189 @code{HFmode}, @code{TQFmode}, @code{SFmode}, @code{DFmode},
1190 @code{XFmode} and @code{TFmode}.
1192 @findex MODE_DECIMAL_FLOAT
1193 @item MODE_DECIMAL_FLOAT
1194 Decimal floating point modes. By default these are @code{SDmode},
1195 @code{DDmode} and @code{TDmode}.
1197 @findex MODE_COMPLEX_INT
1198 @item MODE_COMPLEX_INT
1199 Complex integer modes. (These are not currently implemented).
1201 @findex MODE_COMPLEX_FLOAT
1202 @item MODE_COMPLEX_FLOAT
1203 Complex floating point modes. By default these are @code{QCmode},
1204 @code{HCmode}, @code{SCmode}, @code{DCmode}, @code{XCmode}, and
1207 @findex MODE_FUNCTION
1209 Algol or Pascal function variables including a static chain.
1210 (These are not currently implemented).
1214 Modes representing condition code values. These are @code{CCmode} plus
1215 any @code{CC_MODE} modes listed in the @file{@var{machine}-modes.def}.
1216 @xref{Jump Patterns},
1217 also see @ref{Condition Code}.
1221 This is a catchall mode class for modes which don't fit into the above
1222 classes. Currently @code{VOIDmode} and @code{BLKmode} are in
1226 Here are some C macros that relate to machine modes:
1230 @item GET_MODE (@var{x})
1231 Returns the machine mode of the RTX @var{x}.
1234 @item PUT_MODE (@var{x}, @var{newmode})
1235 Alters the machine mode of the RTX @var{x} to be @var{newmode}.
1237 @findex NUM_MACHINE_MODES
1238 @item NUM_MACHINE_MODES
1239 Stands for the number of machine modes available on the target
1240 machine. This is one greater than the largest numeric value of any
1243 @findex GET_MODE_NAME
1244 @item GET_MODE_NAME (@var{m})
1245 Returns the name of mode @var{m} as a string.
1247 @findex GET_MODE_CLASS
1248 @item GET_MODE_CLASS (@var{m})
1249 Returns the mode class of mode @var{m}.
1251 @findex GET_MODE_WIDER_MODE
1252 @item GET_MODE_WIDER_MODE (@var{m})
1253 Returns the next wider natural mode. For example, the expression
1254 @code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}.
1256 @findex GET_MODE_SIZE
1257 @item GET_MODE_SIZE (@var{m})
1258 Returns the size in bytes of a datum of mode @var{m}.
1260 @findex GET_MODE_BITSIZE
1261 @item GET_MODE_BITSIZE (@var{m})
1262 Returns the size in bits of a datum of mode @var{m}.
1264 @findex GET_MODE_MASK
1265 @item GET_MODE_MASK (@var{m})
1266 Returns a bitmask containing 1 for all bits in a word that fit within
1267 mode @var{m}. This macro can only be used for modes whose bitsize is
1268 less than or equal to @code{HOST_BITS_PER_INT}.
1270 @findex GET_MODE_ALIGNMENT
1271 @item GET_MODE_ALIGNMENT (@var{m})
1272 Return the required alignment, in bits, for an object of mode @var{m}.
1274 @findex GET_MODE_UNIT_SIZE
1275 @item GET_MODE_UNIT_SIZE (@var{m})
1276 Returns the size in bytes of the subunits of a datum of mode @var{m}.
1277 This is the same as @code{GET_MODE_SIZE} except in the case of complex
1278 modes. For them, the unit size is the size of the real or imaginary
1281 @findex GET_MODE_NUNITS
1282 @item GET_MODE_NUNITS (@var{m})
1283 Returns the number of units contained in a mode, i.e.,
1284 @code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}.
1286 @findex GET_CLASS_NARROWEST_MODE
1287 @item GET_CLASS_NARROWEST_MODE (@var{c})
1288 Returns the narrowest mode in mode class @var{c}.
1293 The global variables @code{byte_mode} and @code{word_mode} contain modes
1294 whose classes are @code{MODE_INT} and whose bitsizes are either
1295 @code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit
1296 machines, these are @code{QImode} and @code{SImode}, respectively.
1299 @section Constant Expression Types
1300 @cindex RTL constants
1301 @cindex RTL constant expression types
1303 The simplest RTL expressions are those that represent constant values.
1307 @item (const_int @var{i})
1308 This type of expression represents the integer value @var{i}. @var{i}
1309 is customarily accessed with the macro @code{INTVAL} as in
1310 @code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}.
1312 Constants generated for modes with fewer bits than @code{HOST_WIDE_INT}
1313 must be sign extended to full width (e.g., with @code{gen_int_mode}).
1319 There is only one expression object for the integer value zero; it is
1320 the value of the variable @code{const0_rtx}. Likewise, the only
1321 expression for integer value one is found in @code{const1_rtx}, the only
1322 expression for integer value two is found in @code{const2_rtx}, and the
1323 only expression for integer value negative one is found in
1324 @code{constm1_rtx}. Any attempt to create an expression of code
1325 @code{const_int} and value zero, one, two or negative one will return
1326 @code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or
1327 @code{constm1_rtx} as appropriate.
1329 @findex const_true_rtx
1330 Similarly, there is only one object for the integer whose value is
1331 @code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If
1332 @code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and
1333 @code{const1_rtx} will point to the same object. If
1334 @code{STORE_FLAG_VALUE} is @minus{}1, @code{const_true_rtx} and
1335 @code{constm1_rtx} will point to the same object.
1337 @findex const_double
1338 @item (const_double:@var{m} @var{addr} @var{i0} @var{i1} @dots{})
1339 Represents either a floating-point constant of mode @var{m} or an
1340 integer constant too large to fit into @code{HOST_BITS_PER_WIDE_INT}
1341 bits but small enough to fit within twice that number of bits (GCC
1342 does not provide a mechanism to represent even larger constants). In
1343 the latter case, @var{m} will be @code{VOIDmode}.
1345 @findex const_vector
1346 @item (const_vector:@var{m} [@var{x0} @var{x1} @dots{}])
1347 Represents a vector constant. The square brackets stand for the vector
1348 containing the constant elements. @var{x0}, @var{x1} and so on are
1349 the @code{const_int} or @code{const_double} elements.
1351 The number of units in a @code{const_vector} is obtained with the macro
1352 @code{CONST_VECTOR_NUNITS} as in @code{CONST_VECTOR_NUNITS (@var{v})}.
1354 Individual elements in a vector constant are accessed with the macro
1355 @code{CONST_VECTOR_ELT} as in @code{CONST_VECTOR_ELT (@var{v}, @var{n})}
1356 where @var{v} is the vector constant and @var{n} is the element
1359 @findex CONST_DOUBLE_MEM
1360 @findex CONST_DOUBLE_CHAIN
1361 @var{addr} is used to contain the @code{mem} expression that corresponds
1362 to the location in memory that at which the constant can be found. If
1363 it has not been allocated a memory location, but is on the chain of all
1364 @code{const_double} expressions in this compilation (maintained using an
1365 undisplayed field), @var{addr} contains @code{const0_rtx}. If it is not
1366 on the chain, @var{addr} contains @code{cc0_rtx}. @var{addr} is
1367 customarily accessed with the macro @code{CONST_DOUBLE_MEM} and the
1368 chain field via @code{CONST_DOUBLE_CHAIN}.
1370 @findex CONST_DOUBLE_LOW
1371 If @var{m} is @code{VOIDmode}, the bits of the value are stored in
1372 @var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro
1373 @code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}.
1375 If the constant is floating point (regardless of its precision), then
1376 the number of integers used to store the value depends on the size of
1377 @code{REAL_VALUE_TYPE} (@pxref{Floating Point}). The integers
1378 represent a floating point number, but not precisely in the target
1379 machine's or host machine's floating point format. To convert them to
1380 the precise bit pattern used by the target machine, use the macro
1381 @code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}).
1386 The macro @code{CONST0_RTX (@var{mode})} refers to an expression with
1387 value 0 in mode @var{mode}. If mode @var{mode} is of mode class
1388 @code{MODE_INT}, it returns @code{const0_rtx}. If mode @var{mode} is of
1389 mode class @code{MODE_FLOAT}, it returns a @code{CONST_DOUBLE}
1390 expression in mode @var{mode}. Otherwise, it returns a
1391 @code{CONST_VECTOR} expression in mode @var{mode}. Similarly, the macro
1392 @code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in
1393 mode @var{mode} and similarly for @code{CONST2_RTX}. The
1394 @code{CONST1_RTX} and @code{CONST2_RTX} macros are undefined
1397 @findex const_string
1398 @item (const_string @var{str})
1399 Represents a constant string with value @var{str}. Currently this is
1400 used only for insn attributes (@pxref{Insn Attributes}) since constant
1401 strings in C are placed in memory.
1404 @item (symbol_ref:@var{mode} @var{symbol})
1405 Represents the value of an assembler label for data. @var{symbol} is
1406 a string that describes the name of the assembler label. If it starts
1407 with a @samp{*}, the label is the rest of @var{symbol} not including
1408 the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed
1411 The @code{symbol_ref} contains a mode, which is usually @code{Pmode}.
1412 Usually that is the only mode for which a symbol is directly valid.
1415 @item (label_ref:@var{mode} @var{label})
1416 Represents the value of an assembler label for code. It contains one
1417 operand, an expression, which must be a @code{code_label} or a @code{note}
1418 of type @code{NOTE_INSN_DELETED_LABEL} that appears in the instruction
1419 sequence to identify the place where the label should go.
1421 The reason for using a distinct expression type for code label
1422 references is so that jump optimization can distinguish them.
1424 The @code{label_ref} contains a mode, which is usually @code{Pmode}.
1425 Usually that is the only mode for which a label is directly valid.
1427 @item (const:@var{m} @var{exp})
1428 Represents a constant that is the result of an assembly-time
1429 arithmetic computation. The operand, @var{exp}, is an expression that
1430 contains only constants (@code{const_int}, @code{symbol_ref} and
1431 @code{label_ref} expressions) combined with @code{plus} and
1432 @code{minus}. However, not all combinations are valid, since the
1433 assembler cannot do arbitrary arithmetic on relocatable symbols.
1435 @var{m} should be @code{Pmode}.
1438 @item (high:@var{m} @var{exp})
1439 Represents the high-order bits of @var{exp}, usually a
1440 @code{symbol_ref}. The number of bits is machine-dependent and is
1441 normally the number of bits specified in an instruction that initializes
1442 the high order bits of a register. It is used with @code{lo_sum} to
1443 represent the typical two-instruction sequence used in RISC machines to
1444 reference a global memory location.
1446 @var{m} should be @code{Pmode}.
1449 @node Regs and Memory
1450 @section Registers and Memory
1451 @cindex RTL register expressions
1452 @cindex RTL memory expressions
1454 Here are the RTL expression types for describing access to machine
1455 registers and to main memory.
1459 @cindex hard registers
1460 @cindex pseudo registers
1461 @item (reg:@var{m} @var{n})
1462 For small values of the integer @var{n} (those that are less than
1463 @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
1464 register number @var{n}: a @dfn{hard register}. For larger values of
1465 @var{n}, it stands for a temporary value or @dfn{pseudo register}.
1466 The compiler's strategy is to generate code assuming an unlimited
1467 number of such pseudo registers, and later convert them into hard
1468 registers or into memory references.
1470 @var{m} is the machine mode of the reference. It is necessary because
1471 machines can generally refer to each register in more than one mode.
1472 For example, a register may contain a full word but there may be
1473 instructions to refer to it as a half word or as a single byte, as
1474 well as instructions to refer to it as a floating point number of
1477 Even for a register that the machine can access in only one mode,
1478 the mode must always be specified.
1480 The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
1481 description, since the number of hard registers on the machine is an
1482 invariant characteristic of the machine. Note, however, that not
1483 all of the machine registers must be general registers. All the
1484 machine registers that can be used for storage of data are given
1485 hard register numbers, even those that can be used only in certain
1486 instructions or can hold only certain types of data.
1488 A hard register may be accessed in various modes throughout one
1489 function, but each pseudo register is given a natural mode
1490 and is accessed only in that mode. When it is necessary to describe
1491 an access to a pseudo register using a nonnatural mode, a @code{subreg}
1494 A @code{reg} expression with a machine mode that specifies more than
1495 one word of data may actually stand for several consecutive registers.
1496 If in addition the register number specifies a hardware register, then
1497 it actually represents several consecutive hardware registers starting
1498 with the specified one.
1500 Each pseudo register number used in a function's RTL code is
1501 represented by a unique @code{reg} expression.
1503 @findex FIRST_VIRTUAL_REGISTER
1504 @findex LAST_VIRTUAL_REGISTER
1505 Some pseudo register numbers, those within the range of
1506 @code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only
1507 appear during the RTL generation phase and are eliminated before the
1508 optimization phases. These represent locations in the stack frame that
1509 cannot be determined until RTL generation for the function has been
1510 completed. The following virtual register numbers are defined:
1513 @findex VIRTUAL_INCOMING_ARGS_REGNUM
1514 @item VIRTUAL_INCOMING_ARGS_REGNUM
1515 This points to the first word of the incoming arguments passed on the
1516 stack. Normally these arguments are placed there by the caller, but the
1517 callee may have pushed some arguments that were previously passed in
1520 @cindex @code{FIRST_PARM_OFFSET} and virtual registers
1521 @cindex @code{ARG_POINTER_REGNUM} and virtual registers
1522 When RTL generation is complete, this virtual register is replaced
1523 by the sum of the register given by @code{ARG_POINTER_REGNUM} and the
1524 value of @code{FIRST_PARM_OFFSET}.
1526 @findex VIRTUAL_STACK_VARS_REGNUM
1527 @cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers
1528 @item VIRTUAL_STACK_VARS_REGNUM
1529 If @code{FRAME_GROWS_DOWNWARD} is defined to a nonzero value, this points
1530 to immediately above the first variable on the stack. Otherwise, it points
1531 to the first variable on the stack.
1533 @cindex @code{STARTING_FRAME_OFFSET} and virtual registers
1534 @cindex @code{FRAME_POINTER_REGNUM} and virtual registers
1535 @code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the
1536 register given by @code{FRAME_POINTER_REGNUM} and the value
1537 @code{STARTING_FRAME_OFFSET}.
1539 @findex VIRTUAL_STACK_DYNAMIC_REGNUM
1540 @item VIRTUAL_STACK_DYNAMIC_REGNUM
1541 This points to the location of dynamically allocated memory on the stack
1542 immediately after the stack pointer has been adjusted by the amount of
1545 @cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers
1546 @cindex @code{STACK_POINTER_REGNUM} and virtual registers
1547 This virtual register is replaced by the sum of the register given by
1548 @code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}.
1550 @findex VIRTUAL_OUTGOING_ARGS_REGNUM
1551 @item VIRTUAL_OUTGOING_ARGS_REGNUM
1552 This points to the location in the stack at which outgoing arguments
1553 should be written when the stack is pre-pushed (arguments pushed using
1554 push insns should always use @code{STACK_POINTER_REGNUM}).
1556 @cindex @code{STACK_POINTER_OFFSET} and virtual registers
1557 This virtual register is replaced by the sum of the register given by
1558 @code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}.
1562 @item (subreg:@var{m} @var{reg} @var{bytenum})
1563 @code{subreg} expressions are used to refer to a register in a machine
1564 mode other than its natural one, or to refer to one register of
1565 a multi-part @code{reg} that actually refers to several registers.
1567 Each pseudo-register has a natural mode. If it is necessary to
1568 operate on it in a different mode---for example, to perform a fullword
1569 move instruction on a pseudo-register that contains a single
1570 byte---the pseudo-register must be enclosed in a @code{subreg}. In
1571 such a case, @var{bytenum} is zero.
1573 Usually @var{m} is at least as narrow as the mode of @var{reg}, in which
1574 case it is restricting consideration to only the bits of @var{reg} that
1577 Sometimes @var{m} is wider than the mode of @var{reg}. These
1578 @code{subreg} expressions are often called @dfn{paradoxical}. They are
1579 used in cases where we want to refer to an object in a wider mode but do
1580 not care what value the additional bits have. The reload pass ensures
1581 that paradoxical references are only made to hard registers.
1583 The other use of @code{subreg} is to extract the individual registers of
1584 a multi-register value. Machine modes such as @code{DImode} and
1585 @code{TImode} can indicate values longer than a word, values which
1586 usually require two or more consecutive registers. To access one of the
1587 registers, use a @code{subreg} with mode @code{SImode} and a
1588 @var{bytenum} offset that says which register.
1590 Storing in a non-paradoxical @code{subreg} has undefined results for
1591 bits belonging to the same word as the @code{subreg}. This laxity makes
1592 it easier to generate efficient code for such instructions. To
1593 represent an instruction that preserves all the bits outside of those in
1594 the @code{subreg}, use @code{strict_low_part} around the @code{subreg}.
1596 @cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
1597 The compilation parameter @code{WORDS_BIG_ENDIAN}, if set to 1, says
1598 that byte number zero is part of the most significant word; otherwise,
1599 it is part of the least significant word.
1601 @cindex @code{BYTES_BIG_ENDIAN}, effect on @code{subreg}
1602 The compilation parameter @code{BYTES_BIG_ENDIAN}, if set to 1, says
1603 that byte number zero is the most significant byte within a word;
1604 otherwise, it is the least significant byte within a word.
1606 @cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg}
1607 On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with
1608 @code{WORDS_BIG_ENDIAN}.
1609 However, most parts of the compiler treat floating point values as if
1610 they had the same endianness as integer values. This works because
1611 they handle them solely as a collection of integer values, with no
1612 particular numerical value. Only real.c and the runtime libraries
1613 care about @code{FLOAT_WORDS_BIG_ENDIAN}.
1615 @cindex combiner pass
1617 @cindex @code{subreg}, special reload handling
1618 Between the combiner pass and the reload pass, it is possible to have a
1619 paradoxical @code{subreg} which contains a @code{mem} instead of a
1620 @code{reg} as its first operand. After the reload pass, it is also
1621 possible to have a non-paradoxical @code{subreg} which contains a
1622 @code{mem}; this usually occurs when the @code{mem} is a stack slot
1623 which replaced a pseudo register.
1625 Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
1626 using a @code{subreg}. On some machines the most significant part of a
1627 @code{DFmode} value does not have the same format as a single-precision
1630 It is also not valid to access a single word of a multi-word value in a
1631 hard register when less registers can hold the value than would be
1632 expected from its size. For example, some 32-bit machines have
1633 floating-point registers that can hold an entire @code{DFmode} value.
1634 If register 10 were such a register @code{(subreg:SI (reg:DF 10) 4)}
1635 would be invalid because there is no way to convert that reference to
1636 a single machine register. The reload pass prevents @code{subreg}
1637 expressions such as these from being formed.
1641 The first operand of a @code{subreg} expression is customarily accessed
1642 with the @code{SUBREG_REG} macro and the second operand is customarily
1643 accessed with the @code{SUBREG_BYTE} macro.
1646 @cindex scratch operands
1647 @item (scratch:@var{m})
1648 This represents a scratch register that will be required for the
1649 execution of a single instruction and not used subsequently. It is
1650 converted into a @code{reg} by either the local register allocator or
1653 @code{scratch} is usually present inside a @code{clobber} operation
1654 (@pxref{Side Effects}).
1657 @cindex condition code register
1659 This refers to the machine's condition code register. It has no
1660 operands and may not have a machine mode. There are two ways to use it:
1664 To stand for a complete set of condition code flags. This is best on
1665 most machines, where each comparison sets the entire series of flags.
1667 With this technique, @code{(cc0)} may be validly used in only two
1668 contexts: as the destination of an assignment (in test and compare
1669 instructions) and in comparison operators comparing against zero
1670 (@code{const_int} with value zero; that is to say, @code{const0_rtx}).
1673 To stand for a single flag that is the result of a single condition.
1674 This is useful on machines that have only a single flag bit, and in
1675 which comparison instructions must specify the condition to test.
1677 With this technique, @code{(cc0)} may be validly used in only two
1678 contexts: as the destination of an assignment (in test and compare
1679 instructions) where the source is a comparison operator, and as the
1680 first operand of @code{if_then_else} (in a conditional branch).
1684 There is only one expression object of code @code{cc0}; it is the
1685 value of the variable @code{cc0_rtx}. Any attempt to create an
1686 expression of code @code{cc0} will return @code{cc0_rtx}.
1688 Instructions can set the condition code implicitly. On many machines,
1689 nearly all instructions set the condition code based on the value that
1690 they compute or store. It is not necessary to record these actions
1691 explicitly in the RTL because the machine description includes a
1692 prescription for recognizing the instructions that do so (by means of
1693 the macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only
1694 instructions whose sole purpose is to set the condition code, and
1695 instructions that use the condition code, need mention @code{(cc0)}.
1697 On some machines, the condition code register is given a register number
1698 and a @code{reg} is used instead of @code{(cc0)}. This is usually the
1699 preferable approach if only a small subset of instructions modify the
1700 condition code. Other machines store condition codes in general
1701 registers; in such cases a pseudo register should be used.
1703 Some machines, such as the SPARC and RS/6000, have two sets of
1704 arithmetic instructions, one that sets and one that does not set the
1705 condition code. This is best handled by normally generating the
1706 instruction that does not set the condition code, and making a pattern
1707 that both performs the arithmetic and sets the condition code register
1708 (which would not be @code{(cc0)} in this case). For examples, search
1709 for @samp{addcc} and @samp{andcc} in @file{sparc.md}.
1713 @cindex program counter
1714 This represents the machine's program counter. It has no operands and
1715 may not have a machine mode. @code{(pc)} may be validly used only in
1716 certain specific contexts in jump instructions.
1719 There is only one expression object of code @code{pc}; it is the value
1720 of the variable @code{pc_rtx}. Any attempt to create an expression of
1721 code @code{pc} will return @code{pc_rtx}.
1723 All instructions that do not jump alter the program counter implicitly
1724 by incrementing it, but there is no need to mention this in the RTL@.
1727 @item (mem:@var{m} @var{addr} @var{alias})
1728 This RTX represents a reference to main memory at an address
1729 represented by the expression @var{addr}. @var{m} specifies how large
1730 a unit of memory is accessed. @var{alias} specifies an alias set for the
1731 reference. In general two items are in different alias sets if they cannot
1732 reference the same memory address.
1734 The construct @code{(mem:BLK (scratch))} is considered to alias all
1735 other memories. Thus it may be used as a memory barrier in epilogue
1736 stack deallocation patterns.
1739 @item (addressof:@var{m} @var{reg})
1740 This RTX represents a request for the address of register @var{reg}. Its mode
1741 is always @code{Pmode}. If there are any @code{addressof}
1742 expressions left in the function after CSE, @var{reg} is forced into the
1743 stack and the @code{addressof} expression is replaced with a @code{plus}
1744 expression for the address of its stack slot.
1748 @section RTL Expressions for Arithmetic
1749 @cindex arithmetic, in RTL
1750 @cindex math, in RTL
1751 @cindex RTL expressions for arithmetic
1753 Unless otherwise specified, all the operands of arithmetic expressions
1754 must be valid for mode @var{m}. An operand is valid for mode @var{m}
1755 if it has mode @var{m}, or if it is a @code{const_int} or
1756 @code{const_double} and @var{m} is a mode of class @code{MODE_INT}.
1758 For commutative binary operations, constants should be placed in the
1766 @cindex RTL addition
1767 @cindex RTL addition with signed saturation
1768 @cindex RTL addition with unsigned saturation
1769 @item (plus:@var{m} @var{x} @var{y})
1770 @itemx (ss_plus:@var{m} @var{x} @var{y})
1771 @itemx (us_plus:@var{m} @var{x} @var{y})
1773 These three expressions all represent the sum of the values
1774 represented by @var{x} and @var{y} carried out in machine mode
1775 @var{m}. They differ in their behavior on overflow of integer modes.
1776 @code{plus} wraps round modulo the width of @var{m}; @code{ss_plus}
1777 saturates at the maximum signed value representable in @var{m};
1778 @code{us_plus} saturates at the maximum unsigned value.
1780 @c ??? What happens on overflow of floating point modes?
1783 @item (lo_sum:@var{m} @var{x} @var{y})
1785 This expression represents the sum of @var{x} and the low-order bits
1786 of @var{y}. It is used with @code{high} (@pxref{Constants}) to
1787 represent the typical two-instruction sequence used in RISC machines
1788 to reference a global memory location.
1790 The number of low order bits is machine-dependent but is
1791 normally the number of bits in a @code{Pmode} item minus the number of
1792 bits set by @code{high}.
1794 @var{m} should be @code{Pmode}.
1799 @cindex RTL difference
1800 @cindex RTL subtraction
1801 @cindex RTL subtraction with signed saturation
1802 @cindex RTL subtraction with unsigned saturation
1803 @item (minus:@var{m} @var{x} @var{y})
1804 @itemx (ss_minus:@var{m} @var{x} @var{y})
1805 @itemx (us_minus:@var{m} @var{x} @var{y})
1807 These three expressions represent the result of subtracting @var{y}
1808 from @var{x}, carried out in mode @var{M}. Behavior on overflow is
1809 the same as for the three variants of @code{plus} (see above).
1812 @cindex RTL comparison
1813 @item (compare:@var{m} @var{x} @var{y})
1814 Represents the result of subtracting @var{y} from @var{x} for purposes
1815 of comparison. The result is computed without overflow, as if with
1818 Of course, machines can't really subtract with infinite precision.
1819 However, they can pretend to do so when only the sign of the result will
1820 be used, which is the case when the result is stored in the condition
1821 code. And that is the @emph{only} way this kind of expression may
1822 validly be used: as a value to be stored in the condition codes, either
1823 @code{(cc0)} or a register. @xref{Comparisons}.
1825 The mode @var{m} is not related to the modes of @var{x} and @var{y}, but
1826 instead is the mode of the condition code value. If @code{(cc0)} is
1827 used, it is @code{VOIDmode}. Otherwise it is some mode in class
1828 @code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}. If @var{m}
1829 is @code{VOIDmode} or @code{CCmode}, the operation returns sufficient
1830 information (in an unspecified format) so that any comparison operator
1831 can be applied to the result of the @code{COMPARE} operation. For other
1832 modes in class @code{MODE_CC}, the operation only returns a subset of
1835 Normally, @var{x} and @var{y} must have the same mode. Otherwise,
1836 @code{compare} is valid only if the mode of @var{x} is in class
1837 @code{MODE_INT} and @var{y} is a @code{const_int} or
1838 @code{const_double} with mode @code{VOIDmode}. The mode of @var{x}
1839 determines what mode the comparison is to be done in; thus it must not
1842 If one of the operands is a constant, it should be placed in the
1843 second operand and the comparison code adjusted as appropriate.
1845 A @code{compare} specifying two @code{VOIDmode} constants is not valid
1846 since there is no way to know in what mode the comparison is to be
1847 performed; the comparison must either be folded during the compilation
1848 or the first operand must be loaded into a register while its mode is
1852 @item (neg:@var{m} @var{x})
1853 Represents the negation (subtraction from zero) of the value represented
1854 by @var{x}, carried out in mode @var{m}.
1857 @cindex multiplication
1859 @item (mult:@var{m} @var{x} @var{y})
1860 Represents the signed product of the values represented by @var{x} and
1861 @var{y} carried out in machine mode @var{m}.
1863 Some machines support a multiplication that generates a product wider
1864 than the operands. Write the pattern for this as
1867 (mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
1870 where @var{m} is wider than the modes of @var{x} and @var{y}, which need
1873 For unsigned widening multiplication, use the same idiom, but with
1874 @code{zero_extend} instead of @code{sign_extend}.
1878 @cindex signed division
1880 @item (div:@var{m} @var{x} @var{y})
1881 Represents the quotient in signed division of @var{x} by @var{y},
1882 carried out in machine mode @var{m}. If @var{m} is a floating point
1883 mode, it represents the exact quotient; otherwise, the integerized
1886 Some machines have division instructions in which the operands and
1887 quotient widths are not all the same; you should represent
1888 such instructions using @code{truncate} and @code{sign_extend} as in,
1891 (truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
1895 @cindex unsigned division
1897 @item (udiv:@var{m} @var{x} @var{y})
1898 Like @code{div} but represents unsigned division.
1904 @item (mod:@var{m} @var{x} @var{y})
1905 @itemx (umod:@var{m} @var{x} @var{y})
1906 Like @code{div} and @code{udiv} but represent the remainder instead of
1911 @cindex signed minimum
1912 @cindex signed maximum
1913 @item (smin:@var{m} @var{x} @var{y})
1914 @itemx (smax:@var{m} @var{x} @var{y})
1915 Represents the smaller (for @code{smin}) or larger (for @code{smax}) of
1916 @var{x} and @var{y}, interpreted as signed values in mode @var{m}.
1917 When used with floating point, if both operands are zeros, or if either
1918 operand is @code{NaN}, then it is unspecified which of the two operands
1919 is returned as the result.
1923 @cindex unsigned minimum and maximum
1924 @item (umin:@var{m} @var{x} @var{y})
1925 @itemx (umax:@var{m} @var{x} @var{y})
1926 Like @code{smin} and @code{smax}, but the values are interpreted as unsigned
1930 @cindex complement, bitwise
1931 @cindex bitwise complement
1932 @item (not:@var{m} @var{x})
1933 Represents the bitwise complement of the value represented by @var{x},
1934 carried out in mode @var{m}, which must be a fixed-point machine mode.
1937 @cindex logical-and, bitwise
1938 @cindex bitwise logical-and
1939 @item (and:@var{m} @var{x} @var{y})
1940 Represents the bitwise logical-and of the values represented by
1941 @var{x} and @var{y}, carried out in machine mode @var{m}, which must be
1942 a fixed-point machine mode.
1945 @cindex inclusive-or, bitwise
1946 @cindex bitwise inclusive-or
1947 @item (ior:@var{m} @var{x} @var{y})
1948 Represents the bitwise inclusive-or of the values represented by @var{x}
1949 and @var{y}, carried out in machine mode @var{m}, which must be a
1953 @cindex exclusive-or, bitwise
1954 @cindex bitwise exclusive-or
1955 @item (xor:@var{m} @var{x} @var{y})
1956 Represents the bitwise exclusive-or of the values represented by @var{x}
1957 and @var{y}, carried out in machine mode @var{m}, which must be a
1963 @cindex arithmetic shift
1964 @item (ashift:@var{m} @var{x} @var{c})
1965 Represents the result of arithmetically shifting @var{x} left by @var{c}
1966 places. @var{x} have mode @var{m}, a fixed-point machine mode. @var{c}
1967 be a fixed-point mode or be a constant with mode @code{VOIDmode}; which
1968 mode is determined by the mode called for in the machine description
1969 entry for the left-shift instruction. For example, on the VAX, the mode
1970 of @var{c} is @code{QImode} regardless of @var{m}.
1975 @item (lshiftrt:@var{m} @var{x} @var{c})
1976 @itemx (ashiftrt:@var{m} @var{x} @var{c})
1977 Like @code{ashift} but for right shift. Unlike the case for left shift,
1978 these two operations are distinct.
1984 @cindex right rotate
1985 @item (rotate:@var{m} @var{x} @var{c})
1986 @itemx (rotatert:@var{m} @var{x} @var{c})
1987 Similar but represent left and right rotate. If @var{c} is a constant,
1991 @cindex absolute value
1992 @item (abs:@var{m} @var{x})
1993 Represents the absolute value of @var{x}, computed in mode @var{m}.
1997 @item (sqrt:@var{m} @var{x})
1998 Represents the square root of @var{x}, computed in mode @var{m}.
1999 Most often @var{m} will be a floating point mode.
2002 @item (ffs:@var{m} @var{x})
2003 Represents one plus the index of the least significant 1-bit in
2004 @var{x}, represented as an integer of mode @var{m}. (The value is
2005 zero if @var{x} is zero.) The mode of @var{x} need not be @var{m};
2006 depending on the target machine, various mode combinations may be
2010 @item (clz:@var{m} @var{x})
2011 Represents the number of leading 0-bits in @var{x}, represented as an
2012 integer of mode @var{m}, starting at the most significant bit position.
2013 If @var{x} is zero, the value is determined by
2014 @code{CLZ_DEFINED_VALUE_AT_ZERO}. Note that this is one of
2015 the few expressions that is not invariant under widening. The mode of
2016 @var{x} will usually be an integer mode.
2019 @item (ctz:@var{m} @var{x})
2020 Represents the number of trailing 0-bits in @var{x}, represented as an
2021 integer of mode @var{m}, starting at the least significant bit position.
2022 If @var{x} is zero, the value is determined by
2023 @code{CTZ_DEFINED_VALUE_AT_ZERO}. Except for this case,
2024 @code{ctz(x)} is equivalent to @code{ffs(@var{x}) - 1}. The mode of
2025 @var{x} will usually be an integer mode.
2028 @item (popcount:@var{m} @var{x})
2029 Represents the number of 1-bits in @var{x}, represented as an integer of
2030 mode @var{m}. The mode of @var{x} will usually be an integer mode.
2033 @item (parity:@var{m} @var{x})
2034 Represents the number of 1-bits modulo 2 in @var{x}, represented as an
2035 integer of mode @var{m}. The mode of @var{x} will usually be an integer
2040 @section Comparison Operations
2041 @cindex RTL comparison operations
2043 Comparison operators test a relation on two operands and are considered
2044 to represent a machine-dependent nonzero value described by, but not
2045 necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
2046 if the relation holds, or zero if it does not, for comparison operators
2047 whose results have a `MODE_INT' mode,
2048 @code{FLOAT_STORE_FLAG_VALUE} (@pxref{Misc}) if the relation holds, or
2049 zero if it does not, for comparison operators that return floating-point
2050 values, and a vector of either @code{VECTOR_STORE_FLAG_VALUE} (@pxref{Misc})
2051 if the relation holds, or of zeros if it does not, for comparison operators
2052 that return vector results.
2053 The mode of the comparison operation is independent of the mode
2054 of the data being compared. If the comparison operation is being tested
2055 (e.g., the first operand of an @code{if_then_else}), the mode must be
2058 @cindex condition codes
2059 There are two ways that comparison operations may be used. The
2060 comparison operators may be used to compare the condition codes
2061 @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such
2062 a construct actually refers to the result of the preceding instruction
2063 in which the condition codes were set. The instruction setting the
2064 condition code must be adjacent to the instruction using the condition
2065 code; only @code{note} insns may separate them.
2067 Alternatively, a comparison operation may directly compare two data
2068 objects. The mode of the comparison is determined by the operands; they
2069 must both be valid for a common machine mode. A comparison with both
2070 operands constant would be invalid as the machine mode could not be
2071 deduced from it, but such a comparison should never exist in RTL due to
2074 In the example above, if @code{(cc0)} were last set to
2075 @code{(compare @var{x} @var{y})}, the comparison operation is
2076 identical to @code{(eq @var{x} @var{y})}. Usually only one style
2077 of comparisons is supported on a particular machine, but the combine
2078 pass will try to merge the operations to produce the @code{eq} shown
2079 in case it exists in the context of the particular insn involved.
2081 Inequality comparisons come in two flavors, signed and unsigned. Thus,
2082 there are distinct expression codes @code{gt} and @code{gtu} for signed and
2083 unsigned greater-than. These can produce different results for the same
2084 pair of integer values: for example, 1 is signed greater-than @minus{}1 but not
2085 unsigned greater-than, because @minus{}1 when regarded as unsigned is actually
2086 @code{0xffffffff} which is greater than 1.
2088 The signed comparisons are also used for floating point values. Floating
2089 point comparisons are distinguished by the machine modes of the operands.
2094 @item (eq:@var{m} @var{x} @var{y})
2095 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2096 are equal, otherwise 0.
2100 @item (ne:@var{m} @var{x} @var{y})
2101 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2102 are not equal, otherwise 0.
2105 @cindex greater than
2106 @item (gt:@var{m} @var{x} @var{y})
2107 @code{STORE_FLAG_VALUE} if the @var{x} is greater than @var{y}. If they
2108 are fixed-point, the comparison is done in a signed sense.
2111 @cindex greater than
2112 @cindex unsigned greater than
2113 @item (gtu:@var{m} @var{x} @var{y})
2114 Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
2119 @cindex unsigned less than
2120 @item (lt:@var{m} @var{x} @var{y})
2121 @itemx (ltu:@var{m} @var{x} @var{y})
2122 Like @code{gt} and @code{gtu} but test for ``less than''.
2125 @cindex greater than
2127 @cindex unsigned greater than
2128 @item (ge:@var{m} @var{x} @var{y})
2129 @itemx (geu:@var{m} @var{x} @var{y})
2130 Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
2133 @cindex less than or equal
2135 @cindex unsigned less than
2136 @item (le:@var{m} @var{x} @var{y})
2137 @itemx (leu:@var{m} @var{x} @var{y})
2138 Like @code{gt} and @code{gtu} but test for ``less than or equal''.
2140 @findex if_then_else
2141 @item (if_then_else @var{cond} @var{then} @var{else})
2142 This is not a comparison operation but is listed here because it is
2143 always used in conjunction with a comparison operation. To be
2144 precise, @var{cond} is a comparison expression. This expression
2145 represents a choice, according to @var{cond}, between the value
2146 represented by @var{then} and the one represented by @var{else}.
2148 On most machines, @code{if_then_else} expressions are valid only
2149 to express conditional jumps.
2152 @item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
2153 Similar to @code{if_then_else}, but more general. Each of @var{test1},
2154 @var{test2}, @dots{} is performed in turn. The result of this expression is
2155 the @var{value} corresponding to the first nonzero test, or @var{default} if
2156 none of the tests are nonzero expressions.
2158 This is currently not valid for instruction patterns and is supported only
2159 for insn attributes. @xref{Insn Attributes}.
2166 Special expression codes exist to represent bit-field instructions.
2169 @findex sign_extract
2170 @cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
2171 @item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
2172 This represents a reference to a sign-extended bit-field contained or
2173 starting in @var{loc} (a memory or register reference). The bit-field
2174 is @var{size} bits wide and starts at bit @var{pos}. The compilation
2175 option @code{BITS_BIG_ENDIAN} says which end of the memory unit
2176 @var{pos} counts from.
2178 If @var{loc} is in memory, its mode must be a single-byte integer mode.
2179 If @var{loc} is in a register, the mode to use is specified by the
2180 operand of the @code{insv} or @code{extv} pattern
2181 (@pxref{Standard Names}) and is usually a full-word integer mode,
2182 which is the default if none is specified.
2184 The mode of @var{pos} is machine-specific and is also specified
2185 in the @code{insv} or @code{extv} pattern.
2187 The mode @var{m} is the same as the mode that would be used for
2188 @var{loc} if it were a register.
2190 A @code{sign_extract} can not appear as an lvalue, or part thereof,
2193 @findex zero_extract
2194 @item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
2195 Like @code{sign_extract} but refers to an unsigned or zero-extended
2196 bit-field. The same sequence of bits are extracted, but they
2197 are filled to an entire word with zeros instead of by sign-extension.
2199 Unlike @code{sign_extract}, this type of expressions can be lvalues
2200 in RTL; they may appear on the left side of an assignment, indicating
2201 insertion of a value into the specified bit-field.
2204 @node Vector Operations
2205 @section Vector Operations
2206 @cindex vector operations
2208 All normal RTL expressions can be used with vector modes; they are
2209 interpreted as operating on each part of the vector independently.
2210 Additionally, there are a few new expressions to describe specific vector
2215 @item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items})
2216 This describes a merge operation between two vectors. The result is a vector
2217 of mode @var{m}; its elements are selected from either @var{vec1} or
2218 @var{vec2}. Which elements are selected is described by @var{items}, which
2219 is a bit mask represented by a @code{const_int}; a zero bit indicates the
2220 corresponding element in the result vector is taken from @var{vec2} while
2221 a set bit indicates it is taken from @var{vec1}.
2224 @item (vec_select:@var{m} @var{vec1} @var{selection})
2225 This describes an operation that selects parts of a vector. @var{vec1} is
2226 the source vector, @var{selection} is a @code{parallel} that contains a
2227 @code{const_int} for each of the subparts of the result vector, giving the
2228 number of the source subpart that should be stored into it.
2231 @item (vec_concat:@var{m} @var{vec1} @var{vec2})
2232 Describes a vector concat operation. The result is a concatenation of the
2233 vectors @var{vec1} and @var{vec2}; its length is the sum of the lengths of
2236 @findex vec_duplicate
2237 @item (vec_duplicate:@var{m} @var{vec})
2238 This operation converts a small vector into a larger one by duplicating the
2239 input values. The output vector mode must have the same submodes as the
2240 input vector mode, and the number of output parts must be an integer multiple
2241 of the number of input parts.
2246 @section Conversions
2248 @cindex machine mode conversions
2250 All conversions between machine modes must be represented by
2251 explicit conversion operations. For example, an expression
2252 which is the sum of a byte and a full word cannot be written as
2253 @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
2254 operation requires two operands of the same machine mode.
2255 Therefore, the byte-sized operand is enclosed in a conversion
2259 (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
2262 The conversion operation is not a mere placeholder, because there
2263 may be more than one way of converting from a given starting mode
2264 to the desired final mode. The conversion operation code says how
2267 For all conversion operations, @var{x} must not be @code{VOIDmode}
2268 because the mode in which to do the conversion would not be known.
2269 The conversion must either be done at compile-time or @var{x}
2270 must be placed into a register.
2274 @item (sign_extend:@var{m} @var{x})
2275 Represents the result of sign-extending the value @var{x}
2276 to machine mode @var{m}. @var{m} must be a fixed-point mode
2277 and @var{x} a fixed-point value of a mode narrower than @var{m}.
2280 @item (zero_extend:@var{m} @var{x})
2281 Represents the result of zero-extending the value @var{x}
2282 to machine mode @var{m}. @var{m} must be a fixed-point mode
2283 and @var{x} a fixed-point value of a mode narrower than @var{m}.
2285 @findex float_extend
2286 @item (float_extend:@var{m} @var{x})
2287 Represents the result of extending the value @var{x}
2288 to machine mode @var{m}. @var{m} must be a floating point mode
2289 and @var{x} a floating point value of a mode narrower than @var{m}.
2292 @item (truncate:@var{m} @var{x})
2293 Represents the result of truncating the value @var{x}
2294 to machine mode @var{m}. @var{m} must be a fixed-point mode
2295 and @var{x} a fixed-point value of a mode wider than @var{m}.
2298 @item (ss_truncate:@var{m} @var{x})
2299 Represents the result of truncating the value @var{x}
2300 to machine mode @var{m}, using signed saturation in the case of
2301 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
2305 @item (us_truncate:@var{m} @var{x})
2306 Represents the result of truncating the value @var{x}
2307 to machine mode @var{m}, using unsigned saturation in the case of
2308 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
2311 @findex float_truncate
2312 @item (float_truncate:@var{m} @var{x})
2313 Represents the result of truncating the value @var{x}
2314 to machine mode @var{m}. @var{m} must be a floating point mode
2315 and @var{x} a floating point value of a mode wider than @var{m}.
2318 @item (float:@var{m} @var{x})
2319 Represents the result of converting fixed point value @var{x},
2320 regarded as signed, to floating point mode @var{m}.
2322 @findex unsigned_float
2323 @item (unsigned_float:@var{m} @var{x})
2324 Represents the result of converting fixed point value @var{x},
2325 regarded as unsigned, to floating point mode @var{m}.
2328 @item (fix:@var{m} @var{x})
2329 When @var{m} is a fixed point mode, represents the result of
2330 converting floating point value @var{x} to mode @var{m}, regarded as
2331 signed. How rounding is done is not specified, so this operation may
2332 be used validly in compiling C code only for integer-valued operands.
2334 @findex unsigned_fix
2335 @item (unsigned_fix:@var{m} @var{x})
2336 Represents the result of converting floating point value @var{x} to
2337 fixed point mode @var{m}, regarded as unsigned. How rounding is done
2341 @item (fix:@var{m} @var{x})
2342 When @var{m} is a floating point mode, represents the result of
2343 converting floating point value @var{x} (valid for mode @var{m}) to an
2344 integer, still represented in floating point mode @var{m}, by rounding
2348 @node RTL Declarations
2349 @section Declarations
2350 @cindex RTL declarations
2351 @cindex declarations, RTL
2353 Declaration expression codes do not represent arithmetic operations
2354 but rather state assertions about their operands.
2357 @findex strict_low_part
2358 @cindex @code{subreg}, in @code{strict_low_part}
2359 @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
2360 This expression code is used in only one context: as the destination operand of a
2361 @code{set} expression. In addition, the operand of this expression
2362 must be a non-paradoxical @code{subreg} expression.
2364 The presence of @code{strict_low_part} says that the part of the
2365 register which is meaningful in mode @var{n}, but is not part of
2366 mode @var{m}, is not to be altered. Normally, an assignment to such
2367 a subreg is allowed to have undefined effects on the rest of the
2368 register when @var{m} is less than a word.
2372 @section Side Effect Expressions
2373 @cindex RTL side effect expressions
2375 The expression codes described so far represent values, not actions.
2376 But machine instructions never produce values; they are meaningful
2377 only for their side effects on the state of the machine. Special
2378 expression codes are used to represent side effects.
2380 The body of an instruction is always one of these side effect codes;
2381 the codes described above, which represent values, appear only as
2382 the operands of these.
2386 @item (set @var{lval} @var{x})
2387 Represents the action of storing the value of @var{x} into the place
2388 represented by @var{lval}. @var{lval} must be an expression
2389 representing a place that can be stored in: @code{reg} (or @code{subreg},
2390 @code{strict_low_part} or @code{zero_extract}), @code{mem}, @code{pc},
2391 @code{parallel}, or @code{cc0}.
2393 If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
2394 machine mode; then @var{x} must be valid for that mode.
2396 If @var{lval} is a @code{reg} whose machine mode is less than the full
2397 width of the register, then it means that the part of the register
2398 specified by the machine mode is given the specified value and the
2399 rest of the register receives an undefined value. Likewise, if
2400 @var{lval} is a @code{subreg} whose machine mode is narrower than
2401 the mode of the register, the rest of the register can be changed in
2404 If @var{lval} is a @code{strict_low_part} of a subreg, then the part
2405 of the register specified by the machine mode of the @code{subreg} is
2406 given the value @var{x} and the rest of the register is not changed.
2408 If @var{lval} is a @code{zero_extract}, then the referenced part of
2409 the bit-field (a memory or register reference) specified by the
2410 @code{zero_extract} is given the value @var{x} and the rest of the
2411 bit-field is not changed. Note that @code{sign_extract} can not
2412 appear in @var{lval}.
2414 If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
2415 be either a @code{compare} expression or a value that may have any mode.
2416 The latter case represents a ``test'' instruction. The expression
2417 @code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to
2418 @code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}.
2419 Use the former expression to save space during the compilation.
2421 If @var{lval} is a @code{parallel}, it is used to represent the case of
2422 a function returning a structure in multiple registers. Each element
2423 of the @code{parallel} is an @code{expr_list} whose first operand is a
2424 @code{reg} and whose second operand is a @code{const_int} representing the
2425 offset (in bytes) into the structure at which the data in that register
2426 corresponds. The first element may be null to indicate that the structure
2427 is also passed partly in memory.
2429 @cindex jump instructions and @code{set}
2430 @cindex @code{if_then_else} usage
2431 If @var{lval} is @code{(pc)}, we have a jump instruction, and the
2432 possibilities for @var{x} are very limited. It may be a
2433 @code{label_ref} expression (unconditional jump). It may be an
2434 @code{if_then_else} (conditional jump), in which case either the
2435 second or the third operand must be @code{(pc)} (for the case which
2436 does not jump) and the other of the two must be a @code{label_ref}
2437 (for the case which does jump). @var{x} may also be a @code{mem} or
2438 @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
2439 @code{mem}; these unusual patterns are used to represent jumps through
2442 If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of
2443 @var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
2444 valid for the mode of @var{lval}.
2448 @var{lval} is customarily accessed with the @code{SET_DEST} macro and
2449 @var{x} with the @code{SET_SRC} macro.
2453 As the sole expression in a pattern, represents a return from the
2454 current function, on machines where this can be done with one
2455 instruction, such as VAXen. On machines where a multi-instruction
2456 ``epilogue'' must be executed in order to return from the function,
2457 returning is done by jumping to a label which precedes the epilogue, and
2458 the @code{return} expression code is never used.
2460 Inside an @code{if_then_else} expression, represents the value to be
2461 placed in @code{pc} to return to the caller.
2463 Note that an insn pattern of @code{(return)} is logically equivalent to
2464 @code{(set (pc) (return))}, but the latter form is never used.
2467 @item (call @var{function} @var{nargs})
2468 Represents a function call. @var{function} is a @code{mem} expression
2469 whose address is the address of the function to be called.
2470 @var{nargs} is an expression which can be used for two purposes: on
2471 some machines it represents the number of bytes of stack argument; on
2472 others, it represents the number of argument registers.
2474 Each machine has a standard machine mode which @var{function} must
2475 have. The machine description defines macro @code{FUNCTION_MODE} to
2476 expand into the requisite mode name. The purpose of this mode is to
2477 specify what kind of addressing is allowed, on machines where the
2478 allowed kinds of addressing depend on the machine mode being
2482 @item (clobber @var{x})
2483 Represents the storing or possible storing of an unpredictable,
2484 undescribed value into @var{x}, which must be a @code{reg},
2485 @code{scratch}, @code{parallel} or @code{mem} expression.
2487 One place this is used is in string instructions that store standard
2488 values into particular hard registers. It may not be worth the
2489 trouble to describe the values that are stored, but it is essential to
2490 inform the compiler that the registers will be altered, lest it
2491 attempt to keep data in them across the string instruction.
2493 If @var{x} is @code{(mem:BLK (const_int 0))} or
2494 @code{(mem:BLK (scratch))}, it means that all memory
2495 locations must be presumed clobbered. If @var{x} is a @code{parallel},
2496 it has the same meaning as a @code{parallel} in a @code{set} expression.
2498 Note that the machine description classifies certain hard registers as
2499 ``call-clobbered''. All function call instructions are assumed by
2500 default to clobber these registers, so there is no need to use
2501 @code{clobber} expressions to indicate this fact. Also, each function
2502 call is assumed to have the potential to alter any memory location,
2503 unless the function is declared @code{const}.
2505 If the last group of expressions in a @code{parallel} are each a
2506 @code{clobber} expression whose arguments are @code{reg} or
2507 @code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
2508 phase can add the appropriate @code{clobber} expressions to an insn it
2509 has constructed when doing so will cause a pattern to be matched.
2511 This feature can be used, for example, on a machine that whose multiply
2512 and add instructions don't use an MQ register but which has an
2513 add-accumulate instruction that does clobber the MQ register. Similarly,
2514 a combined instruction might require a temporary register while the
2515 constituent instructions might not.
2517 When a @code{clobber} expression for a register appears inside a
2518 @code{parallel} with other side effects, the register allocator
2519 guarantees that the register is unoccupied both before and after that
2520 insn. However, the reload phase may allocate a register used for one of
2521 the inputs unless the @samp{&} constraint is specified for the selected
2522 alternative (@pxref{Modifiers}). You can clobber either a specific hard
2523 register, a pseudo register, or a @code{scratch} expression; in the
2524 latter two cases, GCC will allocate a hard register that is available
2525 there for use as a temporary.
2527 For instructions that require a temporary register, you should use
2528 @code{scratch} instead of a pseudo-register because this will allow the
2529 combiner phase to add the @code{clobber} when required. You do this by
2530 coding (@code{clobber} (@code{match_scratch} @dots{})). If you do
2531 clobber a pseudo register, use one which appears nowhere else---generate
2532 a new one each time. Otherwise, you may confuse CSE@.
2534 There is one other known use for clobbering a pseudo register in a
2535 @code{parallel}: when one of the input operands of the insn is also
2536 clobbered by the insn. In this case, using the same pseudo register in
2537 the clobber and elsewhere in the insn produces the expected results.
2541 Represents the use of the value of @var{x}. It indicates that the
2542 value in @var{x} at this point in the program is needed, even though
2543 it may not be apparent why this is so. Therefore, the compiler will
2544 not attempt to delete previous instructions whose only effect is to
2545 store a value in @var{x}. @var{x} must be a @code{reg} expression.
2547 In some situations, it may be tempting to add a @code{use} of a
2548 register in a @code{parallel} to describe a situation where the value
2549 of a special register will modify the behavior of the instruction.
2550 An hypothetical example might be a pattern for an addition that can
2551 either wrap around or use saturating addition depending on the value
2552 of a special control register:
2555 (parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
2562 This will not work, several of the optimizers only look at expressions
2563 locally; it is very likely that if you have multiple insns with
2564 identical inputs to the @code{unspec}, they will be optimized away even
2565 if register 1 changes in between.
2567 This means that @code{use} can @emph{only} be used to describe
2568 that the register is live. You should think twice before adding
2569 @code{use} statements, more often you will want to use @code{unspec}
2570 instead. The @code{use} RTX is most commonly useful to describe that
2571 a fixed register is implicitly used in an insn. It is also safe to use
2572 in patterns where the compiler knows for other reasons that the result
2573 of the whole pattern is variable, such as @samp{movmem@var{m}} or
2574 @samp{call} patterns.
2576 During the reload phase, an insn that has a @code{use} as pattern
2577 can carry a reg_equal note. These @code{use} insns will be deleted
2578 before the reload phase exits.
2580 During the delayed branch scheduling phase, @var{x} may be an insn.
2581 This indicates that @var{x} previously was located at this place in the
2582 code and its data dependencies need to be taken into account. These
2583 @code{use} insns will be deleted before the delayed branch scheduling
2587 @item (parallel [@var{x0} @var{x1} @dots{}])
2588 Represents several side effects performed in parallel. The square
2589 brackets stand for a vector; the operand of @code{parallel} is a
2590 vector of expressions. @var{x0}, @var{x1} and so on are individual
2591 side effect expressions---expressions of code @code{set}, @code{call},
2592 @code{return}, @code{clobber} or @code{use}.
2594 ``In parallel'' means that first all the values used in the individual
2595 side-effects are computed, and second all the actual side-effects are
2596 performed. For example,
2599 (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
2600 (set (mem:SI (reg:SI 1)) (reg:SI 1))])
2604 says unambiguously that the values of hard register 1 and the memory
2605 location addressed by it are interchanged. In both places where
2606 @code{(reg:SI 1)} appears as a memory address it refers to the value
2607 in register 1 @emph{before} the execution of the insn.
2609 It follows that it is @emph{incorrect} to use @code{parallel} and
2610 expect the result of one @code{set} to be available for the next one.
2611 For example, people sometimes attempt to represent a jump-if-zero
2612 instruction this way:
2615 (parallel [(set (cc0) (reg:SI 34))
2616 (set (pc) (if_then_else
2617 (eq (cc0) (const_int 0))
2623 But this is incorrect, because it says that the jump condition depends
2624 on the condition code value @emph{before} this instruction, not on the
2625 new value that is set by this instruction.
2627 @cindex peephole optimization, RTL representation
2628 Peephole optimization, which takes place together with final assembly
2629 code output, can produce insns whose patterns consist of a @code{parallel}
2630 whose elements are the operands needed to output the resulting
2631 assembler code---often @code{reg}, @code{mem} or constant expressions.
2632 This would not be well-formed RTL at any other stage in compilation,
2633 but it is ok then because no further optimization remains to be done.
2634 However, the definition of the macro @code{NOTICE_UPDATE_CC}, if
2635 any, must deal with such insns if you define any peephole optimizations.
2638 @item (cond_exec [@var{cond} @var{expr}])
2639 Represents a conditionally executed expression. The @var{expr} is
2640 executed only if the @var{cond} is nonzero. The @var{cond} expression
2641 must not have side-effects, but the @var{expr} may very well have
2645 @item (sequence [@var{insns} @dots{}])
2646 Represents a sequence of insns. Each of the @var{insns} that appears
2647 in the vector is suitable for appearing in the chain of insns, so it
2648 must be an @code{insn}, @code{jump_insn}, @code{call_insn},
2649 @code{code_label}, @code{barrier} or @code{note}.
2651 A @code{sequence} RTX is never placed in an actual insn during RTL
2652 generation. It represents the sequence of insns that result from a
2653 @code{define_expand} @emph{before} those insns are passed to
2654 @code{emit_insn} to insert them in the chain of insns. When actually
2655 inserted, the individual sub-insns are separated out and the
2656 @code{sequence} is forgotten.
2658 After delay-slot scheduling is completed, an insn and all the insns that
2659 reside in its delay slots are grouped together into a @code{sequence}.
2660 The insn requiring the delay slot is the first insn in the vector;
2661 subsequent insns are to be placed in the delay slot.
2663 @code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
2664 indicate that a branch insn should be used that will conditionally annul
2665 the effect of the insns in the delay slots. In such a case,
2666 @code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
2667 the branch and should be executed only if the branch is taken; otherwise
2668 the insn should be executed only if the branch is not taken.
2672 These expression codes appear in place of a side effect, as the body of
2673 an insn, though strictly speaking they do not always describe side
2678 @item (asm_input @var{s})
2679 Represents literal assembler code as described by the string @var{s}.
2682 @findex unspec_volatile
2683 @item (unspec [@var{operands} @dots{}] @var{index})
2684 @itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
2685 Represents a machine-specific operation on @var{operands}. @var{index}
2686 selects between multiple machine-specific operations.
2687 @code{unspec_volatile} is used for volatile operations and operations
2688 that may trap; @code{unspec} is used for other operations.
2690 These codes may appear inside a @code{pattern} of an
2691 insn, inside a @code{parallel}, or inside an expression.
2694 @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
2695 Represents a table of jump addresses. The vector elements @var{lr0},
2696 etc., are @code{label_ref} expressions. The mode @var{m} specifies
2697 how much space is given to each address; normally @var{m} would be
2700 @findex addr_diff_vec
2701 @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags})
2702 Represents a table of jump addresses expressed as offsets from
2703 @var{base}. The vector elements @var{lr0}, etc., are @code{label_ref}
2704 expressions and so is @var{base}. The mode @var{m} specifies how much
2705 space is given to each address-difference. @var{min} and @var{max}
2706 are set up by branch shortening and hold a label with a minimum and a
2707 maximum address, respectively. @var{flags} indicates the relative
2708 position of @var{base}, @var{min} and @var{max} to the containing insn
2709 and of @var{min} and @var{max} to @var{base}. See rtl.def for details.
2712 @item (prefetch:@var{m} @var{addr} @var{rw} @var{locality})
2713 Represents prefetch of memory at address @var{addr}.
2714 Operand @var{rw} is 1 if the prefetch is for data to be written, 0 otherwise;
2715 targets that do not support write prefetches should treat this as a normal
2717 Operand @var{locality} specifies the amount of temporal locality; 0 if there
2718 is none or 1, 2, or 3 for increasing levels of temporal locality;
2719 targets that do not support locality hints should ignore this.
2721 This insn is used to minimize cache-miss latency by moving data into a
2722 cache before it is accessed. It should use only non-faulting data prefetch
2727 @section Embedded Side-Effects on Addresses
2728 @cindex RTL preincrement
2729 @cindex RTL postincrement
2730 @cindex RTL predecrement
2731 @cindex RTL postdecrement
2733 Six special side-effect expression codes appear as memory addresses.
2737 @item (pre_dec:@var{m} @var{x})
2738 Represents the side effect of decrementing @var{x} by a standard
2739 amount and represents also the value that @var{x} has after being
2740 decremented. @var{x} must be a @code{reg} or @code{mem}, but most
2741 machines allow only a @code{reg}. @var{m} must be the machine mode
2742 for pointers on the machine in use. The amount @var{x} is decremented
2743 by is the length in bytes of the machine mode of the containing memory
2744 reference of which this expression serves as the address. Here is an
2748 (mem:DF (pre_dec:SI (reg:SI 39)))
2752 This says to decrement pseudo register 39 by the length of a @code{DFmode}
2753 value and use the result to address a @code{DFmode} value.
2756 @item (pre_inc:@var{m} @var{x})
2757 Similar, but specifies incrementing @var{x} instead of decrementing it.
2760 @item (post_dec:@var{m} @var{x})
2761 Represents the same side effect as @code{pre_dec} but a different
2762 value. The value represented here is the value @var{x} has @i{before}
2766 @item (post_inc:@var{m} @var{x})
2767 Similar, but specifies incrementing @var{x} instead of decrementing it.
2770 @item (post_modify:@var{m} @var{x} @var{y})
2772 Represents the side effect of setting @var{x} to @var{y} and
2773 represents @var{x} before @var{x} is modified. @var{x} must be a
2774 @code{reg} or @code{mem}, but most machines allow only a @code{reg}.
2775 @var{m} must be the machine mode for pointers on the machine in use.
2777 The expression @var{y} must be one of three forms:
2779 @code{(plus:@var{m} @var{x} @var{z})},
2780 @code{(minus:@var{m} @var{x} @var{z})}, or
2781 @code{(plus:@var{m} @var{x} @var{i})},
2783 where @var{z} is an index register and @var{i} is a constant.
2785 Here is an example of its use:
2788 (mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
2792 This says to modify pseudo register 42 by adding the contents of pseudo
2793 register 48 to it, after the use of what ever 42 points to.
2796 @item (pre_modify:@var{m} @var{x} @var{expr})
2797 Similar except side effects happen before the use.
2800 These embedded side effect expressions must be used with care. Instruction
2801 patterns may not use them. Until the @samp{flow} pass of the compiler,
2802 they may occur only to represent pushes onto the stack. The @samp{flow}
2803 pass finds cases where registers are incremented or decremented in one
2804 instruction and used as an address shortly before or after; these cases are
2805 then transformed to use pre- or post-increment or -decrement.
2807 If a register used as the operand of these expressions is used in
2808 another address in an insn, the original value of the register is used.
2809 Uses of the register outside of an address are not permitted within the
2810 same insn as a use in an embedded side effect expression because such
2811 insns behave differently on different machines and hence must be treated
2812 as ambiguous and disallowed.
2814 An instruction that can be represented with an embedded side effect
2815 could also be represented using @code{parallel} containing an additional
2816 @code{set} to describe how the address register is altered. This is not
2817 done because machines that allow these operations at all typically
2818 allow them wherever a memory address is called for. Describing them as
2819 additional parallel stores would require doubling the number of entries
2820 in the machine description.
2823 @section Assembler Instructions as Expressions
2824 @cindex assembler instructions in RTL
2826 @cindex @code{asm_operands}, usage
2827 The RTX code @code{asm_operands} represents a value produced by a
2828 user-specified assembler instruction. It is used to represent
2829 an @code{asm} statement with arguments. An @code{asm} statement with
2830 a single output operand, like this:
2833 asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
2837 is represented using a single @code{asm_operands} RTX which represents
2838 the value that is stored in @code{outputvar}:
2841 (set @var{rtx-for-outputvar}
2842 (asm_operands "foo %1,%2,%0" "a" 0
2843 [@var{rtx-for-addition-result} @var{rtx-for-*z}]
2844 [(asm_input:@var{m1} "g")
2845 (asm_input:@var{m2} "di")]))
2849 Here the operands of the @code{asm_operands} RTX are the assembler
2850 template string, the output-operand's constraint, the index-number of the
2851 output operand among the output operands specified, a vector of input
2852 operand RTX's, and a vector of input-operand modes and constraints. The
2853 mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
2856 When an @code{asm} statement has multiple output values, its insn has
2857 several such @code{set} RTX's inside of a @code{parallel}. Each @code{set}
2858 contains a @code{asm_operands}; all of these share the same assembler
2859 template and vectors, but each contains the constraint for the respective
2860 output operand. They are also distinguished by the output-operand index
2861 number, which is 0, 1, @dots{} for successive output operands.
2867 The RTL representation of the code for a function is a doubly-linked
2868 chain of objects called @dfn{insns}. Insns are expressions with
2869 special codes that are used for no other purpose. Some insns are
2870 actual instructions; others represent dispatch tables for @code{switch}
2871 statements; others represent labels to jump to or various sorts of
2872 declarative information.
2874 In addition to its own specific data, each insn must have a unique
2875 id-number that distinguishes it from all other insns in the current
2876 function (after delayed branch scheduling, copies of an insn with the
2877 same id-number may be present in multiple places in a function, but
2878 these copies will always be identical and will only appear inside a
2879 @code{sequence}), and chain pointers to the preceding and following
2880 insns. These three fields occupy the same position in every insn,
2881 independent of the expression code of the insn. They could be accessed
2882 with @code{XEXP} and @code{XINT}, but instead three special macros are
2887 @item INSN_UID (@var{i})
2888 Accesses the unique id of insn @var{i}.
2891 @item PREV_INSN (@var{i})
2892 Accesses the chain pointer to the insn preceding @var{i}.
2893 If @var{i} is the first insn, this is a null pointer.
2896 @item NEXT_INSN (@var{i})
2897 Accesses the chain pointer to the insn following @var{i}.
2898 If @var{i} is the last insn, this is a null pointer.
2902 @findex get_last_insn
2903 The first insn in the chain is obtained by calling @code{get_insns}; the
2904 last insn is the result of calling @code{get_last_insn}. Within the
2905 chain delimited by these insns, the @code{NEXT_INSN} and
2906 @code{PREV_INSN} pointers must always correspond: if @var{insn} is not
2910 NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
2914 is always true and if @var{insn} is not the last insn,
2917 PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
2923 After delay slot scheduling, some of the insns in the chain might be
2924 @code{sequence} expressions, which contain a vector of insns. The value
2925 of @code{NEXT_INSN} in all but the last of these insns is the next insn
2926 in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
2927 is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
2928 which it is contained. Similar rules apply for @code{PREV_INSN}.
2930 This means that the above invariants are not necessarily true for insns
2931 inside @code{sequence} expressions. Specifically, if @var{insn} is the
2932 first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
2933 is the insn containing the @code{sequence} expression, as is the value
2934 of @code{PREV_INSN (NEXT_INSN (@var{insn}))} if @var{insn} is the last
2935 insn in the @code{sequence} expression. You can use these expressions
2936 to find the containing @code{sequence} expression.
2938 Every insn has one of the following six expression codes:
2943 The expression code @code{insn} is used for instructions that do not jump
2944 and do not do function calls. @code{sequence} expressions are always
2945 contained in insns with code @code{insn} even if one of those insns
2946 should jump or do function calls.
2948 Insns with code @code{insn} have four additional fields beyond the three
2949 mandatory ones listed above. These four are described in a table below.
2953 The expression code @code{jump_insn} is used for instructions that may
2954 jump (or, more generally, may contain @code{label_ref} expressions). If
2955 there is an instruction to return from the current function, it is
2956 recorded as a @code{jump_insn}.
2959 @code{jump_insn} insns have the same extra fields as @code{insn} insns,
2960 accessed in the same way and in addition contain a field
2961 @code{JUMP_LABEL} which is defined once jump optimization has completed.
2963 For simple conditional and unconditional jumps, this field contains
2964 the @code{code_label} to which this insn will (possibly conditionally)
2965 branch. In a more complex jump, @code{JUMP_LABEL} records one of the
2966 labels that the insn refers to; the only way to find the others is to
2967 scan the entire body of the insn. In an @code{addr_vec},
2968 @code{JUMP_LABEL} is @code{NULL_RTX}.
2970 Return insns count as jumps, but since they do not refer to any
2971 labels, their @code{JUMP_LABEL} is @code{NULL_RTX}.
2975 The expression code @code{call_insn} is used for instructions that may do
2976 function calls. It is important to distinguish these instructions because
2977 they imply that certain registers and memory locations may be altered
2980 @findex CALL_INSN_FUNCTION_USAGE
2981 @code{call_insn} insns have the same extra fields as @code{insn} insns,
2982 accessed in the same way and in addition contain a field
2983 @code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of
2984 @code{expr_list} expressions) containing @code{use} and @code{clobber}
2985 expressions that denote hard registers and @code{MEM}s used or
2986 clobbered by the called function.
2988 A @code{MEM} generally points to a stack slots in which arguments passed
2989 to the libcall by reference (@pxref{Register Arguments,
2990 TARGET_PASS_BY_REFERENCE}) are stored. If the argument is
2991 caller-copied (@pxref{Register Arguments, TARGET_CALLEE_COPIES}),
2992 the stack slot will be mentioned in @code{CLOBBER} and @code{USE}
2993 entries; if it's callee-copied, only a @code{USE} will appear, and the
2994 @code{MEM} may point to addresses that are not stack slots. These
2995 @code{MEM}s are used only in libcalls, because, unlike regular function
2996 calls, @code{CONST_CALL}s (which libcalls generally are, @pxref{Flags,
2997 CONST_CALL_P}) aren't assumed to read and write all memory, so flow
2998 would consider the stores dead and remove them. Note that, since a
2999 libcall must never return values in memory (@pxref{Aggregate Return,
3000 RETURN_IN_MEMORY}), there will never be a @code{CLOBBER} for a memory
3001 address holding a return value.
3003 @code{CLOBBER}ed registers in this list augment registers specified in
3004 @code{CALL_USED_REGISTERS} (@pxref{Register Basics}).
3007 @findex CODE_LABEL_NUMBER
3009 A @code{code_label} insn represents a label that a jump insn can jump
3010 to. It contains two special fields of data in addition to the three
3011 standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
3012 number}, a number that identifies this label uniquely among all the
3013 labels in the compilation (not just in the current function).
3014 Ultimately, the label is represented in the assembler output as an
3015 assembler label, usually of the form @samp{L@var{n}} where @var{n} is
3018 When a @code{code_label} appears in an RTL expression, it normally
3019 appears within a @code{label_ref} which represents the address of
3020 the label, as a number.
3022 Besides as a @code{code_label}, a label can also be represented as a
3023 @code{note} of type @code{NOTE_INSN_DELETED_LABEL}.
3026 The field @code{LABEL_NUSES} is only defined once the jump optimization
3027 phase is completed. It contains the number of times this label is
3028 referenced in the current function.
3031 @findex SET_LABEL_KIND
3032 @findex LABEL_ALT_ENTRY_P
3033 @cindex alternate entry points
3034 The field @code{LABEL_KIND} differentiates four different types of
3035 labels: @code{LABEL_NORMAL}, @code{LABEL_STATIC_ENTRY},
3036 @code{LABEL_GLOBAL_ENTRY}, and @code{LABEL_WEAK_ENTRY}. The only labels
3037 that do not have type @code{LABEL_NORMAL} are @dfn{alternate entry
3038 points} to the current function. These may be static (visible only in
3039 the containing translation unit), global (exposed to all translation
3040 units), or weak (global, but can be overridden by another symbol with the
3043 Much of the compiler treats all four kinds of label identically. Some
3044 of it needs to know whether or not a label is an alternate entry point;
3045 for this purpose, the macro @code{LABEL_ALT_ENTRY_P} is provided. It is
3046 equivalent to testing whether @samp{LABEL_KIND (label) == LABEL_NORMAL}.
3047 The only place that cares about the distinction between static, global,
3048 and weak alternate entry points, besides the front-end code that creates
3049 them, is the function @code{output_alternate_entry_point}, in
3052 To set the kind of a label, use the @code{SET_LABEL_KIND} macro.
3056 Barriers are placed in the instruction stream when control cannot flow
3057 past them. They are placed after unconditional jump instructions to
3058 indicate that the jumps are unconditional and after calls to
3059 @code{volatile} functions, which do not return (e.g., @code{exit}).
3060 They contain no information beyond the three standard fields.
3063 @findex NOTE_LINE_NUMBER
3064 @findex NOTE_SOURCE_FILE
3066 @code{note} insns are used to represent additional debugging and
3067 declarative information. They contain two nonstandard fields, an
3068 integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
3069 string accessed with @code{NOTE_SOURCE_FILE}.
3071 If @code{NOTE_LINE_NUMBER} is positive, the note represents the
3072 position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
3073 that the line came from. These notes control generation of line
3074 number data in the assembler output.
3076 Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
3077 code with one of the following values (and @code{NOTE_SOURCE_FILE}
3078 must contain a null pointer):
3081 @findex NOTE_INSN_DELETED
3082 @item NOTE_INSN_DELETED
3083 Such a note is completely ignorable. Some passes of the compiler
3084 delete insns by altering them into notes of this kind.
3086 @findex NOTE_INSN_DELETED_LABEL
3087 @item NOTE_INSN_DELETED_LABEL
3088 This marks what used to be a @code{code_label}, but was not used for other
3089 purposes than taking its address and was transformed to mark that no
3092 @findex NOTE_INSN_BLOCK_BEG
3093 @findex NOTE_INSN_BLOCK_END
3094 @item NOTE_INSN_BLOCK_BEG
3095 @itemx NOTE_INSN_BLOCK_END
3096 These types of notes indicate the position of the beginning and end
3097 of a level of scoping of variable names. They control the output
3098 of debugging information.
3100 @findex NOTE_INSN_EH_REGION_BEG
3101 @findex NOTE_INSN_EH_REGION_END
3102 @item NOTE_INSN_EH_REGION_BEG
3103 @itemx NOTE_INSN_EH_REGION_END
3104 These types of notes indicate the position of the beginning and end of a
3105 level of scoping for exception handling. @code{NOTE_BLOCK_NUMBER}
3106 identifies which @code{CODE_LABEL} or @code{note} of type
3107 @code{NOTE_INSN_DELETED_LABEL} is associated with the given region.
3109 @findex NOTE_INSN_LOOP_BEG
3110 @findex NOTE_INSN_LOOP_END
3111 @item NOTE_INSN_LOOP_BEG
3112 @itemx NOTE_INSN_LOOP_END
3113 These types of notes indicate the position of the beginning and end
3114 of a @code{while} or @code{for} loop. They enable the loop optimizer
3115 to find loops quickly.
3117 @findex NOTE_INSN_LOOP_CONT
3118 @item NOTE_INSN_LOOP_CONT
3119 Appears at the place in a loop that @code{continue} statements jump to.
3121 @findex NOTE_INSN_LOOP_VTOP
3122 @item NOTE_INSN_LOOP_VTOP
3123 This note indicates the place in a loop where the exit test begins for
3124 those loops in which the exit test has been duplicated. This position
3125 becomes another virtual start of the loop when considering loop
3128 @findex NOTE_INSN_FUNCTION_BEG
3129 @item NOTE_INSN_FUNCTION_BEG
3130 Appears at the start of the function body, after the function
3133 @findex NOTE_INSN_FUNCTION_END
3134 @item NOTE_INSN_FUNCTION_END
3135 Appears near the end of the function body, just before the label that
3136 @code{return} statements jump to (on machine where a single instruction
3137 does not suffice for returning). This note may be deleted by jump
3142 These codes are printed symbolically when they appear in debugging dumps.
3145 @cindex @code{TImode}, in @code{insn}
3146 @cindex @code{HImode}, in @code{insn}
3147 @cindex @code{QImode}, in @code{insn}
3148 The machine mode of an insn is normally @code{VOIDmode}, but some
3149 phases use the mode for various purposes.
3151 The common subexpression elimination pass sets the mode of an insn to
3152 @code{QImode} when it is the first insn in a block that has already
3155 The second Haifa scheduling pass, for targets that can multiple issue,
3156 sets the mode of an insn to @code{TImode} when it is believed that the
3157 instruction begins an issue group. That is, when the instruction
3158 cannot issue simultaneously with the previous. This may be relied on
3159 by later passes, in particular machine-dependent reorg.
3161 Here is a table of the extra fields of @code{insn}, @code{jump_insn}
3162 and @code{call_insn} insns:
3166 @item PATTERN (@var{i})
3167 An expression for the side effect performed by this insn. This must be
3168 one of the following codes: @code{set}, @code{call}, @code{use},
3169 @code{clobber}, @code{return}, @code{asm_input}, @code{asm_output},
3170 @code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec},
3171 @code{unspec_volatile}, @code{parallel}, @code{cond_exec}, or @code{sequence}. If it is a @code{parallel},
3172 each element of the @code{parallel} must be one these codes, except that
3173 @code{parallel} expressions cannot be nested and @code{addr_vec} and
3174 @code{addr_diff_vec} are not permitted inside a @code{parallel} expression.
3177 @item INSN_CODE (@var{i})
3178 An integer that says which pattern in the machine description matches
3179 this insn, or @minus{}1 if the matching has not yet been attempted.
3181 Such matching is never attempted and this field remains @minus{}1 on an insn
3182 whose pattern consists of a single @code{use}, @code{clobber},
3183 @code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.
3185 @findex asm_noperands
3186 Matching is also never attempted on insns that result from an @code{asm}
3187 statement. These contain at least one @code{asm_operands} expression.
3188 The function @code{asm_noperands} returns a non-negative value for
3191 In the debugging output, this field is printed as a number followed by
3192 a symbolic representation that locates the pattern in the @file{md}
3193 file as some small positive or negative offset from a named pattern.
3196 @item LOG_LINKS (@var{i})
3197 A list (chain of @code{insn_list} expressions) giving information about
3198 dependencies between instructions within a basic block. Neither a jump
3199 nor a label may come between the related insns.
3202 @item REG_NOTES (@var{i})
3203 A list (chain of @code{expr_list} and @code{insn_list} expressions)
3204 giving miscellaneous information about the insn. It is often
3205 information pertaining to the registers used in this insn.
3208 The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
3209 expressions. Each of these has two operands: the first is an insn,
3210 and the second is another @code{insn_list} expression (the next one in
3211 the chain). The last @code{insn_list} in the chain has a null pointer
3212 as second operand. The significant thing about the chain is which
3213 insns appear in it (as first operands of @code{insn_list}
3214 expressions). Their order is not significant.
3216 This list is originally set up by the flow analysis pass; it is a null
3217 pointer until then. Flow only adds links for those data dependencies
3218 which can be used for instruction combination. For each insn, the flow
3219 analysis pass adds a link to insns which store into registers values
3220 that are used for the first time in this insn. The instruction
3221 scheduling pass adds extra links so that every dependence will be
3222 represented. Links represent data dependencies, antidependencies and
3223 output dependencies; the machine mode of the link distinguishes these
3224 three types: antidependencies have mode @code{REG_DEP_ANTI}, output
3225 dependencies have mode @code{REG_DEP_OUTPUT}, and data dependencies have
3226 mode @code{VOIDmode}.
3228 The @code{REG_NOTES} field of an insn is a chain similar to the
3229 @code{LOG_LINKS} field but it includes @code{expr_list} expressions in
3230 addition to @code{insn_list} expressions. There are several kinds of
3231 register notes, which are distinguished by the machine mode, which in a
3232 register note is really understood as being an @code{enum reg_note}.
3233 The first operand @var{op} of the note is data whose meaning depends on
3236 @findex REG_NOTE_KIND
3237 @findex PUT_REG_NOTE_KIND
3238 The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of
3239 register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND
3240 (@var{x}, @var{newkind})} sets the register note type of @var{x} to be
3243 Register notes are of three classes: They may say something about an
3244 input to an insn, they may say something about an output of an insn, or
3245 they may create a linkage between two insns. There are also a set
3246 of values that are only used in @code{LOG_LINKS}.
3248 These register notes annotate inputs to an insn:
3253 The value in @var{op} dies in this insn; that is to say, altering the
3254 value immediately after this insn would not affect the future behavior
3257 It does not follow that the register @var{op} has no useful value after
3258 this insn since @var{op} is not necessarily modified by this insn.
3259 Rather, no subsequent instruction uses the contents of @var{op}.
3263 The register @var{op} being set by this insn will not be used in a
3264 subsequent insn. This differs from a @code{REG_DEAD} note, which
3265 indicates that the value in an input will not be used subsequently.
3266 These two notes are independent; both may be present for the same
3271 The register @var{op} is incremented (or decremented; at this level
3272 there is no distinction) by an embedded side effect inside this insn.
3273 This means it appears in a @code{post_inc}, @code{pre_inc},
3274 @code{post_dec} or @code{pre_dec} expression.
3278 The register @var{op} is known to have a nonnegative value when this
3279 insn is reached. This is used so that decrement and branch until zero
3280 instructions, such as the m68k dbra, can be matched.
3282 The @code{REG_NONNEG} note is added to insns only if the machine
3283 description has a @samp{decrement_and_branch_until_zero} pattern.
3285 @findex REG_NO_CONFLICT
3286 @item REG_NO_CONFLICT
3287 This insn does not cause a conflict between @var{op} and the item
3288 being set by this insn even though it might appear that it does.
3289 In other words, if the destination register and @var{op} could
3290 otherwise be assigned the same register, this insn does not
3291 prevent that assignment.
3293 Insns with this note are usually part of a block that begins with a
3294 @code{clobber} insn specifying a multi-word pseudo register (which will
3295 be the output of the block), a group of insns that each set one word of
3296 the value and have the @code{REG_NO_CONFLICT} note attached, and a final
3297 insn that copies the output to itself with an attached @code{REG_EQUAL}
3298 note giving the expression being computed. This block is encapsulated
3299 with @code{REG_LIBCALL} and @code{REG_RETVAL} notes on the first and
3300 last insns, respectively.
3304 This insn uses @var{op}, a @code{code_label} or a @code{note} of type
3305 @code{NOTE_INSN_DELETED_LABEL}, but is not a
3306 @code{jump_insn}, or it is a @code{jump_insn} that required the label to
3307 be held in a register. The presence of this note allows jump
3308 optimization to be aware that @var{op} is, in fact, being used, and flow
3309 optimization to build an accurate flow graph.
3311 @findex REG_CROSSING_JUMP
3312 @item REG_CROSSING_JUMP
3313 This insn is an branching instruction (either an unconditional jump or
3314 an indirect jump) which crosses between hot and cold sections, which
3315 could potentially be very far apart in the executable. The presence
3316 of this note indicates to other optimizations that this this branching
3317 instruction should not be ``collapsed'' into a simpler branching
3318 construct. It is used when the optimization to partition basic blocks
3319 into hot and cold sections is turned on.
3323 Appears attached to each @code{CALL_INSN} to @code{setjmp} or a
3327 The following notes describe attributes of outputs of an insn:
3334 This note is only valid on an insn that sets only one register and
3335 indicates that that register will be equal to @var{op} at run time; the
3336 scope of this equivalence differs between the two types of notes. The
3337 value which the insn explicitly copies into the register may look
3338 different from @var{op}, but they will be equal at run time. If the
3339 output of the single @code{set} is a @code{strict_low_part} expression,
3340 the note refers to the register that is contained in @code{SUBREG_REG}
3341 of the @code{subreg} expression.
3343 For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout
3344 the entire function, and could validly be replaced in all its
3345 occurrences by @var{op}. (``Validly'' here refers to the data flow of
3346 the program; simple replacement may make some insns invalid.) For
3347 example, when a constant is loaded into a register that is never
3348 assigned any other value, this kind of note is used.
3350 When a parameter is copied into a pseudo-register at entry to a function,
3351 a note of this kind records that the register is equivalent to the stack
3352 slot where the parameter was passed. Although in this case the register
3353 may be set by other insns, it is still valid to replace the register
3354 by the stack slot throughout the function.
3356 A @code{REG_EQUIV} note is also used on an instruction which copies a
3357 register parameter into a pseudo-register at entry to a function, if
3358 there is a stack slot where that parameter could be stored. Although
3359 other insns may set the pseudo-register, it is valid for the compiler to
3360 replace the pseudo-register by stack slot throughout the function,
3361 provided the compiler ensures that the stack slot is properly
3362 initialized by making the replacement in the initial copy instruction as
3363 well. This is used on machines for which the calling convention
3364 allocates stack space for register parameters. See
3365 @code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}.
3367 In the case of @code{REG_EQUAL}, the register that is set by this insn
3368 will be equal to @var{op} at run time at the end of this insn but not
3369 necessarily elsewhere in the function. In this case, @var{op}
3370 is typically an arithmetic expression. For example, when a sequence of
3371 insns such as a library call is used to perform an arithmetic operation,
3372 this kind of note is attached to the insn that produces or copies the
3375 These two notes are used in different ways by the compiler passes.
3376 @code{REG_EQUAL} is used by passes prior to register allocation (such as
3377 common subexpression elimination and loop optimization) to tell them how
3378 to think of that value. @code{REG_EQUIV} notes are used by register
3379 allocation to indicate that there is an available substitute expression
3380 (either a constant or a @code{mem} expression for the location of a
3381 parameter on the stack) that may be used in place of a register if
3382 insufficient registers are available.
3384 Except for stack homes for parameters, which are indicated by a
3385 @code{REG_EQUIV} note and are not useful to the early optimization
3386 passes and pseudo registers that are equivalent to a memory location
3387 throughout their entire life, which is not detected until later in
3388 the compilation, all equivalences are initially indicated by an attached
3389 @code{REG_EQUAL} note. In the early stages of register allocation, a
3390 @code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if
3391 @var{op} is a constant and the insn represents the only set of its
3392 destination register.
3394 Thus, compiler passes prior to register allocation need only check for
3395 @code{REG_EQUAL} notes and passes subsequent to register allocation
3396 need only check for @code{REG_EQUIV} notes.
3399 These notes describe linkages between insns. They occur in pairs: one
3400 insn has one of a pair of notes that points to a second insn, which has
3401 the inverse note pointing back to the first insn.
3406 This insn copies the value of a multi-insn sequence (for example, a
3407 library call), and @var{op} is the first insn of the sequence (for a
3408 library call, the first insn that was generated to set up the arguments
3409 for the library call).
3411 Loop optimization uses this note to treat such a sequence as a single
3412 operation for code motion purposes and flow analysis uses this note to
3413 delete such sequences whose results are dead.
3415 A @code{REG_EQUAL} note will also usually be attached to this insn to
3416 provide the expression being computed by the sequence.
3418 These notes will be deleted after reload, since they are no longer
3423 This is the inverse of @code{REG_RETVAL}: it is placed on the first
3424 insn of a multi-insn sequence, and it points to the last one.
3426 These notes are deleted after reload, since they are no longer useful or
3429 @findex REG_CC_SETTER
3433 On machines that use @code{cc0}, the insns which set and use @code{cc0}
3434 set and use @code{cc0} are adjacent. However, when branch delay slot
3435 filling is done, this may no longer be true. In this case a
3436 @code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to
3437 point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will
3438 be placed on the insn using @code{cc0} to point to the insn setting
3442 These values are only used in the @code{LOG_LINKS} field, and indicate
3443 the type of dependency that each link represents. Links which indicate
3444 a data dependence (a read after write dependence) do not use any code,
3445 they simply have mode @code{VOIDmode}, and are printed without any
3449 @findex REG_DEP_ANTI
3451 This indicates an anti dependence (a write after read dependence).
3453 @findex REG_DEP_OUTPUT
3454 @item REG_DEP_OUTPUT
3455 This indicates an output dependence (a write after write dependence).
3458 These notes describe information gathered from gcov profile data. They
3459 are stored in the @code{REG_NOTES} field of an insn as an
3465 This is used to specify the ratio of branches to non-branches of a
3466 branch insn according to the profile data. The value is stored as a
3467 value between 0 and REG_BR_PROB_BASE; larger values indicate a higher
3468 probability that the branch will be taken.
3472 These notes are found in JUMP insns after delayed branch scheduling
3473 has taken place. They indicate both the direction and the likelihood
3474 of the JUMP@. The format is a bitmask of ATTR_FLAG_* values.
3476 @findex REG_FRAME_RELATED_EXPR
3477 @item REG_FRAME_RELATED_EXPR
3478 This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression
3479 is used in place of the actual insn pattern. This is done in cases where
3480 the pattern is either complex or misleading.
3483 For convenience, the machine mode in an @code{insn_list} or
3484 @code{expr_list} is printed using these symbolic codes in debugging dumps.
3488 The only difference between the expression codes @code{insn_list} and
3489 @code{expr_list} is that the first operand of an @code{insn_list} is
3490 assumed to be an insn and is printed in debugging dumps as the insn's
3491 unique id; the first operand of an @code{expr_list} is printed in the
3492 ordinary way as an expression.
3495 @section RTL Representation of Function-Call Insns
3496 @cindex calling functions in RTL
3497 @cindex RTL function-call insns
3498 @cindex function-call insns
3500 Insns that call subroutines have the RTL expression code @code{call_insn}.
3501 These insns must satisfy special rules, and their bodies must use a special
3502 RTL expression code, @code{call}.
3504 @cindex @code{call} usage
3505 A @code{call} expression has two operands, as follows:
3508 (call (mem:@var{fm} @var{addr}) @var{nbytes})
3512 Here @var{nbytes} is an operand that represents the number of bytes of
3513 argument data being passed to the subroutine, @var{fm} is a machine mode
3514 (which must equal as the definition of the @code{FUNCTION_MODE} macro in
3515 the machine description) and @var{addr} represents the address of the
3518 For a subroutine that returns no value, the @code{call} expression as
3519 shown above is the entire body of the insn, except that the insn might
3520 also contain @code{use} or @code{clobber} expressions.
3522 @cindex @code{BLKmode}, and function return values
3523 For a subroutine that returns a value whose mode is not @code{BLKmode},
3524 the value is returned in a hard register. If this register's number is
3525 @var{r}, then the body of the call insn looks like this:
3528 (set (reg:@var{m} @var{r})
3529 (call (mem:@var{fm} @var{addr}) @var{nbytes}))
3533 This RTL expression makes it clear (to the optimizer passes) that the
3534 appropriate register receives a useful value in this insn.
3536 When a subroutine returns a @code{BLKmode} value, it is handled by
3537 passing to the subroutine the address of a place to store the value.
3538 So the call insn itself does not ``return'' any value, and it has the
3539 same RTL form as a call that returns nothing.
3541 On some machines, the call instruction itself clobbers some register,
3542 for example to contain the return address. @code{call_insn} insns
3543 on these machines should have a body which is a @code{parallel}
3544 that contains both the @code{call} expression and @code{clobber}
3545 expressions that indicate which registers are destroyed. Similarly,
3546 if the call instruction requires some register other than the stack
3547 pointer that is not explicitly mentioned in its RTL, a @code{use}
3548 subexpression should mention that register.
3550 Functions that are called are assumed to modify all registers listed in
3551 the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register
3552 Basics}) and, with the exception of @code{const} functions and library
3553 calls, to modify all of memory.
3555 Insns containing just @code{use} expressions directly precede the
3556 @code{call_insn} insn to indicate which registers contain inputs to the
3557 function. Similarly, if registers other than those in
3558 @code{CALL_USED_REGISTERS} are clobbered by the called function, insns
3559 containing a single @code{clobber} follow immediately after the call to
3560 indicate which registers.
3563 @section Structure Sharing Assumptions
3564 @cindex sharing of RTL components
3565 @cindex RTL structure sharing assumptions
3567 The compiler assumes that certain kinds of RTL expressions are unique;
3568 there do not exist two distinct objects representing the same value.
3569 In other cases, it makes an opposite assumption: that no RTL expression
3570 object of a certain kind appears in more than one place in the
3571 containing structure.
3573 These assumptions refer to a single function; except for the RTL
3574 objects that describe global variables and external functions,
3575 and a few standard objects such as small integer constants,
3576 no RTL objects are common to two functions.
3579 @cindex @code{reg}, RTL sharing
3581 Each pseudo-register has only a single @code{reg} object to represent it,
3582 and therefore only a single machine mode.
3584 @cindex symbolic label
3585 @cindex @code{symbol_ref}, RTL sharing
3587 For any symbolic label, there is only one @code{symbol_ref} object
3590 @cindex @code{const_int}, RTL sharing
3592 All @code{const_int} expressions with equal values are shared.
3594 @cindex @code{pc}, RTL sharing
3596 There is only one @code{pc} expression.
3598 @cindex @code{cc0}, RTL sharing
3600 There is only one @code{cc0} expression.
3602 @cindex @code{const_double}, RTL sharing
3604 There is only one @code{const_double} expression with value 0 for
3605 each floating point mode. Likewise for values 1 and 2.
3607 @cindex @code{const_vector}, RTL sharing
3609 There is only one @code{const_vector} expression with value 0 for
3610 each vector mode, be it an integer or a double constant vector.
3612 @cindex @code{label_ref}, RTL sharing
3613 @cindex @code{scratch}, RTL sharing
3615 No @code{label_ref} or @code{scratch} appears in more than one place in
3616 the RTL structure; in other words, it is safe to do a tree-walk of all
3617 the insns in the function and assume that each time a @code{label_ref}
3618 or @code{scratch} is seen it is distinct from all others that are seen.
3620 @cindex @code{mem}, RTL sharing
3622 Only one @code{mem} object is normally created for each static
3623 variable or stack slot, so these objects are frequently shared in all
3624 the places they appear. However, separate but equal objects for these
3625 variables are occasionally made.
3627 @cindex @code{asm_operands}, RTL sharing
3629 When a single @code{asm} statement has multiple output operands, a
3630 distinct @code{asm_operands} expression is made for each output operand.
3631 However, these all share the vector which contains the sequence of input
3632 operands. This sharing is used later on to test whether two
3633 @code{asm_operands} expressions come from the same statement, so all
3634 optimizations must carefully preserve the sharing if they copy the
3638 No RTL object appears in more than one place in the RTL structure
3639 except as described above. Many passes of the compiler rely on this
3640 by assuming that they can modify RTL objects in place without unwanted
3641 side-effects on other insns.
3643 @findex unshare_all_rtl
3645 During initial RTL generation, shared structure is freely introduced.
3646 After all the RTL for a function has been generated, all shared
3647 structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
3648 after which the above rules are guaranteed to be followed.
3650 @findex copy_rtx_if_shared
3652 During the combiner pass, shared structure within an insn can exist
3653 temporarily. However, the shared structure is copied before the
3654 combiner is finished with the insn. This is done by calling
3655 @code{copy_rtx_if_shared}, which is a subroutine of
3656 @code{unshare_all_rtl}.
3660 @section Reading RTL
3662 To read an RTL object from a file, call @code{read_rtx}. It takes one
3663 argument, a stdio stream, and returns a single RTL object. This routine
3664 is defined in @file{read-rtl.c}. It is not available in the compiler
3665 itself, only the various programs that generate the compiler back end
3666 from the machine description.
3668 People frequently have the idea of using RTL stored as text in a file as
3669 an interface between a language front end and the bulk of GCC@. This
3670 idea is not feasible.
3672 GCC was designed to use RTL internally only. Correct RTL for a given
3673 program is very dependent on the particular target machine. And the RTL
3674 does not contain all the information about the program.
3676 The proper way to interface GCC to a new language front end is with
3677 the ``tree'' data structure, described in the files @file{tree.h} and
3678 @file{tree.def}. The documentation for this structure (@pxref{Trees})