1 @c Copyright (C) 1988-2017 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
6 @chapter RTL Representation
7 @cindex RTL representation
8 @cindex representation of RTL
9 @cindex Register Transfer Language (RTL)
11 The last part of the compiler work is done on a low-level intermediate
12 representation called Register Transfer Language. In this language, the
13 instructions to be output are described, pretty much one by one, in an
14 algebraic form that describes what the instruction does.
16 RTL is inspired by Lisp lists. It has both an internal form, made up of
17 structures that point at other structures, and a textual form that is used
18 in the machine description and in printed debugging dumps. The textual
19 form uses nested parentheses to indicate the pointers in the internal form.
22 * RTL Objects:: Expressions vs vectors vs strings vs integers.
23 * RTL Classes:: Categories of RTL expression objects, and their structure.
24 * Accessors:: Macros to access expression operands or vector elts.
25 * Special Accessors:: Macros to access specific annotations on RTL.
26 * Flags:: Other flags in an RTL expression.
27 * Machine Modes:: Describing the size and format of a datum.
28 * Constants:: Expressions with constant values.
29 * Regs and Memory:: Expressions representing register contents or memory.
30 * Arithmetic:: Expressions representing arithmetic on other expressions.
31 * Comparisons:: Expressions representing comparison of expressions.
32 * Bit-Fields:: Expressions representing bit-fields in memory or reg.
33 * Vector Operations:: Expressions involving vector datatypes.
34 * Conversions:: Extending, truncating, floating or fixing.
35 * RTL Declarations:: Declaring volatility, constancy, etc.
36 * Side Effects:: Expressions for storing in registers, etc.
37 * Incdec:: Embedded side-effects for autoincrement addressing.
38 * Assembler:: Representing @code{asm} with operands.
39 * Debug Information:: Expressions representing debugging information.
40 * Insns:: Expression types for entire insns.
41 * Calls:: RTL representation of function call insns.
42 * Sharing:: Some expressions are unique; others *must* be copied.
43 * Reading RTL:: Reading textual RTL from a file.
47 @section RTL Object Types
48 @cindex RTL object types
53 @cindex RTL expression
55 RTL uses five kinds of objects: expressions, integers, wide integers,
56 strings and vectors. Expressions are the most important ones. An RTL
57 expression (``RTX'', for short) is a C structure, but it is usually
58 referred to with a pointer; a type that is given the typedef name
61 An integer is simply an @code{int}; their written form uses decimal
62 digits. A wide integer is an integral object whose type is
63 @code{HOST_WIDE_INT}; their written form uses decimal digits.
65 A string is a sequence of characters. In core it is represented as a
66 @code{char *} in usual C fashion, and it is written in C syntax as well.
67 However, strings in RTL may never be null. If you write an empty string in
68 a machine description, it is represented in core as a null pointer rather
69 than as a pointer to a null character. In certain contexts, these null
70 pointers instead of strings are valid. Within RTL code, strings are most
71 commonly found inside @code{symbol_ref} expressions, but they appear in
72 other contexts in the RTL expressions that make up machine descriptions.
74 In a machine description, strings are normally written with double
75 quotes, as you would in C@. However, strings in machine descriptions may
76 extend over many lines, which is invalid C, and adjacent string
77 constants are not concatenated as they are in C@. Any string constant
78 may be surrounded with a single set of parentheses. Sometimes this
79 makes the machine description easier to read.
81 There is also a special syntax for strings, which can be useful when C
82 code is embedded in a machine description. Wherever a string can
83 appear, it is also valid to write a C-style brace block. The entire
84 brace block, including the outermost pair of braces, is considered to be
85 the string constant. Double quote characters inside the braces are not
86 special. Therefore, if you write string constants in the C code, you
87 need not escape each quote character with a backslash.
89 A vector contains an arbitrary number of pointers to expressions. The
90 number of elements in the vector is explicitly present in the vector.
91 The written form of a vector consists of square brackets
92 (@samp{[@dots{}]}) surrounding the elements, in sequence and with
93 whitespace separating them. Vectors of length zero are not created;
94 null pointers are used instead.
96 @cindex expression codes
97 @cindex codes, RTL expression
100 Expressions are classified by @dfn{expression codes} (also called RTX
101 codes). The expression code is a name defined in @file{rtl.def}, which is
102 also (in uppercase) a C enumeration constant. The possible expression
103 codes and their meanings are machine-independent. The code of an RTX can
104 be extracted with the macro @code{GET_CODE (@var{x})} and altered with
105 @code{PUT_CODE (@var{x}, @var{newcode})}.
107 The expression code determines how many operands the expression contains,
108 and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell
109 by looking at an operand what kind of object it is. Instead, you must know
110 from its context---from the expression code of the containing expression.
111 For example, in an expression of code @code{subreg}, the first operand is
112 to be regarded as an expression and the second operand as a polynomial
113 integer. In an expression of code @code{plus}, there are two operands,
114 both of which are to be regarded as expressions. In a @code{symbol_ref}
115 expression, there is one operand, which is to be regarded as a string.
117 Expressions are written as parentheses containing the name of the
118 expression type, its flags and machine mode if any, and then the operands
119 of the expression (separated by spaces).
121 Expression code names in the @samp{md} file are written in lowercase,
122 but when they appear in C code they are written in uppercase. In this
123 manual, they are shown as follows: @code{const_int}.
127 In a few contexts a null pointer is valid where an expression is normally
128 wanted. The written form of this is @code{(nil)}.
131 @section RTL Classes and Formats
133 @cindex classes of RTX codes
134 @cindex RTX codes, classes of
135 @findex GET_RTX_CLASS
137 The various expression codes are divided into several @dfn{classes},
138 which are represented by single characters. You can determine the class
139 of an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}.
140 Currently, @file{rtl.def} defines these classes:
144 An RTX code that represents an actual object, such as a register
145 (@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}).
146 @code{LO_SUM}) is also included; instead, @code{SUBREG} and
147 @code{STRICT_LOW_PART} are not in this class, but in class @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
196 @code{POST_INC}. @samp{XEXP (@var{x}, 0)} gives the auto-modified
200 All other RTX codes. This category includes the remaining codes used
201 only in machine descriptions (@code{DEFINE_*}, etc.). It also includes
202 all the codes describing side effects (@code{SET}, @code{USE},
203 @code{CLOBBER}, etc.) and the non-insns that may appear on an insn
204 chain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}.
205 @code{SUBREG} is also part of this class.
209 For each expression code, @file{rtl.def} specifies the number of
210 contained objects and their kinds using a sequence of characters
211 called the @dfn{format} of the expression code. For example,
212 the format of @code{subreg} is @samp{ep}.
214 @cindex RTL format characters
215 These are the most commonly used format characters:
219 An expression (actually a pointer to an expression).
231 A vector of expressions.
234 A few other format characters are used occasionally:
238 @samp{u} is equivalent to @samp{e} except that it is printed differently
239 in debugging dumps. It is used for pointers to insns.
242 @samp{n} is equivalent to @samp{i} except that it is printed differently
243 in debugging dumps. It is used for the line number or code number of a
247 @samp{S} indicates a string which is optional. In the RTL objects in
248 core, @samp{S} is equivalent to @samp{s}, but when the object is read,
249 from an @samp{md} file, the string value of this operand may be omitted.
250 An omitted string is taken to be the null string.
253 @samp{V} indicates a vector which is optional. In the RTL objects in
254 core, @samp{V} is equivalent to @samp{E}, but when the object is read
255 from an @samp{md} file, the vector value of this operand may be omitted.
256 An omitted vector is effectively the same as a vector of no elements.
259 @samp{B} indicates a pointer to basic block structure.
262 A polynomial integer. At present this is used only for @code{SUBREG_BYTE}.
265 @samp{0} means a slot whose contents do not fit any normal category.
266 @samp{0} slots are not printed at all in dumps, and are often used in
267 special ways by small parts of the compiler.
270 There are macros to get the number of operands and the format
271 of an expression code:
274 @findex GET_RTX_LENGTH
275 @item GET_RTX_LENGTH (@var{code})
276 Number of operands of an RTX of code @var{code}.
278 @findex GET_RTX_FORMAT
279 @item GET_RTX_FORMAT (@var{code})
280 The format of an RTX of code @var{code}, as a C string.
283 Some classes of RTX codes always have the same format. For example, it
284 is safe to assume that all comparison operations have format @code{ee}.
288 All codes of this class have format @code{e}.
293 All codes of these classes have format @code{ee}.
297 All codes of these classes have format @code{eee}.
300 All codes of this class have formats that begin with @code{iuueiee}.
301 @xref{Insns}. Note that not all RTL objects linked onto an insn chain
302 are of class @code{i}.
307 You can make no assumptions about the format of these codes.
311 @section Access to Operands
313 @cindex access to operands
314 @cindex operand access
320 Operands of expressions are accessed using the macros @code{XEXP},
321 @code{XINT}, @code{XWINT} and @code{XSTR}. Each of these macros takes
322 two arguments: an expression-pointer (RTX) and an operand number
323 (counting from zero). Thus,
330 accesses operand 2 of expression @var{x}, as an expression.
337 accesses the same operand as an integer. @code{XSTR}, used in the same
338 fashion, would access it as a string.
340 Any operand can be accessed as an integer, as an expression or as a string.
341 You must choose the correct method of access for the kind of value actually
342 stored in the operand. You would do this based on the expression code of
343 the containing expression. That is also how you would know how many
346 For example, if @var{x} is an @code{int_list} expression, you know that it has
347 two operands which can be correctly accessed as @code{XINT (@var{x}, 0)}
348 and @code{XEXP (@var{x}, 1)}. Incorrect accesses like
349 @code{XEXP (@var{x}, 0)} and @code{XINT (@var{x}, 1)} would compile,
350 but would trigger an internal compiler error when rtl checking is enabled.
351 Nothing stops you from writing @code{XEXP (@var{x}, 28)} either, but
352 this will access memory past the end of the expression with
353 unpredictable results.
355 Access to operands which are vectors is more complicated. You can use the
356 macro @code{XVEC} to get the vector-pointer itself, or the macros
357 @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
362 @item XVEC (@var{exp}, @var{idx})
363 Access the vector-pointer which is operand number @var{idx} in @var{exp}.
366 @item XVECLEN (@var{exp}, @var{idx})
367 Access the length (number of elements) in the vector which is
368 in operand number @var{idx} in @var{exp}. This value is an @code{int}.
371 @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
372 Access element number @var{eltnum} in the vector which is
373 in operand number @var{idx} in @var{exp}. This value is an RTX@.
375 It is up to you to make sure that @var{eltnum} is not negative
376 and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
379 All the macros defined in this section expand into lvalues and therefore
380 can be used to assign the operands, lengths and vector elements as well as
383 @node Special Accessors
384 @section Access to Special Operands
385 @cindex access to special operands
387 Some RTL nodes have special annotations associated with them.
392 @findex MEM_ALIAS_SET
393 @item MEM_ALIAS_SET (@var{x})
394 If 0, @var{x} is not in any alias set, and may alias anything. Otherwise,
395 @var{x} can only alias @code{MEM}s in a conflicting alias set. This value
396 is set in a language-dependent manner in the front-end, and should not be
397 altered in the back-end. In some front-ends, these numbers may correspond
398 in some way to types, or other language-level entities, but they need not,
399 and the back-end makes no such assumptions.
400 These set numbers are tested with @code{alias_sets_conflict_p}.
403 @item MEM_EXPR (@var{x})
404 If this register is known to hold the value of some user-level
405 declaration, this is that tree node. It may also be a
406 @code{COMPONENT_REF}, in which case this is some field reference,
407 and @code{TREE_OPERAND (@var{x}, 0)} contains the declaration,
408 or another @code{COMPONENT_REF}, or null if there is no compile-time
409 object associated with the reference.
411 @findex MEM_OFFSET_KNOWN_P
412 @item MEM_OFFSET_KNOWN_P (@var{x})
413 True if the offset of the memory reference from @code{MEM_EXPR} is known.
414 @samp{MEM_OFFSET (@var{x})} provides the offset if so.
417 @item MEM_OFFSET (@var{x})
418 The offset from the start of @code{MEM_EXPR}. The value is only valid if
419 @samp{MEM_OFFSET_KNOWN_P (@var{x})} is true.
421 @findex MEM_SIZE_KNOWN_P
422 @item MEM_SIZE_KNOWN_P (@var{x})
423 True if the size of the memory reference is known.
424 @samp{MEM_SIZE (@var{x})} provides its size if so.
427 @item MEM_SIZE (@var{x})
428 The size in bytes of the memory reference.
429 This is mostly relevant for @code{BLKmode} references as otherwise
430 the size is implied by the mode. The value is only valid if
431 @samp{MEM_SIZE_KNOWN_P (@var{x})} is true.
434 @item MEM_ALIGN (@var{x})
435 The known alignment in bits of the memory reference.
437 @findex MEM_ADDR_SPACE
438 @item MEM_ADDR_SPACE (@var{x})
439 The address space of the memory reference. This will commonly be zero
440 for the generic address space.
445 @findex ORIGINAL_REGNO
446 @item ORIGINAL_REGNO (@var{x})
447 This field holds the number the register ``originally'' had; for a
448 pseudo register turned into a hard reg this will hold the old pseudo
452 @item REG_EXPR (@var{x})
453 If this register is known to hold the value of some user-level
454 declaration, this is that tree node.
457 @item REG_OFFSET (@var{x})
458 If this register is known to hold the value of some user-level
459 declaration, this is the offset into that logical storage.
464 @findex SYMBOL_REF_DECL
465 @item SYMBOL_REF_DECL (@var{x})
466 If the @code{symbol_ref} @var{x} was created for a @code{VAR_DECL} or
467 a @code{FUNCTION_DECL}, that tree is recorded here. If this value is
468 null, then @var{x} was created by back end code generation routines,
469 and there is no associated front end symbol table entry.
471 @code{SYMBOL_REF_DECL} may also point to a tree of class @code{'c'},
472 that is, some sort of constant. In this case, the @code{symbol_ref}
473 is an entry in the per-file constant pool; again, there is no associated
474 front end symbol table entry.
476 @findex SYMBOL_REF_CONSTANT
477 @item SYMBOL_REF_CONSTANT (@var{x})
478 If @samp{CONSTANT_POOL_ADDRESS_P (@var{x})} is true, this is the constant
479 pool entry for @var{x}. It is null otherwise.
481 @findex SYMBOL_REF_DATA
482 @item SYMBOL_REF_DATA (@var{x})
483 A field of opaque type used to store @code{SYMBOL_REF_DECL} or
484 @code{SYMBOL_REF_CONSTANT}.
486 @findex SYMBOL_REF_FLAGS
487 @item SYMBOL_REF_FLAGS (@var{x})
488 In a @code{symbol_ref}, this is used to communicate various predicates
489 about the symbol. Some of these are common enough to be computed by
490 common code, some are specific to the target. The common bits are:
493 @findex SYMBOL_REF_FUNCTION_P
494 @findex SYMBOL_FLAG_FUNCTION
495 @item SYMBOL_FLAG_FUNCTION
496 Set if the symbol refers to a function.
498 @findex SYMBOL_REF_LOCAL_P
499 @findex SYMBOL_FLAG_LOCAL
500 @item SYMBOL_FLAG_LOCAL
501 Set if the symbol is local to this ``module''.
502 See @code{TARGET_BINDS_LOCAL_P}.
504 @findex SYMBOL_REF_EXTERNAL_P
505 @findex SYMBOL_FLAG_EXTERNAL
506 @item SYMBOL_FLAG_EXTERNAL
507 Set if this symbol is not defined in this translation unit.
508 Note that this is not the inverse of @code{SYMBOL_FLAG_LOCAL}.
510 @findex SYMBOL_REF_SMALL_P
511 @findex SYMBOL_FLAG_SMALL
512 @item SYMBOL_FLAG_SMALL
513 Set if the symbol is located in the small data section.
514 See @code{TARGET_IN_SMALL_DATA_P}.
516 @findex SYMBOL_FLAG_TLS_SHIFT
517 @findex SYMBOL_REF_TLS_MODEL
518 @item SYMBOL_REF_TLS_MODEL (@var{x})
519 This is a multi-bit field accessor that returns the @code{tls_model}
520 to be used for a thread-local storage symbol. It returns zero for
521 non-thread-local symbols.
523 @findex SYMBOL_REF_HAS_BLOCK_INFO_P
524 @findex SYMBOL_FLAG_HAS_BLOCK_INFO
525 @item SYMBOL_FLAG_HAS_BLOCK_INFO
526 Set if the symbol has @code{SYMBOL_REF_BLOCK} and
527 @code{SYMBOL_REF_BLOCK_OFFSET} fields.
529 @findex SYMBOL_REF_ANCHOR_P
530 @findex SYMBOL_FLAG_ANCHOR
531 @cindex @option{-fsection-anchors}
532 @item SYMBOL_FLAG_ANCHOR
533 Set if the symbol is used as a section anchor. ``Section anchors''
534 are symbols that have a known position within an @code{object_block}
535 and that can be used to access nearby members of that block.
536 They are used to implement @option{-fsection-anchors}.
538 If this flag is set, then @code{SYMBOL_FLAG_HAS_BLOCK_INFO} will be too.
541 Bits beginning with @code{SYMBOL_FLAG_MACH_DEP} are available for
545 @findex SYMBOL_REF_BLOCK
546 @item SYMBOL_REF_BLOCK (@var{x})
547 If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the
548 @samp{object_block} structure to which the symbol belongs,
549 or @code{NULL} if it has not been assigned a block.
551 @findex SYMBOL_REF_BLOCK_OFFSET
552 @item SYMBOL_REF_BLOCK_OFFSET (@var{x})
553 If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the offset of @var{x}
554 from the first object in @samp{SYMBOL_REF_BLOCK (@var{x})}. The value is
555 negative if @var{x} has not yet been assigned to a block, or it has not
556 been given an offset within that block.
560 @section Flags in an RTL Expression
561 @cindex flags in RTL expression
563 RTL expressions contain several flags (one-bit bit-fields)
564 that are used in certain types of expression. Most often they
565 are accessed with the following macros, which expand into lvalues.
568 @findex CROSSING_JUMP_P
569 @cindex @code{jump_insn} and @samp{/j}
570 @item CROSSING_JUMP_P (@var{x})
571 Nonzero in a @code{jump_insn} if it crosses between hot and cold sections,
572 which could potentially be very far apart in the executable. The presence
573 of this flag indicates to other optimizations that this branching instruction
574 should not be ``collapsed'' into a simpler branching construct. It is used
575 when the optimization to partition basic blocks into hot and cold sections
578 @findex CONSTANT_POOL_ADDRESS_P
579 @cindex @code{symbol_ref} and @samp{/u}
580 @cindex @code{unchanging}, in @code{symbol_ref}
581 @item CONSTANT_POOL_ADDRESS_P (@var{x})
582 Nonzero in a @code{symbol_ref} if it refers to part of the current
583 function's constant pool. For most targets these addresses are in a
584 @code{.rodata} section entirely separate from the function, but for
585 some targets the addresses are close to the beginning of the function.
586 In either case GCC assumes these addresses can be addressed directly,
587 perhaps with the help of base registers.
588 Stored in the @code{unchanging} field and printed as @samp{/u}.
590 @findex INSN_ANNULLED_BRANCH_P
591 @cindex @code{jump_insn} and @samp{/u}
592 @cindex @code{call_insn} and @samp{/u}
593 @cindex @code{insn} and @samp{/u}
594 @cindex @code{unchanging}, in @code{jump_insn}, @code{call_insn} and @code{insn}
595 @item INSN_ANNULLED_BRANCH_P (@var{x})
596 In a @code{jump_insn}, @code{call_insn}, or @code{insn} indicates
597 that the branch is an annulling one. See the discussion under
598 @code{sequence} below. Stored in the @code{unchanging} field and
599 printed as @samp{/u}.
601 @findex INSN_DELETED_P
602 @cindex @code{insn} and @samp{/v}
603 @cindex @code{call_insn} and @samp{/v}
604 @cindex @code{jump_insn} and @samp{/v}
605 @cindex @code{code_label} and @samp{/v}
606 @cindex @code{jump_table_data} and @samp{/v}
607 @cindex @code{barrier} and @samp{/v}
608 @cindex @code{note} and @samp{/v}
609 @cindex @code{volatil}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, @code{jump_table_data}, @code{barrier}, and @code{note}
610 @item INSN_DELETED_P (@var{x})
611 In an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label},
612 @code{jump_table_data}, @code{barrier}, or @code{note},
613 nonzero if the insn has been deleted. Stored in the
614 @code{volatil} field and printed as @samp{/v}.
616 @findex INSN_FROM_TARGET_P
617 @cindex @code{insn} and @samp{/s}
618 @cindex @code{jump_insn} and @samp{/s}
619 @cindex @code{call_insn} and @samp{/s}
620 @cindex @code{in_struct}, in @code{insn} and @code{jump_insn} and @code{call_insn}
621 @item INSN_FROM_TARGET_P (@var{x})
622 In an @code{insn} or @code{jump_insn} or @code{call_insn} in a delay
623 slot of a branch, indicates that the insn
624 is from the target of the branch. If the branch insn has
625 @code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if
626 the branch is taken. For annulled branches with
627 @code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the
628 branch is not taken. When @code{INSN_ANNULLED_BRANCH_P} is not set,
629 this insn will always be executed. Stored in the @code{in_struct}
630 field and printed as @samp{/s}.
632 @findex LABEL_PRESERVE_P
633 @cindex @code{code_label} and @samp{/i}
634 @cindex @code{note} and @samp{/i}
635 @cindex @code{in_struct}, in @code{code_label} and @code{note}
636 @item LABEL_PRESERVE_P (@var{x})
637 In a @code{code_label} or @code{note}, indicates that the label is referenced by
638 code or data not visible to the RTL of a given function.
639 Labels referenced by a non-local goto will have this bit set. Stored
640 in the @code{in_struct} field and printed as @samp{/s}.
642 @findex LABEL_REF_NONLOCAL_P
643 @cindex @code{label_ref} and @samp{/v}
644 @cindex @code{reg_label} and @samp{/v}
645 @cindex @code{volatil}, in @code{label_ref} and @code{reg_label}
646 @item LABEL_REF_NONLOCAL_P (@var{x})
647 In @code{label_ref} and @code{reg_label} expressions, nonzero if this is
648 a reference to a non-local label.
649 Stored in the @code{volatil} field and printed as @samp{/v}.
651 @findex MEM_KEEP_ALIAS_SET_P
652 @cindex @code{mem} and @samp{/j}
653 @cindex @code{jump}, in @code{mem}
654 @item MEM_KEEP_ALIAS_SET_P (@var{x})
655 In @code{mem} expressions, 1 if we should keep the alias set for this
656 mem unchanged when we access a component. Set to 1, for example, when we
657 are already in a non-addressable component of an aggregate.
658 Stored in the @code{jump} field and printed as @samp{/j}.
660 @findex MEM_VOLATILE_P
661 @cindex @code{mem} and @samp{/v}
662 @cindex @code{asm_input} and @samp{/v}
663 @cindex @code{asm_operands} and @samp{/v}
664 @cindex @code{volatil}, in @code{mem}, @code{asm_operands}, and @code{asm_input}
665 @item MEM_VOLATILE_P (@var{x})
666 In @code{mem}, @code{asm_operands}, and @code{asm_input} expressions,
667 nonzero for volatile memory references.
668 Stored in the @code{volatil} field and printed as @samp{/v}.
671 @cindex @code{mem} and @samp{/c}
672 @cindex @code{call}, in @code{mem}
673 @item MEM_NOTRAP_P (@var{x})
674 In @code{mem}, nonzero for memory references that will not trap.
675 Stored in the @code{call} field and printed as @samp{/c}.
678 @cindex @code{mem} and @samp{/f}
679 @cindex @code{frame_related}, in @code{mem}
680 @item MEM_POINTER (@var{x})
681 Nonzero in a @code{mem} if the memory reference holds a pointer.
682 Stored in the @code{frame_related} field and printed as @samp{/f}.
684 @findex MEM_READONLY_P
685 @cindex @code{mem} and @samp{/u}
686 @cindex @code{unchanging}, in @code{mem}
687 @item MEM_READONLY_P (@var{x})
688 Nonzero in a @code{mem}, if the memory is statically allocated and read-only.
690 Read-only in this context means never modified during the lifetime of the
691 program, not necessarily in ROM or in write-disabled pages. A common
692 example of the later is a shared library's global offset table. This
693 table is initialized by the runtime loader, so the memory is technically
694 writable, but after control is transferred from the runtime loader to the
695 application, this memory will never be subsequently modified.
697 Stored in the @code{unchanging} field and printed as @samp{/u}.
699 @findex PREFETCH_SCHEDULE_BARRIER_P
700 @cindex @code{prefetch} and @samp{/v}
701 @cindex @code{volatile}, in @code{prefetch}
702 @item PREFETCH_SCHEDULE_BARRIER_P (@var{x})
703 In a @code{prefetch}, indicates that the prefetch is a scheduling barrier.
704 No other INSNs will be moved over it.
705 Stored in the @code{volatil} field and printed as @samp{/v}.
707 @findex REG_FUNCTION_VALUE_P
708 @cindex @code{reg} and @samp{/i}
709 @cindex @code{return_val}, in @code{reg}
710 @item REG_FUNCTION_VALUE_P (@var{x})
711 Nonzero in a @code{reg} if it is the place in which this function's
712 value is going to be returned. (This happens only in a hard
713 register.) Stored in the @code{return_val} field and printed as
717 @cindex @code{reg} and @samp{/f}
718 @cindex @code{frame_related}, in @code{reg}
719 @item REG_POINTER (@var{x})
720 Nonzero in a @code{reg} if the register holds a pointer. Stored in the
721 @code{frame_related} field and printed as @samp{/f}.
723 @findex REG_USERVAR_P
724 @cindex @code{reg} and @samp{/v}
725 @cindex @code{volatil}, in @code{reg}
726 @item REG_USERVAR_P (@var{x})
727 In a @code{reg}, nonzero if it corresponds to a variable present in
728 the user's source code. Zero for temporaries generated internally by
729 the compiler. Stored in the @code{volatil} field and printed as
732 The same hard register may be used also for collecting the values of
733 functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
736 @findex RTL_CONST_CALL_P
737 @cindex @code{call_insn} and @samp{/u}
738 @cindex @code{unchanging}, in @code{call_insn}
739 @item RTL_CONST_CALL_P (@var{x})
740 In a @code{call_insn} indicates that the insn represents a call to a
741 const function. Stored in the @code{unchanging} field and printed as
744 @findex RTL_PURE_CALL_P
745 @cindex @code{call_insn} and @samp{/i}
746 @cindex @code{return_val}, in @code{call_insn}
747 @item RTL_PURE_CALL_P (@var{x})
748 In a @code{call_insn} indicates that the insn represents a call to a
749 pure function. Stored in the @code{return_val} field and printed as
752 @findex RTL_CONST_OR_PURE_CALL_P
753 @cindex @code{call_insn} and @samp{/u} or @samp{/i}
754 @item RTL_CONST_OR_PURE_CALL_P (@var{x})
755 In a @code{call_insn}, true if @code{RTL_CONST_CALL_P} or
756 @code{RTL_PURE_CALL_P} is true.
758 @findex RTL_LOOPING_CONST_OR_PURE_CALL_P
759 @cindex @code{call_insn} and @samp{/c}
760 @cindex @code{call}, in @code{call_insn}
761 @item RTL_LOOPING_CONST_OR_PURE_CALL_P (@var{x})
762 In a @code{call_insn} indicates that the insn represents a possibly
763 infinite looping call to a const or pure function. Stored in the
764 @code{call} field and printed as @samp{/c}. Only true if one of
765 @code{RTL_CONST_CALL_P} or @code{RTL_PURE_CALL_P} is true.
767 @findex RTX_FRAME_RELATED_P
768 @cindex @code{insn} and @samp{/f}
769 @cindex @code{call_insn} and @samp{/f}
770 @cindex @code{jump_insn} and @samp{/f}
771 @cindex @code{barrier} and @samp{/f}
772 @cindex @code{set} and @samp{/f}
773 @cindex @code{frame_related}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, and @code{set}
774 @item RTX_FRAME_RELATED_P (@var{x})
775 Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn},
776 @code{barrier}, or @code{set} which is part of a function prologue
777 and sets the stack pointer, sets the frame pointer, or saves a register.
778 This flag should also be set on an instruction that sets up a temporary
779 register to use in place of the frame pointer.
780 Stored in the @code{frame_related} field and printed as @samp{/f}.
782 In particular, on RISC targets where there are limits on the sizes of
783 immediate constants, it is sometimes impossible to reach the register
784 save area directly from the stack pointer. In that case, a temporary
785 register is used that is near enough to the register save area, and the
786 Canonical Frame Address, i.e., DWARF2's logical frame pointer, register
787 must (temporarily) be changed to be this temporary register. So, the
788 instruction that sets this temporary register must be marked as
789 @code{RTX_FRAME_RELATED_P}.
791 If the marked instruction is overly complex (defined in terms of what
792 @code{dwarf2out_frame_debug_expr} can handle), you will also have to
793 create a @code{REG_FRAME_RELATED_EXPR} note and attach it to the
794 instruction. This note should contain a simple expression of the
795 computation performed by this instruction, i.e., one that
796 @code{dwarf2out_frame_debug_expr} can handle.
798 This flag is required for exception handling support on targets with RTL
801 @findex SCHED_GROUP_P
802 @cindex @code{insn} and @samp{/s}
803 @cindex @code{call_insn} and @samp{/s}
804 @cindex @code{jump_insn} and @samp{/s}
805 @cindex @code{jump_table_data} and @samp{/s}
806 @cindex @code{in_struct}, in @code{insn}, @code{call_insn}, @code{jump_insn} and @code{jump_table_data}
807 @item SCHED_GROUP_P (@var{x})
808 During instruction scheduling, in an @code{insn}, @code{call_insn},
809 @code{jump_insn} or @code{jump_table_data}, indicates that the
810 previous insn must be scheduled together with this insn. This is used to
811 ensure that certain groups of instructions will not be split up by the
812 instruction scheduling pass, for example, @code{use} insns before
813 a @code{call_insn} may not be separated from the @code{call_insn}.
814 Stored in the @code{in_struct} field and printed as @samp{/s}.
816 @findex SET_IS_RETURN_P
817 @cindex @code{insn} and @samp{/j}
818 @cindex @code{jump}, in @code{insn}
819 @item SET_IS_RETURN_P (@var{x})
820 For a @code{set}, nonzero if it is for a return.
821 Stored in the @code{jump} field and printed as @samp{/j}.
823 @findex SIBLING_CALL_P
824 @cindex @code{call_insn} and @samp{/j}
825 @cindex @code{jump}, in @code{call_insn}
826 @item SIBLING_CALL_P (@var{x})
827 For a @code{call_insn}, nonzero if the insn is a sibling call.
828 Stored in the @code{jump} field and printed as @samp{/j}.
830 @findex STRING_POOL_ADDRESS_P
831 @cindex @code{symbol_ref} and @samp{/f}
832 @cindex @code{frame_related}, in @code{symbol_ref}
833 @item STRING_POOL_ADDRESS_P (@var{x})
834 For a @code{symbol_ref} expression, nonzero if it addresses this function's
835 string constant pool.
836 Stored in the @code{frame_related} field and printed as @samp{/f}.
838 @findex SUBREG_PROMOTED_UNSIGNED_P
839 @cindex @code{subreg} and @samp{/u} and @samp{/v}
840 @cindex @code{unchanging}, in @code{subreg}
841 @cindex @code{volatil}, in @code{subreg}
842 @item SUBREG_PROMOTED_UNSIGNED_P (@var{x})
843 Returns a value greater then zero for a @code{subreg} that has
844 @code{SUBREG_PROMOTED_VAR_P} nonzero if the object being referenced is kept
845 zero-extended, zero if it is kept sign-extended, and less then zero if it is
846 extended some other way via the @code{ptr_extend} instruction.
847 Stored in the @code{unchanging}
848 field and @code{volatil} field, printed as @samp{/u} and @samp{/v}.
849 This macro may only be used to get the value it may not be used to change
850 the value. Use @code{SUBREG_PROMOTED_UNSIGNED_SET} to change the value.
852 @findex SUBREG_PROMOTED_UNSIGNED_SET
853 @cindex @code{subreg} and @samp{/u}
854 @cindex @code{unchanging}, in @code{subreg}
855 @cindex @code{volatil}, in @code{subreg}
856 @item SUBREG_PROMOTED_UNSIGNED_SET (@var{x})
857 Set the @code{unchanging} and @code{volatil} fields in a @code{subreg}
858 to reflect zero, sign, or other extension. If @code{volatil} is
859 zero, then @code{unchanging} as nonzero means zero extension and as
860 zero means sign extension. If @code{volatil} is nonzero then some
861 other type of extension was done via the @code{ptr_extend} instruction.
863 @findex SUBREG_PROMOTED_VAR_P
864 @cindex @code{subreg} and @samp{/s}
865 @cindex @code{in_struct}, in @code{subreg}
866 @item SUBREG_PROMOTED_VAR_P (@var{x})
867 Nonzero in a @code{subreg} if it was made when accessing an object that
868 was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine
869 description macro (@pxref{Storage Layout}). In this case, the mode of
870 the @code{subreg} is the declared mode of the object and the mode of
871 @code{SUBREG_REG} is the mode of the register that holds the object.
872 Promoted variables are always either sign- or zero-extended to the wider
873 mode on every assignment. Stored in the @code{in_struct} field and
874 printed as @samp{/s}.
876 @findex SYMBOL_REF_USED
877 @cindex @code{used}, in @code{symbol_ref}
878 @item SYMBOL_REF_USED (@var{x})
879 In a @code{symbol_ref}, indicates that @var{x} has been used. This is
880 normally only used to ensure that @var{x} is only declared external
881 once. Stored in the @code{used} field.
883 @findex SYMBOL_REF_WEAK
884 @cindex @code{symbol_ref} and @samp{/i}
885 @cindex @code{return_val}, in @code{symbol_ref}
886 @item SYMBOL_REF_WEAK (@var{x})
887 In a @code{symbol_ref}, indicates that @var{x} has been declared weak.
888 Stored in the @code{return_val} field and printed as @samp{/i}.
890 @findex SYMBOL_REF_FLAG
891 @cindex @code{symbol_ref} and @samp{/v}
892 @cindex @code{volatil}, in @code{symbol_ref}
893 @item SYMBOL_REF_FLAG (@var{x})
894 In a @code{symbol_ref}, this is used as a flag for machine-specific purposes.
895 Stored in the @code{volatil} field and printed as @samp{/v}.
897 Most uses of @code{SYMBOL_REF_FLAG} are historic and may be subsumed
898 by @code{SYMBOL_REF_FLAGS}. Certainly use of @code{SYMBOL_REF_FLAGS}
899 is mandatory if the target requires more than one bit of storage.
902 These are the fields to which the above macros refer:
906 @cindex @samp{/c} in RTL dump
908 In a @code{mem}, 1 means that the memory reference will not trap.
910 In a @code{call}, 1 means that this pure or const call may possibly
913 In an RTL dump, this flag is represented as @samp{/c}.
915 @findex frame_related
916 @cindex @samp{/f} in RTL dump
918 In an @code{insn} or @code{set} expression, 1 means that it is part of
919 a function prologue and sets the stack pointer, sets the frame pointer,
920 saves a register, or sets up a temporary register to use in place of the
923 In @code{reg} expressions, 1 means that the register holds a pointer.
925 In @code{mem} expressions, 1 means that the memory reference holds a pointer.
927 In @code{symbol_ref} expressions, 1 means that the reference addresses
928 this function's string constant pool.
930 In an RTL dump, this flag is represented as @samp{/f}.
933 @cindex @samp{/s} in RTL dump
935 In @code{reg} expressions, it is 1 if the register has its entire life
936 contained within the test expression of some loop.
938 In @code{subreg} expressions, 1 means that the @code{subreg} is accessing
939 an object that has had its mode promoted from a wider mode.
941 In @code{label_ref} expressions, 1 means that the referenced label is
942 outside the innermost loop containing the insn in which the @code{label_ref}
945 In @code{code_label} expressions, it is 1 if the label may never be deleted.
946 This is used for labels which are the target of non-local gotos. Such a
947 label that would have been deleted is replaced with a @code{note} of type
948 @code{NOTE_INSN_DELETED_LABEL}.
950 In an @code{insn} during dead-code elimination, 1 means that the insn is
953 In an @code{insn} or @code{jump_insn} during reorg for an insn in the
954 delay slot of a branch,
955 1 means that this insn is from the target of the branch.
957 In an @code{insn} during instruction scheduling, 1 means that this insn
958 must be scheduled as part of a group together with the previous insn.
960 In an RTL dump, this flag is represented as @samp{/s}.
963 @cindex @samp{/i} in RTL dump
965 In @code{reg} expressions, 1 means the register contains
966 the value to be returned by the current function. On
967 machines that pass parameters in registers, the same register number
968 may be used for parameters as well, but this flag is not set on such
971 In @code{symbol_ref} expressions, 1 means the referenced symbol is weak.
973 In @code{call} expressions, 1 means the call is pure.
975 In an RTL dump, this flag is represented as @samp{/i}.
978 @cindex @samp{/j} in RTL dump
980 In a @code{mem} expression, 1 means we should keep the alias set for this
981 mem unchanged when we access a component.
983 In a @code{set}, 1 means it is for a return.
985 In a @code{call_insn}, 1 means it is a sibling call.
987 In a @code{jump_insn}, 1 means it is a crossing jump.
989 In an RTL dump, this flag is represented as @samp{/j}.
992 @cindex @samp{/u} in RTL dump
994 In @code{reg} and @code{mem} expressions, 1 means
995 that the value of the expression never changes.
997 In @code{subreg} expressions, it is 1 if the @code{subreg} references an
998 unsigned object whose mode has been promoted to a wider mode.
1000 In an @code{insn} or @code{jump_insn} in the delay slot of a branch
1001 instruction, 1 means an annulling branch should be used.
1003 In a @code{symbol_ref} expression, 1 means that this symbol addresses
1004 something in the per-function constant pool.
1006 In a @code{call_insn} 1 means that this instruction is a call to a const
1009 In an RTL dump, this flag is represented as @samp{/u}.
1013 This flag is used directly (without an access macro) at the end of RTL
1014 generation for a function, to count the number of times an expression
1015 appears in insns. Expressions that appear more than once are copied,
1016 according to the rules for shared structure (@pxref{Sharing}).
1018 For a @code{reg}, it is used directly (without an access macro) by the
1019 leaf register renumbering code to ensure that each register is only
1022 In a @code{symbol_ref}, it indicates that an external declaration for
1023 the symbol has already been written.
1026 @cindex @samp{/v} in RTL dump
1028 @cindex volatile memory references
1029 In a @code{mem}, @code{asm_operands}, or @code{asm_input}
1030 expression, it is 1 if the memory
1031 reference is volatile. Volatile memory references may not be deleted,
1032 reordered or combined.
1034 In a @code{symbol_ref} expression, it is used for machine-specific
1037 In a @code{reg} expression, it is 1 if the value is a user-level variable.
1038 0 indicates an internal compiler temporary.
1040 In an @code{insn}, 1 means the insn has been deleted.
1042 In @code{label_ref} and @code{reg_label} expressions, 1 means a reference
1043 to a non-local label.
1045 In @code{prefetch} expressions, 1 means that the containing insn is a
1048 In an RTL dump, this flag is represented as @samp{/v}.
1052 @section Machine Modes
1053 @cindex machine modes
1055 @findex machine_mode
1056 A machine mode describes a size of data object and the representation used
1057 for it. In the C code, machine modes are represented by an enumeration
1058 type, @code{machine_mode}, defined in @file{machmode.def}. Each RTL
1059 expression has room for a machine mode and so do certain kinds of tree
1060 expressions (declarations and types, to be precise).
1062 In debugging dumps and machine descriptions, the machine mode of an RTL
1063 expression is written after the expression code with a colon to separate
1064 them. The letters @samp{mode} which appear at the end of each machine mode
1065 name are omitted. For example, @code{(reg:SI 38)} is a @code{reg}
1066 expression with machine mode @code{SImode}. If the mode is
1067 @code{VOIDmode}, it is not written at all.
1069 Here is a table of machine modes. The term ``byte'' below refers to an
1070 object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}).
1075 ``Bit'' mode represents a single bit, for predicate registers.
1079 ``Quarter-Integer'' mode represents a single byte treated as an integer.
1083 ``Half-Integer'' mode represents a two-byte integer.
1087 ``Partial Single Integer'' mode represents an integer which occupies
1088 four bytes but which doesn't really use all four. On some machines,
1089 this is the right mode to use for pointers.
1093 ``Single Integer'' mode represents a four-byte integer.
1097 ``Partial Double Integer'' mode represents an integer which occupies
1098 eight bytes but which doesn't really use all eight. On some machines,
1099 this is the right mode to use for certain pointers.
1103 ``Double Integer'' mode represents an eight-byte integer.
1107 ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
1111 ``Octa Integer'' (?) mode represents a thirty-two-byte integer.
1115 ``Hexadeca Integer'' (?) mode represents a sixty-four-byte integer.
1119 ``Quarter-Floating'' mode represents a quarter-precision (single byte)
1120 floating point number.
1124 ``Half-Floating'' mode represents a half-precision (two byte) floating
1129 ``Three-Quarter-Floating'' (?) mode represents a three-quarter-precision
1130 (three byte) floating point number.
1134 ``Single Floating'' mode represents a four byte floating point number.
1135 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1136 this is a single-precision IEEE floating point number; it can also be
1137 used for double-precision (on processors with 16-bit bytes) and
1138 single-precision VAX and IBM types.
1142 ``Double Floating'' mode represents an eight byte floating point number.
1143 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1144 this is a double-precision IEEE floating point number.
1148 ``Extended Floating'' mode represents an IEEE extended floating point
1149 number. This mode only has 80 meaningful bits (ten bytes). Some
1150 processors require such numbers to be padded to twelve bytes, others
1151 to sixteen; this mode is used for either.
1155 ``Single Decimal Floating'' mode represents a four byte decimal
1156 floating point number (as distinct from conventional binary floating
1161 ``Double Decimal Floating'' mode represents an eight byte decimal
1162 floating point number.
1166 ``Tetra Decimal Floating'' mode represents a sixteen byte decimal
1167 floating point number all 128 of whose bits are meaningful.
1171 ``Tetra Floating'' mode represents a sixteen byte floating point number
1172 all 128 of whose bits are meaningful. One common use is the
1173 IEEE quad-precision format.
1177 ``Quarter-Fractional'' mode represents a single byte treated as a signed
1178 fractional number. The default format is ``s.7''.
1182 ``Half-Fractional'' mode represents a two-byte signed fractional number.
1183 The default format is ``s.15''.
1187 ``Single Fractional'' mode represents a four-byte signed fractional number.
1188 The default format is ``s.31''.
1192 ``Double Fractional'' mode represents an eight-byte signed fractional number.
1193 The default format is ``s.63''.
1197 ``Tetra Fractional'' mode represents a sixteen-byte signed fractional number.
1198 The default format is ``s.127''.
1202 ``Unsigned Quarter-Fractional'' mode represents a single byte treated as an
1203 unsigned fractional number. The default format is ``.8''.
1207 ``Unsigned Half-Fractional'' mode represents a two-byte unsigned fractional
1208 number. The default format is ``.16''.
1212 ``Unsigned Single Fractional'' mode represents a four-byte unsigned fractional
1213 number. The default format is ``.32''.
1217 ``Unsigned Double Fractional'' mode represents an eight-byte unsigned
1218 fractional number. The default format is ``.64''.
1222 ``Unsigned Tetra Fractional'' mode represents a sixteen-byte unsigned
1223 fractional number. The default format is ``.128''.
1227 ``Half-Accumulator'' mode represents a two-byte signed accumulator.
1228 The default format is ``s8.7''.
1232 ``Single Accumulator'' mode represents a four-byte signed accumulator.
1233 The default format is ``s16.15''.
1237 ``Double Accumulator'' mode represents an eight-byte signed accumulator.
1238 The default format is ``s32.31''.
1242 ``Tetra Accumulator'' mode represents a sixteen-byte signed accumulator.
1243 The default format is ``s64.63''.
1247 ``Unsigned Half-Accumulator'' mode represents a two-byte unsigned accumulator.
1248 The default format is ``8.8''.
1252 ``Unsigned Single Accumulator'' mode represents a four-byte unsigned
1253 accumulator. The default format is ``16.16''.
1257 ``Unsigned Double Accumulator'' mode represents an eight-byte unsigned
1258 accumulator. The default format is ``32.32''.
1262 ``Unsigned Tetra Accumulator'' mode represents a sixteen-byte unsigned
1263 accumulator. The default format is ``64.64''.
1267 ``Condition Code'' mode represents the value of a condition code, which
1268 is a machine-specific set of bits used to represent the result of a
1269 comparison operation. Other machine-specific modes may also be used for
1270 the condition code. These modes are not used on machines that use
1271 @code{cc0} (@pxref{Condition Code}).
1275 ``Block'' mode represents values that are aggregates to which none of
1276 the other modes apply. In RTL, only memory references can have this mode,
1277 and only if they appear in string-move or vector instructions. On machines
1278 which have no such instructions, @code{BLKmode} will not appear in RTL@.
1282 Void mode means the absence of a mode or an unspecified mode.
1283 For example, RTL expressions of code @code{const_int} have mode
1284 @code{VOIDmode} because they can be taken to have whatever mode the context
1285 requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by
1286 the absence of any mode.
1294 @item QCmode, HCmode, SCmode, DCmode, XCmode, TCmode
1295 These modes stand for a complex number represented as a pair of floating
1296 point values. The floating point values are in @code{QFmode},
1297 @code{HFmode}, @code{SFmode}, @code{DFmode}, @code{XFmode}, and
1298 @code{TFmode}, respectively.
1306 @item CQImode, CHImode, CSImode, CDImode, CTImode, COImode
1307 These modes stand for a complex number represented as a pair of integer
1308 values. The integer values are in @code{QImode}, @code{HImode},
1309 @code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode},
1314 @item BND32mode BND64mode
1315 These modes stand for bounds for pointer of 32 and 64 bit size respectively.
1316 Mode size is double pointer mode size.
1319 The machine description defines @code{Pmode} as a C macro which expands
1320 into the machine mode used for addresses. Normally this is the mode
1321 whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines.
1323 The only modes which a machine description @i{must} support are
1324 @code{QImode}, and the modes corresponding to @code{BITS_PER_WORD},
1325 @code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}.
1326 The compiler will attempt to use @code{DImode} for 8-byte structures and
1327 unions, but this can be prevented by overriding the definition of
1328 @code{MAX_FIXED_MODE_SIZE}. Alternatively, you can have the compiler
1329 use @code{TImode} for 16-byte structures and unions. Likewise, you can
1330 arrange for the C type @code{short int} to avoid using @code{HImode}.
1332 @cindex mode classes
1333 Very few explicit references to machine modes remain in the compiler and
1334 these few references will soon be removed. Instead, the machine modes
1335 are divided into mode classes. These are represented by the enumeration
1336 type @code{enum mode_class} defined in @file{machmode.h}. The possible
1342 Integer modes. By default these are @code{BImode}, @code{QImode},
1343 @code{HImode}, @code{SImode}, @code{DImode}, @code{TImode}, and
1346 @findex MODE_PARTIAL_INT
1347 @item MODE_PARTIAL_INT
1348 The ``partial integer'' modes, @code{PQImode}, @code{PHImode},
1349 @code{PSImode} and @code{PDImode}.
1353 Floating point modes. By default these are @code{QFmode},
1354 @code{HFmode}, @code{TQFmode}, @code{SFmode}, @code{DFmode},
1355 @code{XFmode} and @code{TFmode}.
1357 @findex MODE_DECIMAL_FLOAT
1358 @item MODE_DECIMAL_FLOAT
1359 Decimal floating point modes. By default these are @code{SDmode},
1360 @code{DDmode} and @code{TDmode}.
1364 Signed fractional modes. By default these are @code{QQmode}, @code{HQmode},
1365 @code{SQmode}, @code{DQmode} and @code{TQmode}.
1369 Unsigned fractional modes. By default these are @code{UQQmode}, @code{UHQmode},
1370 @code{USQmode}, @code{UDQmode} and @code{UTQmode}.
1374 Signed accumulator modes. By default these are @code{HAmode},
1375 @code{SAmode}, @code{DAmode} and @code{TAmode}.
1379 Unsigned accumulator modes. By default these are @code{UHAmode},
1380 @code{USAmode}, @code{UDAmode} and @code{UTAmode}.
1382 @findex MODE_COMPLEX_INT
1383 @item MODE_COMPLEX_INT
1384 Complex integer modes. (These are not currently implemented).
1386 @findex MODE_COMPLEX_FLOAT
1387 @item MODE_COMPLEX_FLOAT
1388 Complex floating point modes. By default these are @code{QCmode},
1389 @code{HCmode}, @code{SCmode}, @code{DCmode}, @code{XCmode}, and
1392 @findex MODE_FUNCTION
1394 Algol or Pascal function variables including a static chain.
1395 (These are not currently implemented).
1399 Modes representing condition code values. These are @code{CCmode} plus
1400 any @code{CC_MODE} modes listed in the @file{@var{machine}-modes.def}.
1401 @xref{Jump Patterns},
1402 also see @ref{Condition Code}.
1404 @findex MODE_POINTER_BOUNDS
1405 @item MODE_POINTER_BOUNDS
1406 Pointer bounds modes. Used to represent values of pointer bounds type.
1407 Operations in these modes may be executed as NOPs depending on hardware
1408 features and environment setup.
1412 This is a catchall mode class for modes which don't fit into the above
1413 classes. Currently @code{VOIDmode} and @code{BLKmode} are in
1417 Here are some C macros that relate to machine modes:
1421 @item GET_MODE (@var{x})
1422 Returns the machine mode of the RTX @var{x}.
1425 @item PUT_MODE (@var{x}, @var{newmode})
1426 Alters the machine mode of the RTX @var{x} to be @var{newmode}.
1428 @findex NUM_MACHINE_MODES
1429 @item NUM_MACHINE_MODES
1430 Stands for the number of machine modes available on the target
1431 machine. This is one greater than the largest numeric value of any
1434 @findex GET_MODE_NAME
1435 @item GET_MODE_NAME (@var{m})
1436 Returns the name of mode @var{m} as a string.
1438 @findex GET_MODE_CLASS
1439 @item GET_MODE_CLASS (@var{m})
1440 Returns the mode class of mode @var{m}.
1442 @findex GET_MODE_WIDER_MODE
1443 @item GET_MODE_WIDER_MODE (@var{m})
1444 Returns the next wider natural mode. For example, the expression
1445 @code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}.
1447 @findex GET_MODE_SIZE
1448 @item GET_MODE_SIZE (@var{m})
1449 Returns the size in bytes of a datum of mode @var{m}.
1451 @findex GET_MODE_BITSIZE
1452 @item GET_MODE_BITSIZE (@var{m})
1453 Returns the size in bits of a datum of mode @var{m}.
1455 @findex GET_MODE_IBIT
1456 @item GET_MODE_IBIT (@var{m})
1457 Returns the number of integral bits of a datum of fixed-point mode @var{m}.
1459 @findex GET_MODE_FBIT
1460 @item GET_MODE_FBIT (@var{m})
1461 Returns the number of fractional bits of a datum of fixed-point mode @var{m}.
1463 @findex GET_MODE_MASK
1464 @item GET_MODE_MASK (@var{m})
1465 Returns a bitmask containing 1 for all bits in a word that fit within
1466 mode @var{m}. This macro can only be used for modes whose bitsize is
1467 less than or equal to @code{HOST_BITS_PER_INT}.
1469 @findex GET_MODE_ALIGNMENT
1470 @item GET_MODE_ALIGNMENT (@var{m})
1471 Return the required alignment, in bits, for an object of mode @var{m}.
1473 @findex GET_MODE_UNIT_SIZE
1474 @item GET_MODE_UNIT_SIZE (@var{m})
1475 Returns the size in bytes of the subunits of a datum of mode @var{m}.
1476 This is the same as @code{GET_MODE_SIZE} except in the case of complex
1477 modes. For them, the unit size is the size of the real or imaginary
1480 @findex GET_MODE_NUNITS
1481 @item GET_MODE_NUNITS (@var{m})
1482 Returns the number of units contained in a mode, i.e.,
1483 @code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}.
1485 @findex GET_CLASS_NARROWEST_MODE
1486 @item GET_CLASS_NARROWEST_MODE (@var{c})
1487 Returns the narrowest mode in mode class @var{c}.
1490 The following 3 variables are defined on every target. They can be
1491 used to allocate buffers that are guaranteed to be large enough to
1492 hold any value that can be represented on the target. The first two
1493 can be overridden by defining them in the target's mode.def file,
1494 however, the value must be a constant that can determined very early
1495 in the compilation process. The third symbol cannot be overridden.
1498 @findex BITS_PER_UNIT
1500 The number of bits in an addressable storage unit (byte). If you do
1501 not define this, the default is 8.
1503 @findex MAX_BITSIZE_MODE_ANY_INT
1504 @item MAX_BITSIZE_MODE_ANY_INT
1505 The maximum bitsize of any mode that is used in integer math. This
1506 should be overridden by the target if it uses large integers as
1507 containers for larger vectors but otherwise never uses the contents to
1508 compute integer values.
1510 @findex MAX_BITSIZE_MODE_ANY_MODE
1511 @item MAX_BITSIZE_MODE_ANY_MODE
1512 The bitsize of the largest mode on the target.
1517 The global variables @code{byte_mode} and @code{word_mode} contain modes
1518 whose classes are @code{MODE_INT} and whose bitsizes are either
1519 @code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit
1520 machines, these are @code{QImode} and @code{SImode}, respectively.
1523 @section Constant Expression Types
1524 @cindex RTL constants
1525 @cindex RTL constant expression types
1527 The simplest RTL expressions are those that represent constant values.
1531 @item (const_int @var{i})
1532 This type of expression represents the integer value @var{i}. @var{i}
1533 is customarily accessed with the macro @code{INTVAL} as in
1534 @code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}.
1536 Constants generated for modes with fewer bits than in
1537 @code{HOST_WIDE_INT} must be sign extended to full width (e.g., with
1538 @code{gen_int_mode}). For constants for modes with more bits than in
1539 @code{HOST_WIDE_INT} the implied high order bits of that constant are
1540 copies of the top bit. Note however that values are neither
1541 inherently signed nor inherently unsigned; where necessary, signedness
1542 is determined by the rtl operation instead.
1548 There is only one expression object for the integer value zero; it is
1549 the value of the variable @code{const0_rtx}. Likewise, the only
1550 expression for integer value one is found in @code{const1_rtx}, the only
1551 expression for integer value two is found in @code{const2_rtx}, and the
1552 only expression for integer value negative one is found in
1553 @code{constm1_rtx}. Any attempt to create an expression of code
1554 @code{const_int} and value zero, one, two or negative one will return
1555 @code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or
1556 @code{constm1_rtx} as appropriate.
1558 @findex const_true_rtx
1559 Similarly, there is only one object for the integer whose value is
1560 @code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If
1561 @code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and
1562 @code{const1_rtx} will point to the same object. If
1563 @code{STORE_FLAG_VALUE} is @minus{}1, @code{const_true_rtx} and
1564 @code{constm1_rtx} will point to the same object.
1566 @findex const_double
1567 @item (const_double:@var{m} @var{i0} @var{i1} @dots{})
1568 This represents either a floating-point constant of mode @var{m} or
1569 (on older ports that do not define
1570 @code{TARGET_SUPPORTS_WIDE_INT}) an integer constant too large to fit
1571 into @code{HOST_BITS_PER_WIDE_INT} bits but small enough to fit within
1572 twice that number of bits. In the latter case, @var{m} will be
1573 @code{VOIDmode}. For integral values constants for modes with more
1574 bits than twice the number in @code{HOST_WIDE_INT} the implied high
1575 order bits of that constant are copies of the top bit of
1576 @code{CONST_DOUBLE_HIGH}. Note however that integral values are
1577 neither inherently signed nor inherently unsigned; where necessary,
1578 signedness is determined by the rtl operation instead.
1580 On more modern ports, @code{CONST_DOUBLE} only represents floating
1581 point values. New ports define @code{TARGET_SUPPORTS_WIDE_INT} to
1582 make this designation.
1584 @findex CONST_DOUBLE_LOW
1585 If @var{m} is @code{VOIDmode}, the bits of the value are stored in
1586 @var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro
1587 @code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}.
1589 If the constant is floating point (regardless of its precision), then
1590 the number of integers used to store the value depends on the size of
1591 @code{REAL_VALUE_TYPE} (@pxref{Floating Point}). The integers
1592 represent a floating point number, but not precisely in the target
1593 machine's or host machine's floating point format. To convert them to
1594 the precise bit pattern used by the target machine, use the macro
1595 @code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}).
1597 @findex CONST_WIDE_INT
1598 @item (const_wide_int:@var{m} @var{nunits} @var{elt0} @dots{})
1599 This contains an array of @code{HOST_WIDE_INT}s that is large enough
1600 to hold any constant that can be represented on the target. This form
1601 of rtl is only used on targets that define
1602 @code{TARGET_SUPPORTS_WIDE_INT} to be nonzero and then
1603 @code{CONST_DOUBLE}s are only used to hold floating-point values. If
1604 the target leaves @code{TARGET_SUPPORTS_WIDE_INT} defined as 0,
1605 @code{CONST_WIDE_INT}s are not used and @code{CONST_DOUBLE}s are as
1608 The values are stored in a compressed format. The higher-order
1609 0s or -1s are not represented if they are just the logical sign
1610 extension of the number that is represented.
1612 @findex CONST_WIDE_INT_VEC
1613 @item CONST_WIDE_INT_VEC (@var{code})
1614 Returns the entire array of @code{HOST_WIDE_INT}s that are used to
1615 store the value. This macro should be rarely used.
1617 @findex CONST_WIDE_INT_NUNITS
1618 @item CONST_WIDE_INT_NUNITS (@var{code})
1619 The number of @code{HOST_WIDE_INT}s used to represent the number.
1620 Note that this generally is smaller than the number of
1621 @code{HOST_WIDE_INT}s implied by the mode size.
1623 @findex CONST_WIDE_INT_ELT
1624 @item CONST_WIDE_INT_NUNITS (@var{code},@var{i})
1625 Returns the @code{i}th element of the array. Element 0 is contains
1626 the low order bits of the constant.
1629 @item (const_fixed:@var{m} @dots{})
1630 Represents a fixed-point constant of mode @var{m}.
1631 The operand is a data structure of type @code{struct fixed_value} and
1632 is accessed with the macro @code{CONST_FIXED_VALUE}. The high part of
1633 data is accessed with @code{CONST_FIXED_VALUE_HIGH}; the low part is
1634 accessed with @code{CONST_FIXED_VALUE_LOW}.
1636 @findex const_poly_int
1637 @item (const_poly_int:@var{m} [@var{c0} @var{c1} @dots{}])
1638 Represents a @code{poly_int}-style polynomial integer with coefficients
1639 @var{c0}, @var{c1}, @dots{}. The coefficients are @code{wide_int}-based
1640 integers rather than rtxes. @code{CONST_POLY_INT_COEFFS} gives the
1641 values of individual coefficients (which is mostly only useful in
1642 low-level routines) and @code{const_poly_int_value} gives the full
1643 @code{poly_int} value.
1645 @findex const_vector
1646 @item (const_vector:@var{m} [@var{x0} @var{x1} @dots{}])
1647 Represents a vector constant. The square brackets stand for the vector
1648 containing the constant elements. @var{x0}, @var{x1} and so on are
1649 the @code{const_int}, @code{const_wide_int}, @code{const_double} or
1650 @code{const_fixed} elements.
1652 The number of units in a @code{const_vector} is obtained with the macro
1653 @code{CONST_VECTOR_NUNITS} as in @code{CONST_VECTOR_NUNITS (@var{v})}.
1655 Individual elements in a vector constant are accessed with the macro
1656 @code{CONST_VECTOR_ELT} as in @code{CONST_VECTOR_ELT (@var{v}, @var{n})}
1657 where @var{v} is the vector constant and @var{n} is the element
1660 @findex const_string
1661 @item (const_string @var{str})
1662 Represents a constant string with value @var{str}. Currently this is
1663 used only for insn attributes (@pxref{Insn Attributes}) since constant
1664 strings in C are placed in memory.
1667 @item (symbol_ref:@var{mode} @var{symbol})
1668 Represents the value of an assembler label for data. @var{symbol} is
1669 a string that describes the name of the assembler label. If it starts
1670 with a @samp{*}, the label is the rest of @var{symbol} not including
1671 the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed
1674 The @code{symbol_ref} contains a mode, which is usually @code{Pmode}.
1675 Usually that is the only mode for which a symbol is directly valid.
1678 @item (label_ref:@var{mode} @var{label})
1679 Represents the value of an assembler label for code. It contains one
1680 operand, an expression, which must be a @code{code_label} or a @code{note}
1681 of type @code{NOTE_INSN_DELETED_LABEL} that appears in the instruction
1682 sequence to identify the place where the label should go.
1684 The reason for using a distinct expression type for code label
1685 references is so that jump optimization can distinguish them.
1687 The @code{label_ref} contains a mode, which is usually @code{Pmode}.
1688 Usually that is the only mode for which a label is directly valid.
1691 @item (const:@var{m} @var{exp})
1692 Wraps an rtx computation @var{exp} whose inputs and result do not
1693 change during the execution of a thread. There are two valid uses.
1694 The first is to represent a global or thread-local address calculation.
1695 In this case @var{exp} should contain @code{const_int},
1696 @code{symbol_ref}, @code{label_ref} or @code{unspec} expressions,
1697 combined with @code{plus} and @code{minus}. Any such @code{unspec}s
1698 are target-specific and typically represent some form of relocation
1699 operator. @var{m} should be a valid address mode.
1701 The second use of @code{const} is to wrap a vector operation.
1702 In this case @var{exp} must be a @code{vec_duplicate} or
1703 @code{vec_series} expression.
1706 @item (high:@var{m} @var{exp})
1707 Represents the high-order bits of @var{exp}, usually a
1708 @code{symbol_ref}. The number of bits is machine-dependent and is
1709 normally the number of bits specified in an instruction that initializes
1710 the high order bits of a register. It is used with @code{lo_sum} to
1711 represent the typical two-instruction sequence used in RISC machines to
1712 reference a global memory location.
1714 @var{m} should be @code{Pmode}.
1720 The macro @code{CONST0_RTX (@var{mode})} refers to an expression with
1721 value 0 in mode @var{mode}. If mode @var{mode} is of mode class
1722 @code{MODE_INT}, it returns @code{const0_rtx}. If mode @var{mode} is of
1723 mode class @code{MODE_FLOAT}, it returns a @code{CONST_DOUBLE}
1724 expression in mode @var{mode}. Otherwise, it returns a
1725 @code{CONST_VECTOR} expression in mode @var{mode}. Similarly, the macro
1726 @code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in
1727 mode @var{mode} and similarly for @code{CONST2_RTX}. The
1728 @code{CONST1_RTX} and @code{CONST2_RTX} macros are undefined
1731 @node Regs and Memory
1732 @section Registers and Memory
1733 @cindex RTL register expressions
1734 @cindex RTL memory expressions
1736 Here are the RTL expression types for describing access to machine
1737 registers and to main memory.
1741 @cindex hard registers
1742 @cindex pseudo registers
1743 @item (reg:@var{m} @var{n})
1744 For small values of the integer @var{n} (those that are less than
1745 @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
1746 register number @var{n}: a @dfn{hard register}. For larger values of
1747 @var{n}, it stands for a temporary value or @dfn{pseudo register}.
1748 The compiler's strategy is to generate code assuming an unlimited
1749 number of such pseudo registers, and later convert them into hard
1750 registers or into memory references.
1752 @var{m} is the machine mode of the reference. It is necessary because
1753 machines can generally refer to each register in more than one mode.
1754 For example, a register may contain a full word but there may be
1755 instructions to refer to it as a half word or as a single byte, as
1756 well as instructions to refer to it as a floating point number of
1759 Even for a register that the machine can access in only one mode,
1760 the mode must always be specified.
1762 The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
1763 description, since the number of hard registers on the machine is an
1764 invariant characteristic of the machine. Note, however, that not
1765 all of the machine registers must be general registers. All the
1766 machine registers that can be used for storage of data are given
1767 hard register numbers, even those that can be used only in certain
1768 instructions or can hold only certain types of data.
1770 A hard register may be accessed in various modes throughout one
1771 function, but each pseudo register is given a natural mode
1772 and is accessed only in that mode. When it is necessary to describe
1773 an access to a pseudo register using a nonnatural mode, a @code{subreg}
1776 A @code{reg} expression with a machine mode that specifies more than
1777 one word of data may actually stand for several consecutive registers.
1778 If in addition the register number specifies a hardware register, then
1779 it actually represents several consecutive hardware registers starting
1780 with the specified one.
1782 Each pseudo register number used in a function's RTL code is
1783 represented by a unique @code{reg} expression.
1785 @findex FIRST_VIRTUAL_REGISTER
1786 @findex LAST_VIRTUAL_REGISTER
1787 Some pseudo register numbers, those within the range of
1788 @code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only
1789 appear during the RTL generation phase and are eliminated before the
1790 optimization phases. These represent locations in the stack frame that
1791 cannot be determined until RTL generation for the function has been
1792 completed. The following virtual register numbers are defined:
1795 @findex VIRTUAL_INCOMING_ARGS_REGNUM
1796 @item VIRTUAL_INCOMING_ARGS_REGNUM
1797 This points to the first word of the incoming arguments passed on the
1798 stack. Normally these arguments are placed there by the caller, but the
1799 callee may have pushed some arguments that were previously passed in
1802 @cindex @code{FIRST_PARM_OFFSET} and virtual registers
1803 @cindex @code{ARG_POINTER_REGNUM} and virtual registers
1804 When RTL generation is complete, this virtual register is replaced
1805 by the sum of the register given by @code{ARG_POINTER_REGNUM} and the
1806 value of @code{FIRST_PARM_OFFSET}.
1808 @findex VIRTUAL_STACK_VARS_REGNUM
1809 @cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers
1810 @item VIRTUAL_STACK_VARS_REGNUM
1811 If @code{FRAME_GROWS_DOWNWARD} is defined to a nonzero value, this points
1812 to immediately above the first variable on the stack. Otherwise, it points
1813 to the first variable on the stack.
1815 @cindex @code{TARGET_STARTING_FRAME_OFFSET} and virtual registers
1816 @cindex @code{FRAME_POINTER_REGNUM} and virtual registers
1817 @code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the
1818 register given by @code{FRAME_POINTER_REGNUM} and the value
1819 @code{TARGET_STARTING_FRAME_OFFSET}.
1821 @findex VIRTUAL_STACK_DYNAMIC_REGNUM
1822 @item VIRTUAL_STACK_DYNAMIC_REGNUM
1823 This points to the location of dynamically allocated memory on the stack
1824 immediately after the stack pointer has been adjusted by the amount of
1827 @cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers
1828 @cindex @code{STACK_POINTER_REGNUM} and virtual registers
1829 This virtual register is replaced by the sum of the register given by
1830 @code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}.
1832 @findex VIRTUAL_OUTGOING_ARGS_REGNUM
1833 @item VIRTUAL_OUTGOING_ARGS_REGNUM
1834 This points to the location in the stack at which outgoing arguments
1835 should be written when the stack is pre-pushed (arguments pushed using
1836 push insns should always use @code{STACK_POINTER_REGNUM}).
1838 @cindex @code{STACK_POINTER_OFFSET} and virtual registers
1839 This virtual register is replaced by the sum of the register given by
1840 @code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}.
1844 @item (subreg:@var{m1} @var{reg:m2} @var{bytenum})
1846 @code{subreg} expressions are used to refer to a register in a machine
1847 mode other than its natural one, or to refer to one register of
1848 a multi-part @code{reg} that actually refers to several registers.
1850 Each pseudo register has a natural mode. If it is necessary to
1851 operate on it in a different mode, the register must be
1852 enclosed in a @code{subreg}.
1854 There are currently three supported types for the first operand of a
1857 @item pseudo registers
1858 This is the most common case. Most @code{subreg}s have pseudo
1859 @code{reg}s as their first operand.
1862 @code{subreg}s of @code{mem} were common in earlier versions of GCC and
1863 are still supported. During the reload pass these are replaced by plain
1864 @code{mem}s. On machines that do not do instruction scheduling, use of
1865 @code{subreg}s of @code{mem} are still used, but this is no longer
1866 recommended. Such @code{subreg}s are considered to be
1867 @code{register_operand}s rather than @code{memory_operand}s before and
1868 during reload. Because of this, the scheduling passes cannot properly
1869 schedule instructions with @code{subreg}s of @code{mem}, so for machines
1870 that do scheduling, @code{subreg}s of @code{mem} should never be used.
1871 To support this, the combine and recog passes have explicit code to
1872 inhibit the creation of @code{subreg}s of @code{mem} when
1873 @code{INSN_SCHEDULING} is defined.
1875 The use of @code{subreg}s of @code{mem} after the reload pass is an area
1876 that is not well understood and should be avoided. There is still some
1877 code in the compiler to support this, but this code has possibly rotted.
1878 This use of @code{subreg}s is discouraged and will most likely not be
1879 supported in the future.
1881 @item hard registers
1882 It is seldom necessary to wrap hard registers in @code{subreg}s; such
1883 registers would normally reduce to a single @code{reg} rtx. This use of
1884 @code{subreg}s is discouraged and may not be supported in the future.
1888 @code{subreg}s of @code{subreg}s are not supported. Using
1889 @code{simplify_gen_subreg} is the recommended way to avoid this problem.
1891 @code{subreg}s come in two distinct flavors, each having its own
1895 @item Paradoxical subregs
1896 When @var{m1} is strictly wider than @var{m2}, the @code{subreg}
1897 expression is called @dfn{paradoxical}. The canonical test for this
1898 class of @code{subreg} is:
1901 paradoxical_subreg_p (@var{m1}, @var{m2})
1904 Paradoxical @code{subreg}s can be used as both lvalues and rvalues.
1905 When used as an lvalue, the low-order bits of the source value
1906 are stored in @var{reg} and the high-order bits are discarded.
1907 When used as an rvalue, the low-order bits of the @code{subreg} are
1908 taken from @var{reg} while the high-order bits may or may not be
1911 The high-order bits of rvalues are defined in the following circumstances:
1914 @item @code{subreg}s of @code{mem}
1915 When @var{m2} is smaller than a word, the macro @code{LOAD_EXTEND_OP},
1916 can control how the high-order bits are defined.
1918 @item @code{subreg} of @code{reg}s
1919 The upper bits are defined when @code{SUBREG_PROMOTED_VAR_P} is true.
1920 @code{SUBREG_PROMOTED_UNSIGNED_P} describes what the upper bits hold.
1921 Such subregs usually represent local variables, register variables
1922 and parameter pseudo variables that have been promoted to a wider mode.
1926 @var{bytenum} is always zero for a paradoxical @code{subreg}, even on
1929 For example, the paradoxical @code{subreg}:
1932 (set (subreg:SI (reg:HI @var{x}) 0) @var{y})
1935 stores the lower 2 bytes of @var{y} in @var{x} and discards the upper
1936 2 bytes. A subsequent:
1939 (set @var{z} (subreg:SI (reg:HI @var{x}) 0))
1942 would set the lower two bytes of @var{z} to @var{y} and set the upper
1943 two bytes to an unknown value assuming @code{SUBREG_PROMOTED_VAR_P} is
1946 @item Normal subregs
1947 When @var{m1} is at least as narrow as @var{m2} the @code{subreg}
1948 expression is called @dfn{normal}.
1950 @findex REGMODE_NATURAL_SIZE
1951 Normal @code{subreg}s restrict consideration to certain bits of
1952 @var{reg}. For this purpose, @var{reg} is divided into
1953 individually-addressable blocks in which each block has:
1956 REGMODE_NATURAL_SIZE (@var{m2})
1959 bytes. Usually the value is @code{UNITS_PER_WORD}; that is,
1960 most targets usually treat each word of a register as being
1961 independently addressable.
1963 There are two types of normal @code{subreg}. If @var{m1} is known
1964 to be no bigger than a block, the @code{subreg} refers to the
1965 least-significant part (or @dfn{lowpart}) of one block of @var{reg}.
1966 If @var{m1} is known to be larger than a block, the @code{subreg} refers
1967 to two or more complete blocks.
1969 When used as an lvalue, @code{subreg} is a block-based accessor.
1970 Storing to a @code{subreg} modifies all the blocks of @var{reg} that
1971 overlap the @code{subreg}, but it leaves the other blocks of @var{reg}
1974 When storing to a normal @code{subreg} that is smaller than a block,
1975 the other bits of the referenced block are usually left in an undefined
1976 state. This laxity makes it easier to generate efficient code for
1977 such instructions. To represent an instruction that preserves all the
1978 bits outside of those in the @code{subreg}, use @code{strict_low_part}
1979 or @code{zero_extract} around the @code{subreg}.
1981 @var{bytenum} must identify the offset of the first byte of the
1982 @code{subreg} from the start of @var{reg}, assuming that @var{reg} is
1983 laid out in memory order. The memory order of bytes is defined by
1984 two target macros, @code{WORDS_BIG_ENDIAN} and @code{BYTES_BIG_ENDIAN}:
1988 @cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
1989 @code{WORDS_BIG_ENDIAN}, if set to 1, says that byte number zero is
1990 part of the most significant word; otherwise, it is part of the least
1994 @cindex @code{BYTES_BIG_ENDIAN}, effect on @code{subreg}
1995 @code{BYTES_BIG_ENDIAN}, if set to 1, says that byte number zero is
1996 the most significant byte within a word; otherwise, it is the least
1997 significant byte within a word.
2000 @cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg}
2001 On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with
2002 @code{WORDS_BIG_ENDIAN}. However, most parts of the compiler treat
2003 floating point values as if they had the same endianness as integer
2004 values. This works because they handle them solely as a collection of
2005 integer values, with no particular numerical value. Only real.c and
2006 the runtime libraries care about @code{FLOAT_WORDS_BIG_ENDIAN}.
2011 (subreg:HI (reg:SI @var{x}) 2)
2014 on a @code{BYTES_BIG_ENDIAN}, @samp{UNITS_PER_WORD == 4} target is the same as
2017 (subreg:HI (reg:SI @var{x}) 0)
2020 on a little-endian, @samp{UNITS_PER_WORD == 4} target. Both
2021 @code{subreg}s access the lower two bytes of register @var{x}.
2023 Note that the byte offset is a polynomial integer; it may not be a
2024 compile-time constant on targets with variable-sized modes. However,
2025 the restrictions above mean that there are only a certain set of
2026 acceptable offsets for a given combination of @var{m1} and @var{m2}.
2027 The compiler can always tell which blocks a valid subreg occupies, and
2028 whether the subreg is a lowpart of a block.
2032 A @code{MODE_PARTIAL_INT} mode behaves as if it were as wide as the
2033 corresponding @code{MODE_INT} mode, except that it has an unknown
2034 number of undefined bits. For example:
2037 (subreg:PSI (reg:SI 0) 0)
2040 @findex REGMODE_NATURAL_SIZE
2041 accesses the whole of @samp{(reg:SI 0)}, but the exact relationship
2042 between the @code{PSImode} value and the @code{SImode} value is not
2043 defined. If we assume @samp{REGMODE_NATURAL_SIZE (DImode) <= 4},
2044 then the following two @code{subreg}s:
2047 (subreg:PSI (reg:DI 0) 0)
2048 (subreg:PSI (reg:DI 0) 4)
2051 represent independent 4-byte accesses to the two halves of
2052 @samp{(reg:DI 0)}. Both @code{subreg}s have an unknown number
2055 If @samp{REGMODE_NATURAL_SIZE (PSImode) <= 2} then these two @code{subreg}s:
2058 (subreg:HI (reg:PSI 0) 0)
2059 (subreg:HI (reg:PSI 0) 2)
2062 represent independent 2-byte accesses that together span the whole
2063 of @samp{(reg:PSI 0)}. Storing to the first @code{subreg} does not
2064 affect the value of the second, and vice versa. @samp{(reg:PSI 0)}
2065 has an unknown number of undefined bits, so the assignment:
2068 (set (subreg:HI (reg:PSI 0) 0) (reg:HI 4))
2071 does not guarantee that @samp{(subreg:HI (reg:PSI 0) 0)} has the
2072 value @samp{(reg:HI 4)}.
2074 @cindex @code{TARGET_CAN_CHANGE_MODE_CLASS} and subreg semantics
2075 The rules above apply to both pseudo @var{reg}s and hard @var{reg}s.
2076 If the semantics are not correct for particular combinations of
2077 @var{m1}, @var{m2} and hard @var{reg}, the target-specific code
2078 must ensure that those combinations are never used. For example:
2081 TARGET_CAN_CHANGE_MODE_CLASS (@var{m2}, @var{m1}, @var{class})
2084 must be false for every class @var{class} that includes @var{reg}.
2086 GCC must be able to determine at compile time whether a subreg is
2087 paradoxical, whether it occupies a whole number of blocks, or whether
2088 it is a lowpart of a block. This means that certain combinations of
2089 variable-sized mode are not permitted. For example, if @var{m2}
2090 holds @var{n} @code{SI} values, where @var{n} is greater than zero,
2091 it is not possible to form a @code{DI} @code{subreg} of it; such a
2092 @code{subreg} would be paradoxical when @var{n} is 1 but not when
2093 @var{n} is greater than 1.
2097 The first operand of a @code{subreg} expression is customarily accessed
2098 with the @code{SUBREG_REG} macro and the second operand is customarily
2099 accessed with the @code{SUBREG_BYTE} macro.
2101 It has been several years since a platform in which
2102 @code{BYTES_BIG_ENDIAN} not equal to @code{WORDS_BIG_ENDIAN} has
2103 been tested. Anyone wishing to support such a platform in the future
2104 may be confronted with code rot.
2107 @cindex scratch operands
2108 @item (scratch:@var{m})
2109 This represents a scratch register that will be required for the
2110 execution of a single instruction and not used subsequently. It is
2111 converted into a @code{reg} by either the local register allocator or
2114 @code{scratch} is usually present inside a @code{clobber} operation
2115 (@pxref{Side Effects}).
2118 @cindex condition code register
2120 This refers to the machine's condition code register. It has no
2121 operands and may not have a machine mode. There are two ways to use it:
2125 To stand for a complete set of condition code flags. This is best on
2126 most machines, where each comparison sets the entire series of flags.
2128 With this technique, @code{(cc0)} may be validly used in only two
2129 contexts: as the destination of an assignment (in test and compare
2130 instructions) and in comparison operators comparing against zero
2131 (@code{const_int} with value zero; that is to say, @code{const0_rtx}).
2134 To stand for a single flag that is the result of a single condition.
2135 This is useful on machines that have only a single flag bit, and in
2136 which comparison instructions must specify the condition to test.
2138 With this technique, @code{(cc0)} may be validly used in only two
2139 contexts: as the destination of an assignment (in test and compare
2140 instructions) where the source is a comparison operator, and as the
2141 first operand of @code{if_then_else} (in a conditional branch).
2145 There is only one expression object of code @code{cc0}; it is the
2146 value of the variable @code{cc0_rtx}. Any attempt to create an
2147 expression of code @code{cc0} will return @code{cc0_rtx}.
2149 Instructions can set the condition code implicitly. On many machines,
2150 nearly all instructions set the condition code based on the value that
2151 they compute or store. It is not necessary to record these actions
2152 explicitly in the RTL because the machine description includes a
2153 prescription for recognizing the instructions that do so (by means of
2154 the macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only
2155 instructions whose sole purpose is to set the condition code, and
2156 instructions that use the condition code, need mention @code{(cc0)}.
2158 On some machines, the condition code register is given a register number
2159 and a @code{reg} is used instead of @code{(cc0)}. This is usually the
2160 preferable approach if only a small subset of instructions modify the
2161 condition code. Other machines store condition codes in general
2162 registers; in such cases a pseudo register should be used.
2164 Some machines, such as the SPARC and RS/6000, have two sets of
2165 arithmetic instructions, one that sets and one that does not set the
2166 condition code. This is best handled by normally generating the
2167 instruction that does not set the condition code, and making a pattern
2168 that both performs the arithmetic and sets the condition code register
2169 (which would not be @code{(cc0)} in this case). For examples, search
2170 for @samp{addcc} and @samp{andcc} in @file{sparc.md}.
2174 @cindex program counter
2175 This represents the machine's program counter. It has no operands and
2176 may not have a machine mode. @code{(pc)} may be validly used only in
2177 certain specific contexts in jump instructions.
2180 There is only one expression object of code @code{pc}; it is the value
2181 of the variable @code{pc_rtx}. Any attempt to create an expression of
2182 code @code{pc} will return @code{pc_rtx}.
2184 All instructions that do not jump alter the program counter implicitly
2185 by incrementing it, but there is no need to mention this in the RTL@.
2188 @item (mem:@var{m} @var{addr} @var{alias})
2189 This RTX represents a reference to main memory at an address
2190 represented by the expression @var{addr}. @var{m} specifies how large
2191 a unit of memory is accessed. @var{alias} specifies an alias set for the
2192 reference. In general two items are in different alias sets if they cannot
2193 reference the same memory address.
2195 The construct @code{(mem:BLK (scratch))} is considered to alias all
2196 other memories. Thus it may be used as a memory barrier in epilogue
2197 stack deallocation patterns.
2200 @item (concat@var{m} @var{rtx} @var{rtx})
2201 This RTX represents the concatenation of two other RTXs. This is used
2202 for complex values. It should only appear in the RTL attached to
2203 declarations and during RTL generation. It should not appear in the
2204 ordinary insn chain.
2207 @item (concatn@var{m} [@var{rtx} @dots{}])
2208 This RTX represents the concatenation of all the @var{rtx} to make a
2209 single value. Like @code{concat}, this should only appear in
2210 declarations, and not in the insn chain.
2214 @section RTL Expressions for Arithmetic
2215 @cindex arithmetic, in RTL
2216 @cindex math, in RTL
2217 @cindex RTL expressions for arithmetic
2219 Unless otherwise specified, all the operands of arithmetic expressions
2220 must be valid for mode @var{m}. An operand is valid for mode @var{m}
2221 if it has mode @var{m}, or if it is a @code{const_int} or
2222 @code{const_double} and @var{m} is a mode of class @code{MODE_INT}.
2224 For commutative binary operations, constants should be placed in the
2232 @cindex RTL addition
2233 @cindex RTL addition with signed saturation
2234 @cindex RTL addition with unsigned saturation
2235 @item (plus:@var{m} @var{x} @var{y})
2236 @itemx (ss_plus:@var{m} @var{x} @var{y})
2237 @itemx (us_plus:@var{m} @var{x} @var{y})
2239 These three expressions all represent the sum of the values
2240 represented by @var{x} and @var{y} carried out in machine mode
2241 @var{m}. They differ in their behavior on overflow of integer modes.
2242 @code{plus} wraps round modulo the width of @var{m}; @code{ss_plus}
2243 saturates at the maximum signed value representable in @var{m};
2244 @code{us_plus} saturates at the maximum unsigned value.
2246 @c ??? What happens on overflow of floating point modes?
2249 @item (lo_sum:@var{m} @var{x} @var{y})
2251 This expression represents the sum of @var{x} and the low-order bits
2252 of @var{y}. It is used with @code{high} (@pxref{Constants}) to
2253 represent the typical two-instruction sequence used in RISC machines
2254 to reference a global memory location.
2256 The number of low order bits is machine-dependent but is
2257 normally the number of bits in a @code{Pmode} item minus the number of
2258 bits set by @code{high}.
2260 @var{m} should be @code{Pmode}.
2265 @cindex RTL difference
2266 @cindex RTL subtraction
2267 @cindex RTL subtraction with signed saturation
2268 @cindex RTL subtraction with unsigned saturation
2269 @item (minus:@var{m} @var{x} @var{y})
2270 @itemx (ss_minus:@var{m} @var{x} @var{y})
2271 @itemx (us_minus:@var{m} @var{x} @var{y})
2273 These three expressions represent the result of subtracting @var{y}
2274 from @var{x}, carried out in mode @var{M}. Behavior on overflow is
2275 the same as for the three variants of @code{plus} (see above).
2278 @cindex RTL comparison
2279 @item (compare:@var{m} @var{x} @var{y})
2280 Represents the result of subtracting @var{y} from @var{x} for purposes
2281 of comparison. The result is computed without overflow, as if with
2284 Of course, machines cannot really subtract with infinite precision.
2285 However, they can pretend to do so when only the sign of the result will
2286 be used, which is the case when the result is stored in the condition
2287 code. And that is the @emph{only} way this kind of expression may
2288 validly be used: as a value to be stored in the condition codes, either
2289 @code{(cc0)} or a register. @xref{Comparisons}.
2291 The mode @var{m} is not related to the modes of @var{x} and @var{y}, but
2292 instead is the mode of the condition code value. If @code{(cc0)} is
2293 used, it is @code{VOIDmode}. Otherwise it is some mode in class
2294 @code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}. If @var{m}
2295 is @code{VOIDmode} or @code{CCmode}, the operation returns sufficient
2296 information (in an unspecified format) so that any comparison operator
2297 can be applied to the result of the @code{COMPARE} operation. For other
2298 modes in class @code{MODE_CC}, the operation only returns a subset of
2301 Normally, @var{x} and @var{y} must have the same mode. Otherwise,
2302 @code{compare} is valid only if the mode of @var{x} is in class
2303 @code{MODE_INT} and @var{y} is a @code{const_int} or
2304 @code{const_double} with mode @code{VOIDmode}. The mode of @var{x}
2305 determines what mode the comparison is to be done in; thus it must not
2308 If one of the operands is a constant, it should be placed in the
2309 second operand and the comparison code adjusted as appropriate.
2311 A @code{compare} specifying two @code{VOIDmode} constants is not valid
2312 since there is no way to know in what mode the comparison is to be
2313 performed; the comparison must either be folded during the compilation
2314 or the first operand must be loaded into a register while its mode is
2321 @cindex negation with signed saturation
2322 @cindex negation with unsigned saturation
2323 @item (neg:@var{m} @var{x})
2324 @itemx (ss_neg:@var{m} @var{x})
2325 @itemx (us_neg:@var{m} @var{x})
2326 These two expressions represent the negation (subtraction from zero) of
2327 the value represented by @var{x}, carried out in mode @var{m}. They
2328 differ in the behavior on overflow of integer modes. In the case of
2329 @code{neg}, the negation of the operand may be a number not representable
2330 in mode @var{m}, in which case it is truncated to @var{m}. @code{ss_neg}
2331 and @code{us_neg} ensure that an out-of-bounds result saturates to the
2332 maximum or minimum signed or unsigned value.
2337 @cindex multiplication
2339 @cindex multiplication with signed saturation
2340 @cindex multiplication with unsigned saturation
2341 @item (mult:@var{m} @var{x} @var{y})
2342 @itemx (ss_mult:@var{m} @var{x} @var{y})
2343 @itemx (us_mult:@var{m} @var{x} @var{y})
2344 Represents the signed product of the values represented by @var{x} and
2345 @var{y} carried out in machine mode @var{m}.
2346 @code{ss_mult} and @code{us_mult} ensure that an out-of-bounds result
2347 saturates to the maximum or minimum signed or unsigned value.
2349 Some machines support a multiplication that generates a product wider
2350 than the operands. Write the pattern for this as
2353 (mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
2356 where @var{m} is wider than the modes of @var{x} and @var{y}, which need
2359 For unsigned widening multiplication, use the same idiom, but with
2360 @code{zero_extend} instead of @code{sign_extend}.
2363 @item (fma:@var{m} @var{x} @var{y} @var{z})
2364 Represents the @code{fma}, @code{fmaf}, and @code{fmal} builtin
2365 functions, which compute @samp{@var{x} * @var{y} + @var{z}}
2366 without doing an intermediate rounding step.
2371 @cindex signed division
2372 @cindex signed division with signed saturation
2374 @item (div:@var{m} @var{x} @var{y})
2375 @itemx (ss_div:@var{m} @var{x} @var{y})
2376 Represents the quotient in signed division of @var{x} by @var{y},
2377 carried out in machine mode @var{m}. If @var{m} is a floating point
2378 mode, it represents the exact quotient; otherwise, the integerized
2380 @code{ss_div} ensures that an out-of-bounds result saturates to the maximum
2381 or minimum signed value.
2383 Some machines have division instructions in which the operands and
2384 quotient widths are not all the same; you should represent
2385 such instructions using @code{truncate} and @code{sign_extend} as in,
2388 (truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
2392 @cindex unsigned division
2393 @cindex unsigned division with unsigned saturation
2395 @item (udiv:@var{m} @var{x} @var{y})
2396 @itemx (us_div:@var{m} @var{x} @var{y})
2397 Like @code{div} but represents unsigned division.
2398 @code{us_div} ensures that an out-of-bounds result saturates to the maximum
2399 or minimum unsigned value.
2405 @item (mod:@var{m} @var{x} @var{y})
2406 @itemx (umod:@var{m} @var{x} @var{y})
2407 Like @code{div} and @code{udiv} but represent the remainder instead of
2412 @cindex signed minimum
2413 @cindex signed maximum
2414 @item (smin:@var{m} @var{x} @var{y})
2415 @itemx (smax:@var{m} @var{x} @var{y})
2416 Represents the smaller (for @code{smin}) or larger (for @code{smax}) of
2417 @var{x} and @var{y}, interpreted as signed values in mode @var{m}.
2418 When used with floating point, if both operands are zeros, or if either
2419 operand is @code{NaN}, then it is unspecified which of the two operands
2420 is returned as the result.
2424 @cindex unsigned minimum and maximum
2425 @item (umin:@var{m} @var{x} @var{y})
2426 @itemx (umax:@var{m} @var{x} @var{y})
2427 Like @code{smin} and @code{smax}, but the values are interpreted as unsigned
2431 @cindex complement, bitwise
2432 @cindex bitwise complement
2433 @item (not:@var{m} @var{x})
2434 Represents the bitwise complement of the value represented by @var{x},
2435 carried out in mode @var{m}, which must be a fixed-point machine mode.
2438 @cindex logical-and, bitwise
2439 @cindex bitwise logical-and
2440 @item (and:@var{m} @var{x} @var{y})
2441 Represents the bitwise logical-and of the values represented by
2442 @var{x} and @var{y}, carried out in machine mode @var{m}, which must be
2443 a fixed-point machine mode.
2446 @cindex inclusive-or, bitwise
2447 @cindex bitwise inclusive-or
2448 @item (ior:@var{m} @var{x} @var{y})
2449 Represents the bitwise inclusive-or of the values represented by @var{x}
2450 and @var{y}, carried out in machine mode @var{m}, which must be a
2454 @cindex exclusive-or, bitwise
2455 @cindex bitwise exclusive-or
2456 @item (xor:@var{m} @var{x} @var{y})
2457 Represents the bitwise exclusive-or of the values represented by @var{x}
2458 and @var{y}, carried out in machine mode @var{m}, which must be a
2466 @cindex arithmetic shift
2467 @cindex arithmetic shift with signed saturation
2468 @cindex arithmetic shift with unsigned saturation
2469 @item (ashift:@var{m} @var{x} @var{c})
2470 @itemx (ss_ashift:@var{m} @var{x} @var{c})
2471 @itemx (us_ashift:@var{m} @var{x} @var{c})
2472 These three expressions represent the result of arithmetically shifting @var{x}
2473 left by @var{c} places. They differ in their behavior on overflow of integer
2474 modes. An @code{ashift} operation is a plain shift with no special behavior
2475 in case of a change in the sign bit; @code{ss_ashift} and @code{us_ashift}
2476 saturates to the minimum or maximum representable value if any of the bits
2477 shifted out differs from the final sign bit.
2479 @var{x} have mode @var{m}, a fixed-point machine mode. @var{c}
2480 be a fixed-point mode or be a constant with mode @code{VOIDmode}; which
2481 mode is determined by the mode called for in the machine description
2482 entry for the left-shift instruction. For example, on the VAX, the mode
2483 of @var{c} is @code{QImode} regardless of @var{m}.
2488 @item (lshiftrt:@var{m} @var{x} @var{c})
2489 @itemx (ashiftrt:@var{m} @var{x} @var{c})
2490 Like @code{ashift} but for right shift. Unlike the case for left shift,
2491 these two operations are distinct.
2497 @cindex right rotate
2498 @item (rotate:@var{m} @var{x} @var{c})
2499 @itemx (rotatert:@var{m} @var{x} @var{c})
2500 Similar but represent left and right rotate. If @var{c} is a constant,
2505 @cindex absolute value
2506 @item (abs:@var{m} @var{x})
2507 @item (ss_abs:@var{m} @var{x})
2508 Represents the absolute value of @var{x}, computed in mode @var{m}.
2509 @code{ss_abs} ensures that an out-of-bounds result saturates to the
2510 maximum signed value.
2515 @item (sqrt:@var{m} @var{x})
2516 Represents the square root of @var{x}, computed in mode @var{m}.
2517 Most often @var{m} will be a floating point mode.
2520 @item (ffs:@var{m} @var{x})
2521 Represents one plus the index of the least significant 1-bit in
2522 @var{x}, represented as an integer of mode @var{m}. (The value is
2523 zero if @var{x} is zero.) The mode of @var{x} must be @var{m}
2527 @item (clrsb:@var{m} @var{x})
2528 Represents the number of redundant leading sign bits in @var{x},
2529 represented as an integer of mode @var{m}, starting at the most
2530 significant bit position. This is one less than the number of leading
2531 sign bits (either 0 or 1), with no special cases. The mode of @var{x}
2532 must be @var{m} or @code{VOIDmode}.
2535 @item (clz:@var{m} @var{x})
2536 Represents the number of leading 0-bits in @var{x}, represented as an
2537 integer of mode @var{m}, starting at the most significant bit position.
2538 If @var{x} is zero, the value is determined by
2539 @code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}). Note that this is one of
2540 the few expressions that is not invariant under widening. The mode of
2541 @var{x} must be @var{m} or @code{VOIDmode}.
2544 @item (ctz:@var{m} @var{x})
2545 Represents the number of trailing 0-bits in @var{x}, represented as an
2546 integer of mode @var{m}, starting at the least significant bit position.
2547 If @var{x} is zero, the value is determined by
2548 @code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}). Except for this case,
2549 @code{ctz(x)} is equivalent to @code{ffs(@var{x}) - 1}. The mode of
2550 @var{x} must be @var{m} or @code{VOIDmode}.
2553 @item (popcount:@var{m} @var{x})
2554 Represents the number of 1-bits in @var{x}, represented as an integer of
2555 mode @var{m}. The mode of @var{x} must be @var{m} or @code{VOIDmode}.
2558 @item (parity:@var{m} @var{x})
2559 Represents the number of 1-bits modulo 2 in @var{x}, represented as an
2560 integer of mode @var{m}. The mode of @var{x} must be @var{m} or
2564 @item (bswap:@var{m} @var{x})
2565 Represents the value @var{x} with the order of bytes reversed, carried out
2566 in mode @var{m}, which must be a fixed-point machine mode.
2567 The mode of @var{x} must be @var{m} or @code{VOIDmode}.
2571 @section Comparison Operations
2572 @cindex RTL comparison operations
2574 Comparison operators test a relation on two operands and are considered
2575 to represent a machine-dependent nonzero value described by, but not
2576 necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
2577 if the relation holds, or zero if it does not, for comparison operators
2578 whose results have a `MODE_INT' mode,
2579 @code{FLOAT_STORE_FLAG_VALUE} (@pxref{Misc}) if the relation holds, or
2580 zero if it does not, for comparison operators that return floating-point
2581 values, and a vector of either @code{VECTOR_STORE_FLAG_VALUE} (@pxref{Misc})
2582 if the relation holds, or of zeros if it does not, for comparison operators
2583 that return vector results.
2584 The mode of the comparison operation is independent of the mode
2585 of the data being compared. If the comparison operation is being tested
2586 (e.g., the first operand of an @code{if_then_else}), the mode must be
2589 @cindex condition codes
2590 There are two ways that comparison operations may be used. The
2591 comparison operators may be used to compare the condition codes
2592 @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such
2593 a construct actually refers to the result of the preceding instruction
2594 in which the condition codes were set. The instruction setting the
2595 condition code must be adjacent to the instruction using the condition
2596 code; only @code{note} insns may separate them.
2598 Alternatively, a comparison operation may directly compare two data
2599 objects. The mode of the comparison is determined by the operands; they
2600 must both be valid for a common machine mode. A comparison with both
2601 operands constant would be invalid as the machine mode could not be
2602 deduced from it, but such a comparison should never exist in RTL due to
2605 In the example above, if @code{(cc0)} were last set to
2606 @code{(compare @var{x} @var{y})}, the comparison operation is
2607 identical to @code{(eq @var{x} @var{y})}. Usually only one style
2608 of comparisons is supported on a particular machine, but the combine
2609 pass will try to merge the operations to produce the @code{eq} shown
2610 in case it exists in the context of the particular insn involved.
2612 Inequality comparisons come in two flavors, signed and unsigned. Thus,
2613 there are distinct expression codes @code{gt} and @code{gtu} for signed and
2614 unsigned greater-than. These can produce different results for the same
2615 pair of integer values: for example, 1 is signed greater-than @minus{}1 but not
2616 unsigned greater-than, because @minus{}1 when regarded as unsigned is actually
2617 @code{0xffffffff} which is greater than 1.
2619 The signed comparisons are also used for floating point values. Floating
2620 point comparisons are distinguished by the machine modes of the operands.
2625 @item (eq:@var{m} @var{x} @var{y})
2626 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2627 are equal, otherwise 0.
2631 @item (ne:@var{m} @var{x} @var{y})
2632 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2633 are not equal, otherwise 0.
2636 @cindex greater than
2637 @item (gt:@var{m} @var{x} @var{y})
2638 @code{STORE_FLAG_VALUE} if the @var{x} is greater than @var{y}. If they
2639 are fixed-point, the comparison is done in a signed sense.
2642 @cindex greater than
2643 @cindex unsigned greater than
2644 @item (gtu:@var{m} @var{x} @var{y})
2645 Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
2650 @cindex unsigned less than
2651 @item (lt:@var{m} @var{x} @var{y})
2652 @itemx (ltu:@var{m} @var{x} @var{y})
2653 Like @code{gt} and @code{gtu} but test for ``less than''.
2656 @cindex greater than
2658 @cindex unsigned greater than
2659 @item (ge:@var{m} @var{x} @var{y})
2660 @itemx (geu:@var{m} @var{x} @var{y})
2661 Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
2664 @cindex less than or equal
2666 @cindex unsigned less than
2667 @item (le:@var{m} @var{x} @var{y})
2668 @itemx (leu:@var{m} @var{x} @var{y})
2669 Like @code{gt} and @code{gtu} but test for ``less than or equal''.
2671 @findex if_then_else
2672 @item (if_then_else @var{cond} @var{then} @var{else})
2673 This is not a comparison operation but is listed here because it is
2674 always used in conjunction with a comparison operation. To be
2675 precise, @var{cond} is a comparison expression. This expression
2676 represents a choice, according to @var{cond}, between the value
2677 represented by @var{then} and the one represented by @var{else}.
2679 On most machines, @code{if_then_else} expressions are valid only
2680 to express conditional jumps.
2683 @item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
2684 Similar to @code{if_then_else}, but more general. Each of @var{test1},
2685 @var{test2}, @dots{} is performed in turn. The result of this expression is
2686 the @var{value} corresponding to the first nonzero test, or @var{default} if
2687 none of the tests are nonzero expressions.
2689 This is currently not valid for instruction patterns and is supported only
2690 for insn attributes. @xref{Insn Attributes}.
2697 Special expression codes exist to represent bit-field instructions.
2700 @findex sign_extract
2701 @cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
2702 @item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
2703 This represents a reference to a sign-extended bit-field contained or
2704 starting in @var{loc} (a memory or register reference). The bit-field
2705 is @var{size} bits wide and starts at bit @var{pos}. The compilation
2706 option @code{BITS_BIG_ENDIAN} says which end of the memory unit
2707 @var{pos} counts from.
2709 If @var{loc} is in memory, its mode must be a single-byte integer mode.
2710 If @var{loc} is in a register, the mode to use is specified by the
2711 operand of the @code{insv} or @code{extv} pattern
2712 (@pxref{Standard Names}) and is usually a full-word integer mode,
2713 which is the default if none is specified.
2715 The mode of @var{pos} is machine-specific and is also specified
2716 in the @code{insv} or @code{extv} pattern.
2718 The mode @var{m} is the same as the mode that would be used for
2719 @var{loc} if it were a register.
2721 A @code{sign_extract} can not appear as an lvalue, or part thereof,
2724 @findex zero_extract
2725 @item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
2726 Like @code{sign_extract} but refers to an unsigned or zero-extended
2727 bit-field. The same sequence of bits are extracted, but they
2728 are filled to an entire word with zeros instead of by sign-extension.
2730 Unlike @code{sign_extract}, this type of expressions can be lvalues
2731 in RTL; they may appear on the left side of an assignment, indicating
2732 insertion of a value into the specified bit-field.
2735 @node Vector Operations
2736 @section Vector Operations
2737 @cindex vector operations
2739 All normal RTL expressions can be used with vector modes; they are
2740 interpreted as operating on each part of the vector independently.
2741 Additionally, there are a few new expressions to describe specific vector
2746 @item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items})
2747 This describes a merge operation between two vectors. The result is a vector
2748 of mode @var{m}; its elements are selected from either @var{vec1} or
2749 @var{vec2}. Which elements are selected is described by @var{items}, which
2750 is a bit mask represented by a @code{const_int}; a zero bit indicates the
2751 corresponding element in the result vector is taken from @var{vec2} while
2752 a set bit indicates it is taken from @var{vec1}.
2755 @item (vec_select:@var{m} @var{vec1} @var{selection})
2756 This describes an operation that selects parts of a vector. @var{vec1} is
2757 the source vector, and @var{selection} is a @code{parallel} that contains a
2758 @code{const_int} for each of the subparts of the result vector, giving the
2759 number of the source subpart that should be stored into it.
2760 The result mode @var{m} is either the submode for a single element of
2761 @var{vec1} (if only one subpart is selected), or another vector mode
2762 with that element submode (if multiple subparts are selected).
2765 @item (vec_concat:@var{m} @var{x1} @var{x2})
2766 Describes a vector concat operation. The result is a concatenation of the
2767 vectors or scalars @var{x1} and @var{x2}; its length is the sum of the
2768 lengths of the two inputs.
2770 @findex vec_duplicate
2771 @item (vec_duplicate:@var{m} @var{x})
2772 This operation converts a scalar into a vector or a small vector into a
2773 larger one by duplicating the input values. The output vector mode must have
2774 the same submodes as the input vector mode or the scalar modes, and the
2775 number of output parts must be an integer multiple of the number of input
2779 @item (vec_series:@var{m} @var{base} @var{step})
2780 This operation creates a vector in which element @var{i} is equal to
2781 @samp{@var{base} + @var{i}*@var{step}}. @var{m} must be a vector integer mode.
2785 @section Conversions
2787 @cindex machine mode conversions
2789 All conversions between machine modes must be represented by
2790 explicit conversion operations. For example, an expression
2791 which is the sum of a byte and a full word cannot be written as
2792 @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
2793 operation requires two operands of the same machine mode.
2794 Therefore, the byte-sized operand is enclosed in a conversion
2798 (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
2801 The conversion operation is not a mere placeholder, because there
2802 may be more than one way of converting from a given starting mode
2803 to the desired final mode. The conversion operation code says how
2806 For all conversion operations, @var{x} must not be @code{VOIDmode}
2807 because the mode in which to do the conversion would not be known.
2808 The conversion must either be done at compile-time or @var{x}
2809 must be placed into a register.
2813 @item (sign_extend:@var{m} @var{x})
2814 Represents the result of sign-extending the value @var{x}
2815 to machine mode @var{m}. @var{m} must be a fixed-point mode
2816 and @var{x} a fixed-point value of a mode narrower than @var{m}.
2819 @item (zero_extend:@var{m} @var{x})
2820 Represents the result of zero-extending the value @var{x}
2821 to machine mode @var{m}. @var{m} must be a fixed-point mode
2822 and @var{x} a fixed-point value of a mode narrower than @var{m}.
2824 @findex float_extend
2825 @item (float_extend:@var{m} @var{x})
2826 Represents the result of extending the value @var{x}
2827 to machine mode @var{m}. @var{m} must be a floating point mode
2828 and @var{x} a floating point value of a mode narrower than @var{m}.
2831 @item (truncate:@var{m} @var{x})
2832 Represents the result of truncating the value @var{x}
2833 to machine mode @var{m}. @var{m} must be a fixed-point mode
2834 and @var{x} a fixed-point value of a mode wider than @var{m}.
2837 @item (ss_truncate:@var{m} @var{x})
2838 Represents the result of truncating the value @var{x}
2839 to machine mode @var{m}, using signed saturation in the case of
2840 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
2844 @item (us_truncate:@var{m} @var{x})
2845 Represents the result of truncating the value @var{x}
2846 to machine mode @var{m}, using unsigned saturation in the case of
2847 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
2850 @findex float_truncate
2851 @item (float_truncate:@var{m} @var{x})
2852 Represents the result of truncating the value @var{x}
2853 to machine mode @var{m}. @var{m} must be a floating point mode
2854 and @var{x} a floating point value of a mode wider than @var{m}.
2857 @item (float:@var{m} @var{x})
2858 Represents the result of converting fixed point value @var{x},
2859 regarded as signed, to floating point mode @var{m}.
2861 @findex unsigned_float
2862 @item (unsigned_float:@var{m} @var{x})
2863 Represents the result of converting fixed point value @var{x},
2864 regarded as unsigned, to floating point mode @var{m}.
2867 @item (fix:@var{m} @var{x})
2868 When @var{m} is a floating-point mode, represents the result of
2869 converting floating point value @var{x} (valid for mode @var{m}) to an
2870 integer, still represented in floating point mode @var{m}, by rounding
2873 When @var{m} is a fixed-point mode, represents the result of
2874 converting floating point value @var{x} to mode @var{m}, regarded as
2875 signed. How rounding is done is not specified, so this operation may
2876 be used validly in compiling C code only for integer-valued operands.
2878 @findex unsigned_fix
2879 @item (unsigned_fix:@var{m} @var{x})
2880 Represents the result of converting floating point value @var{x} to
2881 fixed point mode @var{m}, regarded as unsigned. How rounding is done
2884 @findex fract_convert
2885 @item (fract_convert:@var{m} @var{x})
2886 Represents the result of converting fixed-point value @var{x} to
2887 fixed-point mode @var{m}, signed integer value @var{x} to
2888 fixed-point mode @var{m}, floating-point value @var{x} to
2889 fixed-point mode @var{m}, fixed-point value @var{x} to integer mode @var{m}
2890 regarded as signed, or fixed-point value @var{x} to floating-point mode @var{m}.
2891 When overflows or underflows happen, the results are undefined.
2894 @item (sat_fract:@var{m} @var{x})
2895 Represents the result of converting fixed-point value @var{x} to
2896 fixed-point mode @var{m}, signed integer value @var{x} to
2897 fixed-point mode @var{m}, or floating-point value @var{x} to
2898 fixed-point mode @var{m}.
2899 When overflows or underflows happen, the results are saturated to the
2900 maximum or the minimum.
2902 @findex unsigned_fract_convert
2903 @item (unsigned_fract_convert:@var{m} @var{x})
2904 Represents the result of converting fixed-point value @var{x} to
2905 integer mode @var{m} regarded as unsigned, or unsigned integer value @var{x} to
2906 fixed-point mode @var{m}.
2907 When overflows or underflows happen, the results are undefined.
2909 @findex unsigned_sat_fract
2910 @item (unsigned_sat_fract:@var{m} @var{x})
2911 Represents the result of converting unsigned integer value @var{x} to
2912 fixed-point mode @var{m}.
2913 When overflows or underflows happen, the results are saturated to the
2914 maximum or the minimum.
2917 @node RTL Declarations
2918 @section Declarations
2919 @cindex RTL declarations
2920 @cindex declarations, RTL
2922 Declaration expression codes do not represent arithmetic operations
2923 but rather state assertions about their operands.
2926 @findex strict_low_part
2927 @cindex @code{subreg}, in @code{strict_low_part}
2928 @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
2929 This expression code is used in only one context: as the destination operand of a
2930 @code{set} expression. In addition, the operand of this expression
2931 must be a non-paradoxical @code{subreg} expression.
2933 The presence of @code{strict_low_part} says that the part of the
2934 register which is meaningful in mode @var{n}, but is not part of
2935 mode @var{m}, is not to be altered. Normally, an assignment to such
2936 a subreg is allowed to have undefined effects on the rest of the
2937 register when @var{m} is smaller than @samp{REGMODE_NATURAL_SIZE (@var{n})}.
2941 @section Side Effect Expressions
2942 @cindex RTL side effect expressions
2944 The expression codes described so far represent values, not actions.
2945 But machine instructions never produce values; they are meaningful
2946 only for their side effects on the state of the machine. Special
2947 expression codes are used to represent side effects.
2949 The body of an instruction is always one of these side effect codes;
2950 the codes described above, which represent values, appear only as
2951 the operands of these.
2955 @item (set @var{lval} @var{x})
2956 Represents the action of storing the value of @var{x} into the place
2957 represented by @var{lval}. @var{lval} must be an expression
2958 representing a place that can be stored in: @code{reg} (or @code{subreg},
2959 @code{strict_low_part} or @code{zero_extract}), @code{mem}, @code{pc},
2960 @code{parallel}, or @code{cc0}.
2962 If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
2963 machine mode; then @var{x} must be valid for that mode.
2965 If @var{lval} is a @code{reg} whose machine mode is less than the full
2966 width of the register, then it means that the part of the register
2967 specified by the machine mode is given the specified value and the
2968 rest of the register receives an undefined value. Likewise, if
2969 @var{lval} is a @code{subreg} whose machine mode is narrower than
2970 the mode of the register, the rest of the register can be changed in
2973 If @var{lval} is a @code{strict_low_part} of a subreg, then the part
2974 of the register specified by the machine mode of the @code{subreg} is
2975 given the value @var{x} and the rest of the register is not changed.
2977 If @var{lval} is a @code{zero_extract}, then the referenced part of
2978 the bit-field (a memory or register reference) specified by the
2979 @code{zero_extract} is given the value @var{x} and the rest of the
2980 bit-field is not changed. Note that @code{sign_extract} can not
2981 appear in @var{lval}.
2983 If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
2984 be either a @code{compare} expression or a value that may have any mode.
2985 The latter case represents a ``test'' instruction. The expression
2986 @code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to
2987 @code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}.
2988 Use the former expression to save space during the compilation.
2990 If @var{lval} is a @code{parallel}, it is used to represent the case of
2991 a function returning a structure in multiple registers. Each element
2992 of the @code{parallel} is an @code{expr_list} whose first operand is a
2993 @code{reg} and whose second operand is a @code{const_int} representing the
2994 offset (in bytes) into the structure at which the data in that register
2995 corresponds. The first element may be null to indicate that the structure
2996 is also passed partly in memory.
2998 @cindex jump instructions and @code{set}
2999 @cindex @code{if_then_else} usage
3000 If @var{lval} is @code{(pc)}, we have a jump instruction, and the
3001 possibilities for @var{x} are very limited. It may be a
3002 @code{label_ref} expression (unconditional jump). It may be an
3003 @code{if_then_else} (conditional jump), in which case either the
3004 second or the third operand must be @code{(pc)} (for the case which
3005 does not jump) and the other of the two must be a @code{label_ref}
3006 (for the case which does jump). @var{x} may also be a @code{mem} or
3007 @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
3008 @code{mem}; these unusual patterns are used to represent jumps through
3011 If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of
3012 @var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
3013 valid for the mode of @var{lval}.
3017 @var{lval} is customarily accessed with the @code{SET_DEST} macro and
3018 @var{x} with the @code{SET_SRC} macro.
3022 As the sole expression in a pattern, represents a return from the
3023 current function, on machines where this can be done with one
3024 instruction, such as VAXen. On machines where a multi-instruction
3025 ``epilogue'' must be executed in order to return from the function,
3026 returning is done by jumping to a label which precedes the epilogue, and
3027 the @code{return} expression code is never used.
3029 Inside an @code{if_then_else} expression, represents the value to be
3030 placed in @code{pc} to return to the caller.
3032 Note that an insn pattern of @code{(return)} is logically equivalent to
3033 @code{(set (pc) (return))}, but the latter form is never used.
3035 @findex simple_return
3036 @item (simple_return)
3037 Like @code{(return)}, but truly represents only a function return, while
3038 @code{(return)} may represent an insn that also performs other functions
3039 of the function epilogue. Like @code{(return)}, this may also occur in
3043 @item (call @var{function} @var{nargs})
3044 Represents a function call. @var{function} is a @code{mem} expression
3045 whose address is the address of the function to be called.
3046 @var{nargs} is an expression which can be used for two purposes: on
3047 some machines it represents the number of bytes of stack argument; on
3048 others, it represents the number of argument registers.
3050 Each machine has a standard machine mode which @var{function} must
3051 have. The machine description defines macro @code{FUNCTION_MODE} to
3052 expand into the requisite mode name. The purpose of this mode is to
3053 specify what kind of addressing is allowed, on machines where the
3054 allowed kinds of addressing depend on the machine mode being
3058 @item (clobber @var{x})
3059 Represents the storing or possible storing of an unpredictable,
3060 undescribed value into @var{x}, which must be a @code{reg},
3061 @code{scratch}, @code{parallel} or @code{mem} expression.
3063 One place this is used is in string instructions that store standard
3064 values into particular hard registers. It may not be worth the
3065 trouble to describe the values that are stored, but it is essential to
3066 inform the compiler that the registers will be altered, lest it
3067 attempt to keep data in them across the string instruction.
3069 If @var{x} is @code{(mem:BLK (const_int 0))} or
3070 @code{(mem:BLK (scratch))}, it means that all memory
3071 locations must be presumed clobbered. If @var{x} is a @code{parallel},
3072 it has the same meaning as a @code{parallel} in a @code{set} expression.
3074 Note that the machine description classifies certain hard registers as
3075 ``call-clobbered''. All function call instructions are assumed by
3076 default to clobber these registers, so there is no need to use
3077 @code{clobber} expressions to indicate this fact. Also, each function
3078 call is assumed to have the potential to alter any memory location,
3079 unless the function is declared @code{const}.
3081 If the last group of expressions in a @code{parallel} are each a
3082 @code{clobber} expression whose arguments are @code{reg} or
3083 @code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
3084 phase can add the appropriate @code{clobber} expressions to an insn it
3085 has constructed when doing so will cause a pattern to be matched.
3087 This feature can be used, for example, on a machine that whose multiply
3088 and add instructions don't use an MQ register but which has an
3089 add-accumulate instruction that does clobber the MQ register. Similarly,
3090 a combined instruction might require a temporary register while the
3091 constituent instructions might not.
3093 When a @code{clobber} expression for a register appears inside a
3094 @code{parallel} with other side effects, the register allocator
3095 guarantees that the register is unoccupied both before and after that
3096 insn if it is a hard register clobber. For pseudo-register clobber,
3097 the register allocator and the reload pass do not assign the same hard
3098 register to the clobber and the input operands if there is an insn
3099 alternative containing the @samp{&} constraint (@pxref{Modifiers}) for
3100 the clobber and the hard register is in register classes of the
3101 clobber in the alternative. You can clobber either a specific hard
3102 register, a pseudo register, or a @code{scratch} expression; in the
3103 latter two cases, GCC will allocate a hard register that is available
3104 there for use as a temporary.
3106 For instructions that require a temporary register, you should use
3107 @code{scratch} instead of a pseudo-register because this will allow the
3108 combiner phase to add the @code{clobber} when required. You do this by
3109 coding (@code{clobber} (@code{match_scratch} @dots{})). If you do
3110 clobber a pseudo register, use one which appears nowhere else---generate
3111 a new one each time. Otherwise, you may confuse CSE@.
3113 There is one other known use for clobbering a pseudo register in a
3114 @code{parallel}: when one of the input operands of the insn is also
3115 clobbered by the insn. In this case, using the same pseudo register in
3116 the clobber and elsewhere in the insn produces the expected results.
3120 Represents the use of the value of @var{x}. It indicates that the
3121 value in @var{x} at this point in the program is needed, even though
3122 it may not be apparent why this is so. Therefore, the compiler will
3123 not attempt to delete previous instructions whose only effect is to
3124 store a value in @var{x}. @var{x} must be a @code{reg} expression.
3126 In some situations, it may be tempting to add a @code{use} of a
3127 register in a @code{parallel} to describe a situation where the value
3128 of a special register will modify the behavior of the instruction.
3129 A hypothetical example might be a pattern for an addition that can
3130 either wrap around or use saturating addition depending on the value
3131 of a special control register:
3134 (parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
3141 This will not work, several of the optimizers only look at expressions
3142 locally; it is very likely that if you have multiple insns with
3143 identical inputs to the @code{unspec}, they will be optimized away even
3144 if register 1 changes in between.
3146 This means that @code{use} can @emph{only} be used to describe
3147 that the register is live. You should think twice before adding
3148 @code{use} statements, more often you will want to use @code{unspec}
3149 instead. The @code{use} RTX is most commonly useful to describe that
3150 a fixed register is implicitly used in an insn. It is also safe to use
3151 in patterns where the compiler knows for other reasons that the result
3152 of the whole pattern is variable, such as @samp{movmem@var{m}} or
3153 @samp{call} patterns.
3155 During the reload phase, an insn that has a @code{use} as pattern
3156 can carry a reg_equal note. These @code{use} insns will be deleted
3157 before the reload phase exits.
3159 During the delayed branch scheduling phase, @var{x} may be an insn.
3160 This indicates that @var{x} previously was located at this place in the
3161 code and its data dependencies need to be taken into account. These
3162 @code{use} insns will be deleted before the delayed branch scheduling
3166 @item (parallel [@var{x0} @var{x1} @dots{}])
3167 Represents several side effects performed in parallel. The square
3168 brackets stand for a vector; the operand of @code{parallel} is a
3169 vector of expressions. @var{x0}, @var{x1} and so on are individual
3170 side effect expressions---expressions of code @code{set}, @code{call},
3171 @code{return}, @code{simple_return}, @code{clobber} or @code{use}.
3173 ``In parallel'' means that first all the values used in the individual
3174 side-effects are computed, and second all the actual side-effects are
3175 performed. For example,
3178 (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
3179 (set (mem:SI (reg:SI 1)) (reg:SI 1))])
3183 says unambiguously that the values of hard register 1 and the memory
3184 location addressed by it are interchanged. In both places where
3185 @code{(reg:SI 1)} appears as a memory address it refers to the value
3186 in register 1 @emph{before} the execution of the insn.
3188 It follows that it is @emph{incorrect} to use @code{parallel} and
3189 expect the result of one @code{set} to be available for the next one.
3190 For example, people sometimes attempt to represent a jump-if-zero
3191 instruction this way:
3194 (parallel [(set (cc0) (reg:SI 34))
3195 (set (pc) (if_then_else
3196 (eq (cc0) (const_int 0))
3202 But this is incorrect, because it says that the jump condition depends
3203 on the condition code value @emph{before} this instruction, not on the
3204 new value that is set by this instruction.
3206 @cindex peephole optimization, RTL representation
3207 Peephole optimization, which takes place together with final assembly
3208 code output, can produce insns whose patterns consist of a @code{parallel}
3209 whose elements are the operands needed to output the resulting
3210 assembler code---often @code{reg}, @code{mem} or constant expressions.
3211 This would not be well-formed RTL at any other stage in compilation,
3212 but it is OK then because no further optimization remains to be done.
3213 However, the definition of the macro @code{NOTICE_UPDATE_CC}, if
3214 any, must deal with such insns if you define any peephole optimizations.
3217 @item (cond_exec [@var{cond} @var{expr}])
3218 Represents a conditionally executed expression. The @var{expr} is
3219 executed only if the @var{cond} is nonzero. The @var{cond} expression
3220 must not have side-effects, but the @var{expr} may very well have
3224 @item (sequence [@var{insns} @dots{}])
3225 Represents a sequence of insns. If a @code{sequence} appears in the
3226 chain of insns, then each of the @var{insns} that appears in the sequence
3227 must be suitable for appearing in the chain of insns, i.e. must satisfy
3228 the @code{INSN_P} predicate.
3230 After delay-slot scheduling is completed, an insn and all the insns that
3231 reside in its delay slots are grouped together into a @code{sequence}.
3232 The insn requiring the delay slot is the first insn in the vector;
3233 subsequent insns are to be placed in the delay slot.
3235 @code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
3236 indicate that a branch insn should be used that will conditionally annul
3237 the effect of the insns in the delay slots. In such a case,
3238 @code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
3239 the branch and should be executed only if the branch is taken; otherwise
3240 the insn should be executed only if the branch is not taken.
3243 Some back ends also use @code{sequence} objects for purposes other than
3244 delay-slot groups. This is not supported in the common parts of the
3245 compiler, which treat such sequences as delay-slot groups.
3247 DWARF2 Call Frame Address (CFA) adjustments are sometimes also expressed
3248 using @code{sequence} objects as the value of a @code{RTX_FRAME_RELATED_P}
3249 note. This only happens if the CFA adjustments cannot be easily derived
3250 from the pattern of the instruction to which the note is attached. In
3251 such cases, the value of the note is used instead of best-guesing the
3252 semantics of the instruction. The back end can attach notes containing
3253 a @code{sequence} of @code{set} patterns that express the effect of the
3257 These expression codes appear in place of a side effect, as the body of
3258 an insn, though strictly speaking they do not always describe side
3263 @item (asm_input @var{s})
3264 Represents literal assembler code as described by the string @var{s}.
3267 @findex unspec_volatile
3268 @item (unspec [@var{operands} @dots{}] @var{index})
3269 @itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
3270 Represents a machine-specific operation on @var{operands}. @var{index}
3271 selects between multiple machine-specific operations.
3272 @code{unspec_volatile} is used for volatile operations and operations
3273 that may trap; @code{unspec} is used for other operations.
3275 These codes may appear inside a @code{pattern} of an
3276 insn, inside a @code{parallel}, or inside an expression.
3279 @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
3280 Represents a table of jump addresses. The vector elements @var{lr0},
3281 etc., are @code{label_ref} expressions. The mode @var{m} specifies
3282 how much space is given to each address; normally @var{m} would be
3285 @findex addr_diff_vec
3286 @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags})
3287 Represents a table of jump addresses expressed as offsets from
3288 @var{base}. The vector elements @var{lr0}, etc., are @code{label_ref}
3289 expressions and so is @var{base}. The mode @var{m} specifies how much
3290 space is given to each address-difference. @var{min} and @var{max}
3291 are set up by branch shortening and hold a label with a minimum and a
3292 maximum address, respectively. @var{flags} indicates the relative
3293 position of @var{base}, @var{min} and @var{max} to the containing insn
3294 and of @var{min} and @var{max} to @var{base}. See rtl.def for details.
3297 @item (prefetch:@var{m} @var{addr} @var{rw} @var{locality})
3298 Represents prefetch of memory at address @var{addr}.
3299 Operand @var{rw} is 1 if the prefetch is for data to be written, 0 otherwise;
3300 targets that do not support write prefetches should treat this as a normal
3302 Operand @var{locality} specifies the amount of temporal locality; 0 if there
3303 is none or 1, 2, or 3 for increasing levels of temporal locality;
3304 targets that do not support locality hints should ignore this.
3306 This insn is used to minimize cache-miss latency by moving data into a
3307 cache before it is accessed. It should use only non-faulting data prefetch
3312 @section Embedded Side-Effects on Addresses
3313 @cindex RTL preincrement
3314 @cindex RTL postincrement
3315 @cindex RTL predecrement
3316 @cindex RTL postdecrement
3318 Six special side-effect expression codes appear as memory addresses.
3322 @item (pre_dec:@var{m} @var{x})
3323 Represents the side effect of decrementing @var{x} by a standard
3324 amount and represents also the value that @var{x} has after being
3325 decremented. @var{x} must be a @code{reg} or @code{mem}, but most
3326 machines allow only a @code{reg}. @var{m} must be the machine mode
3327 for pointers on the machine in use. The amount @var{x} is decremented
3328 by is the length in bytes of the machine mode of the containing memory
3329 reference of which this expression serves as the address. Here is an
3333 (mem:DF (pre_dec:SI (reg:SI 39)))
3337 This says to decrement pseudo register 39 by the length of a @code{DFmode}
3338 value and use the result to address a @code{DFmode} value.
3341 @item (pre_inc:@var{m} @var{x})
3342 Similar, but specifies incrementing @var{x} instead of decrementing it.
3345 @item (post_dec:@var{m} @var{x})
3346 Represents the same side effect as @code{pre_dec} but a different
3347 value. The value represented here is the value @var{x} has @i{before}
3351 @item (post_inc:@var{m} @var{x})
3352 Similar, but specifies incrementing @var{x} instead of decrementing it.
3355 @item (post_modify:@var{m} @var{x} @var{y})
3357 Represents the side effect of setting @var{x} to @var{y} and
3358 represents @var{x} before @var{x} is modified. @var{x} must be a
3359 @code{reg} or @code{mem}, but most machines allow only a @code{reg}.
3360 @var{m} must be the machine mode for pointers on the machine in use.
3362 The expression @var{y} must be one of three forms:
3363 @code{(plus:@var{m} @var{x} @var{z})},
3364 @code{(minus:@var{m} @var{x} @var{z})}, or
3365 @code{(plus:@var{m} @var{x} @var{i})},
3366 where @var{z} is an index register and @var{i} is a constant.
3368 Here is an example of its use:
3371 (mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
3375 This says to modify pseudo register 42 by adding the contents of pseudo
3376 register 48 to it, after the use of what ever 42 points to.
3379 @item (pre_modify:@var{m} @var{x} @var{expr})
3380 Similar except side effects happen before the use.
3383 These embedded side effect expressions must be used with care. Instruction
3384 patterns may not use them. Until the @samp{flow} pass of the compiler,
3385 they may occur only to represent pushes onto the stack. The @samp{flow}
3386 pass finds cases where registers are incremented or decremented in one
3387 instruction and used as an address shortly before or after; these cases are
3388 then transformed to use pre- or post-increment or -decrement.
3390 If a register used as the operand of these expressions is used in
3391 another address in an insn, the original value of the register is used.
3392 Uses of the register outside of an address are not permitted within the
3393 same insn as a use in an embedded side effect expression because such
3394 insns behave differently on different machines and hence must be treated
3395 as ambiguous and disallowed.
3397 An instruction that can be represented with an embedded side effect
3398 could also be represented using @code{parallel} containing an additional
3399 @code{set} to describe how the address register is altered. This is not
3400 done because machines that allow these operations at all typically
3401 allow them wherever a memory address is called for. Describing them as
3402 additional parallel stores would require doubling the number of entries
3403 in the machine description.
3406 @section Assembler Instructions as Expressions
3407 @cindex assembler instructions in RTL
3409 @cindex @code{asm_operands}, usage
3410 The RTX code @code{asm_operands} represents a value produced by a
3411 user-specified assembler instruction. It is used to represent
3412 an @code{asm} statement with arguments. An @code{asm} statement with
3413 a single output operand, like this:
3416 asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
3420 is represented using a single @code{asm_operands} RTX which represents
3421 the value that is stored in @code{outputvar}:
3424 (set @var{rtx-for-outputvar}
3425 (asm_operands "foo %1,%2,%0" "a" 0
3426 [@var{rtx-for-addition-result} @var{rtx-for-*z}]
3427 [(asm_input:@var{m1} "g")
3428 (asm_input:@var{m2} "di")]))
3432 Here the operands of the @code{asm_operands} RTX are the assembler
3433 template string, the output-operand's constraint, the index-number of the
3434 output operand among the output operands specified, a vector of input
3435 operand RTX's, and a vector of input-operand modes and constraints. The
3436 mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
3439 When an @code{asm} statement has multiple output values, its insn has
3440 several such @code{set} RTX's inside of a @code{parallel}. Each @code{set}
3441 contains an @code{asm_operands}; all of these share the same assembler
3442 template and vectors, but each contains the constraint for the respective
3443 output operand. They are also distinguished by the output-operand index
3444 number, which is 0, 1, @dots{} for successive output operands.
3446 @node Debug Information
3447 @section Variable Location Debug Information in RTL
3448 @cindex Variable Location Debug Information in RTL
3450 Variable tracking relies on @code{MEM_EXPR} and @code{REG_EXPR}
3451 annotations to determine what user variables memory and register
3452 references refer to.
3454 Variable tracking at assignments uses these notes only when they refer
3455 to variables that live at fixed locations (e.g., addressable
3456 variables, global non-automatic variables). For variables whose
3457 location may vary, it relies on the following types of notes.
3460 @findex var_location
3461 @item (var_location:@var{mode} @var{var} @var{exp} @var{stat})
3462 Binds variable @code{var}, a tree, to value @var{exp}, an RTL
3463 expression. It appears only in @code{NOTE_INSN_VAR_LOCATION} and
3464 @code{DEBUG_INSN}s, with slightly different meanings. @var{mode}, if
3465 present, represents the mode of @var{exp}, which is useful if it is a
3466 modeless expression. @var{stat} is only meaningful in notes,
3467 indicating whether the variable is known to be initialized or
3471 @item (debug_expr:@var{mode} @var{decl})
3472 Stands for the value bound to the @code{DEBUG_EXPR_DECL} @var{decl},
3473 that points back to it, within value expressions in
3474 @code{VAR_LOCATION} nodes.
3476 @findex debug_implicit_ptr
3477 @item (debug_implicit_ptr:@var{mode} @var{decl})
3478 Stands for the location of a @var{decl} that is no longer addressable.
3481 @item (entry_value:@var{mode} @var{decl})
3482 Stands for the value a @var{decl} had at the entry point of the
3483 containing function.
3485 @findex debug_parameter_ref
3486 @item (debug_parameter_ref:@var{mode} @var{decl})
3487 Refers to a parameter that was completely optimized out.
3489 @findex debug_marker
3490 @item (debug_marker:@var{mode})
3491 Marks a program location. With @code{VOIDmode}, it stands for the
3492 beginning of a statement, a recommended inspection point logically after
3493 all prior side effects, and before any subsequent side effects.
3501 The RTL representation of the code for a function is a doubly-linked
3502 chain of objects called @dfn{insns}. Insns are expressions with
3503 special codes that are used for no other purpose. Some insns are
3504 actual instructions; others represent dispatch tables for @code{switch}
3505 statements; others represent labels to jump to or various sorts of
3506 declarative information.
3508 In addition to its own specific data, each insn must have a unique
3509 id-number that distinguishes it from all other insns in the current
3510 function (after delayed branch scheduling, copies of an insn with the
3511 same id-number may be present in multiple places in a function, but
3512 these copies will always be identical and will only appear inside a
3513 @code{sequence}), and chain pointers to the preceding and following
3514 insns. These three fields occupy the same position in every insn,
3515 independent of the expression code of the insn. They could be accessed
3516 with @code{XEXP} and @code{XINT}, but instead three special macros are
3521 @item INSN_UID (@var{i})
3522 Accesses the unique id of insn @var{i}.
3525 @item PREV_INSN (@var{i})
3526 Accesses the chain pointer to the insn preceding @var{i}.
3527 If @var{i} is the first insn, this is a null pointer.
3530 @item NEXT_INSN (@var{i})
3531 Accesses the chain pointer to the insn following @var{i}.
3532 If @var{i} is the last insn, this is a null pointer.
3536 @findex get_last_insn
3537 The first insn in the chain is obtained by calling @code{get_insns}; the
3538 last insn is the result of calling @code{get_last_insn}. Within the
3539 chain delimited by these insns, the @code{NEXT_INSN} and
3540 @code{PREV_INSN} pointers must always correspond: if @var{insn} is not
3544 NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
3548 is always true and if @var{insn} is not the last insn,
3551 PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
3557 After delay slot scheduling, some of the insns in the chain might be
3558 @code{sequence} expressions, which contain a vector of insns. The value
3559 of @code{NEXT_INSN} in all but the last of these insns is the next insn
3560 in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
3561 is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
3562 which it is contained. Similar rules apply for @code{PREV_INSN}.
3564 This means that the above invariants are not necessarily true for insns
3565 inside @code{sequence} expressions. Specifically, if @var{insn} is the
3566 first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
3567 is the insn containing the @code{sequence} expression, as is the value
3568 of @code{PREV_INSN (NEXT_INSN (@var{insn}))} if @var{insn} is the last
3569 insn in the @code{sequence} expression. You can use these expressions
3570 to find the containing @code{sequence} expression.
3572 Every insn has one of the following expression codes:
3577 The expression code @code{insn} is used for instructions that do not jump
3578 and do not do function calls. @code{sequence} expressions are always
3579 contained in insns with code @code{insn} even if one of those insns
3580 should jump or do function calls.
3582 Insns with code @code{insn} have four additional fields beyond the three
3583 mandatory ones listed above. These four are described in a table below.
3587 The expression code @code{jump_insn} is used for instructions that may
3588 jump (or, more generally, may contain @code{label_ref} expressions to
3589 which @code{pc} can be set in that instruction). If there is an
3590 instruction to return from the current function, it is recorded as a
3594 @code{jump_insn} insns have the same extra fields as @code{insn} insns,
3595 accessed in the same way and in addition contain a field
3596 @code{JUMP_LABEL} which is defined once jump optimization has completed.
3598 For simple conditional and unconditional jumps, this field contains
3599 the @code{code_label} to which this insn will (possibly conditionally)
3600 branch. In a more complex jump, @code{JUMP_LABEL} records one of the
3601 labels that the insn refers to; other jump target labels are recorded
3602 as @code{REG_LABEL_TARGET} notes. The exception is @code{addr_vec}
3603 and @code{addr_diff_vec}, where @code{JUMP_LABEL} is @code{NULL_RTX}
3604 and the only way to find the labels is to scan the entire body of the
3607 Return insns count as jumps, but their @code{JUMP_LABEL} is @code{RETURN}
3608 or @code{SIMPLE_RETURN}.
3612 The expression code @code{call_insn} is used for instructions that may do
3613 function calls. It is important to distinguish these instructions because
3614 they imply that certain registers and memory locations may be altered
3617 @findex CALL_INSN_FUNCTION_USAGE
3618 @code{call_insn} insns have the same extra fields as @code{insn} insns,
3619 accessed in the same way and in addition contain a field
3620 @code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of
3621 @code{expr_list} expressions) containing @code{use}, @code{clobber} and
3622 sometimes @code{set} expressions that denote hard registers and
3623 @code{mem}s used or clobbered by the called function.
3625 A @code{mem} generally points to a stack slot in which arguments passed
3626 to the libcall by reference (@pxref{Register Arguments,
3627 TARGET_PASS_BY_REFERENCE}) are stored. If the argument is
3628 caller-copied (@pxref{Register Arguments, TARGET_CALLEE_COPIES}),
3629 the stack slot will be mentioned in @code{clobber} and @code{use}
3630 entries; if it's callee-copied, only a @code{use} will appear, and the
3631 @code{mem} may point to addresses that are not stack slots.
3633 Registers occurring inside a @code{clobber} in this list augment
3634 registers specified in @code{CALL_USED_REGISTERS} (@pxref{Register
3637 If the list contains a @code{set} involving two registers, it indicates
3638 that the function returns one of its arguments. Such a @code{set} may
3639 look like a no-op if the same register holds the argument and the return
3643 @findex CODE_LABEL_NUMBER
3645 A @code{code_label} insn represents a label that a jump insn can jump
3646 to. It contains two special fields of data in addition to the three
3647 standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
3648 number}, a number that identifies this label uniquely among all the
3649 labels in the compilation (not just in the current function).
3650 Ultimately, the label is represented in the assembler output as an
3651 assembler label, usually of the form @samp{L@var{n}} where @var{n} is
3654 When a @code{code_label} appears in an RTL expression, it normally
3655 appears within a @code{label_ref} which represents the address of
3656 the label, as a number.
3658 Besides as a @code{code_label}, a label can also be represented as a
3659 @code{note} of type @code{NOTE_INSN_DELETED_LABEL}.
3662 The field @code{LABEL_NUSES} is only defined once the jump optimization
3663 phase is completed. It contains the number of times this label is
3664 referenced in the current function.
3667 @findex SET_LABEL_KIND
3668 @findex LABEL_ALT_ENTRY_P
3669 @cindex alternate entry points
3670 The field @code{LABEL_KIND} differentiates four different types of
3671 labels: @code{LABEL_NORMAL}, @code{LABEL_STATIC_ENTRY},
3672 @code{LABEL_GLOBAL_ENTRY}, and @code{LABEL_WEAK_ENTRY}. The only labels
3673 that do not have type @code{LABEL_NORMAL} are @dfn{alternate entry
3674 points} to the current function. These may be static (visible only in
3675 the containing translation unit), global (exposed to all translation
3676 units), or weak (global, but can be overridden by another symbol with the
3679 Much of the compiler treats all four kinds of label identically. Some
3680 of it needs to know whether or not a label is an alternate entry point;
3681 for this purpose, the macro @code{LABEL_ALT_ENTRY_P} is provided. It is
3682 equivalent to testing whether @samp{LABEL_KIND (label) == LABEL_NORMAL}.
3683 The only place that cares about the distinction between static, global,
3684 and weak alternate entry points, besides the front-end code that creates
3685 them, is the function @code{output_alternate_entry_point}, in
3688 To set the kind of a label, use the @code{SET_LABEL_KIND} macro.
3690 @findex jump_table_data
3691 @item jump_table_data
3692 A @code{jump_table_data} insn is a placeholder for the jump-table data
3693 of a @code{casesi} or @code{tablejump} insn. They are placed after
3694 a @code{tablejump_p} insn. A @code{jump_table_data} insn is not part o
3695 a basic blockm but it is associated with the basic block that ends with
3696 the @code{tablejump_p} insn. The @code{PATTERN} of a @code{jump_table_data}
3697 is always either an @code{addr_vec} or an @code{addr_diff_vec}, and a
3698 @code{jump_table_data} insn is always preceded by a @code{code_label}.
3699 The @code{tablejump_p} insn refers to that @code{code_label} via its
3704 Barriers are placed in the instruction stream when control cannot flow
3705 past them. They are placed after unconditional jump instructions to
3706 indicate that the jumps are unconditional and after calls to
3707 @code{volatile} functions, which do not return (e.g., @code{exit}).
3708 They contain no information beyond the three standard fields.
3711 @findex NOTE_LINE_NUMBER
3712 @findex NOTE_SOURCE_FILE
3714 @code{note} insns are used to represent additional debugging and
3715 declarative information. They contain two nonstandard fields, an
3716 integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
3717 string accessed with @code{NOTE_SOURCE_FILE}.
3719 If @code{NOTE_LINE_NUMBER} is positive, the note represents the
3720 position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
3721 that the line came from. These notes control generation of line
3722 number data in the assembler output.
3724 Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
3725 code with one of the following values (and @code{NOTE_SOURCE_FILE}
3726 must contain a null pointer):
3729 @findex NOTE_INSN_DELETED
3730 @item NOTE_INSN_DELETED
3731 Such a note is completely ignorable. Some passes of the compiler
3732 delete insns by altering them into notes of this kind.
3734 @findex NOTE_INSN_DELETED_LABEL
3735 @item NOTE_INSN_DELETED_LABEL
3736 This marks what used to be a @code{code_label}, but was not used for other
3737 purposes than taking its address and was transformed to mark that no
3740 @findex NOTE_INSN_BLOCK_BEG
3741 @findex NOTE_INSN_BLOCK_END
3742 @item NOTE_INSN_BLOCK_BEG
3743 @itemx NOTE_INSN_BLOCK_END
3744 These types of notes indicate the position of the beginning and end
3745 of a level of scoping of variable names. They control the output
3746 of debugging information.
3748 @findex NOTE_INSN_EH_REGION_BEG
3749 @findex NOTE_INSN_EH_REGION_END
3750 @item NOTE_INSN_EH_REGION_BEG
3751 @itemx NOTE_INSN_EH_REGION_END
3752 These types of notes indicate the position of the beginning and end of a
3753 level of scoping for exception handling. @code{NOTE_EH_HANDLER}
3754 identifies which region is associated with these notes.
3756 @findex NOTE_INSN_FUNCTION_BEG
3757 @item NOTE_INSN_FUNCTION_BEG
3758 Appears at the start of the function body, after the function
3761 @findex NOTE_INSN_VAR_LOCATION
3762 @findex NOTE_VAR_LOCATION
3763 @item NOTE_INSN_VAR_LOCATION
3764 This note is used to generate variable location debugging information.
3765 It indicates that the user variable in its @code{VAR_LOCATION} operand
3766 is at the location given in the RTL expression, or holds a value that
3767 can be computed by evaluating the RTL expression from that static
3768 point in the program up to the next such note for the same user
3771 @findex NOTE_INSN_BEGIN_STMT
3772 @item NOTE_INSN_BEGIN_STMT
3773 This note is used to generate @code{is_stmt} markers in line number
3774 debuggign information. It indicates the beginning of a user
3779 These codes are printed symbolically when they appear in debugging dumps.
3782 @findex INSN_VAR_LOCATION
3784 The expression code @code{debug_insn} is used for pseudo-instructions
3785 that hold debugging information for variable tracking at assignments
3786 (see @option{-fvar-tracking-assignments} option). They are the RTL
3787 representation of @code{GIMPLE_DEBUG} statements
3788 (@ref{@code{GIMPLE_DEBUG}}), with a @code{VAR_LOCATION} operand that
3789 binds a user variable tree to an RTL representation of the
3790 @code{value} in the corresponding statement. A @code{DEBUG_EXPR} in
3791 it stands for the value bound to the corresponding
3792 @code{DEBUG_EXPR_DECL}.
3794 @code{GIMPLE_DEBUG_BEGIN_STMT} is expanded to RTL as a @code{DEBUG_INSN}
3795 with a @code{VOIDmode} @code{DEBUG_MARKER} @code{PATTERN}. These
3796 @code{DEBUG_INSN}s, that do not carry @code{VAR_LOCATION} information,
3797 just @code{DEBUG_MARKER}s, can be detected by testing
3798 @code{DEBUG_MARKER_INSN_P}, whereas those that do can be recognized as
3799 @code{DEBUG_BIND_INSN_P}.
3801 Throughout optimization passes, @code{DEBUG_INSN}s are not reordered
3802 with respect to each other, particularly during scheduling. Binding
3803 information is kept in pseudo-instruction form, so that, unlike notes,
3804 it gets the same treatment and adjustments that regular instructions
3805 would. It is the variable tracking pass that turns these
3806 pseudo-instructions into @code{NOTE_INSN_VAR_LOCATION} and
3807 @code{NOTE_INSN_BEGIN_STMT} notes,
3808 analyzing control flow, value equivalences and changes to registers and
3809 memory referenced in value expressions, propagating the values of debug
3810 temporaries and determining expressions that can be used to compute the
3811 value of each user variable at as many points (ranges, actually) in the
3812 program as possible.
3814 Unlike @code{NOTE_INSN_VAR_LOCATION}, the value expression in an
3815 @code{INSN_VAR_LOCATION} denotes a value at that specific point in the
3816 program, rather than an expression that can be evaluated at any later
3817 point before an overriding @code{VAR_LOCATION} is encountered. E.g.,
3818 if a user variable is bound to a @code{REG} and then a subsequent insn
3819 modifies the @code{REG}, the note location would keep mapping the user
3820 variable to the register across the insn, whereas the insn location
3821 would keep the variable bound to the value, so that the variable
3822 tracking pass would emit another location note for the variable at the
3823 point in which the register is modified.
3827 @cindex @code{TImode}, in @code{insn}
3828 @cindex @code{HImode}, in @code{insn}
3829 @cindex @code{QImode}, in @code{insn}
3830 The machine mode of an insn is normally @code{VOIDmode}, but some
3831 phases use the mode for various purposes.
3833 The common subexpression elimination pass sets the mode of an insn to
3834 @code{QImode} when it is the first insn in a block that has already
3837 The second Haifa scheduling pass, for targets that can multiple issue,
3838 sets the mode of an insn to @code{TImode} when it is believed that the
3839 instruction begins an issue group. That is, when the instruction
3840 cannot issue simultaneously with the previous. This may be relied on
3841 by later passes, in particular machine-dependent reorg.
3843 Here is a table of the extra fields of @code{insn}, @code{jump_insn}
3844 and @code{call_insn} insns:
3848 @item PATTERN (@var{i})
3849 An expression for the side effect performed by this insn. This must
3850 be one of the following codes: @code{set}, @code{call}, @code{use},
3851 @code{clobber}, @code{return}, @code{simple_return}, @code{asm_input},
3852 @code{asm_output}, @code{addr_vec}, @code{addr_diff_vec},
3853 @code{trap_if}, @code{unspec}, @code{unspec_volatile},
3854 @code{parallel}, @code{cond_exec}, or @code{sequence}. If it is a
3855 @code{parallel}, each element of the @code{parallel} must be one these
3856 codes, except that @code{parallel} expressions cannot be nested and
3857 @code{addr_vec} and @code{addr_diff_vec} are not permitted inside a
3858 @code{parallel} expression.
3861 @item INSN_CODE (@var{i})
3862 An integer that says which pattern in the machine description matches
3863 this insn, or @minus{}1 if the matching has not yet been attempted.
3865 Such matching is never attempted and this field remains @minus{}1 on an insn
3866 whose pattern consists of a single @code{use}, @code{clobber},
3867 @code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.
3869 @findex asm_noperands
3870 Matching is also never attempted on insns that result from an @code{asm}
3871 statement. These contain at least one @code{asm_operands} expression.
3872 The function @code{asm_noperands} returns a non-negative value for
3875 In the debugging output, this field is printed as a number followed by
3876 a symbolic representation that locates the pattern in the @file{md}
3877 file as some small positive or negative offset from a named pattern.
3880 @item LOG_LINKS (@var{i})
3881 A list (chain of @code{insn_list} expressions) giving information about
3882 dependencies between instructions within a basic block. Neither a jump
3883 nor a label may come between the related insns. These are only used by
3884 the schedulers and by combine. This is a deprecated data structure.
3885 Def-use and use-def chains are now preferred.
3888 @item REG_NOTES (@var{i})
3889 A list (chain of @code{expr_list}, @code{insn_list} and @code{int_list}
3890 expressions) giving miscellaneous information about the insn. It is often
3891 information pertaining to the registers used in this insn.
3894 The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
3895 expressions. Each of these has two operands: the first is an insn,
3896 and the second is another @code{insn_list} expression (the next one in
3897 the chain). The last @code{insn_list} in the chain has a null pointer
3898 as second operand. The significant thing about the chain is which
3899 insns appear in it (as first operands of @code{insn_list}
3900 expressions). Their order is not significant.
3902 This list is originally set up by the flow analysis pass; it is a null
3903 pointer until then. Flow only adds links for those data dependencies
3904 which can be used for instruction combination. For each insn, the flow
3905 analysis pass adds a link to insns which store into registers values
3906 that are used for the first time in this insn.
3908 The @code{REG_NOTES} field of an insn is a chain similar to the
3909 @code{LOG_LINKS} field but it includes @code{expr_list} and @code{int_list}
3910 expressions in addition to @code{insn_list} expressions. There are several
3911 kinds of register notes, which are distinguished by the machine mode, which
3912 in a register note is really understood as being an @code{enum reg_note}.
3913 The first operand @var{op} of the note is data whose meaning depends on
3916 @findex REG_NOTE_KIND
3917 @findex PUT_REG_NOTE_KIND
3918 The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of
3919 register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND
3920 (@var{x}, @var{newkind})} sets the register note type of @var{x} to be
3923 Register notes are of three classes: They may say something about an
3924 input to an insn, they may say something about an output of an insn, or
3925 they may create a linkage between two insns. There are also a set
3926 of values that are only used in @code{LOG_LINKS}.
3928 These register notes annotate inputs to an insn:
3933 The value in @var{op} dies in this insn; that is to say, altering the
3934 value immediately after this insn would not affect the future behavior
3937 It does not follow that the register @var{op} has no useful value after
3938 this insn since @var{op} is not necessarily modified by this insn.
3939 Rather, no subsequent instruction uses the contents of @var{op}.
3943 The register @var{op} being set by this insn will not be used in a
3944 subsequent insn. This differs from a @code{REG_DEAD} note, which
3945 indicates that the value in an input will not be used subsequently.
3946 These two notes are independent; both may be present for the same
3951 The register @var{op} is incremented (or decremented; at this level
3952 there is no distinction) by an embedded side effect inside this insn.
3953 This means it appears in a @code{post_inc}, @code{pre_inc},
3954 @code{post_dec} or @code{pre_dec} expression.
3958 The register @var{op} is known to have a nonnegative value when this
3959 insn is reached. This is used so that decrement and branch until zero
3960 instructions, such as the m68k dbra, can be matched.
3962 The @code{REG_NONNEG} note is added to insns only if the machine
3963 description has a @samp{decrement_and_branch_until_zero} pattern.
3965 @findex REG_LABEL_OPERAND
3966 @item REG_LABEL_OPERAND
3967 This insn uses @var{op}, a @code{code_label} or a @code{note} of type
3968 @code{NOTE_INSN_DELETED_LABEL}, but is not a @code{jump_insn}, or it
3969 is a @code{jump_insn} that refers to the operand as an ordinary
3970 operand. The label may still eventually be a jump target, but if so
3971 in an indirect jump in a subsequent insn. The presence of this note
3972 allows jump optimization to be aware that @var{op} is, in fact, being
3973 used, and flow optimization to build an accurate flow graph.
3975 @findex REG_LABEL_TARGET
3976 @item REG_LABEL_TARGET
3977 This insn is a @code{jump_insn} but not an @code{addr_vec} or
3978 @code{addr_diff_vec}. It uses @var{op}, a @code{code_label} as a
3979 direct or indirect jump target. Its purpose is similar to that of
3980 @code{REG_LABEL_OPERAND}. This note is only present if the insn has
3981 multiple targets; the last label in the insn (in the highest numbered
3982 insn-field) goes into the @code{JUMP_LABEL} field and does not have a
3983 @code{REG_LABEL_TARGET} note. @xref{Insns, JUMP_LABEL}.
3987 Appears attached to each @code{CALL_INSN} to @code{setjmp} or a
3991 The following notes describe attributes of outputs of an insn:
3998 This note is only valid on an insn that sets only one register and
3999 indicates that that register will be equal to @var{op} at run time; the
4000 scope of this equivalence differs between the two types of notes. The
4001 value which the insn explicitly copies into the register may look
4002 different from @var{op}, but they will be equal at run time. If the
4003 output of the single @code{set} is a @code{strict_low_part} or
4004 @code{zero_extract} expression, the note refers to the register that
4005 is contained in its first operand.
4007 For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout
4008 the entire function, and could validly be replaced in all its
4009 occurrences by @var{op}. (``Validly'' here refers to the data flow of
4010 the program; simple replacement may make some insns invalid.) For
4011 example, when a constant is loaded into a register that is never
4012 assigned any other value, this kind of note is used.
4014 When a parameter is copied into a pseudo-register at entry to a function,
4015 a note of this kind records that the register is equivalent to the stack
4016 slot where the parameter was passed. Although in this case the register
4017 may be set by other insns, it is still valid to replace the register
4018 by the stack slot throughout the function.
4020 A @code{REG_EQUIV} note is also used on an instruction which copies a
4021 register parameter into a pseudo-register at entry to a function, if
4022 there is a stack slot where that parameter could be stored. Although
4023 other insns may set the pseudo-register, it is valid for the compiler to
4024 replace the pseudo-register by stack slot throughout the function,
4025 provided the compiler ensures that the stack slot is properly
4026 initialized by making the replacement in the initial copy instruction as
4027 well. This is used on machines for which the calling convention
4028 allocates stack space for register parameters. See
4029 @code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}.
4031 In the case of @code{REG_EQUAL}, the register that is set by this insn
4032 will be equal to @var{op} at run time at the end of this insn but not
4033 necessarily elsewhere in the function. In this case, @var{op}
4034 is typically an arithmetic expression. For example, when a sequence of
4035 insns such as a library call is used to perform an arithmetic operation,
4036 this kind of note is attached to the insn that produces or copies the
4039 These two notes are used in different ways by the compiler passes.
4040 @code{REG_EQUAL} is used by passes prior to register allocation (such as
4041 common subexpression elimination and loop optimization) to tell them how
4042 to think of that value. @code{REG_EQUIV} notes are used by register
4043 allocation to indicate that there is an available substitute expression
4044 (either a constant or a @code{mem} expression for the location of a
4045 parameter on the stack) that may be used in place of a register if
4046 insufficient registers are available.
4048 Except for stack homes for parameters, which are indicated by a
4049 @code{REG_EQUIV} note and are not useful to the early optimization
4050 passes and pseudo registers that are equivalent to a memory location
4051 throughout their entire life, which is not detected until later in
4052 the compilation, all equivalences are initially indicated by an attached
4053 @code{REG_EQUAL} note. In the early stages of register allocation, a
4054 @code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if
4055 @var{op} is a constant and the insn represents the only set of its
4056 destination register.
4058 Thus, compiler passes prior to register allocation need only check for
4059 @code{REG_EQUAL} notes and passes subsequent to register allocation
4060 need only check for @code{REG_EQUIV} notes.
4063 These notes describe linkages between insns. They occur in pairs: one
4064 insn has one of a pair of notes that points to a second insn, which has
4065 the inverse note pointing back to the first insn.
4068 @findex REG_CC_SETTER
4072 On machines that use @code{cc0}, the insns which set and use @code{cc0}
4073 set and use @code{cc0} are adjacent. However, when branch delay slot
4074 filling is done, this may no longer be true. In this case a
4075 @code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to
4076 point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will
4077 be placed on the insn using @code{cc0} to point to the insn setting
4081 These values are only used in the @code{LOG_LINKS} field, and indicate
4082 the type of dependency that each link represents. Links which indicate
4083 a data dependence (a read after write dependence) do not use any code,
4084 they simply have mode @code{VOIDmode}, and are printed without any
4088 @findex REG_DEP_TRUE
4090 This indicates a true dependence (a read after write dependence).
4092 @findex REG_DEP_OUTPUT
4093 @item REG_DEP_OUTPUT
4094 This indicates an output dependence (a write after write dependence).
4096 @findex REG_DEP_ANTI
4098 This indicates an anti dependence (a write after read dependence).
4102 These notes describe information gathered from gcov profile data. They
4103 are stored in the @code{REG_NOTES} field of an insn.
4108 This is used to specify the ratio of branches to non-branches of a
4109 branch insn according to the profile data. The note is represented
4110 as an @code{int_list} expression whose integer value is an encoding
4111 of @code{profile_probability} type. @code{profile_probability} provide
4112 member function @code{from_reg_br_prob_note} and @code{to_reg_br_prob_note}
4113 to extract and store the probability into the RTL encoding.
4117 These notes are found in JUMP insns after delayed branch scheduling
4118 has taken place. They indicate both the direction and the likelihood
4119 of the JUMP@. The format is a bitmask of ATTR_FLAG_* values.
4121 @findex REG_FRAME_RELATED_EXPR
4122 @item REG_FRAME_RELATED_EXPR
4123 This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression
4124 is used in place of the actual insn pattern. This is done in cases where
4125 the pattern is either complex or misleading.
4128 The note @code{REG_CALL_NOCF_CHECK} is used in conjunction with the
4129 @option{-fcf-protection=branch} option. The note is set if a
4130 @code{nocf_check} attribute is specified for a function type or a
4131 pointer to function type. The note is stored in the @code{REG_NOTES}
4135 @findex REG_CALL_NOCF_CHECK
4136 @item REG_CALL_NOCF_CHECK
4137 Users have control through the @code{nocf_check} attribute to identify
4138 which calls to a function should be skipped from control-flow instrumentation
4139 when the option @option{-fcf-protection=branch} is specified. The compiler
4140 puts a @code{REG_CALL_NOCF_CHECK} note on each @code{CALL_INSN} instruction
4141 that has a function type marked with a @code{nocf_check} attribute.
4144 For convenience, the machine mode in an @code{insn_list} or
4145 @code{expr_list} is printed using these symbolic codes in debugging dumps.
4149 The only difference between the expression codes @code{insn_list} and
4150 @code{expr_list} is that the first operand of an @code{insn_list} is
4151 assumed to be an insn and is printed in debugging dumps as the insn's
4152 unique id; the first operand of an @code{expr_list} is printed in the
4153 ordinary way as an expression.
4156 @section RTL Representation of Function-Call Insns
4157 @cindex calling functions in RTL
4158 @cindex RTL function-call insns
4159 @cindex function-call insns
4161 Insns that call subroutines have the RTL expression code @code{call_insn}.
4162 These insns must satisfy special rules, and their bodies must use a special
4163 RTL expression code, @code{call}.
4165 @cindex @code{call} usage
4166 A @code{call} expression has two operands, as follows:
4169 (call (mem:@var{fm} @var{addr}) @var{nbytes})
4173 Here @var{nbytes} is an operand that represents the number of bytes of
4174 argument data being passed to the subroutine, @var{fm} is a machine mode
4175 (which must equal as the definition of the @code{FUNCTION_MODE} macro in
4176 the machine description) and @var{addr} represents the address of the
4179 For a subroutine that returns no value, the @code{call} expression as
4180 shown above is the entire body of the insn, except that the insn might
4181 also contain @code{use} or @code{clobber} expressions.
4183 @cindex @code{BLKmode}, and function return values
4184 For a subroutine that returns a value whose mode is not @code{BLKmode},
4185 the value is returned in a hard register. If this register's number is
4186 @var{r}, then the body of the call insn looks like this:
4189 (set (reg:@var{m} @var{r})
4190 (call (mem:@var{fm} @var{addr}) @var{nbytes}))
4194 This RTL expression makes it clear (to the optimizer passes) that the
4195 appropriate register receives a useful value in this insn.
4197 When a subroutine returns a @code{BLKmode} value, it is handled by
4198 passing to the subroutine the address of a place to store the value.
4199 So the call insn itself does not ``return'' any value, and it has the
4200 same RTL form as a call that returns nothing.
4202 On some machines, the call instruction itself clobbers some register,
4203 for example to contain the return address. @code{call_insn} insns
4204 on these machines should have a body which is a @code{parallel}
4205 that contains both the @code{call} expression and @code{clobber}
4206 expressions that indicate which registers are destroyed. Similarly,
4207 if the call instruction requires some register other than the stack
4208 pointer that is not explicitly mentioned in its RTL, a @code{use}
4209 subexpression should mention that register.
4211 Functions that are called are assumed to modify all registers listed in
4212 the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register
4213 Basics}) and, with the exception of @code{const} functions and library
4214 calls, to modify all of memory.
4216 Insns containing just @code{use} expressions directly precede the
4217 @code{call_insn} insn to indicate which registers contain inputs to the
4218 function. Similarly, if registers other than those in
4219 @code{CALL_USED_REGISTERS} are clobbered by the called function, insns
4220 containing a single @code{clobber} follow immediately after the call to
4221 indicate which registers.
4224 @section Structure Sharing Assumptions
4225 @cindex sharing of RTL components
4226 @cindex RTL structure sharing assumptions
4228 The compiler assumes that certain kinds of RTL expressions are unique;
4229 there do not exist two distinct objects representing the same value.
4230 In other cases, it makes an opposite assumption: that no RTL expression
4231 object of a certain kind appears in more than one place in the
4232 containing structure.
4234 These assumptions refer to a single function; except for the RTL
4235 objects that describe global variables and external functions,
4236 and a few standard objects such as small integer constants,
4237 no RTL objects are common to two functions.
4240 @cindex @code{reg}, RTL sharing
4242 Each pseudo-register has only a single @code{reg} object to represent it,
4243 and therefore only a single machine mode.
4245 @cindex symbolic label
4246 @cindex @code{symbol_ref}, RTL sharing
4248 For any symbolic label, there is only one @code{symbol_ref} object
4251 @cindex @code{const_int}, RTL sharing
4253 All @code{const_int} expressions with equal values are shared.
4255 @cindex @code{const_poly_int}, RTL sharing
4257 All @code{const_poly_int} expressions with equal modes and values
4260 @cindex @code{pc}, RTL sharing
4262 There is only one @code{pc} expression.
4264 @cindex @code{cc0}, RTL sharing
4266 There is only one @code{cc0} expression.
4268 @cindex @code{const_double}, RTL sharing
4270 There is only one @code{const_double} expression with value 0 for
4271 each floating point mode. Likewise for values 1 and 2.
4273 @cindex @code{const_vector}, RTL sharing
4275 There is only one @code{const_vector} expression with value 0 for
4276 each vector mode, be it an integer or a double constant vector.
4278 @cindex @code{label_ref}, RTL sharing
4279 @cindex @code{scratch}, RTL sharing
4281 No @code{label_ref} or @code{scratch} appears in more than one place in
4282 the RTL structure; in other words, it is safe to do a tree-walk of all
4283 the insns in the function and assume that each time a @code{label_ref}
4284 or @code{scratch} is seen it is distinct from all others that are seen.
4286 @cindex @code{mem}, RTL sharing
4288 Only one @code{mem} object is normally created for each static
4289 variable or stack slot, so these objects are frequently shared in all
4290 the places they appear. However, separate but equal objects for these
4291 variables are occasionally made.
4293 @cindex @code{asm_operands}, RTL sharing
4295 When a single @code{asm} statement has multiple output operands, a
4296 distinct @code{asm_operands} expression is made for each output operand.
4297 However, these all share the vector which contains the sequence of input
4298 operands. This sharing is used later on to test whether two
4299 @code{asm_operands} expressions come from the same statement, so all
4300 optimizations must carefully preserve the sharing if they copy the
4304 No RTL object appears in more than one place in the RTL structure
4305 except as described above. Many passes of the compiler rely on this
4306 by assuming that they can modify RTL objects in place without unwanted
4307 side-effects on other insns.
4309 @findex unshare_all_rtl
4311 During initial RTL generation, shared structure is freely introduced.
4312 After all the RTL for a function has been generated, all shared
4313 structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
4314 after which the above rules are guaranteed to be followed.
4316 @findex copy_rtx_if_shared
4318 During the combiner pass, shared structure within an insn can exist
4319 temporarily. However, the shared structure is copied before the
4320 combiner is finished with the insn. This is done by calling
4321 @code{copy_rtx_if_shared}, which is a subroutine of
4322 @code{unshare_all_rtl}.
4326 @section Reading RTL
4328 To read an RTL object from a file, call @code{read_rtx}. It takes one
4329 argument, a stdio stream, and returns a single RTL object. This routine
4330 is defined in @file{read-rtl.c}. It is not available in the compiler
4331 itself, only the various programs that generate the compiler back end
4332 from the machine description.
4334 People frequently have the idea of using RTL stored as text in a file as
4335 an interface between a language front end and the bulk of GCC@. This
4336 idea is not feasible.
4338 GCC was designed to use RTL internally only. Correct RTL for a given
4339 program is very dependent on the particular target machine. And the RTL
4340 does not contain all the information about the program.
4342 The proper way to interface GCC to a new language front end is with
4343 the ``tree'' data structure, described in the files @file{tree.h} and
4344 @file{tree.def}. The documentation for this structure (@pxref{GENERIC})