1 @c Copyright (C) 1988-2013 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
6 @chapter RTL Representation
7 @cindex RTL representation
8 @cindex representation of RTL
9 @cindex Register Transfer Language (RTL)
11 The last part of the compiler work is done on a low-level intermediate
12 representation called Register Transfer Language. In this language, the
13 instructions to be output are described, pretty much one by one, in an
14 algebraic form that describes what the instruction does.
16 RTL is inspired by Lisp lists. It has both an internal form, made up of
17 structures that point at other structures, and a textual form that is used
18 in the machine description and in printed debugging dumps. The textual
19 form uses nested parentheses to indicate the pointers in the internal form.
22 * RTL Objects:: Expressions vs vectors vs strings vs integers.
23 * RTL Classes:: Categories of RTL expression objects, and their structure.
24 * Accessors:: Macros to access expression operands or vector elts.
25 * Special Accessors:: Macros to access specific annotations on RTL.
26 * Flags:: Other flags in an RTL expression.
27 * Machine Modes:: Describing the size and format of a datum.
28 * Constants:: Expressions with constant values.
29 * Regs and Memory:: Expressions representing register contents or memory.
30 * Arithmetic:: Expressions representing arithmetic on other expressions.
31 * Comparisons:: Expressions representing comparison of expressions.
32 * Bit-Fields:: Expressions representing bit-fields in memory or reg.
33 * Vector Operations:: Expressions involving vector datatypes.
34 * Conversions:: Extending, truncating, floating or fixing.
35 * RTL Declarations:: Declaring volatility, constancy, etc.
36 * Side Effects:: Expressions for storing in registers, etc.
37 * Incdec:: Embedded side-effects for autoincrement addressing.
38 * Assembler:: Representing @code{asm} with operands.
39 * Debug Information:: Expressions representing debugging information.
40 * Insns:: Expression types for entire insns.
41 * Calls:: RTL representation of function call insns.
42 * Sharing:: Some expressions are unique; others *must* be copied.
43 * Reading RTL:: Reading textual RTL from a file.
47 @section RTL Object Types
48 @cindex RTL object types
53 @cindex RTL expression
55 RTL uses five kinds of objects: expressions, integers, wide integers,
56 strings and vectors. Expressions are the most important ones. An RTL
57 expression (``RTX'', for short) is a C structure, but it is usually
58 referred to with a pointer; a type that is given the typedef name
61 An integer is simply an @code{int}; their written form uses decimal
62 digits. A wide integer is an integral object whose type is
63 @code{HOST_WIDE_INT}; their written form uses decimal digits.
65 A string is a sequence of characters. In core it is represented as a
66 @code{char *} in usual C fashion, and it is written in C syntax as well.
67 However, strings in RTL may never be null. If you write an empty string in
68 a machine description, it is represented in core as a null pointer rather
69 than as a pointer to a null character. In certain contexts, these null
70 pointers instead of strings are valid. Within RTL code, strings are most
71 commonly found inside @code{symbol_ref} expressions, but they appear in
72 other contexts in the RTL expressions that make up machine descriptions.
74 In a machine description, strings are normally written with double
75 quotes, as you would in C@. However, strings in machine descriptions may
76 extend over many lines, which is invalid C, and adjacent string
77 constants are not concatenated as they are in C@. Any string constant
78 may be surrounded with a single set of parentheses. Sometimes this
79 makes the machine description easier to read.
81 There is also a special syntax for strings, which can be useful when C
82 code is embedded in a machine description. Wherever a string can
83 appear, it is also valid to write a C-style brace block. The entire
84 brace block, including the outermost pair of braces, is considered to be
85 the string constant. Double quote characters inside the braces are not
86 special. Therefore, if you write string constants in the C code, you
87 need not escape each quote character with a backslash.
89 A vector contains an arbitrary number of pointers to expressions. The
90 number of elements in the vector is explicitly present in the vector.
91 The written form of a vector consists of square brackets
92 (@samp{[@dots{}]}) surrounding the elements, in sequence and with
93 whitespace separating them. Vectors of length zero are not created;
94 null pointers are used instead.
96 @cindex expression codes
97 @cindex codes, RTL expression
100 Expressions are classified by @dfn{expression codes} (also called RTX
101 codes). The expression code is a name defined in @file{rtl.def}, which is
102 also (in uppercase) a C enumeration constant. The possible expression
103 codes and their meanings are machine-independent. The code of an RTX can
104 be extracted with the macro @code{GET_CODE (@var{x})} and altered with
105 @code{PUT_CODE (@var{x}, @var{newcode})}.
107 The expression code determines how many operands the expression contains,
108 and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell
109 by looking at an operand what kind of object it is. Instead, you must know
110 from its context---from the expression code of the containing expression.
111 For example, in an expression of code @code{subreg}, the first operand is
112 to be regarded as an expression and the second operand as an integer. In
113 an expression of code @code{plus}, there are two operands, both of which
114 are to be regarded as expressions. In a @code{symbol_ref} expression,
115 there is one operand, which is to be regarded as a string.
117 Expressions are written as parentheses containing the name of the
118 expression type, its flags and machine mode if any, and then the operands
119 of the expression (separated by spaces).
121 Expression code names in the @samp{md} file are written in lowercase,
122 but when they appear in C code they are written in uppercase. In this
123 manual, they are shown as follows: @code{const_int}.
127 In a few contexts a null pointer is valid where an expression is normally
128 wanted. The written form of this is @code{(nil)}.
131 @section RTL Classes and Formats
133 @cindex classes of RTX codes
134 @cindex RTX codes, classes of
135 @findex GET_RTX_CLASS
137 The various expression codes are divided into several @dfn{classes},
138 which are represented by single characters. You can determine the class
139 of an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}.
140 Currently, @file{rtl.def} defines these classes:
144 An RTX code that represents an actual object, such as a register
145 (@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}).
146 @code{LO_SUM}) is also included; instead, @code{SUBREG} and
147 @code{STRICT_LOW_PART} are not in this class, but in class @code{x}.
150 An RTX code that represents a constant object. @code{HIGH} is also
151 included in this class.
154 An RTX code for a non-symmetric comparison, such as @code{GEU} or
157 @item RTX_COMM_COMPARE
158 An RTX code for a symmetric (commutative) comparison, such as @code{EQ}
162 An RTX code for a unary arithmetic operation, such as @code{NEG},
163 @code{NOT}, or @code{ABS}. This category also includes value extension
164 (sign or zero) and conversions between integer and floating point.
167 An RTX code for a commutative binary operation, such as @code{PLUS} or
168 @code{AND}. @code{NE} and @code{EQ} are comparisons, so they have class
172 An RTX code for a non-commutative binary operation, such as @code{MINUS},
173 @code{DIV}, or @code{ASHIFTRT}.
175 @item RTX_BITFIELD_OPS
176 An RTX code for a bit-field operation. Currently only
177 @code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}. These have three inputs
178 and are lvalues (so they can be used for insertion as well).
182 An RTX code for other three input operations. Currently only
183 @code{IF_THEN_ELSE}, @code{VEC_MERGE}, @code{SIGN_EXTRACT},
184 @code{ZERO_EXTRACT}, and @code{FMA}.
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.
410 @findex MEM_OFFSET_KNOWN_P
411 @item MEM_OFFSET_KNOWN_P (@var{x})
412 True if the offset of the memory reference from @code{MEM_EXPR} is known.
413 @samp{MEM_OFFSET (@var{x})} provides the offset if so.
416 @item MEM_OFFSET (@var{x})
417 The offset from the start of @code{MEM_EXPR}. The value is only valid if
418 @samp{MEM_OFFSET_KNOWN_P (@var{x})} is true.
420 @findex MEM_SIZE_KNOWN_P
421 @item MEM_SIZE_KNOWN_P (@var{x})
422 True if the size of the memory reference is known.
423 @samp{MEM_SIZE (@var{x})} provides its size if so.
426 @item MEM_SIZE (@var{x})
427 The size in bytes of the memory reference.
428 This is mostly relevant for @code{BLKmode} references as otherwise
429 the size is implied by the mode. The value is only valid if
430 @samp{MEM_SIZE_KNOWN_P (@var{x})} is true.
433 @item MEM_ALIGN (@var{x})
434 The known alignment in bits of the memory reference.
436 @findex MEM_ADDR_SPACE
437 @item MEM_ADDR_SPACE (@var{x})
438 The address space of the memory reference. This will commonly be zero
439 for the generic address space.
444 @findex ORIGINAL_REGNO
445 @item ORIGINAL_REGNO (@var{x})
446 This field holds the number the register ``originally'' had; for a
447 pseudo register turned into a hard reg this will hold the old pseudo
451 @item REG_EXPR (@var{x})
452 If this register is known to hold the value of some user-level
453 declaration, this is that tree node.
456 @item REG_OFFSET (@var{x})
457 If this register is known to hold the value of some user-level
458 declaration, this is the offset into that logical storage.
463 @findex SYMBOL_REF_DECL
464 @item SYMBOL_REF_DECL (@var{x})
465 If the @code{symbol_ref} @var{x} was created for a @code{VAR_DECL} or
466 a @code{FUNCTION_DECL}, that tree is recorded here. If this value is
467 null, then @var{x} was created by back end code generation routines,
468 and there is no associated front end symbol table entry.
470 @code{SYMBOL_REF_DECL} may also point to a tree of class @code{'c'},
471 that is, some sort of constant. In this case, the @code{symbol_ref}
472 is an entry in the per-file constant pool; again, there is no associated
473 front end symbol table entry.
475 @findex SYMBOL_REF_CONSTANT
476 @item SYMBOL_REF_CONSTANT (@var{x})
477 If @samp{CONSTANT_POOL_ADDRESS_P (@var{x})} is true, this is the constant
478 pool entry for @var{x}. It is null otherwise.
480 @findex SYMBOL_REF_DATA
481 @item SYMBOL_REF_DATA (@var{x})
482 A field of opaque type used to store @code{SYMBOL_REF_DECL} or
483 @code{SYMBOL_REF_CONSTANT}.
485 @findex SYMBOL_REF_FLAGS
486 @item SYMBOL_REF_FLAGS (@var{x})
487 In a @code{symbol_ref}, this is used to communicate various predicates
488 about the symbol. Some of these are common enough to be computed by
489 common code, some are specific to the target. The common bits are:
492 @findex SYMBOL_REF_FUNCTION_P
493 @findex SYMBOL_FLAG_FUNCTION
494 @item SYMBOL_FLAG_FUNCTION
495 Set if the symbol refers to a function.
497 @findex SYMBOL_REF_LOCAL_P
498 @findex SYMBOL_FLAG_LOCAL
499 @item SYMBOL_FLAG_LOCAL
500 Set if the symbol is local to this ``module''.
501 See @code{TARGET_BINDS_LOCAL_P}.
503 @findex SYMBOL_REF_EXTERNAL_P
504 @findex SYMBOL_FLAG_EXTERNAL
505 @item SYMBOL_FLAG_EXTERNAL
506 Set if this symbol is not defined in this translation unit.
507 Note that this is not the inverse of @code{SYMBOL_FLAG_LOCAL}.
509 @findex SYMBOL_REF_SMALL_P
510 @findex SYMBOL_FLAG_SMALL
511 @item SYMBOL_FLAG_SMALL
512 Set if the symbol is located in the small data section.
513 See @code{TARGET_IN_SMALL_DATA_P}.
515 @findex SYMBOL_FLAG_TLS_SHIFT
516 @findex SYMBOL_REF_TLS_MODEL
517 @item SYMBOL_REF_TLS_MODEL (@var{x})
518 This is a multi-bit field accessor that returns the @code{tls_model}
519 to be used for a thread-local storage symbol. It returns zero for
520 non-thread-local symbols.
522 @findex SYMBOL_REF_HAS_BLOCK_INFO_P
523 @findex SYMBOL_FLAG_HAS_BLOCK_INFO
524 @item SYMBOL_FLAG_HAS_BLOCK_INFO
525 Set if the symbol has @code{SYMBOL_REF_BLOCK} and
526 @code{SYMBOL_REF_BLOCK_OFFSET} fields.
528 @findex SYMBOL_REF_ANCHOR_P
529 @findex SYMBOL_FLAG_ANCHOR
530 @cindex @option{-fsection-anchors}
531 @item SYMBOL_FLAG_ANCHOR
532 Set if the symbol is used as a section anchor. ``Section anchors''
533 are symbols that have a known position within an @code{object_block}
534 and that can be used to access nearby members of that block.
535 They are used to implement @option{-fsection-anchors}.
537 If this flag is set, then @code{SYMBOL_FLAG_HAS_BLOCK_INFO} will be too.
540 Bits beginning with @code{SYMBOL_FLAG_MACH_DEP} are available for
544 @findex SYMBOL_REF_BLOCK
545 @item SYMBOL_REF_BLOCK (@var{x})
546 If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the
547 @samp{object_block} structure to which the symbol belongs,
548 or @code{NULL} if it has not been assigned a block.
550 @findex SYMBOL_REF_BLOCK_OFFSET
551 @item SYMBOL_REF_BLOCK_OFFSET (@var{x})
552 If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the offset of @var{x}
553 from the first object in @samp{SYMBOL_REF_BLOCK (@var{x})}. The value is
554 negative if @var{x} has not yet been assigned to a block, or it has not
555 been given an offset within that block.
559 @section Flags in an RTL Expression
560 @cindex flags in RTL expression
562 RTL expressions contain several flags (one-bit bit-fields)
563 that are used in certain types of expression. Most often they
564 are accessed with the following macros, which expand into lvalues.
567 @findex CONSTANT_POOL_ADDRESS_P
568 @cindex @code{symbol_ref} and @samp{/u}
569 @cindex @code{unchanging}, in @code{symbol_ref}
570 @item CONSTANT_POOL_ADDRESS_P (@var{x})
571 Nonzero in a @code{symbol_ref} if it refers to part of the current
572 function's constant pool. For most targets these addresses are in a
573 @code{.rodata} section entirely separate from the function, but for
574 some targets the addresses are close to the beginning of the function.
575 In either case GCC assumes these addresses can be addressed directly,
576 perhaps with the help of base registers.
577 Stored in the @code{unchanging} field and printed as @samp{/u}.
579 @findex RTL_CONST_CALL_P
580 @cindex @code{call_insn} and @samp{/u}
581 @cindex @code{unchanging}, in @code{call_insn}
582 @item RTL_CONST_CALL_P (@var{x})
583 In a @code{call_insn} indicates that the insn represents a call to a
584 const function. Stored in the @code{unchanging} field and printed as
587 @findex RTL_PURE_CALL_P
588 @cindex @code{call_insn} and @samp{/i}
589 @cindex @code{return_val}, in @code{call_insn}
590 @item RTL_PURE_CALL_P (@var{x})
591 In a @code{call_insn} indicates that the insn represents a call to a
592 pure function. Stored in the @code{return_val} field and printed as
595 @findex RTL_CONST_OR_PURE_CALL_P
596 @cindex @code{call_insn} and @samp{/u} or @samp{/i}
597 @item RTL_CONST_OR_PURE_CALL_P (@var{x})
598 In a @code{call_insn}, true if @code{RTL_CONST_CALL_P} or
599 @code{RTL_PURE_CALL_P} is true.
601 @findex RTL_LOOPING_CONST_OR_PURE_CALL_P
602 @cindex @code{call_insn} and @samp{/c}
603 @cindex @code{call}, in @code{call_insn}
604 @item RTL_LOOPING_CONST_OR_PURE_CALL_P (@var{x})
605 In a @code{call_insn} indicates that the insn represents a possibly
606 infinite looping call to a const or pure function. Stored in the
607 @code{call} field and printed as @samp{/c}. Only true if one of
608 @code{RTL_CONST_CALL_P} or @code{RTL_PURE_CALL_P} is true.
610 @findex INSN_ANNULLED_BRANCH_P
611 @cindex @code{jump_insn} and @samp{/u}
612 @cindex @code{call_insn} and @samp{/u}
613 @cindex @code{insn} and @samp{/u}
614 @cindex @code{unchanging}, in @code{jump_insn}, @code{call_insn} and @code{insn}
615 @item INSN_ANNULLED_BRANCH_P (@var{x})
616 In a @code{jump_insn}, @code{call_insn}, or @code{insn} indicates
617 that the branch is an annulling one. See the discussion under
618 @code{sequence} below. Stored in the @code{unchanging} field and
619 printed as @samp{/u}.
621 @findex INSN_DELETED_P
622 @cindex @code{insn} and @samp{/v}
623 @cindex @code{call_insn} and @samp{/v}
624 @cindex @code{jump_insn} and @samp{/v}
625 @cindex @code{code_label} and @samp{/v}
626 @cindex @code{barrier} and @samp{/v}
627 @cindex @code{note} and @samp{/v}
628 @cindex @code{volatil}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, @code{barrier}, and @code{note}
629 @item INSN_DELETED_P (@var{x})
630 In an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label},
631 @code{barrier}, or @code{note},
632 nonzero if the insn has been deleted. Stored in the
633 @code{volatil} field and printed as @samp{/v}.
635 @findex INSN_FROM_TARGET_P
636 @cindex @code{insn} and @samp{/s}
637 @cindex @code{jump_insn} and @samp{/s}
638 @cindex @code{call_insn} and @samp{/s}
639 @cindex @code{in_struct}, in @code{insn} and @code{jump_insn} and @code{call_insn}
640 @item INSN_FROM_TARGET_P (@var{x})
641 In an @code{insn} or @code{jump_insn} or @code{call_insn} in a delay
642 slot of a branch, indicates that the insn
643 is from the target of the branch. If the branch insn has
644 @code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if
645 the branch is taken. For annulled branches with
646 @code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the
647 branch is not taken. When @code{INSN_ANNULLED_BRANCH_P} is not set,
648 this insn will always be executed. Stored in the @code{in_struct}
649 field and printed as @samp{/s}.
651 @findex LABEL_PRESERVE_P
652 @cindex @code{code_label} and @samp{/i}
653 @cindex @code{note} and @samp{/i}
654 @cindex @code{in_struct}, in @code{code_label} and @code{note}
655 @item LABEL_PRESERVE_P (@var{x})
656 In a @code{code_label} or @code{note}, indicates that the label is referenced by
657 code or data not visible to the RTL of a given function.
658 Labels referenced by a non-local goto will have this bit set. Stored
659 in the @code{in_struct} field and printed as @samp{/s}.
661 @findex LABEL_REF_NONLOCAL_P
662 @cindex @code{label_ref} and @samp{/v}
663 @cindex @code{reg_label} and @samp{/v}
664 @cindex @code{volatil}, in @code{label_ref} and @code{reg_label}
665 @item LABEL_REF_NONLOCAL_P (@var{x})
666 In @code{label_ref} and @code{reg_label} expressions, nonzero if this is
667 a reference to a non-local label.
668 Stored in the @code{volatil} field and printed as @samp{/v}.
670 @findex MEM_KEEP_ALIAS_SET_P
671 @cindex @code{mem} and @samp{/j}
672 @cindex @code{jump}, in @code{mem}
673 @item MEM_KEEP_ALIAS_SET_P (@var{x})
674 In @code{mem} expressions, 1 if we should keep the alias set for this
675 mem unchanged when we access a component. Set to 1, for example, when we
676 are already in a non-addressable component of an aggregate.
677 Stored in the @code{jump} field and printed as @samp{/j}.
679 @findex MEM_VOLATILE_P
680 @cindex @code{mem} and @samp{/v}
681 @cindex @code{asm_input} and @samp{/v}
682 @cindex @code{asm_operands} and @samp{/v}
683 @cindex @code{volatil}, in @code{mem}, @code{asm_operands}, and @code{asm_input}
684 @item MEM_VOLATILE_P (@var{x})
685 In @code{mem}, @code{asm_operands}, and @code{asm_input} expressions,
686 nonzero for volatile memory references.
687 Stored in the @code{volatil} field and printed as @samp{/v}.
690 @cindex @code{mem} and @samp{/c}
691 @cindex @code{call}, in @code{mem}
692 @item MEM_NOTRAP_P (@var{x})
693 In @code{mem}, nonzero for memory references that will not trap.
694 Stored in the @code{call} field and printed as @samp{/c}.
697 @cindex @code{mem} and @samp{/f}
698 @cindex @code{frame_related}, in @code{mem}
699 @item MEM_POINTER (@var{x})
700 Nonzero in a @code{mem} if the memory reference holds a pointer.
701 Stored in the @code{frame_related} field and printed as @samp{/f}.
703 @findex REG_FUNCTION_VALUE_P
704 @cindex @code{reg} and @samp{/i}
705 @cindex @code{return_val}, in @code{reg}
706 @item REG_FUNCTION_VALUE_P (@var{x})
707 Nonzero in a @code{reg} if it is the place in which this function's
708 value is going to be returned. (This happens only in a hard
709 register.) Stored in the @code{return_val} field and printed as
713 @cindex @code{reg} and @samp{/f}
714 @cindex @code{frame_related}, in @code{reg}
715 @item REG_POINTER (@var{x})
716 Nonzero in a @code{reg} if the register holds a pointer. Stored in the
717 @code{frame_related} field and printed as @samp{/f}.
719 @findex REG_USERVAR_P
720 @cindex @code{reg} and @samp{/v}
721 @cindex @code{volatil}, in @code{reg}
722 @item REG_USERVAR_P (@var{x})
723 In a @code{reg}, nonzero if it corresponds to a variable present in
724 the user's source code. Zero for temporaries generated internally by
725 the compiler. Stored in the @code{volatil} field and printed as
728 The same hard register may be used also for collecting the values of
729 functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
732 @findex RTX_FRAME_RELATED_P
733 @cindex @code{insn} and @samp{/f}
734 @cindex @code{call_insn} and @samp{/f}
735 @cindex @code{jump_insn} and @samp{/f}
736 @cindex @code{barrier} and @samp{/f}
737 @cindex @code{set} and @samp{/f}
738 @cindex @code{frame_related}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, and @code{set}
739 @item RTX_FRAME_RELATED_P (@var{x})
740 Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn},
741 @code{barrier}, or @code{set} which is part of a function prologue
742 and sets the stack pointer, sets the frame pointer, or saves a register.
743 This flag should also be set on an instruction that sets up a temporary
744 register to use in place of the frame pointer.
745 Stored in the @code{frame_related} field and printed as @samp{/f}.
747 In particular, on RISC targets where there are limits on the sizes of
748 immediate constants, it is sometimes impossible to reach the register
749 save area directly from the stack pointer. In that case, a temporary
750 register is used that is near enough to the register save area, and the
751 Canonical Frame Address, i.e., DWARF2's logical frame pointer, register
752 must (temporarily) be changed to be this temporary register. So, the
753 instruction that sets this temporary register must be marked as
754 @code{RTX_FRAME_RELATED_P}.
756 If the marked instruction is overly complex (defined in terms of what
757 @code{dwarf2out_frame_debug_expr} can handle), you will also have to
758 create a @code{REG_FRAME_RELATED_EXPR} note and attach it to the
759 instruction. This note should contain a simple expression of the
760 computation performed by this instruction, i.e., one that
761 @code{dwarf2out_frame_debug_expr} can handle.
763 This flag is required for exception handling support on targets with RTL
766 @findex MEM_READONLY_P
767 @cindex @code{mem} and @samp{/u}
768 @cindex @code{unchanging}, in @code{mem}
769 @item MEM_READONLY_P (@var{x})
770 Nonzero in a @code{mem}, if the memory is statically allocated and read-only.
772 Read-only in this context means never modified during the lifetime of the
773 program, not necessarily in ROM or in write-disabled pages. A common
774 example of the later is a shared library's global offset table. This
775 table is initialized by the runtime loader, so the memory is technically
776 writable, but after control is transferred from the runtime loader to the
777 application, this memory will never be subsequently modified.
779 Stored in the @code{unchanging} field and printed as @samp{/u}.
781 @findex SCHED_GROUP_P
782 @cindex @code{insn} and @samp{/s}
783 @cindex @code{call_insn} and @samp{/s}
784 @cindex @code{jump_insn} and @samp{/s}
785 @cindex @code{in_struct}, in @code{insn}, @code{jump_insn} and @code{call_insn}
786 @item SCHED_GROUP_P (@var{x})
787 During instruction scheduling, in an @code{insn}, @code{call_insn} or
788 @code{jump_insn}, indicates that the
789 previous insn must be scheduled together with this insn. This is used to
790 ensure that certain groups of instructions will not be split up by the
791 instruction scheduling pass, for example, @code{use} insns before
792 a @code{call_insn} may not be separated from the @code{call_insn}.
793 Stored in the @code{in_struct} field and printed as @samp{/s}.
795 @findex SET_IS_RETURN_P
796 @cindex @code{insn} and @samp{/j}
797 @cindex @code{jump}, in @code{insn}
798 @item SET_IS_RETURN_P (@var{x})
799 For a @code{set}, nonzero if it is for a return.
800 Stored in the @code{jump} field and printed as @samp{/j}.
802 @findex SIBLING_CALL_P
803 @cindex @code{call_insn} and @samp{/j}
804 @cindex @code{jump}, in @code{call_insn}
805 @item SIBLING_CALL_P (@var{x})
806 For a @code{call_insn}, nonzero if the insn is a sibling call.
807 Stored in the @code{jump} field and printed as @samp{/j}.
809 @findex STRING_POOL_ADDRESS_P
810 @cindex @code{symbol_ref} and @samp{/f}
811 @cindex @code{frame_related}, in @code{symbol_ref}
812 @item STRING_POOL_ADDRESS_P (@var{x})
813 For a @code{symbol_ref} expression, nonzero if it addresses this function's
814 string constant pool.
815 Stored in the @code{frame_related} field and printed as @samp{/f}.
817 @findex SUBREG_PROMOTED_UNSIGNED_P
818 @cindex @code{subreg} and @samp{/u} and @samp{/v}
819 @cindex @code{unchanging}, in @code{subreg}
820 @cindex @code{volatil}, in @code{subreg}
821 @item SUBREG_PROMOTED_UNSIGNED_P (@var{x})
822 Returns a value greater then zero for a @code{subreg} that has
823 @code{SUBREG_PROMOTED_VAR_P} nonzero if the object being referenced is kept
824 zero-extended, zero if it is kept sign-extended, and less then zero if it is
825 extended some other way via the @code{ptr_extend} instruction.
826 Stored in the @code{unchanging}
827 field and @code{volatil} field, printed as @samp{/u} and @samp{/v}.
828 This macro may only be used to get the value it may not be used to change
829 the value. Use @code{SUBREG_PROMOTED_UNSIGNED_SET} to change the value.
831 @findex SUBREG_PROMOTED_UNSIGNED_SET
832 @cindex @code{subreg} and @samp{/u}
833 @cindex @code{unchanging}, in @code{subreg}
834 @cindex @code{volatil}, in @code{subreg}
835 @item SUBREG_PROMOTED_UNSIGNED_SET (@var{x})
836 Set the @code{unchanging} and @code{volatil} fields in a @code{subreg}
837 to reflect zero, sign, or other extension. If @code{volatil} is
838 zero, then @code{unchanging} as nonzero means zero extension and as
839 zero means sign extension. If @code{volatil} is nonzero then some
840 other type of extension was done via the @code{ptr_extend} instruction.
842 @findex SUBREG_PROMOTED_VAR_P
843 @cindex @code{subreg} and @samp{/s}
844 @cindex @code{in_struct}, in @code{subreg}
845 @item SUBREG_PROMOTED_VAR_P (@var{x})
846 Nonzero in a @code{subreg} if it was made when accessing an object that
847 was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine
848 description macro (@pxref{Storage Layout}). In this case, the mode of
849 the @code{subreg} is the declared mode of the object and the mode of
850 @code{SUBREG_REG} is the mode of the register that holds the object.
851 Promoted variables are always either sign- or zero-extended to the wider
852 mode on every assignment. Stored in the @code{in_struct} field and
853 printed as @samp{/s}.
855 @findex SYMBOL_REF_USED
856 @cindex @code{used}, in @code{symbol_ref}
857 @item SYMBOL_REF_USED (@var{x})
858 In a @code{symbol_ref}, indicates that @var{x} has been used. This is
859 normally only used to ensure that @var{x} is only declared external
860 once. Stored in the @code{used} field.
862 @findex SYMBOL_REF_WEAK
863 @cindex @code{symbol_ref} and @samp{/i}
864 @cindex @code{return_val}, in @code{symbol_ref}
865 @item SYMBOL_REF_WEAK (@var{x})
866 In a @code{symbol_ref}, indicates that @var{x} has been declared weak.
867 Stored in the @code{return_val} field and printed as @samp{/i}.
869 @findex SYMBOL_REF_FLAG
870 @cindex @code{symbol_ref} and @samp{/v}
871 @cindex @code{volatil}, in @code{symbol_ref}
872 @item SYMBOL_REF_FLAG (@var{x})
873 In a @code{symbol_ref}, this is used as a flag for machine-specific purposes.
874 Stored in the @code{volatil} field and printed as @samp{/v}.
876 Most uses of @code{SYMBOL_REF_FLAG} are historic and may be subsumed
877 by @code{SYMBOL_REF_FLAGS}. Certainly use of @code{SYMBOL_REF_FLAGS}
878 is mandatory if the target requires more than one bit of storage.
880 @findex PREFETCH_SCHEDULE_BARRIER_P
881 @cindex @code{prefetch} and @samp{/v}
882 @cindex @code{volatile}, in @code{prefetch}
883 @item PREFETCH_SCHEDULE_BARRIER_P (@var{x})
884 In a @code{prefetch}, indicates that the prefetch is a scheduling barrier.
885 No other INSNs will be moved over it.
886 Stored in the @code{volatil} field and printed as @samp{/v}.
889 These are the fields to which the above macros refer:
893 @cindex @samp{/c} in RTL dump
895 In a @code{mem}, 1 means that the memory reference will not trap.
897 In a @code{call}, 1 means that this pure or const call may possibly
900 In an RTL dump, this flag is represented as @samp{/c}.
902 @findex frame_related
903 @cindex @samp{/f} in RTL dump
905 In an @code{insn} or @code{set} expression, 1 means that it is part of
906 a function prologue and sets the stack pointer, sets the frame pointer,
907 saves a register, or sets up a temporary register to use in place of the
910 In @code{reg} expressions, 1 means that the register holds a pointer.
912 In @code{mem} expressions, 1 means that the memory reference holds a pointer.
914 In @code{symbol_ref} expressions, 1 means that the reference addresses
915 this function's string constant pool.
917 In an RTL dump, this flag is represented as @samp{/f}.
920 @cindex @samp{/s} in RTL dump
922 In @code{reg} expressions, it is 1 if the register has its entire life
923 contained within the test expression of some loop.
925 In @code{subreg} expressions, 1 means that the @code{subreg} is accessing
926 an object that has had its mode promoted from a wider mode.
928 In @code{label_ref} expressions, 1 means that the referenced label is
929 outside the innermost loop containing the insn in which the @code{label_ref}
932 In @code{code_label} expressions, it is 1 if the label may never be deleted.
933 This is used for labels which are the target of non-local gotos. Such a
934 label that would have been deleted is replaced with a @code{note} of type
935 @code{NOTE_INSN_DELETED_LABEL}.
937 In an @code{insn} during dead-code elimination, 1 means that the insn is
940 In an @code{insn} or @code{jump_insn} during reorg for an insn in the
941 delay slot of a branch,
942 1 means that this insn is from the target of the branch.
944 In an @code{insn} during instruction scheduling, 1 means that this insn
945 must be scheduled as part of a group together with the previous insn.
947 In an RTL dump, this flag is represented as @samp{/s}.
950 @cindex @samp{/i} in RTL dump
952 In @code{reg} expressions, 1 means the register contains
953 the value to be returned by the current function. On
954 machines that pass parameters in registers, the same register number
955 may be used for parameters as well, but this flag is not set on such
958 In @code{symbol_ref} expressions, 1 means the referenced symbol is weak.
960 In @code{call} expressions, 1 means the call is pure.
962 In an RTL dump, this flag is represented as @samp{/i}.
965 @cindex @samp{/j} in RTL dump
967 In a @code{mem} expression, 1 means we should keep the alias set for this
968 mem unchanged when we access a component.
970 In a @code{set}, 1 means it is for a return.
972 In a @code{call_insn}, 1 means it is a sibling call.
974 In an RTL dump, this flag is represented as @samp{/j}.
977 @cindex @samp{/u} in RTL dump
979 In @code{reg} and @code{mem} expressions, 1 means
980 that the value of the expression never changes.
982 In @code{subreg} expressions, it is 1 if the @code{subreg} references an
983 unsigned object whose mode has been promoted to a wider mode.
985 In an @code{insn} or @code{jump_insn} in the delay slot of a branch
986 instruction, 1 means an annulling branch should be used.
988 In a @code{symbol_ref} expression, 1 means that this symbol addresses
989 something in the per-function constant pool.
991 In a @code{call_insn} 1 means that this instruction is a call to a const
994 In an RTL dump, this flag is represented as @samp{/u}.
998 This flag is used directly (without an access macro) at the end of RTL
999 generation for a function, to count the number of times an expression
1000 appears in insns. Expressions that appear more than once are copied,
1001 according to the rules for shared structure (@pxref{Sharing}).
1003 For a @code{reg}, it is used directly (without an access macro) by the
1004 leaf register renumbering code to ensure that each register is only
1007 In a @code{symbol_ref}, it indicates that an external declaration for
1008 the symbol has already been written.
1011 @cindex @samp{/v} in RTL dump
1013 @cindex volatile memory references
1014 In a @code{mem}, @code{asm_operands}, or @code{asm_input}
1015 expression, it is 1 if the memory
1016 reference is volatile. Volatile memory references may not be deleted,
1017 reordered or combined.
1019 In a @code{symbol_ref} expression, it is used for machine-specific
1022 In a @code{reg} expression, it is 1 if the value is a user-level variable.
1023 0 indicates an internal compiler temporary.
1025 In an @code{insn}, 1 means the insn has been deleted.
1027 In @code{label_ref} and @code{reg_label} expressions, 1 means a reference
1028 to a non-local label.
1030 In @code{prefetch} expressions, 1 means that the containing insn is a
1033 In an RTL dump, this flag is represented as @samp{/v}.
1037 @section Machine Modes
1038 @cindex machine modes
1040 @findex enum machine_mode
1041 A machine mode describes a size of data object and the representation used
1042 for it. In the C code, machine modes are represented by an enumeration
1043 type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL
1044 expression has room for a machine mode and so do certain kinds of tree
1045 expressions (declarations and types, to be precise).
1047 In debugging dumps and machine descriptions, the machine mode of an RTL
1048 expression is written after the expression code with a colon to separate
1049 them. The letters @samp{mode} which appear at the end of each machine mode
1050 name are omitted. For example, @code{(reg:SI 38)} is a @code{reg}
1051 expression with machine mode @code{SImode}. If the mode is
1052 @code{VOIDmode}, it is not written at all.
1054 Here is a table of machine modes. The term ``byte'' below refers to an
1055 object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}).
1060 ``Bit'' mode represents a single bit, for predicate registers.
1064 ``Quarter-Integer'' mode represents a single byte treated as an integer.
1068 ``Half-Integer'' mode represents a two-byte integer.
1072 ``Partial Single Integer'' mode represents an integer which occupies
1073 four bytes but which doesn't really use all four. On some machines,
1074 this is the right mode to use for pointers.
1078 ``Single Integer'' mode represents a four-byte integer.
1082 ``Partial Double Integer'' mode represents an integer which occupies
1083 eight bytes but which doesn't really use all eight. On some machines,
1084 this is the right mode to use for certain pointers.
1088 ``Double Integer'' mode represents an eight-byte integer.
1092 ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
1096 ``Octa Integer'' (?) mode represents a thirty-two-byte integer.
1100 ``Quarter-Floating'' mode represents a quarter-precision (single byte)
1101 floating point number.
1105 ``Half-Floating'' mode represents a half-precision (two byte) floating
1110 ``Three-Quarter-Floating'' (?) mode represents a three-quarter-precision
1111 (three byte) floating point number.
1115 ``Single Floating'' mode represents a four byte floating point number.
1116 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1117 this is a single-precision IEEE floating point number; it can also be
1118 used for double-precision (on processors with 16-bit bytes) and
1119 single-precision VAX and IBM types.
1123 ``Double Floating'' mode represents an eight byte floating point number.
1124 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1125 this is a double-precision IEEE floating point number.
1129 ``Extended Floating'' mode represents an IEEE extended floating point
1130 number. This mode only has 80 meaningful bits (ten bytes). Some
1131 processors require such numbers to be padded to twelve bytes, others
1132 to sixteen; this mode is used for either.
1136 ``Single Decimal Floating'' mode represents a four byte decimal
1137 floating point number (as distinct from conventional binary floating
1142 ``Double Decimal Floating'' mode represents an eight byte decimal
1143 floating point number.
1147 ``Tetra Decimal Floating'' mode represents a sixteen byte decimal
1148 floating point number all 128 of whose bits are meaningful.
1152 ``Tetra Floating'' mode represents a sixteen byte floating point number
1153 all 128 of whose bits are meaningful. One common use is the
1154 IEEE quad-precision format.
1158 ``Quarter-Fractional'' mode represents a single byte treated as a signed
1159 fractional number. The default format is ``s.7''.
1163 ``Half-Fractional'' mode represents a two-byte signed fractional number.
1164 The default format is ``s.15''.
1168 ``Single Fractional'' mode represents a four-byte signed fractional number.
1169 The default format is ``s.31''.
1173 ``Double Fractional'' mode represents an eight-byte signed fractional number.
1174 The default format is ``s.63''.
1178 ``Tetra Fractional'' mode represents a sixteen-byte signed fractional number.
1179 The default format is ``s.127''.
1183 ``Unsigned Quarter-Fractional'' mode represents a single byte treated as an
1184 unsigned fractional number. The default format is ``.8''.
1188 ``Unsigned Half-Fractional'' mode represents a two-byte unsigned fractional
1189 number. The default format is ``.16''.
1193 ``Unsigned Single Fractional'' mode represents a four-byte unsigned fractional
1194 number. The default format is ``.32''.
1198 ``Unsigned Double Fractional'' mode represents an eight-byte unsigned
1199 fractional number. The default format is ``.64''.
1203 ``Unsigned Tetra Fractional'' mode represents a sixteen-byte unsigned
1204 fractional number. The default format is ``.128''.
1208 ``Half-Accumulator'' mode represents a two-byte signed accumulator.
1209 The default format is ``s8.7''.
1213 ``Single Accumulator'' mode represents a four-byte signed accumulator.
1214 The default format is ``s16.15''.
1218 ``Double Accumulator'' mode represents an eight-byte signed accumulator.
1219 The default format is ``s32.31''.
1223 ``Tetra Accumulator'' mode represents a sixteen-byte signed accumulator.
1224 The default format is ``s64.63''.
1228 ``Unsigned Half-Accumulator'' mode represents a two-byte unsigned accumulator.
1229 The default format is ``8.8''.
1233 ``Unsigned Single Accumulator'' mode represents a four-byte unsigned
1234 accumulator. The default format is ``16.16''.
1238 ``Unsigned Double Accumulator'' mode represents an eight-byte unsigned
1239 accumulator. The default format is ``32.32''.
1243 ``Unsigned Tetra Accumulator'' mode represents a sixteen-byte unsigned
1244 accumulator. The default format is ``64.64''.
1248 ``Condition Code'' mode represents the value of a condition code, which
1249 is a machine-specific set of bits used to represent the result of a
1250 comparison operation. Other machine-specific modes may also be used for
1251 the condition code. These modes are not used on machines that use
1252 @code{cc0} (@pxref{Condition Code}).
1256 ``Block'' mode represents values that are aggregates to which none of
1257 the other modes apply. In RTL, only memory references can have this mode,
1258 and only if they appear in string-move or vector instructions. On machines
1259 which have no such instructions, @code{BLKmode} will not appear in RTL@.
1263 Void mode means the absence of a mode or an unspecified mode.
1264 For example, RTL expressions of code @code{const_int} have mode
1265 @code{VOIDmode} because they can be taken to have whatever mode the context
1266 requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by
1267 the absence of any mode.
1275 @item QCmode, HCmode, SCmode, DCmode, XCmode, TCmode
1276 These modes stand for a complex number represented as a pair of floating
1277 point values. The floating point values are in @code{QFmode},
1278 @code{HFmode}, @code{SFmode}, @code{DFmode}, @code{XFmode}, and
1279 @code{TFmode}, respectively.
1287 @item CQImode, CHImode, CSImode, CDImode, CTImode, COImode
1288 These modes stand for a complex number represented as a pair of integer
1289 values. The integer values are in @code{QImode}, @code{HImode},
1290 @code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode},
1294 The machine description defines @code{Pmode} as a C macro which expands
1295 into the machine mode used for addresses. Normally this is the mode
1296 whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines.
1298 The only modes which a machine description @i{must} support are
1299 @code{QImode}, and the modes corresponding to @code{BITS_PER_WORD},
1300 @code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}.
1301 The compiler will attempt to use @code{DImode} for 8-byte structures and
1302 unions, but this can be prevented by overriding the definition of
1303 @code{MAX_FIXED_MODE_SIZE}. Alternatively, you can have the compiler
1304 use @code{TImode} for 16-byte structures and unions. Likewise, you can
1305 arrange for the C type @code{short int} to avoid using @code{HImode}.
1307 @cindex mode classes
1308 Very few explicit references to machine modes remain in the compiler and
1309 these few references will soon be removed. Instead, the machine modes
1310 are divided into mode classes. These are represented by the enumeration
1311 type @code{enum mode_class} defined in @file{machmode.h}. The possible
1317 Integer modes. By default these are @code{BImode}, @code{QImode},
1318 @code{HImode}, @code{SImode}, @code{DImode}, @code{TImode}, and
1321 @findex MODE_PARTIAL_INT
1322 @item MODE_PARTIAL_INT
1323 The ``partial integer'' modes, @code{PQImode}, @code{PHImode},
1324 @code{PSImode} and @code{PDImode}.
1328 Floating point modes. By default these are @code{QFmode},
1329 @code{HFmode}, @code{TQFmode}, @code{SFmode}, @code{DFmode},
1330 @code{XFmode} and @code{TFmode}.
1332 @findex MODE_DECIMAL_FLOAT
1333 @item MODE_DECIMAL_FLOAT
1334 Decimal floating point modes. By default these are @code{SDmode},
1335 @code{DDmode} and @code{TDmode}.
1339 Signed fractional modes. By default these are @code{QQmode}, @code{HQmode},
1340 @code{SQmode}, @code{DQmode} and @code{TQmode}.
1344 Unsigned fractional modes. By default these are @code{UQQmode}, @code{UHQmode},
1345 @code{USQmode}, @code{UDQmode} and @code{UTQmode}.
1349 Signed accumulator modes. By default these are @code{HAmode},
1350 @code{SAmode}, @code{DAmode} and @code{TAmode}.
1354 Unsigned accumulator modes. By default these are @code{UHAmode},
1355 @code{USAmode}, @code{UDAmode} and @code{UTAmode}.
1357 @findex MODE_COMPLEX_INT
1358 @item MODE_COMPLEX_INT
1359 Complex integer modes. (These are not currently implemented).
1361 @findex MODE_COMPLEX_FLOAT
1362 @item MODE_COMPLEX_FLOAT
1363 Complex floating point modes. By default these are @code{QCmode},
1364 @code{HCmode}, @code{SCmode}, @code{DCmode}, @code{XCmode}, and
1367 @findex MODE_FUNCTION
1369 Algol or Pascal function variables including a static chain.
1370 (These are not currently implemented).
1374 Modes representing condition code values. These are @code{CCmode} plus
1375 any @code{CC_MODE} modes listed in the @file{@var{machine}-modes.def}.
1376 @xref{Jump Patterns},
1377 also see @ref{Condition Code}.
1381 This is a catchall mode class for modes which don't fit into the above
1382 classes. Currently @code{VOIDmode} and @code{BLKmode} are in
1386 Here are some C macros that relate to machine modes:
1390 @item GET_MODE (@var{x})
1391 Returns the machine mode of the RTX @var{x}.
1394 @item PUT_MODE (@var{x}, @var{newmode})
1395 Alters the machine mode of the RTX @var{x} to be @var{newmode}.
1397 @findex NUM_MACHINE_MODES
1398 @item NUM_MACHINE_MODES
1399 Stands for the number of machine modes available on the target
1400 machine. This is one greater than the largest numeric value of any
1403 @findex GET_MODE_NAME
1404 @item GET_MODE_NAME (@var{m})
1405 Returns the name of mode @var{m} as a string.
1407 @findex GET_MODE_CLASS
1408 @item GET_MODE_CLASS (@var{m})
1409 Returns the mode class of mode @var{m}.
1411 @findex GET_MODE_WIDER_MODE
1412 @item GET_MODE_WIDER_MODE (@var{m})
1413 Returns the next wider natural mode. For example, the expression
1414 @code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}.
1416 @findex GET_MODE_SIZE
1417 @item GET_MODE_SIZE (@var{m})
1418 Returns the size in bytes of a datum of mode @var{m}.
1420 @findex GET_MODE_BITSIZE
1421 @item GET_MODE_BITSIZE (@var{m})
1422 Returns the size in bits of a datum of mode @var{m}.
1424 @findex GET_MODE_IBIT
1425 @item GET_MODE_IBIT (@var{m})
1426 Returns the number of integral bits of a datum of fixed-point mode @var{m}.
1428 @findex GET_MODE_FBIT
1429 @item GET_MODE_FBIT (@var{m})
1430 Returns the number of fractional bits of a datum of fixed-point mode @var{m}.
1432 @findex GET_MODE_MASK
1433 @item GET_MODE_MASK (@var{m})
1434 Returns a bitmask containing 1 for all bits in a word that fit within
1435 mode @var{m}. This macro can only be used for modes whose bitsize is
1436 less than or equal to @code{HOST_BITS_PER_INT}.
1438 @findex GET_MODE_ALIGNMENT
1439 @item GET_MODE_ALIGNMENT (@var{m})
1440 Return the required alignment, in bits, for an object of mode @var{m}.
1442 @findex GET_MODE_UNIT_SIZE
1443 @item GET_MODE_UNIT_SIZE (@var{m})
1444 Returns the size in bytes of the subunits of a datum of mode @var{m}.
1445 This is the same as @code{GET_MODE_SIZE} except in the case of complex
1446 modes. For them, the unit size is the size of the real or imaginary
1449 @findex GET_MODE_NUNITS
1450 @item GET_MODE_NUNITS (@var{m})
1451 Returns the number of units contained in a mode, i.e.,
1452 @code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}.
1454 @findex GET_CLASS_NARROWEST_MODE
1455 @item GET_CLASS_NARROWEST_MODE (@var{c})
1456 Returns the narrowest mode in mode class @var{c}.
1461 The global variables @code{byte_mode} and @code{word_mode} contain modes
1462 whose classes are @code{MODE_INT} and whose bitsizes are either
1463 @code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit
1464 machines, these are @code{QImode} and @code{SImode}, respectively.
1467 @section Constant Expression Types
1468 @cindex RTL constants
1469 @cindex RTL constant expression types
1471 The simplest RTL expressions are those that represent constant values.
1475 @item (const_int @var{i})
1476 This type of expression represents the integer value @var{i}. @var{i}
1477 is customarily accessed with the macro @code{INTVAL} as in
1478 @code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}.
1480 Constants generated for modes with fewer bits than in
1481 @code{HOST_WIDE_INT} must be sign extended to full width (e.g., with
1482 @code{gen_int_mode}). For constants for modes with more bits than in
1483 @code{HOST_WIDE_INT} the implied high order bits of that constant are
1484 copies of the top bit. Note however that values are neither
1485 inherently signed nor inherently unsigned; where necessary, signedness
1486 is determined by the rtl operation instead.
1492 There is only one expression object for the integer value zero; it is
1493 the value of the variable @code{const0_rtx}. Likewise, the only
1494 expression for integer value one is found in @code{const1_rtx}, the only
1495 expression for integer value two is found in @code{const2_rtx}, and the
1496 only expression for integer value negative one is found in
1497 @code{constm1_rtx}. Any attempt to create an expression of code
1498 @code{const_int} and value zero, one, two or negative one will return
1499 @code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or
1500 @code{constm1_rtx} as appropriate.
1502 @findex const_true_rtx
1503 Similarly, there is only one object for the integer whose value is
1504 @code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If
1505 @code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and
1506 @code{const1_rtx} will point to the same object. If
1507 @code{STORE_FLAG_VALUE} is @minus{}1, @code{const_true_rtx} and
1508 @code{constm1_rtx} will point to the same object.
1510 @findex const_double
1511 @item (const_double:@var{m} @var{i0} @var{i1} @dots{})
1512 Represents either a floating-point constant of mode @var{m} or an
1513 integer constant too large to fit into @code{HOST_BITS_PER_WIDE_INT}
1514 bits but small enough to fit within twice that number of bits (GCC
1515 does not provide a mechanism to represent even larger constants). In
1516 the latter case, @var{m} will be @code{VOIDmode}. For integral values
1517 constants for modes with more bits than twice the number in
1518 @code{HOST_WIDE_INT} the implied high order bits of that constant are
1519 copies of the top bit of @code{CONST_DOUBLE_HIGH}. Note however that
1520 integral values are neither inherently signed nor inherently unsigned;
1521 where necessary, signedness is determined by the rtl operation
1524 @findex CONST_DOUBLE_LOW
1525 If @var{m} is @code{VOIDmode}, the bits of the value are stored in
1526 @var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro
1527 @code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}.
1529 If the constant is floating point (regardless of its precision), then
1530 the number of integers used to store the value depends on the size of
1531 @code{REAL_VALUE_TYPE} (@pxref{Floating Point}). The integers
1532 represent a floating point number, but not precisely in the target
1533 machine's or host machine's floating point format. To convert them to
1534 the precise bit pattern used by the target machine, use the macro
1535 @code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}).
1538 @item (const_fixed:@var{m} @dots{})
1539 Represents a fixed-point constant of mode @var{m}.
1540 The operand is a data structure of type @code{struct fixed_value} and
1541 is accessed with the macro @code{CONST_FIXED_VALUE}. The high part of
1542 data is accessed with @code{CONST_FIXED_VALUE_HIGH}; the low part is
1543 accessed with @code{CONST_FIXED_VALUE_LOW}.
1545 @findex const_vector
1546 @item (const_vector:@var{m} [@var{x0} @var{x1} @dots{}])
1547 Represents a vector constant. The square brackets stand for the vector
1548 containing the constant elements. @var{x0}, @var{x1} and so on are
1549 the @code{const_int}, @code{const_double} or @code{const_fixed} elements.
1551 The number of units in a @code{const_vector} is obtained with the macro
1552 @code{CONST_VECTOR_NUNITS} as in @code{CONST_VECTOR_NUNITS (@var{v})}.
1554 Individual elements in a vector constant are accessed with the macro
1555 @code{CONST_VECTOR_ELT} as in @code{CONST_VECTOR_ELT (@var{v}, @var{n})}
1556 where @var{v} is the vector constant and @var{n} is the element
1559 @findex const_string
1560 @item (const_string @var{str})
1561 Represents a constant string with value @var{str}. Currently this is
1562 used only for insn attributes (@pxref{Insn Attributes}) since constant
1563 strings in C are placed in memory.
1566 @item (symbol_ref:@var{mode} @var{symbol})
1567 Represents the value of an assembler label for data. @var{symbol} is
1568 a string that describes the name of the assembler label. If it starts
1569 with a @samp{*}, the label is the rest of @var{symbol} not including
1570 the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed
1573 The @code{symbol_ref} contains a mode, which is usually @code{Pmode}.
1574 Usually that is the only mode for which a symbol is directly valid.
1577 @item (label_ref:@var{mode} @var{label})
1578 Represents the value of an assembler label for code. It contains one
1579 operand, an expression, which must be a @code{code_label} or a @code{note}
1580 of type @code{NOTE_INSN_DELETED_LABEL} that appears in the instruction
1581 sequence to identify the place where the label should go.
1583 The reason for using a distinct expression type for code label
1584 references is so that jump optimization can distinguish them.
1586 The @code{label_ref} contains a mode, which is usually @code{Pmode}.
1587 Usually that is the only mode for which a label is directly valid.
1590 @item (const:@var{m} @var{exp})
1591 Represents a constant that is the result of an assembly-time
1592 arithmetic computation. The operand, @var{exp}, is an expression that
1593 contains only constants (@code{const_int}, @code{symbol_ref} and
1594 @code{label_ref} expressions) combined with @code{plus} and
1595 @code{minus}. However, not all combinations are valid, since the
1596 assembler cannot do arbitrary arithmetic on relocatable symbols.
1598 @var{m} should be @code{Pmode}.
1601 @item (high:@var{m} @var{exp})
1602 Represents the high-order bits of @var{exp}, usually a
1603 @code{symbol_ref}. The number of bits is machine-dependent and is
1604 normally the number of bits specified in an instruction that initializes
1605 the high order bits of a register. It is used with @code{lo_sum} to
1606 represent the typical two-instruction sequence used in RISC machines to
1607 reference a global memory location.
1609 @var{m} should be @code{Pmode}.
1615 The macro @code{CONST0_RTX (@var{mode})} refers to an expression with
1616 value 0 in mode @var{mode}. If mode @var{mode} is of mode class
1617 @code{MODE_INT}, it returns @code{const0_rtx}. If mode @var{mode} is of
1618 mode class @code{MODE_FLOAT}, it returns a @code{CONST_DOUBLE}
1619 expression in mode @var{mode}. Otherwise, it returns a
1620 @code{CONST_VECTOR} expression in mode @var{mode}. Similarly, the macro
1621 @code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in
1622 mode @var{mode} and similarly for @code{CONST2_RTX}. The
1623 @code{CONST1_RTX} and @code{CONST2_RTX} macros are undefined
1626 @node Regs and Memory
1627 @section Registers and Memory
1628 @cindex RTL register expressions
1629 @cindex RTL memory expressions
1631 Here are the RTL expression types for describing access to machine
1632 registers and to main memory.
1636 @cindex hard registers
1637 @cindex pseudo registers
1638 @item (reg:@var{m} @var{n})
1639 For small values of the integer @var{n} (those that are less than
1640 @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
1641 register number @var{n}: a @dfn{hard register}. For larger values of
1642 @var{n}, it stands for a temporary value or @dfn{pseudo register}.
1643 The compiler's strategy is to generate code assuming an unlimited
1644 number of such pseudo registers, and later convert them into hard
1645 registers or into memory references.
1647 @var{m} is the machine mode of the reference. It is necessary because
1648 machines can generally refer to each register in more than one mode.
1649 For example, a register may contain a full word but there may be
1650 instructions to refer to it as a half word or as a single byte, as
1651 well as instructions to refer to it as a floating point number of
1654 Even for a register that the machine can access in only one mode,
1655 the mode must always be specified.
1657 The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
1658 description, since the number of hard registers on the machine is an
1659 invariant characteristic of the machine. Note, however, that not
1660 all of the machine registers must be general registers. All the
1661 machine registers that can be used for storage of data are given
1662 hard register numbers, even those that can be used only in certain
1663 instructions or can hold only certain types of data.
1665 A hard register may be accessed in various modes throughout one
1666 function, but each pseudo register is given a natural mode
1667 and is accessed only in that mode. When it is necessary to describe
1668 an access to a pseudo register using a nonnatural mode, a @code{subreg}
1671 A @code{reg} expression with a machine mode that specifies more than
1672 one word of data may actually stand for several consecutive registers.
1673 If in addition the register number specifies a hardware register, then
1674 it actually represents several consecutive hardware registers starting
1675 with the specified one.
1677 Each pseudo register number used in a function's RTL code is
1678 represented by a unique @code{reg} expression.
1680 @findex FIRST_VIRTUAL_REGISTER
1681 @findex LAST_VIRTUAL_REGISTER
1682 Some pseudo register numbers, those within the range of
1683 @code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only
1684 appear during the RTL generation phase and are eliminated before the
1685 optimization phases. These represent locations in the stack frame that
1686 cannot be determined until RTL generation for the function has been
1687 completed. The following virtual register numbers are defined:
1690 @findex VIRTUAL_INCOMING_ARGS_REGNUM
1691 @item VIRTUAL_INCOMING_ARGS_REGNUM
1692 This points to the first word of the incoming arguments passed on the
1693 stack. Normally these arguments are placed there by the caller, but the
1694 callee may have pushed some arguments that were previously passed in
1697 @cindex @code{FIRST_PARM_OFFSET} and virtual registers
1698 @cindex @code{ARG_POINTER_REGNUM} and virtual registers
1699 When RTL generation is complete, this virtual register is replaced
1700 by the sum of the register given by @code{ARG_POINTER_REGNUM} and the
1701 value of @code{FIRST_PARM_OFFSET}.
1703 @findex VIRTUAL_STACK_VARS_REGNUM
1704 @cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers
1705 @item VIRTUAL_STACK_VARS_REGNUM
1706 If @code{FRAME_GROWS_DOWNWARD} is defined to a nonzero value, this points
1707 to immediately above the first variable on the stack. Otherwise, it points
1708 to the first variable on the stack.
1710 @cindex @code{STARTING_FRAME_OFFSET} and virtual registers
1711 @cindex @code{FRAME_POINTER_REGNUM} and virtual registers
1712 @code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the
1713 register given by @code{FRAME_POINTER_REGNUM} and the value
1714 @code{STARTING_FRAME_OFFSET}.
1716 @findex VIRTUAL_STACK_DYNAMIC_REGNUM
1717 @item VIRTUAL_STACK_DYNAMIC_REGNUM
1718 This points to the location of dynamically allocated memory on the stack
1719 immediately after the stack pointer has been adjusted by the amount of
1722 @cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers
1723 @cindex @code{STACK_POINTER_REGNUM} and virtual registers
1724 This virtual register is replaced by the sum of the register given by
1725 @code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}.
1727 @findex VIRTUAL_OUTGOING_ARGS_REGNUM
1728 @item VIRTUAL_OUTGOING_ARGS_REGNUM
1729 This points to the location in the stack at which outgoing arguments
1730 should be written when the stack is pre-pushed (arguments pushed using
1731 push insns should always use @code{STACK_POINTER_REGNUM}).
1733 @cindex @code{STACK_POINTER_OFFSET} and virtual registers
1734 This virtual register is replaced by the sum of the register given by
1735 @code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}.
1739 @item (subreg:@var{m1} @var{reg:m2} @var{bytenum})
1741 @code{subreg} expressions are used to refer to a register in a machine
1742 mode other than its natural one, or to refer to one register of
1743 a multi-part @code{reg} that actually refers to several registers.
1745 Each pseudo register has a natural mode. If it is necessary to
1746 operate on it in a different mode, the register must be
1747 enclosed in a @code{subreg}.
1749 There are currently three supported types for the first operand of a
1752 @item pseudo registers
1753 This is the most common case. Most @code{subreg}s have pseudo
1754 @code{reg}s as their first operand.
1757 @code{subreg}s of @code{mem} were common in earlier versions of GCC and
1758 are still supported. During the reload pass these are replaced by plain
1759 @code{mem}s. On machines that do not do instruction scheduling, use of
1760 @code{subreg}s of @code{mem} are still used, but this is no longer
1761 recommended. Such @code{subreg}s are considered to be
1762 @code{register_operand}s rather than @code{memory_operand}s before and
1763 during reload. Because of this, the scheduling passes cannot properly
1764 schedule instructions with @code{subreg}s of @code{mem}, so for machines
1765 that do scheduling, @code{subreg}s of @code{mem} should never be used.
1766 To support this, the combine and recog passes have explicit code to
1767 inhibit the creation of @code{subreg}s of @code{mem} when
1768 @code{INSN_SCHEDULING} is defined.
1770 The use of @code{subreg}s of @code{mem} after the reload pass is an area
1771 that is not well understood and should be avoided. There is still some
1772 code in the compiler to support this, but this code has possibly rotted.
1773 This use of @code{subreg}s is discouraged and will most likely not be
1774 supported in the future.
1776 @item hard registers
1777 It is seldom necessary to wrap hard registers in @code{subreg}s; such
1778 registers would normally reduce to a single @code{reg} rtx. This use of
1779 @code{subreg}s is discouraged and may not be supported in the future.
1783 @code{subreg}s of @code{subreg}s are not supported. Using
1784 @code{simplify_gen_subreg} is the recommended way to avoid this problem.
1786 @code{subreg}s come in two distinct flavors, each having its own
1790 @item Paradoxical subregs
1791 When @var{m1} is strictly wider than @var{m2}, the @code{subreg}
1792 expression is called @dfn{paradoxical}. The canonical test for this
1793 class of @code{subreg} is:
1796 GET_MODE_SIZE (@var{m1}) > GET_MODE_SIZE (@var{m2})
1799 Paradoxical @code{subreg}s can be used as both lvalues and rvalues.
1800 When used as an lvalue, the low-order bits of the source value
1801 are stored in @var{reg} and the high-order bits are discarded.
1802 When used as an rvalue, the low-order bits of the @code{subreg} are
1803 taken from @var{reg} while the high-order bits may or may not be
1806 The high-order bits of rvalues are in the following circumstances:
1809 @item @code{subreg}s of @code{mem}
1810 When @var{m2} is smaller than a word, the macro @code{LOAD_EXTEND_OP},
1811 can control how the high-order bits are defined.
1813 @item @code{subreg} of @code{reg}s
1814 The upper bits are defined when @code{SUBREG_PROMOTED_VAR_P} is true.
1815 @code{SUBREG_PROMOTED_UNSIGNED_P} describes what the upper bits hold.
1816 Such subregs usually represent local variables, register variables
1817 and parameter pseudo variables that have been promoted to a wider mode.
1821 @var{bytenum} is always zero for a paradoxical @code{subreg}, even on
1824 For example, the paradoxical @code{subreg}:
1827 (set (subreg:SI (reg:HI @var{x}) 0) @var{y})
1830 stores the lower 2 bytes of @var{y} in @var{x} and discards the upper
1831 2 bytes. A subsequent:
1834 (set @var{z} (subreg:SI (reg:HI @var{x}) 0))
1837 would set the lower two bytes of @var{z} to @var{y} and set the upper
1838 two bytes to an unknown value assuming @code{SUBREG_PROMOTED_VAR_P} is
1841 @item Normal subregs
1842 When @var{m1} is at least as narrow as @var{m2} the @code{subreg}
1843 expression is called @dfn{normal}.
1845 Normal @code{subreg}s restrict consideration to certain bits of
1846 @var{reg}. There are two cases. If @var{m1} is smaller than a word,
1847 the @code{subreg} refers to the least-significant part (or
1848 @dfn{lowpart}) of one word of @var{reg}. If @var{m1} is word-sized or
1849 greater, the @code{subreg} refers to one or more complete words.
1851 When used as an lvalue, @code{subreg} is a word-based accessor.
1852 Storing to a @code{subreg} modifies all the words of @var{reg} that
1853 overlap the @code{subreg}, but it leaves the other words of @var{reg}
1856 When storing to a normal @code{subreg} that is smaller than a word,
1857 the other bits of the referenced word are usually left in an undefined
1858 state. This laxity makes it easier to generate efficient code for
1859 such instructions. To represent an instruction that preserves all the
1860 bits outside of those in the @code{subreg}, use @code{strict_low_part}
1861 or @code{zero_extract} around the @code{subreg}.
1863 @var{bytenum} must identify the offset of the first byte of the
1864 @code{subreg} from the start of @var{reg}, assuming that @var{reg} is
1865 laid out in memory order. The memory order of bytes is defined by
1866 two target macros, @code{WORDS_BIG_ENDIAN} and @code{BYTES_BIG_ENDIAN}:
1870 @cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
1871 @code{WORDS_BIG_ENDIAN}, if set to 1, says that byte number zero is
1872 part of the most significant word; otherwise, it is part of the least
1876 @cindex @code{BYTES_BIG_ENDIAN}, effect on @code{subreg}
1877 @code{BYTES_BIG_ENDIAN}, if set to 1, says that byte number zero is
1878 the most significant byte within a word; otherwise, it is the least
1879 significant byte within a word.
1882 @cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg}
1883 On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with
1884 @code{WORDS_BIG_ENDIAN}. However, most parts of the compiler treat
1885 floating point values as if they had the same endianness as integer
1886 values. This works because they handle them solely as a collection of
1887 integer values, with no particular numerical value. Only real.c and
1888 the runtime libraries care about @code{FLOAT_WORDS_BIG_ENDIAN}.
1893 (subreg:HI (reg:SI @var{x}) 2)
1896 on a @code{BYTES_BIG_ENDIAN}, @samp{UNITS_PER_WORD == 4} target is the same as
1899 (subreg:HI (reg:SI @var{x}) 0)
1902 on a little-endian, @samp{UNITS_PER_WORD == 4} target. Both
1903 @code{subreg}s access the lower two bytes of register @var{x}.
1907 A @code{MODE_PARTIAL_INT} mode behaves as if it were as wide as the
1908 corresponding @code{MODE_INT} mode, except that it has an unknown
1909 number of undefined bits. For example:
1912 (subreg:PSI (reg:SI 0) 0)
1915 accesses the whole of @samp{(reg:SI 0)}, but the exact relationship
1916 between the @code{PSImode} value and the @code{SImode} value is not
1917 defined. If we assume @samp{UNITS_PER_WORD <= 4}, then the following
1921 (subreg:PSI (reg:DI 0) 0)
1922 (subreg:PSI (reg:DI 0) 4)
1925 represent independent 4-byte accesses to the two halves of
1926 @samp{(reg:DI 0)}. Both @code{subreg}s have an unknown number
1929 If @samp{UNITS_PER_WORD <= 2} then these two @code{subreg}s:
1932 (subreg:HI (reg:PSI 0) 0)
1933 (subreg:HI (reg:PSI 0) 2)
1936 represent independent 2-byte accesses that together span the whole
1937 of @samp{(reg:PSI 0)}. Storing to the first @code{subreg} does not
1938 affect the value of the second, and vice versa. @samp{(reg:PSI 0)}
1939 has an unknown number of undefined bits, so the assignment:
1942 (set (subreg:HI (reg:PSI 0) 0) (reg:HI 4))
1945 does not guarantee that @samp{(subreg:HI (reg:PSI 0) 0)} has the
1946 value @samp{(reg:HI 4)}.
1948 @cindex @code{CANNOT_CHANGE_MODE_CLASS} and subreg semantics
1949 The rules above apply to both pseudo @var{reg}s and hard @var{reg}s.
1950 If the semantics are not correct for particular combinations of
1951 @var{m1}, @var{m2} and hard @var{reg}, the target-specific code
1952 must ensure that those combinations are never used. For example:
1955 CANNOT_CHANGE_MODE_CLASS (@var{m2}, @var{m1}, @var{class})
1958 must be true for every class @var{class} that includes @var{reg}.
1962 The first operand of a @code{subreg} expression is customarily accessed
1963 with the @code{SUBREG_REG} macro and the second operand is customarily
1964 accessed with the @code{SUBREG_BYTE} macro.
1966 It has been several years since a platform in which
1967 @code{BYTES_BIG_ENDIAN} not equal to @code{WORDS_BIG_ENDIAN} has
1968 been tested. Anyone wishing to support such a platform in the future
1969 may be confronted with code rot.
1972 @cindex scratch operands
1973 @item (scratch:@var{m})
1974 This represents a scratch register that will be required for the
1975 execution of a single instruction and not used subsequently. It is
1976 converted into a @code{reg} by either the local register allocator or
1979 @code{scratch} is usually present inside a @code{clobber} operation
1980 (@pxref{Side Effects}).
1983 @cindex condition code register
1985 This refers to the machine's condition code register. It has no
1986 operands and may not have a machine mode. There are two ways to use it:
1990 To stand for a complete set of condition code flags. This is best on
1991 most machines, where each comparison sets the entire series of flags.
1993 With this technique, @code{(cc0)} may be validly used in only two
1994 contexts: as the destination of an assignment (in test and compare
1995 instructions) and in comparison operators comparing against zero
1996 (@code{const_int} with value zero; that is to say, @code{const0_rtx}).
1999 To stand for a single flag that is the result of a single condition.
2000 This is useful on machines that have only a single flag bit, and in
2001 which comparison instructions must specify the condition to test.
2003 With this technique, @code{(cc0)} may be validly used in only two
2004 contexts: as the destination of an assignment (in test and compare
2005 instructions) where the source is a comparison operator, and as the
2006 first operand of @code{if_then_else} (in a conditional branch).
2010 There is only one expression object of code @code{cc0}; it is the
2011 value of the variable @code{cc0_rtx}. Any attempt to create an
2012 expression of code @code{cc0} will return @code{cc0_rtx}.
2014 Instructions can set the condition code implicitly. On many machines,
2015 nearly all instructions set the condition code based on the value that
2016 they compute or store. It is not necessary to record these actions
2017 explicitly in the RTL because the machine description includes a
2018 prescription for recognizing the instructions that do so (by means of
2019 the macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only
2020 instructions whose sole purpose is to set the condition code, and
2021 instructions that use the condition code, need mention @code{(cc0)}.
2023 On some machines, the condition code register is given a register number
2024 and a @code{reg} is used instead of @code{(cc0)}. This is usually the
2025 preferable approach if only a small subset of instructions modify the
2026 condition code. Other machines store condition codes in general
2027 registers; in such cases a pseudo register should be used.
2029 Some machines, such as the SPARC and RS/6000, have two sets of
2030 arithmetic instructions, one that sets and one that does not set the
2031 condition code. This is best handled by normally generating the
2032 instruction that does not set the condition code, and making a pattern
2033 that both performs the arithmetic and sets the condition code register
2034 (which would not be @code{(cc0)} in this case). For examples, search
2035 for @samp{addcc} and @samp{andcc} in @file{sparc.md}.
2039 @cindex program counter
2040 This represents the machine's program counter. It has no operands and
2041 may not have a machine mode. @code{(pc)} may be validly used only in
2042 certain specific contexts in jump instructions.
2045 There is only one expression object of code @code{pc}; it is the value
2046 of the variable @code{pc_rtx}. Any attempt to create an expression of
2047 code @code{pc} will return @code{pc_rtx}.
2049 All instructions that do not jump alter the program counter implicitly
2050 by incrementing it, but there is no need to mention this in the RTL@.
2053 @item (mem:@var{m} @var{addr} @var{alias})
2054 This RTX represents a reference to main memory at an address
2055 represented by the expression @var{addr}. @var{m} specifies how large
2056 a unit of memory is accessed. @var{alias} specifies an alias set for the
2057 reference. In general two items are in different alias sets if they cannot
2058 reference the same memory address.
2060 The construct @code{(mem:BLK (scratch))} is considered to alias all
2061 other memories. Thus it may be used as a memory barrier in epilogue
2062 stack deallocation patterns.
2065 @item (concat@var{m} @var{rtx} @var{rtx})
2066 This RTX represents the concatenation of two other RTXs. This is used
2067 for complex values. It should only appear in the RTL attached to
2068 declarations and during RTL generation. It should not appear in the
2069 ordinary insn chain.
2072 @item (concatn@var{m} [@var{rtx} @dots{}])
2073 This RTX represents the concatenation of all the @var{rtx} to make a
2074 single value. Like @code{concat}, this should only appear in
2075 declarations, and not in the insn chain.
2079 @section RTL Expressions for Arithmetic
2080 @cindex arithmetic, in RTL
2081 @cindex math, in RTL
2082 @cindex RTL expressions for arithmetic
2084 Unless otherwise specified, all the operands of arithmetic expressions
2085 must be valid for mode @var{m}. An operand is valid for mode @var{m}
2086 if it has mode @var{m}, or if it is a @code{const_int} or
2087 @code{const_double} and @var{m} is a mode of class @code{MODE_INT}.
2089 For commutative binary operations, constants should be placed in the
2097 @cindex RTL addition
2098 @cindex RTL addition with signed saturation
2099 @cindex RTL addition with unsigned saturation
2100 @item (plus:@var{m} @var{x} @var{y})
2101 @itemx (ss_plus:@var{m} @var{x} @var{y})
2102 @itemx (us_plus:@var{m} @var{x} @var{y})
2104 These three expressions all represent the sum of the values
2105 represented by @var{x} and @var{y} carried out in machine mode
2106 @var{m}. They differ in their behavior on overflow of integer modes.
2107 @code{plus} wraps round modulo the width of @var{m}; @code{ss_plus}
2108 saturates at the maximum signed value representable in @var{m};
2109 @code{us_plus} saturates at the maximum unsigned value.
2111 @c ??? What happens on overflow of floating point modes?
2114 @item (lo_sum:@var{m} @var{x} @var{y})
2116 This expression represents the sum of @var{x} and the low-order bits
2117 of @var{y}. It is used with @code{high} (@pxref{Constants}) to
2118 represent the typical two-instruction sequence used in RISC machines
2119 to reference a global memory location.
2121 The number of low order bits is machine-dependent but is
2122 normally the number of bits in a @code{Pmode} item minus the number of
2123 bits set by @code{high}.
2125 @var{m} should be @code{Pmode}.
2130 @cindex RTL difference
2131 @cindex RTL subtraction
2132 @cindex RTL subtraction with signed saturation
2133 @cindex RTL subtraction with unsigned saturation
2134 @item (minus:@var{m} @var{x} @var{y})
2135 @itemx (ss_minus:@var{m} @var{x} @var{y})
2136 @itemx (us_minus:@var{m} @var{x} @var{y})
2138 These three expressions represent the result of subtracting @var{y}
2139 from @var{x}, carried out in mode @var{M}. Behavior on overflow is
2140 the same as for the three variants of @code{plus} (see above).
2143 @cindex RTL comparison
2144 @item (compare:@var{m} @var{x} @var{y})
2145 Represents the result of subtracting @var{y} from @var{x} for purposes
2146 of comparison. The result is computed without overflow, as if with
2149 Of course, machines can't really subtract with infinite precision.
2150 However, they can pretend to do so when only the sign of the result will
2151 be used, which is the case when the result is stored in the condition
2152 code. And that is the @emph{only} way this kind of expression may
2153 validly be used: as a value to be stored in the condition codes, either
2154 @code{(cc0)} or a register. @xref{Comparisons}.
2156 The mode @var{m} is not related to the modes of @var{x} and @var{y}, but
2157 instead is the mode of the condition code value. If @code{(cc0)} is
2158 used, it is @code{VOIDmode}. Otherwise it is some mode in class
2159 @code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}. If @var{m}
2160 is @code{VOIDmode} or @code{CCmode}, the operation returns sufficient
2161 information (in an unspecified format) so that any comparison operator
2162 can be applied to the result of the @code{COMPARE} operation. For other
2163 modes in class @code{MODE_CC}, the operation only returns a subset of
2166 Normally, @var{x} and @var{y} must have the same mode. Otherwise,
2167 @code{compare} is valid only if the mode of @var{x} is in class
2168 @code{MODE_INT} and @var{y} is a @code{const_int} or
2169 @code{const_double} with mode @code{VOIDmode}. The mode of @var{x}
2170 determines what mode the comparison is to be done in; thus it must not
2173 If one of the operands is a constant, it should be placed in the
2174 second operand and the comparison code adjusted as appropriate.
2176 A @code{compare} specifying two @code{VOIDmode} constants is not valid
2177 since there is no way to know in what mode the comparison is to be
2178 performed; the comparison must either be folded during the compilation
2179 or the first operand must be loaded into a register while its mode is
2186 @cindex negation with signed saturation
2187 @cindex negation with unsigned saturation
2188 @item (neg:@var{m} @var{x})
2189 @itemx (ss_neg:@var{m} @var{x})
2190 @itemx (us_neg:@var{m} @var{x})
2191 These two expressions represent the negation (subtraction from zero) of
2192 the value represented by @var{x}, carried out in mode @var{m}. They
2193 differ in the behavior on overflow of integer modes. In the case of
2194 @code{neg}, the negation of the operand may be a number not representable
2195 in mode @var{m}, in which case it is truncated to @var{m}. @code{ss_neg}
2196 and @code{us_neg} ensure that an out-of-bounds result saturates to the
2197 maximum or minimum signed or unsigned value.
2202 @cindex multiplication
2204 @cindex multiplication with signed saturation
2205 @cindex multiplication with unsigned saturation
2206 @item (mult:@var{m} @var{x} @var{y})
2207 @itemx (ss_mult:@var{m} @var{x} @var{y})
2208 @itemx (us_mult:@var{m} @var{x} @var{y})
2209 Represents the signed product of the values represented by @var{x} and
2210 @var{y} carried out in machine mode @var{m}.
2211 @code{ss_mult} and @code{us_mult} ensure that an out-of-bounds result
2212 saturates to the maximum or minimum signed or unsigned value.
2214 Some machines support a multiplication that generates a product wider
2215 than the operands. Write the pattern for this as
2218 (mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
2221 where @var{m} is wider than the modes of @var{x} and @var{y}, which need
2224 For unsigned widening multiplication, use the same idiom, but with
2225 @code{zero_extend} instead of @code{sign_extend}.
2228 @item (fma:@var{m} @var{x} @var{y} @var{z})
2229 Represents the @code{fma}, @code{fmaf}, and @code{fmal} builtin
2230 functions that do a combined multiply of @var{x} and @var{y} and then
2231 adding to@var{z} without doing an intermediate rounding step.
2236 @cindex signed division
2237 @cindex signed division with signed saturation
2239 @item (div:@var{m} @var{x} @var{y})
2240 @itemx (ss_div:@var{m} @var{x} @var{y})
2241 Represents the quotient in signed division of @var{x} by @var{y},
2242 carried out in machine mode @var{m}. If @var{m} is a floating point
2243 mode, it represents the exact quotient; otherwise, the integerized
2245 @code{ss_div} ensures that an out-of-bounds result saturates to the maximum
2246 or minimum signed value.
2248 Some machines have division instructions in which the operands and
2249 quotient widths are not all the same; you should represent
2250 such instructions using @code{truncate} and @code{sign_extend} as in,
2253 (truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
2257 @cindex unsigned division
2258 @cindex unsigned division with unsigned saturation
2260 @item (udiv:@var{m} @var{x} @var{y})
2261 @itemx (us_div:@var{m} @var{x} @var{y})
2262 Like @code{div} but represents unsigned division.
2263 @code{us_div} ensures that an out-of-bounds result saturates to the maximum
2264 or minimum unsigned value.
2270 @item (mod:@var{m} @var{x} @var{y})
2271 @itemx (umod:@var{m} @var{x} @var{y})
2272 Like @code{div} and @code{udiv} but represent the remainder instead of
2277 @cindex signed minimum
2278 @cindex signed maximum
2279 @item (smin:@var{m} @var{x} @var{y})
2280 @itemx (smax:@var{m} @var{x} @var{y})
2281 Represents the smaller (for @code{smin}) or larger (for @code{smax}) of
2282 @var{x} and @var{y}, interpreted as signed values in mode @var{m}.
2283 When used with floating point, if both operands are zeros, or if either
2284 operand is @code{NaN}, then it is unspecified which of the two operands
2285 is returned as the result.
2289 @cindex unsigned minimum and maximum
2290 @item (umin:@var{m} @var{x} @var{y})
2291 @itemx (umax:@var{m} @var{x} @var{y})
2292 Like @code{smin} and @code{smax}, but the values are interpreted as unsigned
2296 @cindex complement, bitwise
2297 @cindex bitwise complement
2298 @item (not:@var{m} @var{x})
2299 Represents the bitwise complement of the value represented by @var{x},
2300 carried out in mode @var{m}, which must be a fixed-point machine mode.
2303 @cindex logical-and, bitwise
2304 @cindex bitwise logical-and
2305 @item (and:@var{m} @var{x} @var{y})
2306 Represents the bitwise logical-and of the values represented by
2307 @var{x} and @var{y}, carried out in machine mode @var{m}, which must be
2308 a fixed-point machine mode.
2311 @cindex inclusive-or, bitwise
2312 @cindex bitwise inclusive-or
2313 @item (ior:@var{m} @var{x} @var{y})
2314 Represents the bitwise inclusive-or of the values represented by @var{x}
2315 and @var{y}, carried out in machine mode @var{m}, which must be a
2319 @cindex exclusive-or, bitwise
2320 @cindex bitwise exclusive-or
2321 @item (xor:@var{m} @var{x} @var{y})
2322 Represents the bitwise exclusive-or of the values represented by @var{x}
2323 and @var{y}, carried out in machine mode @var{m}, which must be a
2331 @cindex arithmetic shift
2332 @cindex arithmetic shift with signed saturation
2333 @cindex arithmetic shift with unsigned saturation
2334 @item (ashift:@var{m} @var{x} @var{c})
2335 @itemx (ss_ashift:@var{m} @var{x} @var{c})
2336 @itemx (us_ashift:@var{m} @var{x} @var{c})
2337 These three expressions represent the result of arithmetically shifting @var{x}
2338 left by @var{c} places. They differ in their behavior on overflow of integer
2339 modes. An @code{ashift} operation is a plain shift with no special behavior
2340 in case of a change in the sign bit; @code{ss_ashift} and @code{us_ashift}
2341 saturates to the minimum or maximum representable value if any of the bits
2342 shifted out differs from the final sign bit.
2344 @var{x} have mode @var{m}, a fixed-point machine mode. @var{c}
2345 be a fixed-point mode or be a constant with mode @code{VOIDmode}; which
2346 mode is determined by the mode called for in the machine description
2347 entry for the left-shift instruction. For example, on the VAX, the mode
2348 of @var{c} is @code{QImode} regardless of @var{m}.
2353 @item (lshiftrt:@var{m} @var{x} @var{c})
2354 @itemx (ashiftrt:@var{m} @var{x} @var{c})
2355 Like @code{ashift} but for right shift. Unlike the case for left shift,
2356 these two operations are distinct.
2362 @cindex right rotate
2363 @item (rotate:@var{m} @var{x} @var{c})
2364 @itemx (rotatert:@var{m} @var{x} @var{c})
2365 Similar but represent left and right rotate. If @var{c} is a constant,
2370 @cindex absolute value
2371 @item (abs:@var{m} @var{x})
2372 @item (ss_abs:@var{m} @var{x})
2373 Represents the absolute value of @var{x}, computed in mode @var{m}.
2374 @code{ss_abs} ensures that an out-of-bounds result saturates to the
2375 maximum signed value.
2380 @item (sqrt:@var{m} @var{x})
2381 Represents the square root of @var{x}, computed in mode @var{m}.
2382 Most often @var{m} will be a floating point mode.
2385 @item (ffs:@var{m} @var{x})
2386 Represents one plus the index of the least significant 1-bit in
2387 @var{x}, represented as an integer of mode @var{m}. (The value is
2388 zero if @var{x} is zero.) The mode of @var{x} must be @var{m}
2392 @item (clrsb:@var{m} @var{x})
2393 Represents the number of redundant leading sign bits in @var{x},
2394 represented as an integer of mode @var{m}, starting at the most
2395 significant bit position. This is one less than the number of leading
2396 sign bits (either 0 or 1), with no special cases. The mode of @var{x}
2397 must be @var{m} or @code{VOIDmode}.
2400 @item (clz:@var{m} @var{x})
2401 Represents the number of leading 0-bits in @var{x}, represented as an
2402 integer of mode @var{m}, starting at the most significant bit position.
2403 If @var{x} is zero, the value is determined by
2404 @code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}). Note that this is one of
2405 the few expressions that is not invariant under widening. The mode of
2406 @var{x} must be @var{m} or @code{VOIDmode}.
2409 @item (ctz:@var{m} @var{x})
2410 Represents the number of trailing 0-bits in @var{x}, represented as an
2411 integer of mode @var{m}, starting at the least significant bit position.
2412 If @var{x} is zero, the value is determined by
2413 @code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}). Except for this case,
2414 @code{ctz(x)} is equivalent to @code{ffs(@var{x}) - 1}. The mode of
2415 @var{x} must be @var{m} or @code{VOIDmode}.
2418 @item (popcount:@var{m} @var{x})
2419 Represents the number of 1-bits in @var{x}, represented as an integer of
2420 mode @var{m}. The mode of @var{x} must be @var{m} or @code{VOIDmode}.
2423 @item (parity:@var{m} @var{x})
2424 Represents the number of 1-bits modulo 2 in @var{x}, represented as an
2425 integer of mode @var{m}. The mode of @var{x} must be @var{m} or
2429 @item (bswap:@var{m} @var{x})
2430 Represents the value @var{x} with the order of bytes reversed, carried out
2431 in mode @var{m}, which must be a fixed-point machine mode.
2432 The mode of @var{x} must be @var{m} or @code{VOIDmode}.
2436 @section Comparison Operations
2437 @cindex RTL comparison operations
2439 Comparison operators test a relation on two operands and are considered
2440 to represent a machine-dependent nonzero value described by, but not
2441 necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
2442 if the relation holds, or zero if it does not, for comparison operators
2443 whose results have a `MODE_INT' mode,
2444 @code{FLOAT_STORE_FLAG_VALUE} (@pxref{Misc}) if the relation holds, or
2445 zero if it does not, for comparison operators that return floating-point
2446 values, and a vector of either @code{VECTOR_STORE_FLAG_VALUE} (@pxref{Misc})
2447 if the relation holds, or of zeros if it does not, for comparison operators
2448 that return vector results.
2449 The mode of the comparison operation is independent of the mode
2450 of the data being compared. If the comparison operation is being tested
2451 (e.g., the first operand of an @code{if_then_else}), the mode must be
2454 @cindex condition codes
2455 There are two ways that comparison operations may be used. The
2456 comparison operators may be used to compare the condition codes
2457 @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such
2458 a construct actually refers to the result of the preceding instruction
2459 in which the condition codes were set. The instruction setting the
2460 condition code must be adjacent to the instruction using the condition
2461 code; only @code{note} insns may separate them.
2463 Alternatively, a comparison operation may directly compare two data
2464 objects. The mode of the comparison is determined by the operands; they
2465 must both be valid for a common machine mode. A comparison with both
2466 operands constant would be invalid as the machine mode could not be
2467 deduced from it, but such a comparison should never exist in RTL due to
2470 In the example above, if @code{(cc0)} were last set to
2471 @code{(compare @var{x} @var{y})}, the comparison operation is
2472 identical to @code{(eq @var{x} @var{y})}. Usually only one style
2473 of comparisons is supported on a particular machine, but the combine
2474 pass will try to merge the operations to produce the @code{eq} shown
2475 in case it exists in the context of the particular insn involved.
2477 Inequality comparisons come in two flavors, signed and unsigned. Thus,
2478 there are distinct expression codes @code{gt} and @code{gtu} for signed and
2479 unsigned greater-than. These can produce different results for the same
2480 pair of integer values: for example, 1 is signed greater-than @minus{}1 but not
2481 unsigned greater-than, because @minus{}1 when regarded as unsigned is actually
2482 @code{0xffffffff} which is greater than 1.
2484 The signed comparisons are also used for floating point values. Floating
2485 point comparisons are distinguished by the machine modes of the operands.
2490 @item (eq:@var{m} @var{x} @var{y})
2491 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2492 are equal, otherwise 0.
2496 @item (ne:@var{m} @var{x} @var{y})
2497 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2498 are not equal, otherwise 0.
2501 @cindex greater than
2502 @item (gt:@var{m} @var{x} @var{y})
2503 @code{STORE_FLAG_VALUE} if the @var{x} is greater than @var{y}. If they
2504 are fixed-point, the comparison is done in a signed sense.
2507 @cindex greater than
2508 @cindex unsigned greater than
2509 @item (gtu:@var{m} @var{x} @var{y})
2510 Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
2515 @cindex unsigned less than
2516 @item (lt:@var{m} @var{x} @var{y})
2517 @itemx (ltu:@var{m} @var{x} @var{y})
2518 Like @code{gt} and @code{gtu} but test for ``less than''.
2521 @cindex greater than
2523 @cindex unsigned greater than
2524 @item (ge:@var{m} @var{x} @var{y})
2525 @itemx (geu:@var{m} @var{x} @var{y})
2526 Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
2529 @cindex less than or equal
2531 @cindex unsigned less than
2532 @item (le:@var{m} @var{x} @var{y})
2533 @itemx (leu:@var{m} @var{x} @var{y})
2534 Like @code{gt} and @code{gtu} but test for ``less than or equal''.
2536 @findex if_then_else
2537 @item (if_then_else @var{cond} @var{then} @var{else})
2538 This is not a comparison operation but is listed here because it is
2539 always used in conjunction with a comparison operation. To be
2540 precise, @var{cond} is a comparison expression. This expression
2541 represents a choice, according to @var{cond}, between the value
2542 represented by @var{then} and the one represented by @var{else}.
2544 On most machines, @code{if_then_else} expressions are valid only
2545 to express conditional jumps.
2548 @item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
2549 Similar to @code{if_then_else}, but more general. Each of @var{test1},
2550 @var{test2}, @dots{} is performed in turn. The result of this expression is
2551 the @var{value} corresponding to the first nonzero test, or @var{default} if
2552 none of the tests are nonzero expressions.
2554 This is currently not valid for instruction patterns and is supported only
2555 for insn attributes. @xref{Insn Attributes}.
2562 Special expression codes exist to represent bit-field instructions.
2565 @findex sign_extract
2566 @cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
2567 @item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
2568 This represents a reference to a sign-extended bit-field contained or
2569 starting in @var{loc} (a memory or register reference). The bit-field
2570 is @var{size} bits wide and starts at bit @var{pos}. The compilation
2571 option @code{BITS_BIG_ENDIAN} says which end of the memory unit
2572 @var{pos} counts from.
2574 If @var{loc} is in memory, its mode must be a single-byte integer mode.
2575 If @var{loc} is in a register, the mode to use is specified by the
2576 operand of the @code{insv} or @code{extv} pattern
2577 (@pxref{Standard Names}) and is usually a full-word integer mode,
2578 which is the default if none is specified.
2580 The mode of @var{pos} is machine-specific and is also specified
2581 in the @code{insv} or @code{extv} pattern.
2583 The mode @var{m} is the same as the mode that would be used for
2584 @var{loc} if it were a register.
2586 A @code{sign_extract} can not appear as an lvalue, or part thereof,
2589 @findex zero_extract
2590 @item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
2591 Like @code{sign_extract} but refers to an unsigned or zero-extended
2592 bit-field. The same sequence of bits are extracted, but they
2593 are filled to an entire word with zeros instead of by sign-extension.
2595 Unlike @code{sign_extract}, this type of expressions can be lvalues
2596 in RTL; they may appear on the left side of an assignment, indicating
2597 insertion of a value into the specified bit-field.
2600 @node Vector Operations
2601 @section Vector Operations
2602 @cindex vector operations
2604 All normal RTL expressions can be used with vector modes; they are
2605 interpreted as operating on each part of the vector independently.
2606 Additionally, there are a few new expressions to describe specific vector
2611 @item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items})
2612 This describes a merge operation between two vectors. The result is a vector
2613 of mode @var{m}; its elements are selected from either @var{vec1} or
2614 @var{vec2}. Which elements are selected is described by @var{items}, which
2615 is a bit mask represented by a @code{const_int}; a zero bit indicates the
2616 corresponding element in the result vector is taken from @var{vec2} while
2617 a set bit indicates it is taken from @var{vec1}.
2620 @item (vec_select:@var{m} @var{vec1} @var{selection})
2621 This describes an operation that selects parts of a vector. @var{vec1} is
2622 the source vector, and @var{selection} is a @code{parallel} that contains a
2623 @code{const_int} for each of the subparts of the result vector, giving the
2624 number of the source subpart that should be stored into it.
2625 The result mode @var{m} is either the submode for a single element of
2626 @var{vec1} (if only one subpart is selected), or another vector mode
2627 with that element submode (if multiple subparts are selected).
2630 @item (vec_concat:@var{m} @var{x1} @var{x2})
2631 Describes a vector concat operation. The result is a concatenation of the
2632 vectors or scalars @var{x1} and @var{x2}; its length is the sum of the
2633 lengths of the two inputs.
2635 @findex vec_duplicate
2636 @item (vec_duplicate:@var{m} @var{x})
2637 This operation converts a scalar into a vector or a small vector into a
2638 larger one by duplicating the input values. The output vector mode must have
2639 the same submodes as the input vector mode or the scalar modes, and the
2640 number of output parts must be an integer multiple of the number of input
2646 @section Conversions
2648 @cindex machine mode conversions
2650 All conversions between machine modes must be represented by
2651 explicit conversion operations. For example, an expression
2652 which is the sum of a byte and a full word cannot be written as
2653 @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
2654 operation requires two operands of the same machine mode.
2655 Therefore, the byte-sized operand is enclosed in a conversion
2659 (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
2662 The conversion operation is not a mere placeholder, because there
2663 may be more than one way of converting from a given starting mode
2664 to the desired final mode. The conversion operation code says how
2667 For all conversion operations, @var{x} must not be @code{VOIDmode}
2668 because the mode in which to do the conversion would not be known.
2669 The conversion must either be done at compile-time or @var{x}
2670 must be placed into a register.
2674 @item (sign_extend:@var{m} @var{x})
2675 Represents the result of sign-extending the value @var{x}
2676 to machine mode @var{m}. @var{m} must be a fixed-point mode
2677 and @var{x} a fixed-point value of a mode narrower than @var{m}.
2680 @item (zero_extend:@var{m} @var{x})
2681 Represents the result of zero-extending the value @var{x}
2682 to machine mode @var{m}. @var{m} must be a fixed-point mode
2683 and @var{x} a fixed-point value of a mode narrower than @var{m}.
2685 @findex float_extend
2686 @item (float_extend:@var{m} @var{x})
2687 Represents the result of extending the value @var{x}
2688 to machine mode @var{m}. @var{m} must be a floating point mode
2689 and @var{x} a floating point value of a mode narrower than @var{m}.
2692 @item (truncate:@var{m} @var{x})
2693 Represents the result of truncating the value @var{x}
2694 to machine mode @var{m}. @var{m} must be a fixed-point mode
2695 and @var{x} a fixed-point value of a mode wider than @var{m}.
2698 @item (ss_truncate:@var{m} @var{x})
2699 Represents the result of truncating the value @var{x}
2700 to machine mode @var{m}, using signed saturation in the case of
2701 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
2705 @item (us_truncate:@var{m} @var{x})
2706 Represents the result of truncating the value @var{x}
2707 to machine mode @var{m}, using unsigned saturation in the case of
2708 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
2711 @findex float_truncate
2712 @item (float_truncate:@var{m} @var{x})
2713 Represents the result of truncating the value @var{x}
2714 to machine mode @var{m}. @var{m} must be a floating point mode
2715 and @var{x} a floating point value of a mode wider than @var{m}.
2718 @item (float:@var{m} @var{x})
2719 Represents the result of converting fixed point value @var{x},
2720 regarded as signed, to floating point mode @var{m}.
2722 @findex unsigned_float
2723 @item (unsigned_float:@var{m} @var{x})
2724 Represents the result of converting fixed point value @var{x},
2725 regarded as unsigned, to floating point mode @var{m}.
2728 @item (fix:@var{m} @var{x})
2729 When @var{m} is a floating-point mode, represents the result of
2730 converting floating point value @var{x} (valid for mode @var{m}) to an
2731 integer, still represented in floating point mode @var{m}, by rounding
2734 When @var{m} is a fixed-point mode, represents the result of
2735 converting floating point value @var{x} to mode @var{m}, regarded as
2736 signed. How rounding is done is not specified, so this operation may
2737 be used validly in compiling C code only for integer-valued operands.
2739 @findex unsigned_fix
2740 @item (unsigned_fix:@var{m} @var{x})
2741 Represents the result of converting floating point value @var{x} to
2742 fixed point mode @var{m}, regarded as unsigned. How rounding is done
2745 @findex fract_convert
2746 @item (fract_convert:@var{m} @var{x})
2747 Represents the result of converting fixed-point value @var{x} to
2748 fixed-point mode @var{m}, signed integer value @var{x} to
2749 fixed-point mode @var{m}, floating-point value @var{x} to
2750 fixed-point mode @var{m}, fixed-point value @var{x} to integer mode @var{m}
2751 regarded as signed, or fixed-point value @var{x} to floating-point mode @var{m}.
2752 When overflows or underflows happen, the results are undefined.
2755 @item (sat_fract:@var{m} @var{x})
2756 Represents the result of converting fixed-point value @var{x} to
2757 fixed-point mode @var{m}, signed integer value @var{x} to
2758 fixed-point mode @var{m}, or floating-point value @var{x} to
2759 fixed-point mode @var{m}.
2760 When overflows or underflows happen, the results are saturated to the
2761 maximum or the minimum.
2763 @findex unsigned_fract_convert
2764 @item (unsigned_fract_convert:@var{m} @var{x})
2765 Represents the result of converting fixed-point value @var{x} to
2766 integer mode @var{m} regarded as unsigned, or unsigned integer value @var{x} to
2767 fixed-point mode @var{m}.
2768 When overflows or underflows happen, the results are undefined.
2770 @findex unsigned_sat_fract
2771 @item (unsigned_sat_fract:@var{m} @var{x})
2772 Represents the result of converting unsigned integer value @var{x} to
2773 fixed-point mode @var{m}.
2774 When overflows or underflows happen, the results are saturated to the
2775 maximum or the minimum.
2778 @node RTL Declarations
2779 @section Declarations
2780 @cindex RTL declarations
2781 @cindex declarations, RTL
2783 Declaration expression codes do not represent arithmetic operations
2784 but rather state assertions about their operands.
2787 @findex strict_low_part
2788 @cindex @code{subreg}, in @code{strict_low_part}
2789 @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
2790 This expression code is used in only one context: as the destination operand of a
2791 @code{set} expression. In addition, the operand of this expression
2792 must be a non-paradoxical @code{subreg} expression.
2794 The presence of @code{strict_low_part} says that the part of the
2795 register which is meaningful in mode @var{n}, but is not part of
2796 mode @var{m}, is not to be altered. Normally, an assignment to such
2797 a subreg is allowed to have undefined effects on the rest of the
2798 register when @var{m} is less than a word.
2802 @section Side Effect Expressions
2803 @cindex RTL side effect expressions
2805 The expression codes described so far represent values, not actions.
2806 But machine instructions never produce values; they are meaningful
2807 only for their side effects on the state of the machine. Special
2808 expression codes are used to represent side effects.
2810 The body of an instruction is always one of these side effect codes;
2811 the codes described above, which represent values, appear only as
2812 the operands of these.
2816 @item (set @var{lval} @var{x})
2817 Represents the action of storing the value of @var{x} into the place
2818 represented by @var{lval}. @var{lval} must be an expression
2819 representing a place that can be stored in: @code{reg} (or @code{subreg},
2820 @code{strict_low_part} or @code{zero_extract}), @code{mem}, @code{pc},
2821 @code{parallel}, or @code{cc0}.
2823 If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
2824 machine mode; then @var{x} must be valid for that mode.
2826 If @var{lval} is a @code{reg} whose machine mode is less than the full
2827 width of the register, then it means that the part of the register
2828 specified by the machine mode is given the specified value and the
2829 rest of the register receives an undefined value. Likewise, if
2830 @var{lval} is a @code{subreg} whose machine mode is narrower than
2831 the mode of the register, the rest of the register can be changed in
2834 If @var{lval} is a @code{strict_low_part} of a subreg, then the part
2835 of the register specified by the machine mode of the @code{subreg} is
2836 given the value @var{x} and the rest of the register is not changed.
2838 If @var{lval} is a @code{zero_extract}, then the referenced part of
2839 the bit-field (a memory or register reference) specified by the
2840 @code{zero_extract} is given the value @var{x} and the rest of the
2841 bit-field is not changed. Note that @code{sign_extract} can not
2842 appear in @var{lval}.
2844 If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
2845 be either a @code{compare} expression or a value that may have any mode.
2846 The latter case represents a ``test'' instruction. The expression
2847 @code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to
2848 @code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}.
2849 Use the former expression to save space during the compilation.
2851 If @var{lval} is a @code{parallel}, it is used to represent the case of
2852 a function returning a structure in multiple registers. Each element
2853 of the @code{parallel} is an @code{expr_list} whose first operand is a
2854 @code{reg} and whose second operand is a @code{const_int} representing the
2855 offset (in bytes) into the structure at which the data in that register
2856 corresponds. The first element may be null to indicate that the structure
2857 is also passed partly in memory.
2859 @cindex jump instructions and @code{set}
2860 @cindex @code{if_then_else} usage
2861 If @var{lval} is @code{(pc)}, we have a jump instruction, and the
2862 possibilities for @var{x} are very limited. It may be a
2863 @code{label_ref} expression (unconditional jump). It may be an
2864 @code{if_then_else} (conditional jump), in which case either the
2865 second or the third operand must be @code{(pc)} (for the case which
2866 does not jump) and the other of the two must be a @code{label_ref}
2867 (for the case which does jump). @var{x} may also be a @code{mem} or
2868 @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
2869 @code{mem}; these unusual patterns are used to represent jumps through
2872 If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of
2873 @var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
2874 valid for the mode of @var{lval}.
2878 @var{lval} is customarily accessed with the @code{SET_DEST} macro and
2879 @var{x} with the @code{SET_SRC} macro.
2883 As the sole expression in a pattern, represents a return from the
2884 current function, on machines where this can be done with one
2885 instruction, such as VAXen. On machines where a multi-instruction
2886 ``epilogue'' must be executed in order to return from the function,
2887 returning is done by jumping to a label which precedes the epilogue, and
2888 the @code{return} expression code is never used.
2890 Inside an @code{if_then_else} expression, represents the value to be
2891 placed in @code{pc} to return to the caller.
2893 Note that an insn pattern of @code{(return)} is logically equivalent to
2894 @code{(set (pc) (return))}, but the latter form is never used.
2896 @findex simple_return
2897 @item (simple_return)
2898 Like @code{(return)}, but truly represents only a function return, while
2899 @code{(return)} may represent an insn that also performs other functions
2900 of the function epilogue. Like @code{(return)}, this may also occur in
2904 @item (call @var{function} @var{nargs})
2905 Represents a function call. @var{function} is a @code{mem} expression
2906 whose address is the address of the function to be called.
2907 @var{nargs} is an expression which can be used for two purposes: on
2908 some machines it represents the number of bytes of stack argument; on
2909 others, it represents the number of argument registers.
2911 Each machine has a standard machine mode which @var{function} must
2912 have. The machine description defines macro @code{FUNCTION_MODE} to
2913 expand into the requisite mode name. The purpose of this mode is to
2914 specify what kind of addressing is allowed, on machines where the
2915 allowed kinds of addressing depend on the machine mode being
2919 @item (clobber @var{x})
2920 Represents the storing or possible storing of an unpredictable,
2921 undescribed value into @var{x}, which must be a @code{reg},
2922 @code{scratch}, @code{parallel} or @code{mem} expression.
2924 One place this is used is in string instructions that store standard
2925 values into particular hard registers. It may not be worth the
2926 trouble to describe the values that are stored, but it is essential to
2927 inform the compiler that the registers will be altered, lest it
2928 attempt to keep data in them across the string instruction.
2930 If @var{x} is @code{(mem:BLK (const_int 0))} or
2931 @code{(mem:BLK (scratch))}, it means that all memory
2932 locations must be presumed clobbered. If @var{x} is a @code{parallel},
2933 it has the same meaning as a @code{parallel} in a @code{set} expression.
2935 Note that the machine description classifies certain hard registers as
2936 ``call-clobbered''. All function call instructions are assumed by
2937 default to clobber these registers, so there is no need to use
2938 @code{clobber} expressions to indicate this fact. Also, each function
2939 call is assumed to have the potential to alter any memory location,
2940 unless the function is declared @code{const}.
2942 If the last group of expressions in a @code{parallel} are each a
2943 @code{clobber} expression whose arguments are @code{reg} or
2944 @code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
2945 phase can add the appropriate @code{clobber} expressions to an insn it
2946 has constructed when doing so will cause a pattern to be matched.
2948 This feature can be used, for example, on a machine that whose multiply
2949 and add instructions don't use an MQ register but which has an
2950 add-accumulate instruction that does clobber the MQ register. Similarly,
2951 a combined instruction might require a temporary register while the
2952 constituent instructions might not.
2954 When a @code{clobber} expression for a register appears inside a
2955 @code{parallel} with other side effects, the register allocator
2956 guarantees that the register is unoccupied both before and after that
2957 insn if it is a hard register clobber. For pseudo-register clobber,
2958 the register allocator and the reload pass do not assign the same hard
2959 register to the clobber and the input operands if there is an insn
2960 alternative containing the @samp{&} constraint (@pxref{Modifiers}) for
2961 the clobber and the hard register is in register classes of the
2962 clobber in the alternative. You can clobber either a specific hard
2963 register, a pseudo register, or a @code{scratch} expression; in the
2964 latter two cases, GCC will allocate a hard register that is available
2965 there for use as a temporary.
2967 For instructions that require a temporary register, you should use
2968 @code{scratch} instead of a pseudo-register because this will allow the
2969 combiner phase to add the @code{clobber} when required. You do this by
2970 coding (@code{clobber} (@code{match_scratch} @dots{})). If you do
2971 clobber a pseudo register, use one which appears nowhere else---generate
2972 a new one each time. Otherwise, you may confuse CSE@.
2974 There is one other known use for clobbering a pseudo register in a
2975 @code{parallel}: when one of the input operands of the insn is also
2976 clobbered by the insn. In this case, using the same pseudo register in
2977 the clobber and elsewhere in the insn produces the expected results.
2981 Represents the use of the value of @var{x}. It indicates that the
2982 value in @var{x} at this point in the program is needed, even though
2983 it may not be apparent why this is so. Therefore, the compiler will
2984 not attempt to delete previous instructions whose only effect is to
2985 store a value in @var{x}. @var{x} must be a @code{reg} expression.
2987 In some situations, it may be tempting to add a @code{use} of a
2988 register in a @code{parallel} to describe a situation where the value
2989 of a special register will modify the behavior of the instruction.
2990 A hypothetical example might be a pattern for an addition that can
2991 either wrap around or use saturating addition depending on the value
2992 of a special control register:
2995 (parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
3002 This will not work, several of the optimizers only look at expressions
3003 locally; it is very likely that if you have multiple insns with
3004 identical inputs to the @code{unspec}, they will be optimized away even
3005 if register 1 changes in between.
3007 This means that @code{use} can @emph{only} be used to describe
3008 that the register is live. You should think twice before adding
3009 @code{use} statements, more often you will want to use @code{unspec}
3010 instead. The @code{use} RTX is most commonly useful to describe that
3011 a fixed register is implicitly used in an insn. It is also safe to use
3012 in patterns where the compiler knows for other reasons that the result
3013 of the whole pattern is variable, such as @samp{movmem@var{m}} or
3014 @samp{call} patterns.
3016 During the reload phase, an insn that has a @code{use} as pattern
3017 can carry a reg_equal note. These @code{use} insns will be deleted
3018 before the reload phase exits.
3020 During the delayed branch scheduling phase, @var{x} may be an insn.
3021 This indicates that @var{x} previously was located at this place in the
3022 code and its data dependencies need to be taken into account. These
3023 @code{use} insns will be deleted before the delayed branch scheduling
3027 @item (parallel [@var{x0} @var{x1} @dots{}])
3028 Represents several side effects performed in parallel. The square
3029 brackets stand for a vector; the operand of @code{parallel} is a
3030 vector of expressions. @var{x0}, @var{x1} and so on are individual
3031 side effect expressions---expressions of code @code{set}, @code{call},
3032 @code{return}, @code{simple_return}, @code{clobber} or @code{use}.
3034 ``In parallel'' means that first all the values used in the individual
3035 side-effects are computed, and second all the actual side-effects are
3036 performed. For example,
3039 (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
3040 (set (mem:SI (reg:SI 1)) (reg:SI 1))])
3044 says unambiguously that the values of hard register 1 and the memory
3045 location addressed by it are interchanged. In both places where
3046 @code{(reg:SI 1)} appears as a memory address it refers to the value
3047 in register 1 @emph{before} the execution of the insn.
3049 It follows that it is @emph{incorrect} to use @code{parallel} and
3050 expect the result of one @code{set} to be available for the next one.
3051 For example, people sometimes attempt to represent a jump-if-zero
3052 instruction this way:
3055 (parallel [(set (cc0) (reg:SI 34))
3056 (set (pc) (if_then_else
3057 (eq (cc0) (const_int 0))
3063 But this is incorrect, because it says that the jump condition depends
3064 on the condition code value @emph{before} this instruction, not on the
3065 new value that is set by this instruction.
3067 @cindex peephole optimization, RTL representation
3068 Peephole optimization, which takes place together with final assembly
3069 code output, can produce insns whose patterns consist of a @code{parallel}
3070 whose elements are the operands needed to output the resulting
3071 assembler code---often @code{reg}, @code{mem} or constant expressions.
3072 This would not be well-formed RTL at any other stage in compilation,
3073 but it is ok then because no further optimization remains to be done.
3074 However, the definition of the macro @code{NOTICE_UPDATE_CC}, if
3075 any, must deal with such insns if you define any peephole optimizations.
3078 @item (cond_exec [@var{cond} @var{expr}])
3079 Represents a conditionally executed expression. The @var{expr} is
3080 executed only if the @var{cond} is nonzero. The @var{cond} expression
3081 must not have side-effects, but the @var{expr} may very well have
3085 @item (sequence [@var{insns} @dots{}])
3086 Represents a sequence of insns. Each of the @var{insns} that appears
3087 in the vector is suitable for appearing in the chain of insns, so it
3088 must be an @code{insn}, @code{jump_insn}, @code{call_insn},
3089 @code{code_label}, @code{barrier} or @code{note}.
3091 A @code{sequence} RTX is never placed in an actual insn during RTL
3092 generation. It represents the sequence of insns that result from a
3093 @code{define_expand} @emph{before} those insns are passed to
3094 @code{emit_insn} to insert them in the chain of insns. When actually
3095 inserted, the individual sub-insns are separated out and the
3096 @code{sequence} is forgotten.
3098 After delay-slot scheduling is completed, an insn and all the insns that
3099 reside in its delay slots are grouped together into a @code{sequence}.
3100 The insn requiring the delay slot is the first insn in the vector;
3101 subsequent insns are to be placed in the delay slot.
3103 @code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
3104 indicate that a branch insn should be used that will conditionally annul
3105 the effect of the insns in the delay slots. In such a case,
3106 @code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
3107 the branch and should be executed only if the branch is taken; otherwise
3108 the insn should be executed only if the branch is not taken.
3112 These expression codes appear in place of a side effect, as the body of
3113 an insn, though strictly speaking they do not always describe side
3118 @item (asm_input @var{s})
3119 Represents literal assembler code as described by the string @var{s}.
3122 @findex unspec_volatile
3123 @item (unspec [@var{operands} @dots{}] @var{index})
3124 @itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
3125 Represents a machine-specific operation on @var{operands}. @var{index}
3126 selects between multiple machine-specific operations.
3127 @code{unspec_volatile} is used for volatile operations and operations
3128 that may trap; @code{unspec} is used for other operations.
3130 These codes may appear inside a @code{pattern} of an
3131 insn, inside a @code{parallel}, or inside an expression.
3134 @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
3135 Represents a table of jump addresses. The vector elements @var{lr0},
3136 etc., are @code{label_ref} expressions. The mode @var{m} specifies
3137 how much space is given to each address; normally @var{m} would be
3140 @findex addr_diff_vec
3141 @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags})
3142 Represents a table of jump addresses expressed as offsets from
3143 @var{base}. The vector elements @var{lr0}, etc., are @code{label_ref}
3144 expressions and so is @var{base}. The mode @var{m} specifies how much
3145 space is given to each address-difference. @var{min} and @var{max}
3146 are set up by branch shortening and hold a label with a minimum and a
3147 maximum address, respectively. @var{flags} indicates the relative
3148 position of @var{base}, @var{min} and @var{max} to the containing insn
3149 and of @var{min} and @var{max} to @var{base}. See rtl.def for details.
3152 @item (prefetch:@var{m} @var{addr} @var{rw} @var{locality})
3153 Represents prefetch of memory at address @var{addr}.
3154 Operand @var{rw} is 1 if the prefetch is for data to be written, 0 otherwise;
3155 targets that do not support write prefetches should treat this as a normal
3157 Operand @var{locality} specifies the amount of temporal locality; 0 if there
3158 is none or 1, 2, or 3 for increasing levels of temporal locality;
3159 targets that do not support locality hints should ignore this.
3161 This insn is used to minimize cache-miss latency by moving data into a
3162 cache before it is accessed. It should use only non-faulting data prefetch
3167 @section Embedded Side-Effects on Addresses
3168 @cindex RTL preincrement
3169 @cindex RTL postincrement
3170 @cindex RTL predecrement
3171 @cindex RTL postdecrement
3173 Six special side-effect expression codes appear as memory addresses.
3177 @item (pre_dec:@var{m} @var{x})
3178 Represents the side effect of decrementing @var{x} by a standard
3179 amount and represents also the value that @var{x} has after being
3180 decremented. @var{x} must be a @code{reg} or @code{mem}, but most
3181 machines allow only a @code{reg}. @var{m} must be the machine mode
3182 for pointers on the machine in use. The amount @var{x} is decremented
3183 by is the length in bytes of the machine mode of the containing memory
3184 reference of which this expression serves as the address. Here is an
3188 (mem:DF (pre_dec:SI (reg:SI 39)))
3192 This says to decrement pseudo register 39 by the length of a @code{DFmode}
3193 value and use the result to address a @code{DFmode} value.
3196 @item (pre_inc:@var{m} @var{x})
3197 Similar, but specifies incrementing @var{x} instead of decrementing it.
3200 @item (post_dec:@var{m} @var{x})
3201 Represents the same side effect as @code{pre_dec} but a different
3202 value. The value represented here is the value @var{x} has @i{before}
3206 @item (post_inc:@var{m} @var{x})
3207 Similar, but specifies incrementing @var{x} instead of decrementing it.
3210 @item (post_modify:@var{m} @var{x} @var{y})
3212 Represents the side effect of setting @var{x} to @var{y} and
3213 represents @var{x} before @var{x} is modified. @var{x} must be a
3214 @code{reg} or @code{mem}, but most machines allow only a @code{reg}.
3215 @var{m} must be the machine mode for pointers on the machine in use.
3217 The expression @var{y} must be one of three forms:
3218 @code{(plus:@var{m} @var{x} @var{z})},
3219 @code{(minus:@var{m} @var{x} @var{z})}, or
3220 @code{(plus:@var{m} @var{x} @var{i})},
3221 where @var{z} is an index register and @var{i} is a constant.
3223 Here is an example of its use:
3226 (mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
3230 This says to modify pseudo register 42 by adding the contents of pseudo
3231 register 48 to it, after the use of what ever 42 points to.
3234 @item (pre_modify:@var{m} @var{x} @var{expr})
3235 Similar except side effects happen before the use.
3238 These embedded side effect expressions must be used with care. Instruction
3239 patterns may not use them. Until the @samp{flow} pass of the compiler,
3240 they may occur only to represent pushes onto the stack. The @samp{flow}
3241 pass finds cases where registers are incremented or decremented in one
3242 instruction and used as an address shortly before or after; these cases are
3243 then transformed to use pre- or post-increment or -decrement.
3245 If a register used as the operand of these expressions is used in
3246 another address in an insn, the original value of the register is used.
3247 Uses of the register outside of an address are not permitted within the
3248 same insn as a use in an embedded side effect expression because such
3249 insns behave differently on different machines and hence must be treated
3250 as ambiguous and disallowed.
3252 An instruction that can be represented with an embedded side effect
3253 could also be represented using @code{parallel} containing an additional
3254 @code{set} to describe how the address register is altered. This is not
3255 done because machines that allow these operations at all typically
3256 allow them wherever a memory address is called for. Describing them as
3257 additional parallel stores would require doubling the number of entries
3258 in the machine description.
3261 @section Assembler Instructions as Expressions
3262 @cindex assembler instructions in RTL
3264 @cindex @code{asm_operands}, usage
3265 The RTX code @code{asm_operands} represents a value produced by a
3266 user-specified assembler instruction. It is used to represent
3267 an @code{asm} statement with arguments. An @code{asm} statement with
3268 a single output operand, like this:
3271 asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
3275 is represented using a single @code{asm_operands} RTX which represents
3276 the value that is stored in @code{outputvar}:
3279 (set @var{rtx-for-outputvar}
3280 (asm_operands "foo %1,%2,%0" "a" 0
3281 [@var{rtx-for-addition-result} @var{rtx-for-*z}]
3282 [(asm_input:@var{m1} "g")
3283 (asm_input:@var{m2} "di")]))
3287 Here the operands of the @code{asm_operands} RTX are the assembler
3288 template string, the output-operand's constraint, the index-number of the
3289 output operand among the output operands specified, a vector of input
3290 operand RTX's, and a vector of input-operand modes and constraints. The
3291 mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
3294 When an @code{asm} statement has multiple output values, its insn has
3295 several such @code{set} RTX's inside of a @code{parallel}. Each @code{set}
3296 contains an @code{asm_operands}; all of these share the same assembler
3297 template and vectors, but each contains the constraint for the respective
3298 output operand. They are also distinguished by the output-operand index
3299 number, which is 0, 1, @dots{} for successive output operands.
3301 @node Debug Information
3302 @section Variable Location Debug Information in RTL
3303 @cindex Variable Location Debug Information in RTL
3305 Variable tracking relies on @code{MEM_EXPR} and @code{REG_EXPR}
3306 annotations to determine what user variables memory and register
3307 references refer to.
3309 Variable tracking at assignments uses these notes only when they refer
3310 to variables that live at fixed locations (e.g., addressable
3311 variables, global non-automatic variables). For variables whose
3312 location may vary, it relies on the following types of notes.
3315 @findex var_location
3316 @item (var_location:@var{mode} @var{var} @var{exp} @var{stat})
3317 Binds variable @code{var}, a tree, to value @var{exp}, an RTL
3318 expression. It appears only in @code{NOTE_INSN_VAR_LOCATION} and
3319 @code{DEBUG_INSN}s, with slightly different meanings. @var{mode}, if
3320 present, represents the mode of @var{exp}, which is useful if it is a
3321 modeless expression. @var{stat} is only meaningful in notes,
3322 indicating whether the variable is known to be initialized or
3326 @item (debug_expr:@var{mode} @var{decl})
3327 Stands for the value bound to the @code{DEBUG_EXPR_DECL} @var{decl},
3328 that points back to it, within value expressions in
3329 @code{VAR_LOCATION} nodes.
3337 The RTL representation of the code for a function is a doubly-linked
3338 chain of objects called @dfn{insns}. Insns are expressions with
3339 special codes that are used for no other purpose. Some insns are
3340 actual instructions; others represent dispatch tables for @code{switch}
3341 statements; others represent labels to jump to or various sorts of
3342 declarative information.
3344 In addition to its own specific data, each insn must have a unique
3345 id-number that distinguishes it from all other insns in the current
3346 function (after delayed branch scheduling, copies of an insn with the
3347 same id-number may be present in multiple places in a function, but
3348 these copies will always be identical and will only appear inside a
3349 @code{sequence}), and chain pointers to the preceding and following
3350 insns. These three fields occupy the same position in every insn,
3351 independent of the expression code of the insn. They could be accessed
3352 with @code{XEXP} and @code{XINT}, but instead three special macros are
3357 @item INSN_UID (@var{i})
3358 Accesses the unique id of insn @var{i}.
3361 @item PREV_INSN (@var{i})
3362 Accesses the chain pointer to the insn preceding @var{i}.
3363 If @var{i} is the first insn, this is a null pointer.
3366 @item NEXT_INSN (@var{i})
3367 Accesses the chain pointer to the insn following @var{i}.
3368 If @var{i} is the last insn, this is a null pointer.
3372 @findex get_last_insn
3373 The first insn in the chain is obtained by calling @code{get_insns}; the
3374 last insn is the result of calling @code{get_last_insn}. Within the
3375 chain delimited by these insns, the @code{NEXT_INSN} and
3376 @code{PREV_INSN} pointers must always correspond: if @var{insn} is not
3380 NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
3384 is always true and if @var{insn} is not the last insn,
3387 PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
3393 After delay slot scheduling, some of the insns in the chain might be
3394 @code{sequence} expressions, which contain a vector of insns. The value
3395 of @code{NEXT_INSN} in all but the last of these insns is the next insn
3396 in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
3397 is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
3398 which it is contained. Similar rules apply for @code{PREV_INSN}.
3400 This means that the above invariants are not necessarily true for insns
3401 inside @code{sequence} expressions. Specifically, if @var{insn} is the
3402 first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
3403 is the insn containing the @code{sequence} expression, as is the value
3404 of @code{PREV_INSN (NEXT_INSN (@var{insn}))} if @var{insn} is the last
3405 insn in the @code{sequence} expression. You can use these expressions
3406 to find the containing @code{sequence} expression.
3408 Every insn has one of the following expression codes:
3413 The expression code @code{insn} is used for instructions that do not jump
3414 and do not do function calls. @code{sequence} expressions are always
3415 contained in insns with code @code{insn} even if one of those insns
3416 should jump or do function calls.
3418 Insns with code @code{insn} have four additional fields beyond the three
3419 mandatory ones listed above. These four are described in a table below.
3423 The expression code @code{jump_insn} is used for instructions that may
3424 jump (or, more generally, may contain @code{label_ref} expressions to
3425 which @code{pc} can be set in that instruction). If there is an
3426 instruction to return from the current function, it is recorded as a
3430 @code{jump_insn} insns have the same extra fields as @code{insn} insns,
3431 accessed in the same way and in addition contain a field
3432 @code{JUMP_LABEL} which is defined once jump optimization has completed.
3434 For simple conditional and unconditional jumps, this field contains
3435 the @code{code_label} to which this insn will (possibly conditionally)
3436 branch. In a more complex jump, @code{JUMP_LABEL} records one of the
3437 labels that the insn refers to; other jump target labels are recorded
3438 as @code{REG_LABEL_TARGET} notes. The exception is @code{addr_vec}
3439 and @code{addr_diff_vec}, where @code{JUMP_LABEL} is @code{NULL_RTX}
3440 and the only way to find the labels is to scan the entire body of the
3443 Return insns count as jumps, but since they do not refer to any
3444 labels, their @code{JUMP_LABEL} is @code{NULL_RTX}.
3448 The expression code @code{call_insn} is used for instructions that may do
3449 function calls. It is important to distinguish these instructions because
3450 they imply that certain registers and memory locations may be altered
3453 @findex CALL_INSN_FUNCTION_USAGE
3454 @code{call_insn} insns have the same extra fields as @code{insn} insns,
3455 accessed in the same way and in addition contain a field
3456 @code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of
3457 @code{expr_list} expressions) containing @code{use}, @code{clobber} and
3458 sometimes @code{set} expressions that denote hard registers and
3459 @code{mem}s used or clobbered by the called function.
3461 A @code{mem} generally points to a stack slot in which arguments passed
3462 to the libcall by reference (@pxref{Register Arguments,
3463 TARGET_PASS_BY_REFERENCE}) are stored. If the argument is
3464 caller-copied (@pxref{Register Arguments, TARGET_CALLEE_COPIES}),
3465 the stack slot will be mentioned in @code{clobber} and @code{use}
3466 entries; if it's callee-copied, only a @code{use} will appear, and the
3467 @code{mem} may point to addresses that are not stack slots.
3469 Registers occurring inside a @code{clobber} in this list augment
3470 registers specified in @code{CALL_USED_REGISTERS} (@pxref{Register
3473 If the list contains a @code{set} involving two registers, it indicates
3474 that the function returns one of its arguments. Such a @code{set} may
3475 look like a no-op if the same register holds the argument and the return
3479 @findex CODE_LABEL_NUMBER
3481 A @code{code_label} insn represents a label that a jump insn can jump
3482 to. It contains two special fields of data in addition to the three
3483 standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
3484 number}, a number that identifies this label uniquely among all the
3485 labels in the compilation (not just in the current function).
3486 Ultimately, the label is represented in the assembler output as an
3487 assembler label, usually of the form @samp{L@var{n}} where @var{n} is
3490 When a @code{code_label} appears in an RTL expression, it normally
3491 appears within a @code{label_ref} which represents the address of
3492 the label, as a number.
3494 Besides as a @code{code_label}, a label can also be represented as a
3495 @code{note} of type @code{NOTE_INSN_DELETED_LABEL}.
3498 The field @code{LABEL_NUSES} is only defined once the jump optimization
3499 phase is completed. It contains the number of times this label is
3500 referenced in the current function.
3503 @findex SET_LABEL_KIND
3504 @findex LABEL_ALT_ENTRY_P
3505 @cindex alternate entry points
3506 The field @code{LABEL_KIND} differentiates four different types of
3507 labels: @code{LABEL_NORMAL}, @code{LABEL_STATIC_ENTRY},
3508 @code{LABEL_GLOBAL_ENTRY}, and @code{LABEL_WEAK_ENTRY}. The only labels
3509 that do not have type @code{LABEL_NORMAL} are @dfn{alternate entry
3510 points} to the current function. These may be static (visible only in
3511 the containing translation unit), global (exposed to all translation
3512 units), or weak (global, but can be overridden by another symbol with the
3515 Much of the compiler treats all four kinds of label identically. Some
3516 of it needs to know whether or not a label is an alternate entry point;
3517 for this purpose, the macro @code{LABEL_ALT_ENTRY_P} is provided. It is
3518 equivalent to testing whether @samp{LABEL_KIND (label) == LABEL_NORMAL}.
3519 The only place that cares about the distinction between static, global,
3520 and weak alternate entry points, besides the front-end code that creates
3521 them, is the function @code{output_alternate_entry_point}, in
3524 To set the kind of a label, use the @code{SET_LABEL_KIND} macro.
3528 Barriers are placed in the instruction stream when control cannot flow
3529 past them. They are placed after unconditional jump instructions to
3530 indicate that the jumps are unconditional and after calls to
3531 @code{volatile} functions, which do not return (e.g., @code{exit}).
3532 They contain no information beyond the three standard fields.
3535 @findex NOTE_LINE_NUMBER
3536 @findex NOTE_SOURCE_FILE
3538 @code{note} insns are used to represent additional debugging and
3539 declarative information. They contain two nonstandard fields, an
3540 integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
3541 string accessed with @code{NOTE_SOURCE_FILE}.
3543 If @code{NOTE_LINE_NUMBER} is positive, the note represents the
3544 position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
3545 that the line came from. These notes control generation of line
3546 number data in the assembler output.
3548 Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
3549 code with one of the following values (and @code{NOTE_SOURCE_FILE}
3550 must contain a null pointer):
3553 @findex NOTE_INSN_DELETED
3554 @item NOTE_INSN_DELETED
3555 Such a note is completely ignorable. Some passes of the compiler
3556 delete insns by altering them into notes of this kind.
3558 @findex NOTE_INSN_DELETED_LABEL
3559 @item NOTE_INSN_DELETED_LABEL
3560 This marks what used to be a @code{code_label}, but was not used for other
3561 purposes than taking its address and was transformed to mark that no
3564 @findex NOTE_INSN_BLOCK_BEG
3565 @findex NOTE_INSN_BLOCK_END
3566 @item NOTE_INSN_BLOCK_BEG
3567 @itemx NOTE_INSN_BLOCK_END
3568 These types of notes indicate the position of the beginning and end
3569 of a level of scoping of variable names. They control the output
3570 of debugging information.
3572 @findex NOTE_INSN_EH_REGION_BEG
3573 @findex NOTE_INSN_EH_REGION_END
3574 @item NOTE_INSN_EH_REGION_BEG
3575 @itemx NOTE_INSN_EH_REGION_END
3576 These types of notes indicate the position of the beginning and end of a
3577 level of scoping for exception handling. @code{NOTE_BLOCK_NUMBER}
3578 identifies which @code{CODE_LABEL} or @code{note} of type
3579 @code{NOTE_INSN_DELETED_LABEL} is associated with the given region.
3581 @findex NOTE_INSN_LOOP_BEG
3582 @findex NOTE_INSN_LOOP_END
3583 @item NOTE_INSN_LOOP_BEG
3584 @itemx NOTE_INSN_LOOP_END
3585 These types of notes indicate the position of the beginning and end
3586 of a @code{while} or @code{for} loop. They enable the loop optimizer
3587 to find loops quickly.
3589 @findex NOTE_INSN_LOOP_CONT
3590 @item NOTE_INSN_LOOP_CONT
3591 Appears at the place in a loop that @code{continue} statements jump to.
3593 @findex NOTE_INSN_LOOP_VTOP
3594 @item NOTE_INSN_LOOP_VTOP
3595 This note indicates the place in a loop where the exit test begins for
3596 those loops in which the exit test has been duplicated. This position
3597 becomes another virtual start of the loop when considering loop
3600 @findex NOTE_INSN_FUNCTION_BEG
3601 @item NOTE_INSN_FUNCTION_BEG
3602 Appears at the start of the function body, after the function
3605 @findex NOTE_INSN_VAR_LOCATION
3606 @findex NOTE_VAR_LOCATION
3607 @item NOTE_INSN_VAR_LOCATION
3608 This note is used to generate variable location debugging information.
3609 It indicates that the user variable in its @code{VAR_LOCATION} operand
3610 is at the location given in the RTL expression, or holds a value that
3611 can be computed by evaluating the RTL expression from that static
3612 point in the program up to the next such note for the same user
3617 These codes are printed symbolically when they appear in debugging dumps.
3620 @findex INSN_VAR_LOCATION
3622 The expression code @code{debug_insn} is used for pseudo-instructions
3623 that hold debugging information for variable tracking at assignments
3624 (see @option{-fvar-tracking-assignments} option). They are the RTL
3625 representation of @code{GIMPLE_DEBUG} statements
3626 (@ref{@code{GIMPLE_DEBUG}}), with a @code{VAR_LOCATION} operand that
3627 binds a user variable tree to an RTL representation of the
3628 @code{value} in the corresponding statement. A @code{DEBUG_EXPR} in
3629 it stands for the value bound to the corresponding
3630 @code{DEBUG_EXPR_DECL}.
3632 Throughout optimization passes, binding information is kept in
3633 pseudo-instruction form, so that, unlike notes, it gets the same
3634 treatment and adjustments that regular instructions would. It is the
3635 variable tracking pass that turns these pseudo-instructions into var
3636 location notes, analyzing control flow, value equivalences and changes
3637 to registers and memory referenced in value expressions, propagating
3638 the values of debug temporaries and determining expressions that can
3639 be used to compute the value of each user variable at as many points
3640 (ranges, actually) in the program as possible.
3642 Unlike @code{NOTE_INSN_VAR_LOCATION}, the value expression in an
3643 @code{INSN_VAR_LOCATION} denotes a value at that specific point in the
3644 program, rather than an expression that can be evaluated at any later
3645 point before an overriding @code{VAR_LOCATION} is encountered. E.g.,
3646 if a user variable is bound to a @code{REG} and then a subsequent insn
3647 modifies the @code{REG}, the note location would keep mapping the user
3648 variable to the register across the insn, whereas the insn location
3649 would keep the variable bound to the value, so that the variable
3650 tracking pass would emit another location note for the variable at the
3651 point in which the register is modified.
3655 @cindex @code{TImode}, in @code{insn}
3656 @cindex @code{HImode}, in @code{insn}
3657 @cindex @code{QImode}, in @code{insn}
3658 The machine mode of an insn is normally @code{VOIDmode}, but some
3659 phases use the mode for various purposes.
3661 The common subexpression elimination pass sets the mode of an insn to
3662 @code{QImode} when it is the first insn in a block that has already
3665 The second Haifa scheduling pass, for targets that can multiple issue,
3666 sets the mode of an insn to @code{TImode} when it is believed that the
3667 instruction begins an issue group. That is, when the instruction
3668 cannot issue simultaneously with the previous. This may be relied on
3669 by later passes, in particular machine-dependent reorg.
3671 Here is a table of the extra fields of @code{insn}, @code{jump_insn}
3672 and @code{call_insn} insns:
3676 @item PATTERN (@var{i})
3677 An expression for the side effect performed by this insn. This must
3678 be one of the following codes: @code{set}, @code{call}, @code{use},
3679 @code{clobber}, @code{return}, @code{simple_return}, @code{asm_input},
3680 @code{asm_output}, @code{addr_vec}, @code{addr_diff_vec},
3681 @code{trap_if}, @code{unspec}, @code{unspec_volatile},
3682 @code{parallel}, @code{cond_exec}, or @code{sequence}. If it is a
3683 @code{parallel}, each element of the @code{parallel} must be one these
3684 codes, except that @code{parallel} expressions cannot be nested and
3685 @code{addr_vec} and @code{addr_diff_vec} are not permitted inside a
3686 @code{parallel} expression.
3689 @item INSN_CODE (@var{i})
3690 An integer that says which pattern in the machine description matches
3691 this insn, or @minus{}1 if the matching has not yet been attempted.
3693 Such matching is never attempted and this field remains @minus{}1 on an insn
3694 whose pattern consists of a single @code{use}, @code{clobber},
3695 @code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.
3697 @findex asm_noperands
3698 Matching is also never attempted on insns that result from an @code{asm}
3699 statement. These contain at least one @code{asm_operands} expression.
3700 The function @code{asm_noperands} returns a non-negative value for
3703 In the debugging output, this field is printed as a number followed by
3704 a symbolic representation that locates the pattern in the @file{md}
3705 file as some small positive or negative offset from a named pattern.
3708 @item LOG_LINKS (@var{i})
3709 A list (chain of @code{insn_list} expressions) giving information about
3710 dependencies between instructions within a basic block. Neither a jump
3711 nor a label may come between the related insns. These are only used by
3712 the schedulers and by combine. This is a deprecated data structure.
3713 Def-use and use-def chains are now preferred.
3716 @item REG_NOTES (@var{i})
3717 A list (chain of @code{expr_list} and @code{insn_list} expressions)
3718 giving miscellaneous information about the insn. It is often
3719 information pertaining to the registers used in this insn.
3722 The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
3723 expressions. Each of these has two operands: the first is an insn,
3724 and the second is another @code{insn_list} expression (the next one in
3725 the chain). The last @code{insn_list} in the chain has a null pointer
3726 as second operand. The significant thing about the chain is which
3727 insns appear in it (as first operands of @code{insn_list}
3728 expressions). Their order is not significant.
3730 This list is originally set up by the flow analysis pass; it is a null
3731 pointer until then. Flow only adds links for those data dependencies
3732 which can be used for instruction combination. For each insn, the flow
3733 analysis pass adds a link to insns which store into registers values
3734 that are used for the first time in this insn.
3736 The @code{REG_NOTES} field of an insn is a chain similar to the
3737 @code{LOG_LINKS} field but it includes @code{expr_list} expressions in
3738 addition to @code{insn_list} expressions. There are several kinds of
3739 register notes, which are distinguished by the machine mode, which in a
3740 register note is really understood as being an @code{enum reg_note}.
3741 The first operand @var{op} of the note is data whose meaning depends on
3744 @findex REG_NOTE_KIND
3745 @findex PUT_REG_NOTE_KIND
3746 The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of
3747 register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND
3748 (@var{x}, @var{newkind})} sets the register note type of @var{x} to be
3751 Register notes are of three classes: They may say something about an
3752 input to an insn, they may say something about an output of an insn, or
3753 they may create a linkage between two insns. There are also a set
3754 of values that are only used in @code{LOG_LINKS}.
3756 These register notes annotate inputs to an insn:
3761 The value in @var{op} dies in this insn; that is to say, altering the
3762 value immediately after this insn would not affect the future behavior
3765 It does not follow that the register @var{op} has no useful value after
3766 this insn since @var{op} is not necessarily modified by this insn.
3767 Rather, no subsequent instruction uses the contents of @var{op}.
3771 The register @var{op} being set by this insn will not be used in a
3772 subsequent insn. This differs from a @code{REG_DEAD} note, which
3773 indicates that the value in an input will not be used subsequently.
3774 These two notes are independent; both may be present for the same
3779 The register @var{op} is incremented (or decremented; at this level
3780 there is no distinction) by an embedded side effect inside this insn.
3781 This means it appears in a @code{post_inc}, @code{pre_inc},
3782 @code{post_dec} or @code{pre_dec} expression.
3786 The register @var{op} is known to have a nonnegative value when this
3787 insn is reached. This is used so that decrement and branch until zero
3788 instructions, such as the m68k dbra, can be matched.
3790 The @code{REG_NONNEG} note is added to insns only if the machine
3791 description has a @samp{decrement_and_branch_until_zero} pattern.
3793 @findex REG_LABEL_OPERAND
3794 @item REG_LABEL_OPERAND
3795 This insn uses @var{op}, a @code{code_label} or a @code{note} of type
3796 @code{NOTE_INSN_DELETED_LABEL}, but is not a @code{jump_insn}, or it
3797 is a @code{jump_insn} that refers to the operand as an ordinary
3798 operand. The label may still eventually be a jump target, but if so
3799 in an indirect jump in a subsequent insn. The presence of this note
3800 allows jump optimization to be aware that @var{op} is, in fact, being
3801 used, and flow optimization to build an accurate flow graph.
3803 @findex REG_LABEL_TARGET
3804 @item REG_LABEL_TARGET
3805 This insn is a @code{jump_insn} but not an @code{addr_vec} or
3806 @code{addr_diff_vec}. It uses @var{op}, a @code{code_label} as a
3807 direct or indirect jump target. Its purpose is similar to that of
3808 @code{REG_LABEL_OPERAND}. This note is only present if the insn has
3809 multiple targets; the last label in the insn (in the highest numbered
3810 insn-field) goes into the @code{JUMP_LABEL} field and does not have a
3811 @code{REG_LABEL_TARGET} note. @xref{Insns, JUMP_LABEL}.
3813 @findex REG_CROSSING_JUMP
3814 @item REG_CROSSING_JUMP
3815 This insn is a branching instruction (either an unconditional jump or
3816 an indirect jump) which crosses between hot and cold sections, which
3817 could potentially be very far apart in the executable. The presence
3818 of this note indicates to other optimizations that this branching
3819 instruction should not be ``collapsed'' into a simpler branching
3820 construct. It is used when the optimization to partition basic blocks
3821 into hot and cold sections is turned on.
3825 Appears attached to each @code{CALL_INSN} to @code{setjmp} or a
3829 The following notes describe attributes of outputs of an insn:
3836 This note is only valid on an insn that sets only one register and
3837 indicates that that register will be equal to @var{op} at run time; the
3838 scope of this equivalence differs between the two types of notes. The
3839 value which the insn explicitly copies into the register may look
3840 different from @var{op}, but they will be equal at run time. If the
3841 output of the single @code{set} is a @code{strict_low_part} expression,
3842 the note refers to the register that is contained in @code{SUBREG_REG}
3843 of the @code{subreg} expression.
3845 For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout
3846 the entire function, and could validly be replaced in all its
3847 occurrences by @var{op}. (``Validly'' here refers to the data flow of
3848 the program; simple replacement may make some insns invalid.) For
3849 example, when a constant is loaded into a register that is never
3850 assigned any other value, this kind of note is used.
3852 When a parameter is copied into a pseudo-register at entry to a function,
3853 a note of this kind records that the register is equivalent to the stack
3854 slot where the parameter was passed. Although in this case the register
3855 may be set by other insns, it is still valid to replace the register
3856 by the stack slot throughout the function.
3858 A @code{REG_EQUIV} note is also used on an instruction which copies a
3859 register parameter into a pseudo-register at entry to a function, if
3860 there is a stack slot where that parameter could be stored. Although
3861 other insns may set the pseudo-register, it is valid for the compiler to
3862 replace the pseudo-register by stack slot throughout the function,
3863 provided the compiler ensures that the stack slot is properly
3864 initialized by making the replacement in the initial copy instruction as
3865 well. This is used on machines for which the calling convention
3866 allocates stack space for register parameters. See
3867 @code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}.
3869 In the case of @code{REG_EQUAL}, the register that is set by this insn
3870 will be equal to @var{op} at run time at the end of this insn but not
3871 necessarily elsewhere in the function. In this case, @var{op}
3872 is typically an arithmetic expression. For example, when a sequence of
3873 insns such as a library call is used to perform an arithmetic operation,
3874 this kind of note is attached to the insn that produces or copies the
3877 These two notes are used in different ways by the compiler passes.
3878 @code{REG_EQUAL} is used by passes prior to register allocation (such as
3879 common subexpression elimination and loop optimization) to tell them how
3880 to think of that value. @code{REG_EQUIV} notes are used by register
3881 allocation to indicate that there is an available substitute expression
3882 (either a constant or a @code{mem} expression for the location of a
3883 parameter on the stack) that may be used in place of a register if
3884 insufficient registers are available.
3886 Except for stack homes for parameters, which are indicated by a
3887 @code{REG_EQUIV} note and are not useful to the early optimization
3888 passes and pseudo registers that are equivalent to a memory location
3889 throughout their entire life, which is not detected until later in
3890 the compilation, all equivalences are initially indicated by an attached
3891 @code{REG_EQUAL} note. In the early stages of register allocation, a
3892 @code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if
3893 @var{op} is a constant and the insn represents the only set of its
3894 destination register.
3896 Thus, compiler passes prior to register allocation need only check for
3897 @code{REG_EQUAL} notes and passes subsequent to register allocation
3898 need only check for @code{REG_EQUIV} notes.
3901 These notes describe linkages between insns. They occur in pairs: one
3902 insn has one of a pair of notes that points to a second insn, which has
3903 the inverse note pointing back to the first insn.
3906 @findex REG_CC_SETTER
3910 On machines that use @code{cc0}, the insns which set and use @code{cc0}
3911 set and use @code{cc0} are adjacent. However, when branch delay slot
3912 filling is done, this may no longer be true. In this case a
3913 @code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to
3914 point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will
3915 be placed on the insn using @code{cc0} to point to the insn setting
3919 These values are only used in the @code{LOG_LINKS} field, and indicate
3920 the type of dependency that each link represents. Links which indicate
3921 a data dependence (a read after write dependence) do not use any code,
3922 they simply have mode @code{VOIDmode}, and are printed without any
3926 @findex REG_DEP_TRUE
3928 This indicates a true dependence (a read after write dependence).
3930 @findex REG_DEP_OUTPUT
3931 @item REG_DEP_OUTPUT
3932 This indicates an output dependence (a write after write dependence).
3934 @findex REG_DEP_ANTI
3936 This indicates an anti dependence (a write after read dependence).
3940 These notes describe information gathered from gcov profile data. They
3941 are stored in the @code{REG_NOTES} field of an insn as an
3947 This is used to specify the ratio of branches to non-branches of a
3948 branch insn according to the profile data. The value is stored as a
3949 value between 0 and REG_BR_PROB_BASE; larger values indicate a higher
3950 probability that the branch will be taken.
3954 These notes are found in JUMP insns after delayed branch scheduling
3955 has taken place. They indicate both the direction and the likelihood
3956 of the JUMP@. The format is a bitmask of ATTR_FLAG_* values.
3958 @findex REG_FRAME_RELATED_EXPR
3959 @item REG_FRAME_RELATED_EXPR
3960 This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression
3961 is used in place of the actual insn pattern. This is done in cases where
3962 the pattern is either complex or misleading.
3965 For convenience, the machine mode in an @code{insn_list} or
3966 @code{expr_list} is printed using these symbolic codes in debugging dumps.
3970 The only difference between the expression codes @code{insn_list} and
3971 @code{expr_list} is that the first operand of an @code{insn_list} is
3972 assumed to be an insn and is printed in debugging dumps as the insn's
3973 unique id; the first operand of an @code{expr_list} is printed in the
3974 ordinary way as an expression.
3977 @section RTL Representation of Function-Call Insns
3978 @cindex calling functions in RTL
3979 @cindex RTL function-call insns
3980 @cindex function-call insns
3982 Insns that call subroutines have the RTL expression code @code{call_insn}.
3983 These insns must satisfy special rules, and their bodies must use a special
3984 RTL expression code, @code{call}.
3986 @cindex @code{call} usage
3987 A @code{call} expression has two operands, as follows:
3990 (call (mem:@var{fm} @var{addr}) @var{nbytes})
3994 Here @var{nbytes} is an operand that represents the number of bytes of
3995 argument data being passed to the subroutine, @var{fm} is a machine mode
3996 (which must equal as the definition of the @code{FUNCTION_MODE} macro in
3997 the machine description) and @var{addr} represents the address of the
4000 For a subroutine that returns no value, the @code{call} expression as
4001 shown above is the entire body of the insn, except that the insn might
4002 also contain @code{use} or @code{clobber} expressions.
4004 @cindex @code{BLKmode}, and function return values
4005 For a subroutine that returns a value whose mode is not @code{BLKmode},
4006 the value is returned in a hard register. If this register's number is
4007 @var{r}, then the body of the call insn looks like this:
4010 (set (reg:@var{m} @var{r})
4011 (call (mem:@var{fm} @var{addr}) @var{nbytes}))
4015 This RTL expression makes it clear (to the optimizer passes) that the
4016 appropriate register receives a useful value in this insn.
4018 When a subroutine returns a @code{BLKmode} value, it is handled by
4019 passing to the subroutine the address of a place to store the value.
4020 So the call insn itself does not ``return'' any value, and it has the
4021 same RTL form as a call that returns nothing.
4023 On some machines, the call instruction itself clobbers some register,
4024 for example to contain the return address. @code{call_insn} insns
4025 on these machines should have a body which is a @code{parallel}
4026 that contains both the @code{call} expression and @code{clobber}
4027 expressions that indicate which registers are destroyed. Similarly,
4028 if the call instruction requires some register other than the stack
4029 pointer that is not explicitly mentioned in its RTL, a @code{use}
4030 subexpression should mention that register.
4032 Functions that are called are assumed to modify all registers listed in
4033 the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register
4034 Basics}) and, with the exception of @code{const} functions and library
4035 calls, to modify all of memory.
4037 Insns containing just @code{use} expressions directly precede the
4038 @code{call_insn} insn to indicate which registers contain inputs to the
4039 function. Similarly, if registers other than those in
4040 @code{CALL_USED_REGISTERS} are clobbered by the called function, insns
4041 containing a single @code{clobber} follow immediately after the call to
4042 indicate which registers.
4045 @section Structure Sharing Assumptions
4046 @cindex sharing of RTL components
4047 @cindex RTL structure sharing assumptions
4049 The compiler assumes that certain kinds of RTL expressions are unique;
4050 there do not exist two distinct objects representing the same value.
4051 In other cases, it makes an opposite assumption: that no RTL expression
4052 object of a certain kind appears in more than one place in the
4053 containing structure.
4055 These assumptions refer to a single function; except for the RTL
4056 objects that describe global variables and external functions,
4057 and a few standard objects such as small integer constants,
4058 no RTL objects are common to two functions.
4061 @cindex @code{reg}, RTL sharing
4063 Each pseudo-register has only a single @code{reg} object to represent it,
4064 and therefore only a single machine mode.
4066 @cindex symbolic label
4067 @cindex @code{symbol_ref}, RTL sharing
4069 For any symbolic label, there is only one @code{symbol_ref} object
4072 @cindex @code{const_int}, RTL sharing
4074 All @code{const_int} expressions with equal values are shared.
4076 @cindex @code{pc}, RTL sharing
4078 There is only one @code{pc} expression.
4080 @cindex @code{cc0}, RTL sharing
4082 There is only one @code{cc0} expression.
4084 @cindex @code{const_double}, RTL sharing
4086 There is only one @code{const_double} expression with value 0 for
4087 each floating point mode. Likewise for values 1 and 2.
4089 @cindex @code{const_vector}, RTL sharing
4091 There is only one @code{const_vector} expression with value 0 for
4092 each vector mode, be it an integer or a double constant vector.
4094 @cindex @code{label_ref}, RTL sharing
4095 @cindex @code{scratch}, RTL sharing
4097 No @code{label_ref} or @code{scratch} appears in more than one place in
4098 the RTL structure; in other words, it is safe to do a tree-walk of all
4099 the insns in the function and assume that each time a @code{label_ref}
4100 or @code{scratch} is seen it is distinct from all others that are seen.
4102 @cindex @code{mem}, RTL sharing
4104 Only one @code{mem} object is normally created for each static
4105 variable or stack slot, so these objects are frequently shared in all
4106 the places they appear. However, separate but equal objects for these
4107 variables are occasionally made.
4109 @cindex @code{asm_operands}, RTL sharing
4111 When a single @code{asm} statement has multiple output operands, a
4112 distinct @code{asm_operands} expression is made for each output operand.
4113 However, these all share the vector which contains the sequence of input
4114 operands. This sharing is used later on to test whether two
4115 @code{asm_operands} expressions come from the same statement, so all
4116 optimizations must carefully preserve the sharing if they copy the
4120 No RTL object appears in more than one place in the RTL structure
4121 except as described above. Many passes of the compiler rely on this
4122 by assuming that they can modify RTL objects in place without unwanted
4123 side-effects on other insns.
4125 @findex unshare_all_rtl
4127 During initial RTL generation, shared structure is freely introduced.
4128 After all the RTL for a function has been generated, all shared
4129 structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
4130 after which the above rules are guaranteed to be followed.
4132 @findex copy_rtx_if_shared
4134 During the combiner pass, shared structure within an insn can exist
4135 temporarily. However, the shared structure is copied before the
4136 combiner is finished with the insn. This is done by calling
4137 @code{copy_rtx_if_shared}, which is a subroutine of
4138 @code{unshare_all_rtl}.
4142 @section Reading RTL
4144 To read an RTL object from a file, call @code{read_rtx}. It takes one
4145 argument, a stdio stream, and returns a single RTL object. This routine
4146 is defined in @file{read-rtl.c}. It is not available in the compiler
4147 itself, only the various programs that generate the compiler back end
4148 from the machine description.
4150 People frequently have the idea of using RTL stored as text in a file as
4151 an interface between a language front end and the bulk of GCC@. This
4152 idea is not feasible.
4154 GCC was designed to use RTL internally only. Correct RTL for a given
4155 program is very dependent on the particular target machine. And the RTL
4156 does not contain all the information about the program.
4158 The proper way to interface GCC to a new language front end is with
4159 the ``tree'' data structure, described in the files @file{tree.h} and
4160 @file{tree.def}. The documentation for this structure (@pxref{GENERIC})