1 @c Copyright (C) 1988, 1989, 1992, 1994 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
6 @chapter RTL Representation
7 @cindex RTL representation
8 @cindex representation of RTL
9 @cindex Register Transfer Language (RTL)
11 Most of the work of the compiler is done on an intermediate representation
12 called register transfer language. In this language, the instructions to be
13 output are described, pretty much one by one, in an algebraic form that
14 describes what the instruction does.
16 RTL is inspired by Lisp lists. It has both an internal form, made up of
17 structures that point at other structures, and a textual form that is used
18 in the machine description and in printed debugging dumps. The textual
19 form uses nested parentheses to indicate the pointers in the internal form.
22 * RTL Objects:: Expressions vs vectors vs strings vs integers.
23 * Accessors:: Macros to access expression operands or vector elts.
24 * Flags:: Other flags in an RTL expression.
25 * Machine Modes:: Describing the size and format of a datum.
26 * Constants:: Expressions with constant values.
27 * Regs and Memory:: Expressions representing register contents or memory.
28 * Arithmetic:: Expressions representing arithmetic on other expressions.
29 * Comparisons:: Expressions representing comparison of expressions.
30 * Bit Fields:: Expressions representing bitfields in memory or reg.
31 * Conversions:: Extending, truncating, floating or fixing.
32 * RTL Declarations:: Declaring volatility, constancy, etc.
33 * Side Effects:: Expressions for storing in registers, etc.
34 * Incdec:: Embedded side-effects for autoincrement addressing.
35 * Assembler:: Representing @code{asm} with operands.
36 * Insns:: Expression types for entire insns.
37 * Calls:: RTL representation of function call insns.
38 * Sharing:: Some expressions are unique; others *must* be copied.
39 * Reading RTL:: Reading textual RTL from a file.
42 @node RTL Objects, Accessors, RTL, RTL
43 @section RTL Object Types
44 @cindex RTL object types
49 @cindex RTL expression
51 RTL uses five kinds of objects: expressions, integers, wide integers,
52 strings and vectors. Expressions are the most important ones. An RTL
53 expression (``RTX'', for short) is a C structure, but it is usually
54 referred to with a pointer; a type that is given the typedef name
57 An integer is simply an @code{int}; their written form uses decimal digits.
58 A wide integer is an integral object whose type is @code{HOST_WIDE_INT}
59 (@pxref{Config}); their written form uses decimal digits.
61 A string is a sequence of characters. In core it is represented as a
62 @code{char *} in usual C fashion, and it is written in C syntax as well.
63 However, strings in RTL may never be null. If you write an empty string in
64 a machine description, it is represented in core as a null pointer rather
65 than as a pointer to a null character. In certain contexts, these null
66 pointers instead of strings are valid. Within RTL code, strings are most
67 commonly found inside @code{symbol_ref} expressions, but they appear in
68 other contexts in the RTL expressions that make up machine descriptions.
70 A vector contains an arbitrary number of pointers to expressions. The
71 number of elements in the vector is explicitly present in the vector.
72 The written form of a vector consists of square brackets
73 (@samp{[@dots{}]}) surrounding the elements, in sequence and with
74 whitespace separating them. Vectors of length zero are not created;
75 null pointers are used instead.
77 @cindex expression codes
78 @cindex codes, RTL expression
81 Expressions are classified by @dfn{expression codes} (also called RTX
82 codes). The expression code is a name defined in @file{rtl.def}, which is
83 also (in upper case) a C enumeration constant. The possible expression
84 codes and their meanings are machine-independent. The code of an RTX can
85 be extracted with the macro @code{GET_CODE (@var{x})} and altered with
86 @code{PUT_CODE (@var{x}, @var{newcode})}.
88 The expression code determines how many operands the expression contains,
89 and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell
90 by looking at an operand what kind of object it is. Instead, you must know
91 from its context---from the expression code of the containing expression.
92 For example, in an expression of code @code{subreg}, the first operand is
93 to be regarded as an expression and the second operand as an integer. In
94 an expression of code @code{plus}, there are two operands, both of which
95 are to be regarded as expressions. In a @code{symbol_ref} expression,
96 there is one operand, which is to be regarded as a string.
98 Expressions are written as parentheses containing the name of the
99 expression type, its flags and machine mode if any, and then the operands
100 of the expression (separated by spaces).
102 Expression code names in the @samp{md} file are written in lower case,
103 but when they appear in C code they are written in upper case. In this
104 manual, they are shown as follows: @code{const_int}.
108 In a few contexts a null pointer is valid where an expression is normally
109 wanted. The written form of this is @code{(nil)}.
111 @node Accessors, Flags, RTL Objects, RTL
112 @section Access to Operands
114 @cindex access to operands
115 @cindex operand access
118 For each expression type @file{rtl.def} specifies the number of
119 contained objects and their kinds, with four possibilities: @samp{e} for
120 expression (actually a pointer to an expression), @samp{i} for integer,
121 @samp{w} for wide integer, @samp{s} for string, and @samp{E} for vector
122 of expressions. The sequence of letters for an expression code is
123 called its @dfn{format}. Thus, the format of @code{subreg} is
126 @cindex RTL format characters
127 A few other format characters are used occasionally:
131 @samp{u} is equivalent to @samp{e} except that it is printed differently
132 in debugging dumps. It is used for pointers to insns.
135 @samp{n} is equivalent to @samp{i} except that it is printed differently
136 in debugging dumps. It is used for the line number or code number of a
140 @samp{S} indicates a string which is optional. In the RTL objects in
141 core, @samp{S} is equivalent to @samp{s}, but when the object is read,
142 from an @samp{md} file, the string value of this operand may be omitted.
143 An omitted string is taken to be the null string.
146 @samp{V} indicates a vector which is optional. In the RTL objects in
147 core, @samp{V} is equivalent to @samp{E}, but when the object is read
148 from an @samp{md} file, the vector value of this operand may be omitted.
149 An omitted vector is effectively the same as a vector of no elements.
152 @samp{0} means a slot whose contents do not fit any normal category.
153 @samp{0} slots are not printed at all in dumps, and are often used in
154 special ways by small parts of the compiler.
157 There are macros to get the number of operands, the format, and the
158 class of an expression code:
161 @findex GET_RTX_LENGTH
162 @item GET_RTX_LENGTH (@var{code})
163 Number of operands of an RTX of code @var{code}.
165 @findex GET_RTX_FORMAT
166 @item GET_RTX_FORMAT (@var{code})
167 The format of an RTX of code @var{code}, as a C string.
169 @findex GET_RTX_CLASS
170 @cindex classes of RTX codes
171 @item GET_RTX_CLASS (@var{code})
172 A single character representing the type of RTX operation that code
175 The following classes are defined:
179 An RTX code that represents an actual object, such as @code{reg} or
180 @code{mem}. @code{subreg} is not in this class.
183 An RTX code for a comparison. The codes in this class are
184 @code{NE}, @code{EQ}, @code{LE}, @code{LT}, @code{GE}, @code{GT},
185 @code{LEU}, @code{LTU}, @code{GEU}, @code{GTU}.@refill
188 An RTX code for a unary arithmetic operation, such as @code{neg}.
191 An RTX code for a commutative binary operation, other than @code{NE}
192 and @code{EQ} (which have class @samp{<}).
195 An RTX code for a noncommutative binary operation, such as @code{MINUS}.
198 An RTX code for a bitfield operation, either @code{ZERO_EXTRACT} or
202 An RTX code for other three input operations, such as @code{IF_THEN_ELSE}.
205 An RTX code for a machine insn (@code{INSN}, @code{JUMP_INSN}, and
206 @code{CALL_INSN}).@refill
209 An RTX code for something that matches in insns, such as @code{MATCH_DUP}.
220 Operands of expressions are accessed using the macros @code{XEXP},
221 @code{XINT}, @code{XWINT} and @code{XSTR}. Each of these macros takes
222 two arguments: an expression-pointer (RTX) and an operand number
223 (counting from zero). Thus,@refill
230 accesses operand 2 of expression @var{x}, as an expression.
237 accesses the same operand as an integer. @code{XSTR}, used in the same
238 fashion, would access it as a string.
240 Any operand can be accessed as an integer, as an expression or as a string.
241 You must choose the correct method of access for the kind of value actually
242 stored in the operand. You would do this based on the expression code of
243 the containing expression. That is also how you would know how many
246 For example, if @var{x} is a @code{subreg} expression, you know that it has
247 two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
248 and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you
249 would get the address of the expression operand but cast as an integer;
250 that might occasionally be useful, but it would be cleaner to write
251 @code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also
252 compile without error, and would return the second, integer operand cast as
253 an expression pointer, which would probably result in a crash when
254 accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
255 but this will access memory past the end of the expression with
256 unpredictable results.@refill
258 Access to operands which are vectors is more complicated. You can use the
259 macro @code{XVEC} to get the vector-pointer itself, or the macros
260 @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
265 @item XVEC (@var{exp}, @var{idx})
266 Access the vector-pointer which is operand number @var{idx} in @var{exp}.
269 @item XVECLEN (@var{exp}, @var{idx})
270 Access the length (number of elements) in the vector which is
271 in operand number @var{idx} in @var{exp}. This value is an @code{int}.
274 @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
275 Access element number @var{eltnum} in the vector which is
276 in operand number @var{idx} in @var{exp}. This value is an RTX.
278 It is up to you to make sure that @var{eltnum} is not negative
279 and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
282 All the macros defined in this section expand into lvalues and therefore
283 can be used to assign the operands, lengths and vector elements as well as
286 @node Flags, Machine Modes, Accessors, RTL
287 @section Flags in an RTL Expression
288 @cindex flags in RTL expression
290 RTL expressions contain several flags (one-bit bitfields) that are used
291 in certain types of expression. Most often they are accessed with the
295 @findex MEM_VOLATILE_P
296 @cindex @code{mem} and @samp{/v}
297 @cindex @code{volatil}, in @code{mem}
298 @cindex @samp{/v} in RTL dump
299 @item MEM_VOLATILE_P (@var{x})
300 In @code{mem} expressions, nonzero for volatile memory references.
301 Stored in the @code{volatil} field and printed as @samp{/v}.
303 @findex MEM_IN_STRUCT_P
304 @cindex @code{mem} and @samp{/s}
305 @cindex @code{in_struct}, in @code{mem}
306 @cindex @samp{/s} in RTL dump
307 @item MEM_IN_STRUCT_P (@var{x})
308 In @code{mem} expressions, nonzero for reference to an entire
309 structure, union or array, or to a component of one. Zero for
310 references to a scalar variable or through a pointer to a scalar.
311 Stored in the @code{in_struct} field and printed as @samp{/s}.
313 @findex REG_LOOP_TEST_P
314 @cindex @code{reg} and @samp{/s}
315 @cindex @code{in_struct}, in @code{reg}
316 @item REG_LOOP_TEST_P
317 In @code{reg} expressions, nonzero if this register's entire life is
318 contained in the exit test code for some loop. Stored in the
319 @code{in_struct} field and printed as @samp{/s}.
321 @findex REG_USERVAR_P
322 @cindex @code{reg} and @samp{/v}
323 @cindex @code{volatil}, in @code{reg}
324 @item REG_USERVAR_P (@var{x})
325 In a @code{reg}, nonzero if it corresponds to a variable present in
326 the user's source code. Zero for temporaries generated internally by
327 the compiler. Stored in the @code{volatil} field and printed as
330 @cindex @samp{/i} in RTL dump
331 @findex REG_FUNCTION_VALUE_P
332 @cindex @code{reg} and @samp{/i}
333 @cindex @code{integrated}, in @code{reg}
334 @item REG_FUNCTION_VALUE_P (@var{x})
335 Nonzero in a @code{reg} if it is the place in which this function's
336 value is going to be returned. (This happens only in a hard
337 register.) Stored in the @code{integrated} field and printed as
340 The same hard register may be used also for collecting the values of
341 functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
344 @findex SUBREG_PROMOTED_VAR_P
345 @cindex @code{subreg} and @samp{/s}
346 @cindex @code{in_struct}, in @code{subreg}
347 @item SUBREG_PROMOTED_VAR_P
348 Nonzero in a @code{subreg} if it was made when accessing an object that
349 was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine
350 description macro (@pxref{Storage Layout}). In this case, the mode of
351 the @code{subreg} is the declared mode of the object and the mode of
352 @code{SUBREG_REG} is the mode of the register that holds the object.
353 Promoted variables are always either sign- or zero-extended to the wider
354 mode on every assignment. Stored in the @code{in_struct} field and
355 printed as @samp{/s}.
357 @findex SUBREG_PROMOTED_UNSIGNED_P
358 @cindex @code{subreg} and @samp{/u}
359 @cindex @code{unchanging}, in @code{subreg}
360 @item SUBREG_PROMOTED_UNSIGNED_P
361 Nonzero in a @code{subreg} that has @code{SUBREG_PROMOTED_VAR_P} nonzero
362 if the object being referenced is kept zero-extended and zero if it
363 is kept sign-extended. Stored in the @code{unchanging} field and
364 printed as @samp{/u}.
366 @findex RTX_UNCHANGING_P
367 @cindex @code{reg} and @samp{/u}
368 @cindex @code{mem} and @samp{/u}
369 @cindex @code{unchanging}, in @code{reg} and @code{mem}
370 @cindex @samp{/u} in RTL dump
371 @item RTX_UNCHANGING_P (@var{x})
372 Nonzero in a @code{reg} or @code{mem} if the value is not changed.
373 (This flag is not set for memory references via pointers to constants.
374 Such pointers only guarantee that the object will not be changed
375 explicitly by the current function. The object might be changed by
376 other functions or by aliasing.) Stored in the
377 @code{unchanging} field and printed as @samp{/u}.
379 @findex RTX_INTEGRATED_P
380 @cindex @code{integrated}, in @code{insn}
381 @item RTX_INTEGRATED_P (@var{insn})
382 Nonzero in an insn if it resulted from an in-line function call.
383 Stored in the @code{integrated} field and printed as @samp{/i}. This
384 may be deleted; nothing currently depends on it.
386 @findex SYMBOL_REF_USED
387 @cindex @code{used}, in @code{symbol_ref}
388 @item SYMBOL_REF_USED (@var{x})
389 In a @code{symbol_ref}, indicates that @var{x} has been used. This is
390 normally only used to ensure that @var{x} is only declared external
391 once. Stored in the @code{used} field.
393 @findex SYMBOL_REF_FLAG
394 @cindex @code{symbol_ref} and @samp{/v}
395 @cindex @code{volatil}, in @code{symbol_ref}
396 @item SYMBOL_REF_FLAG (@var{x})
397 In a @code{symbol_ref}, this is used as a flag for machine-specific purposes.
398 Stored in the @code{volatil} field and printed as @samp{/v}.
400 @findex LABEL_OUTSIDE_LOOP_P
401 @cindex @code{label_ref} and @samp{/s}
402 @cindex @code{in_struct}, in @code{label_ref}
403 @item LABEL_OUTSIDE_LOOP_P
404 In @code{label_ref} expressions, nonzero if this is a reference to a
405 label that is outside the innermost loop containing the reference to the
406 label. Stored in the @code{in_struct} field and printed as @samp{/s}.
408 @findex INSN_DELETED_P
409 @cindex @code{volatil}, in @code{insn}
410 @item INSN_DELETED_P (@var{insn})
411 In an insn, nonzero if the insn has been deleted. Stored in the
412 @code{volatil} field and printed as @samp{/v}.
414 @findex INSN_ANNULLED_BRANCH_P
415 @cindex @code{insn} and @samp{/u}
416 @cindex @code{unchanging}, in @code{insn}
417 @item INSN_ANNULLED_BRANCH_P (@var{insn})
418 In an @code{insn} in the delay slot of a branch insn, indicates that an
419 annulling branch should be used. See the discussion under
420 @code{sequence} below. Stored in the @code{unchanging} field and printed
423 @findex INSN_FROM_TARGET_P
424 @cindex @code{insn} and @samp{/s}
425 @cindex @code{in_struct}, in @code{insn}
426 @cindex @samp{/s} in RTL dump
427 @item INSN_FROM_TARGET_P (@var{insn})
428 In an @code{insn} in a delay slot of a branch, indicates that the insn
429 is from the target of the branch. If the branch insn has
430 @code{INSN_ANNULLED_BRANCH_P} set, this insn should only be executed if
431 the branch is taken. For annulled branches with this bit clear, the
432 insn should be executed only if the branch is not taken. Stored in the
433 @code{in_struct} field and printed as @samp{/s}.
435 @findex CONSTANT_POOL_ADDRESS_P
436 @cindex @code{symbol_ref} and @samp{/u}
437 @cindex @code{unchanging}, in @code{symbol_ref}
438 @item CONSTANT_POOL_ADDRESS_P (@var{x})
439 Nonzero in a @code{symbol_ref} if it refers to part of the current
440 function's ``constants pool''. These are addresses close to the
441 beginning of the function, and GNU CC assumes they can be addressed
442 directly (perhaps with the help of base registers). Stored in the
443 @code{unchanging} field and printed as @samp{/u}.
446 @cindex @code{call_insn} and @samp{/u}
447 @cindex @code{unchanging}, in @code{call_insn}
448 @item CONST_CALL_P (@var{x})
449 In a @code{call_insn}, indicates that the insn represents a call to a const
450 function. Stored in the @code{unchanging} field and printed as @samp{/u}.
452 @findex LABEL_PRESERVE_P
453 @cindex @code{code_label} and @samp{/i}
454 @cindex @code{in_struct}, in @code{code_label}
455 @item LABEL_PRESERVE_P (@var{x})
456 In a @code{code_label}, indicates that the label can never be deleted.
457 Labels referenced by a non-local goto will have this bit set. Stored
458 in the @code{in_struct} field and printed as @samp{/s}.
460 @findex SCHED_GROUP_P
461 @cindex @code{insn} and @samp{/i}
462 @cindex @code{in_struct}, in @code{insn}
463 @item SCHED_GROUP_P (@var{insn})
464 During instruction scheduling, in an insn, indicates that the previous insn
465 must be scheduled together with this insn. This is used to ensure that
466 certain groups of instructions will not be split up by the instruction
467 scheduling pass, for example, @code{use} insns before a @code{call_insn} may
468 not be separated from the @code{call_insn}. Stored in the @code{in_struct}
469 field and printed as @samp{/s}.
472 These are the fields which the above macros refer to:
477 Normally, this flag is used only momentarily, at the end of RTL
478 generation for a function, to count the number of times an expression
479 appears in insns. Expressions that appear more than once are copied,
480 according to the rules for shared structure (@pxref{Sharing}).
482 In a @code{symbol_ref}, it indicates that an external declaration for
483 the symbol has already been written.
485 In a @code{reg}, it is used by the leaf register renumbering code to ensure
486 that each register is only renumbered once.
490 This flag is used in @code{mem}, @code{symbol_ref} and @code{reg}
491 expressions and in insns. In RTL dump files, it is printed as
494 @cindex volatile memory references
495 In a @code{mem} expression, it is 1 if the memory reference is volatile.
496 Volatile memory references may not be deleted, reordered or combined.
498 In a @code{symbol_ref} expression, it is used for machine-specific
501 In a @code{reg} expression, it is 1 if the value is a user-level variable.
502 0 indicates an internal compiler temporary.
504 In an insn, 1 means the insn has been deleted.
508 In @code{mem} expressions, it is 1 if the memory datum referred to is
509 all or part of a structure or array; 0 if it is (or might be) a scalar
510 variable. A reference through a C pointer has 0 because the pointer
511 might point to a scalar variable. This information allows the compiler
512 to determine something about possible cases of aliasing.
514 In an insn in the delay slot of a branch, 1 means that this insn is from
515 the target of the branch.
517 During instruction scheduling, in an insn, 1 means that this insn must be
518 scheduled as part of a group together with the previous insn.
520 In @code{reg} expressions, it is 1 if the register has its entire life
521 contained within the test expression of some loop.
523 In @code{subreg} expressions, 1 means that the @code{subreg} is accessing
524 an object that has had its mode promoted from a wider mode.
526 In @code{label_ref} expressions, 1 means that the referenced label is
527 outside the innermost loop containing the insn in which the @code{label_ref}
530 In @code{code_label} expressions, it is 1 if the label may never be deleted.
531 This is used for labels which are the target of non-local gotos.
533 In an RTL dump, this flag is represented as @samp{/s}.
537 In @code{reg} and @code{mem} expressions, 1 means
538 that the value of the expression never changes.
540 In @code{subreg} expressions, it is 1 if the @code{subreg} references an
541 unsigned object whose mode has been promoted to a wider mode.
543 In an insn, 1 means that this is an annulling branch.
545 In a @code{symbol_ref} expression, 1 means that this symbol addresses
546 something in the per-function constants pool.
548 In a @code{call_insn}, 1 means that this instruction is a call to a
551 In an RTL dump, this flag is represented as @samp{/u}.
555 In some kinds of expressions, including insns, this flag means the
556 rtl was produced by procedure integration.
558 In a @code{reg} expression, this flag indicates the register
559 containing the value to be returned by the current function. On
560 machines that pass parameters in registers, the same register number
561 may be used for parameters as well, but this flag is not set on such
565 @node Machine Modes, Constants, Flags, RTL
566 @section Machine Modes
567 @cindex machine modes
569 @findex enum machine_mode
570 A machine mode describes a size of data object and the representation used
571 for it. In the C code, machine modes are represented by an enumeration
572 type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL
573 expression has room for a machine mode and so do certain kinds of tree
574 expressions (declarations and types, to be precise).
576 In debugging dumps and machine descriptions, the machine mode of an RTL
577 expression is written after the expression code with a colon to separate
578 them. The letters @samp{mode} which appear at the end of each machine mode
579 name are omitted. For example, @code{(reg:SI 38)} is a @code{reg}
580 expression with machine mode @code{SImode}. If the mode is
581 @code{VOIDmode}, it is not written at all.
583 Here is a table of machine modes. The term ``byte'' below refers to an
584 object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}).
589 ``Quarter-Integer'' mode represents a single byte treated as an integer.
593 ``Half-Integer'' mode represents a two-byte integer.
597 ``Partial Single Integer'' mode represents an integer which occupies
598 four bytes but which doesn't really use all four. On some machines,
599 this is the right mode to use for pointers.
603 ``Single Integer'' mode represents a four-byte integer.
607 ``Partial Double Integer'' mode represents an integer which occupies
608 eight bytes but which doesn't really use all eight. On some machines,
609 this is the right mode to use for certain pointers.
613 ``Double Integer'' mode represents an eight-byte integer.
617 ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
621 ``Single Floating'' mode represents a single-precision (four byte) floating
626 ``Double Floating'' mode represents a double-precision (eight byte) floating
631 ``Extended Floating'' mode represents a triple-precision (twelve byte)
632 floating point number. This mode is used for IEEE extended floating
633 point. On some systems not all bits within these bytes will actually
638 ``Tetra Floating'' mode represents a quadruple-precision (sixteen byte)
639 floating point number.
643 ``Condition Code'' mode represents the value of a condition code, which
644 is a machine-specific set of bits used to represent the result of a
645 comparison operation. Other machine-specific modes may also be used for
646 the condition code. These modes are not used on machines that use
647 @code{cc0} (see @pxref{Condition Code}).
651 ``Block'' mode represents values that are aggregates to which none of
652 the other modes apply. In RTL, only memory references can have this mode,
653 and only if they appear in string-move or vector instructions. On machines
654 which have no such instructions, @code{BLKmode} will not appear in RTL.
658 Void mode means the absence of a mode or an unspecified mode.
659 For example, RTL expressions of code @code{const_int} have mode
660 @code{VOIDmode} because they can be taken to have whatever mode the context
661 requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by
662 the absence of any mode.
668 @item SCmode, DCmode, XCmode, TCmode
669 These modes stand for a complex number represented as a pair of floating
670 point values. The floating point values are in @code{SFmode},
671 @code{DFmode}, @code{XFmode}, and @code{TFmode}, respectively.
679 @item CQImode, CHImode, CSImode, CDImode, CTImode, COImode
680 These modes stand for a complex number represented as a pair of integer
681 values. The integer values are in @code{QImode}, @code{HImode},
682 @code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode},
686 The machine description defines @code{Pmode} as a C macro which expands
687 into the machine mode used for addresses. Normally this is the mode
688 whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines.
690 The only modes which a machine description @i{must} support are
691 @code{QImode}, and the modes corresponding to @code{BITS_PER_WORD},
692 @code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}.
693 The compiler will attempt to use @code{DImode} for 8-byte structures and
694 unions, but this can be prevented by overriding the definition of
695 @code{MAX_FIXED_MODE_SIZE}. Alternatively, you can have the compiler
696 use @code{TImode} for 16-byte structures and unions. Likewise, you can
697 arrange for the C type @code{short int} to avoid using @code{HImode}.
700 Very few explicit references to machine modes remain in the compiler and
701 these few references will soon be removed. Instead, the machine modes
702 are divided into mode classes. These are represented by the enumeration
703 type @code{enum mode_class} defined in @file{machmode.h}. The possible
709 Integer modes. By default these are @code{QImode}, @code{HImode},
710 @code{SImode}, @code{DImode}, and @code{TImode}.
712 @findex MODE_PARTIAL_INT
713 @item MODE_PARTIAL_INT
714 The ``partial integer'' modes, @code{PSImode} and @code{PDImode}.
718 floating point modes. By default these are @code{SFmode}, @code{DFmode},
719 @code{XFmode} and @code{TFmode}.
721 @findex MODE_COMPLEX_INT
722 @item MODE_COMPLEX_INT
723 Complex integer modes. (These are not currently implemented).
725 @findex MODE_COMPLEX_FLOAT
726 @item MODE_COMPLEX_FLOAT
727 Complex floating point modes. By default these are @code{SCmode},
728 @code{DCmode}, @code{XCmode}, and @code{TCmode}.
730 @findex MODE_FUNCTION
732 Algol or Pascal function variables including a static chain.
733 (These are not currently implemented).
737 Modes representing condition code values. These are @code{CCmode} plus
738 any modes listed in the @code{EXTRA_CC_MODES} macro. @xref{Jump Patterns},
739 also see @ref{Condition Code}.
743 This is a catchall mode class for modes which don't fit into the above
744 classes. Currently @code{VOIDmode} and @code{BLKmode} are in
748 Here are some C macros that relate to machine modes:
752 @item GET_MODE (@var{x})
753 Returns the machine mode of the RTX @var{x}.
756 @item PUT_MODE (@var{x}, @var{newmode})
757 Alters the machine mode of the RTX @var{x} to be @var{newmode}.
759 @findex NUM_MACHINE_MODES
760 @item NUM_MACHINE_MODES
761 Stands for the number of machine modes available on the target
762 machine. This is one greater than the largest numeric value of any
765 @findex GET_MODE_NAME
766 @item GET_MODE_NAME (@var{m})
767 Returns the name of mode @var{m} as a string.
769 @findex GET_MODE_CLASS
770 @item GET_MODE_CLASS (@var{m})
771 Returns the mode class of mode @var{m}.
773 @findex GET_MODE_WIDER_MODE
774 @item GET_MODE_WIDER_MODE (@var{m})
775 Returns the next wider natural mode. For example, the expression
776 @code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}.
778 @findex GET_MODE_SIZE
779 @item GET_MODE_SIZE (@var{m})
780 Returns the size in bytes of a datum of mode @var{m}.
782 @findex GET_MODE_BITSIZE
783 @item GET_MODE_BITSIZE (@var{m})
784 Returns the size in bits of a datum of mode @var{m}.
786 @findex GET_MODE_MASK
787 @item GET_MODE_MASK (@var{m})
788 Returns a bitmask containing 1 for all bits in a word that fit within
789 mode @var{m}. This macro can only be used for modes whose bitsize is
790 less than or equal to @code{HOST_BITS_PER_INT}.
792 @findex GET_MODE_ALIGNMENT
793 @item GET_MODE_ALIGNMENT (@var{m)})
794 Return the required alignment, in bits, for an object of mode @var{m}.
796 @findex GET_MODE_UNIT_SIZE
797 @item GET_MODE_UNIT_SIZE (@var{m})
798 Returns the size in bytes of the subunits of a datum of mode @var{m}.
799 This is the same as @code{GET_MODE_SIZE} except in the case of complex
800 modes. For them, the unit size is the size of the real or imaginary
803 @findex GET_MODE_NUNITS
804 @item GET_MODE_NUNITS (@var{m})
805 Returns the number of units contained in a mode, i.e.,
806 @code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}.
808 @findex GET_CLASS_NARROWEST_MODE
809 @item GET_CLASS_NARROWEST_MODE (@var{c})
810 Returns the narrowest mode in mode class @var{c}.
815 The global variables @code{byte_mode} and @code{word_mode} contain modes
816 whose classes are @code{MODE_INT} and whose bitsizes are either
817 @code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit
818 machines, these are @code{QImode} and @code{SImode}, respectively.
820 @node Constants, Regs and Memory, Machine Modes, RTL
821 @section Constant Expression Types
822 @cindex RTL constants
823 @cindex RTL constant expression types
825 The simplest RTL expressions are those that represent constant values.
829 @item (const_int @var{i})
830 This type of expression represents the integer value @var{i}. @var{i}
831 is customarily accessed with the macro @code{INTVAL} as in
832 @code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}.
838 There is only one expression object for the integer value zero; it is
839 the value of the variable @code{const0_rtx}. Likewise, the only
840 expression for integer value one is found in @code{const1_rtx}, the only
841 expression for integer value two is found in @code{const2_rtx}, and the
842 only expression for integer value negative one is found in
843 @code{constm1_rtx}. Any attempt to create an expression of code
844 @code{const_int} and value zero, one, two or negative one will return
845 @code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or
846 @code{constm1_rtx} as appropriate.@refill
848 @findex const_true_rtx
849 Similarly, there is only one object for the integer whose value is
850 @code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If
851 @code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and
852 @code{const1_rtx} will point to the same object. If
853 @code{STORE_FLAG_VALUE} is -1, @code{const_true_rtx} and
854 @code{constm1_rtx} will point to the same object.@refill
857 @item (const_double:@var{m} @var{addr} @var{i0} @var{i1} @dots{})
858 Represents either a floating-point constant of mode @var{m} or an
859 integer constant too large to fit into @code{HOST_BITS_PER_WIDE_INT}
860 bits but small enough to fit within twice that number of bits (GNU CC
861 does not provide a mechanism to represent even larger constants). In
862 the latter case, @var{m} will be @code{VOIDmode}.
864 @findex CONST_DOUBLE_MEM
865 @findex CONST_DOUBLE_CHAIN
866 @var{addr} is used to contain the @code{mem} expression that corresponds
867 to the location in memory that at which the constant can be found. If
868 it has not been allocated a memory location, but is on the chain of all
869 @code{const_double} expressions in this compilation (maintained using an
870 undisplayed field), @var{addr} contains @code{const0_rtx}. If it is not
871 on the chain, @var{addr} contains @code{cc0_rtx}. @var{addr} is
872 customarily accessed with the macro @code{CONST_DOUBLE_MEM} and the
873 chain field via @code{CONST_DOUBLE_CHAIN}.@refill
875 @findex CONST_DOUBLE_LOW
876 If @var{m} is @code{VOIDmode}, the bits of the value are stored in
877 @var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro
878 @code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}.
880 If the constant is floating point (regardless of its precision), then
881 the number of integers used to store the value depends on the size of
882 @code{REAL_VALUE_TYPE} (@pxref{Cross-compilation}). The integers
883 represent a floating point number, but not precisely in the target
884 machine's or host machine's floating point format. To convert them to
885 the precise bit pattern used by the target machine, use the macro
886 @code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}).
891 The macro @code{CONST0_RTX (@var{mode})} refers to an expression with
892 value 0 in mode @var{mode}. If mode @var{mode} is of mode class
893 @code{MODE_INT}, it returns @code{const0_rtx}. Otherwise, it returns a
894 @code{CONST_DOUBLE} expression in mode @var{mode}. Similarly, the macro
895 @code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in
896 mode @var{mode} and similarly for @code{CONST2_RTX}.
899 @item (const_string @var{str})
900 Represents a constant string with value @var{str}. Currently this is
901 used only for insn attributes (@pxref{Insn Attributes}) since constant
902 strings in C are placed in memory.
905 @item (symbol_ref:@var{mode} @var{symbol})
906 Represents the value of an assembler label for data. @var{symbol} is
907 a string that describes the name of the assembler label. If it starts
908 with a @samp{*}, the label is the rest of @var{symbol} not including
909 the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed
912 The @code{symbol_ref} contains a mode, which is usually @code{Pmode}.
913 Usually that is the only mode for which a symbol is directly valid.
916 @item (label_ref @var{label})
917 Represents the value of an assembler label for code. It contains one
918 operand, an expression, which must be a @code{code_label} that appears
919 in the instruction sequence to identify the place where the label
922 The reason for using a distinct expression type for code label
923 references is so that jump optimization can distinguish them.
925 @item (const:@var{m} @var{exp})
926 Represents a constant that is the result of an assembly-time
927 arithmetic computation. The operand, @var{exp}, is an expression that
928 contains only constants (@code{const_int}, @code{symbol_ref} and
929 @code{label_ref} expressions) combined with @code{plus} and
930 @code{minus}. However, not all combinations are valid, since the
931 assembler cannot do arbitrary arithmetic on relocatable symbols.
933 @var{m} should be @code{Pmode}.
936 @item (high:@var{m} @var{exp})
937 Represents the high-order bits of @var{exp}, usually a
938 @code{symbol_ref}. The number of bits is machine-dependent and is
939 normally the number of bits specified in an instruction that initializes
940 the high order bits of a register. It is used with @code{lo_sum} to
941 represent the typical two-instruction sequence used in RISC machines to
942 reference a global memory location.
944 @var{m} should be @code{Pmode}.
947 @node Regs and Memory, Arithmetic, Constants, RTL
948 @section Registers and Memory
949 @cindex RTL register expressions
950 @cindex RTL memory expressions
952 Here are the RTL expression types for describing access to machine
953 registers and to main memory.
957 @cindex hard registers
958 @cindex pseudo registers
959 @item (reg:@var{m} @var{n})
960 For small values of the integer @var{n} (those that are less than
961 @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
962 register number @var{n}: a @dfn{hard register}. For larger values of
963 @var{n}, it stands for a temporary value or @dfn{pseudo register}.
964 The compiler's strategy is to generate code assuming an unlimited
965 number of such pseudo registers, and later convert them into hard
966 registers or into memory references.
968 @var{m} is the machine mode of the reference. It is necessary because
969 machines can generally refer to each register in more than one mode.
970 For example, a register may contain a full word but there may be
971 instructions to refer to it as a half word or as a single byte, as
972 well as instructions to refer to it as a floating point number of
975 Even for a register that the machine can access in only one mode,
976 the mode must always be specified.
978 The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
979 description, since the number of hard registers on the machine is an
980 invariant characteristic of the machine. Note, however, that not
981 all of the machine registers must be general registers. All the
982 machine registers that can be used for storage of data are given
983 hard register numbers, even those that can be used only in certain
984 instructions or can hold only certain types of data.
986 A hard register may be accessed in various modes throughout one
987 function, but each pseudo register is given a natural mode
988 and is accessed only in that mode. When it is necessary to describe
989 an access to a pseudo register using a nonnatural mode, a @code{subreg}
992 A @code{reg} expression with a machine mode that specifies more than
993 one word of data may actually stand for several consecutive registers.
994 If in addition the register number specifies a hardware register, then
995 it actually represents several consecutive hardware registers starting
996 with the specified one.
998 Each pseudo register number used in a function's RTL code is
999 represented by a unique @code{reg} expression.
1001 @findex FIRST_VIRTUAL_REGISTER
1002 @findex LAST_VIRTUAL_REGISTER
1003 Some pseudo register numbers, those within the range of
1004 @code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only
1005 appear during the RTL generation phase and are eliminated before the
1006 optimization phases. These represent locations in the stack frame that
1007 cannot be determined until RTL generation for the function has been
1008 completed. The following virtual register numbers are defined:
1011 @findex VIRTUAL_INCOMING_ARGS_REGNUM
1012 @item VIRTUAL_INCOMING_ARGS_REGNUM
1013 This points to the first word of the incoming arguments passed on the
1014 stack. Normally these arguments are placed there by the caller, but the
1015 callee may have pushed some arguments that were previously passed in
1018 @cindex @code{FIRST_PARM_OFFSET} and virtual registers
1019 @cindex @code{ARG_POINTER_REGNUM} and virtual registers
1020 When RTL generation is complete, this virtual register is replaced
1021 by the sum of the register given by @code{ARG_POINTER_REGNUM} and the
1022 value of @code{FIRST_PARM_OFFSET}.
1024 @findex VIRTUAL_STACK_VARS_REGNUM
1025 @cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers
1026 @item VIRTUAL_STACK_VARS_REGNUM
1027 If @code{FRAME_GROWS_DOWNWARD} is defined, this points to immediately
1028 above the first variable on the stack. Otherwise, it points to the
1029 first variable on the stack.
1031 @cindex @code{STARTING_FRAME_OFFSET} and virtual registers
1032 @cindex @code{FRAME_POINTER_REGNUM} and virtual registers
1033 @code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the
1034 register given by @code{FRAME_POINTER_REGNUM} and the value
1035 @code{STARTING_FRAME_OFFSET}.
1037 @findex VIRTUAL_STACK_DYNAMIC_REGNUM
1038 @item VIRTUAL_STACK_DYNAMIC_REGNUM
1039 This points to the location of dynamically allocated memory on the stack
1040 immediately after the stack pointer has been adjusted by the amount of
1043 @cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers
1044 @cindex @code{STACK_POINTER_REGNUM} and virtual registers
1045 This virtual register is replaced by the sum of the register given by
1046 @code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}.
1048 @findex VIRTUAL_OUTGOING_ARGS_REGNUM
1049 @item VIRTUAL_OUTGOING_ARGS_REGNUM
1050 This points to the location in the stack at which outgoing arguments
1051 should be written when the stack is pre-pushed (arguments pushed using
1052 push insns should always use @code{STACK_POINTER_REGNUM}).
1054 @cindex @code{STACK_POINTER_OFFSET} and virtual registers
1055 This virtual register is replaced by the sum of the register given by
1056 @code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}.
1060 @item (subreg:@var{m} @var{reg} @var{wordnum})
1061 @code{subreg} expressions are used to refer to a register in a machine
1062 mode other than its natural one, or to refer to one register of
1063 a multi-word @code{reg} that actually refers to several registers.
1065 Each pseudo-register has a natural mode. If it is necessary to
1066 operate on it in a different mode---for example, to perform a fullword
1067 move instruction on a pseudo-register that contains a single
1068 byte---the pseudo-register must be enclosed in a @code{subreg}. In
1069 such a case, @var{wordnum} is zero.
1071 Usually @var{m} is at least as narrow as the mode of @var{reg}, in which
1072 case it is restricting consideration to only the bits of @var{reg} that
1075 Sometimes @var{m} is wider than the mode of @var{reg}. These
1076 @code{subreg} expressions are often called @dfn{paradoxical}. They are
1077 used in cases where we want to refer to an object in a wider mode but do
1078 not care what value the additional bits have. The reload pass ensures
1079 that paradoxical references are only made to hard registers.
1081 The other use of @code{subreg} is to extract the individual registers of
1082 a multi-register value. Machine modes such as @code{DImode} and
1083 @code{TImode} can indicate values longer than a word, values which
1084 usually require two or more consecutive registers. To access one of the
1085 registers, use a @code{subreg} with mode @code{SImode} and a
1086 @var{wordnum} that says which register.
1088 Storing in a non-paradoxical @code{subreg} has undefined results for
1089 bits belonging to the same word as the @code{subreg}. This laxity makes
1090 it easier to generate efficient code for such instructions. To
1091 represent an instruction that preserves all the bits outside of those in
1092 the @code{subreg}, use @code{strict_low_part} around the @code{subreg}.
1094 @cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
1095 The compilation parameter @code{WORDS_BIG_ENDIAN}, if set to 1, says
1096 that word number zero is the most significant part; otherwise, it is
1097 the least significant part.
1099 @cindex combiner pass
1101 @cindex @code{subreg}, special reload handling
1102 Between the combiner pass and the reload pass, it is possible to have a
1103 paradoxical @code{subreg} which contains a @code{mem} instead of a
1104 @code{reg} as its first operand. After the reload pass, it is also
1105 possible to have a non-paradoxical @code{subreg} which contains a
1106 @code{mem}; this usually occurs when the @code{mem} is a stack slot
1107 which replaced a pseudo register.
1109 Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
1110 using a @code{subreg}. On some machines the most significant part of a
1111 @code{DFmode} value does not have the same format as a single-precision
1114 It is also not valid to access a single word of a multi-word value in a
1115 hard register when less registers can hold the value than would be
1116 expected from its size. For example, some 32-bit machines have
1117 floating-point registers that can hold an entire @code{DFmode} value.
1118 If register 10 were such a register @code{(subreg:SI (reg:DF 10) 1)}
1119 would be invalid because there is no way to convert that reference to
1120 a single machine register. The reload pass prevents @code{subreg}
1121 expressions such as these from being formed.
1125 The first operand of a @code{subreg} expression is customarily accessed
1126 with the @code{SUBREG_REG} macro and the second operand is customarily
1127 accessed with the @code{SUBREG_WORD} macro.
1130 @cindex scratch operands
1131 @item (scratch:@var{m})
1132 This represents a scratch register that will be required for the
1133 execution of a single instruction and not used subsequently. It is
1134 converted into a @code{reg} by either the local register allocator or
1137 @code{scratch} is usually present inside a @code{clobber} operation
1138 (@pxref{Side Effects}).
1141 @cindex condition code register
1143 This refers to the machine's condition code register. It has no
1144 operands and may not have a machine mode. There are two ways to use it:
1148 To stand for a complete set of condition code flags. This is best on
1149 most machines, where each comparison sets the entire series of flags.
1151 With this technique, @code{(cc0)} may be validly used in only two
1152 contexts: as the destination of an assignment (in test and compare
1153 instructions) and in comparison operators comparing against zero
1154 (@code{const_int} with value zero; that is to say, @code{const0_rtx}).
1157 To stand for a single flag that is the result of a single condition.
1158 This is useful on machines that have only a single flag bit, and in
1159 which comparison instructions must specify the condition to test.
1161 With this technique, @code{(cc0)} may be validly used in only two
1162 contexts: as the destination of an assignment (in test and compare
1163 instructions) where the source is a comparison operator, and as the
1164 first operand of @code{if_then_else} (in a conditional branch).
1168 There is only one expression object of code @code{cc0}; it is the
1169 value of the variable @code{cc0_rtx}. Any attempt to create an
1170 expression of code @code{cc0} will return @code{cc0_rtx}.
1172 Instructions can set the condition code implicitly. On many machines,
1173 nearly all instructions set the condition code based on the value that
1174 they compute or store. It is not necessary to record these actions
1175 explicitly in the RTL because the machine description includes a
1176 prescription for recognizing the instructions that do so (by means of
1177 the macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only
1178 instructions whose sole purpose is to set the condition code, and
1179 instructions that use the condition code, need mention @code{(cc0)}.
1181 On some machines, the condition code register is given a register number
1182 and a @code{reg} is used instead of @code{(cc0)}. This is usually the
1183 preferable approach if only a small subset of instructions modify the
1184 condition code. Other machines store condition codes in general
1185 registers; in such cases a pseudo register should be used.
1187 Some machines, such as the Sparc and RS/6000, have two sets of
1188 arithmetic instructions, one that sets and one that does not set the
1189 condition code. This is best handled by normally generating the
1190 instruction that does not set the condition code, and making a pattern
1191 that both performs the arithmetic and sets the condition code register
1192 (which would not be @code{(cc0)} in this case). For examples, search
1193 for @samp{addcc} and @samp{andcc} in @file{sparc.md}.
1197 @cindex program counter
1198 This represents the machine's program counter. It has no operands and
1199 may not have a machine mode. @code{(pc)} may be validly used only in
1200 certain specific contexts in jump instructions.
1203 There is only one expression object of code @code{pc}; it is the value
1204 of the variable @code{pc_rtx}. Any attempt to create an expression of
1205 code @code{pc} will return @code{pc_rtx}.
1207 All instructions that do not jump alter the program counter implicitly
1208 by incrementing it, but there is no need to mention this in the RTL.
1211 @item (mem:@var{m} @var{addr})
1212 This RTX represents a reference to main memory at an address
1213 represented by the expression @var{addr}. @var{m} specifies how large
1214 a unit of memory is accessed.
1217 @node Arithmetic, Comparisons, Regs and Memory, RTL
1218 @section RTL Expressions for Arithmetic
1219 @cindex arithmetic, in RTL
1220 @cindex math, in RTL
1221 @cindex RTL expressions for arithmetic
1223 Unless otherwise specified, all the operands of arithmetic expressions
1224 must be valid for mode @var{m}. An operand is valid for mode @var{m}
1225 if it has mode @var{m}, or if it is a @code{const_int} or
1226 @code{const_double} and @var{m} is a mode of class @code{MODE_INT}.
1228 For commutative binary operations, constants should be placed in the
1233 @cindex RTL addition
1235 @item (plus:@var{m} @var{x} @var{y})
1236 Represents the sum of the values represented by @var{x} and @var{y}
1237 carried out in machine mode @var{m}.
1240 @item (lo_sum:@var{m} @var{x} @var{y})
1241 Like @code{plus}, except that it represents that sum of @var{x} and the
1242 low-order bits of @var{y}. The number of low order bits is
1243 machine-dependent but is normally the number of bits in a @code{Pmode}
1244 item minus the number of bits set by the @code{high} code
1245 (@pxref{Constants}).
1247 @var{m} should be @code{Pmode}.
1250 @cindex RTL subtraction
1251 @cindex RTL difference
1252 @item (minus:@var{m} @var{x} @var{y})
1253 Like @code{plus} but represents subtraction.
1256 @cindex RTL comparison
1257 @item (compare:@var{m} @var{x} @var{y})
1258 Represents the result of subtracting @var{y} from @var{x} for purposes
1259 of comparison. The result is computed without overflow, as if with
1262 Of course, machines can't really subtract with infinite precision.
1263 However, they can pretend to do so when only the sign of the
1264 result will be used, which is the case when the result is stored
1265 in the condition code. And that is the only way this kind of expression
1266 may validly be used: as a value to be stored in the condition codes.
1268 The mode @var{m} is not related to the modes of @var{x} and @var{y},
1269 but instead is the mode of the condition code value. If @code{(cc0)}
1270 is used, it is @code{VOIDmode}. Otherwise it is some mode in class
1271 @code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}.
1273 Normally, @var{x} and @var{y} must have the same mode. Otherwise,
1274 @code{compare} is valid only if the mode of @var{x} is in class
1275 @code{MODE_INT} and @var{y} is a @code{const_int} or
1276 @code{const_double} with mode @code{VOIDmode}. The mode of @var{x}
1277 determines what mode the comparison is to be done in; thus it must not
1280 If one of the operands is a constant, it should be placed in the
1281 second operand and the comparison code adjusted as appropriate.
1283 A @code{compare} specifying two @code{VOIDmode} constants is not valid
1284 since there is no way to know in what mode the comparison is to be
1285 performed; the comparison must either be folded during the compilation
1286 or the first operand must be loaded into a register while its mode is
1290 @item (neg:@var{m} @var{x})
1291 Represents the negation (subtraction from zero) of the value represented
1292 by @var{x}, carried out in mode @var{m}.
1295 @cindex multiplication
1297 @item (mult:@var{m} @var{x} @var{y})
1298 Represents the signed product of the values represented by @var{x} and
1299 @var{y} carried out in machine mode @var{m}.
1301 Some machines support a multiplication that generates a product wider
1302 than the operands. Write the pattern for this as
1305 (mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
1308 where @var{m} is wider than the modes of @var{x} and @var{y}, which need
1311 Write patterns for unsigned widening multiplication similarly using
1316 @cindex signed division
1318 @item (div:@var{m} @var{x} @var{y})
1319 Represents the quotient in signed division of @var{x} by @var{y},
1320 carried out in machine mode @var{m}. If @var{m} is a floating point
1321 mode, it represents the exact quotient; otherwise, the integerized
1324 Some machines have division instructions in which the operands and
1325 quotient widths are not all the same; you should represent
1326 such instructions using @code{truncate} and @code{sign_extend} as in,
1329 (truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
1333 @cindex unsigned division
1335 @item (udiv:@var{m} @var{x} @var{y})
1336 Like @code{div} but represents unsigned division.
1342 @item (mod:@var{m} @var{x} @var{y})
1343 @itemx (umod:@var{m} @var{x} @var{y})
1344 Like @code{div} and @code{udiv} but represent the remainder instead of
1349 @cindex signed minimum
1350 @cindex signed maximum
1351 @item (smin:@var{m} @var{x} @var{y})
1352 @itemx (smax:@var{m} @var{x} @var{y})
1353 Represents the smaller (for @code{smin}) or larger (for @code{smax}) of
1354 @var{x} and @var{y}, interpreted as signed integers in mode @var{m}.
1358 @cindex unsigned minimum and maximum
1359 @item (umin:@var{m} @var{x} @var{y})
1360 @itemx (umax:@var{m} @var{x} @var{y})
1361 Like @code{smin} and @code{smax}, but the values are interpreted as unsigned
1365 @cindex complement, bitwise
1366 @cindex bitwise complement
1367 @item (not:@var{m} @var{x})
1368 Represents the bitwise complement of the value represented by @var{x},
1369 carried out in mode @var{m}, which must be a fixed-point machine mode.
1372 @cindex logical-and, bitwise
1373 @cindex bitwise logical-and
1374 @item (and:@var{m} @var{x} @var{y})
1375 Represents the bitwise logical-and of the values represented by
1376 @var{x} and @var{y}, carried out in machine mode @var{m}, which must be
1377 a fixed-point machine mode.
1380 @cindex inclusive-or, bitwise
1381 @cindex bitwise inclusive-or
1382 @item (ior:@var{m} @var{x} @var{y})
1383 Represents the bitwise inclusive-or of the values represented by @var{x}
1384 and @var{y}, carried out in machine mode @var{m}, which must be a
1388 @cindex exclusive-or, bitwise
1389 @cindex bitwise exclusive-or
1390 @item (xor:@var{m} @var{x} @var{y})
1391 Represents the bitwise exclusive-or of the values represented by @var{x}
1392 and @var{y}, carried out in machine mode @var{m}, which must be a
1398 @cindex arithmetic shift
1399 @item (ashift:@var{m} @var{x} @var{c})
1400 Represents the result of arithmetically shifting @var{x} left by @var{c}
1401 places. @var{x} have mode @var{m}, a fixed-point machine mode. @var{c}
1402 be a fixed-point mode or be a constant with mode @code{VOIDmode}; which
1403 mode is determined by the mode called for in the machine description
1404 entry for the left-shift instruction. For example, on the Vax, the mode
1405 of @var{c} is @code{QImode} regardless of @var{m}.
1410 @item (lshiftrt:@var{m} @var{x} @var{c})
1411 @itemx (ashiftrt:@var{m} @var{x} @var{c})
1412 Like @code{ashift} but for right shift. Unlike the case for left shift,
1413 these two operations are distinct.
1419 @cindex right rotate
1420 @item (rotate:@var{m} @var{x} @var{c})
1421 @itemx (rotatert:@var{m} @var{x} @var{c})
1422 Similar but represent left and right rotate. If @var{c} is a constant,
1426 @cindex absolute value
1427 @item (abs:@var{m} @var{x})
1428 Represents the absolute value of @var{x}, computed in mode @var{m}.
1432 @item (sqrt:@var{m} @var{x})
1433 Represents the square root of @var{x}, computed in mode @var{m}.
1434 Most often @var{m} will be a floating point mode.
1437 @item (ffs:@var{m} @var{x})
1438 Represents one plus the index of the least significant 1-bit in
1439 @var{x}, represented as an integer of mode @var{m}. (The value is
1440 zero if @var{x} is zero.) The mode of @var{x} need not be @var{m};
1441 depending on the target machine, various mode combinations may be
1445 @node Comparisons, Bit Fields, Arithmetic, RTL
1446 @section Comparison Operations
1447 @cindex RTL comparison operations
1449 Comparison operators test a relation on two operands and are considered
1450 to represent a machine-dependent nonzero value described by, but not
1451 necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
1452 if the relation holds, or zero if it does not. The mode of the
1453 comparison operation is independent of the mode of the data being
1454 compared. If the comparison operation is being tested (e.g., the first
1455 operand of an @code{if_then_else}), the mode must be @code{VOIDmode}.
1456 If the comparison operation is producing data to be stored in some
1457 variable, the mode must be in class @code{MODE_INT}. All comparison
1458 operations producing data must use the same mode, which is
1461 @cindex condition codes
1462 There are two ways that comparison operations may be used. The
1463 comparison operators may be used to compare the condition codes
1464 @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such
1465 a construct actually refers to the result of the preceding instruction
1466 in which the condition codes were set. The instructing setting the
1467 condition code must be adjacent to the instruction using the condition
1468 code; only @code{note} insns may separate them.
1470 Alternatively, a comparison operation may directly compare two data
1471 objects. The mode of the comparison is determined by the operands; they
1472 must both be valid for a common machine mode. A comparison with both
1473 operands constant would be invalid as the machine mode could not be
1474 deduced from it, but such a comparison should never exist in RTL due to
1477 In the example above, if @code{(cc0)} were last set to
1478 @code{(compare @var{x} @var{y})}, the comparison operation is
1479 identical to @code{(eq @var{x} @var{y})}. Usually only one style
1480 of comparisons is supported on a particular machine, but the combine
1481 pass will try to merge the operations to produce the @code{eq} shown
1482 in case it exists in the context of the particular insn involved.
1484 Inequality comparisons come in two flavors, signed and unsigned. Thus,
1485 there are distinct expression codes @code{gt} and @code{gtu} for signed and
1486 unsigned greater-than. These can produce different results for the same
1487 pair of integer values: for example, 1 is signed greater-than -1 but not
1488 unsigned greater-than, because -1 when regarded as unsigned is actually
1489 @code{0xffffffff} which is greater than 1.
1491 The signed comparisons are also used for floating point values. Floating
1492 point comparisons are distinguished by the machine modes of the operands.
1497 @item (eq:@var{m} @var{x} @var{y})
1498 1 if the values represented by @var{x} and @var{y} are equal,
1503 @item (ne:@var{m} @var{x} @var{y})
1504 1 if the values represented by @var{x} and @var{y} are not equal,
1508 @cindex greater than
1509 @item (gt:@var{m} @var{x} @var{y})
1510 1 if the @var{x} is greater than @var{y}. If they are fixed-point,
1511 the comparison is done in a signed sense.
1514 @cindex greater than
1515 @cindex unsigned greater than
1516 @item (gtu:@var{m} @var{x} @var{y})
1517 Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
1522 @cindex unsigned less than
1523 @item (lt:@var{m} @var{x} @var{y})
1524 @itemx (ltu:@var{m} @var{x} @var{y})
1525 Like @code{gt} and @code{gtu} but test for ``less than''.
1528 @cindex greater than
1530 @cindex unsigned greater than
1531 @item (ge:@var{m} @var{x} @var{y})
1532 @itemx (geu:@var{m} @var{x} @var{y})
1533 Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
1536 @cindex less than or equal
1538 @cindex unsigned less than
1539 @item (le:@var{m} @var{x} @var{y})
1540 @itemx (leu:@var{m} @var{x} @var{y})
1541 Like @code{gt} and @code{gtu} but test for ``less than or equal''.
1543 @findex if_then_else
1544 @item (if_then_else @var{cond} @var{then} @var{else})
1545 This is not a comparison operation but is listed here because it is
1546 always used in conjunction with a comparison operation. To be
1547 precise, @var{cond} is a comparison expression. This expression
1548 represents a choice, according to @var{cond}, between the value
1549 represented by @var{then} and the one represented by @var{else}.
1551 On most machines, @code{if_then_else} expressions are valid only
1552 to express conditional jumps.
1555 @item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
1556 Similar to @code{if_then_else}, but more general. Each of @var{test1},
1557 @var{test2}, @dots{} is performed in turn. The result of this expression is
1558 the @var{value} corresponding to the first non-zero test, or @var{default} if
1559 none of the tests are non-zero expressions.
1561 This is currently not valid for instruction patterns and is supported only
1562 for insn attributes. @xref{Insn Attributes}.
1565 @node Bit Fields, Conversions, Comparisons, RTL
1569 Special expression codes exist to represent bitfield instructions.
1570 These types of expressions are lvalues in RTL; they may appear
1571 on the left side of an assignment, indicating insertion of a value
1572 into the specified bit field.
1575 @findex sign_extract
1576 @cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
1577 @item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
1578 This represents a reference to a sign-extended bit field contained or
1579 starting in @var{loc} (a memory or register reference). The bit field
1580 is @var{size} bits wide and starts at bit @var{pos}. The compilation
1581 option @code{BITS_BIG_ENDIAN} says which end of the memory unit
1582 @var{pos} counts from.
1584 If @var{loc} is in memory, its mode must be a single-byte integer mode.
1585 If @var{loc} is in a register, the mode to use is specified by the
1586 operand of the @code{insv} or @code{extv} pattern
1587 (@pxref{Standard Names}) and is usually a full-word integer mode.
1589 The mode of @var{pos} is machine-specific and is also specified
1590 in the @code{insv} or @code{extv} pattern.
1592 The mode @var{m} is the same as the mode that would be used for
1593 @var{loc} if it were a register.
1595 @findex zero_extract
1596 @item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
1597 Like @code{sign_extract} but refers to an unsigned or zero-extended
1598 bit field. The same sequence of bits are extracted, but they
1599 are filled to an entire word with zeros instead of by sign-extension.
1602 @node Conversions, RTL Declarations, Bit Fields, RTL
1603 @section Conversions
1605 @cindex machine mode conversions
1607 All conversions between machine modes must be represented by
1608 explicit conversion operations. For example, an expression
1609 which is the sum of a byte and a full word cannot be written as
1610 @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
1611 operation requires two operands of the same machine mode.
1612 Therefore, the byte-sized operand is enclosed in a conversion
1616 (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
1619 The conversion operation is not a mere placeholder, because there
1620 may be more than one way of converting from a given starting mode
1621 to the desired final mode. The conversion operation code says how
1624 For all conversion operations, @var{x} must not be @code{VOIDmode}
1625 because the mode in which to do the conversion would not be known.
1626 The conversion must either be done at compile-time or @var{x}
1627 must be placed into a register.
1631 @item (sign_extend:@var{m} @var{x})
1632 Represents the result of sign-extending the value @var{x}
1633 to machine mode @var{m}. @var{m} must be a fixed-point mode
1634 and @var{x} a fixed-point value of a mode narrower than @var{m}.
1637 @item (zero_extend:@var{m} @var{x})
1638 Represents the result of zero-extending the value @var{x}
1639 to machine mode @var{m}. @var{m} must be a fixed-point mode
1640 and @var{x} a fixed-point value of a mode narrower than @var{m}.
1642 @findex float_extend
1643 @item (float_extend:@var{m} @var{x})
1644 Represents the result of extending the value @var{x}
1645 to machine mode @var{m}. @var{m} must be a floating point mode
1646 and @var{x} a floating point value of a mode narrower than @var{m}.
1649 @item (truncate:@var{m} @var{x})
1650 Represents the result of truncating the value @var{x}
1651 to machine mode @var{m}. @var{m} must be a fixed-point mode
1652 and @var{x} a fixed-point value of a mode wider than @var{m}.
1654 @findex float_truncate
1655 @item (float_truncate:@var{m} @var{x})
1656 Represents the result of truncating the value @var{x}
1657 to machine mode @var{m}. @var{m} must be a floating point mode
1658 and @var{x} a floating point value of a mode wider than @var{m}.
1661 @item (float:@var{m} @var{x})
1662 Represents the result of converting fixed point value @var{x},
1663 regarded as signed, to floating point mode @var{m}.
1665 @findex unsigned_float
1666 @item (unsigned_float:@var{m} @var{x})
1667 Represents the result of converting fixed point value @var{x},
1668 regarded as unsigned, to floating point mode @var{m}.
1671 @item (fix:@var{m} @var{x})
1672 When @var{m} is a fixed point mode, represents the result of
1673 converting floating point value @var{x} to mode @var{m}, regarded as
1674 signed. How rounding is done is not specified, so this operation may
1675 be used validly in compiling C code only for integer-valued operands.
1677 @findex unsigned_fix
1678 @item (unsigned_fix:@var{m} @var{x})
1679 Represents the result of converting floating point value @var{x} to
1680 fixed point mode @var{m}, regarded as unsigned. How rounding is done
1684 @item (fix:@var{m} @var{x})
1685 When @var{m} is a floating point mode, represents the result of
1686 converting floating point value @var{x} (valid for mode @var{m}) to an
1687 integer, still represented in floating point mode @var{m}, by rounding
1691 @node RTL Declarations, Side Effects, Conversions, RTL
1692 @section Declarations
1693 @cindex RTL declarations
1694 @cindex declarations, RTL
1696 Declaration expression codes do not represent arithmetic operations
1697 but rather state assertions about their operands.
1700 @findex strict_low_part
1701 @cindex @code{subreg}, in @code{strict_low_part}
1702 @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
1703 This expression code is used in only one context: as the destination operand of a
1704 @code{set} expression. In addition, the operand of this expression
1705 must be a non-paradoxical @code{subreg} expression.
1707 The presence of @code{strict_low_part} says that the part of the
1708 register which is meaningful in mode @var{n}, but is not part of
1709 mode @var{m}, is not to be altered. Normally, an assignment to such
1710 a subreg is allowed to have undefined effects on the rest of the
1711 register when @var{m} is less than a word.
1714 @node Side Effects, Incdec, RTL Declarations, RTL
1715 @section Side Effect Expressions
1716 @cindex RTL side effect expressions
1718 The expression codes described so far represent values, not actions.
1719 But machine instructions never produce values; they are meaningful
1720 only for their side effects on the state of the machine. Special
1721 expression codes are used to represent side effects.
1723 The body of an instruction is always one of these side effect codes;
1724 the codes described above, which represent values, appear only as
1725 the operands of these.
1729 @item (set @var{lval} @var{x})
1730 Represents the action of storing the value of @var{x} into the place
1731 represented by @var{lval}. @var{lval} must be an expression
1732 representing a place that can be stored in: @code{reg} (or
1733 @code{subreg} or @code{strict_low_part}), @code{mem}, @code{pc} or
1736 If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
1737 machine mode; then @var{x} must be valid for that mode.@refill
1739 If @var{lval} is a @code{reg} whose machine mode is less than the full
1740 width of the register, then it means that the part of the register
1741 specified by the machine mode is given the specified value and the
1742 rest of the register receives an undefined value. Likewise, if
1743 @var{lval} is a @code{subreg} whose machine mode is narrower than
1744 the mode of the register, the rest of the register can be changed in
1747 If @var{lval} is a @code{strict_low_part} of a @code{subreg}, then the
1748 part of the register specified by the machine mode of the
1749 @code{subreg} is given the value @var{x} and the rest of the register
1750 is not changed.@refill
1752 If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
1753 be either a @code{compare} expression or a value that may have any mode.
1754 The latter case represents a ``test'' instruction. The expression
1755 @code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to
1756 @code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}.
1757 Use the former expression to save space during the compilation.
1759 @cindex jump instructions and @code{set}
1760 @cindex @code{if_then_else} usage
1761 If @var{lval} is @code{(pc)}, we have a jump instruction, and the
1762 possibilities for @var{x} are very limited. It may be a
1763 @code{label_ref} expression (unconditional jump). It may be an
1764 @code{if_then_else} (conditional jump), in which case either the
1765 second or the third operand must be @code{(pc)} (for the case which
1766 does not jump) and the other of the two must be a @code{label_ref}
1767 (for the case which does jump). @var{x} may also be a @code{mem} or
1768 @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
1769 @code{mem}; these unusual patterns are used to represent jumps through
1770 branch tables.@refill
1772 If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of
1773 @var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
1774 valid for the mode of @var{lval}.
1778 @var{lval} is customarily accessed with the @code{SET_DEST} macro and
1779 @var{x} with the @code{SET_SRC} macro.
1783 As the sole expression in a pattern, represents a return from the
1784 current function, on machines where this can be done with one
1785 instruction, such as Vaxes. On machines where a multi-instruction
1786 ``epilogue'' must be executed in order to return from the function,
1787 returning is done by jumping to a label which precedes the epilogue, and
1788 the @code{return} expression code is never used.
1790 Inside an @code{if_then_else} expression, represents the value to be
1791 placed in @code{pc} to return to the caller.
1793 Note that an insn pattern of @code{(return)} is logically equivalent to
1794 @code{(set (pc) (return))}, but the latter form is never used.
1797 @item (call @var{function} @var{nargs})
1798 Represents a function call. @var{function} is a @code{mem} expression
1799 whose address is the address of the function to be called.
1800 @var{nargs} is an expression which can be used for two purposes: on
1801 some machines it represents the number of bytes of stack argument; on
1802 others, it represents the number of argument registers.
1804 Each machine has a standard machine mode which @var{function} must
1805 have. The machine description defines macro @code{FUNCTION_MODE} to
1806 expand into the requisite mode name. The purpose of this mode is to
1807 specify what kind of addressing is allowed, on machines where the
1808 allowed kinds of addressing depend on the machine mode being
1812 @item (clobber @var{x})
1813 Represents the storing or possible storing of an unpredictable,
1814 undescribed value into @var{x}, which must be a @code{reg},
1815 @code{scratch} or @code{mem} expression.
1817 One place this is used is in string instructions that store standard
1818 values into particular hard registers. It may not be worth the
1819 trouble to describe the values that are stored, but it is essential to
1820 inform the compiler that the registers will be altered, lest it
1821 attempt to keep data in them across the string instruction.
1823 If @var{x} is @code{(mem:BLK (const_int 0))}, it means that all memory
1824 locations must be presumed clobbered.
1826 Note that the machine description classifies certain hard registers as
1827 ``call-clobbered''. All function call instructions are assumed by
1828 default to clobber these registers, so there is no need to use
1829 @code{clobber} expressions to indicate this fact. Also, each function
1830 call is assumed to have the potential to alter any memory location,
1831 unless the function is declared @code{const}.
1833 If the last group of expressions in a @code{parallel} are each a
1834 @code{clobber} expression whose arguments are @code{reg} or
1835 @code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
1836 phase can add the appropriate @code{clobber} expressions to an insn it
1837 has constructed when doing so will cause a pattern to be matched.
1839 This feature can be used, for example, on a machine that whose multiply
1840 and add instructions don't use an MQ register but which has an
1841 add-accumulate instruction that does clobber the MQ register. Similarly,
1842 a combined instruction might require a temporary register while the
1843 constituent instructions might not.
1845 When a @code{clobber} expression for a register appears inside a
1846 @code{parallel} with other side effects, the register allocator
1847 guarantees that the register is unoccupied both before and after that
1848 insn. However, the reload phase may allocate a register used for one of
1849 the inputs unless the @samp{&} constraint is specified for the selected
1850 alternative (@pxref{Modifiers}). You can clobber either a specific hard
1851 register, a pseudo register, or a @code{scratch} expression; in the
1852 latter two cases, GNU CC will allocate a hard register that is available
1853 there for use as a temporary.
1855 For instructions that require a temporary register, you should use
1856 @code{scratch} instead of a pseudo-register because this will allow the
1857 combiner phase to add the @code{clobber} when required. You do this by
1858 coding (@code{clobber} (@code{match_scratch} @dots{})). If you do
1859 clobber a pseudo register, use one which appears nowhere else---generate
1860 a new one each time. Otherwise, you may confuse CSE.
1862 There is one other known use for clobbering a pseudo register in a
1863 @code{parallel}: when one of the input operands of the insn is also
1864 clobbered by the insn. In this case, using the same pseudo register in
1865 the clobber and elsewhere in the insn produces the expected results.
1869 Represents the use of the value of @var{x}. It indicates that the
1870 value in @var{x} at this point in the program is needed, even though
1871 it may not be apparent why this is so. Therefore, the compiler will
1872 not attempt to delete previous instructions whose only effect is to
1873 store a value in @var{x}. @var{x} must be a @code{reg} expression.
1875 During the delayed branch scheduling phase, @var{x} may be an insn.
1876 This indicates that @var{x} previously was located at this place in the
1877 code and its data dependencies need to be taken into account. These
1878 @code{use} insns will be deleted before the delayed branch scheduling
1882 @item (parallel [@var{x0} @var{x1} @dots{}])
1883 Represents several side effects performed in parallel. The square
1884 brackets stand for a vector; the operand of @code{parallel} is a
1885 vector of expressions. @var{x0}, @var{x1} and so on are individual
1886 side effect expressions---expressions of code @code{set}, @code{call},
1887 @code{return}, @code{clobber} or @code{use}.@refill
1889 ``In parallel'' means that first all the values used in the individual
1890 side-effects are computed, and second all the actual side-effects are
1891 performed. For example,
1894 (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
1895 (set (mem:SI (reg:SI 1)) (reg:SI 1))])
1899 says unambiguously that the values of hard register 1 and the memory
1900 location addressed by it are interchanged. In both places where
1901 @code{(reg:SI 1)} appears as a memory address it refers to the value
1902 in register 1 @emph{before} the execution of the insn.
1904 It follows that it is @emph{incorrect} to use @code{parallel} and
1905 expect the result of one @code{set} to be available for the next one.
1906 For example, people sometimes attempt to represent a jump-if-zero
1907 instruction this way:
1910 (parallel [(set (cc0) (reg:SI 34))
1911 (set (pc) (if_then_else
1912 (eq (cc0) (const_int 0))
1918 But this is incorrect, because it says that the jump condition depends
1919 on the condition code value @emph{before} this instruction, not on the
1920 new value that is set by this instruction.
1922 @cindex peephole optimization, RTL representation
1923 Peephole optimization, which takes place together with final assembly
1924 code output, can produce insns whose patterns consist of a @code{parallel}
1925 whose elements are the operands needed to output the resulting
1926 assembler code---often @code{reg}, @code{mem} or constant expressions.
1927 This would not be well-formed RTL at any other stage in compilation,
1928 but it is ok then because no further optimization remains to be done.
1929 However, the definition of the macro @code{NOTICE_UPDATE_CC}, if
1930 any, must deal with such insns if you define any peephole optimizations.
1933 @item (sequence [@var{insns} @dots{}])
1934 Represents a sequence of insns. Each of the @var{insns} that appears
1935 in the vector is suitable for appearing in the chain of insns, so it
1936 must be an @code{insn}, @code{jump_insn}, @code{call_insn},
1937 @code{code_label}, @code{barrier} or @code{note}.
1939 A @code{sequence} RTX is never placed in an actual insn during RTL
1940 generation. It represents the sequence of insns that result from a
1941 @code{define_expand} @emph{before} those insns are passed to
1942 @code{emit_insn} to insert them in the chain of insns. When actually
1943 inserted, the individual sub-insns are separated out and the
1944 @code{sequence} is forgotten.
1946 After delay-slot scheduling is completed, an insn and all the insns that
1947 reside in its delay slots are grouped together into a @code{sequence}.
1948 The insn requiring the delay slot is the first insn in the vector;
1949 subsequent insns are to be placed in the delay slot.
1951 @code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
1952 indicate that a branch insn should be used that will conditionally annul
1953 the effect of the insns in the delay slots. In such a case,
1954 @code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
1955 the branch and should be executed only if the branch is taken; otherwise
1956 the insn should be executed only if the branch is not taken.
1960 These expression codes appear in place of a side effect, as the body of
1961 an insn, though strictly speaking they do not always describe side
1966 @item (asm_input @var{s})
1967 Represents literal assembler code as described by the string @var{s}.
1970 @findex unspec_volatile
1971 @item (unspec [@var{operands} @dots{}] @var{index})
1972 @itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
1973 Represents a machine-specific operation on @var{operands}. @var{index}
1974 selects between multiple machine-specific operations.
1975 @code{unspec_volatile} is used for volatile operations and operations
1976 that may trap; @code{unspec} is used for other operations.
1978 These codes may appear inside a @code{pattern} of an
1979 insn, inside a @code{parallel}, or inside an expression.
1982 @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
1983 Represents a table of jump addresses. The vector elements @var{lr0},
1984 etc., are @code{label_ref} expressions. The mode @var{m} specifies
1985 how much space is given to each address; normally @var{m} would be
1988 @findex addr_diff_vec
1989 @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}])
1990 Represents a table of jump addresses expressed as offsets from
1991 @var{base}. The vector elements @var{lr0}, etc., are @code{label_ref}
1992 expressions and so is @var{base}. The mode @var{m} specifies how much
1993 space is given to each address-difference.@refill
1996 @node Incdec, Assembler, Side Effects, RTL
1997 @section Embedded Side-Effects on Addresses
1998 @cindex RTL preincrement
1999 @cindex RTL postincrement
2000 @cindex RTL predecrement
2001 @cindex RTL postdecrement
2003 Four special side-effect expression codes appear as memory addresses.
2007 @item (pre_dec:@var{m} @var{x})
2008 Represents the side effect of decrementing @var{x} by a standard
2009 amount and represents also the value that @var{x} has after being
2010 decremented. @var{x} must be a @code{reg} or @code{mem}, but most
2011 machines allow only a @code{reg}. @var{m} must be the machine mode
2012 for pointers on the machine in use. The amount @var{x} is decremented
2013 by is the length in bytes of the machine mode of the containing memory
2014 reference of which this expression serves as the address. Here is an
2015 example of its use:@refill
2018 (mem:DF (pre_dec:SI (reg:SI 39)))
2022 This says to decrement pseudo register 39 by the length of a @code{DFmode}
2023 value and use the result to address a @code{DFmode} value.
2026 @item (pre_inc:@var{m} @var{x})
2027 Similar, but specifies incrementing @var{x} instead of decrementing it.
2030 @item (post_dec:@var{m} @var{x})
2031 Represents the same side effect as @code{pre_dec} but a different
2032 value. The value represented here is the value @var{x} has @i{before}
2036 @item (post_inc:@var{m} @var{x})
2037 Similar, but specifies incrementing @var{x} instead of decrementing it.
2040 These embedded side effect expressions must be used with care. Instruction
2041 patterns may not use them. Until the @samp{flow} pass of the compiler,
2042 they may occur only to represent pushes onto the stack. The @samp{flow}
2043 pass finds cases where registers are incremented or decremented in one
2044 instruction and used as an address shortly before or after; these cases are
2045 then transformed to use pre- or post-increment or -decrement.
2047 If a register used as the operand of these expressions is used in
2048 another address in an insn, the original value of the register is used.
2049 Uses of the register outside of an address are not permitted within the
2050 same insn as a use in an embedded side effect expression because such
2051 insns behave differently on different machines and hence must be treated
2052 as ambiguous and disallowed.
2054 An instruction that can be represented with an embedded side effect
2055 could also be represented using @code{parallel} containing an additional
2056 @code{set} to describe how the address register is altered. This is not
2057 done because machines that allow these operations at all typically
2058 allow them wherever a memory address is called for. Describing them as
2059 additional parallel stores would require doubling the number of entries
2060 in the machine description.
2062 @node Assembler, Insns, Incdec, RTL
2063 @section Assembler Instructions as Expressions
2064 @cindex assembler instructions in RTL
2066 @cindex @code{asm_operands}, usage
2067 The RTX code @code{asm_operands} represents a value produced by a
2068 user-specified assembler instruction. It is used to represent
2069 an @code{asm} statement with arguments. An @code{asm} statement with
2070 a single output operand, like this:
2073 asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
2077 is represented using a single @code{asm_operands} RTX which represents
2078 the value that is stored in @code{outputvar}:
2081 (set @var{rtx-for-outputvar}
2082 (asm_operands "foo %1,%2,%0" "a" 0
2083 [@var{rtx-for-addition-result} @var{rtx-for-*z}]
2084 [(asm_input:@var{m1} "g")
2085 (asm_input:@var{m2} "di")]))
2089 Here the operands of the @code{asm_operands} RTX are the assembler
2090 template string, the output-operand's constraint, the index-number of the
2091 output operand among the output operands specified, a vector of input
2092 operand RTX's, and a vector of input-operand modes and constraints. The
2093 mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
2096 When an @code{asm} statement has multiple output values, its insn has
2097 several such @code{set} RTX's inside of a @code{parallel}. Each @code{set}
2098 contains a @code{asm_operands}; all of these share the same assembler
2099 template and vectors, but each contains the constraint for the respective
2100 output operand. They are also distinguished by the output-operand index
2101 number, which is 0, 1, @dots{} for successive output operands.
2103 @node Insns, Calls, Assembler, RTL
2107 The RTL representation of the code for a function is a doubly-linked
2108 chain of objects called @dfn{insns}. Insns are expressions with
2109 special codes that are used for no other purpose. Some insns are
2110 actual instructions; others represent dispatch tables for @code{switch}
2111 statements; others represent labels to jump to or various sorts of
2112 declarative information.
2114 In addition to its own specific data, each insn must have a unique
2115 id-number that distinguishes it from all other insns in the current
2116 function (after delayed branch scheduling, copies of an insn with the
2117 same id-number may be present in multiple places in a function, but
2118 these copies will always be identical and will only appear inside a
2119 @code{sequence}), and chain pointers to the preceding and following
2120 insns. These three fields occupy the same position in every insn,
2121 independent of the expression code of the insn. They could be accessed
2122 with @code{XEXP} and @code{XINT}, but instead three special macros are
2127 @item INSN_UID (@var{i})
2128 Accesses the unique id of insn @var{i}.
2131 @item PREV_INSN (@var{i})
2132 Accesses the chain pointer to the insn preceding @var{i}.
2133 If @var{i} is the first insn, this is a null pointer.
2136 @item NEXT_INSN (@var{i})
2137 Accesses the chain pointer to the insn following @var{i}.
2138 If @var{i} is the last insn, this is a null pointer.
2142 @findex get_last_insn
2143 The first insn in the chain is obtained by calling @code{get_insns}; the
2144 last insn is the result of calling @code{get_last_insn}. Within the
2145 chain delimited by these insns, the @code{NEXT_INSN} and
2146 @code{PREV_INSN} pointers must always correspond: if @var{insn} is not
2150 NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
2154 is always true and if @var{insn} is not the last insn,
2157 PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
2163 After delay slot scheduling, some of the insns in the chain might be
2164 @code{sequence} expressions, which contain a vector of insns. The value
2165 of @code{NEXT_INSN} in all but the last of these insns is the next insn
2166 in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
2167 is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
2168 which it is contained. Similar rules apply for @code{PREV_INSN}.
2170 This means that the above invariants are not necessarily true for insns
2171 inside @code{sequence} expressions. Specifically, if @var{insn} is the
2172 first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
2173 is the insn containing the @code{sequence} expression, as is the value
2174 of @code{PREV_INSN (NEXT_INSN (@var{insn}))} is @var{insn} is the last
2175 insn in the @code{sequence} expression. You can use these expressions
2176 to find the containing @code{sequence} expression.@refill
2178 Every insn has one of the following six expression codes:
2183 The expression code @code{insn} is used for instructions that do not jump
2184 and do not do function calls. @code{sequence} expressions are always
2185 contained in insns with code @code{insn} even if one of those insns
2186 should jump or do function calls.
2188 Insns with code @code{insn} have four additional fields beyond the three
2189 mandatory ones listed above. These four are described in a table below.
2193 The expression code @code{jump_insn} is used for instructions that may
2194 jump (or, more generally, may contain @code{label_ref} expressions). If
2195 there is an instruction to return from the current function, it is
2196 recorded as a @code{jump_insn}.
2199 @code{jump_insn} insns have the same extra fields as @code{insn} insns,
2200 accessed in the same way and in addition contain a field
2201 @code{JUMP_LABEL} which is defined once jump optimization has completed.
2203 For simple conditional and unconditional jumps, this field contains the
2204 @code{code_label} to which this insn will (possibly conditionally)
2205 branch. In a more complex jump, @code{JUMP_LABEL} records one of the
2206 labels that the insn refers to; the only way to find the others
2207 is to scan the entire body of the insn.
2209 Return insns count as jumps, but since they do not refer to any labels,
2210 they have zero in the @code{JUMP_LABEL} field.
2214 The expression code @code{call_insn} is used for instructions that may do
2215 function calls. It is important to distinguish these instructions because
2216 they imply that certain registers and memory locations may be altered
2219 @findex CALL_INSN_FUNCTION_USAGE
2220 @code{call_insn} insns have the same extra fields as @code{insn} insns,
2221 accessed in the same way and in addition contain a field
2222 @code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of
2223 @code{expr_list} expressions) containing @code{use} and @code{clobber}
2224 expressions that denote hard registers used or clobbered by the called
2225 function. A register specified in a @code{clobber} in this list is
2226 modified @emph{after} the execution of the @code{call_insn}, while a
2227 register in a @code{clobber} in the body of the @code{call_insn} is
2228 clobbered before the insn completes execution. @code{clobber}
2229 expressions in this list augment registers specified in
2230 @code{CALL_USED_REGISTERS} (@pxref{Register Basics}).
2233 @findex CODE_LABEL_NUMBER
2235 A @code{code_label} insn represents a label that a jump insn can jump
2236 to. It contains two special fields of data in addition to the three
2237 standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
2238 number}, a number that identifies this label uniquely among all the
2239 labels in the compilation (not just in the current function).
2240 Ultimately, the label is represented in the assembler output as an
2241 assembler label, usually of the form @samp{L@var{n}} where @var{n} is
2244 When a @code{code_label} appears in an RTL expression, it normally
2245 appears within a @code{label_ref} which represents the address of
2246 the label, as a number.
2249 The field @code{LABEL_NUSES} is only defined once the jump optimization
2250 phase is completed and contains the number of times this label is
2251 referenced in the current function.
2255 Barriers are placed in the instruction stream when control cannot flow
2256 past them. They are placed after unconditional jump instructions to
2257 indicate that the jumps are unconditional and after calls to
2258 @code{volatile} functions, which do not return (e.g., @code{exit}).
2259 They contain no information beyond the three standard fields.
2262 @findex NOTE_LINE_NUMBER
2263 @findex NOTE_SOURCE_FILE
2265 @code{note} insns are used to represent additional debugging and
2266 declarative information. They contain two nonstandard fields, an
2267 integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
2268 string accessed with @code{NOTE_SOURCE_FILE}.
2270 If @code{NOTE_LINE_NUMBER} is positive, the note represents the
2271 position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
2272 that the line came from. These notes control generation of line
2273 number data in the assembler output.
2275 Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
2276 code with one of the following values (and @code{NOTE_SOURCE_FILE}
2277 must contain a null pointer):
2280 @findex NOTE_INSN_DELETED
2281 @item NOTE_INSN_DELETED
2282 Such a note is completely ignorable. Some passes of the compiler
2283 delete insns by altering them into notes of this kind.
2285 @findex NOTE_INSN_BLOCK_BEG
2286 @findex NOTE_INSN_BLOCK_END
2287 @item NOTE_INSN_BLOCK_BEG
2288 @itemx NOTE_INSN_BLOCK_END
2289 These types of notes indicate the position of the beginning and end
2290 of a level of scoping of variable names. They control the output
2291 of debugging information.
2293 @findex NOTE_INSN_LOOP_BEG
2294 @findex NOTE_INSN_LOOP_END
2295 @item NOTE_INSN_LOOP_BEG
2296 @itemx NOTE_INSN_LOOP_END
2297 These types of notes indicate the position of the beginning and end
2298 of a @code{while} or @code{for} loop. They enable the loop optimizer
2299 to find loops quickly.
2301 @findex NOTE_INSN_LOOP_CONT
2302 @item NOTE_INSN_LOOP_CONT
2303 Appears at the place in a loop that @code{continue} statements jump to.
2305 @findex NOTE_INSN_LOOP_VTOP
2306 @item NOTE_INSN_LOOP_VTOP
2307 This note indicates the place in a loop where the exit test begins for
2308 those loops in which the exit test has been duplicated. This position
2309 becomes another virtual start of the loop when considering loop
2312 @findex NOTE_INSN_FUNCTION_END
2313 @item NOTE_INSN_FUNCTION_END
2314 Appears near the end of the function body, just before the label that
2315 @code{return} statements jump to (on machine where a single instruction
2316 does not suffice for returning). This note may be deleted by jump
2319 @findex NOTE_INSN_SETJMP
2320 @item NOTE_INSN_SETJMP
2321 Appears following each call to @code{setjmp} or a related function.
2324 These codes are printed symbolically when they appear in debugging dumps.
2327 @cindex @code{HImode}, in @code{insn}
2328 @cindex @code{QImode}, in @code{insn}
2329 The machine mode of an insn is normally @code{VOIDmode}, but some
2330 phases use the mode for various purposes; for example, the reload pass
2331 sets it to @code{HImode} if the insn needs reloading but not register
2332 elimination and @code{QImode} if both are required. The common
2333 subexpression elimination pass sets the mode of an insn to @code{QImode}
2334 when it is the first insn in a block that has already been processed.
2336 Here is a table of the extra fields of @code{insn}, @code{jump_insn}
2337 and @code{call_insn} insns:
2341 @item PATTERN (@var{i})
2342 An expression for the side effect performed by this insn. This must be
2343 one of the following codes: @code{set}, @code{call}, @code{use},
2344 @code{clobber}, @code{return}, @code{asm_input}, @code{asm_output},
2345 @code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec},
2346 @code{unspec_volatile}, @code{parallel}, or @code{sequence}. If it is a @code{parallel},
2347 each element of the @code{parallel} must be one these codes, except that
2348 @code{parallel} expressions cannot be nested and @code{addr_vec} and
2349 @code{addr_diff_vec} are not permitted inside a @code{parallel} expression.
2352 @item INSN_CODE (@var{i})
2353 An integer that says which pattern in the machine description matches
2354 this insn, or -1 if the matching has not yet been attempted.
2356 Such matching is never attempted and this field remains -1 on an insn
2357 whose pattern consists of a single @code{use}, @code{clobber},
2358 @code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.
2360 @findex asm_noperands
2361 Matching is also never attempted on insns that result from an @code{asm}
2362 statement. These contain at least one @code{asm_operands} expression.
2363 The function @code{asm_noperands} returns a non-negative value for
2366 In the debugging output, this field is printed as a number followed by
2367 a symbolic representation that locates the pattern in the @file{md}
2368 file as some small positive or negative offset from a named pattern.
2371 @item LOG_LINKS (@var{i})
2372 A list (chain of @code{insn_list} expressions) giving information about
2373 dependencies between instructions within a basic block. Neither a jump
2374 nor a label may come between the related insns.
2377 @item REG_NOTES (@var{i})
2378 A list (chain of @code{expr_list} and @code{insn_list} expressions)
2379 giving miscellaneous information about the insn. It is often information
2380 pertaining to the registers used in this insn.
2383 The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
2384 expressions. Each of these has two operands: the first is an insn,
2385 and the second is another @code{insn_list} expression (the next one in
2386 the chain). The last @code{insn_list} in the chain has a null pointer
2387 as second operand. The significant thing about the chain is which
2388 insns appear in it (as first operands of @code{insn_list}
2389 expressions). Their order is not significant.
2391 This list is originally set up by the flow analysis pass; it is a null
2392 pointer until then. Flow only adds links for those data dependencies
2393 which can be used for instruction combination. For each insn, the flow
2394 analysis pass adds a link to insns which store into registers values
2395 that are used for the first time in this insn. The instruction
2396 scheduling pass adds extra links so that every dependence will be
2397 represented. Links represent data dependencies, antidependencies and
2398 output dependencies; the machine mode of the link distinguishes these
2399 three types: antidependencies have mode @code{REG_DEP_ANTI}, output
2400 dependencies have mode @code{REG_DEP_OUTPUT}, and data dependencies have
2401 mode @code{VOIDmode}.
2403 The @code{REG_NOTES} field of an insn is a chain similar to the
2404 @code{LOG_LINKS} field but it includes @code{expr_list} expressions in
2405 addition to @code{insn_list} expressions. There are several kinds
2406 of register notes, which are distinguished by the machine mode, which
2407 in a register note is really understood as being an @code{enum reg_note}.
2408 The first operand @var{op} of the note is data whose meaning depends on
2411 @findex REG_NOTE_KIND
2412 @findex PUT_REG_NOTE_KIND
2413 The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of
2414 register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND
2415 (@var{x}, @var{newkind})} sets the register note type of @var{x} to be
2418 Register notes are of three classes: They may say something about an
2419 input to an insn, they may say something about an output of an insn, or
2420 they may create a linkage between two insns. There are also a set
2421 of values that are only used in @code{LOG_LINKS}.
2423 These register notes annotate inputs to an insn:
2428 The value in @var{op} dies in this insn; that is to say, altering the
2429 value immediately after this insn would not affect the future behavior
2432 This does not necessarily mean that the register @var{op} has no useful
2433 value after this insn since it may also be an output of the insn. In
2434 such a case, however, a @code{REG_DEAD} note would be redundant and is
2435 usually not present until after the reload pass, but no code relies on
2440 The register @var{op} is incremented (or decremented; at this level
2441 there is no distinction) by an embedded side effect inside this insn.
2442 This means it appears in a @code{post_inc}, @code{pre_inc},
2443 @code{post_dec} or @code{pre_dec} expression.
2447 The register @var{op} is known to have a nonnegative value when this
2448 insn is reached. This is used so that decrement and branch until zero
2449 instructions, such as the m68k dbra, can be matched.
2451 The @code{REG_NONNEG} note is added to insns only if the machine
2452 description has a @samp{decrement_and_branch_until_zero} pattern.
2454 @findex REG_NO_CONFLICT
2455 @item REG_NO_CONFLICT
2456 This insn does not cause a conflict between @var{op} and the item
2457 being set by this insn even though it might appear that it does.
2458 In other words, if the destination register and @var{op} could
2459 otherwise be assigned the same register, this insn does not
2460 prevent that assignment.
2462 Insns with this note are usually part of a block that begins with a
2463 @code{clobber} insn specifying a multi-word pseudo register (which will
2464 be the output of the block), a group of insns that each set one word of
2465 the value and have the @code{REG_NO_CONFLICT} note attached, and a final
2466 insn that copies the output to itself with an attached @code{REG_EQUAL}
2467 note giving the expression being computed. This block is encapsulated
2468 with @code{REG_LIBCALL} and @code{REG_RETVAL} notes on the first and
2469 last insns, respectively.
2473 This insn uses @var{op}, a @code{code_label}, but is not a
2474 @code{jump_insn}. The presence of this note allows jump optimization to
2475 be aware that @var{op} is, in fact, being used.
2478 The following notes describe attributes of outputs of an insn:
2485 This note is only valid on an insn that sets only one register and
2486 indicates that that register will be equal to @var{op} at run time; the
2487 scope of this equivalence differs between the two types of notes. The
2488 value which the insn explicitly copies into the register may look
2489 different from @var{op}, but they will be equal at run time. If the
2490 output of the single @code{set} is a @code{strict_low_part} expression,
2491 the note refers to the register that is contained in @code{SUBREG_REG}
2492 of the @code{subreg} expression.
2494 For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout
2495 the entire function, and could validly be replaced in all its
2496 occurrences by @var{op}. (``Validly'' here refers to the data flow of
2497 the program; simple replacement may make some insns invalid.) For
2498 example, when a constant is loaded into a register that is never
2499 assigned any other value, this kind of note is used.
2501 When a parameter is copied into a pseudo-register at entry to a function,
2502 a note of this kind records that the register is equivalent to the stack
2503 slot where the parameter was passed. Although in this case the register
2504 may be set by other insns, it is still valid to replace the register
2505 by the stack slot throughout the function.
2507 In the case of @code{REG_EQUAL}, the register that is set by this insn
2508 will be equal to @var{op} at run time at the end of this insn but not
2509 necessarily elsewhere in the function. In this case, @var{op}
2510 is typically an arithmetic expression. For example, when a sequence of
2511 insns such as a library call is used to perform an arithmetic operation,
2512 this kind of note is attached to the insn that produces or copies the
2515 These two notes are used in different ways by the compiler passes.
2516 @code{REG_EQUAL} is used by passes prior to register allocation (such as
2517 common subexpression elimination and loop optimization) to tell them how
2518 to think of that value. @code{REG_EQUIV} notes are used by register
2519 allocation to indicate that there is an available substitute expression
2520 (either a constant or a @code{mem} expression for the location of a
2521 parameter on the stack) that may be used in place of a register if
2522 insufficient registers are available.
2524 Except for stack homes for parameters, which are indicated by a
2525 @code{REG_EQUIV} note and are not useful to the early optimization
2526 passes and pseudo registers that are equivalent to a memory location
2527 throughout there entire life, which is not detected until later in
2528 the compilation, all equivalences are initially indicated by an attached
2529 @code{REG_EQUAL} note. In the early stages of register allocation, a
2530 @code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if
2531 @var{op} is a constant and the insn represents the only set of its
2532 destination register.
2534 Thus, compiler passes prior to register allocation need only check for
2535 @code{REG_EQUAL} notes and passes subsequent to register allocation
2536 need only check for @code{REG_EQUIV} notes.
2540 The register @var{op} being set by this insn will not be used in a
2541 subsequent insn. This differs from a @code{REG_DEAD} note, which
2542 indicates that the value in an input will not be used subsequently.
2543 These two notes are independent; both may be present for the same
2548 The single output of this insn contained zero before this insn.
2549 @var{op} is the insn that set it to zero. You can rely on this note if
2550 it is present and @var{op} has not been deleted or turned into a @code{note};
2551 its absence implies nothing.
2554 These notes describe linkages between insns. They occur in pairs: one
2555 insn has one of a pair of notes that points to a second insn, which has
2556 the inverse note pointing back to the first insn.
2561 This insn copies the value of a multi-insn sequence (for example, a
2562 library call), and @var{op} is the first insn of the sequence (for a
2563 library call, the first insn that was generated to set up the arguments
2564 for the library call).
2566 Loop optimization uses this note to treat such a sequence as a single
2567 operation for code motion purposes and flow analysis uses this note to
2568 delete such sequences whose results are dead.
2570 A @code{REG_EQUAL} note will also usually be attached to this insn to
2571 provide the expression being computed by the sequence.
2575 This is the inverse of @code{REG_RETVAL}: it is placed on the first
2576 insn of a multi-insn sequence, and it points to the last one.
2578 @findex REG_CC_SETTER
2582 On machines that use @code{cc0}, the insns which set and use @code{cc0}
2583 set and use @code{cc0} are adjacent. However, when branch delay slot
2584 filling is done, this may no longer be true. In this case a
2585 @code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to
2586 point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will
2587 be placed on the insn using @code{cc0} to point to the insn setting
2591 These values are only used in the @code{LOG_LINKS} field, and indicate
2592 the type of dependency that each link represents. Links which indicate
2593 a data dependence (a read after write dependence) do not use any code,
2594 they simply have mode @code{VOIDmode}, and are printed without any
2598 @findex REG_DEP_ANTI
2600 This indicates an anti dependence (a write after read dependence).
2602 @findex REG_DEP_OUTPUT
2603 @item REG_DEP_OUTPUT
2604 This indicates an output dependence (a write after write dependence).
2607 For convenience, the machine mode in an @code{insn_list} or
2608 @code{expr_list} is printed using these symbolic codes in debugging dumps.
2612 The only difference between the expression codes @code{insn_list} and
2613 @code{expr_list} is that the first operand of an @code{insn_list} is
2614 assumed to be an insn and is printed in debugging dumps as the insn's
2615 unique id; the first operand of an @code{expr_list} is printed in the
2616 ordinary way as an expression.
2618 @node Calls, Sharing, Insns, RTL
2619 @section RTL Representation of Function-Call Insns
2620 @cindex calling functions in RTL
2621 @cindex RTL function-call insns
2622 @cindex function-call insns
2624 Insns that call subroutines have the RTL expression code @code{call_insn}.
2625 These insns must satisfy special rules, and their bodies must use a special
2626 RTL expression code, @code{call}.
2628 @cindex @code{call} usage
2629 A @code{call} expression has two operands, as follows:
2632 (call (mem:@var{fm} @var{addr}) @var{nbytes})
2636 Here @var{nbytes} is an operand that represents the number of bytes of
2637 argument data being passed to the subroutine, @var{fm} is a machine mode
2638 (which must equal as the definition of the @code{FUNCTION_MODE} macro in
2639 the machine description) and @var{addr} represents the address of the
2642 For a subroutine that returns no value, the @code{call} expression as
2643 shown above is the entire body of the insn, except that the insn might
2644 also contain @code{use} or @code{clobber} expressions.
2646 @cindex @code{BLKmode}, and function return values
2647 For a subroutine that returns a value whose mode is not @code{BLKmode},
2648 the value is returned in a hard register. If this register's number is
2649 @var{r}, then the body of the call insn looks like this:
2652 (set (reg:@var{m} @var{r})
2653 (call (mem:@var{fm} @var{addr}) @var{nbytes}))
2657 This RTL expression makes it clear (to the optimizer passes) that the
2658 appropriate register receives a useful value in this insn.
2660 When a subroutine returns a @code{BLKmode} value, it is handled by
2661 passing to the subroutine the address of a place to store the value.
2662 So the call insn itself does not ``return'' any value, and it has the
2663 same RTL form as a call that returns nothing.
2665 On some machines, the call instruction itself clobbers some register,
2666 for example to contain the return address. @code{call_insn} insns
2667 on these machines should have a body which is a @code{parallel}
2668 that contains both the @code{call} expression and @code{clobber}
2669 expressions that indicate which registers are destroyed. Similarly,
2670 if the call instruction requires some register other than the stack
2671 pointer that is not explicitly mentioned it its RTL, a @code{use}
2672 subexpression should mention that register.
2674 Functions that are called are assumed to modify all registers listed in
2675 the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register
2676 Basics}) and, with the exception of @code{const} functions and library
2677 calls, to modify all of memory.
2679 Insns containing just @code{use} expressions directly precede the
2680 @code{call_insn} insn to indicate which registers contain inputs to the
2681 function. Similarly, if registers other than those in
2682 @code{CALL_USED_REGISTERS} are clobbered by the called function, insns
2683 containing a single @code{clobber} follow immediately after the call to
2684 indicate which registers.
2687 @section Structure Sharing Assumptions
2688 @cindex sharing of RTL components
2689 @cindex RTL structure sharing assumptions
2691 The compiler assumes that certain kinds of RTL expressions are unique;
2692 there do not exist two distinct objects representing the same value.
2693 In other cases, it makes an opposite assumption: that no RTL expression
2694 object of a certain kind appears in more than one place in the
2695 containing structure.
2697 These assumptions refer to a single function; except for the RTL
2698 objects that describe global variables and external functions,
2699 and a few standard objects such as small integer constants,
2700 no RTL objects are common to two functions.
2703 @cindex @code{reg}, RTL sharing
2705 Each pseudo-register has only a single @code{reg} object to represent it,
2706 and therefore only a single machine mode.
2708 @cindex symbolic label
2709 @cindex @code{symbol_ref}, RTL sharing
2711 For any symbolic label, there is only one @code{symbol_ref} object
2714 @cindex @code{const_int}, RTL sharing
2716 There is only one @code{const_int} expression with value 0, only
2717 one with value 1, and only one with value @minus{}1.
2718 Some other integer values are also stored uniquely.
2720 @cindex @code{pc}, RTL sharing
2722 There is only one @code{pc} expression.
2724 @cindex @code{cc0}, RTL sharing
2726 There is only one @code{cc0} expression.
2728 @cindex @code{const_double}, RTL sharing
2730 There is only one @code{const_double} expression with value 0 for
2731 each floating point mode. Likewise for values 1 and 2.
2733 @cindex @code{label_ref}, RTL sharing
2734 @cindex @code{scratch}, RTL sharing
2736 No @code{label_ref} or @code{scratch} appears in more than one place in
2737 the RTL structure; in other words, it is safe to do a tree-walk of all
2738 the insns in the function and assume that each time a @code{label_ref}
2739 or @code{scratch} is seen it is distinct from all others that are seen.
2741 @cindex @code{mem}, RTL sharing
2743 Only one @code{mem} object is normally created for each static
2744 variable or stack slot, so these objects are frequently shared in all
2745 the places they appear. However, separate but equal objects for these
2746 variables are occasionally made.
2748 @cindex @code{asm_operands}, RTL sharing
2750 When a single @code{asm} statement has multiple output operands, a
2751 distinct @code{asm_operands} expression is made for each output operand.
2752 However, these all share the vector which contains the sequence of input
2753 operands. This sharing is used later on to test whether two
2754 @code{asm_operands} expressions come from the same statement, so all
2755 optimizations must carefully preserve the sharing if they copy the
2759 No RTL object appears in more than one place in the RTL structure
2760 except as described above. Many passes of the compiler rely on this
2761 by assuming that they can modify RTL objects in place without unwanted
2762 side-effects on other insns.
2764 @findex unshare_all_rtl
2766 During initial RTL generation, shared structure is freely introduced.
2767 After all the RTL for a function has been generated, all shared
2768 structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
2769 after which the above rules are guaranteed to be followed.
2771 @findex copy_rtx_if_shared
2773 During the combiner pass, shared structure within an insn can exist
2774 temporarily. However, the shared structure is copied before the
2775 combiner is finished with the insn. This is done by calling
2776 @code{copy_rtx_if_shared}, which is a subroutine of
2777 @code{unshare_all_rtl}.
2781 @section Reading RTL
2783 To read an RTL object from a file, call @code{read_rtx}. It takes one
2784 argument, a stdio stream, and returns a single RTL object.
2786 Reading RTL from a file is very slow. This is not currently a
2787 problem since reading RTL occurs only as part of building the
2790 People frequently have the idea of using RTL stored as text in a file as
2791 an interface between a language front end and the bulk of GNU CC. This
2792 idea is not feasible.
2794 GNU CC was designed to use RTL internally only. Correct RTL for a given
2795 program is very dependent on the particular target machine. And the RTL
2796 does not contain all the information about the program.
2798 The proper way to interface GNU CC to a new language front end is with
2799 the ``tree'' data structure. There is no manual for this data
2800 structure, but it is described in the files @file{tree.h} and