1 @c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002
2 @c Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
7 @chapter RTL Representation
8 @cindex RTL representation
9 @cindex representation of RTL
10 @cindex Register Transfer Language (RTL)
12 Most of the work of the compiler is done on an intermediate representation
13 called register transfer language. In this language, the instructions to be
14 output are described, pretty much one by one, in an algebraic form that
15 describes what the instruction does.
17 RTL is inspired by Lisp lists. It has both an internal form, made up of
18 structures that point at other structures, and a textual form that is used
19 in the machine description and in printed debugging dumps. The textual
20 form uses nested parentheses to indicate the pointers in the internal form.
23 * RTL Objects:: Expressions vs vectors vs strings vs integers.
24 * RTL Classes:: Categories of RTL expression objects, and their structure.
25 * Accessors:: Macros to access expression operands or vector elts.
26 * 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 * Insns:: Expression types for entire insns.
40 * Calls:: RTL representation of function call insns.
41 * Sharing:: Some expressions are unique; others *must* be copied.
42 * Reading RTL:: Reading textual RTL from a file.
46 @section RTL Object Types
47 @cindex RTL object types
52 @cindex RTL expression
54 RTL uses five kinds of objects: expressions, integers, wide integers,
55 strings and vectors. Expressions are the most important ones. An RTL
56 expression (``RTX'', for short) is a C structure, but it is usually
57 referred to with a pointer; a type that is given the typedef name
60 An integer is simply an @code{int}; their written form uses decimal
61 digits. A wide integer is an integral object whose type is
62 @code{HOST_WIDE_INT}; their written form uses decimal digits.
64 A string is a sequence of characters. In core it is represented as a
65 @code{char *} in usual C fashion, and it is written in C syntax as well.
66 However, strings in RTL may never be null. If you write an empty string in
67 a machine description, it is represented in core as a null pointer rather
68 than as a pointer to a null character. In certain contexts, these null
69 pointers instead of strings are valid. Within RTL code, strings are most
70 commonly found inside @code{symbol_ref} expressions, but they appear in
71 other contexts in the RTL expressions that make up machine descriptions.
73 In a machine description, strings are normally written with double
74 quotes, as you would in C. However, strings in machine descriptions may
75 extend over many lines, which is invalid C, and adjacent string
76 constants are not concatenated as they are in C. Any string constant
77 may be surrounded with a single set of parentheses. Sometimes this
78 makes the machine description easier to read.
80 There is also a special syntax for strings, which can be useful when C
81 code is embedded in a machine description. Wherever a string can
82 appear, it is also valid to write a C-style brace block. The entire
83 brace block, including the outermost pair of braces, is considered to be
84 the string constant. Double quote characters inside the braces are not
85 special. Therefore, if you write string constants in the C code, you
86 need not escape each quote character with a backslash.
88 A vector contains an arbitrary number of pointers to expressions. The
89 number of elements in the vector is explicitly present in the vector.
90 The written form of a vector consists of square brackets
91 (@samp{[@dots{}]}) surrounding the elements, in sequence and with
92 whitespace separating them. Vectors of length zero are not created;
93 null pointers are used instead.
95 @cindex expression codes
96 @cindex codes, RTL expression
99 Expressions are classified by @dfn{expression codes} (also called RTX
100 codes). The expression code is a name defined in @file{rtl.def}, which is
101 also (in upper case) a C enumeration constant. The possible expression
102 codes and their meanings are machine-independent. The code of an RTX can
103 be extracted with the macro @code{GET_CODE (@var{x})} and altered with
104 @code{PUT_CODE (@var{x}, @var{newcode})}.
106 The expression code determines how many operands the expression contains,
107 and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell
108 by looking at an operand what kind of object it is. Instead, you must know
109 from its context---from the expression code of the containing expression.
110 For example, in an expression of code @code{subreg}, the first operand is
111 to be regarded as an expression and the second operand as an integer. In
112 an expression of code @code{plus}, there are two operands, both of which
113 are to be regarded as expressions. In a @code{symbol_ref} expression,
114 there is one operand, which is to be regarded as a string.
116 Expressions are written as parentheses containing the name of the
117 expression type, its flags and machine mode if any, and then the operands
118 of the expression (separated by spaces).
120 Expression code names in the @samp{md} file are written in lower case,
121 but when they appear in C code they are written in upper case. In this
122 manual, they are shown as follows: @code{const_int}.
126 In a few contexts a null pointer is valid where an expression is normally
127 wanted. The written form of this is @code{(nil)}.
130 @section RTL Classes and Formats
132 @cindex classes of RTX codes
133 @cindex RTX codes, classes of
134 @findex GET_RTX_CLASS
136 The various expression codes are divided into several @dfn{classes},
137 which are represented by single characters. You can determine the class
138 of an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}.
139 Currently, @file{rtx.def} defines these classes:
143 An RTX code that represents an actual object, such as a register
144 (@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}).
145 Constants and basic transforms on objects (@code{ADDRESSOF},
146 @code{HIGH}, @code{LO_SUM}) are also included. Note that @code{SUBREG}
147 and @code{STRICT_LOW_PART} are not in this class, but in class @code{x}.
150 An RTX code for a comparison, such as @code{NE} or @code{LT}.
153 An RTX code for a unary arithmetic operation, such as @code{NEG},
154 @code{NOT}, or @code{ABS}. This category also includes value extension
155 (sign or zero) and conversions between integer and floating point.
158 An RTX code for a commutative binary operation, such as @code{PLUS} or
159 @code{AND}. @code{NE} and @code{EQ} are comparisons, so they have class
163 An RTX code for a non-commutative binary operation, such as @code{MINUS},
164 @code{DIV}, or @code{ASHIFTRT}.
167 An RTX code for a bit-field operation. Currently only
168 @code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}. These have three inputs
169 and are lvalues (so they can be used for insertion as well).
173 An RTX code for other three input operations. Currently only
177 An RTX code for an entire instruction: @code{INSN}, @code{JUMP_INSN}, and
178 @code{CALL_INSN}. @xref{Insns}.
181 An RTX code for something that matches in insns, such as
182 @code{MATCH_DUP}. These only occur in machine descriptions.
185 An RTX code for an auto-increment addressing mode, such as
189 All other RTX codes. This category includes the remaining codes used
190 only in machine descriptions (@code{DEFINE_*}, etc.). It also includes
191 all the codes describing side effects (@code{SET}, @code{USE},
192 @code{CLOBBER}, etc.) and the non-insns that may appear on an insn
193 chain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}.
197 For each expression code, @file{rtl.def} specifies the number of
198 contained objects and their kinds using a sequence of characters
199 called the @dfn{format} of the expression code. For example,
200 the format of @code{subreg} is @samp{ei}.
202 @cindex RTL format characters
203 These are the most commonly used format characters:
207 An expression (actually a pointer to an expression).
219 A vector of expressions.
222 A few other format characters are used occasionally:
226 @samp{u} is equivalent to @samp{e} except that it is printed differently
227 in debugging dumps. It is used for pointers to insns.
230 @samp{n} is equivalent to @samp{i} except that it is printed differently
231 in debugging dumps. It is used for the line number or code number of a
235 @samp{S} indicates a string which is optional. In the RTL objects in
236 core, @samp{S} is equivalent to @samp{s}, but when the object is read,
237 from an @samp{md} file, the string value of this operand may be omitted.
238 An omitted string is taken to be the null string.
241 @samp{V} indicates a vector which is optional. In the RTL objects in
242 core, @samp{V} is equivalent to @samp{E}, but when the object is read
243 from an @samp{md} file, the vector value of this operand may be omitted.
244 An omitted vector is effectively the same as a vector of no elements.
247 @samp{0} means a slot whose contents do not fit any normal category.
248 @samp{0} slots are not printed at all in dumps, and are often used in
249 special ways by small parts of the compiler.
252 There are macros to get the number of operands and the format
253 of an expression code:
256 @findex GET_RTX_LENGTH
257 @item GET_RTX_LENGTH (@var{code})
258 Number of operands of an RTX of code @var{code}.
260 @findex GET_RTX_FORMAT
261 @item GET_RTX_FORMAT (@var{code})
262 The format of an RTX of code @var{code}, as a C string.
265 Some classes of RTX codes always have the same format. For example, it
266 is safe to assume that all comparison operations have format @code{ee}.
270 All codes of this class have format @code{e}.
275 All codes of these classes have format @code{ee}.
279 All codes of these classes have format @code{eee}.
282 All codes of this class have formats that begin with @code{iuueiee}.
283 @xref{Insns}. Note that not all RTL objects linked onto an insn chain
284 are of class @code{i}.
289 You can make no assumptions about the format of these codes.
293 @section Access to Operands
295 @cindex access to operands
296 @cindex operand access
302 Operands of expressions are accessed using the macros @code{XEXP},
303 @code{XINT}, @code{XWINT} and @code{XSTR}. Each of these macros takes
304 two arguments: an expression-pointer (RTX) and an operand number
305 (counting from zero). Thus,
312 accesses operand 2 of expression @var{x}, as an expression.
319 accesses the same operand as an integer. @code{XSTR}, used in the same
320 fashion, would access it as a string.
322 Any operand can be accessed as an integer, as an expression or as a string.
323 You must choose the correct method of access for the kind of value actually
324 stored in the operand. You would do this based on the expression code of
325 the containing expression. That is also how you would know how many
328 For example, if @var{x} is a @code{subreg} expression, you know that it has
329 two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
330 and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you
331 would get the address of the expression operand but cast as an integer;
332 that might occasionally be useful, but it would be cleaner to write
333 @code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also
334 compile without error, and would return the second, integer operand cast as
335 an expression pointer, which would probably result in a crash when
336 accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
337 but this will access memory past the end of the expression with
338 unpredictable results.
340 Access to operands which are vectors is more complicated. You can use the
341 macro @code{XVEC} to get the vector-pointer itself, or the macros
342 @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
347 @item XVEC (@var{exp}, @var{idx})
348 Access the vector-pointer which is operand number @var{idx} in @var{exp}.
351 @item XVECLEN (@var{exp}, @var{idx})
352 Access the length (number of elements) in the vector which is
353 in operand number @var{idx} in @var{exp}. This value is an @code{int}.
356 @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
357 Access element number @var{eltnum} in the vector which is
358 in operand number @var{idx} in @var{exp}. This value is an RTX@.
360 It is up to you to make sure that @var{eltnum} is not negative
361 and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
364 All the macros defined in this section expand into lvalues and therefore
365 can be used to assign the operands, lengths and vector elements as well as
369 @section Flags in an RTL Expression
370 @cindex flags in RTL expression
372 RTL expressions contain several flags (one-bit bit-fields)
373 that are used in certain types of expression. Most often they
374 are accessed with the following macros, which expand into lvalues.
377 @findex CONSTANT_POOL_ADDRESS_P
378 @cindex @code{symbol_ref} and @samp{/u}
379 @cindex @code{unchanging}, in @code{symbol_ref}
380 @item CONSTANT_POOL_ADDRESS_P (@var{x})
381 Nonzero in a @code{symbol_ref} if it refers to part of the current
382 function's constant pool. For most targets these addresses are in a
383 @code{.rodata} section entirely separate from the function, but for
384 some targets the addresses are close to the beginning of the function.
385 In either case GCC assumes these addresses can be addressed directly,
386 perhaps with the help of base registers.
387 Stored in the @code{unchanging} field and printed as @samp{/u}.
389 @findex CONST_OR_PURE_CALL_P
390 @cindex @code{call_insn} and @samp{/u}
391 @cindex @code{unchanging}, in @code{call_insn}
392 @item CONST_OR_PURE_CALL_P (@var{x})
393 In a @code{call_insn}, @code{note}, or an @code{expr_list} for notes,
394 indicates that the insn represents a call to a const or pure function.
395 Stored in the @code{unchanging} field and printed as @samp{/u}.
397 @findex INSN_ANNULLED_BRANCH_P
398 @cindex @code{jump_insn} and @samp{/u}
399 @cindex @code{call_insn} and @samp{/u}
400 @cindex @code{unchanging}, in @code{jump_insn} and @code{call_insn}
401 @item INSN_ANNULLED_BRANCH_P (@var{x})
402 In a @code{jump_insn} or @code{call_insn} indicates that the branch is
403 an annulling one. See the discussion under @code{sequence} below.
404 Stored in the @code{unchanging} field and printed as @samp{/u}.
406 @findex INSN_DEAD_CODE_P
407 @cindex @code{insn} and @samp{/s}
408 @cindex @code{in_struct}, in @code{insn}
409 @item INSN_DEAD_CODE_P (@var{x})
410 In an @code{insn} during the dead-code elimination pass, nonzero if the
412 Stored in the @code{in_struct} field and printed as @samp{/s}.
414 @findex INSN_DELETED_P
415 @cindex @code{insn} and @samp{/v}
416 @cindex @code{call_insn} and @samp{/v}
417 @cindex @code{jump_insn} and @samp{/v}
418 @cindex @code{code_label} and @samp{/v}
419 @cindex @code{barrier} and @samp{/v}
420 @cindex @code{note} and @samp{/v}
421 @cindex @code{volatil}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, @code{barrier}, and @code{note}
422 @item INSN_DELETED_P (@var{x})
423 In an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label},
424 @code{barrier}, or @code{note},
425 nonzero if the insn has been deleted. Stored in the
426 @code{volatil} field and printed as @samp{/v}.
428 @findex INSN_FROM_TARGET_P
429 @cindex @code{insn} and @samp{/s}
430 @cindex @code{jump_insn} and @samp{/s}
431 @cindex @code{call_insn} and @samp{/s}
432 @cindex @code{in_struct}, in @code{insn} and @code{jump_insn} and @code{call_insn}
433 @item INSN_FROM_TARGET_P (@var{x})
434 In an @code{insn} or @code{jump_insn} or @code{call_insn} in a delay
435 slot of a branch, indicates that the insn
436 is from the target of the branch. If the branch insn has
437 @code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if
438 the branch is taken. For annulled branches with
439 @code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the
440 branch is not taken. When @code{INSN_ANNULLED_BRANCH_P} is not set,
441 this insn will always be executed. Stored in the @code{in_struct}
442 field and printed as @samp{/s}.
444 @findex LABEL_OUTSIDE_LOOP_P
445 @cindex @code{label_ref} and @samp{/s}
446 @cindex @code{in_struct}, in @code{label_ref}
447 @item LABEL_OUTSIDE_LOOP_P (@var{x})
448 In @code{label_ref} expressions, nonzero if this is a reference to a
449 label that is outside the innermost loop containing the reference to the
450 label. Stored in the @code{in_struct} field and printed as @samp{/s}.
452 @findex LABEL_PRESERVE_P
453 @cindex @code{code_label} and @samp{/i}
454 @cindex @code{note} and @samp{/i}
455 @cindex @code{in_struct}, in @code{code_label} and @code{note}
456 @item LABEL_PRESERVE_P (@var{x})
457 In a @code{code_label} or @code{note}, indicates that the label is referenced by
458 code or data not visible to the RTL of a given function.
459 Labels referenced by a non-local goto will have this bit set. Stored
460 in the @code{in_struct} field and printed as @samp{/s}.
462 @findex LABEL_REF_NONLOCAL_P
463 @cindex @code{label_ref} and @samp{/v}
464 @cindex @code{reg_label} and @samp{/v}
465 @cindex @code{volatil}, in @code{label_ref} and @code{reg_label}
466 @item LABEL_REF_NONLOCAL_P (@var{x})
467 In @code{label_ref} and @code{reg_label} expressions, nonzero if this is
468 a reference to a non-local label.
469 Stored in the @code{volatil} field and printed as @samp{/v}.
471 @findex MEM_IN_STRUCT_P
472 @cindex @code{mem} and @samp{/s}
473 @cindex @code{in_struct}, in @code{mem}
474 @item MEM_IN_STRUCT_P (@var{x})
475 In @code{mem} expressions, nonzero for reference to an entire structure,
476 union or array, or to a component of one. Zero for references to a
477 scalar variable or through a pointer to a scalar. If both this flag and
478 @code{MEM_SCALAR_P} are clear, then we don't know whether this @code{mem}
479 is in a structure or not. Both flags should never be simultaneously set.
480 Stored in the @code{in_struct} field and printed as @samp{/s}.
482 @findex MEM_KEEP_ALIAS_SET_P
483 @cindex @code{mem} and @samp{/j}
484 @cindex @code{jump}, in @code{mem}
485 @item MEM_KEEP_ALIAS_SET_P (@var{x})
486 In @code{mem} expressions, 1 if we should keep the alias set for this
487 mem unchanged when we access a component. Set to 1, for example, when we
488 are already in a non-addressable component of an aggregate.
489 Stored in the @code{jump} field and printed as @samp{/j}.
492 @cindex @code{mem} and @samp{/f}
493 @cindex @code{frame_related}, in @code{mem}
494 @item MEM_SCALAR_P (@var{x})
495 In @code{mem} expressions, nonzero for reference to a scalar known not
496 to be a member of a structure, union, or array. Zero for such
497 references and for indirections through pointers, even pointers pointing
498 to scalar types. If both this flag and @code{MEM_IN_STRUCT_P} are clear,
499 then we don't know whether this @code{mem} is in a structure or not.
500 Both flags should never be simultaneously set.
501 Stored in the @code{frame_related} field and printed as @samp{/f}.
503 @findex MEM_VOLATILE_P
504 @cindex @code{mem} and @samp{/v}
505 @cindex @code{asm_input} and @samp{/v}
506 @cindex @code{asm_operands} and @samp{/v}
507 @cindex @code{volatil}, in @code{mem}, @code{asm_operands}, and @code{asm_input}
508 @item MEM_VOLATILE_P (@var{x})
509 In @code{mem}, @code{asm_operands}, and @code{asm_input} expressions,
510 nonzero for volatile memory references.
511 Stored in the @code{volatil} field and printed as @samp{/v}.
513 @findex REG_FUNCTION_VALUE_P
514 @cindex @code{reg} and @samp{/i}
515 @cindex @code{integrated}, in @code{reg}
516 @item REG_FUNCTION_VALUE_P (@var{x})
517 Nonzero in a @code{reg} if it is the place in which this function's
518 value is going to be returned. (This happens only in a hard
519 register.) Stored in the @code{integrated} field and printed as
522 @findex REG_LOOP_TEST_P
523 @cindex @code{reg} and @samp{/s}
524 @cindex @code{in_struct}, in @code{reg}
525 @item REG_LOOP_TEST_P (@var{x})
526 In @code{reg} expressions, nonzero if this register's entire life is
527 contained in the exit test code for some loop. Stored in the
528 @code{in_struct} field and printed as @samp{/s}.
531 @cindex @code{reg} and @samp{/f}
532 @cindex @code{frame_related}, in @code{reg}
533 @item REG_POINTER (@var{x})
534 Nonzero in a @code{reg} if the register holds a pointer. Stored in the
535 @code{frame_related} field and printed as @samp{/f}.
537 @findex REG_USERVAR_P
538 @cindex @code{reg} and @samp{/v}
539 @cindex @code{volatil}, in @code{reg}
540 @item REG_USERVAR_P (@var{x})
541 In a @code{reg}, nonzero if it corresponds to a variable present in
542 the user's source code. Zero for temporaries generated internally by
543 the compiler. Stored in the @code{volatil} field and printed as
546 The same hard register may be used also for collecting the values of
547 functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
550 @findex RTX_FRAME_RELATED_P
551 @cindex @code{insn} and @samp{/f}
552 @cindex @code{call_insn} and @samp{/f}
553 @cindex @code{jump_insn} and @samp{/f}
554 @cindex @code{barrier} and @samp{/f}
555 @cindex @code{set} and @samp{/f}
556 @cindex @code{frame_related}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, and @code{set}
557 @item RTX_FRAME_RELATED_P (@var{x})
558 Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn},
559 @code{barrier}, or @code{set} which is part of a function prologue
560 and sets the stack pointer, sets the frame pointer, or saves a register.
561 This flag should also be set on an instruction that sets up a temporary
562 register to use in place of the frame pointer.
563 Stored in the @code{frame_related} field and printed as @samp{/f}.
565 In particular, on RISC targets where there are limits on the sizes of
566 immediate constants, it is sometimes impossible to reach the register
567 save area directly from the stack pointer. In that case, a temporary
568 register is used that is near enough to the register save area, and the
569 Canonical Frame Address, i.e., DWARF2's logical frame pointer, register
570 must (temporarily) be changed to be this temporary register. So, the
571 instruction that sets this temporary register must be marked as
572 @code{RTX_FRAME_RELATED_P}.
574 If the marked instruction is overly complex (defined in terms of what
575 @code{dwarf2out_frame_debug_expr} can handle), you will also have to
576 create a @code{REG_FRAME_RELATED_EXPR} note and attach it to the
577 instruction. This note should contain a simple expression of the
578 computation performed by this instruction, i.e., one that
579 @code{dwarf2out_frame_debug_expr} can handle.
581 This flag is required for exception handling support on targets with RTL
584 @findex RTX_INTEGRATED_P
585 @cindex @code{insn} and @samp{/i}
586 @cindex @code{call_insn} and @samp{/i}
587 @cindex @code{jump_insn} and @samp{/i}
588 @cindex @code{barrier} and @samp{/i}
589 @cindex @code{code_label} and @samp{/i}
590 @cindex @code{insn_list} and @samp{/i}
591 @cindex @code{const} and @samp{/i}
592 @cindex @code{note} and @samp{/i}
593 @cindex @code{integrated}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, @code{code_label}, @code{insn_list}, @code{const}, and @code{note}
594 @item RTX_INTEGRATED_P (@var{x})
595 Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier},
596 @code{code_label}, @code{insn_list}, @code{const}, or @code{note} if it
597 resulted from an in-line function call.
598 Stored in the @code{integrated} field and printed as @samp{/i}.
600 @findex RTX_UNCHANGING_P
601 @cindex @code{reg} and @samp{/u}
602 @cindex @code{mem} and @samp{/u}
603 @cindex @code{concat} and @samp{/u}
604 @cindex @code{unchanging}, in @code{reg} and @code{mem}
605 @item RTX_UNCHANGING_P (@var{x})
606 Nonzero in a @code{reg}, @code{mem}, or @code{concat} if the memory
608 anywhere. This does not mean that it is function invariant.
609 Stored in the @code{unchanging} field and printed as @samp{/u}.
611 @findex SCHED_GROUP_P
612 @cindex @code{insn} and @samp{/i}
613 @cindex @code{call_insn} and @samp{/i}
614 @cindex @code{jump_insn} and @samp{/i}
615 @cindex @code{code_label} and @samp{/i}
616 @cindex @code{barrier} and @samp{/i}
617 @cindex @code{note} and @samp{/i}
618 @cindex @code{in_struct}, in @code{insn}, @code{jump_insn}, @code{call_insn}, @code{code_label}, @code{barrier}, and @code{note}
619 @item SCHED_GROUP_P (@var{x})
620 During instruction scheduling, in an @code{insn}, @code{call_insn},
621 @code{jump_insn}, @code{code_label}, @code{barrier}, or
622 @code{note}, indicates that the
623 previous insn must be scheduled together with this insn. This is used to
624 ensure that certain groups of instructions will not be split up by the
625 instruction scheduling pass, for example, @code{use} insns before
626 a @code{call_insn} may not be separated from the @code{call_insn}.
627 Stored in the @code{in_struct} field and printed as @samp{/s}.
629 @findex SET_IS_RETURN_P
630 @cindex @code{insn} and @samp{/j}
631 @cindex @code{jump}, in @code{insn}
632 @item SET_IS_RETURN_P (@var{x})
633 For a @code{set}, nonzero if it is for a return.
634 Stored in the @code{jump} field and printed as @samp{/j}.
636 @findex SIBLING_CALL_P
637 @cindex @code{call_insn} and @samp{/j}
638 @cindex @code{jump}, in @code{call_insn}
639 @item SIBLING_CALL_P (@var{x})
640 For a @code{call_insn}, nonzero if the insn is a sibling call.
641 Stored in the @code{jump} field and printed as @samp{/j}.
643 @findex STRING_POOL_ADDRESS_P
644 @cindex @code{symbol_ref} and @samp{/f}
645 @cindex @code{frame_related}, in @code{symbol_ref}
646 @item STRING_POOL_ADDRESS_P (@var{x})
647 For a @code{symbol_ref} expression, nonzero if it addresses this function's
648 string constant pool.
649 Stored in the @code{frame_related} field and printed as @samp{/f}.
651 @findex SUBREG_PROMOTED_UNSIGNED_P
652 @cindex @code{subreg} and @samp{/u} and @samp{/v}
653 @cindex @code{unchanging}, in @code{subreg}
654 @cindex @code{volatil}, in @code{subreg}
655 @item SUBREG_PROMOTED_UNSIGNED_P (@var{x})
656 Returns a value greater then zero for a @code{subreg} that has
657 @code{SUBREG_PROMOTED_VAR_P} nonzero if the object being referenced is kept
658 zero-extended, zero if it is kept sign-extended, and less then zero if it is
659 extended some other way via the @code{ptr_extend} instruction.
660 Stored in the @code{unchanging}
661 field and @code{volatil} field, printed as @samp{/u} and @samp{/v}.
662 This macro may only be used to get the value it may not be used to change
663 the value. Use @code{SUBREG_PROMOTED_UNSIGNED_SET} to change the value.
665 @findex SUBREG_PROMOTED_UNSIGNED_SET
666 @cindex @code{subreg} and @samp{/u}
667 @cindex @code{unchanging}, in @code{subreg}
668 @cindex @code{volatil}, in @code{subreg}
669 @item SUBREG_PROMOTED_UNSIGNED_SET (@var{x})
670 Set the @code{unchanging} and @code{volatil} fields in a @code{subreg}
671 to reflect zero, sign, or other extension. If @code{volatil} is
672 zero, then @code{unchanging} as nonzero means zero extension and as
673 zero means sign extension. If @code{volatil} is nonzero then some
674 other type of extension was done via the @code{ptr_extend} instruction.
676 @findex SUBREG_PROMOTED_VAR_P
677 @cindex @code{subreg} and @samp{/s}
678 @cindex @code{in_struct}, in @code{subreg}
679 @item SUBREG_PROMOTED_VAR_P (@var{x})
680 Nonzero in a @code{subreg} if it was made when accessing an object that
681 was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine
682 description macro (@pxref{Storage Layout}). In this case, the mode of
683 the @code{subreg} is the declared mode of the object and the mode of
684 @code{SUBREG_REG} is the mode of the register that holds the object.
685 Promoted variables are always either sign- or zero-extended to the wider
686 mode on every assignment. Stored in the @code{in_struct} field and
687 printed as @samp{/s}.
689 @findex SYMBOL_REF_FLAG
690 @cindex @code{symbol_ref} and @samp{/v}
691 @cindex @code{volatil}, in @code{symbol_ref}
692 @item SYMBOL_REF_FLAG (@var{x})
693 In a @code{symbol_ref}, this is used as a flag for machine-specific purposes.
694 Stored in the @code{volatil} field and printed as @samp{/v}.
696 @findex SYMBOL_REF_USED
697 @cindex @code{used}, in @code{symbol_ref}
698 @item SYMBOL_REF_USED (@var{x})
699 In a @code{symbol_ref}, indicates that @var{x} has been used. This is
700 normally only used to ensure that @var{x} is only declared external
701 once. Stored in the @code{used} field.
703 @findex SYMBOL_REF_WEAK
704 @cindex @code{symbol_ref} and @samp{/i}
705 @cindex @code{integrated}, in @code{symbol_ref}
706 @item SYMBOL_REF_WEAK (@var{x})
707 In a @code{symbol_ref}, indicates that @var{x} has been declared weak.
708 Stored in the @code{integrated} field and printed as @samp{/i}.
711 These are the fields to which the above macros refer:
715 @cindex @samp{/c} in RTL dump
717 This flag is currently unused.
719 In an RTL dump, this flag is represented as @samp{/c}.
721 @findex frame_related
722 @cindex @samp{/f} in RTL dump
724 In an @code{insn} or @code{set} expression, 1 means that it is part of
725 a function prologue and sets the stack pointer, sets the frame pointer,
726 saves a register, or sets up a temporary register to use in place of the
729 In @code{reg} expressions, 1 means that the register holds a pointer.
731 In @code{symbol_ref} expressions, 1 means that the reference addresses
732 this function's string constant pool.
734 In @code{mem} expressions, 1 means that the reference is to a scalar.
736 In an RTL dump, this flag is represented as @samp{/f}.
739 @cindex @samp{/s} in RTL dump
741 In @code{mem} expressions, it is 1 if the memory datum referred to is
742 all or part of a structure or array; 0 if it is (or might be) a scalar
743 variable. A reference through a C pointer has 0 because the pointer
744 might point to a scalar variable. This information allows the compiler
745 to determine something about possible cases of aliasing.
747 In @code{reg} expressions, it is 1 if the register has its entire life
748 contained within the test expression of some loop.
750 In @code{subreg} expressions, 1 means that the @code{subreg} is accessing
751 an object that has had its mode promoted from a wider mode.
753 In @code{label_ref} expressions, 1 means that the referenced label is
754 outside the innermost loop containing the insn in which the @code{label_ref}
757 In @code{code_label} expressions, it is 1 if the label may never be deleted.
758 This is used for labels which are the target of non-local gotos. Such a
759 label that would have been deleted is replaced with a @code{note} of type
760 @code{NOTE_INSN_DELETED_LABEL}.
762 In an @code{insn} during dead-code elimination, 1 means that the insn is
765 In an @code{insn} or @code{jump_insn} during reorg for an insn in the
766 delay slot of a branch,
767 1 means that this insn is from the target of the branch.
769 In an @code{insn} during instruction scheduling, 1 means that this insn
770 must be scheduled as part of a group together with the previous insn.
772 In an RTL dump, this flag is represented as @samp{/s}.
775 @cindex @samp{/i} in RTL dump
777 In an @code{insn}, @code{insn_list}, or @code{const}, 1 means the RTL was
778 produced by procedure integration.
780 In @code{reg} expressions, 1 means the register contains
781 the value to be returned by the current function. On
782 machines that pass parameters in registers, the same register number
783 may be used for parameters as well, but this flag is not set on such
786 In @code{symbol_ref} expressions, 1 means the referenced symbol is weak.
788 In an RTL dump, this flag is represented as @samp{/i}.
791 @cindex @samp{/j} in RTL dump
793 In a @code{mem} expression, 1 means we should keep the alias set for this
794 mem unchanged when we access a component.
796 In a @code{set}, 1 means it is for a return.
798 In a @code{call_insn}, 1 means it is a sibling call.
800 In an RTL dump, this flag is represented as @samp{/j}.
803 @cindex @samp{/u} in RTL dump
805 In @code{reg} and @code{mem} expressions, 1 means
806 that the value of the expression never changes.
808 In @code{subreg} expressions, it is 1 if the @code{subreg} references an
809 unsigned object whose mode has been promoted to a wider mode.
811 In an @code{insn} or @code{jump_insn} in the delay slot of a branch
812 instruction, 1 means an annulling branch should be used.
814 In a @code{symbol_ref} expression, 1 means that this symbol addresses
815 something in the per-function constant pool.
817 In a @code{call_insn}, @code{note}, or an @code{expr_list} of notes,
818 1 means that this instruction is a call to a const or pure function.
820 In an RTL dump, this flag is represented as @samp{/u}.
824 This flag is used directly (without an access macro) at the end of RTL
825 generation for a function, to count the number of times an expression
826 appears in insns. Expressions that appear more than once are copied,
827 according to the rules for shared structure (@pxref{Sharing}).
829 For a @code{reg}, it is used directly (without an access macro) by the
830 leaf register renumbering code to ensure that each register is only
833 In a @code{symbol_ref}, it indicates that an external declaration for
834 the symbol has already been written.
837 @cindex @samp{/v} in RTL dump
839 @cindex volatile memory references
840 In a @code{mem}, @code{asm_operands}, or @code{asm_input}
841 expression, it is 1 if the memory
842 reference is volatile. Volatile memory references may not be deleted,
843 reordered or combined.
845 In a @code{symbol_ref} expression, it is used for machine-specific
848 In a @code{reg} expression, it is 1 if the value is a user-level variable.
849 0 indicates an internal compiler temporary.
851 In an @code{insn}, 1 means the insn has been deleted.
853 In @code{label_ref} and @code{reg_label} expressions, 1 means a reference
854 to a non-local label.
856 In an RTL dump, this flag is represented as @samp{/v}.
860 @section Machine Modes
861 @cindex machine modes
863 @findex enum machine_mode
864 A machine mode describes a size of data object and the representation used
865 for it. In the C code, machine modes are represented by an enumeration
866 type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL
867 expression has room for a machine mode and so do certain kinds of tree
868 expressions (declarations and types, to be precise).
870 In debugging dumps and machine descriptions, the machine mode of an RTL
871 expression is written after the expression code with a colon to separate
872 them. The letters @samp{mode} which appear at the end of each machine mode
873 name are omitted. For example, @code{(reg:SI 38)} is a @code{reg}
874 expression with machine mode @code{SImode}. If the mode is
875 @code{VOIDmode}, it is not written at all.
877 Here is a table of machine modes. The term ``byte'' below refers to an
878 object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}).
883 ``Bit'' mode represents a single bit, for predicate registers.
887 ``Quarter-Integer'' mode represents a single byte treated as an integer.
891 ``Half-Integer'' mode represents a two-byte integer.
895 ``Partial Single Integer'' mode represents an integer which occupies
896 four bytes but which doesn't really use all four. On some machines,
897 this is the right mode to use for pointers.
901 ``Single Integer'' mode represents a four-byte integer.
905 ``Partial Double Integer'' mode represents an integer which occupies
906 eight bytes but which doesn't really use all eight. On some machines,
907 this is the right mode to use for certain pointers.
911 ``Double Integer'' mode represents an eight-byte integer.
915 ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
919 ``Octa Integer'' (?) mode represents a thirty-two-byte integer.
923 ``Quarter-Floating'' mode represents a quarter-precision (single byte)
924 floating point number.
928 ``Half-Floating'' mode represents a half-precision (two byte) floating
933 ``Three-Quarter-Floating'' (?) mode represents a three-quarter-precision
934 (three byte) floating point number.
938 ``Single Floating'' mode represents a four byte floating point number.
939 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
940 this is a single-precision IEEE floating point number; it can also be
941 used for double-precision (on processors with 16-bit bytes) and
942 single-precision VAX and IBM types.
946 ``Double Floating'' mode represents an eight byte floating point number.
947 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
948 this is a double-precision IEEE floating point number.
952 ``Extended Floating'' mode represents a twelve byte floating point
953 number. This mode is used for IEEE extended floating point. On some
954 systems not all bits within these bytes will actually be used.
958 ``Tetra Floating'' mode represents a sixteen byte floating point number.
959 This gets used for both the 96-bit extended IEEE floating-point types
960 padded to 128 bits, and true 128-bit extended IEEE floating-point types.
964 ``Condition Code'' mode represents the value of a condition code, which
965 is a machine-specific set of bits used to represent the result of a
966 comparison operation. Other machine-specific modes may also be used for
967 the condition code. These modes are not used on machines that use
968 @code{cc0} (see @pxref{Condition Code}).
972 ``Block'' mode represents values that are aggregates to which none of
973 the other modes apply. In RTL, only memory references can have this mode,
974 and only if they appear in string-move or vector instructions. On machines
975 which have no such instructions, @code{BLKmode} will not appear in RTL@.
979 Void mode means the absence of a mode or an unspecified mode.
980 For example, RTL expressions of code @code{const_int} have mode
981 @code{VOIDmode} because they can be taken to have whatever mode the context
982 requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by
983 the absence of any mode.
991 @item QCmode, HCmode, SCmode, DCmode, XCmode, TCmode
992 These modes stand for a complex number represented as a pair of floating
993 point values. The floating point values are in @code{QFmode},
994 @code{HFmode}, @code{SFmode}, @code{DFmode}, @code{XFmode}, and
995 @code{TFmode}, respectively.
1003 @item CQImode, CHImode, CSImode, CDImode, CTImode, COImode
1004 These modes stand for a complex number represented as a pair of integer
1005 values. The integer values are in @code{QImode}, @code{HImode},
1006 @code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode},
1010 The machine description defines @code{Pmode} as a C macro which expands
1011 into the machine mode used for addresses. Normally this is the mode
1012 whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines.
1014 The only modes which a machine description @i{must} support are
1015 @code{QImode}, and the modes corresponding to @code{BITS_PER_WORD},
1016 @code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}.
1017 The compiler will attempt to use @code{DImode} for 8-byte structures and
1018 unions, but this can be prevented by overriding the definition of
1019 @code{MAX_FIXED_MODE_SIZE}. Alternatively, you can have the compiler
1020 use @code{TImode} for 16-byte structures and unions. Likewise, you can
1021 arrange for the C type @code{short int} to avoid using @code{HImode}.
1023 @cindex mode classes
1024 Very few explicit references to machine modes remain in the compiler and
1025 these few references will soon be removed. Instead, the machine modes
1026 are divided into mode classes. These are represented by the enumeration
1027 type @code{enum mode_class} defined in @file{machmode.h}. The possible
1033 Integer modes. By default these are @code{BImode}, @code{QImode},
1034 @code{HImode}, @code{SImode}, @code{DImode}, @code{TImode}, and
1037 @findex MODE_PARTIAL_INT
1038 @item MODE_PARTIAL_INT
1039 The ``partial integer'' modes, @code{PQImode}, @code{PHImode},
1040 @code{PSImode} and @code{PDImode}.
1044 Floating point modes. By default these are @code{QFmode},
1045 @code{HFmode}, @code{TQFmode}, @code{SFmode}, @code{DFmode},
1046 @code{XFmode} and @code{TFmode}.
1048 @findex MODE_COMPLEX_INT
1049 @item MODE_COMPLEX_INT
1050 Complex integer modes. (These are not currently implemented).
1052 @findex MODE_COMPLEX_FLOAT
1053 @item MODE_COMPLEX_FLOAT
1054 Complex floating point modes. By default these are @code{QCmode},
1055 @code{HCmode}, @code{SCmode}, @code{DCmode}, @code{XCmode}, and
1058 @findex MODE_FUNCTION
1060 Algol or Pascal function variables including a static chain.
1061 (These are not currently implemented).
1065 Modes representing condition code values. These are @code{CCmode} plus
1066 any modes listed in the @code{EXTRA_CC_MODES} macro. @xref{Jump Patterns},
1067 also see @ref{Condition Code}.
1071 This is a catchall mode class for modes which don't fit into the above
1072 classes. Currently @code{VOIDmode} and @code{BLKmode} are in
1076 Here are some C macros that relate to machine modes:
1080 @item GET_MODE (@var{x})
1081 Returns the machine mode of the RTX @var{x}.
1084 @item PUT_MODE (@var{x}, @var{newmode})
1085 Alters the machine mode of the RTX @var{x} to be @var{newmode}.
1087 @findex NUM_MACHINE_MODES
1088 @item NUM_MACHINE_MODES
1089 Stands for the number of machine modes available on the target
1090 machine. This is one greater than the largest numeric value of any
1093 @findex GET_MODE_NAME
1094 @item GET_MODE_NAME (@var{m})
1095 Returns the name of mode @var{m} as a string.
1097 @findex GET_MODE_CLASS
1098 @item GET_MODE_CLASS (@var{m})
1099 Returns the mode class of mode @var{m}.
1101 @findex GET_MODE_WIDER_MODE
1102 @item GET_MODE_WIDER_MODE (@var{m})
1103 Returns the next wider natural mode. For example, the expression
1104 @code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}.
1106 @findex GET_MODE_SIZE
1107 @item GET_MODE_SIZE (@var{m})
1108 Returns the size in bytes of a datum of mode @var{m}.
1110 @findex GET_MODE_BITSIZE
1111 @item GET_MODE_BITSIZE (@var{m})
1112 Returns the size in bits of a datum of mode @var{m}.
1114 @findex GET_MODE_MASK
1115 @item GET_MODE_MASK (@var{m})
1116 Returns a bitmask containing 1 for all bits in a word that fit within
1117 mode @var{m}. This macro can only be used for modes whose bitsize is
1118 less than or equal to @code{HOST_BITS_PER_INT}.
1120 @findex GET_MODE_ALIGNMENT
1121 @item GET_MODE_ALIGNMENT (@var{m})
1122 Return the required alignment, in bits, for an object of mode @var{m}.
1124 @findex GET_MODE_UNIT_SIZE
1125 @item GET_MODE_UNIT_SIZE (@var{m})
1126 Returns the size in bytes of the subunits of a datum of mode @var{m}.
1127 This is the same as @code{GET_MODE_SIZE} except in the case of complex
1128 modes. For them, the unit size is the size of the real or imaginary
1131 @findex GET_MODE_NUNITS
1132 @item GET_MODE_NUNITS (@var{m})
1133 Returns the number of units contained in a mode, i.e.,
1134 @code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}.
1136 @findex GET_CLASS_NARROWEST_MODE
1137 @item GET_CLASS_NARROWEST_MODE (@var{c})
1138 Returns the narrowest mode in mode class @var{c}.
1143 The global variables @code{byte_mode} and @code{word_mode} contain modes
1144 whose classes are @code{MODE_INT} and whose bitsizes are either
1145 @code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit
1146 machines, these are @code{QImode} and @code{SImode}, respectively.
1149 @section Constant Expression Types
1150 @cindex RTL constants
1151 @cindex RTL constant expression types
1153 The simplest RTL expressions are those that represent constant values.
1157 @item (const_int @var{i})
1158 This type of expression represents the integer value @var{i}. @var{i}
1159 is customarily accessed with the macro @code{INTVAL} as in
1160 @code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}.
1166 There is only one expression object for the integer value zero; it is
1167 the value of the variable @code{const0_rtx}. Likewise, the only
1168 expression for integer value one is found in @code{const1_rtx}, the only
1169 expression for integer value two is found in @code{const2_rtx}, and the
1170 only expression for integer value negative one is found in
1171 @code{constm1_rtx}. Any attempt to create an expression of code
1172 @code{const_int} and value zero, one, two or negative one will return
1173 @code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or
1174 @code{constm1_rtx} as appropriate.
1176 @findex const_true_rtx
1177 Similarly, there is only one object for the integer whose value is
1178 @code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If
1179 @code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and
1180 @code{const1_rtx} will point to the same object. If
1181 @code{STORE_FLAG_VALUE} is @minus{}1, @code{const_true_rtx} and
1182 @code{constm1_rtx} will point to the same object.
1184 @findex const_double
1185 @item (const_double:@var{m} @var{addr} @var{i0} @var{i1} @dots{})
1186 Represents either a floating-point constant of mode @var{m} or an
1187 integer constant too large to fit into @code{HOST_BITS_PER_WIDE_INT}
1188 bits but small enough to fit within twice that number of bits (GCC
1189 does not provide a mechanism to represent even larger constants). In
1190 the latter case, @var{m} will be @code{VOIDmode}.
1192 @findex const_vector
1193 @item (const_vector:@var{m} [@var{x0} @var{x1} @dots{}])
1194 Represents a vector constant. The square brackets stand for the vector
1195 containing the constant elements. @var{x0}, @var{x1} and so on are
1196 the @code{const_int} or @code{const_double} elements.
1198 The number of units in a @code{const_vector} is obtained with the macro
1199 @code{CONST_VECTOR_NUNITS} as in @code{CONST_VECTOR_NUNITS (@var{v})}.
1201 Individual elements in a vector constant are accessed with the macro
1202 @code{CONST_VECTOR_ELT} as in @code{CONST_VECTOR_ELT (@var{v}, @var{n})}
1203 where @var{v} is the vector constant and @var{n} is the element
1206 @findex CONST_DOUBLE_MEM
1207 @findex CONST_DOUBLE_CHAIN
1208 @var{addr} is used to contain the @code{mem} expression that corresponds
1209 to the location in memory that at which the constant can be found. If
1210 it has not been allocated a memory location, but is on the chain of all
1211 @code{const_double} expressions in this compilation (maintained using an
1212 undisplayed field), @var{addr} contains @code{const0_rtx}. If it is not
1213 on the chain, @var{addr} contains @code{cc0_rtx}. @var{addr} is
1214 customarily accessed with the macro @code{CONST_DOUBLE_MEM} and the
1215 chain field via @code{CONST_DOUBLE_CHAIN}.
1217 @findex CONST_DOUBLE_LOW
1218 If @var{m} is @code{VOIDmode}, the bits of the value are stored in
1219 @var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro
1220 @code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}.
1222 If the constant is floating point (regardless of its precision), then
1223 the number of integers used to store the value depends on the size of
1224 @code{REAL_VALUE_TYPE} (@pxref{Floating Point}). The integers
1225 represent a floating point number, but not precisely in the target
1226 machine's or host machine's floating point format. To convert them to
1227 the precise bit pattern used by the target machine, use the macro
1228 @code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}).
1233 The macro @code{CONST0_RTX (@var{mode})} refers to an expression with
1234 value 0 in mode @var{mode}. If mode @var{mode} is of mode class
1235 @code{MODE_INT}, it returns @code{const0_rtx}. If mode @var{mode} is of
1236 mode class @code{MODE_FLOAT}, it returns a @code{CONST_DOUBLE}
1237 expression in mode @var{mode}. Otherwise, it returns a
1238 @code{CONST_VECTOR} expression in mode @var{mode}. Similarly, the macro
1239 @code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in
1240 mode @var{mode} and similarly for @code{CONST2_RTX}. The
1241 @code{CONST1_RTX} and @code{CONST2_RTX} macros are undefined
1244 @findex const_string
1245 @item (const_string @var{str})
1246 Represents a constant string with value @var{str}. Currently this is
1247 used only for insn attributes (@pxref{Insn Attributes}) since constant
1248 strings in C are placed in memory.
1251 @item (symbol_ref:@var{mode} @var{symbol})
1252 Represents the value of an assembler label for data. @var{symbol} is
1253 a string that describes the name of the assembler label. If it starts
1254 with a @samp{*}, the label is the rest of @var{symbol} not including
1255 the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed
1258 The @code{symbol_ref} contains a mode, which is usually @code{Pmode}.
1259 Usually that is the only mode for which a symbol is directly valid.
1262 @item (label_ref @var{label})
1263 Represents the value of an assembler label for code. It contains one
1264 operand, an expression, which must be a @code{code_label} or a @code{note}
1265 of type @code{NOTE_INSN_DELETED_LABEL} that appears in the instruction
1266 sequence to identify the place where the label should go.
1268 The reason for using a distinct expression type for code label
1269 references is so that jump optimization can distinguish them.
1271 @item (const:@var{m} @var{exp})
1272 Represents a constant that is the result of an assembly-time
1273 arithmetic computation. The operand, @var{exp}, is an expression that
1274 contains only constants (@code{const_int}, @code{symbol_ref} and
1275 @code{label_ref} expressions) combined with @code{plus} and
1276 @code{minus}. However, not all combinations are valid, since the
1277 assembler cannot do arbitrary arithmetic on relocatable symbols.
1279 @var{m} should be @code{Pmode}.
1282 @item (high:@var{m} @var{exp})
1283 Represents the high-order bits of @var{exp}, usually a
1284 @code{symbol_ref}. The number of bits is machine-dependent and is
1285 normally the number of bits specified in an instruction that initializes
1286 the high order bits of a register. It is used with @code{lo_sum} to
1287 represent the typical two-instruction sequence used in RISC machines to
1288 reference a global memory location.
1290 @var{m} should be @code{Pmode}.
1293 @node Regs and Memory
1294 @section Registers and Memory
1295 @cindex RTL register expressions
1296 @cindex RTL memory expressions
1298 Here are the RTL expression types for describing access to machine
1299 registers and to main memory.
1303 @cindex hard registers
1304 @cindex pseudo registers
1305 @item (reg:@var{m} @var{n})
1306 For small values of the integer @var{n} (those that are less than
1307 @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
1308 register number @var{n}: a @dfn{hard register}. For larger values of
1309 @var{n}, it stands for a temporary value or @dfn{pseudo register}.
1310 The compiler's strategy is to generate code assuming an unlimited
1311 number of such pseudo registers, and later convert them into hard
1312 registers or into memory references.
1314 @var{m} is the machine mode of the reference. It is necessary because
1315 machines can generally refer to each register in more than one mode.
1316 For example, a register may contain a full word but there may be
1317 instructions to refer to it as a half word or as a single byte, as
1318 well as instructions to refer to it as a floating point number of
1321 Even for a register that the machine can access in only one mode,
1322 the mode must always be specified.
1324 The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
1325 description, since the number of hard registers on the machine is an
1326 invariant characteristic of the machine. Note, however, that not
1327 all of the machine registers must be general registers. All the
1328 machine registers that can be used for storage of data are given
1329 hard register numbers, even those that can be used only in certain
1330 instructions or can hold only certain types of data.
1332 A hard register may be accessed in various modes throughout one
1333 function, but each pseudo register is given a natural mode
1334 and is accessed only in that mode. When it is necessary to describe
1335 an access to a pseudo register using a nonnatural mode, a @code{subreg}
1338 A @code{reg} expression with a machine mode that specifies more than
1339 one word of data may actually stand for several consecutive registers.
1340 If in addition the register number specifies a hardware register, then
1341 it actually represents several consecutive hardware registers starting
1342 with the specified one.
1344 Each pseudo register number used in a function's RTL code is
1345 represented by a unique @code{reg} expression.
1347 @findex FIRST_VIRTUAL_REGISTER
1348 @findex LAST_VIRTUAL_REGISTER
1349 Some pseudo register numbers, those within the range of
1350 @code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only
1351 appear during the RTL generation phase and are eliminated before the
1352 optimization phases. These represent locations in the stack frame that
1353 cannot be determined until RTL generation for the function has been
1354 completed. The following virtual register numbers are defined:
1357 @findex VIRTUAL_INCOMING_ARGS_REGNUM
1358 @item VIRTUAL_INCOMING_ARGS_REGNUM
1359 This points to the first word of the incoming arguments passed on the
1360 stack. Normally these arguments are placed there by the caller, but the
1361 callee may have pushed some arguments that were previously passed in
1364 @cindex @code{FIRST_PARM_OFFSET} and virtual registers
1365 @cindex @code{ARG_POINTER_REGNUM} and virtual registers
1366 When RTL generation is complete, this virtual register is replaced
1367 by the sum of the register given by @code{ARG_POINTER_REGNUM} and the
1368 value of @code{FIRST_PARM_OFFSET}.
1370 @findex VIRTUAL_STACK_VARS_REGNUM
1371 @cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers
1372 @item VIRTUAL_STACK_VARS_REGNUM
1373 If @code{FRAME_GROWS_DOWNWARD} is defined, this points to immediately
1374 above the first variable on the stack. Otherwise, it points to the
1375 first variable on the stack.
1377 @cindex @code{STARTING_FRAME_OFFSET} and virtual registers
1378 @cindex @code{FRAME_POINTER_REGNUM} and virtual registers
1379 @code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the
1380 register given by @code{FRAME_POINTER_REGNUM} and the value
1381 @code{STARTING_FRAME_OFFSET}.
1383 @findex VIRTUAL_STACK_DYNAMIC_REGNUM
1384 @item VIRTUAL_STACK_DYNAMIC_REGNUM
1385 This points to the location of dynamically allocated memory on the stack
1386 immediately after the stack pointer has been adjusted by the amount of
1389 @cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers
1390 @cindex @code{STACK_POINTER_REGNUM} and virtual registers
1391 This virtual register is replaced by the sum of the register given by
1392 @code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}.
1394 @findex VIRTUAL_OUTGOING_ARGS_REGNUM
1395 @item VIRTUAL_OUTGOING_ARGS_REGNUM
1396 This points to the location in the stack at which outgoing arguments
1397 should be written when the stack is pre-pushed (arguments pushed using
1398 push insns should always use @code{STACK_POINTER_REGNUM}).
1400 @cindex @code{STACK_POINTER_OFFSET} and virtual registers
1401 This virtual register is replaced by the sum of the register given by
1402 @code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}.
1406 @item (subreg:@var{m} @var{reg} @var{bytenum})
1407 @code{subreg} expressions are used to refer to a register in a machine
1408 mode other than its natural one, or to refer to one register of
1409 a multi-part @code{reg} that actually refers to several registers.
1411 Each pseudo-register has a natural mode. If it is necessary to
1412 operate on it in a different mode---for example, to perform a fullword
1413 move instruction on a pseudo-register that contains a single
1414 byte---the pseudo-register must be enclosed in a @code{subreg}. In
1415 such a case, @var{bytenum} is zero.
1417 Usually @var{m} is at least as narrow as the mode of @var{reg}, in which
1418 case it is restricting consideration to only the bits of @var{reg} that
1421 Sometimes @var{m} is wider than the mode of @var{reg}. These
1422 @code{subreg} expressions are often called @dfn{paradoxical}. They are
1423 used in cases where we want to refer to an object in a wider mode but do
1424 not care what value the additional bits have. The reload pass ensures
1425 that paradoxical references are only made to hard registers.
1427 The other use of @code{subreg} is to extract the individual registers of
1428 a multi-register value. Machine modes such as @code{DImode} and
1429 @code{TImode} can indicate values longer than a word, values which
1430 usually require two or more consecutive registers. To access one of the
1431 registers, use a @code{subreg} with mode @code{SImode} and a
1432 @var{bytenum} offset that says which register.
1434 Storing in a non-paradoxical @code{subreg} has undefined results for
1435 bits belonging to the same word as the @code{subreg}. This laxity makes
1436 it easier to generate efficient code for such instructions. To
1437 represent an instruction that preserves all the bits outside of those in
1438 the @code{subreg}, use @code{strict_low_part} around the @code{subreg}.
1440 @cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
1441 The compilation parameter @code{WORDS_BIG_ENDIAN}, if set to 1, says
1442 that byte number zero is part of the most significant word; otherwise,
1443 it is part of the least significant word.
1445 @cindex @code{BYTES_BIG_ENDIAN}, effect on @code{subreg}
1446 The compilation parameter @code{BYTES_BIG_ENDIAN}, if set to 1, says
1447 that byte number zero is the most significant byte within a word;
1448 otherwise, it is the least significant byte within a word.
1450 @cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg}
1451 On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with
1452 @code{WORDS_BIG_ENDIAN}.
1453 However, most parts of the compiler treat floating point values as if
1454 they had the same endianness as integer values. This works because
1455 they handle them solely as a collection of integer values, with no
1456 particular numerical value. Only real.c and the runtime libraries
1457 care about @code{FLOAT_WORDS_BIG_ENDIAN}.
1459 @cindex combiner pass
1461 @cindex @code{subreg}, special reload handling
1462 Between the combiner pass and the reload pass, it is possible to have a
1463 paradoxical @code{subreg} which contains a @code{mem} instead of a
1464 @code{reg} as its first operand. After the reload pass, it is also
1465 possible to have a non-paradoxical @code{subreg} which contains a
1466 @code{mem}; this usually occurs when the @code{mem} is a stack slot
1467 which replaced a pseudo register.
1469 Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
1470 using a @code{subreg}. On some machines the most significant part of a
1471 @code{DFmode} value does not have the same format as a single-precision
1474 It is also not valid to access a single word of a multi-word value in a
1475 hard register when less registers can hold the value than would be
1476 expected from its size. For example, some 32-bit machines have
1477 floating-point registers that can hold an entire @code{DFmode} value.
1478 If register 10 were such a register @code{(subreg:SI (reg:DF 10) 1)}
1479 would be invalid because there is no way to convert that reference to
1480 a single machine register. The reload pass prevents @code{subreg}
1481 expressions such as these from being formed.
1485 The first operand of a @code{subreg} expression is customarily accessed
1486 with the @code{SUBREG_REG} macro and the second operand is customarily
1487 accessed with the @code{SUBREG_BYTE} macro.
1490 @cindex scratch operands
1491 @item (scratch:@var{m})
1492 This represents a scratch register that will be required for the
1493 execution of a single instruction and not used subsequently. It is
1494 converted into a @code{reg} by either the local register allocator or
1497 @code{scratch} is usually present inside a @code{clobber} operation
1498 (@pxref{Side Effects}).
1501 @cindex condition code register
1503 This refers to the machine's condition code register. It has no
1504 operands and may not have a machine mode. There are two ways to use it:
1508 To stand for a complete set of condition code flags. This is best on
1509 most machines, where each comparison sets the entire series of flags.
1511 With this technique, @code{(cc0)} may be validly used in only two
1512 contexts: as the destination of an assignment (in test and compare
1513 instructions) and in comparison operators comparing against zero
1514 (@code{const_int} with value zero; that is to say, @code{const0_rtx}).
1517 To stand for a single flag that is the result of a single condition.
1518 This is useful on machines that have only a single flag bit, and in
1519 which comparison instructions must specify the condition to test.
1521 With this technique, @code{(cc0)} may be validly used in only two
1522 contexts: as the destination of an assignment (in test and compare
1523 instructions) where the source is a comparison operator, and as the
1524 first operand of @code{if_then_else} (in a conditional branch).
1528 There is only one expression object of code @code{cc0}; it is the
1529 value of the variable @code{cc0_rtx}. Any attempt to create an
1530 expression of code @code{cc0} will return @code{cc0_rtx}.
1532 Instructions can set the condition code implicitly. On many machines,
1533 nearly all instructions set the condition code based on the value that
1534 they compute or store. It is not necessary to record these actions
1535 explicitly in the RTL because the machine description includes a
1536 prescription for recognizing the instructions that do so (by means of
1537 the macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only
1538 instructions whose sole purpose is to set the condition code, and
1539 instructions that use the condition code, need mention @code{(cc0)}.
1541 On some machines, the condition code register is given a register number
1542 and a @code{reg} is used instead of @code{(cc0)}. This is usually the
1543 preferable approach if only a small subset of instructions modify the
1544 condition code. Other machines store condition codes in general
1545 registers; in such cases a pseudo register should be used.
1547 Some machines, such as the Sparc and RS/6000, have two sets of
1548 arithmetic instructions, one that sets and one that does not set the
1549 condition code. This is best handled by normally generating the
1550 instruction that does not set the condition code, and making a pattern
1551 that both performs the arithmetic and sets the condition code register
1552 (which would not be @code{(cc0)} in this case). For examples, search
1553 for @samp{addcc} and @samp{andcc} in @file{sparc.md}.
1557 @cindex program counter
1558 This represents the machine's program counter. It has no operands and
1559 may not have a machine mode. @code{(pc)} may be validly used only in
1560 certain specific contexts in jump instructions.
1563 There is only one expression object of code @code{pc}; it is the value
1564 of the variable @code{pc_rtx}. Any attempt to create an expression of
1565 code @code{pc} will return @code{pc_rtx}.
1567 All instructions that do not jump alter the program counter implicitly
1568 by incrementing it, but there is no need to mention this in the RTL@.
1571 @item (mem:@var{m} @var{addr} @var{alias})
1572 This RTX represents a reference to main memory at an address
1573 represented by the expression @var{addr}. @var{m} specifies how large
1574 a unit of memory is accessed. @var{alias} specifies an alias set for the
1575 reference. In general two items are in different alias sets if they cannot
1576 reference the same memory address.
1578 The construct @code{(mem:BLK (scratch))} is considered to alias all
1579 other memories. Thus it may be used as a memory barrier in epilogue
1580 stack deallocation patterns.
1583 @item (addressof:@var{m} @var{reg})
1584 This RTX represents a request for the address of register @var{reg}. Its mode
1585 is always @code{Pmode}. If there are any @code{addressof}
1586 expressions left in the function after CSE, @var{reg} is forced into the
1587 stack and the @code{addressof} expression is replaced with a @code{plus}
1588 expression for the address of its stack slot.
1592 @section RTL Expressions for Arithmetic
1593 @cindex arithmetic, in RTL
1594 @cindex math, in RTL
1595 @cindex RTL expressions for arithmetic
1597 Unless otherwise specified, all the operands of arithmetic expressions
1598 must be valid for mode @var{m}. An operand is valid for mode @var{m}
1599 if it has mode @var{m}, or if it is a @code{const_int} or
1600 @code{const_double} and @var{m} is a mode of class @code{MODE_INT}.
1602 For commutative binary operations, constants should be placed in the
1607 @cindex RTL addition
1609 @item (plus:@var{m} @var{x} @var{y})
1610 Represents the sum of the values represented by @var{x} and @var{y}
1611 carried out in machine mode @var{m}.
1614 @item (lo_sum:@var{m} @var{x} @var{y})
1615 Like @code{plus}, except that it represents that sum of @var{x} and the
1616 low-order bits of @var{y}. The number of low order bits is
1617 machine-dependent but is normally the number of bits in a @code{Pmode}
1618 item minus the number of bits set by the @code{high} code
1619 (@pxref{Constants}).
1621 @var{m} should be @code{Pmode}.
1624 @cindex RTL subtraction
1625 @cindex RTL difference
1626 @item (minus:@var{m} @var{x} @var{y})
1627 Like @code{plus} but represents subtraction.
1630 @cindex RTL addition with signed saturation
1631 @item (ss_plus:@var{m} @var{x} @var{y})
1633 Like @code{plus}, but using signed saturation in case of an overflow.
1636 @cindex RTL addition with unsigned saturation
1637 @item (us_plus:@var{m} @var{x} @var{y})
1639 Like @code{plus}, but using unsigned saturation in case of an overflow.
1642 @cindex RTL addition with signed saturation
1643 @item (ss_minus:@var{m} @var{x} @var{y})
1645 Like @code{minus}, but using signed saturation in case of an overflow.
1648 @cindex RTL addition with unsigned saturation
1649 @item (us_minus:@var{m} @var{x} @var{y})
1651 Like @code{minus}, but using unsigned saturation in case of an overflow.
1654 @cindex RTL comparison
1655 @item (compare:@var{m} @var{x} @var{y})
1656 Represents the result of subtracting @var{y} from @var{x} for purposes
1657 of comparison. The result is computed without overflow, as if with
1660 Of course, machines can't really subtract with infinite precision.
1661 However, they can pretend to do so when only the sign of the result will
1662 be used, which is the case when the result is stored in the condition
1663 code. And that is the @emph{only} way this kind of expression may
1664 validly be used: as a value to be stored in the condition codes, either
1665 @code{(cc0)} or a register. @xref{Comparisons}.
1667 The mode @var{m} is not related to the modes of @var{x} and @var{y}, but
1668 instead is the mode of the condition code value. If @code{(cc0)} is
1669 used, it is @code{VOIDmode}. Otherwise it is some mode in class
1670 @code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}. If @var{m}
1671 is @code{VOIDmode} or @code{CCmode}, the operation returns sufficient
1672 information (in an unspecified format) so that any comparison operator
1673 can be applied to the result of the @code{COMPARE} operation. For other
1674 modes in class @code{MODE_CC}, the operation only returns a subset of
1677 Normally, @var{x} and @var{y} must have the same mode. Otherwise,
1678 @code{compare} is valid only if the mode of @var{x} is in class
1679 @code{MODE_INT} and @var{y} is a @code{const_int} or
1680 @code{const_double} with mode @code{VOIDmode}. The mode of @var{x}
1681 determines what mode the comparison is to be done in; thus it must not
1684 If one of the operands is a constant, it should be placed in the
1685 second operand and the comparison code adjusted as appropriate.
1687 A @code{compare} specifying two @code{VOIDmode} constants is not valid
1688 since there is no way to know in what mode the comparison is to be
1689 performed; the comparison must either be folded during the compilation
1690 or the first operand must be loaded into a register while its mode is
1694 @item (neg:@var{m} @var{x})
1695 Represents the negation (subtraction from zero) of the value represented
1696 by @var{x}, carried out in mode @var{m}.
1699 @cindex multiplication
1701 @item (mult:@var{m} @var{x} @var{y})
1702 Represents the signed product of the values represented by @var{x} and
1703 @var{y} carried out in machine mode @var{m}.
1705 Some machines support a multiplication that generates a product wider
1706 than the operands. Write the pattern for this as
1709 (mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
1712 where @var{m} is wider than the modes of @var{x} and @var{y}, which need
1715 For unsigned widening multiplication, use the same idiom, but with
1716 @code{zero_extend} instead of @code{sign_extend}.
1720 @cindex signed division
1722 @item (div:@var{m} @var{x} @var{y})
1723 Represents the quotient in signed division of @var{x} by @var{y},
1724 carried out in machine mode @var{m}. If @var{m} is a floating point
1725 mode, it represents the exact quotient; otherwise, the integerized
1728 Some machines have division instructions in which the operands and
1729 quotient widths are not all the same; you should represent
1730 such instructions using @code{truncate} and @code{sign_extend} as in,
1733 (truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
1737 @cindex unsigned division
1739 @item (udiv:@var{m} @var{x} @var{y})
1740 Like @code{div} but represents unsigned division.
1746 @item (mod:@var{m} @var{x} @var{y})
1747 @itemx (umod:@var{m} @var{x} @var{y})
1748 Like @code{div} and @code{udiv} but represent the remainder instead of
1753 @cindex signed minimum
1754 @cindex signed maximum
1755 @item (smin:@var{m} @var{x} @var{y})
1756 @itemx (smax:@var{m} @var{x} @var{y})
1757 Represents the smaller (for @code{smin}) or larger (for @code{smax}) of
1758 @var{x} and @var{y}, interpreted as signed integers in mode @var{m}.
1762 @cindex unsigned minimum and maximum
1763 @item (umin:@var{m} @var{x} @var{y})
1764 @itemx (umax:@var{m} @var{x} @var{y})
1765 Like @code{smin} and @code{smax}, but the values are interpreted as unsigned
1769 @cindex complement, bitwise
1770 @cindex bitwise complement
1771 @item (not:@var{m} @var{x})
1772 Represents the bitwise complement of the value represented by @var{x},
1773 carried out in mode @var{m}, which must be a fixed-point machine mode.
1776 @cindex logical-and, bitwise
1777 @cindex bitwise logical-and
1778 @item (and:@var{m} @var{x} @var{y})
1779 Represents the bitwise logical-and of the values represented by
1780 @var{x} and @var{y}, carried out in machine mode @var{m}, which must be
1781 a fixed-point machine mode.
1784 @cindex inclusive-or, bitwise
1785 @cindex bitwise inclusive-or
1786 @item (ior:@var{m} @var{x} @var{y})
1787 Represents the bitwise inclusive-or of the values represented by @var{x}
1788 and @var{y}, carried out in machine mode @var{m}, which must be a
1792 @cindex exclusive-or, bitwise
1793 @cindex bitwise exclusive-or
1794 @item (xor:@var{m} @var{x} @var{y})
1795 Represents the bitwise exclusive-or of the values represented by @var{x}
1796 and @var{y}, carried out in machine mode @var{m}, which must be a
1802 @cindex arithmetic shift
1803 @item (ashift:@var{m} @var{x} @var{c})
1804 Represents the result of arithmetically shifting @var{x} left by @var{c}
1805 places. @var{x} have mode @var{m}, a fixed-point machine mode. @var{c}
1806 be a fixed-point mode or be a constant with mode @code{VOIDmode}; which
1807 mode is determined by the mode called for in the machine description
1808 entry for the left-shift instruction. For example, on the VAX, the mode
1809 of @var{c} is @code{QImode} regardless of @var{m}.
1814 @item (lshiftrt:@var{m} @var{x} @var{c})
1815 @itemx (ashiftrt:@var{m} @var{x} @var{c})
1816 Like @code{ashift} but for right shift. Unlike the case for left shift,
1817 these two operations are distinct.
1823 @cindex right rotate
1824 @item (rotate:@var{m} @var{x} @var{c})
1825 @itemx (rotatert:@var{m} @var{x} @var{c})
1826 Similar but represent left and right rotate. If @var{c} is a constant,
1830 @cindex absolute value
1831 @item (abs:@var{m} @var{x})
1832 Represents the absolute value of @var{x}, computed in mode @var{m}.
1836 @item (sqrt:@var{m} @var{x})
1837 Represents the square root of @var{x}, computed in mode @var{m}.
1838 Most often @var{m} will be a floating point mode.
1841 @item (ffs:@var{m} @var{x})
1842 Represents one plus the index of the least significant 1-bit in
1843 @var{x}, represented as an integer of mode @var{m}. (The value is
1844 zero if @var{x} is zero.) The mode of @var{x} need not be @var{m};
1845 depending on the target machine, various mode combinations may be
1850 @section Comparison Operations
1851 @cindex RTL comparison operations
1853 Comparison operators test a relation on two operands and are considered
1854 to represent a machine-dependent nonzero value described by, but not
1855 necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
1856 if the relation holds, or zero if it does not. The mode of the
1857 comparison operation is independent of the mode of the data being
1858 compared. If the comparison operation is being tested (e.g., the first
1859 operand of an @code{if_then_else}), the mode must be @code{VOIDmode}.
1860 If the comparison operation is producing data to be stored in some
1861 variable, the mode must be in class @code{MODE_INT}. All comparison
1862 operations producing data must use the same mode, which is
1865 @cindex condition codes
1866 There are two ways that comparison operations may be used. The
1867 comparison operators may be used to compare the condition codes
1868 @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such
1869 a construct actually refers to the result of the preceding instruction
1870 in which the condition codes were set. The instruction setting the
1871 condition code must be adjacent to the instruction using the condition
1872 code; only @code{note} insns may separate them.
1874 Alternatively, a comparison operation may directly compare two data
1875 objects. The mode of the comparison is determined by the operands; they
1876 must both be valid for a common machine mode. A comparison with both
1877 operands constant would be invalid as the machine mode could not be
1878 deduced from it, but such a comparison should never exist in RTL due to
1881 In the example above, if @code{(cc0)} were last set to
1882 @code{(compare @var{x} @var{y})}, the comparison operation is
1883 identical to @code{(eq @var{x} @var{y})}. Usually only one style
1884 of comparisons is supported on a particular machine, but the combine
1885 pass will try to merge the operations to produce the @code{eq} shown
1886 in case it exists in the context of the particular insn involved.
1888 Inequality comparisons come in two flavors, signed and unsigned. Thus,
1889 there are distinct expression codes @code{gt} and @code{gtu} for signed and
1890 unsigned greater-than. These can produce different results for the same
1891 pair of integer values: for example, 1 is signed greater-than @minus{}1 but not
1892 unsigned greater-than, because @minus{}1 when regarded as unsigned is actually
1893 @code{0xffffffff} which is greater than 1.
1895 The signed comparisons are also used for floating point values. Floating
1896 point comparisons are distinguished by the machine modes of the operands.
1901 @item (eq:@var{m} @var{x} @var{y})
1902 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
1903 are equal, otherwise 0.
1907 @item (ne:@var{m} @var{x} @var{y})
1908 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
1909 are not equal, otherwise 0.
1912 @cindex greater than
1913 @item (gt:@var{m} @var{x} @var{y})
1914 @code{STORE_FLAG_VALUE} if the @var{x} is greater than @var{y}. If they
1915 are fixed-point, the comparison is done in a signed sense.
1918 @cindex greater than
1919 @cindex unsigned greater than
1920 @item (gtu:@var{m} @var{x} @var{y})
1921 Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
1926 @cindex unsigned less than
1927 @item (lt:@var{m} @var{x} @var{y})
1928 @itemx (ltu:@var{m} @var{x} @var{y})
1929 Like @code{gt} and @code{gtu} but test for ``less than''.
1932 @cindex greater than
1934 @cindex unsigned greater than
1935 @item (ge:@var{m} @var{x} @var{y})
1936 @itemx (geu:@var{m} @var{x} @var{y})
1937 Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
1940 @cindex less than or equal
1942 @cindex unsigned less than
1943 @item (le:@var{m} @var{x} @var{y})
1944 @itemx (leu:@var{m} @var{x} @var{y})
1945 Like @code{gt} and @code{gtu} but test for ``less than or equal''.
1947 @findex if_then_else
1948 @item (if_then_else @var{cond} @var{then} @var{else})
1949 This is not a comparison operation but is listed here because it is
1950 always used in conjunction with a comparison operation. To be
1951 precise, @var{cond} is a comparison expression. This expression
1952 represents a choice, according to @var{cond}, between the value
1953 represented by @var{then} and the one represented by @var{else}.
1955 On most machines, @code{if_then_else} expressions are valid only
1956 to express conditional jumps.
1959 @item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
1960 Similar to @code{if_then_else}, but more general. Each of @var{test1},
1961 @var{test2}, @dots{} is performed in turn. The result of this expression is
1962 the @var{value} corresponding to the first nonzero test, or @var{default} if
1963 none of the tests are nonzero expressions.
1965 This is currently not valid for instruction patterns and is supported only
1966 for insn attributes. @xref{Insn Attributes}.
1973 Special expression codes exist to represent bit-field instructions.
1974 These types of expressions are lvalues in RTL; they may appear
1975 on the left side of an assignment, indicating insertion of a value
1976 into the specified bit-field.
1979 @findex sign_extract
1980 @cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
1981 @item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
1982 This represents a reference to a sign-extended bit-field contained or
1983 starting in @var{loc} (a memory or register reference). The bit-field
1984 is @var{size} bits wide and starts at bit @var{pos}. The compilation
1985 option @code{BITS_BIG_ENDIAN} says which end of the memory unit
1986 @var{pos} counts from.
1988 If @var{loc} is in memory, its mode must be a single-byte integer mode.
1989 If @var{loc} is in a register, the mode to use is specified by the
1990 operand of the @code{insv} or @code{extv} pattern
1991 (@pxref{Standard Names}) and is usually a full-word integer mode,
1992 which is the default if none is specified.
1994 The mode of @var{pos} is machine-specific and is also specified
1995 in the @code{insv} or @code{extv} pattern.
1997 The mode @var{m} is the same as the mode that would be used for
1998 @var{loc} if it were a register.
2000 @findex zero_extract
2001 @item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
2002 Like @code{sign_extract} but refers to an unsigned or zero-extended
2003 bit-field. The same sequence of bits are extracted, but they
2004 are filled to an entire word with zeros instead of by sign-extension.
2007 @node Vector Operations
2008 @section Vector Operations
2009 @cindex vector operations
2011 All normal RTL expressions can be used with vector modes; they are
2012 interpreted as operating on each part of the vector independently.
2013 Additionally, there are a few new expressions to describe specific vector
2018 @item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items})
2019 This describes a merge operation between two vectors. The result is a vector
2020 of mode @var{m}; its elements are selected from either @var{vec1} or
2021 @var{vec2}. Which elements are selected is described by @var{items}, which
2022 is a bit mask represented by a @code{const_int}; a zero bit indicates the
2023 corresponding element in the result vector is taken from @var{vec2} while
2024 a set bit indicates it is taken from @var{vec1}.
2027 @item (vec_select:@var{m} @var{vec1} @var{selection})
2028 This describes an operation that selects parts of a vector. @var{vec1} is
2029 the source vector, @var{selection} is a @code{parallel} that contains a
2030 @code{const_int} for each of the subparts of the result vector, giving the
2031 number of the source subpart that should be stored into it.
2034 @item (vec_concat:@var{m} @var{vec1} @var{vec2})
2035 Describes a vector concat operation. The result is a concatenation of the
2036 vectors @var{vec1} and @var{vec2}; its length is the sum of the lengths of
2040 @item (vec_const:@var{m} @var{subparts})
2041 This describes a constant vector. @var{subparts} is a @code{parallel} that
2042 contains a constant for each of the subparts of the vector.
2044 @findex vec_duplicate
2045 @item (vec_duplicate:@var{m} @var{vec})
2046 This operation converts a small vector into a larger one by duplicating the
2047 input values. The output vector mode must have the same submodes as the
2048 input vector mode, and the number of output parts must be an integer multiple
2049 of the number of input parts.
2054 @section Conversions
2056 @cindex machine mode conversions
2058 All conversions between machine modes must be represented by
2059 explicit conversion operations. For example, an expression
2060 which is the sum of a byte and a full word cannot be written as
2061 @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
2062 operation requires two operands of the same machine mode.
2063 Therefore, the byte-sized operand is enclosed in a conversion
2067 (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
2070 The conversion operation is not a mere placeholder, because there
2071 may be more than one way of converting from a given starting mode
2072 to the desired final mode. The conversion operation code says how
2075 For all conversion operations, @var{x} must not be @code{VOIDmode}
2076 because the mode in which to do the conversion would not be known.
2077 The conversion must either be done at compile-time or @var{x}
2078 must be placed into a register.
2082 @item (sign_extend:@var{m} @var{x})
2083 Represents the result of sign-extending the value @var{x}
2084 to machine mode @var{m}. @var{m} must be a fixed-point mode
2085 and @var{x} a fixed-point value of a mode narrower than @var{m}.
2088 @item (zero_extend:@var{m} @var{x})
2089 Represents the result of zero-extending the value @var{x}
2090 to machine mode @var{m}. @var{m} must be a fixed-point mode
2091 and @var{x} a fixed-point value of a mode narrower than @var{m}.
2093 @findex float_extend
2094 @item (float_extend:@var{m} @var{x})
2095 Represents the result of extending the value @var{x}
2096 to machine mode @var{m}. @var{m} must be a floating point mode
2097 and @var{x} a floating point value of a mode narrower than @var{m}.
2100 @item (truncate:@var{m} @var{x})
2101 Represents the result of truncating the value @var{x}
2102 to machine mode @var{m}. @var{m} must be a fixed-point mode
2103 and @var{x} a fixed-point value of a mode wider than @var{m}.
2106 @item (ss_truncate:@var{m} @var{x})
2107 Represents the result of truncating the value @var{x}
2108 to machine mode @var{m}, using signed saturation in the case of
2109 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
2113 @item (us_truncate:@var{m} @var{x})
2114 Represents the result of truncating the value @var{x}
2115 to machine mode @var{m}, using unsigned saturation in the case of
2116 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
2119 @findex float_truncate
2120 @item (float_truncate:@var{m} @var{x})
2121 Represents the result of truncating the value @var{x}
2122 to machine mode @var{m}. @var{m} must be a floating point mode
2123 and @var{x} a floating point value of a mode wider than @var{m}.
2126 @item (float:@var{m} @var{x})
2127 Represents the result of converting fixed point value @var{x},
2128 regarded as signed, to floating point mode @var{m}.
2130 @findex unsigned_float
2131 @item (unsigned_float:@var{m} @var{x})
2132 Represents the result of converting fixed point value @var{x},
2133 regarded as unsigned, to floating point mode @var{m}.
2136 @item (fix:@var{m} @var{x})
2137 When @var{m} is a fixed point mode, represents the result of
2138 converting floating point value @var{x} to mode @var{m}, regarded as
2139 signed. How rounding is done is not specified, so this operation may
2140 be used validly in compiling C code only for integer-valued operands.
2142 @findex unsigned_fix
2143 @item (unsigned_fix:@var{m} @var{x})
2144 Represents the result of converting floating point value @var{x} to
2145 fixed point mode @var{m}, regarded as unsigned. How rounding is done
2149 @item (fix:@var{m} @var{x})
2150 When @var{m} is a floating point mode, represents the result of
2151 converting floating point value @var{x} (valid for mode @var{m}) to an
2152 integer, still represented in floating point mode @var{m}, by rounding
2156 @node RTL Declarations
2157 @section Declarations
2158 @cindex RTL declarations
2159 @cindex declarations, RTL
2161 Declaration expression codes do not represent arithmetic operations
2162 but rather state assertions about their operands.
2165 @findex strict_low_part
2166 @cindex @code{subreg}, in @code{strict_low_part}
2167 @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
2168 This expression code is used in only one context: as the destination operand of a
2169 @code{set} expression. In addition, the operand of this expression
2170 must be a non-paradoxical @code{subreg} expression.
2172 The presence of @code{strict_low_part} says that the part of the
2173 register which is meaningful in mode @var{n}, but is not part of
2174 mode @var{m}, is not to be altered. Normally, an assignment to such
2175 a subreg is allowed to have undefined effects on the rest of the
2176 register when @var{m} is less than a word.
2180 @section Side Effect Expressions
2181 @cindex RTL side effect expressions
2183 The expression codes described so far represent values, not actions.
2184 But machine instructions never produce values; they are meaningful
2185 only for their side effects on the state of the machine. Special
2186 expression codes are used to represent side effects.
2188 The body of an instruction is always one of these side effect codes;
2189 the codes described above, which represent values, appear only as
2190 the operands of these.
2194 @item (set @var{lval} @var{x})
2195 Represents the action of storing the value of @var{x} into the place
2196 represented by @var{lval}. @var{lval} must be an expression
2197 representing a place that can be stored in: @code{reg} (or @code{subreg}
2198 or @code{strict_low_part}), @code{mem}, @code{pc}, @code{parallel}, or
2201 If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
2202 machine mode; then @var{x} must be valid for that mode.
2204 If @var{lval} is a @code{reg} whose machine mode is less than the full
2205 width of the register, then it means that the part of the register
2206 specified by the machine mode is given the specified value and the
2207 rest of the register receives an undefined value. Likewise, if
2208 @var{lval} is a @code{subreg} whose machine mode is narrower than
2209 the mode of the register, the rest of the register can be changed in
2212 If @var{lval} is a @code{strict_low_part} of a @code{subreg}, then the
2213 part of the register specified by the machine mode of the
2214 @code{subreg} is given the value @var{x} and the rest of the register
2217 If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
2218 be either a @code{compare} expression or a value that may have any mode.
2219 The latter case represents a ``test'' instruction. The expression
2220 @code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to
2221 @code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}.
2222 Use the former expression to save space during the compilation.
2224 If @var{lval} is a @code{parallel}, it is used to represent the case of
2225 a function returning a structure in multiple registers. Each element
2226 of the @code{parallel} is an @code{expr_list} whose first operand is a
2227 @code{reg} and whose second operand is a @code{const_int} representing the
2228 offset (in bytes) into the structure at which the data in that register
2229 corresponds. The first element may be null to indicate that the structure
2230 is also passed partly in memory.
2232 @cindex jump instructions and @code{set}
2233 @cindex @code{if_then_else} usage
2234 If @var{lval} is @code{(pc)}, we have a jump instruction, and the
2235 possibilities for @var{x} are very limited. It may be a
2236 @code{label_ref} expression (unconditional jump). It may be an
2237 @code{if_then_else} (conditional jump), in which case either the
2238 second or the third operand must be @code{(pc)} (for the case which
2239 does not jump) and the other of the two must be a @code{label_ref}
2240 (for the case which does jump). @var{x} may also be a @code{mem} or
2241 @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
2242 @code{mem}; these unusual patterns are used to represent jumps through
2245 If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of
2246 @var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
2247 valid for the mode of @var{lval}.
2251 @var{lval} is customarily accessed with the @code{SET_DEST} macro and
2252 @var{x} with the @code{SET_SRC} macro.
2256 As the sole expression in a pattern, represents a return from the
2257 current function, on machines where this can be done with one
2258 instruction, such as VAXen. On machines where a multi-instruction
2259 ``epilogue'' must be executed in order to return from the function,
2260 returning is done by jumping to a label which precedes the epilogue, and
2261 the @code{return} expression code is never used.
2263 Inside an @code{if_then_else} expression, represents the value to be
2264 placed in @code{pc} to return to the caller.
2266 Note that an insn pattern of @code{(return)} is logically equivalent to
2267 @code{(set (pc) (return))}, but the latter form is never used.
2270 @item (call @var{function} @var{nargs})
2271 Represents a function call. @var{function} is a @code{mem} expression
2272 whose address is the address of the function to be called.
2273 @var{nargs} is an expression which can be used for two purposes: on
2274 some machines it represents the number of bytes of stack argument; on
2275 others, it represents the number of argument registers.
2277 Each machine has a standard machine mode which @var{function} must
2278 have. The machine description defines macro @code{FUNCTION_MODE} to
2279 expand into the requisite mode name. The purpose of this mode is to
2280 specify what kind of addressing is allowed, on machines where the
2281 allowed kinds of addressing depend on the machine mode being
2285 @item (clobber @var{x})
2286 Represents the storing or possible storing of an unpredictable,
2287 undescribed value into @var{x}, which must be a @code{reg},
2288 @code{scratch}, @code{parallel} or @code{mem} expression.
2290 One place this is used is in string instructions that store standard
2291 values into particular hard registers. It may not be worth the
2292 trouble to describe the values that are stored, but it is essential to
2293 inform the compiler that the registers will be altered, lest it
2294 attempt to keep data in them across the string instruction.
2296 If @var{x} is @code{(mem:BLK (const_int 0))}, it means that all memory
2297 locations must be presumed clobbered. If @var{x} is a @code{parallel},
2298 it has the same meaning as a @code{parallel} in a @code{set} expression.
2300 Note that the machine description classifies certain hard registers as
2301 ``call-clobbered''. All function call instructions are assumed by
2302 default to clobber these registers, so there is no need to use
2303 @code{clobber} expressions to indicate this fact. Also, each function
2304 call is assumed to have the potential to alter any memory location,
2305 unless the function is declared @code{const}.
2307 If the last group of expressions in a @code{parallel} are each a
2308 @code{clobber} expression whose arguments are @code{reg} or
2309 @code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
2310 phase can add the appropriate @code{clobber} expressions to an insn it
2311 has constructed when doing so will cause a pattern to be matched.
2313 This feature can be used, for example, on a machine that whose multiply
2314 and add instructions don't use an MQ register but which has an
2315 add-accumulate instruction that does clobber the MQ register. Similarly,
2316 a combined instruction might require a temporary register while the
2317 constituent instructions might not.
2319 When a @code{clobber} expression for a register appears inside a
2320 @code{parallel} with other side effects, the register allocator
2321 guarantees that the register is unoccupied both before and after that
2322 insn. However, the reload phase may allocate a register used for one of
2323 the inputs unless the @samp{&} constraint is specified for the selected
2324 alternative (@pxref{Modifiers}). You can clobber either a specific hard
2325 register, a pseudo register, or a @code{scratch} expression; in the
2326 latter two cases, GCC will allocate a hard register that is available
2327 there for use as a temporary.
2329 For instructions that require a temporary register, you should use
2330 @code{scratch} instead of a pseudo-register because this will allow the
2331 combiner phase to add the @code{clobber} when required. You do this by
2332 coding (@code{clobber} (@code{match_scratch} @dots{})). If you do
2333 clobber a pseudo register, use one which appears nowhere else---generate
2334 a new one each time. Otherwise, you may confuse CSE@.
2336 There is one other known use for clobbering a pseudo register in a
2337 @code{parallel}: when one of the input operands of the insn is also
2338 clobbered by the insn. In this case, using the same pseudo register in
2339 the clobber and elsewhere in the insn produces the expected results.
2343 Represents the use of the value of @var{x}. It indicates that the
2344 value in @var{x} at this point in the program is needed, even though
2345 it may not be apparent why this is so. Therefore, the compiler will
2346 not attempt to delete previous instructions whose only effect is to
2347 store a value in @var{x}. @var{x} must be a @code{reg} expression.
2349 In some situations, it may be tempting to add a @code{use} of a
2350 register in a @code{parallel} to describe a situation where the value
2351 of a special register will modify the behavior of the instruction.
2352 An hypothetical example might be a pattern for an addition that can
2353 either wrap around or use saturating addition depending on the value
2354 of a special control register:
2357 (parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
2364 This will not work, several of the optimizers only look at expressions
2365 locally; it is very likely that if you have multiple insns with
2366 identical inputs to the @code{unspec}, they will be optimized away even
2367 if register 1 changes in between.
2369 This means that @code{use} can @emph{only} be used to describe
2370 that the register is live. You should think twice before adding
2371 @code{use} statements, more often you will want to use @code{unspec}
2372 instead. The @code{use} RTX is most commonly useful to describe that
2373 a fixed register is implicitly used in an insn. It is also safe to use
2374 in patterns where the compiler knows for other reasons that the result
2375 of the whole pattern is variable, such as @samp{movstr@var{m}} or
2376 @samp{call} patterns.
2378 During the reload phase, an insn that has a @code{use} as pattern
2379 can carry a reg_equal note. These @code{use} insns will be deleted
2380 before the reload phase exits.
2382 During the delayed branch scheduling phase, @var{x} may be an insn.
2383 This indicates that @var{x} previously was located at this place in the
2384 code and its data dependencies need to be taken into account. These
2385 @code{use} insns will be deleted before the delayed branch scheduling
2389 @item (parallel [@var{x0} @var{x1} @dots{}])
2390 Represents several side effects performed in parallel. The square
2391 brackets stand for a vector; the operand of @code{parallel} is a
2392 vector of expressions. @var{x0}, @var{x1} and so on are individual
2393 side effect expressions---expressions of code @code{set}, @code{call},
2394 @code{return}, @code{clobber} or @code{use}.
2396 ``In parallel'' means that first all the values used in the individual
2397 side-effects are computed, and second all the actual side-effects are
2398 performed. For example,
2401 (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
2402 (set (mem:SI (reg:SI 1)) (reg:SI 1))])
2406 says unambiguously that the values of hard register 1 and the memory
2407 location addressed by it are interchanged. In both places where
2408 @code{(reg:SI 1)} appears as a memory address it refers to the value
2409 in register 1 @emph{before} the execution of the insn.
2411 It follows that it is @emph{incorrect} to use @code{parallel} and
2412 expect the result of one @code{set} to be available for the next one.
2413 For example, people sometimes attempt to represent a jump-if-zero
2414 instruction this way:
2417 (parallel [(set (cc0) (reg:SI 34))
2418 (set (pc) (if_then_else
2419 (eq (cc0) (const_int 0))
2425 But this is incorrect, because it says that the jump condition depends
2426 on the condition code value @emph{before} this instruction, not on the
2427 new value that is set by this instruction.
2429 @cindex peephole optimization, RTL representation
2430 Peephole optimization, which takes place together with final assembly
2431 code output, can produce insns whose patterns consist of a @code{parallel}
2432 whose elements are the operands needed to output the resulting
2433 assembler code---often @code{reg}, @code{mem} or constant expressions.
2434 This would not be well-formed RTL at any other stage in compilation,
2435 but it is ok then because no further optimization remains to be done.
2436 However, the definition of the macro @code{NOTICE_UPDATE_CC}, if
2437 any, must deal with such insns if you define any peephole optimizations.
2440 @item (cond_exec [@var{cond} @var{expr}])
2441 Represents a conditionally executed expression. The @var{expr} is
2442 executed only if the @var{cond} is nonzero. The @var{cond} expression
2443 must not have side-effects, but the @var{expr} may very well have
2447 @item (sequence [@var{insns} @dots{}])
2448 Represents a sequence of insns. Each of the @var{insns} that appears
2449 in the vector is suitable for appearing in the chain of insns, so it
2450 must be an @code{insn}, @code{jump_insn}, @code{call_insn},
2451 @code{code_label}, @code{barrier} or @code{note}.
2453 A @code{sequence} RTX is never placed in an actual insn during RTL
2454 generation. It represents the sequence of insns that result from a
2455 @code{define_expand} @emph{before} those insns are passed to
2456 @code{emit_insn} to insert them in the chain of insns. When actually
2457 inserted, the individual sub-insns are separated out and the
2458 @code{sequence} is forgotten.
2460 After delay-slot scheduling is completed, an insn and all the insns that
2461 reside in its delay slots are grouped together into a @code{sequence}.
2462 The insn requiring the delay slot is the first insn in the vector;
2463 subsequent insns are to be placed in the delay slot.
2465 @code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
2466 indicate that a branch insn should be used that will conditionally annul
2467 the effect of the insns in the delay slots. In such a case,
2468 @code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
2469 the branch and should be executed only if the branch is taken; otherwise
2470 the insn should be executed only if the branch is not taken.
2474 These expression codes appear in place of a side effect, as the body of
2475 an insn, though strictly speaking they do not always describe side
2480 @item (asm_input @var{s})
2481 Represents literal assembler code as described by the string @var{s}.
2484 @findex unspec_volatile
2485 @item (unspec [@var{operands} @dots{}] @var{index})
2486 @itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
2487 Represents a machine-specific operation on @var{operands}. @var{index}
2488 selects between multiple machine-specific operations.
2489 @code{unspec_volatile} is used for volatile operations and operations
2490 that may trap; @code{unspec} is used for other operations.
2492 These codes may appear inside a @code{pattern} of an
2493 insn, inside a @code{parallel}, or inside an expression.
2496 @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
2497 Represents a table of jump addresses. The vector elements @var{lr0},
2498 etc., are @code{label_ref} expressions. The mode @var{m} specifies
2499 how much space is given to each address; normally @var{m} would be
2502 @findex addr_diff_vec
2503 @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags})
2504 Represents a table of jump addresses expressed as offsets from
2505 @var{base}. The vector elements @var{lr0}, etc., are @code{label_ref}
2506 expressions and so is @var{base}. The mode @var{m} specifies how much
2507 space is given to each address-difference. @var{min} and @var{max}
2508 are set up by branch shortening and hold a label with a minimum and a
2509 maximum address, respectively. @var{flags} indicates the relative
2510 position of @var{base}, @var{min} and @var{max} to the containing insn
2511 and of @var{min} and @var{max} to @var{base}. See rtl.def for details.
2514 @item (prefetch:@var{m} @var{addr} @var{rw} @var{locality})
2515 Represents prefetch of memory at address @var{addr}.
2516 Operand @var{rw} is 1 if the prefetch is for data to be written, 0 otherwise;
2517 targets that do not support write prefetches should treat this as a normal
2519 Operand @var{locality} specifies the amount of temporal locality; 0 if there
2520 is none or 1, 2, or 3 for increasing levels of temporal locality;
2521 targets that do not support locality hints should ignore this.
2523 This insn is used to minimize cache-miss latency by moving data into a
2524 cache before it is accessed. It should use only non-faulting data prefetch
2529 @section Embedded Side-Effects on Addresses
2530 @cindex RTL preincrement
2531 @cindex RTL postincrement
2532 @cindex RTL predecrement
2533 @cindex RTL postdecrement
2535 Six special side-effect expression codes appear as memory addresses.
2539 @item (pre_dec:@var{m} @var{x})
2540 Represents the side effect of decrementing @var{x} by a standard
2541 amount and represents also the value that @var{x} has after being
2542 decremented. @var{x} must be a @code{reg} or @code{mem}, but most
2543 machines allow only a @code{reg}. @var{m} must be the machine mode
2544 for pointers on the machine in use. The amount @var{x} is decremented
2545 by is the length in bytes of the machine mode of the containing memory
2546 reference of which this expression serves as the address. Here is an
2550 (mem:DF (pre_dec:SI (reg:SI 39)))
2554 This says to decrement pseudo register 39 by the length of a @code{DFmode}
2555 value and use the result to address a @code{DFmode} value.
2558 @item (pre_inc:@var{m} @var{x})
2559 Similar, but specifies incrementing @var{x} instead of decrementing it.
2562 @item (post_dec:@var{m} @var{x})
2563 Represents the same side effect as @code{pre_dec} but a different
2564 value. The value represented here is the value @var{x} has @i{before}
2568 @item (post_inc:@var{m} @var{x})
2569 Similar, but specifies incrementing @var{x} instead of decrementing it.
2572 @item (post_modify:@var{m} @var{x} @var{y})
2574 Represents the side effect of setting @var{x} to @var{y} and
2575 represents @var{x} before @var{x} is modified. @var{x} must be a
2576 @code{reg} or @code{mem}, but most machines allow only a @code{reg}.
2577 @var{m} must be the machine mode for pointers on the machine in use.
2578 The amount @var{x} is decremented by is the length in bytes of the
2579 machine mode of the containing memory reference of which this expression
2580 serves as the address. Note that this is not currently implemented.
2582 The expression @var{y} must be one of three forms:
2584 @code{(plus:@var{m} @var{x} @var{z})},
2585 @code{(minus:@var{m} @var{x} @var{z})}, or
2586 @code{(plus:@var{m} @var{x} @var{i})},
2588 where @var{z} is an index register and @var{i} is a constant.
2590 Here is an example of its use:
2593 (mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
2597 This says to modify pseudo register 42 by adding the contents of pseudo
2598 register 48 to it, after the use of what ever 42 points to.
2601 @item (pre_modify:@var{m} @var{x} @var{expr})
2602 Similar except side effects happen before the use.
2605 These embedded side effect expressions must be used with care. Instruction
2606 patterns may not use them. Until the @samp{flow} pass of the compiler,
2607 they may occur only to represent pushes onto the stack. The @samp{flow}
2608 pass finds cases where registers are incremented or decremented in one
2609 instruction and used as an address shortly before or after; these cases are
2610 then transformed to use pre- or post-increment or -decrement.
2612 If a register used as the operand of these expressions is used in
2613 another address in an insn, the original value of the register is used.
2614 Uses of the register outside of an address are not permitted within the
2615 same insn as a use in an embedded side effect expression because such
2616 insns behave differently on different machines and hence must be treated
2617 as ambiguous and disallowed.
2619 An instruction that can be represented with an embedded side effect
2620 could also be represented using @code{parallel} containing an additional
2621 @code{set} to describe how the address register is altered. This is not
2622 done because machines that allow these operations at all typically
2623 allow them wherever a memory address is called for. Describing them as
2624 additional parallel stores would require doubling the number of entries
2625 in the machine description.
2628 @section Assembler Instructions as Expressions
2629 @cindex assembler instructions in RTL
2631 @cindex @code{asm_operands}, usage
2632 The RTX code @code{asm_operands} represents a value produced by a
2633 user-specified assembler instruction. It is used to represent
2634 an @code{asm} statement with arguments. An @code{asm} statement with
2635 a single output operand, like this:
2638 asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
2642 is represented using a single @code{asm_operands} RTX which represents
2643 the value that is stored in @code{outputvar}:
2646 (set @var{rtx-for-outputvar}
2647 (asm_operands "foo %1,%2,%0" "a" 0
2648 [@var{rtx-for-addition-result} @var{rtx-for-*z}]
2649 [(asm_input:@var{m1} "g")
2650 (asm_input:@var{m2} "di")]))
2654 Here the operands of the @code{asm_operands} RTX are the assembler
2655 template string, the output-operand's constraint, the index-number of the
2656 output operand among the output operands specified, a vector of input
2657 operand RTX's, and a vector of input-operand modes and constraints. The
2658 mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
2661 When an @code{asm} statement has multiple output values, its insn has
2662 several such @code{set} RTX's inside of a @code{parallel}. Each @code{set}
2663 contains a @code{asm_operands}; all of these share the same assembler
2664 template and vectors, but each contains the constraint for the respective
2665 output operand. They are also distinguished by the output-operand index
2666 number, which is 0, 1, @dots{} for successive output operands.
2672 The RTL representation of the code for a function is a doubly-linked
2673 chain of objects called @dfn{insns}. Insns are expressions with
2674 special codes that are used for no other purpose. Some insns are
2675 actual instructions; others represent dispatch tables for @code{switch}
2676 statements; others represent labels to jump to or various sorts of
2677 declarative information.
2679 In addition to its own specific data, each insn must have a unique
2680 id-number that distinguishes it from all other insns in the current
2681 function (after delayed branch scheduling, copies of an insn with the
2682 same id-number may be present in multiple places in a function, but
2683 these copies will always be identical and will only appear inside a
2684 @code{sequence}), and chain pointers to the preceding and following
2685 insns. These three fields occupy the same position in every insn,
2686 independent of the expression code of the insn. They could be accessed
2687 with @code{XEXP} and @code{XINT}, but instead three special macros are
2692 @item INSN_UID (@var{i})
2693 Accesses the unique id of insn @var{i}.
2696 @item PREV_INSN (@var{i})
2697 Accesses the chain pointer to the insn preceding @var{i}.
2698 If @var{i} is the first insn, this is a null pointer.
2701 @item NEXT_INSN (@var{i})
2702 Accesses the chain pointer to the insn following @var{i}.
2703 If @var{i} is the last insn, this is a null pointer.
2707 @findex get_last_insn
2708 The first insn in the chain is obtained by calling @code{get_insns}; the
2709 last insn is the result of calling @code{get_last_insn}. Within the
2710 chain delimited by these insns, the @code{NEXT_INSN} and
2711 @code{PREV_INSN} pointers must always correspond: if @var{insn} is not
2715 NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
2719 is always true and if @var{insn} is not the last insn,
2722 PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
2728 After delay slot scheduling, some of the insns in the chain might be
2729 @code{sequence} expressions, which contain a vector of insns. The value
2730 of @code{NEXT_INSN} in all but the last of these insns is the next insn
2731 in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
2732 is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
2733 which it is contained. Similar rules apply for @code{PREV_INSN}.
2735 This means that the above invariants are not necessarily true for insns
2736 inside @code{sequence} expressions. Specifically, if @var{insn} is the
2737 first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
2738 is the insn containing the @code{sequence} expression, as is the value
2739 of @code{PREV_INSN (NEXT_INSN (@var{insn}))} if @var{insn} is the last
2740 insn in the @code{sequence} expression. You can use these expressions
2741 to find the containing @code{sequence} expression.
2743 Every insn has one of the following six expression codes:
2748 The expression code @code{insn} is used for instructions that do not jump
2749 and do not do function calls. @code{sequence} expressions are always
2750 contained in insns with code @code{insn} even if one of those insns
2751 should jump or do function calls.
2753 Insns with code @code{insn} have four additional fields beyond the three
2754 mandatory ones listed above. These four are described in a table below.
2758 The expression code @code{jump_insn} is used for instructions that may
2759 jump (or, more generally, may contain @code{label_ref} expressions). If
2760 there is an instruction to return from the current function, it is
2761 recorded as a @code{jump_insn}.
2764 @code{jump_insn} insns have the same extra fields as @code{insn} insns,
2765 accessed in the same way and in addition contain a field
2766 @code{JUMP_LABEL} which is defined once jump optimization has completed.
2768 For simple conditional and unconditional jumps, this field contains
2769 the @code{code_label} to which this insn will (possibly conditionally)
2770 branch. In a more complex jump, @code{JUMP_LABEL} records one of the
2771 labels that the insn refers to; the only way to find the others is to
2772 scan the entire body of the insn. In an @code{addr_vec},
2773 @code{JUMP_LABEL} is @code{NULL_RTX}.
2775 Return insns count as jumps, but since they do not refer to any
2776 labels, their @code{JUMP_LABEL} is @code{NULL_RTX}.
2780 The expression code @code{call_insn} is used for instructions that may do
2781 function calls. It is important to distinguish these instructions because
2782 they imply that certain registers and memory locations may be altered
2785 @findex CALL_INSN_FUNCTION_USAGE
2786 @code{call_insn} insns have the same extra fields as @code{insn} insns,
2787 accessed in the same way and in addition contain a field
2788 @code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of
2789 @code{expr_list} expressions) containing @code{use} and @code{clobber}
2790 expressions that denote hard registers and @code{MEM}s used or
2791 clobbered by the called function.
2793 A @code{MEM} generally points to a stack slots in which arguments passed
2794 to the libcall by reference (@pxref{Register Arguments,
2795 FUNCTION_ARG_PASS_BY_REFERENCE}) are stored. If the argument is
2796 caller-copied (@pxref{Register Arguments, FUNCTION_ARG_CALLEE_COPIES}),
2797 the stack slot will be mentioned in @code{CLOBBER} and @code{USE}
2798 entries; if it's callee-copied, only a @code{USE} will appear, and the
2799 @code{MEM} may point to addresses that are not stack slots. These
2800 @code{MEM}s are used only in libcalls, because, unlike regular function
2801 calls, @code{CONST_CALL}s (which libcalls generally are, @pxref{Flags,
2802 CONST_CALL_P}) aren't assumed to read and write all memory, so flow
2803 would consider the stores dead and remove them. Note that, since a
2804 libcall must never return values in memory (@pxref{Aggregate Return,
2805 RETURN_IN_MEMORY}), there will never be a @code{CLOBBER} for a memory
2806 address holding a return value.
2808 @code{CLOBBER}ed registers in this list augment registers specified in
2809 @code{CALL_USED_REGISTERS} (@pxref{Register Basics}).
2812 @findex CODE_LABEL_NUMBER
2814 A @code{code_label} insn represents a label that a jump insn can jump
2815 to. It contains two special fields of data in addition to the three
2816 standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
2817 number}, a number that identifies this label uniquely among all the
2818 labels in the compilation (not just in the current function).
2819 Ultimately, the label is represented in the assembler output as an
2820 assembler label, usually of the form @samp{L@var{n}} where @var{n} is
2823 When a @code{code_label} appears in an RTL expression, it normally
2824 appears within a @code{label_ref} which represents the address of
2825 the label, as a number.
2827 Besides as a @code{code_label}, a label can also be represented as a
2828 @code{note} of type @code{NOTE_INSN_DELETED_LABEL}.
2831 The field @code{LABEL_NUSES} is only defined once the jump optimization
2832 phase is completed and contains the number of times this label is
2833 referenced in the current function.
2835 @findex LABEL_ALTERNATE_NAME
2836 The field @code{LABEL_ALTERNATE_NAME} is used to associate a name with
2837 a @code{code_label}. If this field is defined, the alternate name will
2838 be emitted instead of an internally generated label name.
2842 Barriers are placed in the instruction stream when control cannot flow
2843 past them. They are placed after unconditional jump instructions to
2844 indicate that the jumps are unconditional and after calls to
2845 @code{volatile} functions, which do not return (e.g., @code{exit}).
2846 They contain no information beyond the three standard fields.
2849 @findex NOTE_LINE_NUMBER
2850 @findex NOTE_SOURCE_FILE
2852 @code{note} insns are used to represent additional debugging and
2853 declarative information. They contain two nonstandard fields, an
2854 integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
2855 string accessed with @code{NOTE_SOURCE_FILE}.
2857 If @code{NOTE_LINE_NUMBER} is positive, the note represents the
2858 position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
2859 that the line came from. These notes control generation of line
2860 number data in the assembler output.
2862 Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
2863 code with one of the following values (and @code{NOTE_SOURCE_FILE}
2864 must contain a null pointer):
2867 @findex NOTE_INSN_DELETED
2868 @item NOTE_INSN_DELETED
2869 Such a note is completely ignorable. Some passes of the compiler
2870 delete insns by altering them into notes of this kind.
2872 @findex NOTE_INSN_DELETED_LABEL
2873 @item NOTE_INSN_DELETED_LABEL
2874 This marks what used to be a @code{code_label}, but was not used for other
2875 purposes than taking its address and was transformed to mark that no
2878 @findex NOTE_INSN_BLOCK_BEG
2879 @findex NOTE_INSN_BLOCK_END
2880 @item NOTE_INSN_BLOCK_BEG
2881 @itemx NOTE_INSN_BLOCK_END
2882 These types of notes indicate the position of the beginning and end
2883 of a level of scoping of variable names. They control the output
2884 of debugging information.
2886 @findex NOTE_INSN_EH_REGION_BEG
2887 @findex NOTE_INSN_EH_REGION_END
2888 @item NOTE_INSN_EH_REGION_BEG
2889 @itemx NOTE_INSN_EH_REGION_END
2890 These types of notes indicate the position of the beginning and end of a
2891 level of scoping for exception handling. @code{NOTE_BLOCK_NUMBER}
2892 identifies which @code{CODE_LABEL} or @code{note} of type
2893 @code{NOTE_INSN_DELETED_LABEL} is associated with the given region.
2895 @findex NOTE_INSN_LOOP_BEG
2896 @findex NOTE_INSN_LOOP_END
2897 @item NOTE_INSN_LOOP_BEG
2898 @itemx NOTE_INSN_LOOP_END
2899 These types of notes indicate the position of the beginning and end
2900 of a @code{while} or @code{for} loop. They enable the loop optimizer
2901 to find loops quickly.
2903 @findex NOTE_INSN_LOOP_CONT
2904 @item NOTE_INSN_LOOP_CONT
2905 Appears at the place in a loop that @code{continue} statements jump to.
2907 @findex NOTE_INSN_LOOP_VTOP
2908 @item NOTE_INSN_LOOP_VTOP
2909 This note indicates the place in a loop where the exit test begins for
2910 those loops in which the exit test has been duplicated. This position
2911 becomes another virtual start of the loop when considering loop
2914 @findex NOTE_INSN_FUNCTION_END
2915 @item NOTE_INSN_FUNCTION_END
2916 Appears near the end of the function body, just before the label that
2917 @code{return} statements jump to (on machine where a single instruction
2918 does not suffice for returning). This note may be deleted by jump
2921 @findex NOTE_INSN_SETJMP
2922 @item NOTE_INSN_SETJMP
2923 Appears following each call to @code{setjmp} or a related function.
2926 These codes are printed symbolically when they appear in debugging dumps.
2929 @cindex @code{TImode}, in @code{insn}
2930 @cindex @code{HImode}, in @code{insn}
2931 @cindex @code{QImode}, in @code{insn}
2932 The machine mode of an insn is normally @code{VOIDmode}, but some
2933 phases use the mode for various purposes.
2935 The common subexpression elimination pass sets the mode of an insn to
2936 @code{QImode} when it is the first insn in a block that has already
2939 The second Haifa scheduling pass, for targets that can multiple issue,
2940 sets the mode of an insn to @code{TImode} when it is believed that the
2941 instruction begins an issue group. That is, when the instruction
2942 cannot issue simultaneously with the previous. This may be relied on
2943 by later passes, in particular machine-dependent reorg.
2945 Here is a table of the extra fields of @code{insn}, @code{jump_insn}
2946 and @code{call_insn} insns:
2950 @item PATTERN (@var{i})
2951 An expression for the side effect performed by this insn. This must be
2952 one of the following codes: @code{set}, @code{call}, @code{use},
2953 @code{clobber}, @code{return}, @code{asm_input}, @code{asm_output},
2954 @code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec},
2955 @code{unspec_volatile}, @code{parallel}, @code{cond_exec}, or @code{sequence}. If it is a @code{parallel},
2956 each element of the @code{parallel} must be one these codes, except that
2957 @code{parallel} expressions cannot be nested and @code{addr_vec} and
2958 @code{addr_diff_vec} are not permitted inside a @code{parallel} expression.
2961 @item INSN_CODE (@var{i})
2962 An integer that says which pattern in the machine description matches
2963 this insn, or @minus{}1 if the matching has not yet been attempted.
2965 Such matching is never attempted and this field remains @minus{}1 on an insn
2966 whose pattern consists of a single @code{use}, @code{clobber},
2967 @code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.
2969 @findex asm_noperands
2970 Matching is also never attempted on insns that result from an @code{asm}
2971 statement. These contain at least one @code{asm_operands} expression.
2972 The function @code{asm_noperands} returns a non-negative value for
2975 In the debugging output, this field is printed as a number followed by
2976 a symbolic representation that locates the pattern in the @file{md}
2977 file as some small positive or negative offset from a named pattern.
2980 @item LOG_LINKS (@var{i})
2981 A list (chain of @code{insn_list} expressions) giving information about
2982 dependencies between instructions within a basic block. Neither a jump
2983 nor a label may come between the related insns.
2986 @item REG_NOTES (@var{i})
2987 A list (chain of @code{expr_list} and @code{insn_list} expressions)
2988 giving miscellaneous information about the insn. It is often
2989 information pertaining to the registers used in this insn.
2992 The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
2993 expressions. Each of these has two operands: the first is an insn,
2994 and the second is another @code{insn_list} expression (the next one in
2995 the chain). The last @code{insn_list} in the chain has a null pointer
2996 as second operand. The significant thing about the chain is which
2997 insns appear in it (as first operands of @code{insn_list}
2998 expressions). Their order is not significant.
3000 This list is originally set up by the flow analysis pass; it is a null
3001 pointer until then. Flow only adds links for those data dependencies
3002 which can be used for instruction combination. For each insn, the flow
3003 analysis pass adds a link to insns which store into registers values
3004 that are used for the first time in this insn. The instruction
3005 scheduling pass adds extra links so that every dependence will be
3006 represented. Links represent data dependencies, antidependencies and
3007 output dependencies; the machine mode of the link distinguishes these
3008 three types: antidependencies have mode @code{REG_DEP_ANTI}, output
3009 dependencies have mode @code{REG_DEP_OUTPUT}, and data dependencies have
3010 mode @code{VOIDmode}.
3012 The @code{REG_NOTES} field of an insn is a chain similar to the
3013 @code{LOG_LINKS} field but it includes @code{expr_list} expressions in
3014 addition to @code{insn_list} expressions. There are several kinds of
3015 register notes, which are distinguished by the machine mode, which in a
3016 register note is really understood as being an @code{enum reg_note}.
3017 The first operand @var{op} of the note is data whose meaning depends on
3020 @findex REG_NOTE_KIND
3021 @findex PUT_REG_NOTE_KIND
3022 The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of
3023 register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND
3024 (@var{x}, @var{newkind})} sets the register note type of @var{x} to be
3027 Register notes are of three classes: They may say something about an
3028 input to an insn, they may say something about an output of an insn, or
3029 they may create a linkage between two insns. There are also a set
3030 of values that are only used in @code{LOG_LINKS}.
3032 These register notes annotate inputs to an insn:
3037 The value in @var{op} dies in this insn; that is to say, altering the
3038 value immediately after this insn would not affect the future behavior
3041 It does not follow that the register @var{op} has no useful value after
3042 this insn since @var{op} is not necessarily modified by this insn.
3043 Rather, no subsequent instruction uses the contents of @var{op}.
3047 The register @var{op} being set by this insn will not be used in a
3048 subsequent insn. This differs from a @code{REG_DEAD} note, which
3049 indicates that the value in an input will not be used subsequently.
3050 These two notes are independent; both may be present for the same
3055 The register @var{op} is incremented (or decremented; at this level
3056 there is no distinction) by an embedded side effect inside this insn.
3057 This means it appears in a @code{post_inc}, @code{pre_inc},
3058 @code{post_dec} or @code{pre_dec} expression.
3062 The register @var{op} is known to have a nonnegative value when this
3063 insn is reached. This is used so that decrement and branch until zero
3064 instructions, such as the m68k dbra, can be matched.
3066 The @code{REG_NONNEG} note is added to insns only if the machine
3067 description has a @samp{decrement_and_branch_until_zero} pattern.
3069 @findex REG_NO_CONFLICT
3070 @item REG_NO_CONFLICT
3071 This insn does not cause a conflict between @var{op} and the item
3072 being set by this insn even though it might appear that it does.
3073 In other words, if the destination register and @var{op} could
3074 otherwise be assigned the same register, this insn does not
3075 prevent that assignment.
3077 Insns with this note are usually part of a block that begins with a
3078 @code{clobber} insn specifying a multi-word pseudo register (which will
3079 be the output of the block), a group of insns that each set one word of
3080 the value and have the @code{REG_NO_CONFLICT} note attached, and a final
3081 insn that copies the output to itself with an attached @code{REG_EQUAL}
3082 note giving the expression being computed. This block is encapsulated
3083 with @code{REG_LIBCALL} and @code{REG_RETVAL} notes on the first and
3084 last insns, respectively.
3088 This insn uses @var{op}, a @code{code_label} or a @code{note} of type
3089 @code{NOTE_INSN_DELETED_LABEL}, but is not a
3090 @code{jump_insn}, or it is a @code{jump_insn} that required the label to
3091 be held in a register. The presence of this note allows jump
3092 optimization to be aware that @var{op} is, in fact, being used, and flow
3093 optimization to build an accurate flow graph.
3096 The following notes describe attributes of outputs of an insn:
3103 This note is only valid on an insn that sets only one register and
3104 indicates that that register will be equal to @var{op} at run time; the
3105 scope of this equivalence differs between the two types of notes. The
3106 value which the insn explicitly copies into the register may look
3107 different from @var{op}, but they will be equal at run time. If the
3108 output of the single @code{set} is a @code{strict_low_part} expression,
3109 the note refers to the register that is contained in @code{SUBREG_REG}
3110 of the @code{subreg} expression.
3112 For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout
3113 the entire function, and could validly be replaced in all its
3114 occurrences by @var{op}. (``Validly'' here refers to the data flow of
3115 the program; simple replacement may make some insns invalid.) For
3116 example, when a constant is loaded into a register that is never
3117 assigned any other value, this kind of note is used.
3119 When a parameter is copied into a pseudo-register at entry to a function,
3120 a note of this kind records that the register is equivalent to the stack
3121 slot where the parameter was passed. Although in this case the register
3122 may be set by other insns, it is still valid to replace the register
3123 by the stack slot throughout the function.
3125 A @code{REG_EQUIV} note is also used on an instruction which copies a
3126 register parameter into a pseudo-register at entry to a function, if
3127 there is a stack slot where that parameter could be stored. Although
3128 other insns may set the pseudo-register, it is valid for the compiler to
3129 replace the pseudo-register by stack slot throughout the function,
3130 provided the compiler ensures that the stack slot is properly
3131 initialized by making the replacement in the initial copy instruction as
3132 well. This is used on machines for which the calling convention
3133 allocates stack space for register parameters. See
3134 @code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}.
3136 In the case of @code{REG_EQUAL}, the register that is set by this insn
3137 will be equal to @var{op} at run time at the end of this insn but not
3138 necessarily elsewhere in the function. In this case, @var{op}
3139 is typically an arithmetic expression. For example, when a sequence of
3140 insns such as a library call is used to perform an arithmetic operation,
3141 this kind of note is attached to the insn that produces or copies the
3144 These two notes are used in different ways by the compiler passes.
3145 @code{REG_EQUAL} is used by passes prior to register allocation (such as
3146 common subexpression elimination and loop optimization) to tell them how
3147 to think of that value. @code{REG_EQUIV} notes are used by register
3148 allocation to indicate that there is an available substitute expression
3149 (either a constant or a @code{mem} expression for the location of a
3150 parameter on the stack) that may be used in place of a register if
3151 insufficient registers are available.
3153 Except for stack homes for parameters, which are indicated by a
3154 @code{REG_EQUIV} note and are not useful to the early optimization
3155 passes and pseudo registers that are equivalent to a memory location
3156 throughout their entire life, which is not detected until later in
3157 the compilation, all equivalences are initially indicated by an attached
3158 @code{REG_EQUAL} note. In the early stages of register allocation, a
3159 @code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if
3160 @var{op} is a constant and the insn represents the only set of its
3161 destination register.
3163 Thus, compiler passes prior to register allocation need only check for
3164 @code{REG_EQUAL} notes and passes subsequent to register allocation
3165 need only check for @code{REG_EQUIV} notes.
3169 The single output of this insn contained zero before this insn.
3170 @var{op} is the insn that set it to zero. You can rely on this note if
3171 it is present and @var{op} has not been deleted or turned into a @code{note};
3172 its absence implies nothing.
3175 These notes describe linkages between insns. They occur in pairs: one
3176 insn has one of a pair of notes that points to a second insn, which has
3177 the inverse note pointing back to the first insn.
3182 This insn copies the value of a multi-insn sequence (for example, a
3183 library call), and @var{op} is the first insn of the sequence (for a
3184 library call, the first insn that was generated to set up the arguments
3185 for the library call).
3187 Loop optimization uses this note to treat such a sequence as a single
3188 operation for code motion purposes and flow analysis uses this note to
3189 delete such sequences whose results are dead.
3191 A @code{REG_EQUAL} note will also usually be attached to this insn to
3192 provide the expression being computed by the sequence.
3194 These notes will be deleted after reload, since they are no longer
3199 This is the inverse of @code{REG_RETVAL}: it is placed on the first
3200 insn of a multi-insn sequence, and it points to the last one.
3202 These notes are deleted after reload, since they are no longer useful or
3205 @findex REG_CC_SETTER
3209 On machines that use @code{cc0}, the insns which set and use @code{cc0}
3210 set and use @code{cc0} are adjacent. However, when branch delay slot
3211 filling is done, this may no longer be true. In this case a
3212 @code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to
3213 point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will
3214 be placed on the insn using @code{cc0} to point to the insn setting
3218 These values are only used in the @code{LOG_LINKS} field, and indicate
3219 the type of dependency that each link represents. Links which indicate
3220 a data dependence (a read after write dependence) do not use any code,
3221 they simply have mode @code{VOIDmode}, and are printed without any
3225 @findex REG_DEP_ANTI
3227 This indicates an anti dependence (a write after read dependence).
3229 @findex REG_DEP_OUTPUT
3230 @item REG_DEP_OUTPUT
3231 This indicates an output dependence (a write after write dependence).
3234 These notes describe information gathered from gcov profile data. They
3235 are stored in the @code{REG_NOTES} field of an insn as an
3239 @findex REG_EXEC_COUNT
3240 @item REG_EXEC_COUNT
3241 This is used to indicate the number of times a basic block was executed
3242 according to the profile data. The note is attached to the first insn in
3247 This is used to specify the ratio of branches to non-branches of a
3248 branch insn according to the profile data. The value is stored as a
3249 value between 0 and REG_BR_PROB_BASE; larger values indicate a higher
3250 probability that the branch will be taken.
3254 These notes are found in JUMP insns after delayed branch scheduling
3255 has taken place. They indicate both the direction and the likelihood
3256 of the JUMP@. The format is a bitmask of ATTR_FLAG_* values.
3258 @findex REG_FRAME_RELATED_EXPR
3259 @item REG_FRAME_RELATED_EXPR
3260 This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression
3261 is used in place of the actual insn pattern. This is done in cases where
3262 the pattern is either complex or misleading.
3265 For convenience, the machine mode in an @code{insn_list} or
3266 @code{expr_list} is printed using these symbolic codes in debugging dumps.
3270 The only difference between the expression codes @code{insn_list} and
3271 @code{expr_list} is that the first operand of an @code{insn_list} is
3272 assumed to be an insn and is printed in debugging dumps as the insn's
3273 unique id; the first operand of an @code{expr_list} is printed in the
3274 ordinary way as an expression.
3277 @section RTL Representation of Function-Call Insns
3278 @cindex calling functions in RTL
3279 @cindex RTL function-call insns
3280 @cindex function-call insns
3282 Insns that call subroutines have the RTL expression code @code{call_insn}.
3283 These insns must satisfy special rules, and their bodies must use a special
3284 RTL expression code, @code{call}.
3286 @cindex @code{call} usage
3287 A @code{call} expression has two operands, as follows:
3290 (call (mem:@var{fm} @var{addr}) @var{nbytes})
3294 Here @var{nbytes} is an operand that represents the number of bytes of
3295 argument data being passed to the subroutine, @var{fm} is a machine mode
3296 (which must equal as the definition of the @code{FUNCTION_MODE} macro in
3297 the machine description) and @var{addr} represents the address of the
3300 For a subroutine that returns no value, the @code{call} expression as
3301 shown above is the entire body of the insn, except that the insn might
3302 also contain @code{use} or @code{clobber} expressions.
3304 @cindex @code{BLKmode}, and function return values
3305 For a subroutine that returns a value whose mode is not @code{BLKmode},
3306 the value is returned in a hard register. If this register's number is
3307 @var{r}, then the body of the call insn looks like this:
3310 (set (reg:@var{m} @var{r})
3311 (call (mem:@var{fm} @var{addr}) @var{nbytes}))
3315 This RTL expression makes it clear (to the optimizer passes) that the
3316 appropriate register receives a useful value in this insn.
3318 When a subroutine returns a @code{BLKmode} value, it is handled by
3319 passing to the subroutine the address of a place to store the value.
3320 So the call insn itself does not ``return'' any value, and it has the
3321 same RTL form as a call that returns nothing.
3323 On some machines, the call instruction itself clobbers some register,
3324 for example to contain the return address. @code{call_insn} insns
3325 on these machines should have a body which is a @code{parallel}
3326 that contains both the @code{call} expression and @code{clobber}
3327 expressions that indicate which registers are destroyed. Similarly,
3328 if the call instruction requires some register other than the stack
3329 pointer that is not explicitly mentioned it its RTL, a @code{use}
3330 subexpression should mention that register.
3332 Functions that are called are assumed to modify all registers listed in
3333 the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register
3334 Basics}) and, with the exception of @code{const} functions and library
3335 calls, to modify all of memory.
3337 Insns containing just @code{use} expressions directly precede the
3338 @code{call_insn} insn to indicate which registers contain inputs to the
3339 function. Similarly, if registers other than those in
3340 @code{CALL_USED_REGISTERS} are clobbered by the called function, insns
3341 containing a single @code{clobber} follow immediately after the call to
3342 indicate which registers.
3345 @section Structure Sharing Assumptions
3346 @cindex sharing of RTL components
3347 @cindex RTL structure sharing assumptions
3349 The compiler assumes that certain kinds of RTL expressions are unique;
3350 there do not exist two distinct objects representing the same value.
3351 In other cases, it makes an opposite assumption: that no RTL expression
3352 object of a certain kind appears in more than one place in the
3353 containing structure.
3355 These assumptions refer to a single function; except for the RTL
3356 objects that describe global variables and external functions,
3357 and a few standard objects such as small integer constants,
3358 no RTL objects are common to two functions.
3361 @cindex @code{reg}, RTL sharing
3363 Each pseudo-register has only a single @code{reg} object to represent it,
3364 and therefore only a single machine mode.
3366 @cindex symbolic label
3367 @cindex @code{symbol_ref}, RTL sharing
3369 For any symbolic label, there is only one @code{symbol_ref} object
3372 @cindex @code{const_int}, RTL sharing
3374 All @code{const_int} expressions with equal values are shared.
3376 @cindex @code{pc}, RTL sharing
3378 There is only one @code{pc} expression.
3380 @cindex @code{cc0}, RTL sharing
3382 There is only one @code{cc0} expression.
3384 @cindex @code{const_double}, RTL sharing
3386 There is only one @code{const_double} expression with value 0 for
3387 each floating point mode. Likewise for values 1 and 2.
3389 @cindex @code{const_vector}, RTL sharing
3391 There is only one @code{const_vector} expression with value 0 for
3392 each vector mode, be it an integer or a double constant vector.
3394 @cindex @code{label_ref}, RTL sharing
3395 @cindex @code{scratch}, RTL sharing
3397 No @code{label_ref} or @code{scratch} appears in more than one place in
3398 the RTL structure; in other words, it is safe to do a tree-walk of all
3399 the insns in the function and assume that each time a @code{label_ref}
3400 or @code{scratch} is seen it is distinct from all others that are seen.
3402 @cindex @code{mem}, RTL sharing
3404 Only one @code{mem} object is normally created for each static
3405 variable or stack slot, so these objects are frequently shared in all
3406 the places they appear. However, separate but equal objects for these
3407 variables are occasionally made.
3409 @cindex @code{asm_operands}, RTL sharing
3411 When a single @code{asm} statement has multiple output operands, a
3412 distinct @code{asm_operands} expression is made for each output operand.
3413 However, these all share the vector which contains the sequence of input
3414 operands. This sharing is used later on to test whether two
3415 @code{asm_operands} expressions come from the same statement, so all
3416 optimizations must carefully preserve the sharing if they copy the
3420 No RTL object appears in more than one place in the RTL structure
3421 except as described above. Many passes of the compiler rely on this
3422 by assuming that they can modify RTL objects in place without unwanted
3423 side-effects on other insns.
3425 @findex unshare_all_rtl
3427 During initial RTL generation, shared structure is freely introduced.
3428 After all the RTL for a function has been generated, all shared
3429 structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
3430 after which the above rules are guaranteed to be followed.
3432 @findex copy_rtx_if_shared
3434 During the combiner pass, shared structure within an insn can exist
3435 temporarily. However, the shared structure is copied before the
3436 combiner is finished with the insn. This is done by calling
3437 @code{copy_rtx_if_shared}, which is a subroutine of
3438 @code{unshare_all_rtl}.
3442 @section Reading RTL
3444 To read an RTL object from a file, call @code{read_rtx}. It takes one
3445 argument, a stdio stream, and returns a single RTL object. This routine
3446 is defined in @file{read-rtl.c}. It is not available in the compiler
3447 itself, only the various programs that generate the compiler back end
3448 from the machine description.
3450 People frequently have the idea of using RTL stored as text in a file as
3451 an interface between a language front end and the bulk of GCC@. This
3452 idea is not feasible.
3454 GCC was designed to use RTL internally only. Correct RTL for a given
3455 program is very dependent on the particular target machine. And the RTL
3456 does not contain all the information about the program.
3458 The proper way to interface GCC to a new language front end is with
3459 the ``tree'' data structure, described in the files @file{tree.h} and
3460 @file{tree.def}. The documentation for this structure (@pxref{Trees})