Merge branch 'master' of ssh://
[dragonfly.git] / contrib / gcc-3.4 / gcc / doc / rtl.texi
1@c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004
2@c Free Software Foundation, Inc.
3@c This is part of the GCC manual.
4@c For copying conditions, see the file gcc.texi.
6@node RTL
7@chapter RTL Representation
8@cindex RTL representation
9@cindex representation of RTL
10@cindex Register Transfer Language (RTL)
12Most of the work of the compiler is done on an intermediate representation
13called register transfer language. In this language, the instructions to be
14output are described, pretty much one by one, in an algebraic form that
15describes what the instruction does.
17RTL is inspired by Lisp lists. It has both an internal form, made up of
18structures that point at other structures, and a textual form that is used
19in the machine description and in printed debugging dumps. The textual
20form uses nested parentheses to indicate the pointers in the internal form.
23* RTL Objects:: Expressions vs vectors vs strings vs integers.
24* RTL Classes:: Categories of RTL expression objects, and their structure.
25* Accessors:: Macros to access expression operands or vector elts.
26* Special Accessors:: Macros to access specific annotations on RTL.
27* Flags:: Other flags in an RTL expression.
28* Machine Modes:: Describing the size and format of a datum.
29* Constants:: Expressions with constant values.
30* Regs and Memory:: Expressions representing register contents or memory.
31* Arithmetic:: Expressions representing arithmetic on other expressions.
32* Comparisons:: Expressions representing comparison of expressions.
33* Bit-Fields:: Expressions representing bit-fields in memory or reg.
34* Vector Operations:: Expressions involving vector datatypes.
35* Conversions:: Extending, truncating, floating or fixing.
36* RTL Declarations:: Declaring volatility, constancy, etc.
37* Side Effects:: Expressions for storing in registers, etc.
38* Incdec:: Embedded side-effects for autoincrement addressing.
39* Assembler:: Representing @code{asm} with operands.
40* Insns:: Expression types for entire insns.
41* Calls:: RTL representation of function call insns.
42* Sharing:: Some expressions are unique; others *must* be copied.
43* Reading RTL:: Reading textual RTL from a file.
44@end menu
46@node RTL Objects
47@section RTL Object Types
48@cindex RTL object types
50@cindex RTL integers
51@cindex RTL strings
52@cindex RTL vectors
53@cindex RTL expression
54@cindex RTX (See RTL)
55RTL uses five kinds of objects: expressions, integers, wide integers,
56strings and vectors. Expressions are the most important ones. An RTL
57expression (``RTX'', for short) is a C structure, but it is usually
58referred to with a pointer; a type that is given the typedef name
61An integer is simply an @code{int}; their written form uses decimal
62digits. A wide integer is an integral object whose type is
63@code{HOST_WIDE_INT}; their written form uses decimal digits.
65A string is a sequence of characters. In core it is represented as a
66@code{char *} in usual C fashion, and it is written in C syntax as well.
67However, strings in RTL may never be null. If you write an empty string in
68a machine description, it is represented in core as a null pointer rather
69than as a pointer to a null character. In certain contexts, these null
70pointers instead of strings are valid. Within RTL code, strings are most
71commonly found inside @code{symbol_ref} expressions, but they appear in
72other contexts in the RTL expressions that make up machine descriptions.
74In a machine description, strings are normally written with double
75quotes, as you would in C. However, strings in machine descriptions may
76extend over many lines, which is invalid C, and adjacent string
77constants are not concatenated as they are in C. Any string constant
78may be surrounded with a single set of parentheses. Sometimes this
79makes the machine description easier to read.
81There is also a special syntax for strings, which can be useful when C
82code is embedded in a machine description. Wherever a string can
83appear, it is also valid to write a C-style brace block. The entire
84brace block, including the outermost pair of braces, is considered to be
85the string constant. Double quote characters inside the braces are not
86special. Therefore, if you write string constants in the C code, you
87need not escape each quote character with a backslash.
89A vector contains an arbitrary number of pointers to expressions. The
90number of elements in the vector is explicitly present in the vector.
91The written form of a vector consists of square brackets
92(@samp{[@dots{}]}) surrounding the elements, in sequence and with
93whitespace separating them. Vectors of length zero are not created;
94null pointers are used instead.
96@cindex expression codes
97@cindex codes, RTL expression
98@findex GET_CODE
99@findex PUT_CODE
100Expressions are classified by @dfn{expression codes} (also called RTX
101codes). The expression code is a name defined in @file{rtl.def}, which is
102also (in uppercase) a C enumeration constant. The possible expression
103codes and their meanings are machine-independent. The code of an RTX can
104be extracted with the macro @code{GET_CODE (@var{x})} and altered with
105@code{PUT_CODE (@var{x}, @var{newcode})}.
107The expression code determines how many operands the expression contains,
108and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell
109by looking at an operand what kind of object it is. Instead, you must know
110from its context---from the expression code of the containing expression.
111For example, in an expression of code @code{subreg}, the first operand is
112to be regarded as an expression and the second operand as an integer. In
113an expression of code @code{plus}, there are two operands, both of which
114are to be regarded as expressions. In a @code{symbol_ref} expression,
115there is one operand, which is to be regarded as a string.
117Expressions are written as parentheses containing the name of the
118expression type, its flags and machine mode if any, and then the operands
119of the expression (separated by spaces).
121Expression code names in the @samp{md} file are written in lowercase,
122but when they appear in C code they are written in uppercase. In this
123manual, they are shown as follows: @code{const_int}.
125@cindex (nil)
126@cindex nil
127In a few contexts a null pointer is valid where an expression is normally
128wanted. The written form of this is @code{(nil)}.
130@node RTL Classes
131@section RTL Classes and Formats
132@cindex RTL classes
133@cindex classes of RTX codes
134@cindex RTX codes, classes of
135@findex GET_RTX_CLASS
137The various expression codes are divided into several @dfn{classes},
138which are represented by single characters. You can determine the class
139of an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}.
140Currently, @file{rtx.def} defines these classes:
142@table @code
143@item o
144An RTX code that represents an actual object, such as a register
145(@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}).
146Constants and basic transforms on objects (@code{ADDRESSOF},
147@code{HIGH}, @code{LO_SUM}) are also included. Note that @code{SUBREG}
148and @code{STRICT_LOW_PART} are not in this class, but in class @code{x}.
150@item <
151An RTX code for a comparison, such as @code{NE} or @code{LT}.
153@item 1
154An RTX code for a unary arithmetic operation, such as @code{NEG},
155@code{NOT}, or @code{ABS}. This category also includes value extension
156(sign or zero) and conversions between integer and floating point.
158@item c
159An RTX code for a commutative binary operation, such as @code{PLUS} or
160@code{AND}. @code{NE} and @code{EQ} are comparisons, so they have class
163@item 2
164An RTX code for a non-commutative binary operation, such as @code{MINUS},
165@code{DIV}, or @code{ASHIFTRT}.
167@item b
168An RTX code for a bit-field operation. Currently only
169@code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}. These have three inputs
170and are lvalues (so they can be used for insertion as well).
173@item 3
174An RTX code for other three input operations. Currently only
177@item i
178An RTX code for an entire instruction: @code{INSN}, @code{JUMP_INSN}, and
179@code{CALL_INSN}. @xref{Insns}.
181@item m
182An RTX code for something that matches in insns, such as
183@code{MATCH_DUP}. These only occur in machine descriptions.
185@item a
186An RTX code for an auto-increment addressing mode, such as
189@item x
190All other RTX codes. This category includes the remaining codes used
191only in machine descriptions (@code{DEFINE_*}, etc.). It also includes
192all the codes describing side effects (@code{SET}, @code{USE},
193@code{CLOBBER}, etc.) and the non-insns that may appear on an insn
194chain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}.
195@end table
197@cindex RTL format
198For each expression code, @file{rtl.def} specifies the number of
199contained objects and their kinds using a sequence of characters
200called the @dfn{format} of the expression code. For example,
201the format of @code{subreg} is @samp{ei}.
203@cindex RTL format characters
204These are the most commonly used format characters:
206@table @code
207@item e
208An expression (actually a pointer to an expression).
210@item i
211An integer.
213@item w
214A wide integer.
216@item s
217A string.
219@item E
220A vector of expressions.
221@end table
223A few other format characters are used occasionally:
225@table @code
226@item u
227@samp{u} is equivalent to @samp{e} except that it is printed differently
228in debugging dumps. It is used for pointers to insns.
230@item n
231@samp{n} is equivalent to @samp{i} except that it is printed differently
232in debugging dumps. It is used for the line number or code number of a
233@code{note} insn.
235@item S
236@samp{S} indicates a string which is optional. In the RTL objects in
237core, @samp{S} is equivalent to @samp{s}, but when the object is read,
238from an @samp{md} file, the string value of this operand may be omitted.
239An omitted string is taken to be the null string.
241@item V
242@samp{V} indicates a vector which is optional. In the RTL objects in
243core, @samp{V} is equivalent to @samp{E}, but when the object is read
244from an @samp{md} file, the vector value of this operand may be omitted.
245An omitted vector is effectively the same as a vector of no elements.
247@item B
248@samp{B} indicates a pointer to basic block structure.
250@item 0
251@samp{0} means a slot whose contents do not fit any normal category.
252@samp{0} slots are not printed at all in dumps, and are often used in
253special ways by small parts of the compiler.
254@end table
256There are macros to get the number of operands and the format
257of an expression code:
259@table @code
260@findex GET_RTX_LENGTH
261@item GET_RTX_LENGTH (@var{code})
262Number of operands of an RTX of code @var{code}.
264@findex GET_RTX_FORMAT
265@item GET_RTX_FORMAT (@var{code})
266The format of an RTX of code @var{code}, as a C string.
267@end table
269Some classes of RTX codes always have the same format. For example, it
270is safe to assume that all comparison operations have format @code{ee}.
272@table @code
273@item 1
274All codes of this class have format @code{e}.
276@item <
277@itemx c
278@itemx 2
279All codes of these classes have format @code{ee}.
281@item b
282@itemx 3
283All codes of these classes have format @code{eee}.
285@item i
286All codes of this class have formats that begin with @code{iuueiee}.
287@xref{Insns}. Note that not all RTL objects linked onto an insn chain
288are of class @code{i}.
290@item o
291@itemx m
292@itemx x
293You can make no assumptions about the format of these codes.
294@end table
296@node Accessors
297@section Access to Operands
298@cindex accessors
299@cindex access to operands
300@cindex operand access
302@findex XEXP
303@findex XINT
304@findex XWINT
305@findex XSTR
306Operands of expressions are accessed using the macros @code{XEXP},
307@code{XINT}, @code{XWINT} and @code{XSTR}. Each of these macros takes
308two arguments: an expression-pointer (RTX) and an operand number
309(counting from zero). Thus,
312XEXP (@var{x}, 2)
313@end smallexample
316accesses operand 2 of expression @var{x}, as an expression.
319XINT (@var{x}, 2)
320@end smallexample
323accesses the same operand as an integer. @code{XSTR}, used in the same
324fashion, would access it as a string.
326Any operand can be accessed as an integer, as an expression or as a string.
327You must choose the correct method of access for the kind of value actually
328stored in the operand. You would do this based on the expression code of
329the containing expression. That is also how you would know how many
330operands there are.
332For example, if @var{x} is a @code{subreg} expression, you know that it has
333two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
334and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you
335would get the address of the expression operand but cast as an integer;
336that might occasionally be useful, but it would be cleaner to write
337@code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also
338compile without error, and would return the second, integer operand cast as
339an expression pointer, which would probably result in a crash when
340accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
341but this will access memory past the end of the expression with
342unpredictable results.
344Access to operands which are vectors is more complicated. You can use the
345macro @code{XVEC} to get the vector-pointer itself, or the macros
346@code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
349@table @code
350@findex XVEC
351@item XVEC (@var{exp}, @var{idx})
352Access the vector-pointer which is operand number @var{idx} in @var{exp}.
354@findex XVECLEN
355@item XVECLEN (@var{exp}, @var{idx})
356Access the length (number of elements) in the vector which is
357in operand number @var{idx} in @var{exp}. This value is an @code{int}.
359@findex XVECEXP
360@item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
361Access element number @var{eltnum} in the vector which is
362in operand number @var{idx} in @var{exp}. This value is an RTX@.
364It is up to you to make sure that @var{eltnum} is not negative
365and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
366@end table
368All the macros defined in this section expand into lvalues and therefore
369can be used to assign the operands, lengths and vector elements as well as
370to access them.
372@node Special Accessors
373@section Access to Special Operands
374@cindex access to special operands
376Some RTL nodes have special annotations associated with them.
378@table @code
379@item MEM
380@table @code
381@findex MEM_ALIAS_SET
382@item MEM_ALIAS_SET (@var{x})
383If 0, @var{x} is not in any alias set, and may alias anything. Otherwise,
384@var{x} can only alias @code{MEM}s in a conflicting alias set. This value
385is set in a language-dependent manner in the front-end, and should not be
386altered in the back-end. In some front-ends, these numbers may correspond
387in some way to types, or other language-level entities, but they need not,
388and the back-end makes no such assumptions.
389These set numbers are tested with @code{alias_sets_conflict_p}.
391@findex MEM_EXPR
392@item MEM_EXPR (@var{x})
393If this register is known to hold the value of some user-level
394declaration, this is that tree node. It may also be a
395@code{COMPONENT_REF}, in which case this is some field reference,
396and @code{TREE_OPERAND (@var{x}, 0)} contains the declaration,
397or another @code{COMPONENT_REF}, or null if there is no compile-time
398object associated with the reference.
400@findex MEM_OFFSET
401@item MEM_OFFSET (@var{x})
402The offset from the start of @code{MEM_EXPR} as a @code{CONST_INT} rtx.
404@findex MEM_SIZE
405@item MEM_SIZE (@var{x})
406The size in bytes of the memory reference as a @code{CONST_INT} rtx.
407This is mostly relevant for @code{BLKmode} references as otherwise
408the size is implied by the mode.
410@findex MEM_ALIGN
411@item MEM_ALIGN (@var{x})
412The known alignment in bits of the memory reference.
413@end table
415@item REG
416@table @code
418@item ORIGINAL_REGNO (@var{x})
419This field holds the number the register ``originally'' had; for a
420pseudo register turned into a hard reg this will hold the old pseudo
421register number.
423@findex REG_EXPR
424@item REG_EXPR (@var{x})
425If this register is known to hold the value of some user-level
426declaration, this is that tree node.
428@findex REG_OFFSET
429@item REG_OFFSET (@var{x})
430If this register is known to hold the value of some user-level
431declaration, this is the offset into that logical storage.
432@end table
434@item SYMBOL_REF
435@table @code
436@findex SYMBOL_REF_DECL
437@item SYMBOL_REF_DECL (@var{x})
438If the @code{symbol_ref} @var{x} was created for a @code{VAR_DECL} or
439a @code{FUNCTION_DECL}, that tree is recorded here. If this value is
440null, then @var{x} was created by back end code generation routines,
441and there is no associated front end symbol table entry.
443@code{SYMBOL_REF_DECL} may also point to a tree of class @code{'c'},
444that is, some sort of constant. In this case, the @code{symbol_ref}
445is an entry in the per-file constant pool; again, there is no associated
446front end symbol table entry.
449@item SYMBOL_REF_FLAGS (@var{x})
450In a @code{symbol_ref}, this is used to communicate various predicates
451about the symbol. Some of these are common enough to be computed by
452common code, some are specific to the target. The common bits are:
454@table @code
458Set if the symbol refers to a function.
463Set if the symbol is local to this ``module''.
469Set if this symbol is not defined in this translation unit.
470Note that this is not the inverse of @code{SYMBOL_FLAG_LOCAL}.
475Set if the symbol is located in the small data section.
480@item SYMBOL_REF_TLS_MODEL (@var{x})
481This is a multi-bit field accessor that returns the @code{tls_model}
482to be used for a thread-local storage symbol. It returns zero for
483non-thread-local symbols.
484@end table
486Bits beginning with @code{SYMBOL_FLAG_MACH_DEP} are available for
487the target's use.
488@end table
489@end table
491@node Flags
492@section Flags in an RTL Expression
493@cindex flags in RTL expression
495RTL expressions contain several flags (one-bit bit-fields)
496that are used in certain types of expression. Most often they
497are accessed with the following macros, which expand into lvalues.
499@table @code
501@cindex @code{symbol_ref} and @samp{/u}
502@cindex @code{unchanging}, in @code{symbol_ref}
503@item CONSTANT_POOL_ADDRESS_P (@var{x})
504Nonzero in a @code{symbol_ref} if it refers to part of the current
505function's constant pool. For most targets these addresses are in a
506@code{.rodata} section entirely separate from the function, but for
507some targets the addresses are close to the beginning of the function.
508In either case GCC assumes these addresses can be addressed directly,
509perhaps with the help of base registers.
510Stored in the @code{unchanging} field and printed as @samp{/u}.
513@cindex @code{call_insn} and @samp{/u}
514@cindex @code{unchanging}, in @code{call_insn}
515@item CONST_OR_PURE_CALL_P (@var{x})
516In a @code{call_insn}, @code{note}, or an @code{expr_list} for notes,
517indicates that the insn represents a call to a const or pure function.
518Stored in the @code{unchanging} field and printed as @samp{/u}.
521@cindex @code{jump_insn} and @samp{/u}
522@cindex @code{call_insn} and @samp{/u}
523@cindex @code{insn} and @samp{/u}
524@cindex @code{unchanging}, in @code{jump_insn}, @code{call_insn} and @code{insn}
525@item INSN_ANNULLED_BRANCH_P (@var{x})
526In a @code{jump_insn}, @code{call_insn}, or @code{insn} indicates
527that the branch is an annulling one. See the discussion under
528@code{sequence} below. Stored in the @code{unchanging} field and
529printed as @samp{/u}.
531@findex INSN_DEAD_CODE_P
532@cindex @code{insn} and @samp{/s}
533@cindex @code{in_struct}, in @code{insn}
534@item INSN_DEAD_CODE_P (@var{x})
535In an @code{insn} during the dead-code elimination pass, nonzero if the
536insn is dead.
537Stored in the @code{in_struct} field and printed as @samp{/s}.
539@findex INSN_DELETED_P
540@cindex @code{insn} and @samp{/v}
541@cindex @code{call_insn} and @samp{/v}
542@cindex @code{jump_insn} and @samp{/v}
543@cindex @code{code_label} and @samp{/v}
544@cindex @code{barrier} and @samp{/v}
545@cindex @code{note} and @samp{/v}
546@cindex @code{volatil}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, @code{barrier}, and @code{note}
547@item INSN_DELETED_P (@var{x})
548In an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label},
549@code{barrier}, or @code{note},
550nonzero if the insn has been deleted. Stored in the
551@code{volatil} field and printed as @samp{/v}.
554@cindex @code{insn} and @samp{/s}
555@cindex @code{jump_insn} and @samp{/s}
556@cindex @code{call_insn} and @samp{/s}
557@cindex @code{in_struct}, in @code{insn} and @code{jump_insn} and @code{call_insn}
558@item INSN_FROM_TARGET_P (@var{x})
559In an @code{insn} or @code{jump_insn} or @code{call_insn} in a delay
560slot of a branch, indicates that the insn
561is from the target of the branch. If the branch insn has
562@code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if
563the branch is taken. For annulled branches with
564@code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the
565branch is not taken. When @code{INSN_ANNULLED_BRANCH_P} is not set,
566this insn will always be executed. Stored in the @code{in_struct}
567field and printed as @samp{/s}.
570@cindex @code{label_ref} and @samp{/s}
571@cindex @code{in_struct}, in @code{label_ref}
572@item LABEL_OUTSIDE_LOOP_P (@var{x})
573In @code{label_ref} expressions, nonzero if this is a reference to a
574label that is outside the innermost loop containing the reference to the
575label. Stored in the @code{in_struct} field and printed as @samp{/s}.
578@cindex @code{code_label} and @samp{/i}
579@cindex @code{note} and @samp{/i}
580@cindex @code{in_struct}, in @code{code_label} and @code{note}
581@item LABEL_PRESERVE_P (@var{x})
582In a @code{code_label} or @code{note}, indicates that the label is referenced by
583code or data not visible to the RTL of a given function.
584Labels referenced by a non-local goto will have this bit set. Stored
585in the @code{in_struct} field and printed as @samp{/s}.
588@cindex @code{label_ref} and @samp{/v}
589@cindex @code{reg_label} and @samp{/v}
590@cindex @code{volatil}, in @code{label_ref} and @code{reg_label}
591@item LABEL_REF_NONLOCAL_P (@var{x})
592In @code{label_ref} and @code{reg_label} expressions, nonzero if this is
593a reference to a non-local label.
594Stored in the @code{volatil} field and printed as @samp{/v}.
596@findex MEM_IN_STRUCT_P
597@cindex @code{mem} and @samp{/s}
598@cindex @code{in_struct}, in @code{mem}
599@item MEM_IN_STRUCT_P (@var{x})
600In @code{mem} expressions, nonzero for reference to an entire structure,
601union or array, or to a component of one. Zero for references to a
602scalar variable or through a pointer to a scalar. If both this flag and
603@code{MEM_SCALAR_P} are clear, then we don't know whether this @code{mem}
604is in a structure or not. Both flags should never be simultaneously set.
605Stored in the @code{in_struct} field and printed as @samp{/s}.
608@cindex @code{mem} and @samp{/j}
609@cindex @code{jump}, in @code{mem}
610@item MEM_KEEP_ALIAS_SET_P (@var{x})
611In @code{mem} expressions, 1 if we should keep the alias set for this
612mem unchanged when we access a component. Set to 1, for example, when we
613are already in a non-addressable component of an aggregate.
614Stored in the @code{jump} field and printed as @samp{/j}.
616@findex MEM_SCALAR_P
617@cindex @code{mem} and @samp{/f}
618@cindex @code{frame_related}, in @code{mem}
619@item MEM_SCALAR_P (@var{x})
620In @code{mem} expressions, nonzero for reference to a scalar known not
621to be a member of a structure, union, or array. Zero for such
622references and for indirections through pointers, even pointers pointing
623to scalar types. If both this flag and @code{MEM_IN_STRUCT_P} are clear,
624then we don't know whether this @code{mem} is in a structure or not.
625Both flags should never be simultaneously set.
626Stored in the @code{frame_related} field and printed as @samp{/f}.
628@findex MEM_VOLATILE_P
629@cindex @code{mem} and @samp{/v}
630@cindex @code{asm_input} and @samp{/v}
631@cindex @code{asm_operands} and @samp{/v}
632@cindex @code{volatil}, in @code{mem}, @code{asm_operands}, and @code{asm_input}
633@item MEM_VOLATILE_P (@var{x})
634In @code{mem}, @code{asm_operands}, and @code{asm_input} expressions,
635nonzero for volatile memory references.
636Stored in the @code{volatil} field and printed as @samp{/v}.
638@findex MEM_NOTRAP_P
639@cindex @code{mem} and @samp{/c}
640@cindex @code{call}, in @code{mem}
641@item MEM_NOTRAP_P (@var{x})
642In @code{mem}, nonzero for memory references that will not trap.
643Stored in the @code{call} field and printed as @samp{/c}.
646@cindex @code{reg} and @samp{/i}
647@cindex @code{integrated}, in @code{reg}
648@item REG_FUNCTION_VALUE_P (@var{x})
649Nonzero in a @code{reg} if it is the place in which this function's
650value is going to be returned. (This happens only in a hard
651register.) Stored in the @code{integrated} field and printed as
654@findex REG_LOOP_TEST_P
655@cindex @code{reg} and @samp{/s}
656@cindex @code{in_struct}, in @code{reg}
657@item REG_LOOP_TEST_P (@var{x})
658In @code{reg} expressions, nonzero if this register's entire life is
659contained in the exit test code for some loop. Stored in the
660@code{in_struct} field and printed as @samp{/s}.
662@findex REG_POINTER
663@cindex @code{reg} and @samp{/f}
664@cindex @code{frame_related}, in @code{reg}
665@item REG_POINTER (@var{x})
666Nonzero in a @code{reg} if the register holds a pointer. Stored in the
667@code{frame_related} field and printed as @samp{/f}.
669@findex REG_USERVAR_P
670@cindex @code{reg} and @samp{/v}
671@cindex @code{volatil}, in @code{reg}
672@item REG_USERVAR_P (@var{x})
673In a @code{reg}, nonzero if it corresponds to a variable present in
674the user's source code. Zero for temporaries generated internally by
675the compiler. Stored in the @code{volatil} field and printed as
678The same hard register may be used also for collecting the values of
679functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
680in this kind of use.
683@cindex @code{insn} and @samp{/f}
684@cindex @code{call_insn} and @samp{/f}
685@cindex @code{jump_insn} and @samp{/f}
686@cindex @code{barrier} and @samp{/f}
687@cindex @code{set} and @samp{/f}
688@cindex @code{frame_related}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, and @code{set}
689@item RTX_FRAME_RELATED_P (@var{x})
690Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn},
691@code{barrier}, or @code{set} which is part of a function prologue
692and sets the stack pointer, sets the frame pointer, or saves a register.
693This flag should also be set on an instruction that sets up a temporary
694register to use in place of the frame pointer.
695Stored in the @code{frame_related} field and printed as @samp{/f}.
697In particular, on RISC targets where there are limits on the sizes of
698immediate constants, it is sometimes impossible to reach the register
699save area directly from the stack pointer. In that case, a temporary
700register is used that is near enough to the register save area, and the
701Canonical Frame Address, i.e., DWARF2's logical frame pointer, register
702must (temporarily) be changed to be this temporary register. So, the
703instruction that sets this temporary register must be marked as
706If the marked instruction is overly complex (defined in terms of what
707@code{dwarf2out_frame_debug_expr} can handle), you will also have to
708create a @code{REG_FRAME_RELATED_EXPR} note and attach it to the
709instruction. This note should contain a simple expression of the
710computation performed by this instruction, i.e., one that
711@code{dwarf2out_frame_debug_expr} can handle.
713This flag is required for exception handling support on targets with RTL
717@cindex @code{insn} and @samp{/i}
718@cindex @code{call_insn} and @samp{/i}
719@cindex @code{jump_insn} and @samp{/i}
720@cindex @code{barrier} and @samp{/i}
721@cindex @code{code_label} and @samp{/i}
722@cindex @code{insn_list} and @samp{/i}
723@cindex @code{const} and @samp{/i}
724@cindex @code{note} and @samp{/i}
725@cindex @code{integrated}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, @code{code_label}, @code{insn_list}, @code{const}, and @code{note}
726@item RTX_INTEGRATED_P (@var{x})
727Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier},
728@code{code_label}, @code{insn_list}, @code{const}, or @code{note} if it
729resulted from an in-line function call.
730Stored in the @code{integrated} field and printed as @samp{/i}.
733@cindex @code{reg} and @samp{/u}
734@cindex @code{mem} and @samp{/u}
735@cindex @code{concat} and @samp{/u}
736@cindex @code{unchanging}, in @code{reg} and @code{mem}
737@item RTX_UNCHANGING_P (@var{x})
738Nonzero in a @code{reg}, @code{mem}, or @code{concat} if the register or
739memory is set at most once, anywhere. This does not mean that it is
740function invariant.
742GCC uses this flag to determine whether two references conflict. As
743implemented by @code{true_dependence} in @file{alias.c} for memory
744references, unchanging memory can't conflict with non-unchanging memory;
745a non-unchanging read can conflict with a non-unchanging write; an
746unchanging read can conflict with an unchanging write (since there may
747be a single store to this address to initialize it); and an unchanging
748store can conflict with a non-unchanging read. This means we must make
749conservative assumptions when choosing the value of this flag for a
750memory reference to an object containing both unchanging and
751non-unchanging fields: we must set the flag when writing to the object
752and clear it when reading from the object.
754Stored in the @code{unchanging} field and printed as @samp{/u}.
756@findex SCHED_GROUP_P
757@cindex @code{insn} and @samp{/s}
758@cindex @code{call_insn} and @samp{/s}
759@cindex @code{jump_insn} and @samp{/s}
760@cindex @code{in_struct}, in @code{insn}, @code{jump_insn} and @code{call_insn}
761@item SCHED_GROUP_P (@var{x})
762During instruction scheduling, in an @code{insn}, @code{call_insn} or
763@code{jump_insn}, indicates that the
764previous insn must be scheduled together with this insn. This is used to
765ensure that certain groups of instructions will not be split up by the
766instruction scheduling pass, for example, @code{use} insns before
767a @code{call_insn} may not be separated from the @code{call_insn}.
768Stored in the @code{in_struct} field and printed as @samp{/s}.
770@findex SET_IS_RETURN_P
771@cindex @code{insn} and @samp{/j}
772@cindex @code{jump}, in @code{insn}
773@item SET_IS_RETURN_P (@var{x})
774For a @code{set}, nonzero if it is for a return.
775Stored in the @code{jump} field and printed as @samp{/j}.
777@findex SIBLING_CALL_P
778@cindex @code{call_insn} and @samp{/j}
779@cindex @code{jump}, in @code{call_insn}
780@item SIBLING_CALL_P (@var{x})
781For a @code{call_insn}, nonzero if the insn is a sibling call.
782Stored in the @code{jump} field and printed as @samp{/j}.
785@cindex @code{symbol_ref} and @samp{/f}
786@cindex @code{frame_related}, in @code{symbol_ref}
787@item STRING_POOL_ADDRESS_P (@var{x})
788For a @code{symbol_ref} expression, nonzero if it addresses this function's
789string constant pool.
790Stored in the @code{frame_related} field and printed as @samp{/f}.
793@cindex @code{subreg} and @samp{/u} and @samp{/v}
794@cindex @code{unchanging}, in @code{subreg}
795@cindex @code{volatil}, in @code{subreg}
797Returns a value greater then zero for a @code{subreg} that has
798@code{SUBREG_PROMOTED_VAR_P} nonzero if the object being referenced is kept
799zero-extended, zero if it is kept sign-extended, and less then zero if it is
800extended some other way via the @code{ptr_extend} instruction.
801Stored in the @code{unchanging}
802field and @code{volatil} field, printed as @samp{/u} and @samp{/v}.
803This macro may only be used to get the value it may not be used to change
804the value. Use @code{SUBREG_PROMOTED_UNSIGNED_SET} to change the value.
807@cindex @code{subreg} and @samp{/u}
808@cindex @code{unchanging}, in @code{subreg}
809@cindex @code{volatil}, in @code{subreg}
811Set the @code{unchanging} and @code{volatil} fields in a @code{subreg}
812to reflect zero, sign, or other extension. If @code{volatil} is
813zero, then @code{unchanging} as nonzero means zero extension and as
814zero means sign extension. If @code{volatil} is nonzero then some
815other type of extension was done via the @code{ptr_extend} instruction.
818@cindex @code{subreg} and @samp{/s}
819@cindex @code{in_struct}, in @code{subreg}
820@item SUBREG_PROMOTED_VAR_P (@var{x})
821Nonzero in a @code{subreg} if it was made when accessing an object that
822was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine
823description macro (@pxref{Storage Layout}). In this case, the mode of
824the @code{subreg} is the declared mode of the object and the mode of
825@code{SUBREG_REG} is the mode of the register that holds the object.
826Promoted variables are always either sign- or zero-extended to the wider
827mode on every assignment. Stored in the @code{in_struct} field and
828printed as @samp{/s}.
830@findex SYMBOL_REF_USED
831@cindex @code{used}, in @code{symbol_ref}
832@item SYMBOL_REF_USED (@var{x})
833In a @code{symbol_ref}, indicates that @var{x} has been used. This is
834normally only used to ensure that @var{x} is only declared external
835once. Stored in the @code{used} field.
837@findex SYMBOL_REF_WEAK
838@cindex @code{symbol_ref} and @samp{/i}
839@cindex @code{integrated}, in @code{symbol_ref}
840@item SYMBOL_REF_WEAK (@var{x})
841In a @code{symbol_ref}, indicates that @var{x} has been declared weak.
842Stored in the @code{integrated} field and printed as @samp{/i}.
844@findex SYMBOL_REF_FLAG
845@cindex @code{symbol_ref} and @samp{/v}
846@cindex @code{volatil}, in @code{symbol_ref}
847@item SYMBOL_REF_FLAG (@var{x})
848In a @code{symbol_ref}, this is used as a flag for machine-specific purposes.
849Stored in the @code{volatil} field and printed as @samp{/v}.
851Most uses of @code{SYMBOL_REF_FLAG} are historic and may be subsumed
852by @code{SYMBOL_REF_FLAGS}. Certainly use of @code{SYMBOL_REF_FLAGS}
853is mandatory if the target requires more than one bit of storage.
854@end table
856These are the fields to which the above macros refer:
858@table @code
859@findex call
860@cindex @samp{/c} in RTL dump
861@item call
862In a @code{mem}, 1 means that the memory reference will not trap.
864In an RTL dump, this flag is represented as @samp{/c}.
866@findex frame_related
867@cindex @samp{/f} in RTL dump
868@item frame_related
869In an @code{insn} or @code{set} expression, 1 means that it is part of
870a function prologue and sets the stack pointer, sets the frame pointer,
871saves a register, or sets up a temporary register to use in place of the
872frame pointer.
874In @code{reg} expressions, 1 means that the register holds a pointer.
876In @code{symbol_ref} expressions, 1 means that the reference addresses
877this function's string constant pool.
879In @code{mem} expressions, 1 means that the reference is to a scalar.
881In an RTL dump, this flag is represented as @samp{/f}.
883@findex in_struct
884@cindex @samp{/s} in RTL dump
885@item in_struct
886In @code{mem} expressions, it is 1 if the memory datum referred to is
887all or part of a structure or array; 0 if it is (or might be) a scalar
888variable. A reference through a C pointer has 0 because the pointer
889might point to a scalar variable. This information allows the compiler
890to determine something about possible cases of aliasing.
892In @code{reg} expressions, it is 1 if the register has its entire life
893contained within the test expression of some loop.
895In @code{subreg} expressions, 1 means that the @code{subreg} is accessing
896an object that has had its mode promoted from a wider mode.
898In @code{label_ref} expressions, 1 means that the referenced label is
899outside the innermost loop containing the insn in which the @code{label_ref}
900was found.
902In @code{code_label} expressions, it is 1 if the label may never be deleted.
903This is used for labels which are the target of non-local gotos. Such a
904label that would have been deleted is replaced with a @code{note} of type
907In an @code{insn} during dead-code elimination, 1 means that the insn is
908dead code.
910In an @code{insn} or @code{jump_insn} during reorg for an insn in the
911delay slot of a branch,
9121 means that this insn is from the target of the branch.
914In an @code{insn} during instruction scheduling, 1 means that this insn
915must be scheduled as part of a group together with the previous insn.
917In an RTL dump, this flag is represented as @samp{/s}.
919@findex integrated
920@cindex @samp{/i} in RTL dump
921@item integrated
922In an @code{insn}, @code{insn_list}, or @code{const}, 1 means the RTL was
923produced by procedure integration.
925In @code{reg} expressions, 1 means the register contains
926the value to be returned by the current function. On
927machines that pass parameters in registers, the same register number
928may be used for parameters as well, but this flag is not set on such
931In @code{symbol_ref} expressions, 1 means the referenced symbol is weak.
933In an RTL dump, this flag is represented as @samp{/i}.
935@findex jump
936@cindex @samp{/j} in RTL dump
937@item jump
938In a @code{mem} expression, 1 means we should keep the alias set for this
939mem unchanged when we access a component.
941In a @code{set}, 1 means it is for a return.
943In a @code{call_insn}, 1 means it is a sibling call.
945In an RTL dump, this flag is represented as @samp{/j}.
947@findex unchanging
948@cindex @samp{/u} in RTL dump
949@item unchanging
950In @code{reg} and @code{mem} expressions, 1 means
951that the value of the expression never changes.
953In @code{subreg} expressions, it is 1 if the @code{subreg} references an
954unsigned object whose mode has been promoted to a wider mode.
956In an @code{insn} or @code{jump_insn} in the delay slot of a branch
957instruction, 1 means an annulling branch should be used.
959In a @code{symbol_ref} expression, 1 means that this symbol addresses
960something in the per-function constant pool.
962In a @code{call_insn}, @code{note}, or an @code{expr_list} of notes,
9631 means that this instruction is a call to a const or pure function.
965In an RTL dump, this flag is represented as @samp{/u}.
967@findex used
968@item used
969This flag is used directly (without an access macro) at the end of RTL
970generation for a function, to count the number of times an expression
971appears in insns. Expressions that appear more than once are copied,
972according to the rules for shared structure (@pxref{Sharing}).
974For a @code{reg}, it is used directly (without an access macro) by the
975leaf register renumbering code to ensure that each register is only
976renumbered once.
978In a @code{symbol_ref}, it indicates that an external declaration for
979the symbol has already been written.
981@findex volatil
982@cindex @samp{/v} in RTL dump
983@item volatil
984@cindex volatile memory references
985In a @code{mem}, @code{asm_operands}, or @code{asm_input}
986expression, it is 1 if the memory
987reference is volatile. Volatile memory references may not be deleted,
988reordered or combined.
990In a @code{symbol_ref} expression, it is used for machine-specific
993In a @code{reg} expression, it is 1 if the value is a user-level variable.
9940 indicates an internal compiler temporary.
996In an @code{insn}, 1 means the insn has been deleted.
998In @code{label_ref} and @code{reg_label} expressions, 1 means a reference
999to a non-local label.
1001In an RTL dump, this flag is represented as @samp{/v}.
1002@end table
1004@node Machine Modes
1005@section Machine Modes
1006@cindex machine modes
1008@findex enum machine_mode
1009A machine mode describes a size of data object and the representation used
1010for it. In the C code, machine modes are represented by an enumeration
1011type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL
1012expression has room for a machine mode and so do certain kinds of tree
1013expressions (declarations and types, to be precise).
1015In debugging dumps and machine descriptions, the machine mode of an RTL
1016expression is written after the expression code with a colon to separate
1017them. The letters @samp{mode} which appear at the end of each machine mode
1018name are omitted. For example, @code{(reg:SI 38)} is a @code{reg}
1019expression with machine mode @code{SImode}. If the mode is
1020@code{VOIDmode}, it is not written at all.
1022Here is a table of machine modes. The term ``byte'' below refers to an
1023object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}).
1025@table @code
1026@findex BImode
1027@item BImode
1028``Bit'' mode represents a single bit, for predicate registers.
1030@findex QImode
1031@item QImode
1032``Quarter-Integer'' mode represents a single byte treated as an integer.
1034@findex HImode
1035@item HImode
1036``Half-Integer'' mode represents a two-byte integer.
1038@findex PSImode
1039@item PSImode
1040``Partial Single Integer'' mode represents an integer which occupies
1041four bytes but which doesn't really use all four. On some machines,
1042this is the right mode to use for pointers.
1044@findex SImode
1045@item SImode
1046``Single Integer'' mode represents a four-byte integer.
1048@findex PDImode
1049@item PDImode
1050``Partial Double Integer'' mode represents an integer which occupies
1051eight bytes but which doesn't really use all eight. On some machines,
1052this is the right mode to use for certain pointers.
1054@findex DImode
1055@item DImode
1056``Double Integer'' mode represents an eight-byte integer.
1058@findex TImode
1059@item TImode
1060``Tetra Integer'' (?) mode represents a sixteen-byte integer.
1062@findex OImode
1063@item OImode
1064``Octa Integer'' (?) mode represents a thirty-two-byte integer.
1066@findex QFmode
1067@item QFmode
1068``Quarter-Floating'' mode represents a quarter-precision (single byte)
1069floating point number.
1071@findex HFmode
1072@item HFmode
1073``Half-Floating'' mode represents a half-precision (two byte) floating
1074point number.
1076@findex TQFmode
1077@item TQFmode
1078``Three-Quarter-Floating'' (?) mode represents a three-quarter-precision
1079(three byte) floating point number.
1081@findex SFmode
1082@item SFmode
1083``Single Floating'' mode represents a four byte floating point number.
1084In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1085this is a single-precision IEEE floating point number; it can also be
1086used for double-precision (on processors with 16-bit bytes) and
1087single-precision VAX and IBM types.
1089@findex DFmode
1090@item DFmode
1091``Double Floating'' mode represents an eight byte floating point number.
1092In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1093this is a double-precision IEEE floating point number.
1095@findex XFmode
1096@item XFmode
1097``Extended Floating'' mode represents a twelve byte floating point
1098number. This mode is used for IEEE extended floating point. On some
1099systems not all bits within these bytes will actually be used.
1101@findex TFmode
1102@item TFmode
1103``Tetra Floating'' mode represents a sixteen byte floating point number.
1104This gets used for both the 96-bit extended IEEE floating-point types
1105padded to 128 bits, and true 128-bit extended IEEE floating-point types.
1107@findex CCmode
1108@item CCmode
1109``Condition Code'' mode represents the value of a condition code, which
1110is a machine-specific set of bits used to represent the result of a
1111comparison operation. Other machine-specific modes may also be used for
1112the condition code. These modes are not used on machines that use
1113@code{cc0} (see @pxref{Condition Code}).
1115@findex BLKmode
1116@item BLKmode
1117``Block'' mode represents values that are aggregates to which none of
1118the other modes apply. In RTL, only memory references can have this mode,
1119and only if they appear in string-move or vector instructions. On machines
1120which have no such instructions, @code{BLKmode} will not appear in RTL@.
1122@findex VOIDmode
1123@item VOIDmode
1124Void mode means the absence of a mode or an unspecified mode.
1125For example, RTL expressions of code @code{const_int} have mode
1126@code{VOIDmode} because they can be taken to have whatever mode the context
1127requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by
1128the absence of any mode.
1130@findex QCmode
1131@findex HCmode
1132@findex SCmode
1133@findex DCmode
1134@findex XCmode
1135@findex TCmode
1136@item QCmode, HCmode, SCmode, DCmode, XCmode, TCmode
1137These modes stand for a complex number represented as a pair of floating
1138point values. The floating point values are in @code{QFmode},
1139@code{HFmode}, @code{SFmode}, @code{DFmode}, @code{XFmode}, and
1140@code{TFmode}, respectively.
1142@findex CQImode
1143@findex CHImode
1144@findex CSImode
1145@findex CDImode
1146@findex CTImode
1147@findex COImode
1148@item CQImode, CHImode, CSImode, CDImode, CTImode, COImode
1149These modes stand for a complex number represented as a pair of integer
1150values. The integer values are in @code{QImode}, @code{HImode},
1151@code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode},
1153@end table
1155The machine description defines @code{Pmode} as a C macro which expands
1156into the machine mode used for addresses. Normally this is the mode
1157whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines.
1159The only modes which a machine description @i{must} support are
1160@code{QImode}, and the modes corresponding to @code{BITS_PER_WORD},
1161@code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}.
1162The compiler will attempt to use @code{DImode} for 8-byte structures and
1163unions, but this can be prevented by overriding the definition of
1164@code{MAX_FIXED_MODE_SIZE}. Alternatively, you can have the compiler
1165use @code{TImode} for 16-byte structures and unions. Likewise, you can
1166arrange for the C type @code{short int} to avoid using @code{HImode}.
1168@cindex mode classes
1169Very few explicit references to machine modes remain in the compiler and
1170these few references will soon be removed. Instead, the machine modes
1171are divided into mode classes. These are represented by the enumeration
1172type @code{enum mode_class} defined in @file{machmode.h}. The possible
1173mode classes are:
1175@table @code
1176@findex MODE_INT
1177@item MODE_INT
1178Integer modes. By default these are @code{BImode}, @code{QImode},
1179@code{HImode}, @code{SImode}, @code{DImode}, @code{TImode}, and
1182@findex MODE_PARTIAL_INT
1184The ``partial integer'' modes, @code{PQImode}, @code{PHImode},
1185@code{PSImode} and @code{PDImode}.
1187@findex MODE_FLOAT
1188@item MODE_FLOAT
1189Floating point modes. By default these are @code{QFmode},
1190@code{HFmode}, @code{TQFmode}, @code{SFmode}, @code{DFmode},
1191@code{XFmode} and @code{TFmode}.
1193@findex MODE_COMPLEX_INT
1195Complex integer modes. (These are not currently implemented).
1199Complex floating point modes. By default these are @code{QCmode},
1200@code{HCmode}, @code{SCmode}, @code{DCmode}, @code{XCmode}, and
1203@findex MODE_FUNCTION
1205Algol or Pascal function variables including a static chain.
1206(These are not currently implemented).
1208@findex MODE_CC
1209@item MODE_CC
1210Modes representing condition code values. These are @code{CCmode} plus
1211any modes listed in the @code{EXTRA_CC_MODES} macro. @xref{Jump Patterns},
1212also see @ref{Condition Code}.
1214@findex MODE_RANDOM
1215@item MODE_RANDOM
1216This is a catchall mode class for modes which don't fit into the above
1217classes. Currently @code{VOIDmode} and @code{BLKmode} are in
1219@end table
1221Here are some C macros that relate to machine modes:
1223@table @code
1224@findex GET_MODE
1225@item GET_MODE (@var{x})
1226Returns the machine mode of the RTX @var{x}.
1228@findex PUT_MODE
1229@item PUT_MODE (@var{x}, @var{newmode})
1230Alters the machine mode of the RTX @var{x} to be @var{newmode}.
1234Stands for the number of machine modes available on the target
1235machine. This is one greater than the largest numeric value of any
1236machine mode.
1238@findex GET_MODE_NAME
1239@item GET_MODE_NAME (@var{m})
1240Returns the name of mode @var{m} as a string.
1242@findex GET_MODE_CLASS
1243@item GET_MODE_CLASS (@var{m})
1244Returns the mode class of mode @var{m}.
1247@item GET_MODE_WIDER_MODE (@var{m})
1248Returns the next wider natural mode. For example, the expression
1249@code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}.
1251@findex GET_MODE_SIZE
1252@item GET_MODE_SIZE (@var{m})
1253Returns the size in bytes of a datum of mode @var{m}.
1255@findex GET_MODE_BITSIZE
1256@item GET_MODE_BITSIZE (@var{m})
1257Returns the size in bits of a datum of mode @var{m}.
1259@findex GET_MODE_MASK
1260@item GET_MODE_MASK (@var{m})
1261Returns a bitmask containing 1 for all bits in a word that fit within
1262mode @var{m}. This macro can only be used for modes whose bitsize is
1263less than or equal to @code{HOST_BITS_PER_INT}.
1266@item GET_MODE_ALIGNMENT (@var{m})
1267Return the required alignment, in bits, for an object of mode @var{m}.
1269@findex GET_MODE_UNIT_SIZE
1270@item GET_MODE_UNIT_SIZE (@var{m})
1271Returns the size in bytes of the subunits of a datum of mode @var{m}.
1272This is the same as @code{GET_MODE_SIZE} except in the case of complex
1273modes. For them, the unit size is the size of the real or imaginary
1276@findex GET_MODE_NUNITS
1277@item GET_MODE_NUNITS (@var{m})
1278Returns the number of units contained in a mode, i.e.,
1279@code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}.
1282@item GET_CLASS_NARROWEST_MODE (@var{c})
1283Returns the narrowest mode in mode class @var{c}.
1284@end table
1286@findex byte_mode
1287@findex word_mode
1288The global variables @code{byte_mode} and @code{word_mode} contain modes
1289whose classes are @code{MODE_INT} and whose bitsizes are either
1290@code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit
1291machines, these are @code{QImode} and @code{SImode}, respectively.
1293@node Constants
1294@section Constant Expression Types
1295@cindex RTL constants
1296@cindex RTL constant expression types
1298The simplest RTL expressions are those that represent constant values.
1300@table @code
1301@findex const_int
1302@item (const_int @var{i})
1303This type of expression represents the integer value @var{i}. @var{i}
1304is customarily accessed with the macro @code{INTVAL} as in
1305@code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}.
1307@findex const0_rtx
1308@findex const1_rtx
1309@findex const2_rtx
1310@findex constm1_rtx
1311There is only one expression object for the integer value zero; it is
1312the value of the variable @code{const0_rtx}. Likewise, the only
1313expression for integer value one is found in @code{const1_rtx}, the only
1314expression for integer value two is found in @code{const2_rtx}, and the
1315only expression for integer value negative one is found in
1316@code{constm1_rtx}. Any attempt to create an expression of code
1317@code{const_int} and value zero, one, two or negative one will return
1318@code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or
1319@code{constm1_rtx} as appropriate.
1321@findex const_true_rtx
1322Similarly, there is only one object for the integer whose value is
1323@code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If
1324@code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and
1325@code{const1_rtx} will point to the same object. If
1326@code{STORE_FLAG_VALUE} is @minus{}1, @code{const_true_rtx} and
1327@code{constm1_rtx} will point to the same object.
1329@findex const_double
1330@item (const_double:@var{m} @var{addr} @var{i0} @var{i1} @dots{})
1331Represents either a floating-point constant of mode @var{m} or an
1332integer constant too large to fit into @code{HOST_BITS_PER_WIDE_INT}
1333bits but small enough to fit within twice that number of bits (GCC
1334does not provide a mechanism to represent even larger constants). In
1335the latter case, @var{m} will be @code{VOIDmode}.
1337@findex const_vector
1338@item (const_vector:@var{m} [@var{x0} @var{x1} @dots{}])
1339Represents a vector constant. The square brackets stand for the vector
1340containing the constant elements. @var{x0}, @var{x1} and so on are
1341the @code{const_int} or @code{const_double} elements.
1343The number of units in a @code{const_vector} is obtained with the macro
1344@code{CONST_VECTOR_NUNITS} as in @code{CONST_VECTOR_NUNITS (@var{v})}.
1346Individual elements in a vector constant are accessed with the macro
1347@code{CONST_VECTOR_ELT} as in @code{CONST_VECTOR_ELT (@var{v}, @var{n})}
1348where @var{v} is the vector constant and @var{n} is the element
1351@findex CONST_DOUBLE_MEM
1353@var{addr} is used to contain the @code{mem} expression that corresponds
1354to the location in memory that at which the constant can be found. If
1355it has not been allocated a memory location, but is on the chain of all
1356@code{const_double} expressions in this compilation (maintained using an
1357undisplayed field), @var{addr} contains @code{const0_rtx}. If it is not
1358on the chain, @var{addr} contains @code{cc0_rtx}. @var{addr} is
1359customarily accessed with the macro @code{CONST_DOUBLE_MEM} and the
1360chain field via @code{CONST_DOUBLE_CHAIN}.
1362@findex CONST_DOUBLE_LOW
1363If @var{m} is @code{VOIDmode}, the bits of the value are stored in
1364@var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro
1365@code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}.
1367If the constant is floating point (regardless of its precision), then
1368the number of integers used to store the value depends on the size of
1369@code{REAL_VALUE_TYPE} (@pxref{Floating Point}). The integers
1370represent a floating point number, but not precisely in the target
1371machine's or host machine's floating point format. To convert them to
1372the precise bit pattern used by the target machine, use the macro
1373@code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}).
1375@findex CONST0_RTX
1376@findex CONST1_RTX
1377@findex CONST2_RTX
1378The macro @code{CONST0_RTX (@var{mode})} refers to an expression with
1379value 0 in mode @var{mode}. If mode @var{mode} is of mode class
1380@code{MODE_INT}, it returns @code{const0_rtx}. If mode @var{mode} is of
1381mode class @code{MODE_FLOAT}, it returns a @code{CONST_DOUBLE}
1382expression in mode @var{mode}. Otherwise, it returns a
1383@code{CONST_VECTOR} expression in mode @var{mode}. Similarly, the macro
1384@code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in
1385mode @var{mode} and similarly for @code{CONST2_RTX}. The
1386@code{CONST1_RTX} and @code{CONST2_RTX} macros are undefined
1387for vector modes.
1389@findex const_string
1390@item (const_string @var{str})
1391Represents a constant string with value @var{str}. Currently this is
1392used only for insn attributes (@pxref{Insn Attributes}) since constant
1393strings in C are placed in memory.
1395@findex symbol_ref
1396@item (symbol_ref:@var{mode} @var{symbol})
1397Represents the value of an assembler label for data. @var{symbol} is
1398a string that describes the name of the assembler label. If it starts
1399with a @samp{*}, the label is the rest of @var{symbol} not including
1400the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed
1401with @samp{_}.
1403The @code{symbol_ref} contains a mode, which is usually @code{Pmode}.
1404Usually that is the only mode for which a symbol is directly valid.
1406@findex label_ref
1407@item (label_ref @var{label})
1408Represents the value of an assembler label for code. It contains one
1409operand, an expression, which must be a @code{code_label} or a @code{note}
1410of type @code{NOTE_INSN_DELETED_LABEL} that appears in the instruction
1411sequence to identify the place where the label should go.
1413The reason for using a distinct expression type for code label
1414references is so that jump optimization can distinguish them.
1416@item (const:@var{m} @var{exp})
1417Represents a constant that is the result of an assembly-time
1418arithmetic computation. The operand, @var{exp}, is an expression that
1419contains only constants (@code{const_int}, @code{symbol_ref} and
1420@code{label_ref} expressions) combined with @code{plus} and
1421@code{minus}. However, not all combinations are valid, since the
1422assembler cannot do arbitrary arithmetic on relocatable symbols.
1424@var{m} should be @code{Pmode}.
1426@findex high
1427@item (high:@var{m} @var{exp})
1428Represents the high-order bits of @var{exp}, usually a
1429@code{symbol_ref}. The number of bits is machine-dependent and is
1430normally the number of bits specified in an instruction that initializes
1431the high order bits of a register. It is used with @code{lo_sum} to
1432represent the typical two-instruction sequence used in RISC machines to
1433reference a global memory location.
1435@var{m} should be @code{Pmode}.
1436@end table
1438@node Regs and Memory
1439@section Registers and Memory
1440@cindex RTL register expressions
1441@cindex RTL memory expressions
1443Here are the RTL expression types for describing access to machine
1444registers and to main memory.
1446@table @code
1447@findex reg
1448@cindex hard registers
1449@cindex pseudo registers
1450@item (reg:@var{m} @var{n})
1451For small values of the integer @var{n} (those that are less than
1452@code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
1453register number @var{n}: a @dfn{hard register}. For larger values of
1454@var{n}, it stands for a temporary value or @dfn{pseudo register}.
1455The compiler's strategy is to generate code assuming an unlimited
1456number of such pseudo registers, and later convert them into hard
1457registers or into memory references.
1459@var{m} is the machine mode of the reference. It is necessary because
1460machines can generally refer to each register in more than one mode.
1461For example, a register may contain a full word but there may be
1462instructions to refer to it as a half word or as a single byte, as
1463well as instructions to refer to it as a floating point number of
1464various precisions.
1466Even for a register that the machine can access in only one mode,
1467the mode must always be specified.
1469The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
1470description, since the number of hard registers on the machine is an
1471invariant characteristic of the machine. Note, however, that not
1472all of the machine registers must be general registers. All the
1473machine registers that can be used for storage of data are given
1474hard register numbers, even those that can be used only in certain
1475instructions or can hold only certain types of data.
1477A hard register may be accessed in various modes throughout one
1478function, but each pseudo register is given a natural mode
1479and is accessed only in that mode. When it is necessary to describe
1480an access to a pseudo register using a nonnatural mode, a @code{subreg}
1481expression is used.
1483A @code{reg} expression with a machine mode that specifies more than
1484one word of data may actually stand for several consecutive registers.
1485If in addition the register number specifies a hardware register, then
1486it actually represents several consecutive hardware registers starting
1487with the specified one.
1489Each pseudo register number used in a function's RTL code is
1490represented by a unique @code{reg} expression.
1494Some pseudo register numbers, those within the range of
1496appear during the RTL generation phase and are eliminated before the
1497optimization phases. These represent locations in the stack frame that
1498cannot be determined until RTL generation for the function has been
1499completed. The following virtual register numbers are defined:
1501@table @code
1504This points to the first word of the incoming arguments passed on the
1505stack. Normally these arguments are placed there by the caller, but the
1506callee may have pushed some arguments that were previously passed in
1509@cindex @code{FIRST_PARM_OFFSET} and virtual registers
1510@cindex @code{ARG_POINTER_REGNUM} and virtual registers
1511When RTL generation is complete, this virtual register is replaced
1512by the sum of the register given by @code{ARG_POINTER_REGNUM} and the
1513value of @code{FIRST_PARM_OFFSET}.
1516@cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers
1518If @code{FRAME_GROWS_DOWNWARD} is defined, this points to immediately
1519above the first variable on the stack. Otherwise, it points to the
1520first variable on the stack.
1522@cindex @code{STARTING_FRAME_OFFSET} and virtual registers
1523@cindex @code{FRAME_POINTER_REGNUM} and virtual registers
1524@code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the
1525register given by @code{FRAME_POINTER_REGNUM} and the value
1530This points to the location of dynamically allocated memory on the stack
1531immediately after the stack pointer has been adjusted by the amount of
1532memory desired.
1534@cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers
1535@cindex @code{STACK_POINTER_REGNUM} and virtual registers
1536This virtual register is replaced by the sum of the register given by
1537@code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}.
1541This points to the location in the stack at which outgoing arguments
1542should be written when the stack is pre-pushed (arguments pushed using
1543push insns should always use @code{STACK_POINTER_REGNUM}).
1545@cindex @code{STACK_POINTER_OFFSET} and virtual registers
1546This virtual register is replaced by the sum of the register given by
1547@code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}.
1548@end table
1550@findex subreg
1551@item (subreg:@var{m} @var{reg} @var{bytenum})
1552@code{subreg} expressions are used to refer to a register in a machine
1553mode other than its natural one, or to refer to one register of
1554a multi-part @code{reg} that actually refers to several registers.
1556Each pseudo-register has a natural mode. If it is necessary to
1557operate on it in a different mode---for example, to perform a fullword
1558move instruction on a pseudo-register that contains a single
1559byte---the pseudo-register must be enclosed in a @code{subreg}. In
1560such a case, @var{bytenum} is zero.
1562Usually @var{m} is at least as narrow as the mode of @var{reg}, in which
1563case it is restricting consideration to only the bits of @var{reg} that
1564are in @var{m}.
1566Sometimes @var{m} is wider than the mode of @var{reg}. These
1567@code{subreg} expressions are often called @dfn{paradoxical}. They are
1568used in cases where we want to refer to an object in a wider mode but do
1569not care what value the additional bits have. The reload pass ensures
1570that paradoxical references are only made to hard registers.
1572The other use of @code{subreg} is to extract the individual registers of
1573a multi-register value. Machine modes such as @code{DImode} and
1574@code{TImode} can indicate values longer than a word, values which
1575usually require two or more consecutive registers. To access one of the
1576registers, use a @code{subreg} with mode @code{SImode} and a
1577@var{bytenum} offset that says which register.
1579Storing in a non-paradoxical @code{subreg} has undefined results for
1580bits belonging to the same word as the @code{subreg}. This laxity makes
1581it easier to generate efficient code for such instructions. To
1582represent an instruction that preserves all the bits outside of those in
1583the @code{subreg}, use @code{strict_low_part} around the @code{subreg}.
1585@cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
1586The compilation parameter @code{WORDS_BIG_ENDIAN}, if set to 1, says
1587that byte number zero is part of the most significant word; otherwise,
1588it is part of the least significant word.
1590@cindex @code{BYTES_BIG_ENDIAN}, effect on @code{subreg}
1591The compilation parameter @code{BYTES_BIG_ENDIAN}, if set to 1, says
1592that byte number zero is the most significant byte within a word;
1593otherwise, it is the least significant byte within a word.
1595@cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg}
1596On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with
1598However, most parts of the compiler treat floating point values as if
1599they had the same endianness as integer values. This works because
1600they handle them solely as a collection of integer values, with no
1601particular numerical value. Only real.c and the runtime libraries
1602care about @code{FLOAT_WORDS_BIG_ENDIAN}.
1604@cindex combiner pass
1605@cindex reload pass
1606@cindex @code{subreg}, special reload handling
1607Between the combiner pass and the reload pass, it is possible to have a
1608paradoxical @code{subreg} which contains a @code{mem} instead of a
1609@code{reg} as its first operand. After the reload pass, it is also
1610possible to have a non-paradoxical @code{subreg} which contains a
1611@code{mem}; this usually occurs when the @code{mem} is a stack slot
1612which replaced a pseudo register.
1614Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
1615using a @code{subreg}. On some machines the most significant part of a
1616@code{DFmode} value does not have the same format as a single-precision
1617floating value.
1619It is also not valid to access a single word of a multi-word value in a
1620hard register when less registers can hold the value than would be
1621expected from its size. For example, some 32-bit machines have
1622floating-point registers that can hold an entire @code{DFmode} value.
1623If register 10 were such a register @code{(subreg:SI (reg:DF 10) 1)}
1624would be invalid because there is no way to convert that reference to
1625a single machine register. The reload pass prevents @code{subreg}
1626expressions such as these from being formed.
1628@findex SUBREG_REG
1629@findex SUBREG_BYTE
1630The first operand of a @code{subreg} expression is customarily accessed
1631with the @code{SUBREG_REG} macro and the second operand is customarily
1632accessed with the @code{SUBREG_BYTE} macro.
1634@findex scratch
1635@cindex scratch operands
1636@item (scratch:@var{m})
1637This represents a scratch register that will be required for the
1638execution of a single instruction and not used subsequently. It is
1639converted into a @code{reg} by either the local register allocator or
1640the reload pass.
1642@code{scratch} is usually present inside a @code{clobber} operation
1643(@pxref{Side Effects}).
1645@findex cc0
1646@cindex condition code register
1647@item (cc0)
1648This refers to the machine's condition code register. It has no
1649operands and may not have a machine mode. There are two ways to use it:
1651@itemize @bullet
1653To stand for a complete set of condition code flags. This is best on
1654most machines, where each comparison sets the entire series of flags.
1656With this technique, @code{(cc0)} may be validly used in only two
1657contexts: as the destination of an assignment (in test and compare
1658instructions) and in comparison operators comparing against zero
1659(@code{const_int} with value zero; that is to say, @code{const0_rtx}).
1662To stand for a single flag that is the result of a single condition.
1663This is useful on machines that have only a single flag bit, and in
1664which comparison instructions must specify the condition to test.
1666With this technique, @code{(cc0)} may be validly used in only two
1667contexts: as the destination of an assignment (in test and compare
1668instructions) where the source is a comparison operator, and as the
1669first operand of @code{if_then_else} (in a conditional branch).
1670@end itemize
1672@findex cc0_rtx
1673There is only one expression object of code @code{cc0}; it is the
1674value of the variable @code{cc0_rtx}. Any attempt to create an
1675expression of code @code{cc0} will return @code{cc0_rtx}.
1677Instructions can set the condition code implicitly. On many machines,
1678nearly all instructions set the condition code based on the value that
1679they compute or store. It is not necessary to record these actions
1680explicitly in the RTL because the machine description includes a
1681prescription for recognizing the instructions that do so (by means of
1682the macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only
1683instructions whose sole purpose is to set the condition code, and
1684instructions that use the condition code, need mention @code{(cc0)}.
1686On some machines, the condition code register is given a register number
1687and a @code{reg} is used instead of @code{(cc0)}. This is usually the
1688preferable approach if only a small subset of instructions modify the
1689condition code. Other machines store condition codes in general
1690registers; in such cases a pseudo register should be used.
1692Some machines, such as the SPARC and RS/6000, have two sets of
1693arithmetic instructions, one that sets and one that does not set the
1694condition code. This is best handled by normally generating the
1695instruction that does not set the condition code, and making a pattern
1696that both performs the arithmetic and sets the condition code register
1697(which would not be @code{(cc0)} in this case). For examples, search
1698for @samp{addcc} and @samp{andcc} in @file{}.
1700@findex pc
1701@item (pc)
1702@cindex program counter
1703This represents the machine's program counter. It has no operands and
1704may not have a machine mode. @code{(pc)} may be validly used only in
1705certain specific contexts in jump instructions.
1707@findex pc_rtx
1708There is only one expression object of code @code{pc}; it is the value
1709of the variable @code{pc_rtx}. Any attempt to create an expression of
1710code @code{pc} will return @code{pc_rtx}.
1712All instructions that do not jump alter the program counter implicitly
1713by incrementing it, but there is no need to mention this in the RTL@.
1715@findex mem
1716@item (mem:@var{m} @var{addr} @var{alias})
1717This RTX represents a reference to main memory at an address
1718represented by the expression @var{addr}. @var{m} specifies how large
1719a unit of memory is accessed. @var{alias} specifies an alias set for the
1720reference. In general two items are in different alias sets if they cannot
1721reference the same memory address.
1723The construct @code{(mem:BLK (scratch))} is considered to alias all
1724other memories. Thus it may be used as a memory barrier in epilogue
1725stack deallocation patterns.
1727@findex addressof
1728@item (addressof:@var{m} @var{reg})
1729This RTX represents a request for the address of register @var{reg}. Its mode
1730is always @code{Pmode}. If there are any @code{addressof}
1731expressions left in the function after CSE, @var{reg} is forced into the
1732stack and the @code{addressof} expression is replaced with a @code{plus}
1733expression for the address of its stack slot.
1734@end table
1736@node Arithmetic
1737@section RTL Expressions for Arithmetic
1738@cindex arithmetic, in RTL
1739@cindex math, in RTL
1740@cindex RTL expressions for arithmetic
1742Unless otherwise specified, all the operands of arithmetic expressions
1743must be valid for mode @var{m}. An operand is valid for mode @var{m}
1744if it has mode @var{m}, or if it is a @code{const_int} or
1745@code{const_double} and @var{m} is a mode of class @code{MODE_INT}.
1747For commutative binary operations, constants should be placed in the
1748second operand.
1750@table @code
1751@findex plus
1752@cindex RTL addition
1753@cindex RTL sum
1754@item (plus:@var{m} @var{x} @var{y})
1755Represents the sum of the values represented by @var{x} and @var{y}
1756carried out in machine mode @var{m}.
1758@findex lo_sum
1759@item (lo_sum:@var{m} @var{x} @var{y})
1760Like @code{plus}, except that it represents that sum of @var{x} and the
1761low-order bits of @var{y}. The number of low order bits is
1762machine-dependent but is normally the number of bits in a @code{Pmode}
1763item minus the number of bits set by the @code{high} code
1766@var{m} should be @code{Pmode}.
1768@findex minus
1769@cindex RTL subtraction
1770@cindex RTL difference
1771@item (minus:@var{m} @var{x} @var{y})
1772Like @code{plus} but represents subtraction.
1774@findex ss_plus
1775@cindex RTL addition with signed saturation
1776@item (ss_plus:@var{m} @var{x} @var{y})
1778Like @code{plus}, but using signed saturation in case of an overflow.
1780@findex us_plus
1781@cindex RTL addition with unsigned saturation
1782@item (us_plus:@var{m} @var{x} @var{y})
1784Like @code{plus}, but using unsigned saturation in case of an overflow.
1786@findex ss_minus
1787@cindex RTL addition with signed saturation
1788@item (ss_minus:@var{m} @var{x} @var{y})
1790Like @code{minus}, but using signed saturation in case of an overflow.
1792@findex us_minus
1793@cindex RTL addition with unsigned saturation
1794@item (us_minus:@var{m} @var{x} @var{y})
1796Like @code{minus}, but using unsigned saturation in case of an overflow.
1798@findex compare
1799@cindex RTL comparison
1800@item (compare:@var{m} @var{x} @var{y})
1801Represents the result of subtracting @var{y} from @var{x} for purposes
1802of comparison. The result is computed without overflow, as if with
1803infinite precision.
1805Of course, machines can't really subtract with infinite precision.
1806However, they can pretend to do so when only the sign of the result will
1807be used, which is the case when the result is stored in the condition
1808code. And that is the @emph{only} way this kind of expression may
1809validly be used: as a value to be stored in the condition codes, either
1810@code{(cc0)} or a register. @xref{Comparisons}.
1812The mode @var{m} is not related to the modes of @var{x} and @var{y}, but
1813instead is the mode of the condition code value. If @code{(cc0)} is
1814used, it is @code{VOIDmode}. Otherwise it is some mode in class
1815@code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}. If @var{m}
1816is @code{VOIDmode} or @code{CCmode}, the operation returns sufficient
1817information (in an unspecified format) so that any comparison operator
1818can be applied to the result of the @code{COMPARE} operation. For other
1819modes in class @code{MODE_CC}, the operation only returns a subset of
1820this information.
1822Normally, @var{x} and @var{y} must have the same mode. Otherwise,
1823@code{compare} is valid only if the mode of @var{x} is in class
1824@code{MODE_INT} and @var{y} is a @code{const_int} or
1825@code{const_double} with mode @code{VOIDmode}. The mode of @var{x}
1826determines what mode the comparison is to be done in; thus it must not
1827be @code{VOIDmode}.
1829If one of the operands is a constant, it should be placed in the
1830second operand and the comparison code adjusted as appropriate.
1832A @code{compare} specifying two @code{VOIDmode} constants is not valid
1833since there is no way to know in what mode the comparison is to be
1834performed; the comparison must either be folded during the compilation
1835or the first operand must be loaded into a register while its mode is
1836still known.
1838@findex neg
1839@item (neg:@var{m} @var{x})
1840Represents the negation (subtraction from zero) of the value represented
1841by @var{x}, carried out in mode @var{m}.
1843@findex mult
1844@cindex multiplication
1845@cindex product
1846@item (mult:@var{m} @var{x} @var{y})
1847Represents the signed product of the values represented by @var{x} and
1848@var{y} carried out in machine mode @var{m}.
1850Some machines support a multiplication that generates a product wider
1851than the operands. Write the pattern for this as
1854(mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
1855@end smallexample
1857where @var{m} is wider than the modes of @var{x} and @var{y}, which need
1858not be the same.
1860For unsigned widening multiplication, use the same idiom, but with
1861@code{zero_extend} instead of @code{sign_extend}.
1863@findex div
1864@cindex division
1865@cindex signed division
1866@cindex quotient
1867@item (div:@var{m} @var{x} @var{y})
1868Represents the quotient in signed division of @var{x} by @var{y},
1869carried out in machine mode @var{m}. If @var{m} is a floating point
1870mode, it represents the exact quotient; otherwise, the integerized
1873Some machines have division instructions in which the operands and
1874quotient widths are not all the same; you should represent
1875such instructions using @code{truncate} and @code{sign_extend} as in,
1878(truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
1879@end smallexample
1881@findex udiv
1882@cindex unsigned division
1883@cindex division
1884@item (udiv:@var{m} @var{x} @var{y})
1885Like @code{div} but represents unsigned division.
1887@findex mod
1888@findex umod
1889@cindex remainder
1890@cindex division
1891@item (mod:@var{m} @var{x} @var{y})
1892@itemx (umod:@var{m} @var{x} @var{y})
1893Like @code{div} and @code{udiv} but represent the remainder instead of
1894the quotient.
1896@findex smin
1897@findex smax
1898@cindex signed minimum
1899@cindex signed maximum
1900@item (smin:@var{m} @var{x} @var{y})
1901@itemx (smax:@var{m} @var{x} @var{y})
1902Represents the smaller (for @code{smin}) or larger (for @code{smax}) of
1903@var{x} and @var{y}, interpreted as signed integers in mode @var{m}.
1905@findex umin
1906@findex umax
1907@cindex unsigned minimum and maximum
1908@item (umin:@var{m} @var{x} @var{y})
1909@itemx (umax:@var{m} @var{x} @var{y})
1910Like @code{smin} and @code{smax}, but the values are interpreted as unsigned
1913@findex not
1914@cindex complement, bitwise
1915@cindex bitwise complement
1916@item (not:@var{m} @var{x})
1917Represents the bitwise complement of the value represented by @var{x},
1918carried out in mode @var{m}, which must be a fixed-point machine mode.
1920@findex and
1921@cindex logical-and, bitwise
1922@cindex bitwise logical-and
1923@item (and:@var{m} @var{x} @var{y})
1924Represents the bitwise logical-and of the values represented by
1925@var{x} and @var{y}, carried out in machine mode @var{m}, which must be
1926a fixed-point machine mode.
1928@findex ior
1929@cindex inclusive-or, bitwise
1930@cindex bitwise inclusive-or
1931@item (ior:@var{m} @var{x} @var{y})
1932Represents the bitwise inclusive-or of the values represented by @var{x}
1933and @var{y}, carried out in machine mode @var{m}, which must be a
1934fixed-point mode.
1936@findex xor
1937@cindex exclusive-or, bitwise
1938@cindex bitwise exclusive-or
1939@item (xor:@var{m} @var{x} @var{y})
1940Represents the bitwise exclusive-or of the values represented by @var{x}
1941and @var{y}, carried out in machine mode @var{m}, which must be a
1942fixed-point mode.
1944@findex ashift
1945@cindex left shift
1946@cindex shift
1947@cindex arithmetic shift
1948@item (ashift:@var{m} @var{x} @var{c})
1949Represents the result of arithmetically shifting @var{x} left by @var{c}
1950places. @var{x} have mode @var{m}, a fixed-point machine mode. @var{c}
1951be a fixed-point mode or be a constant with mode @code{VOIDmode}; which
1952mode is determined by the mode called for in the machine description
1953entry for the left-shift instruction. For example, on the VAX, the mode
1954of @var{c} is @code{QImode} regardless of @var{m}.
1956@findex lshiftrt
1957@cindex right shift
1958@findex ashiftrt
1959@item (lshiftrt:@var{m} @var{x} @var{c})
1960@itemx (ashiftrt:@var{m} @var{x} @var{c})
1961Like @code{ashift} but for right shift. Unlike the case for left shift,
1962these two operations are distinct.
1964@findex rotate
1965@cindex rotate
1966@cindex left rotate
1967@findex rotatert
1968@cindex right rotate
1969@item (rotate:@var{m} @var{x} @var{c})
1970@itemx (rotatert:@var{m} @var{x} @var{c})
1971Similar but represent left and right rotate. If @var{c} is a constant,
1972use @code{rotate}.
1974@findex abs
1975@cindex absolute value
1976@item (abs:@var{m} @var{x})
1977Represents the absolute value of @var{x}, computed in mode @var{m}.
1979@findex sqrt
1980@cindex square root
1981@item (sqrt:@var{m} @var{x})
1982Represents the square root of @var{x}, computed in mode @var{m}.
1983Most often @var{m} will be a floating point mode.
1985@findex ffs
1986@item (ffs:@var{m} @var{x})
1987Represents one plus the index of the least significant 1-bit in
1988@var{x}, represented as an integer of mode @var{m}. (The value is
1989zero if @var{x} is zero.) The mode of @var{x} need not be @var{m};
1990depending on the target machine, various mode combinations may be
1993@findex clz
1994@item (clz:@var{m} @var{x})
1995Represents the number of leading 0-bits in @var{x}, represented as an
1996integer of mode @var{m}, starting at the most significant bit position.
1997If @var{x} is zero, the value is determined by
1998@code{CLZ_DEFINED_VALUE_AT_ZERO}. Note that this is one of
1999the few expressions that is not invariant under widening. The mode of
2000@var{x} will usually be an integer mode.
2002@findex ctz
2003@item (ctz:@var{m} @var{x})
2004Represents the number of trailing 0-bits in @var{x}, represented as an
2005integer of mode @var{m}, starting at the least significant bit position.
2006If @var{x} is zero, the value is determined by
2007@code{CTZ_DEFINED_VALUE_AT_ZERO}. Except for this case,
2008@code{ctz(x)} is equivalent to @code{ffs(@var{x}) - 1}. The mode of
2009@var{x} will usually be an integer mode.
2011@findex popcount
2012@item (popcount:@var{m} @var{x})
2013Represents the number of 1-bits in @var{x}, represented as an integer of
2014mode @var{m}. The mode of @var{x} will usually be an integer mode.
2016@findex parity
2017@item (parity:@var{m} @var{x})
2018Represents the number of 1-bits modulo 2 in @var{x}, represented as an
2019integer of mode @var{m}. The mode of @var{x} will usually be an integer
2021@end table
2023@node Comparisons
2024@section Comparison Operations
2025@cindex RTL comparison operations
2027Comparison operators test a relation on two operands and are considered
2028to represent a machine-dependent nonzero value described by, but not
2029necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
2030if the relation holds, or zero if it does not, for comparison operators
2031whose results have a `MODE_INT' mode, and
2032@code{FLOAT_STORE_FLAG_VALUE} (@pxref{Misc}) if the relation holds, or
2033zero if it does not, for comparison operators that return floating-point
2034values. The mode of the comparison operation is independent of the mode
2035of the data being compared. If the comparison operation is being tested
2036(e.g., the first operand of an @code{if_then_else}), the mode must be
2039@cindex condition codes
2040There are two ways that comparison operations may be used. The
2041comparison operators may be used to compare the condition codes
2042@code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such
2043a construct actually refers to the result of the preceding instruction
2044in which the condition codes were set. The instruction setting the
2045condition code must be adjacent to the instruction using the condition
2046code; only @code{note} insns may separate them.
2048Alternatively, a comparison operation may directly compare two data
2049objects. The mode of the comparison is determined by the operands; they
2050must both be valid for a common machine mode. A comparison with both
2051operands constant would be invalid as the machine mode could not be
2052deduced from it, but such a comparison should never exist in RTL due to
2053constant folding.
2055In the example above, if @code{(cc0)} were last set to
2056@code{(compare @var{x} @var{y})}, the comparison operation is
2057identical to @code{(eq @var{x} @var{y})}. Usually only one style
2058of comparisons is supported on a particular machine, but the combine
2059pass will try to merge the operations to produce the @code{eq} shown
2060in case it exists in the context of the particular insn involved.
2062Inequality comparisons come in two flavors, signed and unsigned. Thus,
2063there are distinct expression codes @code{gt} and @code{gtu} for signed and
2064unsigned greater-than. These can produce different results for the same
2065pair of integer values: for example, 1 is signed greater-than @minus{}1 but not
2066unsigned greater-than, because @minus{}1 when regarded as unsigned is actually
2067@code{0xffffffff} which is greater than 1.
2069The signed comparisons are also used for floating point values. Floating
2070point comparisons are distinguished by the machine modes of the operands.
2072@table @code
2073@findex eq
2074@cindex equal
2075@item (eq:@var{m} @var{x} @var{y})
2076@code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2077are equal, otherwise 0.
2079@findex ne
2080@cindex not equal
2081@item (ne:@var{m} @var{x} @var{y})
2082@code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2083are not equal, otherwise 0.
2085@findex gt
2086@cindex greater than
2087@item (gt:@var{m} @var{x} @var{y})
2088@code{STORE_FLAG_VALUE} if the @var{x} is greater than @var{y}. If they
2089are fixed-point, the comparison is done in a signed sense.
2091@findex gtu
2092@cindex greater than
2093@cindex unsigned greater than
2094@item (gtu:@var{m} @var{x} @var{y})
2095Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
2097@findex lt
2098@cindex less than
2099@findex ltu
2100@cindex unsigned less than
2101@item (lt:@var{m} @var{x} @var{y})
2102@itemx (ltu:@var{m} @var{x} @var{y})
2103Like @code{gt} and @code{gtu} but test for ``less than''.
2105@findex ge
2106@cindex greater than
2107@findex geu
2108@cindex unsigned greater than
2109@item (ge:@var{m} @var{x} @var{y})
2110@itemx (geu:@var{m} @var{x} @var{y})
2111Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
2113@findex le
2114@cindex less than or equal
2115@findex leu
2116@cindex unsigned less than
2117@item (le:@var{m} @var{x} @var{y})
2118@itemx (leu:@var{m} @var{x} @var{y})
2119Like @code{gt} and @code{gtu} but test for ``less than or equal''.
2121@findex if_then_else
2122@item (if_then_else @var{cond} @var{then} @var{else})
2123This is not a comparison operation but is listed here because it is
2124always used in conjunction with a comparison operation. To be
2125precise, @var{cond} is a comparison expression. This expression
2126represents a choice, according to @var{cond}, between the value
2127represented by @var{then} and the one represented by @var{else}.
2129On most machines, @code{if_then_else} expressions are valid only
2130to express conditional jumps.
2132@findex cond
2133@item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
2134Similar to @code{if_then_else}, but more general. Each of @var{test1},
2135@var{test2}, @dots{} is performed in turn. The result of this expression is
2136the @var{value} corresponding to the first nonzero test, or @var{default} if
2137none of the tests are nonzero expressions.
2139This is currently not valid for instruction patterns and is supported only
2140for insn attributes. @xref{Insn Attributes}.
2141@end table
2143@node Bit-Fields
2144@section Bit-Fields
2145@cindex bit-fields
2147Special expression codes exist to represent bit-field instructions.
2148These types of expressions are lvalues in RTL; they may appear
2149on the left side of an assignment, indicating insertion of a value
2150into the specified bit-field.
2152@table @code
2153@findex sign_extract
2154@cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
2155@item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
2156This represents a reference to a sign-extended bit-field contained or
2157starting in @var{loc} (a memory or register reference). The bit-field
2158is @var{size} bits wide and starts at bit @var{pos}. The compilation
2159option @code{BITS_BIG_ENDIAN} says which end of the memory unit
2160@var{pos} counts from.
2162If @var{loc} is in memory, its mode must be a single-byte integer mode.
2163If @var{loc} is in a register, the mode to use is specified by the
2164operand of the @code{insv} or @code{extv} pattern
2165(@pxref{Standard Names}) and is usually a full-word integer mode,
2166which is the default if none is specified.
2168The mode of @var{pos} is machine-specific and is also specified
2169in the @code{insv} or @code{extv} pattern.
2171The mode @var{m} is the same as the mode that would be used for
2172@var{loc} if it were a register.
2174@findex zero_extract
2175@item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
2176Like @code{sign_extract} but refers to an unsigned or zero-extended
2177bit-field. The same sequence of bits are extracted, but they
2178are filled to an entire word with zeros instead of by sign-extension.
2179@end table
2181@node Vector Operations
2182@section Vector Operations
2183@cindex vector operations
2185All normal RTL expressions can be used with vector modes; they are
2186interpreted as operating on each part of the vector independently.
2187Additionally, there are a few new expressions to describe specific vector
2190@table @code
2191@findex vec_merge
2192@item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items})
2193This describes a merge operation between two vectors. The result is a vector
2194of mode @var{m}; its elements are selected from either @var{vec1} or
2195@var{vec2}. Which elements are selected is described by @var{items}, which
2196is a bit mask represented by a @code{const_int}; a zero bit indicates the
2197corresponding element in the result vector is taken from @var{vec2} while
2198a set bit indicates it is taken from @var{vec1}.
2200@findex vec_select
2201@item (vec_select:@var{m} @var{vec1} @var{selection})
2202This describes an operation that selects parts of a vector. @var{vec1} is
2203the source vector, @var{selection} is a @code{parallel} that contains a
2204@code{const_int} for each of the subparts of the result vector, giving the
2205number of the source subpart that should be stored into it.
2207@findex vec_concat
2208@item (vec_concat:@var{m} @var{vec1} @var{vec2})
2209Describes a vector concat operation. The result is a concatenation of the
2210vectors @var{vec1} and @var{vec2}; its length is the sum of the lengths of
2211the two inputs.
2213@findex vec_duplicate
2214@item (vec_duplicate:@var{m} @var{vec})
2215This operation converts a small vector into a larger one by duplicating the
2216input values. The output vector mode must have the same submodes as the
2217input vector mode, and the number of output parts must be an integer multiple
2218of the number of input parts.
2220@end table
2222@node Conversions
2223@section Conversions
2224@cindex conversions
2225@cindex machine mode conversions
2227All conversions between machine modes must be represented by
2228explicit conversion operations. For example, an expression
2229which is the sum of a byte and a full word cannot be written as
2230@code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
2231operation requires two operands of the same machine mode.
2232Therefore, the byte-sized operand is enclosed in a conversion
2233operation, as in
2236(plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
2237@end smallexample
2239The conversion operation is not a mere placeholder, because there
2240may be more than one way of converting from a given starting mode
2241to the desired final mode. The conversion operation code says how
2242to do it.
2244For all conversion operations, @var{x} must not be @code{VOIDmode}
2245because the mode in which to do the conversion would not be known.
2246The conversion must either be done at compile-time or @var{x}
2247must be placed into a register.
2249@table @code
2250@findex sign_extend
2251@item (sign_extend:@var{m} @var{x})
2252Represents the result of sign-extending the value @var{x}
2253to machine mode @var{m}. @var{m} must be a fixed-point mode
2254and @var{x} a fixed-point value of a mode narrower than @var{m}.
2256@findex zero_extend
2257@item (zero_extend:@var{m} @var{x})
2258Represents the result of zero-extending the value @var{x}
2259to machine mode @var{m}. @var{m} must be a fixed-point mode
2260and @var{x} a fixed-point value of a mode narrower than @var{m}.
2262@findex float_extend
2263@item (float_extend:@var{m} @var{x})
2264Represents the result of extending the value @var{x}
2265to machine mode @var{m}. @var{m} must be a floating point mode
2266and @var{x} a floating point value of a mode narrower than @var{m}.
2268@findex truncate
2269@item (truncate:@var{m} @var{x})
2270Represents the result of truncating the value @var{x}
2271to machine mode @var{m}. @var{m} must be a fixed-point mode
2272and @var{x} a fixed-point value of a mode wider than @var{m}.
2274@findex ss_truncate
2275@item (ss_truncate:@var{m} @var{x})
2276Represents the result of truncating the value @var{x}
2277to machine mode @var{m}, using signed saturation in the case of
2278overflow. Both @var{m} and the mode of @var{x} must be fixed-point
2281@findex us_truncate
2282@item (us_truncate:@var{m} @var{x})
2283Represents the result of truncating the value @var{x}
2284to machine mode @var{m}, using unsigned saturation in the case of
2285overflow. Both @var{m} and the mode of @var{x} must be fixed-point
2288@findex float_truncate
2289@item (float_truncate:@var{m} @var{x})
2290Represents the result of truncating the value @var{x}
2291to machine mode @var{m}. @var{m} must be a floating point mode
2292and @var{x} a floating point value of a mode wider than @var{m}.
2294@findex float
2295@item (float:@var{m} @var{x})
2296Represents the result of converting fixed point value @var{x},
2297regarded as signed, to floating point mode @var{m}.
2299@findex unsigned_float
2300@item (unsigned_float:@var{m} @var{x})
2301Represents the result of converting fixed point value @var{x},
2302regarded as unsigned, to floating point mode @var{m}.
2304@findex fix
2305@item (fix:@var{m} @var{x})
2306When @var{m} is a fixed point mode, represents the result of
2307converting floating point value @var{x} to mode @var{m}, regarded as
2308signed. How rounding is done is not specified, so this operation may
2309be used validly in compiling C code only for integer-valued operands.
2311@findex unsigned_fix
2312@item (unsigned_fix:@var{m} @var{x})
2313Represents the result of converting floating point value @var{x} to
2314fixed point mode @var{m}, regarded as unsigned. How rounding is done
2315is not specified.
2317@findex fix
2318@item (fix:@var{m} @var{x})
2319When @var{m} is a floating point mode, represents the result of
2320converting floating point value @var{x} (valid for mode @var{m}) to an
2321integer, still represented in floating point mode @var{m}, by rounding
2322towards zero.
2323@end table
2325@node RTL Declarations
2326@section Declarations
2327@cindex RTL declarations
2328@cindex declarations, RTL
2330Declaration expression codes do not represent arithmetic operations
2331but rather state assertions about their operands.
2333@table @code
2334@findex strict_low_part
2335@cindex @code{subreg}, in @code{strict_low_part}
2336@item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
2337This expression code is used in only one context: as the destination operand of a
2338@code{set} expression. In addition, the operand of this expression
2339must be a non-paradoxical @code{subreg} expression.
2341The presence of @code{strict_low_part} says that the part of the
2342register which is meaningful in mode @var{n}, but is not part of
2343mode @var{m}, is not to be altered. Normally, an assignment to such
2344a subreg is allowed to have undefined effects on the rest of the
2345register when @var{m} is less than a word.
2346@end table
2348@node Side Effects
2349@section Side Effect Expressions
2350@cindex RTL side effect expressions
2352The expression codes described so far represent values, not actions.
2353But machine instructions never produce values; they are meaningful
2354only for their side effects on the state of the machine. Special
2355expression codes are used to represent side effects.
2357The body of an instruction is always one of these side effect codes;
2358the codes described above, which represent values, appear only as
2359the operands of these.
2361@table @code
2362@findex set
2363@item (set @var{lval} @var{x})
2364Represents the action of storing the value of @var{x} into the place
2365represented by @var{lval}. @var{lval} must be an expression
2366representing a place that can be stored in: @code{reg} (or @code{subreg},
2367@code{strict_low_part} or @code{zero_extract}), @code{mem}, @code{pc},
2368@code{parallel}, or @code{cc0}.
2370If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
2371machine mode; then @var{x} must be valid for that mode.
2373If @var{lval} is a @code{reg} whose machine mode is less than the full
2374width of the register, then it means that the part of the register
2375specified by the machine mode is given the specified value and the
2376rest of the register receives an undefined value. Likewise, if
2377@var{lval} is a @code{subreg} whose machine mode is narrower than
2378the mode of the register, the rest of the register can be changed in
2379an undefined way.
2381If @var{lval} is a @code{strict_low_part} or @code{zero_extract}
2382of a @code{subreg}, then the part of the register specified by the
2383machine mode of the @code{subreg} is given the value @var{x} and
2384the rest of the register is not changed.
2386If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
2387be either a @code{compare} expression or a value that may have any mode.
2388The latter case represents a ``test'' instruction. The expression
2389@code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to
2390@code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}.
2391Use the former expression to save space during the compilation.
2393If @var{lval} is a @code{parallel}, it is used to represent the case of
2394a function returning a structure in multiple registers. Each element
2395of the @code{parallel} is an @code{expr_list} whose first operand is a
2396@code{reg} and whose second operand is a @code{const_int} representing the
2397offset (in bytes) into the structure at which the data in that register
2398corresponds. The first element may be null to indicate that the structure
2399is also passed partly in memory.
2401@cindex jump instructions and @code{set}
2402@cindex @code{if_then_else} usage
2403If @var{lval} is @code{(pc)}, we have a jump instruction, and the
2404possibilities for @var{x} are very limited. It may be a
2405@code{label_ref} expression (unconditional jump). It may be an
2406@code{if_then_else} (conditional jump), in which case either the
2407second or the third operand must be @code{(pc)} (for the case which
2408does not jump) and the other of the two must be a @code{label_ref}
2409(for the case which does jump). @var{x} may also be a @code{mem} or
2410@code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
2411@code{mem}; these unusual patterns are used to represent jumps through
2412branch tables.
2414If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of
2415@var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
2416valid for the mode of @var{lval}.
2418@findex SET_DEST
2419@findex SET_SRC
2420@var{lval} is customarily accessed with the @code{SET_DEST} macro and
2421@var{x} with the @code{SET_SRC} macro.
2423@findex return
2424@item (return)
2425As the sole expression in a pattern, represents a return from the
2426current function, on machines where this can be done with one
2427instruction, such as VAXen. On machines where a multi-instruction
2428``epilogue'' must be executed in order to return from the function,
2429returning is done by jumping to a label which precedes the epilogue, and
2430the @code{return} expression code is never used.
2432Inside an @code{if_then_else} expression, represents the value to be
2433placed in @code{pc} to return to the caller.
2435Note that an insn pattern of @code{(return)} is logically equivalent to
2436@code{(set (pc) (return))}, but the latter form is never used.
2438@findex call
2439@item (call @var{function} @var{nargs})
2440Represents a function call. @var{function} is a @code{mem} expression
2441whose address is the address of the function to be called.
2442@var{nargs} is an expression which can be used for two purposes: on
2443some machines it represents the number of bytes of stack argument; on
2444others, it represents the number of argument registers.
2446Each machine has a standard machine mode which @var{function} must
2447have. The machine description defines macro @code{FUNCTION_MODE} to
2448expand into the requisite mode name. The purpose of this mode is to
2449specify what kind of addressing is allowed, on machines where the
2450allowed kinds of addressing depend on the machine mode being
2453@findex clobber
2454@item (clobber @var{x})
2455Represents the storing or possible storing of an unpredictable,
2456undescribed value into @var{x}, which must be a @code{reg},
2457@code{scratch}, @code{parallel} or @code{mem} expression.
2459One place this is used is in string instructions that store standard
2460values into particular hard registers. It may not be worth the
2461trouble to describe the values that are stored, but it is essential to
2462inform the compiler that the registers will be altered, lest it
2463attempt to keep data in them across the string instruction.
2465If @var{x} is @code{(mem:BLK (const_int 0))} or
2466@code{(mem:BLK (scratch))}, it means that all memory
2467locations must be presumed clobbered. If @var{x} is a @code{parallel},
2468it has the same meaning as a @code{parallel} in a @code{set} expression.
2470Note that the machine description classifies certain hard registers as
2471``call-clobbered''. All function call instructions are assumed by
2472default to clobber these registers, so there is no need to use
2473@code{clobber} expressions to indicate this fact. Also, each function
2474call is assumed to have the potential to alter any memory location,
2475unless the function is declared @code{const}.
2477If the last group of expressions in a @code{parallel} are each a
2478@code{clobber} expression whose arguments are @code{reg} or
2479@code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
2480phase can add the appropriate @code{clobber} expressions to an insn it
2481has constructed when doing so will cause a pattern to be matched.
2483This feature can be used, for example, on a machine that whose multiply
2484and add instructions don't use an MQ register but which has an
2485add-accumulate instruction that does clobber the MQ register. Similarly,
2486a combined instruction might require a temporary register while the
2487constituent instructions might not.
2489When a @code{clobber} expression for a register appears inside a
2490@code{parallel} with other side effects, the register allocator
2491guarantees that the register is unoccupied both before and after that
2492insn. However, the reload phase may allocate a register used for one of
2493the inputs unless the @samp{&} constraint is specified for the selected
2494alternative (@pxref{Modifiers}). You can clobber either a specific hard
2495register, a pseudo register, or a @code{scratch} expression; in the
2496latter two cases, GCC will allocate a hard register that is available
2497there for use as a temporary.
2499For instructions that require a temporary register, you should use
2500@code{scratch} instead of a pseudo-register because this will allow the
2501combiner phase to add the @code{clobber} when required. You do this by
2502coding (@code{clobber} (@code{match_scratch} @dots{})). If you do
2503clobber a pseudo register, use one which appears nowhere else---generate
2504a new one each time. Otherwise, you may confuse CSE@.
2506There is one other known use for clobbering a pseudo register in a
2507@code{parallel}: when one of the input operands of the insn is also
2508clobbered by the insn. In this case, using the same pseudo register in
2509the clobber and elsewhere in the insn produces the expected results.
2511@findex use
2512@item (use @var{x})
2513Represents the use of the value of @var{x}. It indicates that the
2514value in @var{x} at this point in the program is needed, even though
2515it may not be apparent why this is so. Therefore, the compiler will
2516not attempt to delete previous instructions whose only effect is to
2517store a value in @var{x}. @var{x} must be a @code{reg} expression.
2519In some situations, it may be tempting to add a @code{use} of a
2520register in a @code{parallel} to describe a situation where the value
2521of a special register will modify the behavior of the instruction.
2522An hypothetical example might be a pattern for an addition that can
2523either wrap around or use saturating addition depending on the value
2524of a special control register:
2527(parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
2528 (reg:SI 4)] 0))
2529 (use (reg:SI 1))])
2530@end smallexample
2534This will not work, several of the optimizers only look at expressions
2535locally; it is very likely that if you have multiple insns with
2536identical inputs to the @code{unspec}, they will be optimized away even
2537if register 1 changes in between.
2539This means that @code{use} can @emph{only} be used to describe
2540that the register is live. You should think twice before adding
2541@code{use} statements, more often you will want to use @code{unspec}
2542instead. The @code{use} RTX is most commonly useful to describe that
2543a fixed register is implicitly used in an insn. It is also safe to use
2544in patterns where the compiler knows for other reasons that the result
2545of the whole pattern is variable, such as @samp{movstr@var{m}} or
2546@samp{call} patterns.
2548During the reload phase, an insn that has a @code{use} as pattern
2549can carry a reg_equal note. These @code{use} insns will be deleted
2550before the reload phase exits.
2552During the delayed branch scheduling phase, @var{x} may be an insn.
2553This indicates that @var{x} previously was located at this place in the
2554code and its data dependencies need to be taken into account. These
2555@code{use} insns will be deleted before the delayed branch scheduling
2556phase exits.
2558@findex parallel
2559@item (parallel [@var{x0} @var{x1} @dots{}])
2560Represents several side effects performed in parallel. The square
2561brackets stand for a vector; the operand of @code{parallel} is a
2562vector of expressions. @var{x0}, @var{x1} and so on are individual
2563side effect expressions---expressions of code @code{set}, @code{call},
2564@code{return}, @code{clobber} or @code{use}.
2566``In parallel'' means that first all the values used in the individual
2567side-effects are computed, and second all the actual side-effects are
2568performed. For example,
2571(parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
2572 (set (mem:SI (reg:SI 1)) (reg:SI 1))])
2573@end smallexample
2576says unambiguously that the values of hard register 1 and the memory
2577location addressed by it are interchanged. In both places where
2578@code{(reg:SI 1)} appears as a memory address it refers to the value
2579in register 1 @emph{before} the execution of the insn.
2581It follows that it is @emph{incorrect} to use @code{parallel} and
2582expect the result of one @code{set} to be available for the next one.
2583For example, people sometimes attempt to represent a jump-if-zero
2584instruction this way:
2587(parallel [(set (cc0) (reg:SI 34))
2588 (set (pc) (if_then_else
2589 (eq (cc0) (const_int 0))
2590 (label_ref @dots{})
2591 (pc)))])
2592@end smallexample
2595But this is incorrect, because it says that the jump condition depends
2596on the condition code value @emph{before} this instruction, not on the
2597new value that is set by this instruction.
2599@cindex peephole optimization, RTL representation
2600Peephole optimization, which takes place together with final assembly
2601code output, can produce insns whose patterns consist of a @code{parallel}
2602whose elements are the operands needed to output the resulting
2603assembler code---often @code{reg}, @code{mem} or constant expressions.
2604This would not be well-formed RTL at any other stage in compilation,
2605but it is ok then because no further optimization remains to be done.
2606However, the definition of the macro @code{NOTICE_UPDATE_CC}, if
2607any, must deal with such insns if you define any peephole optimizations.
2609@findex cond_exec
2610@item (cond_exec [@var{cond} @var{expr}])
2611Represents a conditionally executed expression. The @var{expr} is
2612executed only if the @var{cond} is nonzero. The @var{cond} expression
2613must not have side-effects, but the @var{expr} may very well have
2616@findex sequence
2617@item (sequence [@var{insns} @dots{}])
2618Represents a sequence of insns. Each of the @var{insns} that appears
2619in the vector is suitable for appearing in the chain of insns, so it
2620must be an @code{insn}, @code{jump_insn}, @code{call_insn},
2621@code{code_label}, @code{barrier} or @code{note}.
2623A @code{sequence} RTX is never placed in an actual insn during RTL
2624generation. It represents the sequence of insns that result from a
2625@code{define_expand} @emph{before} those insns are passed to
2626@code{emit_insn} to insert them in the chain of insns. When actually
2627inserted, the individual sub-insns are separated out and the
2628@code{sequence} is forgotten.
2630After delay-slot scheduling is completed, an insn and all the insns that
2631reside in its delay slots are grouped together into a @code{sequence}.
2632The insn requiring the delay slot is the first insn in the vector;
2633subsequent insns are to be placed in the delay slot.
2635@code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
2636indicate that a branch insn should be used that will conditionally annul
2637the effect of the insns in the delay slots. In such a case,
2638@code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
2639the branch and should be executed only if the branch is taken; otherwise
2640the insn should be executed only if the branch is not taken.
2641@xref{Delay Slots}.
2642@end table
2644These expression codes appear in place of a side effect, as the body of
2645an insn, though strictly speaking they do not always describe side
2646effects as such:
2648@table @code
2649@findex asm_input
2650@item (asm_input @var{s})
2651Represents literal assembler code as described by the string @var{s}.
2653@findex unspec
2654@findex unspec_volatile
2655@item (unspec [@var{operands} @dots{}] @var{index})
2656@itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
2657Represents a machine-specific operation on @var{operands}. @var{index}
2658selects between multiple machine-specific operations.
2659@code{unspec_volatile} is used for volatile operations and operations
2660that may trap; @code{unspec} is used for other operations.
2662These codes may appear inside a @code{pattern} of an
2663insn, inside a @code{parallel}, or inside an expression.
2665@findex addr_vec
2666@item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
2667Represents a table of jump addresses. The vector elements @var{lr0},
2668etc., are @code{label_ref} expressions. The mode @var{m} specifies
2669how much space is given to each address; normally @var{m} would be
2672@findex addr_diff_vec
2673@item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags})
2674Represents a table of jump addresses expressed as offsets from
2675@var{base}. The vector elements @var{lr0}, etc., are @code{label_ref}
2676expressions and so is @var{base}. The mode @var{m} specifies how much
2677space is given to each address-difference. @var{min} and @var{max}
2678are set up by branch shortening and hold a label with a minimum and a
2679maximum address, respectively. @var{flags} indicates the relative
2680position of @var{base}, @var{min} and @var{max} to the containing insn
2681and of @var{min} and @var{max} to @var{base}. See rtl.def for details.
2683@findex prefetch
2684@item (prefetch:@var{m} @var{addr} @var{rw} @var{locality})
2685Represents prefetch of memory at address @var{addr}.
2686Operand @var{rw} is 1 if the prefetch is for data to be written, 0 otherwise;
2687targets that do not support write prefetches should treat this as a normal
2689Operand @var{locality} specifies the amount of temporal locality; 0 if there
2690is none or 1, 2, or 3 for increasing levels of temporal locality;
2691targets that do not support locality hints should ignore this.
2693This insn is used to minimize cache-miss latency by moving data into a
2694cache before it is accessed. It should use only non-faulting data prefetch
2696@end table
2698@node Incdec
2699@section Embedded Side-Effects on Addresses
2700@cindex RTL preincrement
2701@cindex RTL postincrement
2702@cindex RTL predecrement
2703@cindex RTL postdecrement
2705Six special side-effect expression codes appear as memory addresses.
2707@table @code
2708@findex pre_dec
2709@item (pre_dec:@var{m} @var{x})
2710Represents the side effect of decrementing @var{x} by a standard
2711amount and represents also the value that @var{x} has after being
2712decremented. @var{x} must be a @code{reg} or @code{mem}, but most
2713machines allow only a @code{reg}. @var{m} must be the machine mode
2714for pointers on the machine in use. The amount @var{x} is decremented
2715by is the length in bytes of the machine mode of the containing memory
2716reference of which this expression serves as the address. Here is an
2717example of its use:
2720(mem:DF (pre_dec:SI (reg:SI 39)))
2721@end smallexample
2724This says to decrement pseudo register 39 by the length of a @code{DFmode}
2725value and use the result to address a @code{DFmode} value.
2727@findex pre_inc
2728@item (pre_inc:@var{m} @var{x})
2729Similar, but specifies incrementing @var{x} instead of decrementing it.
2731@findex post_dec
2732@item (post_dec:@var{m} @var{x})
2733Represents the same side effect as @code{pre_dec} but a different
2734value. The value represented here is the value @var{x} has @i{before}
2735being decremented.
2737@findex post_inc
2738@item (post_inc:@var{m} @var{x})
2739Similar, but specifies incrementing @var{x} instead of decrementing it.
2741@findex post_modify
2742@item (post_modify:@var{m} @var{x} @var{y})
2744Represents the side effect of setting @var{x} to @var{y} and
2745represents @var{x} before @var{x} is modified. @var{x} must be a
2746@code{reg} or @code{mem}, but most machines allow only a @code{reg}.
2747@var{m} must be the machine mode for pointers on the machine in use.
2749The expression @var{y} must be one of three forms:
2750@table @code
2751@code{(plus:@var{m} @var{x} @var{z})},
2752@code{(minus:@var{m} @var{x} @var{z})}, or
2753@code{(plus:@var{m} @var{x} @var{i})},
2754@end table
2755where @var{z} is an index register and @var{i} is a constant.
2757Here is an example of its use:
2760(mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
2761 (reg:SI 48))))
2762@end smallexample
2764This says to modify pseudo register 42 by adding the contents of pseudo
2765register 48 to it, after the use of what ever 42 points to.
2767@findex pre_modify
2768@item (pre_modify:@var{m} @var{x} @var{expr})
2769Similar except side effects happen before the use.
2770@end table
2772These embedded side effect expressions must be used with care. Instruction
2773patterns may not use them. Until the @samp{flow} pass of the compiler,
2774they may occur only to represent pushes onto the stack. The @samp{flow}
2775pass finds cases where registers are incremented or decremented in one
2776instruction and used as an address shortly before or after; these cases are
2777then transformed to use pre- or post-increment or -decrement.
2779If a register used as the operand of these expressions is used in
2780another address in an insn, the original value of the register is used.
2781Uses of the register outside of an address are not permitted within the
2782same insn as a use in an embedded side effect expression because such
2783insns behave differently on different machines and hence must be treated
2784as ambiguous and disallowed.
2786An instruction that can be represented with an embedded side effect
2787could also be represented using @code{parallel} containing an additional
2788@code{set} to describe how the address register is altered. This is not
2789done because machines that allow these operations at all typically
2790allow them wherever a memory address is called for. Describing them as
2791additional parallel stores would require doubling the number of entries
2792in the machine description.
2794@node Assembler
2795@section Assembler Instructions as Expressions
2796@cindex assembler instructions in RTL
2798@cindex @code{asm_operands}, usage
2799The RTX code @code{asm_operands} represents a value produced by a
2800user-specified assembler instruction. It is used to represent
2801an @code{asm} statement with arguments. An @code{asm} statement with
2802a single output operand, like this:
2805asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
2806@end smallexample
2809is represented using a single @code{asm_operands} RTX which represents
2810the value that is stored in @code{outputvar}:
2813(set @var{rtx-for-outputvar}
2814 (asm_operands "foo %1,%2,%0" "a" 0
2815 [@var{rtx-for-addition-result} @var{rtx-for-*z}]
2816 [(asm_input:@var{m1} "g")
2817 (asm_input:@var{m2} "di")]))
2818@end smallexample
2821Here the operands of the @code{asm_operands} RTX are the assembler
2822template string, the output-operand's constraint, the index-number of the
2823output operand among the output operands specified, a vector of input
2824operand RTX's, and a vector of input-operand modes and constraints. The
2825mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
2828When an @code{asm} statement has multiple output values, its insn has
2829several such @code{set} RTX's inside of a @code{parallel}. Each @code{set}
2830contains a @code{asm_operands}; all of these share the same assembler
2831template and vectors, but each contains the constraint for the respective
2832output operand. They are also distinguished by the output-operand index
2833number, which is 0, 1, @dots{} for successive output operands.
2835@node Insns
2836@section Insns
2837@cindex insns
2839The RTL representation of the code for a function is a doubly-linked
2840chain of objects called @dfn{insns}. Insns are expressions with
2841special codes that are used for no other purpose. Some insns are
2842actual instructions; others represent dispatch tables for @code{switch}
2843statements; others represent labels to jump to or various sorts of
2844declarative information.
2846In addition to its own specific data, each insn must have a unique
2847id-number that distinguishes it from all other insns in the current
2848function (after delayed branch scheduling, copies of an insn with the
2849same id-number may be present in multiple places in a function, but
2850these copies will always be identical and will only appear inside a
2851@code{sequence}), and chain pointers to the preceding and following
2852insns. These three fields occupy the same position in every insn,
2853independent of the expression code of the insn. They could be accessed
2854with @code{XEXP} and @code{XINT}, but instead three special macros are
2855always used:
2857@table @code
2858@findex INSN_UID
2859@item INSN_UID (@var{i})
2860Accesses the unique id of insn @var{i}.
2862@findex PREV_INSN
2863@item PREV_INSN (@var{i})
2864Accesses the chain pointer to the insn preceding @var{i}.
2865If @var{i} is the first insn, this is a null pointer.
2867@findex NEXT_INSN
2868@item NEXT_INSN (@var{i})
2869Accesses the chain pointer to the insn following @var{i}.
2870If @var{i} is the last insn, this is a null pointer.
2871@end table
2873@findex get_insns
2874@findex get_last_insn
2875The first insn in the chain is obtained by calling @code{get_insns}; the
2876last insn is the result of calling @code{get_last_insn}. Within the
2877chain delimited by these insns, the @code{NEXT_INSN} and
2878@code{PREV_INSN} pointers must always correspond: if @var{insn} is not
2879the first insn,
2882NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
2883@end smallexample
2886is always true and if @var{insn} is not the last insn,
2889PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
2890@end smallexample
2893is always true.
2895After delay slot scheduling, some of the insns in the chain might be
2896@code{sequence} expressions, which contain a vector of insns. The value
2897of @code{NEXT_INSN} in all but the last of these insns is the next insn
2898in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
2899is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
2900which it is contained. Similar rules apply for @code{PREV_INSN}.
2902This means that the above invariants are not necessarily true for insns
2903inside @code{sequence} expressions. Specifically, if @var{insn} is the
2904first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
2905is the insn containing the @code{sequence} expression, as is the value
2906of @code{PREV_INSN (NEXT_INSN (@var{insn}))} if @var{insn} is the last
2907insn in the @code{sequence} expression. You can use these expressions
2908to find the containing @code{sequence} expression.
2910Every insn has one of the following six expression codes:
2912@table @code
2913@findex insn
2914@item insn
2915The expression code @code{insn} is used for instructions that do not jump
2916and do not do function calls. @code{sequence} expressions are always
2917contained in insns with code @code{insn} even if one of those insns
2918should jump or do function calls.
2920Insns with code @code{insn} have four additional fields beyond the three
2921mandatory ones listed above. These four are described in a table below.
2923@findex jump_insn
2924@item jump_insn
2925The expression code @code{jump_insn} is used for instructions that may
2926jump (or, more generally, may contain @code{label_ref} expressions). If
2927there is an instruction to return from the current function, it is
2928recorded as a @code{jump_insn}.
2930@findex JUMP_LABEL
2931@code{jump_insn} insns have the same extra fields as @code{insn} insns,
2932accessed in the same way and in addition contain a field
2933@code{JUMP_LABEL} which is defined once jump optimization has completed.
2935For simple conditional and unconditional jumps, this field contains
2936the @code{code_label} to which this insn will (possibly conditionally)
2937branch. In a more complex jump, @code{JUMP_LABEL} records one of the
2938labels that the insn refers to; the only way to find the others is to
2939scan the entire body of the insn. In an @code{addr_vec},
2940@code{JUMP_LABEL} is @code{NULL_RTX}.
2942Return insns count as jumps, but since they do not refer to any
2943labels, their @code{JUMP_LABEL} is @code{NULL_RTX}.
2945@findex call_insn
2946@item call_insn
2947The expression code @code{call_insn} is used for instructions that may do
2948function calls. It is important to distinguish these instructions because
2949they imply that certain registers and memory locations may be altered
2953@code{call_insn} insns have the same extra fields as @code{insn} insns,
2954accessed in the same way and in addition contain a field
2955@code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of
2956@code{expr_list} expressions) containing @code{use} and @code{clobber}
2957expressions that denote hard registers and @code{MEM}s used or
2958clobbered by the called function.
2960A @code{MEM} generally points to a stack slots in which arguments passed
2961to the libcall by reference (@pxref{Register Arguments,
2962FUNCTION_ARG_PASS_BY_REFERENCE}) are stored. If the argument is
2963caller-copied (@pxref{Register Arguments, FUNCTION_ARG_CALLEE_COPIES}),
2964the stack slot will be mentioned in @code{CLOBBER} and @code{USE}
2965entries; if it's callee-copied, only a @code{USE} will appear, and the
2966@code{MEM} may point to addresses that are not stack slots. These
2967@code{MEM}s are used only in libcalls, because, unlike regular function
2968calls, @code{CONST_CALL}s (which libcalls generally are, @pxref{Flags,
2969CONST_CALL_P}) aren't assumed to read and write all memory, so flow
2970would consider the stores dead and remove them. Note that, since a
2971libcall must never return values in memory (@pxref{Aggregate Return,
2972RETURN_IN_MEMORY}), there will never be a @code{CLOBBER} for a memory
2973address holding a return value.
2975@code{CLOBBER}ed registers in this list augment registers specified in
2976@code{CALL_USED_REGISTERS} (@pxref{Register Basics}).
2978@findex code_label
2980@item code_label
2981A @code{code_label} insn represents a label that a jump insn can jump
2982to. It contains two special fields of data in addition to the three
2983standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
2984number}, a number that identifies this label uniquely among all the
2985labels in the compilation (not just in the current function).
2986Ultimately, the label is represented in the assembler output as an
2987assembler label, usually of the form @samp{L@var{n}} where @var{n} is
2988the label number.
2990When a @code{code_label} appears in an RTL expression, it normally
2991appears within a @code{label_ref} which represents the address of
2992the label, as a number.
2994Besides as a @code{code_label}, a label can also be represented as a
2995@code{note} of type @code{NOTE_INSN_DELETED_LABEL}.
2997@findex LABEL_NUSES
2998The field @code{LABEL_NUSES} is only defined once the jump optimization
2999phase is completed. It contains the number of times this label is
3000referenced in the current function.
3002@findex LABEL_KIND
3003@findex SET_LABEL_KIND
3004@findex LABEL_ALT_ENTRY_P
3005@cindex alternate entry points
3006The field @code{LABEL_KIND} differentiates four different types of
3007labels: @code{LABEL_NORMAL}, @code{LABEL_STATIC_ENTRY},
3008@code{LABEL_GLOBAL_ENTRY}, and @code{LABEL_WEAK_ENTRY}. The only labels
3009that do not have type @code{LABEL_NORMAL} are @dfn{alternate entry
3010points} to the current function. These may be static (visible only in
3011the containing translation unit), global (exposed to all translation
3012units), or weak (global, but can be overridden by another symbol with the
3013same name).
3015Much of the compiler treats all four kinds of label identically. Some
3016of it needs to know whether or not a label is an alternate entry point;
3017for this purpose, the macro @code{LABEL_ALT_ENTRY_P} is provided. It is
3018equivalent to testing whether @samp{LABEL_KIND (label) == LABEL_NORMAL}.
3019The only place that cares about the distinction between static, global,
3020and weak alternate entry points, besides the front-end code that creates
3021them, is the function @code{output_alternate_entry_point}, in
3024To set the kind of a label, use the @code{SET_LABEL_KIND} macro.
3026@findex barrier
3027@item barrier
3028Barriers are placed in the instruction stream when control cannot flow
3029past them. They are placed after unconditional jump instructions to
3030indicate that the jumps are unconditional and after calls to
3031@code{volatile} functions, which do not return (e.g., @code{exit}).
3032They contain no information beyond the three standard fields.
3034@findex note
3035@findex NOTE_LINE_NUMBER
3036@findex NOTE_SOURCE_FILE
3037@item note
3038@code{note} insns are used to represent additional debugging and
3039declarative information. They contain two nonstandard fields, an
3040integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
3041string accessed with @code{NOTE_SOURCE_FILE}.
3043If @code{NOTE_LINE_NUMBER} is positive, the note represents the
3044position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
3045that the line came from. These notes control generation of line
3046number data in the assembler output.
3048Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
3049code with one of the following values (and @code{NOTE_SOURCE_FILE}
3050must contain a null pointer):
3052@table @code
3055Such a note is completely ignorable. Some passes of the compiler
3056delete insns by altering them into notes of this kind.
3060This marks what used to be a @code{code_label}, but was not used for other
3061purposes than taking its address and was transformed to mark that no
3062code jumps to it.
3068These types of notes indicate the position of the beginning and end
3069of a level of scoping of variable names. They control the output
3070of debugging information.
3076These types of notes indicate the position of the beginning and end of a
3077level of scoping for exception handling. @code{NOTE_BLOCK_NUMBER}
3078identifies which @code{CODE_LABEL} or @code{note} of type
3079@code{NOTE_INSN_DELETED_LABEL} is associated with the given region.
3081@findex NOTE_INSN_LOOP_BEG
3082@findex NOTE_INSN_LOOP_END
3085These types of notes indicate the position of the beginning and end
3086of a @code{while} or @code{for} loop. They enable the loop optimizer
3087to find loops quickly.
3091Appears at the place in a loop that @code{continue} statements jump to.
3095This note indicates the place in a loop where the exit test begins for
3096those loops in which the exit test has been duplicated. This position
3097becomes another virtual start of the loop when considering loop
3102Appears near the end of the function body, just before the label that
3103@code{return} statements jump to (on machine where a single instruction
3104does not suffice for returning). This note may be deleted by jump
3107@findex NOTE_INSN_SETJMP
3109Appears following each call to @code{setjmp} or a related function.
3110@end table
3112These codes are printed symbolically when they appear in debugging dumps.
3113@end table
3115@cindex @code{TImode}, in @code{insn}
3116@cindex @code{HImode}, in @code{insn}
3117@cindex @code{QImode}, in @code{insn}
3118The machine mode of an insn is normally @code{VOIDmode}, but some
3119phases use the mode for various purposes.
3121The common subexpression elimination pass sets the mode of an insn to
3122@code{QImode} when it is the first insn in a block that has already
3123been processed.
3125The second Haifa scheduling pass, for targets that can multiple issue,
3126sets the mode of an insn to @code{TImode} when it is believed that the
3127instruction begins an issue group. That is, when the instruction
3128cannot issue simultaneously with the previous. This may be relied on
3129by later passes, in particular machine-dependent reorg.
3131Here is a table of the extra fields of @code{insn}, @code{jump_insn}
3132and @code{call_insn} insns:
3134@table @code
3135@findex PATTERN
3136@item PATTERN (@var{i})
3137An expression for the side effect performed by this insn. This must be
3138one of the following codes: @code{set}, @code{call}, @code{use},
3139@code{clobber}, @code{return}, @code{asm_input}, @code{asm_output},
3140@code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec},
3141@code{unspec_volatile}, @code{parallel}, @code{cond_exec}, or @code{sequence}. If it is a @code{parallel},
3142each element of the @code{parallel} must be one these codes, except that
3143@code{parallel} expressions cannot be nested and @code{addr_vec} and
3144@code{addr_diff_vec} are not permitted inside a @code{parallel} expression.
3146@findex INSN_CODE
3147@item INSN_CODE (@var{i})
3148An integer that says which pattern in the machine description matches
3149this insn, or @minus{}1 if the matching has not yet been attempted.
3151Such matching is never attempted and this field remains @minus{}1 on an insn
3152whose pattern consists of a single @code{use}, @code{clobber},
3153@code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.
3155@findex asm_noperands
3156Matching is also never attempted on insns that result from an @code{asm}
3157statement. These contain at least one @code{asm_operands} expression.
3158The function @code{asm_noperands} returns a non-negative value for
3159such insns.
3161In the debugging output, this field is printed as a number followed by
3162a symbolic representation that locates the pattern in the @file{md}
3163file as some small positive or negative offset from a named pattern.
3165@findex LOG_LINKS
3166@item LOG_LINKS (@var{i})
3167A list (chain of @code{insn_list} expressions) giving information about
3168dependencies between instructions within a basic block. Neither a jump
3169nor a label may come between the related insns.
3171@findex REG_NOTES
3172@item REG_NOTES (@var{i})
3173A list (chain of @code{expr_list} and @code{insn_list} expressions)
3174giving miscellaneous information about the insn. It is often
3175information pertaining to the registers used in this insn.
3176@end table
3178The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
3179expressions. Each of these has two operands: the first is an insn,
3180and the second is another @code{insn_list} expression (the next one in
3181the chain). The last @code{insn_list} in the chain has a null pointer
3182as second operand. The significant thing about the chain is which
3183insns appear in it (as first operands of @code{insn_list}
3184expressions). Their order is not significant.
3186This list is originally set up by the flow analysis pass; it is a null
3187pointer until then. Flow only adds links for those data dependencies
3188which can be used for instruction combination. For each insn, the flow
3189analysis pass adds a link to insns which store into registers values
3190that are used for the first time in this insn. The instruction
3191scheduling pass adds extra links so that every dependence will be
3192represented. Links represent data dependencies, antidependencies and
3193output dependencies; the machine mode of the link distinguishes these
3194three types: antidependencies have mode @code{REG_DEP_ANTI}, output
3195dependencies have mode @code{REG_DEP_OUTPUT}, and data dependencies have
3196mode @code{VOIDmode}.
3198The @code{REG_NOTES} field of an insn is a chain similar to the
3199@code{LOG_LINKS} field but it includes @code{expr_list} expressions in
3200addition to @code{insn_list} expressions. There are several kinds of
3201register notes, which are distinguished by the machine mode, which in a
3202register note is really understood as being an @code{enum reg_note}.
3203The first operand @var{op} of the note is data whose meaning depends on
3204the kind of note.
3206@findex REG_NOTE_KIND
3207@findex PUT_REG_NOTE_KIND
3208The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of
3209register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND
3210(@var{x}, @var{newkind})} sets the register note type of @var{x} to be
3213Register notes are of three classes: They may say something about an
3214input to an insn, they may say something about an output of an insn, or
3215they may create a linkage between two insns. There are also a set
3216of values that are only used in @code{LOG_LINKS}.
3218These register notes annotate inputs to an insn:
3220@table @code
3221@findex REG_DEAD
3222@item REG_DEAD
3223The value in @var{op} dies in this insn; that is to say, altering the
3224value immediately after this insn would not affect the future behavior
3225of the program.
3227It does not follow that the register @var{op} has no useful value after
3228this insn since @var{op} is not necessarily modified by this insn.
3229Rather, no subsequent instruction uses the contents of @var{op}.
3231@findex REG_UNUSED
3232@item REG_UNUSED
3233The register @var{op} being set by this insn will not be used in a
3234subsequent insn. This differs from a @code{REG_DEAD} note, which
3235indicates that the value in an input will not be used subsequently.
3236These two notes are independent; both may be present for the same
3239@findex REG_INC
3240@item REG_INC
3241The register @var{op} is incremented (or decremented; at this level
3242there is no distinction) by an embedded side effect inside this insn.
3243This means it appears in a @code{post_inc}, @code{pre_inc},
3244@code{post_dec} or @code{pre_dec} expression.
3246@findex REG_NONNEG
3247@item REG_NONNEG
3248The register @var{op} is known to have a nonnegative value when this
3249insn is reached. This is used so that decrement and branch until zero
3250instructions, such as the m68k dbra, can be matched.
3252The @code{REG_NONNEG} note is added to insns only if the machine
3253description has a @samp{decrement_and_branch_until_zero} pattern.
3255@findex REG_NO_CONFLICT
3257This insn does not cause a conflict between @var{op} and the item
3258being set by this insn even though it might appear that it does.
3259In other words, if the destination register and @var{op} could
3260otherwise be assigned the same register, this insn does not
3261prevent that assignment.
3263Insns with this note are usually part of a block that begins with a
3264@code{clobber} insn specifying a multi-word pseudo register (which will
3265be the output of the block), a group of insns that each set one word of
3266the value and have the @code{REG_NO_CONFLICT} note attached, and a final
3267insn that copies the output to itself with an attached @code{REG_EQUAL}
3268note giving the expression being computed. This block is encapsulated
3269with @code{REG_LIBCALL} and @code{REG_RETVAL} notes on the first and
3270last insns, respectively.
3272@findex REG_LABEL
3273@item REG_LABEL
3274This insn uses @var{op}, a @code{code_label} or a @code{note} of type
3275@code{NOTE_INSN_DELETED_LABEL}, but is not a
3276@code{jump_insn}, or it is a @code{jump_insn} that required the label to
3277be held in a register. The presence of this note allows jump
3278optimization to be aware that @var{op} is, in fact, being used, and flow
3279optimization to build an accurate flow graph.
3280@end table
3282The following notes describe attributes of outputs of an insn:
3284@table @code
3285@findex REG_EQUIV
3286@findex REG_EQUAL
3287@item REG_EQUIV
3288@itemx REG_EQUAL
3289This note is only valid on an insn that sets only one register and
3290indicates that that register will be equal to @var{op} at run time; the
3291scope of this equivalence differs between the two types of notes. The
3292value which the insn explicitly copies into the register may look
3293different from @var{op}, but they will be equal at run time. If the
3294output of the single @code{set} is a @code{strict_low_part} expression,
3295the note refers to the register that is contained in @code{SUBREG_REG}
3296of the @code{subreg} expression.
3298For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout
3299the entire function, and could validly be replaced in all its
3300occurrences by @var{op}. (``Validly'' here refers to the data flow of
3301the program; simple replacement may make some insns invalid.) For
3302example, when a constant is loaded into a register that is never
3303assigned any other value, this kind of note is used.
3305When a parameter is copied into a pseudo-register at entry to a function,
3306a note of this kind records that the register is equivalent to the stack
3307slot where the parameter was passed. Although in this case the register
3308may be set by other insns, it is still valid to replace the register
3309by the stack slot throughout the function.
3311A @code{REG_EQUIV} note is also used on an instruction which copies a
3312register parameter into a pseudo-register at entry to a function, if
3313there is a stack slot where that parameter could be stored. Although
3314other insns may set the pseudo-register, it is valid for the compiler to
3315replace the pseudo-register by stack slot throughout the function,
3316provided the compiler ensures that the stack slot is properly
3317initialized by making the replacement in the initial copy instruction as
3318well. This is used on machines for which the calling convention
3319allocates stack space for register parameters. See
3320@code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}.
3322In the case of @code{REG_EQUAL}, the register that is set by this insn
3323will be equal to @var{op} at run time at the end of this insn but not
3324necessarily elsewhere in the function. In this case, @var{op}
3325is typically an arithmetic expression. For example, when a sequence of
3326insns such as a library call is used to perform an arithmetic operation,
3327this kind of note is attached to the insn that produces or copies the
3328final value.
3330These two notes are used in different ways by the compiler passes.
3331@code{REG_EQUAL} is used by passes prior to register allocation (such as
3332common subexpression elimination and loop optimization) to tell them how
3333to think of that value. @code{REG_EQUIV} notes are used by register
3334allocation to indicate that there is an available substitute expression
3335(either a constant or a @code{mem} expression for the location of a
3336parameter on the stack) that may be used in place of a register if
3337insufficient registers are available.
3339Except for stack homes for parameters, which are indicated by a
3340@code{REG_EQUIV} note and are not useful to the early optimization
3341passes and pseudo registers that are equivalent to a memory location
3342throughout their entire life, which is not detected until later in
3343the compilation, all equivalences are initially indicated by an attached
3344@code{REG_EQUAL} note. In the early stages of register allocation, a
3345@code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if
3346@var{op} is a constant and the insn represents the only set of its
3347destination register.
3349Thus, compiler passes prior to register allocation need only check for
3350@code{REG_EQUAL} notes and passes subsequent to register allocation
3351need only check for @code{REG_EQUIV} notes.
3352@end table
3354These notes describe linkages between insns. They occur in pairs: one
3355insn has one of a pair of notes that points to a second insn, which has
3356the inverse note pointing back to the first insn.
3358@table @code
3359@findex REG_RETVAL
3360@item REG_RETVAL
3361This insn copies the value of a multi-insn sequence (for example, a
3362library call), and @var{op} is the first insn of the sequence (for a
3363library call, the first insn that was generated to set up the arguments
3364for the library call).
3366Loop optimization uses this note to treat such a sequence as a single
3367operation for code motion purposes and flow analysis uses this note to
3368delete such sequences whose results are dead.
3370A @code{REG_EQUAL} note will also usually be attached to this insn to
3371provide the expression being computed by the sequence.
3373These notes will be deleted after reload, since they are no longer
3374accurate or useful.
3376@findex REG_LIBCALL
3377@item REG_LIBCALL
3378This is the inverse of @code{REG_RETVAL}: it is placed on the first
3379insn of a multi-insn sequence, and it points to the last one.
3381These notes are deleted after reload, since they are no longer useful or
3384@findex REG_CC_SETTER
3385@findex REG_CC_USER
3386@item REG_CC_SETTER
3387@itemx REG_CC_USER
3388On machines that use @code{cc0}, the insns which set and use @code{cc0}
3389set and use @code{cc0} are adjacent. However, when branch delay slot
3390filling is done, this may no longer be true. In this case a
3391@code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to
3392point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will
3393be placed on the insn using @code{cc0} to point to the insn setting
3395@end table
3397These values are only used in the @code{LOG_LINKS} field, and indicate
3398the type of dependency that each link represents. Links which indicate
3399a data dependence (a read after write dependence) do not use any code,
3400they simply have mode @code{VOIDmode}, and are printed without any
3401descriptive text.
3403@table @code
3404@findex REG_DEP_ANTI
3405@item REG_DEP_ANTI
3406This indicates an anti dependence (a write after read dependence).
3408@findex REG_DEP_OUTPUT
3409@item REG_DEP_OUTPUT
3410This indicates an output dependence (a write after write dependence).
3411@end table
3413These notes describe information gathered from gcov profile data. They
3414are stored in the @code{REG_NOTES} field of an insn as an
3417@table @code
3418@findex REG_BR_PROB
3419@item REG_BR_PROB
3420This is used to specify the ratio of branches to non-branches of a
3421branch insn according to the profile data. The value is stored as a
3422value between 0 and REG_BR_PROB_BASE; larger values indicate a higher
3423probability that the branch will be taken.
3425@findex REG_BR_PRED
3426@item REG_BR_PRED
3427These notes are found in JUMP insns after delayed branch scheduling
3428has taken place. They indicate both the direction and the likelihood
3429of the JUMP@. The format is a bitmask of ATTR_FLAG_* values.
3433This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression
3434is used in place of the actual insn pattern. This is done in cases where
3435the pattern is either complex or misleading.
3436@end table
3438For convenience, the machine mode in an @code{insn_list} or
3439@code{expr_list} is printed using these symbolic codes in debugging dumps.
3441@findex insn_list
3442@findex expr_list
3443The only difference between the expression codes @code{insn_list} and
3444@code{expr_list} is that the first operand of an @code{insn_list} is
3445assumed to be an insn and is printed in debugging dumps as the insn's
3446unique id; the first operand of an @code{expr_list} is printed in the
3447ordinary way as an expression.
3449@node Calls
3450@section RTL Representation of Function-Call Insns
3451@cindex calling functions in RTL
3452@cindex RTL function-call insns
3453@cindex function-call insns
3455Insns that call subroutines have the RTL expression code @code{call_insn}.
3456These insns must satisfy special rules, and their bodies must use a special
3457RTL expression code, @code{call}.
3459@cindex @code{call} usage
3460A @code{call} expression has two operands, as follows:
3463(call (mem:@var{fm} @var{addr}) @var{nbytes})
3464@end smallexample
3467Here @var{nbytes} is an operand that represents the number of bytes of
3468argument data being passed to the subroutine, @var{fm} is a machine mode
3469(which must equal as the definition of the @code{FUNCTION_MODE} macro in
3470the machine description) and @var{addr} represents the address of the
3473For a subroutine that returns no value, the @code{call} expression as
3474shown above is the entire body of the insn, except that the insn might
3475also contain @code{use} or @code{clobber} expressions.
3477@cindex @code{BLKmode}, and function return values
3478For a subroutine that returns a value whose mode is not @code{BLKmode},
3479the value is returned in a hard register. If this register's number is
3480@var{r}, then the body of the call insn looks like this:
3483(set (reg:@var{m} @var{r})
3484 (call (mem:@var{fm} @var{addr}) @var{nbytes}))
3485@end smallexample
3488This RTL expression makes it clear (to the optimizer passes) that the
3489appropriate register receives a useful value in this insn.
3491When a subroutine returns a @code{BLKmode} value, it is handled by
3492passing to the subroutine the address of a place to store the value.
3493So the call insn itself does not ``return'' any value, and it has the
3494same RTL form as a call that returns nothing.
3496On some machines, the call instruction itself clobbers some register,
3497for example to contain the return address. @code{call_insn} insns
3498on these machines should have a body which is a @code{parallel}
3499that contains both the @code{call} expression and @code{clobber}
3500expressions that indicate which registers are destroyed. Similarly,
3501if the call instruction requires some register other than the stack
3502pointer that is not explicitly mentioned it its RTL, a @code{use}
3503subexpression should mention that register.
3505Functions that are called are assumed to modify all registers listed in
3506the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register
3507Basics}) and, with the exception of @code{const} functions and library
3508calls, to modify all of memory.
3510Insns containing just @code{use} expressions directly precede the
3511@code{call_insn} insn to indicate which registers contain inputs to the
3512function. Similarly, if registers other than those in
3513@code{CALL_USED_REGISTERS} are clobbered by the called function, insns
3514containing a single @code{clobber} follow immediately after the call to
3515indicate which registers.
3517@node Sharing
3518@section Structure Sharing Assumptions
3519@cindex sharing of RTL components
3520@cindex RTL structure sharing assumptions
3522The compiler assumes that certain kinds of RTL expressions are unique;
3523there do not exist two distinct objects representing the same value.
3524In other cases, it makes an opposite assumption: that no RTL expression
3525object of a certain kind appears in more than one place in the
3526containing structure.
3528These assumptions refer to a single function; except for the RTL
3529objects that describe global variables and external functions,
3530and a few standard objects such as small integer constants,
3531no RTL objects are common to two functions.
3533@itemize @bullet
3534@cindex @code{reg}, RTL sharing
3536Each pseudo-register has only a single @code{reg} object to represent it,
3537and therefore only a single machine mode.
3539@cindex symbolic label
3540@cindex @code{symbol_ref}, RTL sharing
3542For any symbolic label, there is only one @code{symbol_ref} object
3543referring to it.
3545@cindex @code{const_int}, RTL sharing
3547All @code{const_int} expressions with equal values are shared.
3549@cindex @code{pc}, RTL sharing
3551There is only one @code{pc} expression.
3553@cindex @code{cc0}, RTL sharing
3555There is only one @code{cc0} expression.
3557@cindex @code{const_double}, RTL sharing
3559There is only one @code{const_double} expression with value 0 for
3560each floating point mode. Likewise for values 1 and 2.
3562@cindex @code{const_vector}, RTL sharing
3564There is only one @code{const_vector} expression with value 0 for
3565each vector mode, be it an integer or a double constant vector.
3567@cindex @code{label_ref}, RTL sharing
3568@cindex @code{scratch}, RTL sharing
3570No @code{label_ref} or @code{scratch} appears in more than one place in
3571the RTL structure; in other words, it is safe to do a tree-walk of all
3572the insns in the function and assume that each time a @code{label_ref}
3573or @code{scratch} is seen it is distinct from all others that are seen.
3575@cindex @code{mem}, RTL sharing
3577Only one @code{mem} object is normally created for each static
3578variable or stack slot, so these objects are frequently shared in all
3579the places they appear. However, separate but equal objects for these
3580variables are occasionally made.
3582@cindex @code{asm_operands}, RTL sharing
3584When a single @code{asm} statement has multiple output operands, a
3585distinct @code{asm_operands} expression is made for each output operand.
3586However, these all share the vector which contains the sequence of input
3587operands. This sharing is used later on to test whether two
3588@code{asm_operands} expressions come from the same statement, so all
3589optimizations must carefully preserve the sharing if they copy the
3590vector at all.
3593No RTL object appears in more than one place in the RTL structure
3594except as described above. Many passes of the compiler rely on this
3595by assuming that they can modify RTL objects in place without unwanted
3596side-effects on other insns.
3598@findex unshare_all_rtl
3600During initial RTL generation, shared structure is freely introduced.
3601After all the RTL for a function has been generated, all shared
3602structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
3603after which the above rules are guaranteed to be followed.
3605@findex copy_rtx_if_shared
3607During the combiner pass, shared structure within an insn can exist
3608temporarily. However, the shared structure is copied before the
3609combiner is finished with the insn. This is done by calling
3610@code{copy_rtx_if_shared}, which is a subroutine of
3612@end itemize
3614@node Reading RTL
3615@section Reading RTL
3617To read an RTL object from a file, call @code{read_rtx}. It takes one
3618argument, a stdio stream, and returns a single RTL object. This routine
3619is defined in @file{read-rtl.c}. It is not available in the compiler
3620itself, only the various programs that generate the compiler back end
3621from the machine description.
3623People frequently have the idea of using RTL stored as text in a file as
3624an interface between a language front end and the bulk of GCC@. This
3625idea is not feasible.
3627GCC was designed to use RTL internally only. Correct RTL for a given
3628program is very dependent on the particular target machine. And the RTL
3629does not contain all the information about the program.
3631The proper way to interface GCC to a new language front end is with
3632the ``tree'' data structure, described in the files @file{tree.h} and
3633@file{tree.def}. The documentation for this structure (@pxref{Trees})
3634is incomplete.