diff options
Diffstat (limited to 'gnu/usr.bin/cc/doc/rtl.texi')
| -rw-r--r-- | gnu/usr.bin/cc/doc/rtl.texi | 2800 |
1 files changed, 0 insertions, 2800 deletions
diff --git a/gnu/usr.bin/cc/doc/rtl.texi b/gnu/usr.bin/cc/doc/rtl.texi deleted file mode 100644 index 6da63f2..0000000 --- a/gnu/usr.bin/cc/doc/rtl.texi +++ /dev/null @@ -1,2800 +0,0 @@ -@c Copyright (C) 1988, 1989, 1992, 1994 Free Software Foundation, Inc. -@c This is part of the GCC manual. -@c For copying conditions, see the file gcc.texi. - -@node RTL -@chapter RTL Representation -@cindex RTL representation -@cindex representation of RTL -@cindex Register Transfer Language (RTL) - -Most of the work of the compiler is done on an intermediate representation -called register transfer language. In this language, the instructions to be -output are described, pretty much one by one, in an algebraic form that -describes what the instruction does. - -RTL is inspired by Lisp lists. It has both an internal form, made up of -structures that point at other structures, and a textual form that is used -in the machine description and in printed debugging dumps. The textual -form uses nested parentheses to indicate the pointers in the internal form. - -@menu -* RTL Objects:: Expressions vs vectors vs strings vs integers. -* Accessors:: Macros to access expression operands or vector elts. -* Flags:: Other flags in an RTL expression. -* Machine Modes:: Describing the size and format of a datum. -* Constants:: Expressions with constant values. -* Regs and Memory:: Expressions representing register contents or memory. -* Arithmetic:: Expressions representing arithmetic on other expressions. -* Comparisons:: Expressions representing comparison of expressions. -* Bit Fields:: Expressions representing bitfields in memory or reg. -* Conversions:: Extending, truncating, floating or fixing. -* RTL Declarations:: Declaring volatility, constancy, etc. -* Side Effects:: Expressions for storing in registers, etc. -* Incdec:: Embedded side-effects for autoincrement addressing. -* Assembler:: Representing @code{asm} with operands. -* Insns:: Expression types for entire insns. -* Calls:: RTL representation of function call insns. -* Sharing:: Some expressions are unique; others *must* be copied. -* Reading RTL:: Reading textual RTL from a file. -@end menu - -@node RTL Objects, Accessors, RTL, RTL -@section RTL Object Types -@cindex RTL object types - -@cindex RTL integers -@cindex RTL strings -@cindex RTL vectors -@cindex RTL expression -@cindex RTX (See RTL) -RTL uses five kinds of objects: expressions, integers, wide integers, -strings and vectors. Expressions are the most important ones. An RTL -expression (``RTX'', for short) is a C structure, but it is usually -referred to with a pointer; a type that is given the typedef name -@code{rtx}. - -An integer is simply an @code{int}; their written form uses decimal digits. -A wide integer is an integral object whose type is @code{HOST_WIDE_INT} -(@pxref{Config}); their written form uses decimal digits. - -A string is a sequence of characters. In core it is represented as a -@code{char *} in usual C fashion, and it is written in C syntax as well. -However, strings in RTL may never be null. If you write an empty string in -a machine description, it is represented in core as a null pointer rather -than as a pointer to a null character. In certain contexts, these null -pointers instead of strings are valid. Within RTL code, strings are most -commonly found inside @code{symbol_ref} expressions, but they appear in -other contexts in the RTL expressions that make up machine descriptions. - -A vector contains an arbitrary number of pointers to expressions. The -number of elements in the vector is explicitly present in the vector. -The written form of a vector consists of square brackets -(@samp{[@dots{}]}) surrounding the elements, in sequence and with -whitespace separating them. Vectors of length zero are not created; -null pointers are used instead. - -@cindex expression codes -@cindex codes, RTL expression -@findex GET_CODE -@findex PUT_CODE -Expressions are classified by @dfn{expression codes} (also called RTX -codes). The expression code is a name defined in @file{rtl.def}, which is -also (in upper case) a C enumeration constant. The possible expression -codes and their meanings are machine-independent. The code of an RTX can -be extracted with the macro @code{GET_CODE (@var{x})} and altered with -@code{PUT_CODE (@var{x}, @var{newcode})}. - -The expression code determines how many operands the expression contains, -and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell -by looking at an operand what kind of object it is. Instead, you must know -from its context---from the expression code of the containing expression. -For example, in an expression of code @code{subreg}, the first operand is -to be regarded as an expression and the second operand as an integer. In -an expression of code @code{plus}, there are two operands, both of which -are to be regarded as expressions. In a @code{symbol_ref} expression, -there is one operand, which is to be regarded as a string. - -Expressions are written as parentheses containing the name of the -expression type, its flags and machine mode if any, and then the operands -of the expression (separated by spaces). - -Expression code names in the @samp{md} file are written in lower case, -but when they appear in C code they are written in upper case. In this -manual, they are shown as follows: @code{const_int}. - -@cindex (nil) -@cindex nil -In a few contexts a null pointer is valid where an expression is normally -wanted. The written form of this is @code{(nil)}. - -@node Accessors, Flags, RTL Objects, RTL -@section Access to Operands -@cindex accessors -@cindex access to operands -@cindex operand access - -@cindex RTL format -For each expression type @file{rtl.def} specifies the number of -contained objects and their kinds, with four possibilities: @samp{e} for -expression (actually a pointer to an expression), @samp{i} for integer, -@samp{w} for wide integer, @samp{s} for string, and @samp{E} for vector -of expressions. The sequence of letters for an expression code is -called its @dfn{format}. Thus, the format of @code{subreg} is -@samp{ei}.@refill - -@cindex RTL format characters -A few other format characters are used occasionally: - -@table @code -@item u -@samp{u} is equivalent to @samp{e} except that it is printed differently -in debugging dumps. It is used for pointers to insns. - -@item n -@samp{n} is equivalent to @samp{i} except that it is printed differently -in debugging dumps. It is used for the line number or code number of a -@code{note} insn. - -@item S -@samp{S} indicates a string which is optional. In the RTL objects in -core, @samp{S} is equivalent to @samp{s}, but when the object is read, -from an @samp{md} file, the string value of this operand may be omitted. -An omitted string is taken to be the null string. - -@item V -@samp{V} indicates a vector which is optional. In the RTL objects in -core, @samp{V} is equivalent to @samp{E}, but when the object is read -from an @samp{md} file, the vector value of this operand may be omitted. -An omitted vector is effectively the same as a vector of no elements. - -@item 0 -@samp{0} means a slot whose contents do not fit any normal category. -@samp{0} slots are not printed at all in dumps, and are often used in -special ways by small parts of the compiler. -@end table - -There are macros to get the number of operands, the format, and the -class of an expression code: - -@table @code -@findex GET_RTX_LENGTH -@item GET_RTX_LENGTH (@var{code}) -Number of operands of an RTX of code @var{code}. - -@findex GET_RTX_FORMAT -@item GET_RTX_FORMAT (@var{code}) -The format of an RTX of code @var{code}, as a C string. - -@findex GET_RTX_CLASS -@cindex classes of RTX codes -@item GET_RTX_CLASS (@var{code}) -A single character representing the type of RTX operation that code -@var{code} performs. - -The following classes are defined: - -@table @code -@item o -An RTX code that represents an actual object, such as @code{reg} or -@code{mem}. @code{subreg} is not in this class. - -@item < -An RTX code for a comparison. The codes in this class are -@code{NE}, @code{EQ}, @code{LE}, @code{LT}, @code{GE}, @code{GT}, -@code{LEU}, @code{LTU}, @code{GEU}, @code{GTU}.@refill - -@item 1 -An RTX code for a unary arithmetic operation, such as @code{neg}. - -@item c -An RTX code for a commutative binary operation, other than @code{NE} -and @code{EQ} (which have class @samp{<}). - -@item 2 -An RTX code for a noncommutative binary operation, such as @code{MINUS}. - -@item b -An RTX code for a bitfield operation, either @code{ZERO_EXTRACT} or -@code{SIGN_EXTRACT}. - -@item 3 -An RTX code for other three input operations, such as @code{IF_THEN_ELSE}. - -@item i -An RTX code for a machine insn (@code{INSN}, @code{JUMP_INSN}, and -@code{CALL_INSN}).@refill - -@item m -An RTX code for something that matches in insns, such as @code{MATCH_DUP}. - -@item x -All other RTX codes. -@end table -@end table - -@findex XEXP -@findex XINT -@findex XWINT -@findex XSTR -Operands of expressions are accessed using the macros @code{XEXP}, -@code{XINT}, @code{XWINT} and @code{XSTR}. Each of these macros takes -two arguments: an expression-pointer (RTX) and an operand number -(counting from zero). Thus,@refill - -@example -XEXP (@var{x}, 2) -@end example - -@noindent -accesses operand 2 of expression @var{x}, as an expression. - -@example -XINT (@var{x}, 2) -@end example - -@noindent -accesses the same operand as an integer. @code{XSTR}, used in the same -fashion, would access it as a string. - -Any operand can be accessed as an integer, as an expression or as a string. -You must choose the correct method of access for the kind of value actually -stored in the operand. You would do this based on the expression code of -the containing expression. That is also how you would know how many -operands there are. - -For example, if @var{x} is a @code{subreg} expression, you know that it has -two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)} -and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you -would get the address of the expression operand but cast as an integer; -that might occasionally be useful, but it would be cleaner to write -@code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also -compile without error, and would return the second, integer operand cast as -an expression pointer, which would probably result in a crash when -accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either, -but this will access memory past the end of the expression with -unpredictable results.@refill - -Access to operands which are vectors is more complicated. You can use the -macro @code{XVEC} to get the vector-pointer itself, or the macros -@code{XVECEXP} and @code{XVECLEN} to access the elements and length of a -vector. - -@table @code -@findex XVEC -@item XVEC (@var{exp}, @var{idx}) -Access the vector-pointer which is operand number @var{idx} in @var{exp}. - -@findex XVECLEN -@item XVECLEN (@var{exp}, @var{idx}) -Access the length (number of elements) in the vector which is -in operand number @var{idx} in @var{exp}. This value is an @code{int}. - -@findex XVECEXP -@item XVECEXP (@var{exp}, @var{idx}, @var{eltnum}) -Access element number @var{eltnum} in the vector which is -in operand number @var{idx} in @var{exp}. This value is an RTX. - -It is up to you to make sure that @var{eltnum} is not negative -and is less than @code{XVECLEN (@var{exp}, @var{idx})}. -@end table - -All the macros defined in this section expand into lvalues and therefore -can be used to assign the operands, lengths and vector elements as well as -to access them. - -@node Flags, Machine Modes, Accessors, RTL -@section Flags in an RTL Expression -@cindex flags in RTL expression - -RTL expressions contain several flags (one-bit bitfields) that are used -in certain types of expression. Most often they are accessed with the -following macros: - -@table @code -@findex MEM_VOLATILE_P -@cindex @code{mem} and @samp{/v} -@cindex @code{volatil}, in @code{mem} -@cindex @samp{/v} in RTL dump -@item MEM_VOLATILE_P (@var{x}) -In @code{mem} expressions, nonzero for volatile memory references. -Stored in the @code{volatil} field and printed as @samp{/v}. - -@findex MEM_IN_STRUCT_P -@cindex @code{mem} and @samp{/s} -@cindex @code{in_struct}, in @code{mem} -@cindex @samp{/s} in RTL dump -@item MEM_IN_STRUCT_P (@var{x}) -In @code{mem} expressions, nonzero for reference to an entire -structure, union or array, or to a component of one. Zero for -references to a scalar variable or through a pointer to a scalar. -Stored in the @code{in_struct} field and printed as @samp{/s}. - -@findex REG_LOOP_TEST_P -@cindex @code{reg} and @samp{/s} -@cindex @code{in_struct}, in @code{reg} -@item REG_LOOP_TEST_P -In @code{reg} expressions, nonzero if this register's entire life is -contained in the exit test code for some loop. Stored in the -@code{in_struct} field and printed as @samp{/s}. - -@findex REG_USERVAR_P -@cindex @code{reg} and @samp{/v} -@cindex @code{volatil}, in @code{reg} -@item REG_USERVAR_P (@var{x}) -In a @code{reg}, nonzero if it corresponds to a variable present in -the user's source code. Zero for temporaries generated internally by -the compiler. Stored in the @code{volatil} field and printed as -@samp{/v}. - -@cindex @samp{/i} in RTL dump -@findex REG_FUNCTION_VALUE_P -@cindex @code{reg} and @samp{/i} -@cindex @code{integrated}, in @code{reg} -@item REG_FUNCTION_VALUE_P (@var{x}) -Nonzero in a @code{reg} if it is the place in which this function's -value is going to be returned. (This happens only in a hard -register.) Stored in the @code{integrated} field and printed as -@samp{/i}. - -The same hard register may be used also for collecting the values of -functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero -in this kind of use. - -@findex SUBREG_PROMOTED_VAR_P -@cindex @code{subreg} and @samp{/s} -@cindex @code{in_struct}, in @code{subreg} -@item SUBREG_PROMOTED_VAR_P -Nonzero in a @code{subreg} if it was made when accessing an object that -was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine -description macro (@pxref{Storage Layout}). In this case, the mode of -the @code{subreg} is the declared mode of the object and the mode of -@code{SUBREG_REG} is the mode of the register that holds the object. -Promoted variables are always either sign- or zero-extended to the wider -mode on every assignment. Stored in the @code{in_struct} field and -printed as @samp{/s}. - -@findex SUBREG_PROMOTED_UNSIGNED_P -@cindex @code{subreg} and @samp{/u} -@cindex @code{unchanging}, in @code{subreg} -@item SUBREG_PROMOTED_UNSIGNED_P -Nonzero in a @code{subreg} that has @code{SUBREG_PROMOTED_VAR_P} nonzero -if the object being referenced is kept zero-extended and zero if it -is kept sign-extended. Stored in the @code{unchanging} field and -printed as @samp{/u}. - -@findex RTX_UNCHANGING_P -@cindex @code{reg} and @samp{/u} -@cindex @code{mem} and @samp{/u} -@cindex @code{unchanging}, in @code{reg} and @code{mem} -@cindex @samp{/u} in RTL dump -@item RTX_UNCHANGING_P (@var{x}) -Nonzero in a @code{reg} or @code{mem} if the value is not changed. -(This flag is not set for memory references via pointers to constants. -Such pointers only guarantee that the object will not be changed -explicitly by the current function. The object might be changed by -other functions or by aliasing.) Stored in the -@code{unchanging} field and printed as @samp{/u}. - -@findex RTX_INTEGRATED_P -@cindex @code{integrated}, in @code{insn} -@item RTX_INTEGRATED_P (@var{insn}) -Nonzero in an insn if it resulted from an in-line function call. -Stored in the @code{integrated} field and printed as @samp{/i}. This -may be deleted; nothing currently depends on it. - -@findex SYMBOL_REF_USED -@cindex @code{used}, in @code{symbol_ref} -@item SYMBOL_REF_USED (@var{x}) -In a @code{symbol_ref}, indicates that @var{x} has been used. This is -normally only used to ensure that @var{x} is only declared external -once. Stored in the @code{used} field. - -@findex SYMBOL_REF_FLAG -@cindex @code{symbol_ref} and @samp{/v} -@cindex @code{volatil}, in @code{symbol_ref} -@item SYMBOL_REF_FLAG (@var{x}) -In a @code{symbol_ref}, this is used as a flag for machine-specific purposes. -Stored in the @code{volatil} field and printed as @samp{/v}. - -@findex LABEL_OUTSIDE_LOOP_P -@cindex @code{label_ref} and @samp{/s} -@cindex @code{in_struct}, in @code{label_ref} -@item LABEL_OUTSIDE_LOOP_P -In @code{label_ref} expressions, nonzero if this is a reference to a -label that is outside the innermost loop containing the reference to the -label. Stored in the @code{in_struct} field and printed as @samp{/s}. - -@findex INSN_DELETED_P -@cindex @code{volatil}, in @code{insn} -@item INSN_DELETED_P (@var{insn}) -In an insn, nonzero if the insn has been deleted. Stored in the -@code{volatil} field and printed as @samp{/v}. - -@findex INSN_ANNULLED_BRANCH_P -@cindex @code{insn} and @samp{/u} -@cindex @code{unchanging}, in @code{insn} -@item INSN_ANNULLED_BRANCH_P (@var{insn}) -In an @code{insn} in the delay slot of a branch insn, indicates that an -annulling branch should be used. See the discussion under -@code{sequence} below. Stored in the @code{unchanging} field and printed -as @samp{/u}. - -@findex INSN_FROM_TARGET_P -@cindex @code{insn} and @samp{/s} -@cindex @code{in_struct}, in @code{insn} -@cindex @samp{/s} in RTL dump -@item INSN_FROM_TARGET_P (@var{insn}) -In an @code{insn} in a delay slot of a branch, indicates that the insn -is from the target of the branch. If the branch insn has -@code{INSN_ANNULLED_BRANCH_P} set, this insn should only be executed if -the branch is taken. For annulled branches with this bit clear, the -insn should be executed only if the branch is not taken. Stored in the -@code{in_struct} field and printed as @samp{/s}. - -@findex CONSTANT_POOL_ADDRESS_P -@cindex @code{symbol_ref} and @samp{/u} -@cindex @code{unchanging}, in @code{symbol_ref} -@item CONSTANT_POOL_ADDRESS_P (@var{x}) -Nonzero in a @code{symbol_ref} if it refers to part of the current -function's ``constants pool''. These are addresses close to the -beginning of the function, and GNU CC assumes they can be addressed -directly (perhaps with the help of base registers). Stored in the -@code{unchanging} field and printed as @samp{/u}. - -@findex CONST_CALL_P -@cindex @code{call_insn} and @samp{/u} -@cindex @code{unchanging}, in @code{call_insn} -@item CONST_CALL_P (@var{x}) -In a @code{call_insn}, indicates that the insn represents a call to a const -function. Stored in the @code{unchanging} field and printed as @samp{/u}. - -@findex LABEL_PRESERVE_P -@cindex @code{code_label} and @samp{/i} -@cindex @code{in_struct}, in @code{code_label} -@item LABEL_PRESERVE_P (@var{x}) -In a @code{code_label}, indicates that the label can never be deleted. -Labels referenced by a non-local goto will have this bit set. Stored -in the @code{in_struct} field and printed as @samp{/s}. - -@findex SCHED_GROUP_P -@cindex @code{insn} and @samp{/i} -@cindex @code{in_struct}, in @code{insn} -@item SCHED_GROUP_P (@var{insn}) -During instruction scheduling, in an insn, indicates that the previous insn -must be scheduled together with this insn. This is used to ensure that -certain groups of instructions will not be split up by the instruction -scheduling pass, for example, @code{use} insns before a @code{call_insn} may -not be separated from the @code{call_insn}. Stored in the @code{in_struct} -field and printed as @samp{/s}. -@end table - -These are the fields which the above macros refer to: - -@table @code -@findex used -@item used -Normally, this flag is used only momentarily, at the end of RTL -generation for a function, to count the number of times an expression -appears in insns. Expressions that appear more than once are copied, -according to the rules for shared structure (@pxref{Sharing}). - -In a @code{symbol_ref}, it indicates that an external declaration for -the symbol has already been written. - -In a @code{reg}, it is used by the leaf register renumbering code to ensure -that each register is only renumbered once. - -@findex volatil -@item volatil -This flag is used in @code{mem}, @code{symbol_ref} and @code{reg} -expressions and in insns. In RTL dump files, it is printed as -@samp{/v}. - -@cindex volatile memory references -In a @code{mem} expression, it is 1 if the memory reference is volatile. -Volatile memory references may not be deleted, reordered or combined. - -In a @code{symbol_ref} expression, it is used for machine-specific -purposes. - -In a @code{reg} expression, it is 1 if the value is a user-level variable. -0 indicates an internal compiler temporary. - -In an insn, 1 means the insn has been deleted. - -@findex in_struct -@item in_struct -In @code{mem} expressions, it is 1 if the memory datum referred to is -all or part of a structure or array; 0 if it is (or might be) a scalar -variable. A reference through a C pointer has 0 because the pointer -might point to a scalar variable. This information allows the compiler -to determine something about possible cases of aliasing. - -In an insn in the delay slot of a branch, 1 means that this insn is from -the target of the branch. - -During instruction scheduling, in an insn, 1 means that this insn must be -scheduled as part of a group together with the previous insn. - -In @code{reg} expressions, it is 1 if the register has its entire life -contained within the test expression of some loop. - -In @code{subreg} expressions, 1 means that the @code{subreg} is accessing -an object that has had its mode promoted from a wider mode. - -In @code{label_ref} expressions, 1 means that the referenced label is -outside the innermost loop containing the insn in which the @code{label_ref} -was found. - -In @code{code_label} expressions, it is 1 if the label may never be deleted. -This is used for labels which are the target of non-local gotos. - -In an RTL dump, this flag is represented as @samp{/s}. - -@findex unchanging -@item unchanging -In @code{reg} and @code{mem} expressions, 1 means -that the value of the expression never changes. - -In @code{subreg} expressions, it is 1 if the @code{subreg} references an -unsigned object whose mode has been promoted to a wider mode. - -In an insn, 1 means that this is an annulling branch. - -In a @code{symbol_ref} expression, 1 means that this symbol addresses -something in the per-function constants pool. - -In a @code{call_insn}, 1 means that this instruction is a call to a -const function. - -In an RTL dump, this flag is represented as @samp{/u}. - -@findex integrated -@item integrated -In some kinds of expressions, including insns, this flag means the -rtl was produced by procedure integration. - -In a @code{reg} expression, this flag indicates the register -containing the value to be returned by the current function. On -machines that pass parameters in registers, the same register number -may be used for parameters as well, but this flag is not set on such -uses. -@end table - -@node Machine Modes, Constants, Flags, RTL -@section Machine Modes -@cindex machine modes - -@findex enum machine_mode -A machine mode describes a size of data object and the representation used -for it. In the C code, machine modes are represented by an enumeration -type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL -expression has room for a machine mode and so do certain kinds of tree -expressions (declarations and types, to be precise). - -In debugging dumps and machine descriptions, the machine mode of an RTL -expression is written after the expression code with a colon to separate -them. The letters @samp{mode} which appear at the end of each machine mode -name are omitted. For example, @code{(reg:SI 38)} is a @code{reg} -expression with machine mode @code{SImode}. If the mode is -@code{VOIDmode}, it is not written at all. - -Here is a table of machine modes. The term ``byte'' below refers to an -object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}). - -@table @code -@findex QImode -@item QImode -``Quarter-Integer'' mode represents a single byte treated as an integer. - -@findex HImode -@item HImode -``Half-Integer'' mode represents a two-byte integer. - -@findex PSImode -@item PSImode -``Partial Single Integer'' mode represents an integer which occupies -four bytes but which doesn't really use all four. On some machines, -this is the right mode to use for pointers. - -@findex SImode -@item SImode -``Single Integer'' mode represents a four-byte integer. - -@findex PDImode -@item PDImode -``Partial Double Integer'' mode represents an integer which occupies -eight bytes but which doesn't really use all eight. On some machines, -this is the right mode to use for certain pointers. - -@findex DImode -@item DImode -``Double Integer'' mode represents an eight-byte integer. - -@findex TImode -@item TImode -``Tetra Integer'' (?) mode represents a sixteen-byte integer. - -@findex SFmode -@item SFmode -``Single Floating'' mode represents a single-precision (four byte) floating -point number. - -@findex DFmode -@item DFmode -``Double Floating'' mode represents a double-precision (eight byte) floating -point number. - -@findex XFmode -@item XFmode -``Extended Floating'' mode represents a triple-precision (twelve byte) -floating point number. This mode is used for IEEE extended floating -point. - -@findex TFmode -@item TFmode -``Tetra Floating'' mode represents a quadruple-precision (sixteen byte) -floating point number. - -@findex CCmode -@item CCmode -``Condition Code'' mode represents the value of a condition code, which -is a machine-specific set of bits used to represent the result of a -comparison operation. Other machine-specific modes may also be used for -the condition code. These modes are not used on machines that use -@code{cc0} (see @pxref{Condition Code}). - -@findex BLKmode -@item BLKmode -``Block'' mode represents values that are aggregates to which none of -the other modes apply. In RTL, only memory references can have this mode, -and only if they appear in string-move or vector instructions. On machines -which have no such instructions, @code{BLKmode} will not appear in RTL. - -@findex VOIDmode -@item VOIDmode -Void mode means the absence of a mode or an unspecified mode. -For example, RTL expressions of code @code{const_int} have mode -@code{VOIDmode} because they can be taken to have whatever mode the context -requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by -the absence of any mode. - -@findex SCmode -@findex DCmode -@findex XCmode -@findex TCmode -@item SCmode, DCmode, XCmode, TCmode -These modes stand for a complex number represented as a pair of floating -point values. The floating point values are in @code{SFmode}, -@code{DFmode}, @code{XFmode}, and @code{TFmode}, respectively. - -@findex CQImode -@findex CHImode -@findex CSImode -@findex CDImode -@findex CTImode -@findex COImode -@item CQImode, CHImode, CSImode, CDImode, CTImode, COImode -These modes stand for a complex number represented as a pair of integer -values. The integer values are in @code{QImode}, @code{HImode}, -@code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode}, -respectively. -@end table - -The machine description defines @code{Pmode} as a C macro which expands -into the machine mode used for addresses. Normally this is the mode -whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines. - -The only modes which a machine description @i{must} support are -@code{QImode}, and the modes corresponding to @code{BITS_PER_WORD}, -@code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}. -The compiler will attempt to use @code{DImode} for 8-byte structures and -unions, but this can be prevented by overriding the definition of -@code{MAX_FIXED_MODE_SIZE}. Alternatively, you can have the compiler -use @code{TImode} for 16-byte structures and unions. Likewise, you can -arrange for the C type @code{short int} to avoid using @code{HImode}. - -@cindex mode classes -Very few explicit references to machine modes remain in the compiler and -these few references will soon be removed. Instead, the machine modes -are divided into mode classes. These are represented by the enumeration -type @code{enum mode_class} defined in @file{machmode.h}. The possible -mode classes are: - -@table @code -@findex MODE_INT -@item MODE_INT -Integer modes. By default these are @code{QImode}, @code{HImode}, -@code{SImode}, @code{DImode}, and @code{TImode}. - -@findex MODE_PARTIAL_INT -@item MODE_PARTIAL_INT -The ``partial integer'' modes, @code{PSImode} and @code{PDImode}. - -@findex MODE_FLOAT -@item MODE_FLOAT -floating point modes. By default these are @code{SFmode}, @code{DFmode}, -@code{XFmode} and @code{TFmode}. - -@findex MODE_COMPLEX_INT -@item MODE_COMPLEX_INT -Complex integer modes. (These are not currently implemented). - -@findex MODE_COMPLEX_FLOAT -@item MODE_COMPLEX_FLOAT -Complex floating point modes. By default these are @code{SCmode}, -@code{DCmode}, @code{XCmode}, and @code{TCmode}. - -@findex MODE_FUNCTION -@item MODE_FUNCTION -Algol or Pascal function variables including a static chain. -(These are not currently implemented). - -@findex MODE_CC -@item MODE_CC -Modes representing condition code values. These are @code{CCmode} plus -any modes listed in the @code{EXTRA_CC_MODES} macro. @xref{Jump Patterns}, -also see @ref{Condition Code}. - -@findex MODE_RANDOM -@item MODE_RANDOM -This is a catchall mode class for modes which don't fit into the above -classes. Currently @code{VOIDmode} and @code{BLKmode} are in -@code{MODE_RANDOM}. -@end table - -Here are some C macros that relate to machine modes: - -@table @code -@findex GET_MODE -@item GET_MODE (@var{x}) -Returns the machine mode of the RTX @var{x}. - -@findex PUT_MODE -@item PUT_MODE (@var{x}, @var{newmode}) -Alters the machine mode of the RTX @var{x} to be @var{newmode}. - -@findex NUM_MACHINE_MODES -@item NUM_MACHINE_MODES -Stands for the number of machine modes available on the target -machine. This is one greater than the largest numeric value of any -machine mode. - -@findex GET_MODE_NAME -@item GET_MODE_NAME (@var{m}) -Returns the name of mode @var{m} as a string. - -@findex GET_MODE_CLASS -@item GET_MODE_CLASS (@var{m}) -Returns the mode class of mode @var{m}. - -@findex GET_MODE_WIDER_MODE -@item GET_MODE_WIDER_MODE (@var{m}) -Returns the next wider natural mode. For example, the expression -@code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}. - -@findex GET_MODE_SIZE -@item GET_MODE_SIZE (@var{m}) -Returns the size in bytes of a datum of mode @var{m}. - -@findex GET_MODE_BITSIZE -@item GET_MODE_BITSIZE (@var{m}) -Returns the size in bits of a datum of mode @var{m}. - -@findex GET_MODE_MASK -@item GET_MODE_MASK (@var{m}) -Returns a bitmask containing 1 for all bits in a word that fit within -mode @var{m}. This macro can only be used for modes whose bitsize is -less than or equal to @code{HOST_BITS_PER_INT}. - -@findex GET_MODE_ALIGNMENT -@item GET_MODE_ALIGNMENT (@var{m)}) -Return the required alignment, in bits, for an object of mode @var{m}. - -@findex GET_MODE_UNIT_SIZE -@item GET_MODE_UNIT_SIZE (@var{m}) -Returns the size in bytes of the subunits of a datum of mode @var{m}. -This is the same as @code{GET_MODE_SIZE} except in the case of complex -modes. For them, the unit size is the size of the real or imaginary -part. - -@findex GET_MODE_NUNITS -@item GET_MODE_NUNITS (@var{m}) -Returns the number of units contained in a mode, i.e., -@code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}. - -@findex GET_CLASS_NARROWEST_MODE -@item GET_CLASS_NARROWEST_MODE (@var{c}) -Returns the narrowest mode in mode class @var{c}. -@end table - -@findex byte_mode -@findex word_mode -The global variables @code{byte_mode} and @code{word_mode} contain modes -whose classes are @code{MODE_INT} and whose bitsizes are either -@code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit -machines, these are @code{QImode} and @code{SImode}, respectively. - -@node Constants, Regs and Memory, Machine Modes, RTL -@section Constant Expression Types -@cindex RTL constants -@cindex RTL constant expression types - -The simplest RTL expressions are those that represent constant values. - -@table @code -@findex const_int -@item (const_int @var{i}) -This type of expression represents the integer value @var{i}. @var{i} -is customarily accessed with the macro @code{INTVAL} as in -@code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}. - -@findex const0_rtx -@findex const1_rtx -@findex const2_rtx -@findex constm1_rtx -There is only one expression object for the integer value zero; it is -the value of the variable @code{const0_rtx}. Likewise, the only -expression for integer value one is found in @code{const1_rtx}, the only -expression for integer value two is found in @code{const2_rtx}, and the -only expression for integer value negative one is found in -@code{constm1_rtx}. Any attempt to create an expression of code -@code{const_int} and value zero, one, two or negative one will return -@code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or -@code{constm1_rtx} as appropriate.@refill - -@findex const_true_rtx -Similarly, there is only one object for the integer whose value is -@code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If -@code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and -@code{const1_rtx} will point to the same object. If -@code{STORE_FLAG_VALUE} is -1, @code{const_true_rtx} and -@code{constm1_rtx} will point to the same object.@refill - -@findex const_double -@item (const_double:@var{m} @var{addr} @var{i0} @var{i1} @dots{}) -Represents either a floating-point constant of mode @var{m} or an -integer constant too large to fit into @code{HOST_BITS_PER_WIDE_INT} -bits but small enough to fit within twice that number of bits (GNU CC -does not provide a mechanism to represent even larger constants). In -the latter case, @var{m} will be @code{VOIDmode}. - -@findex CONST_DOUBLE_MEM -@findex CONST_DOUBLE_CHAIN -@var{addr} is used to contain the @code{mem} expression that corresponds -to the location in memory that at which the constant can be found. If -it has not been allocated a memory location, but is on the chain of all -@code{const_double} expressions in this compilation (maintained using an -undisplayed field), @var{addr} contains @code{const0_rtx}. If it is not -on the chain, @var{addr} contains @code{cc0_rtx}. @var{addr} is -customarily accessed with the macro @code{CONST_DOUBLE_MEM} and the -chain field via @code{CONST_DOUBLE_CHAIN}.@refill - -@findex CONST_DOUBLE_LOW -If @var{m} is @code{VOIDmode}, the bits of the value are stored in -@var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro -@code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}. - -If the constant is floating point (regardless of its precision), then -the number of integers used to store the value depends on the size of -@code{REAL_VALUE_TYPE} (@pxref{Cross-compilation}). The integers -represent a floating point number, but not precisely in the target -machine's or host machine's floating point format. To convert them to -the precise bit pattern used by the target machine, use the macro -@code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}). - -@findex CONST0_RTX -@findex CONST1_RTX -@findex CONST2_RTX -The macro @code{CONST0_RTX (@var{mode})} refers to an expression with -value 0 in mode @var{mode}. If mode @var{mode} is of mode class -@code{MODE_INT}, it returns @code{const0_rtx}. Otherwise, it returns a -@code{CONST_DOUBLE} expression in mode @var{mode}. Similarly, the macro -@code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in -mode @var{mode} and similarly for @code{CONST2_RTX}. - -@findex const_string -@item (const_string @var{str}) -Represents a constant string with value @var{str}. Currently this is -used only for insn attributes (@pxref{Insn Attributes}) since constant -strings in C are placed in memory. - -@findex symbol_ref -@item (symbol_ref:@var{mode} @var{symbol}) -Represents the value of an assembler label for data. @var{symbol} is -a string that describes the name of the assembler label. If it starts -with a @samp{*}, the label is the rest of @var{symbol} not including -the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed -with @samp{_}. - -The @code{symbol_ref} contains a mode, which is usually @code{Pmode}. -Usually that is the only mode for which a symbol is directly valid. - -@findex label_ref -@item (label_ref @var{label}) -Represents the value of an assembler label for code. It contains one -operand, an expression, which must be a @code{code_label} that appears -in the instruction sequence to identify the place where the label -should go. - -The reason for using a distinct expression type for code label -references is so that jump optimization can distinguish them. - -@item (const:@var{m} @var{exp}) -Represents a constant that is the result of an assembly-time -arithmetic computation. The operand, @var{exp}, is an expression that -contains only constants (@code{const_int}, @code{symbol_ref} and -@code{label_ref} expressions) combined with @code{plus} and -@code{minus}. However, not all combinations are valid, since the -assembler cannot do arbitrary arithmetic on relocatable symbols. - -@var{m} should be @code{Pmode}. - -@findex high -@item (high:@var{m} @var{exp}) -Represents the high-order bits of @var{exp}, usually a -@code{symbol_ref}. The number of bits is machine-dependent and is -normally the number of bits specified in an instruction that initializes -the high order bits of a register. It is used with @code{lo_sum} to -represent the typical two-instruction sequence used in RISC machines to -reference a global memory location. - -@var{m} should be @code{Pmode}. -@end table - -@node Regs and Memory, Arithmetic, Constants, RTL -@section Registers and Memory -@cindex RTL register expressions -@cindex RTL memory expressions - -Here are the RTL expression types for describing access to machine -registers and to main memory. - -@table @code -@findex reg -@cindex hard registers -@cindex pseudo registers -@item (reg:@var{m} @var{n}) -For small values of the integer @var{n} (those that are less than -@code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine -register number @var{n}: a @dfn{hard register}. For larger values of -@var{n}, it stands for a temporary value or @dfn{pseudo register}. -The compiler's strategy is to generate code assuming an unlimited -number of such pseudo registers, and later convert them into hard -registers or into memory references. - -@var{m} is the machine mode of the reference. It is necessary because -machines can generally refer to each register in more than one mode. -For example, a register may contain a full word but there may be -instructions to refer to it as a half word or as a single byte, as -well as instructions to refer to it as a floating point number of -various precisions. - -Even for a register that the machine can access in only one mode, -the mode must always be specified. - -The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine -description, since the number of hard registers on the machine is an -invariant characteristic of the machine. Note, however, that not -all of the machine registers must be general registers. All the -machine registers that can be used for storage of data are given -hard register numbers, even those that can be used only in certain -instructions or can hold only certain types of data. - -A hard register may be accessed in various modes throughout one -function, but each pseudo register is given a natural mode -and is accessed only in that mode. When it is necessary to describe -an access to a pseudo register using a nonnatural mode, a @code{subreg} -expression is used. - -A @code{reg} expression with a machine mode that specifies more than -one word of data may actually stand for several consecutive registers. -If in addition the register number specifies a hardware register, then -it actually represents several consecutive hardware registers starting -with the specified one. - -Each pseudo register number used in a function's RTL code is -represented by a unique @code{reg} expression. - -@findex FIRST_VIRTUAL_REGISTER -@findex LAST_VIRTUAL_REGISTER -Some pseudo register numbers, those within the range of -@code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only -appear during the RTL generation phase and are eliminated before the -optimization phases. These represent locations in the stack frame that -cannot be determined until RTL generation for the function has been -completed. The following virtual register numbers are defined: - -@table @code -@findex VIRTUAL_INCOMING_ARGS_REGNUM -@item VIRTUAL_INCOMING_ARGS_REGNUM -This points to the first word of the incoming arguments passed on the -stack. Normally these arguments are placed there by the caller, but the -callee may have pushed some arguments that were previously passed in -registers. - -@cindex @code{FIRST_PARM_OFFSET} and virtual registers -@cindex @code{ARG_POINTER_REGNUM} and virtual registers -When RTL generation is complete, this virtual register is replaced -by the sum of the register given by @code{ARG_POINTER_REGNUM} and the -value of @code{FIRST_PARM_OFFSET}. - -@findex VIRTUAL_STACK_VARS_REGNUM -@cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers -@item VIRTUAL_STACK_VARS_REGNUM -If @code{FRAME_GROWS_DOWNWARD} is defined, this points to immediately -above the first variable on the stack. Otherwise, it points to the -first variable on the stack. - -@cindex @code{STARTING_FRAME_OFFSET} and virtual registers -@cindex @code{FRAME_POINTER_REGNUM} and virtual registers -@code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the -register given by @code{FRAME_POINTER_REGNUM} and the value -@code{STARTING_FRAME_OFFSET}. - -@findex VIRTUAL_STACK_DYNAMIC_REGNUM -@item VIRTUAL_STACK_DYNAMIC_REGNUM -This points to the location of dynamically allocated memory on the stack -immediately after the stack pointer has been adjusted by the amount of -memory desired. - -@cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers -@cindex @code{STACK_POINTER_REGNUM} and virtual registers -This virtual register is replaced by the sum of the register given by -@code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}. - -@findex VIRTUAL_OUTGOING_ARGS_REGNUM -@item VIRTUAL_OUTGOING_ARGS_REGNUM -This points to the location in the stack at which outgoing arguments -should be written when the stack is pre-pushed (arguments pushed using -push insns should always use @code{STACK_POINTER_REGNUM}). - -@cindex @code{STACK_POINTER_OFFSET} and virtual registers -This virtual register is replaced by the sum of the register given by -@code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}. -@end table - -@findex subreg -@item (subreg:@var{m} @var{reg} @var{wordnum}) -@code{subreg} expressions are used to refer to a register in a machine -mode other than its natural one, or to refer to one register of -a multi-word @code{reg} that actually refers to several registers. - -Each pseudo-register has a natural mode. If it is necessary to -operate on it in a different mode---for example, to perform a fullword -move instruction on a pseudo-register that contains a single -byte---the pseudo-register must be enclosed in a @code{subreg}. In -such a case, @var{wordnum} is zero. - -Usually @var{m} is at least as narrow as the mode of @var{reg}, in which -case it is restricting consideration to only the bits of @var{reg} that -are in @var{m}. - -Sometimes @var{m} is wider than the mode of @var{reg}. These -@code{subreg} expressions are often called @dfn{paradoxical}. They are -used in cases where we want to refer to an object in a wider mode but do -not care what value the additional bits have. The reload pass ensures -that paradoxical references are only made to hard registers. - -The other use of @code{subreg} is to extract the individual registers of -a multi-register value. Machine modes such as @code{DImode} and -@code{TImode} can indicate values longer than a word, values which -usually require two or more consecutive registers. To access one of the -registers, use a @code{subreg} with mode @code{SImode} and a -@var{wordnum} that says which register. - -Storing in a non-paradoxical @code{subreg} has undefined results for -bits belonging to the same word as the @code{subreg}. This laxity makes -it easier to generate efficient code for such instructions. To -represent an instruction that preserves all the bits outside of those in -the @code{subreg}, use @code{strict_low_part} around the @code{subreg}. - -@cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg} -The compilation parameter @code{WORDS_BIG_ENDIAN}, if set to 1, says -that word number zero is the most significant part; otherwise, it is -the least significant part. - -@cindex combiner pass -@cindex reload pass -@cindex @code{subreg}, special reload handling -Between the combiner pass and the reload pass, it is possible to have a -paradoxical @code{subreg} which contains a @code{mem} instead of a -@code{reg} as its first operand. After the reload pass, it is also -possible to have a non-paradoxical @code{subreg} which contains a -@code{mem}; this usually occurs when the @code{mem} is a stack slot -which replaced a pseudo register. - -Note that it is not valid to access a @code{DFmode} value in @code{SFmode} -using a @code{subreg}. On some machines the most significant part of a -@code{DFmode} value does not have the same format as a single-precision -floating value. - -It is also not valid to access a single word of a multi-word value in a -hard register when less registers can hold the value than would be -expected from its size. For example, some 32-bit machines have -floating-point registers that can hold an entire @code{DFmode} value. -If register 10 were such a register @code{(subreg:SI (reg:DF 10) 1)} -would be invalid because there is no way to convert that reference to -a single machine register. The reload pass prevents @code{subreg} -expressions such as these from being formed. - -@findex SUBREG_REG -@findex SUBREG_WORD -The first operand of a @code{subreg} expression is customarily accessed -with the @code{SUBREG_REG} macro and the second operand is customarily -accessed with the @code{SUBREG_WORD} macro. - -@findex scratch -@cindex scratch operands -@item (scratch:@var{m}) -This represents a scratch register that will be required for the -execution of a single instruction and not used subsequently. It is -converted into a @code{reg} by either the local register allocator or -the reload pass. - -@code{scratch} is usually present inside a @code{clobber} operation -(@pxref{Side Effects}). - -@findex cc0 -@cindex condition code register -@item (cc0) -This refers to the machine's condition code register. It has no -operands and may not have a machine mode. There are two ways to use it: - -@itemize @bullet -@item -To stand for a complete set of condition code flags. This is best on -most machines, where each comparison sets the entire series of flags. - -With this technique, @code{(cc0)} may be validly used in only two -contexts: as the destination of an assignment (in test and compare -instructions) and in comparison operators comparing against zero -(@code{const_int} with value zero; that is to say, @code{const0_rtx}). - -@item -To stand for a single flag that is the result of a single condition. -This is useful on machines that have only a single flag bit, and in -which comparison instructions must specify the condition to test. - -With this technique, @code{(cc0)} may be validly used in only two -contexts: as the destination of an assignment (in test and compare -instructions) where the source is a comparison operator, and as the -first operand of @code{if_then_else} (in a conditional branch). -@end itemize - -@findex cc0_rtx -There is only one expression object of code @code{cc0}; it is the -value of the variable @code{cc0_rtx}. Any attempt to create an -expression of code @code{cc0} will return @code{cc0_rtx}. - -Instructions can set the condition code implicitly. On many machines, -nearly all instructions set the condition code based on the value that -they compute or store. It is not necessary to record these actions -explicitly in the RTL because the machine description includes a -prescription for recognizing the instructions that do so (by means of -the macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only -instructions whose sole purpose is to set the condition code, and -instructions that use the condition code, need mention @code{(cc0)}. - -On some machines, the condition code register is given a register number -and a @code{reg} is used instead of @code{(cc0)}. This is usually the -preferable approach if only a small subset of instructions modify the -condition code. Other machines store condition codes in general -registers; in such cases a pseudo register should be used. - -Some machines, such as the Sparc and RS/6000, have two sets of -arithmetic instructions, one that sets and one that does not set the -condition code. This is best handled by normally generating the -instruction that does not set the condition code, and making a pattern -that both performs the arithmetic and sets the condition code register -(which would not be @code{(cc0)} in this case). For examples, search -for @samp{addcc} and @samp{andcc} in @file{sparc.md}. - -@findex pc -@item (pc) -@cindex program counter -This represents the machine's program counter. It has no operands and -may not have a machine mode. @code{(pc)} may be validly used only in -certain specific contexts in jump instructions. - -@findex pc_rtx -There is only one expression object of code @code{pc}; it is the value -of the variable @code{pc_rtx}. Any attempt to create an expression of -code @code{pc} will return @code{pc_rtx}. - -All instructions that do not jump alter the program counter implicitly -by incrementing it, but there is no need to mention this in the RTL. - -@findex mem -@item (mem:@var{m} @var{addr}) -This RTX represents a reference to main memory at an address -represented by the expression @var{addr}. @var{m} specifies how large -a unit of memory is accessed. -@end table - -@node Arithmetic, Comparisons, Regs and Memory, RTL -@section RTL Expressions for Arithmetic -@cindex arithmetic, in RTL -@cindex math, in RTL -@cindex RTL expressions for arithmetic - -Unless otherwise specified, all the operands of arithmetic expressions -must be valid for mode @var{m}. An operand is valid for mode @var{m} -if it has mode @var{m}, or if it is a @code{const_int} or -@code{const_double} and @var{m} is a mode of class @code{MODE_INT}. - -For commutative binary operations, constants should be placed in the -second operand. - -@table @code -@findex plus -@cindex RTL addition -@cindex RTL sum -@item (plus:@var{m} @var{x} @var{y}) -Represents the sum of the values represented by @var{x} and @var{y} -carried out in machine mode @var{m}. - -@findex lo_sum -@item (lo_sum:@var{m} @var{x} @var{y}) -Like @code{plus}, except that it represents that sum of @var{x} and the -low-order bits of @var{y}. The number of low order bits is -machine-dependent but is normally the number of bits in a @code{Pmode} -item minus the number of bits set by the @code{high} code -(@pxref{Constants}). - -@var{m} should be @code{Pmode}. - -@findex minus -@cindex RTL subtraction -@cindex RTL difference -@item (minus:@var{m} @var{x} @var{y}) -Like @code{plus} but represents subtraction. - -@findex compare -@cindex RTL comparison -@item (compare:@var{m} @var{x} @var{y}) -Represents the result of subtracting @var{y} from @var{x} for purposes -of comparison. The result is computed without overflow, as if with -infinite precision. - -Of course, machines can't really subtract with infinite precision. -However, they can pretend to do so when only the sign of the -result will be used, which is the case when the result is stored -in the condition code. And that is the only way this kind of expression -may validly be used: as a value to be stored in the condition codes. - -The mode @var{m} is not related to the modes of @var{x} and @var{y}, -but instead is the mode of the condition code value. If @code{(cc0)} -is used, it is @code{VOIDmode}. Otherwise it is some mode in class -@code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}. - -Normally, @var{x} and @var{y} must have the same mode. Otherwise, -@code{compare} is valid only if the mode of @var{x} is in class -@code{MODE_INT} and @var{y} is a @code{const_int} or -@code{const_double} with mode @code{VOIDmode}. The mode of @var{x} -determines what mode the comparison is to be done in; thus it must not -be @code{VOIDmode}. - -If one of the operands is a constant, it should be placed in the -second operand and the comparison code adjusted as appropriate. - -A @code{compare} specifying two @code{VOIDmode} constants is not valid -since there is no way to know in what mode the comparison is to be -performed; the comparison must either be folded during the compilation -or the first operand must be loaded into a register while its mode is -still known. - -@findex neg -@item (neg:@var{m} @var{x}) -Represents the negation (subtraction from zero) of the value represented -by @var{x}, carried out in mode @var{m}. - -@findex mult -@cindex multiplication -@cindex product -@item (mult:@var{m} @var{x} @var{y}) -Represents the signed product of the values represented by @var{x} and -@var{y} carried out in machine mode @var{m}. - -Some machines support a multiplication that generates a product wider -than the operands. Write the pattern for this as - -@example -(mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y})) -@end example - -where @var{m} is wider than the modes of @var{x} and @var{y}, which need -not be the same. - -Write patterns for unsigned widening multiplication similarly using -@code{zero_extend}. - -@findex div -@cindex division -@cindex signed division -@cindex quotient -@item (div:@var{m} @var{x} @var{y}) -Represents the quotient in signed division of @var{x} by @var{y}, -carried out in machine mode @var{m}. If @var{m} is a floating point -mode, it represents the exact quotient; otherwise, the integerized -quotient. - -Some machines have division instructions in which the operands and -quotient widths are not all the same; you should represent -such instructions using @code{truncate} and @code{sign_extend} as in, - -@example -(truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y}))) -@end example - -@findex udiv -@cindex unsigned division -@cindex division -@item (udiv:@var{m} @var{x} @var{y}) -Like @code{div} but represents unsigned division. - -@findex mod -@findex umod -@cindex remainder -@cindex division -@item (mod:@var{m} @var{x} @var{y}) -@itemx (umod:@var{m} @var{x} @var{y}) -Like @code{div} and @code{udiv} but represent the remainder instead of -the quotient. - -@findex smin -@findex smax -@cindex signed minimum -@cindex signed maximum -@item (smin:@var{m} @var{x} @var{y}) -@itemx (smax:@var{m} @var{x} @var{y}) -Represents the smaller (for @code{smin}) or larger (for @code{smax}) of -@var{x} and @var{y}, interpreted as signed integers in mode @var{m}. - -@findex umin -@findex umax -@cindex unsigned minimum and maximum -@item (umin:@var{m} @var{x} @var{y}) -@itemx (umax:@var{m} @var{x} @var{y}) -Like @code{smin} and @code{smax}, but the values are interpreted as unsigned -integers. - -@findex not -@cindex complement, bitwise -@cindex bitwise complement -@item (not:@var{m} @var{x}) -Represents the bitwise complement of the value represented by @var{x}, -carried out in mode @var{m}, which must be a fixed-point machine mode. - -@findex and -@cindex logical-and, bitwise -@cindex bitwise logical-and -@item (and:@var{m} @var{x} @var{y}) -Represents the bitwise logical-and of the values represented by -@var{x} and @var{y}, carried out in machine mode @var{m}, which must be -a fixed-point machine mode. - -@findex ior -@cindex inclusive-or, bitwise -@cindex bitwise inclusive-or -@item (ior:@var{m} @var{x} @var{y}) -Represents the bitwise inclusive-or of the values represented by @var{x} -and @var{y}, carried out in machine mode @var{m}, which must be a -fixed-point mode. - -@findex xor -@cindex exclusive-or, bitwise -@cindex bitwise exclusive-or -@item (xor:@var{m} @var{x} @var{y}) -Represents the bitwise exclusive-or of the values represented by @var{x} -and @var{y}, carried out in machine mode @var{m}, which must be a -fixed-point mode. - -@findex ashift -@cindex left shift -@cindex shift -@cindex arithmetic shift -@item (ashift:@var{m} @var{x} @var{c}) -Represents the result of arithmetically shifting @var{x} left by @var{c} -places. @var{x} have mode @var{m}, a fixed-point machine mode. @var{c} -be a fixed-point mode or be a constant with mode @code{VOIDmode}; which -mode is determined by the mode called for in the machine description -entry for the left-shift instruction. For example, on the Vax, the mode -of @var{c} is @code{QImode} regardless of @var{m}. - -@findex lshiftrt -@cindex right shift -@findex ashiftrt -@item (lshiftrt:@var{m} @var{x} @var{c}) -@itemx (ashiftrt:@var{m} @var{x} @var{c}) -Like @code{ashift} but for right shift. Unlike the case for left shift, -these two operations are distinct. - -@findex rotate -@cindex rotate -@cindex left rotate -@findex rotatert -@cindex right rotate -@item (rotate:@var{m} @var{x} @var{c}) -@itemx (rotatert:@var{m} @var{x} @var{c}) -Similar but represent left and right rotate. If @var{c} is a constant, -use @code{rotate}. - -@findex abs -@cindex absolute value -@item (abs:@var{m} @var{x}) -Represents the absolute value of @var{x}, computed in mode @var{m}. - -@findex sqrt -@cindex square root -@item (sqrt:@var{m} @var{x}) -Represents the square root of @var{x}, computed in mode @var{m}. -Most often @var{m} will be a floating point mode. - -@findex ffs -@item (ffs:@var{m} @var{x}) -Represents one plus the index of the least significant 1-bit in -@var{x}, represented as an integer of mode @var{m}. (The value is -zero if @var{x} is zero.) The mode of @var{x} need not be @var{m}; -depending on the target machine, various mode combinations may be -valid. -@end table - -@node Comparisons, Bit Fields, Arithmetic, RTL -@section Comparison Operations -@cindex RTL comparison operations - -Comparison operators test a relation on two operands and are considered -to represent a machine-dependent nonzero value described by, but not -necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc}) -if the relation holds, or zero if it does not. The mode of the -comparison operation is independent of the mode of the data being -compared. If the comparison operation is being tested (e.g., the first -operand of an @code{if_then_else}), the mode must be @code{VOIDmode}. -If the comparison operation is producing data to be stored in some -variable, the mode must be in class @code{MODE_INT}. All comparison -operations producing data must use the same mode, which is -machine-specific. - -@cindex condition codes -There are two ways that comparison operations may be used. The -comparison operators may be used to compare the condition codes -@code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such -a construct actually refers to the result of the preceding instruction -in which the condition codes were set. The instructing setting the -condition code must be adjacent to the instruction using the condition -code; only @code{note} insns may separate them. - -Alternatively, a comparison operation may directly compare two data -objects. The mode of the comparison is determined by the operands; they -must both be valid for a common machine mode. A comparison with both -operands constant would be invalid as the machine mode could not be -deduced from it, but such a comparison should never exist in RTL due to -constant folding. - -In the example above, if @code{(cc0)} were last set to -@code{(compare @var{x} @var{y})}, the comparison operation is -identical to @code{(eq @var{x} @var{y})}. Usually only one style -of comparisons is supported on a particular machine, but the combine -pass will try to merge the operations to produce the @code{eq} shown -in case it exists in the context of the particular insn involved. - -Inequality comparisons come in two flavors, signed and unsigned. Thus, -there are distinct expression codes @code{gt} and @code{gtu} for signed and -unsigned greater-than. These can produce different results for the same -pair of integer values: for example, 1 is signed greater-than -1 but not -unsigned greater-than, because -1 when regarded as unsigned is actually -@code{0xffffffff} which is greater than 1. - -The signed comparisons are also used for floating point values. Floating -point comparisons are distinguished by the machine modes of the operands. - -@table @code -@findex eq -@cindex equal -@item (eq:@var{m} @var{x} @var{y}) -1 if the values represented by @var{x} and @var{y} are equal, -otherwise 0. - -@findex ne -@cindex not equal -@item (ne:@var{m} @var{x} @var{y}) -1 if the values represented by @var{x} and @var{y} are not equal, -otherwise 0. - -@findex gt -@cindex greater than -@item (gt:@var{m} @var{x} @var{y}) -1 if the @var{x} is greater than @var{y}. If they are fixed-point, -the comparison is done in a signed sense. - -@findex gtu -@cindex greater than -@cindex unsigned greater than -@item (gtu:@var{m} @var{x} @var{y}) -Like @code{gt} but does unsigned comparison, on fixed-point numbers only. - -@findex lt -@cindex less than -@findex ltu -@cindex unsigned less than -@item (lt:@var{m} @var{x} @var{y}) -@itemx (ltu:@var{m} @var{x} @var{y}) -Like @code{gt} and @code{gtu} but test for ``less than''. - -@findex ge -@cindex greater than -@findex geu -@cindex unsigned greater than -@item (ge:@var{m} @var{x} @var{y}) -@itemx (geu:@var{m} @var{x} @var{y}) -Like @code{gt} and @code{gtu} but test for ``greater than or equal''. - -@findex le -@cindex less than or equal -@findex leu -@cindex unsigned less than -@item (le:@var{m} @var{x} @var{y}) -@itemx (leu:@var{m} @var{x} @var{y}) -Like @code{gt} and @code{gtu} but test for ``less than or equal''. - -@findex if_then_else -@item (if_then_else @var{cond} @var{then} @var{else}) -This is not a comparison operation but is listed here because it is -always used in conjunction with a comparison operation. To be -precise, @var{cond} is a comparison expression. This expression -represents a choice, according to @var{cond}, between the value -represented by @var{then} and the one represented by @var{else}. - -On most machines, @code{if_then_else} expressions are valid only -to express conditional jumps. - -@findex cond -@item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default}) -Similar to @code{if_then_else}, but more general. Each of @var{test1}, -@var{test2}, @dots{} is performed in turn. The result of this expression is -the @var{value} corresponding to the first non-zero test, or @var{default} if -none of the tests are non-zero expressions. - -This is currently not valid for instruction patterns and is supported only -for insn attributes. @xref{Insn Attributes}. -@end table - -@node Bit Fields, Conversions, Comparisons, RTL -@section Bit Fields -@cindex bit fields - -Special expression codes exist to represent bitfield instructions. -These types of expressions are lvalues in RTL; they may appear -on the left side of an assignment, indicating insertion of a value -into the specified bit field. - -@table @code -@findex sign_extract -@cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract} -@item (sign_extract:@var{m} @var{loc} @var{size} @var{pos}) -This represents a reference to a sign-extended bit field contained or -starting in @var{loc} (a memory or register reference). The bit field -is @var{size} bits wide and starts at bit @var{pos}. The compilation -option @code{BITS_BIG_ENDIAN} says which end of the memory unit -@var{pos} counts from. - -If @var{loc} is in memory, its mode must be a single-byte integer mode. -If @var{loc} is in a register, the mode to use is specified by the -operand of the @code{insv} or @code{extv} pattern -(@pxref{Standard Names}) and is usually a full-word integer mode. - -The mode of @var{pos} is machine-specific and is also specified -in the @code{insv} or @code{extv} pattern. - -The mode @var{m} is the same as the mode that would be used for -@var{loc} if it were a register. - -@findex zero_extract -@item (zero_extract:@var{m} @var{loc} @var{size} @var{pos}) -Like @code{sign_extract} but refers to an unsigned or zero-extended -bit field. The same sequence of bits are extracted, but they -are filled to an entire word with zeros instead of by sign-extension. -@end table - -@node Conversions, RTL Declarations, Bit Fields, RTL -@section Conversions -@cindex conversions -@cindex machine mode conversions - -All conversions between machine modes must be represented by -explicit conversion operations. For example, an expression -which is the sum of a byte and a full word cannot be written as -@code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus} -operation requires two operands of the same machine mode. -Therefore, the byte-sized operand is enclosed in a conversion -operation, as in - -@example -(plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80)) -@end example - -The conversion operation is not a mere placeholder, because there -may be more than one way of converting from a given starting mode -to the desired final mode. The conversion operation code says how -to do it. - -For all conversion operations, @var{x} must not be @code{VOIDmode} -because the mode in which to do the conversion would not be known. -The conversion must either be done at compile-time or @var{x} -must be placed into a register. - -@table @code -@findex sign_extend -@item (sign_extend:@var{m} @var{x}) -Represents the result of sign-extending the value @var{x} -to machine mode @var{m}. @var{m} must be a fixed-point mode -and @var{x} a fixed-point value of a mode narrower than @var{m}. - -@findex zero_extend -@item (zero_extend:@var{m} @var{x}) -Represents the result of zero-extending the value @var{x} -to machine mode @var{m}. @var{m} must be a fixed-point mode -and @var{x} a fixed-point value of a mode narrower than @var{m}. - -@findex float_extend -@item (float_extend:@var{m} @var{x}) -Represents the result of extending the value @var{x} -to machine mode @var{m}. @var{m} must be a floating point mode -and @var{x} a floating point value of a mode narrower than @var{m}. - -@findex truncate -@item (truncate:@var{m} @var{x}) -Represents the result of truncating the value @var{x} -to machine mode @var{m}. @var{m} must be a fixed-point mode -and @var{x} a fixed-point value of a mode wider than @var{m}. - -@findex float_truncate -@item (float_truncate:@var{m} @var{x}) -Represents the result of truncating the value @var{x} -to machine mode @var{m}. @var{m} must be a floating point mode -and @var{x} a floating point value of a mode wider than @var{m}. - -@findex float -@item (float:@var{m} @var{x}) -Represents the result of converting fixed point value @var{x}, -regarded as signed, to floating point mode @var{m}. - -@findex unsigned_float -@item (unsigned_float:@var{m} @var{x}) -Represents the result of converting fixed point value @var{x}, -regarded as unsigned, to floating point mode @var{m}. - -@findex fix -@item (fix:@var{m} @var{x}) -When @var{m} is a fixed point mode, represents the result of -converting floating point value @var{x} to mode @var{m}, regarded as -signed. How rounding is done is not specified, so this operation may -be used validly in compiling C code only for integer-valued operands. - -@findex unsigned_fix -@item (unsigned_fix:@var{m} @var{x}) -Represents the result of converting floating point value @var{x} to -fixed point mode @var{m}, regarded as unsigned. How rounding is done -is not specified. - -@findex fix -@item (fix:@var{m} @var{x}) -When @var{m} is a floating point mode, represents the result of -converting floating point value @var{x} (valid for mode @var{m}) to an -integer, still represented in floating point mode @var{m}, by rounding -towards zero. -@end table - -@node RTL Declarations, Side Effects, Conversions, RTL -@section Declarations -@cindex RTL declarations -@cindex declarations, RTL - -Declaration expression codes do not represent arithmetic operations -but rather state assertions about their operands. - -@table @code -@findex strict_low_part -@cindex @code{subreg}, in @code{strict_low_part} -@item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0)) -This expression code is used in only one context: as the destination operand of a -@code{set} expression. In addition, the operand of this expression -must be a non-paradoxical @code{subreg} expression. - -The presence of @code{strict_low_part} says that the part of the -register which is meaningful in mode @var{n}, but is not part of -mode @var{m}, is not to be altered. Normally, an assignment to such -a subreg is allowed to have undefined effects on the rest of the -register when @var{m} is less than a word. -@end table - -@node Side Effects, Incdec, RTL Declarations, RTL -@section Side Effect Expressions -@cindex RTL side effect expressions - -The expression codes described so far represent values, not actions. -But machine instructions never produce values; they are meaningful -only for their side effects on the state of the machine. Special -expression codes are used to represent side effects. - -The body of an instruction is always one of these side effect codes; -the codes described above, which represent values, appear only as -the operands of these. - -@table @code -@findex set -@item (set @var{lval} @var{x}) -Represents the action of storing the value of @var{x} into the place -represented by @var{lval}. @var{lval} must be an expression -representing a place that can be stored in: @code{reg} (or -@code{subreg} or @code{strict_low_part}), @code{mem}, @code{pc} or -@code{cc0}.@refill - -If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a -machine mode; then @var{x} must be valid for that mode.@refill - -If @var{lval} is a @code{reg} whose machine mode is less than the full -width of the register, then it means that the part of the register -specified by the machine mode is given the specified value and the -rest of the register receives an undefined value. Likewise, if -@var{lval} is a @code{subreg} whose machine mode is narrower than -the mode of the register, the rest of the register can be changed in -an undefined way. - -If @var{lval} is a @code{strict_low_part} of a @code{subreg}, then the -part of the register specified by the machine mode of the -@code{subreg} is given the value @var{x} and the rest of the register -is not changed.@refill - -If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may -be either a @code{compare} expression or a value that may have any mode. -The latter case represents a ``test'' instruction. The expression -@code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to -@code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}. -Use the former expression to save space during the compilation. - -@cindex jump instructions and @code{set} -@cindex @code{if_then_else} usage -If @var{lval} is @code{(pc)}, we have a jump instruction, and the -possibilities for @var{x} are very limited. It may be a -@code{label_ref} expression (unconditional jump). It may be an -@code{if_then_else} (conditional jump), in which case either the -second or the third operand must be @code{(pc)} (for the case which -does not jump) and the other of the two must be a @code{label_ref} -(for the case which does jump). @var{x} may also be a @code{mem} or -@code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a -@code{mem}; these unusual patterns are used to represent jumps through -branch tables.@refill - -If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of -@var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be -valid for the mode of @var{lval}. - -@findex SET_DEST -@findex SET_SRC -@var{lval} is customarily accessed with the @code{SET_DEST} macro and -@var{x} with the @code{SET_SRC} macro. - -@findex return -@item (return) -As the sole expression in a pattern, represents a return from the -current function, on machines where this can be done with one -instruction, such as Vaxes. On machines where a multi-instruction -``epilogue'' must be executed in order to return from the function, -returning is done by jumping to a label which precedes the epilogue, and -the @code{return} expression code is never used. - -Inside an @code{if_then_else} expression, represents the value to be -placed in @code{pc} to return to the caller. - -Note that an insn pattern of @code{(return)} is logically equivalent to -@code{(set (pc) (return))}, but the latter form is never used. - -@findex call -@item (call @var{function} @var{nargs}) -Represents a function call. @var{function} is a @code{mem} expression -whose address is the address of the function to be called. -@var{nargs} is an expression which can be used for two purposes: on -some machines it represents the number of bytes of stack argument; on -others, it represents the number of argument registers. - -Each machine has a standard machine mode which @var{function} must -have. The machine description defines macro @code{FUNCTION_MODE} to -expand into the requisite mode name. The purpose of this mode is to -specify what kind of addressing is allowed, on machines where the -allowed kinds of addressing depend on the machine mode being -addressed. - -@findex clobber -@item (clobber @var{x}) -Represents the storing or possible storing of an unpredictable, -undescribed value into @var{x}, which must be a @code{reg}, -@code{scratch} or @code{mem} expression. - -One place this is used is in string instructions that store standard -values into particular hard registers. It may not be worth the -trouble to describe the values that are stored, but it is essential to -inform the compiler that the registers will be altered, lest it -attempt to keep data in them across the string instruction. - -If @var{x} is @code{(mem:BLK (const_int 0))}, it means that all memory -locations must be presumed clobbered. - -Note that the machine description classifies certain hard registers as -``call-clobbered''. All function call instructions are assumed by -default to clobber these registers, so there is no need to use -@code{clobber} expressions to indicate this fact. Also, each function -call is assumed to have the potential to alter any memory location, -unless the function is declared @code{const}. - -If the last group of expressions in a @code{parallel} are each a -@code{clobber} expression whose arguments are @code{reg} or -@code{match_scratch} (@pxref{RTL Template}) expressions, the combiner -phase can add the appropriate @code{clobber} expressions to an insn it -has constructed when doing so will cause a pattern to be matched. - -This feature can be used, for example, on a machine that whose multiply -and add instructions don't use an MQ register but which has an -add-accumulate instruction that does clobber the MQ register. Similarly, -a combined instruction might require a temporary register while the -constituent instructions might not. - -When a @code{clobber} expression for a register appears inside a -@code{parallel} with other side effects, the register allocator -guarantees that the register is unoccupied both before and after that -insn. However, the reload phase may allocate a register used for one of -the inputs unless the @samp{&} constraint is specified for the selected -alternative (@pxref{Modifiers}). You can clobber either a specific hard -register, a pseudo register, or a @code{scratch} expression; in the -latter two cases, GNU CC will allocate a hard register that is available -there for use as a temporary. - -For instructions that require a temporary register, you should use -@code{scratch} instead of a pseudo-register because this will allow the -combiner phase to add the @code{clobber} when required. You do this by -coding (@code{clobber} (@code{match_scratch} @dots{})). If you do -clobber a pseudo register, use one which appears nowhere else---generate -a new one each time. Otherwise, you may confuse CSE. - -There is one other known use for clobbering a pseudo register in a -@code{parallel}: when one of the input operands of the insn is also -clobbered by the insn. In this case, using the same pseudo register in -the clobber and elsewhere in the insn produces the expected results. - -@findex use -@item (use @var{x}) -Represents the use of the value of @var{x}. It indicates that the -value in @var{x} at this point in the program is needed, even though -it may not be apparent why this is so. Therefore, the compiler will -not attempt to delete previous instructions whose only effect is to -store a value in @var{x}. @var{x} must be a @code{reg} expression. - -During the delayed branch scheduling phase, @var{x} may be an insn. -This indicates that @var{x} previously was located at this place in the -code and its data dependencies need to be taken into account. These -@code{use} insns will be deleted before the delayed branch scheduling -phase exits. - -@findex parallel -@item (parallel [@var{x0} @var{x1} @dots{}]) -Represents several side effects performed in parallel. The square -brackets stand for a vector; the operand of @code{parallel} is a -vector of expressions. @var{x0}, @var{x1} and so on are individual -side effect expressions---expressions of code @code{set}, @code{call}, -@code{return}, @code{clobber} or @code{use}.@refill - -``In parallel'' means that first all the values used in the individual -side-effects are computed, and second all the actual side-effects are -performed. For example, - -@example -(parallel [(set (reg:SI 1) (mem:SI (reg:SI 1))) - (set (mem:SI (reg:SI 1)) (reg:SI 1))]) -@end example - -@noindent -says unambiguously that the values of hard register 1 and the memory -location addressed by it are interchanged. In both places where -@code{(reg:SI 1)} appears as a memory address it refers to the value -in register 1 @emph{before} the execution of the insn. - -It follows that it is @emph{incorrect} to use @code{parallel} and -expect the result of one @code{set} to be available for the next one. -For example, people sometimes attempt to represent a jump-if-zero -instruction this way: - -@example -(parallel [(set (cc0) (reg:SI 34)) - (set (pc) (if_then_else - (eq (cc0) (const_int 0)) - (label_ref @dots{}) - (pc)))]) -@end example - -@noindent -But this is incorrect, because it says that the jump condition depends -on the condition code value @emph{before} this instruction, not on the -new value that is set by this instruction. - -@cindex peephole optimization, RTL representation -Peephole optimization, which takes place together with final assembly -code output, can produce insns whose patterns consist of a @code{parallel} -whose elements are the operands needed to output the resulting -assembler code---often @code{reg}, @code{mem} or constant expressions. -This would not be well-formed RTL at any other stage in compilation, -but it is ok then because no further optimization remains to be done. -However, the definition of the macro @code{NOTICE_UPDATE_CC}, if -any, must deal with such insns if you define any peephole optimizations. - -@findex sequence -@item (sequence [@var{insns} @dots{}]) -Represents a sequence of insns. Each of the @var{insns} that appears -in the vector is suitable for appearing in the chain of insns, so it -must be an @code{insn}, @code{jump_insn}, @code{call_insn}, -@code{code_label}, @code{barrier} or @code{note}. - -A @code{sequence} RTX is never placed in an actual insn during RTL -generation. It represents the sequence of insns that result from a -@code{define_expand} @emph{before} those insns are passed to -@code{emit_insn} to insert them in the chain of insns. When actually -inserted, the individual sub-insns are separated out and the -@code{sequence} is forgotten. - -After delay-slot scheduling is completed, an insn and all the insns that -reside in its delay slots are grouped together into a @code{sequence}. -The insn requiring the delay slot is the first insn in the vector; -subsequent insns are to be placed in the delay slot. - -@code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to -indicate that a branch insn should be used that will conditionally annul -the effect of the insns in the delay slots. In such a case, -@code{INSN_FROM_TARGET_P} indicates that the insn is from the target of -the branch and should be executed only if the branch is taken; otherwise -the insn should be executed only if the branch is not taken. -@xref{Delay Slots}. -@end table - -These expression codes appear in place of a side effect, as the body of -an insn, though strictly speaking they do not always describe side -effects as such: - -@table @code -@findex asm_input -@item (asm_input @var{s}) -Represents literal assembler code as described by the string @var{s}. - -@findex unspec -@findex unspec_volatile -@item (unspec [@var{operands} @dots{}] @var{index}) -@itemx (unspec_volatile [@var{operands} @dots{}] @var{index}) -Represents a machine-specific operation on @var{operands}. @var{index} -selects between multiple machine-specific operations. -@code{unspec_volatile} is used for volatile operations and operations -that may trap; @code{unspec} is used for other operations. - -These codes may appear inside a @code{pattern} of an -insn, inside a @code{parallel}, or inside an expression. - -@findex addr_vec -@item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}]) -Represents a table of jump addresses. The vector elements @var{lr0}, -etc., are @code{label_ref} expressions. The mode @var{m} specifies -how much space is given to each address; normally @var{m} would be -@code{Pmode}. - -@findex addr_diff_vec -@item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}]) -Represents a table of jump addresses expressed as offsets from -@var{base}. The vector elements @var{lr0}, etc., are @code{label_ref} -expressions and so is @var{base}. The mode @var{m} specifies how much -space is given to each address-difference.@refill -@end table - -@node Incdec, Assembler, Side Effects, RTL -@section Embedded Side-Effects on Addresses -@cindex RTL preincrement -@cindex RTL postincrement -@cindex RTL predecrement -@cindex RTL postdecrement - -Four special side-effect expression codes appear as memory addresses. - -@table @code -@findex pre_dec -@item (pre_dec:@var{m} @var{x}) -Represents the side effect of decrementing @var{x} by a standard -amount and represents also the value that @var{x} has after being -decremented. @var{x} must be a @code{reg} or @code{mem}, but most -machines allow only a @code{reg}. @var{m} must be the machine mode -for pointers on the machine in use. The amount @var{x} is decremented -by is the length in bytes of the machine mode of the containing memory -reference of which this expression serves as the address. Here is an -example of its use:@refill - -@example -(mem:DF (pre_dec:SI (reg:SI 39))) -@end example - -@noindent -This says to decrement pseudo register 39 by the length of a @code{DFmode} -value and use the result to address a @code{DFmode} value. - -@findex pre_inc -@item (pre_inc:@var{m} @var{x}) -Similar, but specifies incrementing @var{x} instead of decrementing it. - -@findex post_dec -@item (post_dec:@var{m} @var{x}) -Represents the same side effect as @code{pre_dec} but a different -value. The value represented here is the value @var{x} has @i{before} -being decremented. - -@findex post_inc -@item (post_inc:@var{m} @var{x}) -Similar, but specifies incrementing @var{x} instead of decrementing it. -@end table - -These embedded side effect expressions must be used with care. Instruction -patterns may not use them. Until the @samp{flow} pass of the compiler, -they may occur only to represent pushes onto the stack. The @samp{flow} -pass finds cases where registers are incremented or decremented in one -instruction and used as an address shortly before or after; these cases are -then transformed to use pre- or post-increment or -decrement. - -If a register used as the operand of these expressions is used in -another address in an insn, the original value of the register is used. -Uses of the register outside of an address are not permitted within the -same insn as a use in an embedded side effect expression because such -insns behave differently on different machines and hence must be treated -as ambiguous and disallowed. - -An instruction that can be represented with an embedded side effect -could also be represented using @code{parallel} containing an additional -@code{set} to describe how the address register is altered. This is not -done because machines that allow these operations at all typically -allow them wherever a memory address is called for. Describing them as -additional parallel stores would require doubling the number of entries -in the machine description. - -@node Assembler, Insns, Incdec, RTL -@section Assembler Instructions as Expressions -@cindex assembler instructions in RTL - -@cindex @code{asm_operands}, usage -The RTX code @code{asm_operands} represents a value produced by a -user-specified assembler instruction. It is used to represent -an @code{asm} statement with arguments. An @code{asm} statement with -a single output operand, like this: - -@smallexample -asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z)); -@end smallexample - -@noindent -is represented using a single @code{asm_operands} RTX which represents -the value that is stored in @code{outputvar}: - -@smallexample -(set @var{rtx-for-outputvar} - (asm_operands "foo %1,%2,%0" "a" 0 - [@var{rtx-for-addition-result} @var{rtx-for-*z}] - [(asm_input:@var{m1} "g") - (asm_input:@var{m2} "di")])) -@end smallexample - -@noindent -Here the operands of the @code{asm_operands} RTX are the assembler -template string, the output-operand's constraint, the index-number of the -output operand among the output operands specified, a vector of input -operand RTX's, and a vector of input-operand modes and constraints. The -mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of -@code{*z}. - -When an @code{asm} statement has multiple output values, its insn has -several such @code{set} RTX's inside of a @code{parallel}. Each @code{set} -contains a @code{asm_operands}; all of these share the same assembler -template and vectors, but each contains the constraint for the respective -output operand. They are also distinguished by the output-operand index -number, which is 0, 1, @dots{} for successive output operands. - -@node Insns, Calls, Assembler, RTL -@section Insns -@cindex insns - -The RTL representation of the code for a function is a doubly-linked -chain of objects called @dfn{insns}. Insns are expressions with -special codes that are used for no other purpose. Some insns are -actual instructions; others represent dispatch tables for @code{switch} -statements; others represent labels to jump to or various sorts of -declarative information. - -In addition to its own specific data, each insn must have a unique -id-number that distinguishes it from all other insns in the current -function (after delayed branch scheduling, copies of an insn with the -same id-number may be present in multiple places in a function, but -these copies will always be identical and will only appear inside a -@code{sequence}), and chain pointers to the preceding and following -insns. These three fields occupy the same position in every insn, -independent of the expression code of the insn. They could be accessed -with @code{XEXP} and @code{XINT}, but instead three special macros are -always used: - -@table @code -@findex INSN_UID -@item INSN_UID (@var{i}) -Accesses the unique id of insn @var{i}. - -@findex PREV_INSN -@item PREV_INSN (@var{i}) -Accesses the chain pointer to the insn preceding @var{i}. -If @var{i} is the first insn, this is a null pointer. - -@findex NEXT_INSN -@item NEXT_INSN (@var{i}) -Accesses the chain pointer to the insn following @var{i}. -If @var{i} is the last insn, this is a null pointer. -@end table - -@findex get_insns -@findex get_last_insn -The first insn in the chain is obtained by calling @code{get_insns}; the -last insn is the result of calling @code{get_last_insn}. Within the -chain delimited by these insns, the @code{NEXT_INSN} and -@code{PREV_INSN} pointers must always correspond: if @var{insn} is not -the first insn, - -@example -NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn} -@end example - -@noindent -is always true and if @var{insn} is not the last insn, - -@example -PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn} -@end example - -@noindent -is always true. - -After delay slot scheduling, some of the insns in the chain might be -@code{sequence} expressions, which contain a vector of insns. The value -of @code{NEXT_INSN} in all but the last of these insns is the next insn -in the vector; the value of @code{NEXT_INSN} of the last insn in the vector -is the same as the value of @code{NEXT_INSN} for the @code{sequence} in -which it is contained. Similar rules apply for @code{PREV_INSN}. - -This means that the above invariants are not necessarily true for insns -inside @code{sequence} expressions. Specifically, if @var{insn} is the -first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))} -is the insn containing the @code{sequence} expression, as is the value -of @code{PREV_INSN (NEXT_INSN (@var{insn}))} is @var{insn} is the last -insn in the @code{sequence} expression. You can use these expressions -to find the containing @code{sequence} expression.@refill - -Every insn has one of the following six expression codes: - -@table @code -@findex insn -@item insn -The expression code @code{insn} is used for instructions that do not jump -and do not do function calls. @code{sequence} expressions are always -contained in insns with code @code{insn} even if one of those insns -should jump or do function calls. - -Insns with code @code{insn} have four additional fields beyond the three -mandatory ones listed above. These four are described in a table below. - -@findex jump_insn -@item jump_insn -The expression code @code{jump_insn} is used for instructions that may -jump (or, more generally, may contain @code{label_ref} expressions). If -there is an instruction to return from the current function, it is -recorded as a @code{jump_insn}. - -@findex JUMP_LABEL -@code{jump_insn} insns have the same extra fields as @code{insn} insns, -accessed in the same way and in addition contain a field -@code{JUMP_LABEL} which is defined once jump optimization has completed. - -For simple conditional and unconditional jumps, this field contains the -@code{code_label} to which this insn will (possibly conditionally) -branch. In a more complex jump, @code{JUMP_LABEL} records one of the -labels that the insn refers to; the only way to find the others -is to scan the entire body of the insn. - -Return insns count as jumps, but since they do not refer to any labels, -they have zero in the @code{JUMP_LABEL} field. - -@findex call_insn -@item call_insn -The expression code @code{call_insn} is used for instructions that may do -function calls. It is important to distinguish these instructions because -they imply that certain registers and memory locations may be altered -unpredictably. - -@findex CALL_INSN_FUNCTION_USAGE -@code{call_insn} insns have the same extra fields as @code{insn} insns, -accessed in the same way and in addition contain a field -@code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of -@code{expr_list} expressions) containing @code{use} and @code{clobber} -expressions that denote hard registers used or clobbered by the called -function. A register specified in a @code{clobber} in this list is -modified @emph{after} the execution of the @code{call_insn}, while a -register in a @code{clobber} in the body of the @code{call_insn} is -clobbered before the insn completes execution. @code{clobber} -expressions in this list augment registers specified in -@code{CALL_USED_REGISTERS} (@pxref{Register Basics}). - -@findex code_label -@findex CODE_LABEL_NUMBER -@item code_label -A @code{code_label} insn represents a label that a jump insn can jump -to. It contains two special fields of data in addition to the three -standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label -number}, a number that identifies this label uniquely among all the -labels in the compilation (not just in the current function). -Ultimately, the label is represented in the assembler output as an -assembler label, usually of the form @samp{L@var{n}} where @var{n} is -the label number. - -When a @code{code_label} appears in an RTL expression, it normally -appears within a @code{label_ref} which represents the address of -the label, as a number. - -@findex LABEL_NUSES -The field @code{LABEL_NUSES} is only defined once the jump optimization -phase is completed and contains the number of times this label is -referenced in the current function. - -@findex barrier -@item barrier -Barriers are placed in the instruction stream when control cannot flow -past them. They are placed after unconditional jump instructions to -indicate that the jumps are unconditional and after calls to -@code{volatile} functions, which do not return (e.g., @code{exit}). -They contain no information beyond the three standard fields. - -@findex note -@findex NOTE_LINE_NUMBER -@findex NOTE_SOURCE_FILE -@item note -@code{note} insns are used to represent additional debugging and -declarative information. They contain two nonstandard fields, an -integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a -string accessed with @code{NOTE_SOURCE_FILE}. - -If @code{NOTE_LINE_NUMBER} is positive, the note represents the -position of a source line and @code{NOTE_SOURCE_FILE} is the source file name -that the line came from. These notes control generation of line -number data in the assembler output. - -Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a -code with one of the following values (and @code{NOTE_SOURCE_FILE} -must contain a null pointer): - -@table @code -@findex NOTE_INSN_DELETED -@item NOTE_INSN_DELETED -Such a note is completely ignorable. Some passes of the compiler -delete insns by altering them into notes of this kind. - -@findex NOTE_INSN_BLOCK_BEG -@findex NOTE_INSN_BLOCK_END -@item NOTE_INSN_BLOCK_BEG -@itemx NOTE_INSN_BLOCK_END -These types of notes indicate the position of the beginning and end -of a level of scoping of variable names. They control the output -of debugging information. - -@findex NOTE_INSN_LOOP_BEG -@findex NOTE_INSN_LOOP_END -@item NOTE_INSN_LOOP_BEG -@itemx NOTE_INSN_LOOP_END -These types of notes indicate the position of the beginning and end -of a @code{while} or @code{for} loop. They enable the loop optimizer -to find loops quickly. - -@findex NOTE_INSN_LOOP_CONT -@item NOTE_INSN_LOOP_CONT -Appears at the place in a loop that @code{continue} statements jump to. - -@findex NOTE_INSN_LOOP_VTOP -@item NOTE_INSN_LOOP_VTOP -This note indicates the place in a loop where the exit test begins for -those loops in which the exit test has been duplicated. This position -becomes another virtual start of the loop when considering loop -invariants. - -@findex NOTE_INSN_FUNCTION_END -@item NOTE_INSN_FUNCTION_END -Appears near the end of the function body, just before the label that -@code{return} statements jump to (on machine where a single instruction -does not suffice for returning). This note may be deleted by jump -optimization. - -@findex NOTE_INSN_SETJMP -@item NOTE_INSN_SETJMP -Appears following each call to @code{setjmp} or a related function. -@end table - -These codes are printed symbolically when they appear in debugging dumps. -@end table - -@cindex @code{HImode}, in @code{insn} -@cindex @code{QImode}, in @code{insn} -The machine mode of an insn is normally @code{VOIDmode}, but some -phases use the mode for various purposes; for example, the reload pass -sets it to @code{HImode} if the insn needs reloading but not register -elimination and @code{QImode} if both are required. The common -subexpression elimination pass sets the mode of an insn to @code{QImode} -when it is the first insn in a block that has already been processed. - -Here is a table of the extra fields of @code{insn}, @code{jump_insn} -and @code{call_insn} insns: - -@table @code -@findex PATTERN -@item PATTERN (@var{i}) -An expression for the side effect performed by this insn. This must be -one of the following codes: @code{set}, @code{call}, @code{use}, -@code{clobber}, @code{return}, @code{asm_input}, @code{asm_output}, -@code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec}, -@code{unspec_volatile}, @code{parallel}, or @code{sequence}. If it is a @code{parallel}, -each element of the @code{parallel} must be one these codes, except that -@code{parallel} expressions cannot be nested and @code{addr_vec} and -@code{addr_diff_vec} are not permitted inside a @code{parallel} expression. - -@findex INSN_CODE -@item INSN_CODE (@var{i}) -An integer that says which pattern in the machine description matches -this insn, or -1 if the matching has not yet been attempted. - -Such matching is never attempted and this field remains -1 on an insn -whose pattern consists of a single @code{use}, @code{clobber}, -@code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression. - -@findex asm_noperands -Matching is also never attempted on insns that result from an @code{asm} -statement. These contain at least one @code{asm_operands} expression. -The function @code{asm_noperands} returns a non-negative value for -such insns. - -In the debugging output, this field is printed as a number followed by -a symbolic representation that locates the pattern in the @file{md} -file as some small positive or negative offset from a named pattern. - -@findex LOG_LINKS -@item LOG_LINKS (@var{i}) -A list (chain of @code{insn_list} expressions) giving information about -dependencies between instructions within a basic block. Neither a jump -nor a label may come between the related insns. - -@findex REG_NOTES -@item REG_NOTES (@var{i}) -A list (chain of @code{expr_list} and @code{insn_list} expressions) -giving miscellaneous information about the insn. It is often information -pertaining to the registers used in this insn. -@end table - -The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list} -expressions. Each of these has two operands: the first is an insn, -and the second is another @code{insn_list} expression (the next one in -the chain). The last @code{insn_list} in the chain has a null pointer -as second operand. The significant thing about the chain is which -insns appear in it (as first operands of @code{insn_list} -expressions). Their order is not significant. - -This list is originally set up by the flow analysis pass; it is a null -pointer until then. Flow only adds links for those data dependencies -which can be used for instruction combination. For each insn, the flow -analysis pass adds a link to insns which store into registers values -that are used for the first time in this insn. The instruction -scheduling pass adds extra links so that every dependence will be -represented. Links represent data dependencies, antidependencies and -output dependencies; the machine mode of the link distinguishes these -three types: antidependencies have mode @code{REG_DEP_ANTI}, output -dependencies have mode @code{REG_DEP_OUTPUT}, and data dependencies have -mode @code{VOIDmode}. - -The @code{REG_NOTES} field of an insn is a chain similar to the -@code{LOG_LINKS} field but it includes @code{expr_list} expressions in -addition to @code{insn_list} expressions. There are several kinds -of register notes, which are distinguished by the machine mode, which -in a register note is really understood as being an @code{enum reg_note}. -The first operand @var{op} of the note is data whose meaning depends on -the kind of note. - -@findex REG_NOTE_KIND -@findex PUT_REG_NOTE_KIND -The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of -register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND -(@var{x}, @var{newkind})} sets the register note type of @var{x} to be -@var{newkind}. - -Register notes are of three classes: They may say something about an -input to an insn, they may say something about an output of an insn, or -they may create a linkage between two insns. There are also a set -of values that are only used in @code{LOG_LINKS}. - -These register notes annotate inputs to an insn: - -@table @code -@findex REG_DEAD -@item REG_DEAD -The value in @var{op} dies in this insn; that is to say, altering the -value immediately after this insn would not affect the future behavior -of the program. - -This does not necessarily mean that the register @var{op} has no useful -value after this insn since it may also be an output of the insn. In -such a case, however, a @code{REG_DEAD} note would be redundant and is -usually not present until after the reload pass, but no code relies on -this fact. - -@findex REG_INC -@item REG_INC -The register @var{op} is incremented (or decremented; at this level -there is no distinction) by an embedded side effect inside this insn. -This means it appears in a @code{post_inc}, @code{pre_inc}, -@code{post_dec} or @code{pre_dec} expression. - -@findex REG_NONNEG -@item REG_NONNEG -The register @var{op} is known to have a nonnegative value when this -insn is reached. This is used so that decrement and branch until zero -instructions, such as the m68k dbra, can be matched. - -The @code{REG_NONNEG} note is added to insns only if the machine -description has a @samp{decrement_and_branch_until_zero} pattern. - -@findex REG_NO_CONFLICT -@item REG_NO_CONFLICT -This insn does not cause a conflict between @var{op} and the item -being set by this insn even though it might appear that it does. -In other words, if the destination register and @var{op} could -otherwise be assigned the same register, this insn does not -prevent that assignment. - -Insns with this note are usually part of a block that begins with a -@code{clobber} insn specifying a multi-word pseudo register (which will -be the output of the block), a group of insns that each set one word of -the value and have the @code{REG_NO_CONFLICT} note attached, and a final -insn that copies the output to itself with an attached @code{REG_EQUAL} -note giving the expression being computed. This block is encapsulated -with @code{REG_LIBCALL} and @code{REG_RETVAL} notes on the first and -last insns, respectively. - -@findex REG_LABEL -@item REG_LABEL -This insn uses @var{op}, a @code{code_label}, but is not a -@code{jump_insn}. The presence of this note allows jump optimization to -be aware that @var{op} is, in fact, being used. -@end table - -The following notes describe attributes of outputs of an insn: - -@table @code -@findex REG_EQUIV -@findex REG_EQUAL -@item REG_EQUIV -@itemx REG_EQUAL -This note is only valid on an insn that sets only one register and -indicates that that register will be equal to @var{op} at run time; the -scope of this equivalence differs between the two types of notes. The -value which the insn explicitly copies into the register may look -different from @var{op}, but they will be equal at run time. If the -output of the single @code{set} is a @code{strict_low_part} expression, -the note refers to the register that is contained in @code{SUBREG_REG} -of the @code{subreg} expression. - -For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout -the entire function, and could validly be replaced in all its -occurrences by @var{op}. (``Validly'' here refers to the data flow of -the program; simple replacement may make some insns invalid.) For -example, when a constant is loaded into a register that is never -assigned any other value, this kind of note is used. - -When a parameter is copied into a pseudo-register at entry to a function, -a note of this kind records that the register is equivalent to the stack -slot where the parameter was passed. Although in this case the register -may be set by other insns, it is still valid to replace the register -by the stack slot throughout the function. - -In the case of @code{REG_EQUAL}, the register that is set by this insn -will be equal to @var{op} at run time at the end of this insn but not -necessarily elsewhere in the function. In this case, @var{op} -is typically an arithmetic expression. For example, when a sequence of -insns such as a library call is used to perform an arithmetic operation, -this kind of note is attached to the insn that produces or copies the -final value. - -These two notes are used in different ways by the compiler passes. -@code{REG_EQUAL} is used by passes prior to register allocation (such as -common subexpression elimination and loop optimization) to tell them how -to think of that value. @code{REG_EQUIV} notes are used by register -allocation to indicate that there is an available substitute expression -(either a constant or a @code{mem} expression for the location of a -parameter on the stack) that may be used in place of a register if -insufficient registers are available. - -Except for stack homes for parameters, which are indicated by a -@code{REG_EQUIV} note and are not useful to the early optimization -passes and pseudo registers that are equivalent to a memory location -throughout there entire life, which is not detected until later in -the compilation, all equivalences are initially indicated by an attached -@code{REG_EQUAL} note. In the early stages of register allocation, a -@code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if -@var{op} is a constant and the insn represents the only set of its -destination register. - -Thus, compiler passes prior to register allocation need only check for -@code{REG_EQUAL} notes and passes subsequent to register allocation -need only check for @code{REG_EQUIV} notes. - -@findex REG_UNUSED -@item REG_UNUSED -The register @var{op} being set by this insn will not be used in a -subsequent insn. This differs from a @code{REG_DEAD} note, which -indicates that the value in an input will not be used subsequently. -These two notes are independent; both may be present for the same -register. - -@findex REG_WAS_0 -@item REG_WAS_0 -The single output of this insn contained zero before this insn. -@var{op} is the insn that set it to zero. You can rely on this note if -it is present and @var{op} has not been deleted or turned into a @code{note}; -its absence implies nothing. -@end table - -These notes describe linkages between insns. They occur in pairs: one -insn has one of a pair of notes that points to a second insn, which has -the inverse note pointing back to the first insn. - -@table @code -@findex REG_RETVAL -@item REG_RETVAL -This insn copies the value of a multi-insn sequence (for example, a -library call), and @var{op} is the first insn of the sequence (for a -library call, the first insn that was generated to set up the arguments -for the library call). - -Loop optimization uses this note to treat such a sequence as a single -operation for code motion purposes and flow analysis uses this note to -delete such sequences whose results are dead. - -A @code{REG_EQUAL} note will also usually be attached to this insn to -provide the expression being computed by the sequence. - -@findex REG_LIBCALL -@item REG_LIBCALL -This is the inverse of @code{REG_RETVAL}: it is placed on the first -insn of a multi-insn sequence, and it points to the last one. - -@findex REG_CC_SETTER -@findex REG_CC_USER -@item REG_CC_SETTER -@itemx REG_CC_USER -On machines that use @code{cc0}, the insns which set and use @code{cc0} -set and use @code{cc0} are adjacent. However, when branch delay slot -filling is done, this may no longer be true. In this case a -@code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to -point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will -be placed on the insn using @code{cc0} to point to the insn setting -@code{cc0}.@refill -@end table - -These values are only used in the @code{LOG_LINKS} field, and indicate -the type of dependency that each link represents. Links which indicate -a data dependence (a read after write dependence) do not use any code, -they simply have mode @code{VOIDmode}, and are printed without any -descriptive text. - -@table @code -@findex REG_DEP_ANTI -@item REG_DEP_ANTI -This indicates an anti dependence (a write after read dependence). - -@findex REG_DEP_OUTPUT -@item REG_DEP_OUTPUT -This indicates an output dependence (a write after write dependence). -@end table - -For convenience, the machine mode in an @code{insn_list} or -@code{expr_list} is printed using these symbolic codes in debugging dumps. - -@findex insn_list -@findex expr_list -The only difference between the expression codes @code{insn_list} and -@code{expr_list} is that the first operand of an @code{insn_list} is -assumed to be an insn and is printed in debugging dumps as the insn's -unique id; the first operand of an @code{expr_list} is printed in the -ordinary way as an expression. - -@node Calls, Sharing, Insns, RTL -@section RTL Representation of Function-Call Insns -@cindex calling functions in RTL -@cindex RTL function-call insns -@cindex function-call insns - -Insns that call subroutines have the RTL expression code @code{call_insn}. -These insns must satisfy special rules, and their bodies must use a special -RTL expression code, @code{call}. - -@cindex @code{call} usage -A @code{call} expression has two operands, as follows: - -@example -(call (mem:@var{fm} @var{addr}) @var{nbytes}) -@end example - -@noindent -Here @var{nbytes} is an operand that represents the number of bytes of -argument data being passed to the subroutine, @var{fm} is a machine mode -(which must equal as the definition of the @code{FUNCTION_MODE} macro in -the machine description) and @var{addr} represents the address of the -subroutine. - -For a subroutine that returns no value, the @code{call} expression as -shown above is the entire body of the insn, except that the insn might -also contain @code{use} or @code{clobber} expressions. - -@cindex @code{BLKmode}, and function return values -For a subroutine that returns a value whose mode is not @code{BLKmode}, -the value is returned in a hard register. If this register's number is -@var{r}, then the body of the call insn looks like this: - -@example -(set (reg:@var{m} @var{r}) - (call (mem:@var{fm} @var{addr}) @var{nbytes})) -@end example - -@noindent -This RTL expression makes it clear (to the optimizer passes) that the -appropriate register receives a useful value in this insn. - -When a subroutine returns a @code{BLKmode} value, it is handled by -passing to the subroutine the address of a place to store the value. -So the call insn itself does not ``return'' any value, and it has the -same RTL form as a call that returns nothing. - -On some machines, the call instruction itself clobbers some register, -for example to contain the return address. @code{call_insn} insns -on these machines should have a body which is a @code{parallel} -that contains both the @code{call} expression and @code{clobber} -expressions that indicate which registers are destroyed. Similarly, -if the call instruction requires some register other than the stack -pointer that is not explicitly mentioned it its RTL, a @code{use} -subexpression should mention that register. - -Functions that are called are assumed to modify all registers listed in -the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register -Basics}) and, with the exception of @code{const} functions and library -calls, to modify all of memory. - -Insns containing just @code{use} expressions directly precede the -@code{call_insn} insn to indicate which registers contain inputs to the -function. Similarly, if registers other than those in -@code{CALL_USED_REGISTERS} are clobbered by the called function, insns -containing a single @code{clobber} follow immediately after the call to -indicate which registers. - -@node Sharing -@section Structure Sharing Assumptions -@cindex sharing of RTL components -@cindex RTL structure sharing assumptions - -The compiler assumes that certain kinds of RTL expressions are unique; -there do not exist two distinct objects representing the same value. -In other cases, it makes an opposite assumption: that no RTL expression -object of a certain kind appears in more than one place in the -containing structure. - -These assumptions refer to a single function; except for the RTL -objects that describe global variables and external functions, -and a few standard objects such as small integer constants, -no RTL objects are common to two functions. - -@itemize @bullet -@cindex @code{reg}, RTL sharing -@item -Each pseudo-register has only a single @code{reg} object to represent it, -and therefore only a single machine mode. - -@cindex symbolic label -@cindex @code{symbol_ref}, RTL sharing -@item -For any symbolic label, there is only one @code{symbol_ref} object -referring to it. - -@cindex @code{const_int}, RTL sharing -@item -There is only one @code{const_int} expression with value 0, only -one with value 1, and only one with value @minus{}1. -Some other integer values are also stored uniquely. - -@cindex @code{pc}, RTL sharing -@item -There is only one @code{pc} expression. - -@cindex @code{cc0}, RTL sharing -@item -There is only one @code{cc0} expression. - -@cindex @code{const_double}, RTL sharing -@item -There is only one @code{const_double} expression with value 0 for -each floating point mode. Likewise for values 1 and 2. - -@cindex @code{label_ref}, RTL sharing -@cindex @code{scratch}, RTL sharing -@item -No @code{label_ref} or @code{scratch} appears in more than one place in -the RTL structure; in other words, it is safe to do a tree-walk of all -the insns in the function and assume that each time a @code{label_ref} -or @code{scratch} is seen it is distinct from all others that are seen. - -@cindex @code{mem}, RTL sharing -@item -Only one @code{mem} object is normally created for each static -variable or stack slot, so these objects are frequently shared in all -the places they appear. However, separate but equal objects for these -variables are occasionally made. - -@cindex @code{asm_operands}, RTL sharing -@item -When a single @code{asm} statement has multiple output operands, a -distinct @code{asm_operands} expression is made for each output operand. -However, these all share the vector which contains the sequence of input -operands. This sharing is used later on to test whether two -@code{asm_operands} expressions come from the same statement, so all -optimizations must carefully preserve the sharing if they copy the -vector at all. - -@item -No RTL object appears in more than one place in the RTL structure -except as described above. Many passes of the compiler rely on this -by assuming that they can modify RTL objects in place without unwanted -side-effects on other insns. - -@findex unshare_all_rtl -@item -During initial RTL generation, shared structure is freely introduced. -After all the RTL for a function has been generated, all shared -structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c}, -after which the above rules are guaranteed to be followed. - -@findex copy_rtx_if_shared -@item -During the combiner pass, shared structure within an insn can exist -temporarily. However, the shared structure is copied before the -combiner is finished with the insn. This is done by calling -@code{copy_rtx_if_shared}, which is a subroutine of -@code{unshare_all_rtl}. -@end itemize - -@node Reading RTL -@section Reading RTL - -To read an RTL object from a file, call @code{read_rtx}. It takes one -argument, a stdio stream, and returns a single RTL object. - -Reading RTL from a file is very slow. This is no currently not a -problem because reading RTL occurs only as part of building the -compiler. - -People frequently have the idea of using RTL stored as text in a file as -an interface between a language front end and the bulk of GNU CC. This -idea is not feasible. - -GNU CC was designed to use RTL internally only. Correct RTL for a given -program is very dependent on the particular target machine. And the RTL -does not contain all the information about the program. - -The proper way to interface GNU CC to a new language front end is with -the ``tree'' data structure. There is no manual for this data -structure, but it is described in the files @file{tree.h} and -@file{tree.def}. |
