**/*.texi: Reorder index entries

[thirdparty/gcc.git] / gcc / doc / rtl.texi

@c Copyright (C) 1988-2023 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)

The last part of the compiler work is done on a low-level 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.
* RTL Classes::       Categories of RTL expression objects, and their structure.
* Accessors::         Macros to access expression operands or vector elts.
* Special Accessors:: Macros to access specific annotations on RTL.
* 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 bit-fields in memory or reg.
* Vector Operations:: Expressions involving vector datatypes.
* 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.
* Debug Information:: Expressions representing debugging information.
* Insns::             Expression types for entire insns.
* Calls::             RTL representation of function call insns.
* RTL SSA::           An on-the-side SSA form for RTL
* Sharing::           Some expressions are unique; others *must* be copied.
* Reading RTL::       Reading textual RTL from a file.
@end menu

@node RTL Objects
@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}; 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.

In a machine description, strings are normally written with double
quotes, as you would in C@.  However, strings in machine descriptions may
extend over many lines, which is invalid C, and adjacent string
constants are not concatenated as they are in C@.  Any string constant
may be surrounded with a single set of parentheses.  Sometimes this
makes the machine description easier to read.

There is also a special syntax for strings, which can be useful when C
code is embedded in a machine description.  Wherever a string can
appear, it is also valid to write a C-style brace block.  The entire
brace block, including the outermost pair of braces, is considered to be
the string constant.  Double quote characters inside the braces are not
special.  Therefore, if you write string constants in the C code, you
need not escape each quote character with a backslash.

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 uppercase) 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 a polynomial
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 lowercase,
but when they appear in C code they are written in uppercase.  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 RTL Classes
@section RTL Classes and Formats
@cindex RTL classes
@cindex classes of RTX codes
@cindex RTX codes, classes of
@findex GET_RTX_CLASS

The various expression codes are divided into several @dfn{classes},
which are represented by single characters.  You can determine the class
of an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}.
Currently, @file{rtl.def} defines these classes:

@table @code
@item RTX_OBJ
An RTX code that represents an actual object, such as a register
(@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}).
@code{LO_SUM} is also included; instead, @code{SUBREG} and
@code{STRICT_LOW_PART} are not in this class, but in class
@code{RTX_EXTRA}.

@item RTX_CONST_OBJ
An RTX code that represents a constant object.  @code{HIGH} is also
included in this class.

@item RTX_COMPARE
An RTX code for a non-symmetric comparison, such as @code{GEU} or
@code{LT}.

@item RTX_COMM_COMPARE
An RTX code for a symmetric (commutative) comparison, such as @code{EQ}
or @code{ORDERED}.

@item RTX_UNARY
An RTX code for a unary arithmetic operation, such as @code{NEG},
@code{NOT}, or @code{ABS}.  This category also includes value extension
(sign or zero) and conversions between integer and floating point.

@item RTX_COMM_ARITH
An RTX code for a commutative binary operation, such as @code{PLUS} or
@code{AND}.  @code{NE} and @code{EQ} are comparisons, so they have class
@code{RTX_COMM_COMPARE}.

@item RTX_BIN_ARITH
An RTX code for a non-commutative binary operation, such as @code{MINUS},
@code{DIV}, or @code{ASHIFTRT}.

@item RTX_BITFIELD_OPS
An RTX code for a bit-field operation.  Currently only
@code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}.  These have three inputs
and are lvalues (so they can be used for insertion as well).
@xref{Bit-Fields}.

@item RTX_TERNARY
An RTX code for other three input operations.  Currently only
@code{IF_THEN_ELSE},  @code{VEC_MERGE}, @code{SIGN_EXTRACT},
@code{ZERO_EXTRACT}, and @code{FMA}.

@item RTX_INSN
An RTX code for an entire instruction:  @code{INSN}, @code{JUMP_INSN}, and
@code{CALL_INSN}.  @xref{Insns}.

@item RTX_MATCH
An RTX code for something that matches in insns, such as
@code{MATCH_DUP}.  These only occur in machine descriptions.

@item RTX_AUTOINC
An RTX code for an auto-increment addressing mode, such as
@code{POST_INC}.  @samp{XEXP (@var{x}, 0)} gives the auto-modified
register.

@item RTX_EXTRA
All other RTX codes.  This category includes the remaining codes used
only in machine descriptions (@code{DEFINE_*}, etc.).  It also includes
all the codes describing side effects (@code{SET}, @code{USE},
@code{CLOBBER}, etc.) and the non-insns that may appear on an insn
chain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}.
@code{SUBREG} is also part of this class.
@end table

@cindex RTL format
For each expression code, @file{rtl.def} specifies the number of
contained objects and their kinds using a sequence of characters
called the @dfn{format} of the expression code.  For example,
the format of @code{subreg} is @samp{ep}.

@cindex RTL format characters
These are the most commonly used format characters:

@table @code
@item e
An expression (actually a pointer to an expression).

@item i
An integer.

@item w
A wide integer.

@item s
A string.

@item E
A vector of expressions.
@end table

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 B
@samp{B} indicates a pointer to basic block structure.

@item p
A polynomial integer.  At present this is used only for @code{SUBREG_BYTE}.

@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 and the format
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.
@end table

Some classes of RTX codes always have the same format.  For example, it
is safe to assume that all comparison operations have format @code{ee}.

@table @code
@item RTX_UNARY
All codes of this class have format @code{e}.

@item RTX_BIN_ARITH
@itemx RTX_COMM_ARITH
@itemx RTX_COMM_COMPARE
@itemx RTX_COMPARE
All codes of these classes have format @code{ee}.

@item RTX_BITFIELD_OPS
@itemx RTX_TERNARY
All codes of these classes have format @code{eee}.

@item RTX_INSN
All codes of this class have formats that begin with @code{iuueiee}.
@xref{Insns}.  Note that not all RTL objects linked onto an insn chain
are of class @code{RTX_INSN}.

@item RTX_CONST_OBJ
@itemx RTX_OBJ
@itemx RTX_MATCH
@itemx RTX_EXTRA
You can make no assumptions about the format of these codes.
@end table

@node Accessors
@section Access to Operands
@cindex accessors
@cindex access to operands
@cindex operand access

@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,

@smallexample
XEXP (@var{x}, 2)
@end smallexample

@noindent
accesses operand 2 of expression @var{x}, as an expression.

@smallexample
XINT (@var{x}, 2)
@end smallexample

@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 an @code{int_list} expression, you know that it has
two operands which can be correctly accessed as @code{XINT (@var{x}, 0)}
and @code{XEXP (@var{x}, 1)}.  Incorrect accesses like
@code{XEXP (@var{x}, 0)} and @code{XINT (@var{x}, 1)} would compile,
but would trigger an internal compiler error when rtl checking is enabled.
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.

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 Special Accessors
@section Access to Special Operands
@cindex access to special operands

Some RTL nodes have special annotations associated with them.

@table @code
@item MEM
@table @code
@findex MEM_ALIAS_SET
@item MEM_ALIAS_SET (@var{x})
If 0, @var{x} is not in any alias set, and may alias anything.  Otherwise,
@var{x} can only alias @code{MEM}s in a conflicting alias set.  This value
is set in a language-dependent manner in the front-end, and should not be
altered in the back-end.  In some front-ends, these numbers may correspond
in some way to types, or other language-level entities, but they need not,
and the back-end makes no such assumptions.
These set numbers are tested with @code{alias_sets_conflict_p}.

@findex MEM_EXPR
@item MEM_EXPR (@var{x})
If this register is known to hold the value of some user-level
declaration, this is that tree node.  It may also be a
@code{COMPONENT_REF}, in which case this is some field reference,
and @code{TREE_OPERAND (@var{x}, 0)} contains the declaration,
or another @code{COMPONENT_REF}, or null if there is no compile-time
object associated with the reference.

@findex MEM_OFFSET_KNOWN_P
@item MEM_OFFSET_KNOWN_P (@var{x})
True if the offset of the memory reference from @code{MEM_EXPR} is known.
@samp{MEM_OFFSET (@var{x})} provides the offset if so.

@findex MEM_OFFSET
@item MEM_OFFSET (@var{x})
The offset from the start of @code{MEM_EXPR}.  The value is only valid if
@samp{MEM_OFFSET_KNOWN_P (@var{x})} is true.

@findex MEM_SIZE_KNOWN_P
@item MEM_SIZE_KNOWN_P (@var{x})
True if the size of the memory reference is known.
@samp{MEM_SIZE (@var{x})} provides its size if so.

@findex MEM_SIZE
@item MEM_SIZE (@var{x})
The size in bytes of the memory reference.
This is mostly relevant for @code{BLKmode} references as otherwise
the size is implied by the mode.  The value is only valid if
@samp{MEM_SIZE_KNOWN_P (@var{x})} is true.

@findex MEM_ALIGN
@item MEM_ALIGN (@var{x})
The known alignment in bits of the memory reference.

@findex MEM_ADDR_SPACE
@item MEM_ADDR_SPACE (@var{x})
The address space of the memory reference.  This will commonly be zero
for the generic address space.
@end table

@item REG
@table @code
@findex ORIGINAL_REGNO
@item ORIGINAL_REGNO (@var{x})
This field holds the number the register ``originally'' had; for a
pseudo register turned into a hard reg this will hold the old pseudo
register number.

@findex REG_EXPR
@item REG_EXPR (@var{x})
If this register is known to hold the value of some user-level
declaration, this is that tree node.

@findex REG_OFFSET
@item REG_OFFSET (@var{x})
If this register is known to hold the value of some user-level
declaration, this is the offset into that logical storage.
@end table

@item SYMBOL_REF
@table @code
@findex SYMBOL_REF_DECL
@item SYMBOL_REF_DECL (@var{x})
If the @code{symbol_ref} @var{x} was created for a @code{VAR_DECL} or
a @code{FUNCTION_DECL}, that tree is recorded here.  If this value is
null, then @var{x} was created by back end code generation routines,
and there is no associated front end symbol table entry.

@code{SYMBOL_REF_DECL} may also point to a tree of class @code{'c'},
that is, some sort of constant.  In this case, the @code{symbol_ref}
is an entry in the per-file constant pool; again, there is no associated
front end symbol table entry.

@findex SYMBOL_REF_CONSTANT
@item SYMBOL_REF_CONSTANT (@var{x})
If @samp{CONSTANT_POOL_ADDRESS_P (@var{x})} is true, this is the constant
pool entry for @var{x}.  It is null otherwise.

@findex SYMBOL_REF_DATA
@item SYMBOL_REF_DATA (@var{x})
A field of opaque type used to store @code{SYMBOL_REF_DECL} or
@code{SYMBOL_REF_CONSTANT}.

@findex SYMBOL_REF_FLAGS
@item SYMBOL_REF_FLAGS (@var{x})
In a @code{symbol_ref}, this is used to communicate various predicates
about the symbol.  Some of these are common enough to be computed by
common code, some are specific to the target.  The common bits are:

@table @code
@findex SYMBOL_REF_FUNCTION_P
@findex SYMBOL_FLAG_FUNCTION
@item SYMBOL_FLAG_FUNCTION
Set if the symbol refers to a function.

@findex SYMBOL_REF_LOCAL_P
@findex SYMBOL_FLAG_LOCAL
@item SYMBOL_FLAG_LOCAL
Set if the symbol is local to this ``module''.
See @code{TARGET_BINDS_LOCAL_P}.

@findex SYMBOL_REF_EXTERNAL_P
@findex SYMBOL_FLAG_EXTERNAL
@item SYMBOL_FLAG_EXTERNAL
Set if this symbol is not defined in this translation unit.
Note that this is not the inverse of @code{SYMBOL_FLAG_LOCAL}.

@findex SYMBOL_REF_SMALL_P
@findex SYMBOL_FLAG_SMALL
@item SYMBOL_FLAG_SMALL
Set if the symbol is located in the small data section.
See @code{TARGET_IN_SMALL_DATA_P}.

@findex SYMBOL_FLAG_TLS_SHIFT
@findex SYMBOL_REF_TLS_MODEL
@item SYMBOL_REF_TLS_MODEL (@var{x})
This is a multi-bit field accessor that returns the @code{tls_model}
to be used for a thread-local storage symbol.  It returns zero for
non-thread-local symbols.

@findex SYMBOL_REF_HAS_BLOCK_INFO_P
@findex SYMBOL_FLAG_HAS_BLOCK_INFO
@item SYMBOL_FLAG_HAS_BLOCK_INFO
Set if the symbol has @code{SYMBOL_REF_BLOCK} and
@code{SYMBOL_REF_BLOCK_OFFSET} fields.

@findex SYMBOL_REF_ANCHOR_P
@findex SYMBOL_FLAG_ANCHOR
@cindex @option{-fsection-anchors}
@item SYMBOL_FLAG_ANCHOR
Set if the symbol is used as a section anchor.  ``Section anchors''
are symbols that have a known position within an @code{object_block}
and that can be used to access nearby members of that block.
They are used to implement @option{-fsection-anchors}.

If this flag is set, then @code{SYMBOL_FLAG_HAS_BLOCK_INFO} will be too.
@end table

Bits beginning with @code{SYMBOL_FLAG_MACH_DEP} are available for
the target's use.
@end table

@findex SYMBOL_REF_BLOCK
@item SYMBOL_REF_BLOCK (@var{x})
If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the
@samp{object_block} structure to which the symbol belongs,
or @code{NULL} if it has not been assigned a block.

@findex SYMBOL_REF_BLOCK_OFFSET
@item SYMBOL_REF_BLOCK_OFFSET (@var{x})
If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the offset of @var{x}
from the first object in @samp{SYMBOL_REF_BLOCK (@var{x})}.  The value is
negative if @var{x} has not yet been assigned to a block, or it has not
been given an offset within that block.
@end table

@node Flags
@section Flags in an RTL Expression
@cindex flags in RTL expression

RTL expressions contain several flags (one-bit bit-fields)
that are used in certain types of expression.  Most often they
are accessed with the following macros, which expand into lvalues.

@table @code
@findex CROSSING_JUMP_P
@cindex @code{jump_insn} and @samp{/j}
@item CROSSING_JUMP_P (@var{x})
Nonzero in a @code{jump_insn} if it crosses between hot and cold sections,
which could potentially be very far apart in the executable.  The presence
of this flag indicates to other optimizations that this branching instruction
should not be ``collapsed'' into a simpler branching construct.  It is used
when the optimization to partition basic blocks into hot and cold sections
is turned on.

@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 constant pool.  For most targets these addresses are in a
@code{.rodata} section entirely separate from the function, but for
some targets the addresses are close to the beginning of the function.
In either case GCC assumes these addresses can be addressed directly,
perhaps with the help of base registers.
Stored in the @code{unchanging} field and printed as @samp{/u}.

@findex INSN_ANNULLED_BRANCH_P
@cindex @code{jump_insn} and @samp{/u}
@cindex @code{call_insn} and @samp{/u}
@cindex @code{insn} and @samp{/u}
@cindex @code{unchanging}, in @code{jump_insn}, @code{call_insn} and @code{insn}
@item INSN_ANNULLED_BRANCH_P (@var{x})
In a @code{jump_insn}, @code{call_insn}, or @code{insn} indicates
that the branch is an annulling one.  See the discussion under
@code{sequence} below.  Stored in the @code{unchanging} field and
printed as @samp{/u}.

@findex INSN_DELETED_P
@cindex @code{insn} and @samp{/v}
@cindex @code{call_insn} and @samp{/v}
@cindex @code{jump_insn} and @samp{/v}
@cindex @code{code_label} and @samp{/v}
@cindex @code{jump_table_data} and @samp{/v}
@cindex @code{barrier} and @samp{/v}
@cindex @code{note} and @samp{/v}
@cindex @code{volatil}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, @code{jump_table_data}, @code{barrier}, and @code{note}
@item INSN_DELETED_P (@var{x})
In an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label},
@code{jump_table_data}, @code{barrier}, or @code{note},
nonzero if the insn has been deleted.  Stored in the
@code{volatil} field and printed as @samp{/v}.

@findex INSN_FROM_TARGET_P
@cindex @code{insn} and @samp{/s}
@cindex @code{jump_insn} and @samp{/s}
@cindex @code{call_insn} and @samp{/s}
@cindex @code{in_struct}, in @code{insn} and @code{jump_insn} and @code{call_insn}
@item INSN_FROM_TARGET_P (@var{x})
In an @code{insn} or @code{jump_insn} or @code{call_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 will only be executed if
the branch is taken.  For annulled branches with
@code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the
branch is not taken.  When @code{INSN_ANNULLED_BRANCH_P} is not set,
this insn will always be executed.  Stored in the @code{in_struct}
field and printed as @samp{/s}.

@findex LABEL_PRESERVE_P
@cindex @code{code_label} and @samp{/i}
@cindex @code{note} and @samp{/i}
@cindex @code{in_struct}, in @code{code_label} and @code{note}
@item LABEL_PRESERVE_P (@var{x})
In a @code{code_label} or @code{note}, indicates that the label is referenced by
code or data not visible to the RTL of a given function.
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 LABEL_REF_NONLOCAL_P
@cindex @code{label_ref} and @samp{/v}
@cindex @code{reg_label} and @samp{/v}
@cindex @code{volatil}, in @code{label_ref} and @code{reg_label}
@item LABEL_REF_NONLOCAL_P (@var{x})
In @code{label_ref} and @code{reg_label} expressions, nonzero if this is
a reference to a non-local label.
Stored in the @code{volatil} field and printed as @samp{/v}.

@findex MEM_KEEP_ALIAS_SET_P
@cindex @code{mem} and @samp{/j}
@cindex @code{jump}, in @code{mem}
@item MEM_KEEP_ALIAS_SET_P (@var{x})
In @code{mem} expressions, 1 if we should keep the alias set for this
mem unchanged when we access a component.  Set to 1, for example, when we
are already in a non-addressable component of an aggregate.
Stored in the @code{jump} field and printed as @samp{/j}.

@findex MEM_VOLATILE_P
@cindex @code{mem} and @samp{/v}
@cindex @code{asm_input} and @samp{/v}
@cindex @code{asm_operands} and @samp{/v}
@cindex @code{volatil}, in @code{mem}, @code{asm_operands}, and @code{asm_input}
@item MEM_VOLATILE_P (@var{x})
In @code{mem}, @code{asm_operands}, and @code{asm_input} expressions,
nonzero for volatile memory references.
Stored in the @code{volatil} field and printed as @samp{/v}.

@findex MEM_NOTRAP_P
@cindex @code{mem} and @samp{/c}
@cindex @code{call}, in @code{mem}
@item MEM_NOTRAP_P (@var{x})
In @code{mem}, nonzero for memory references that will not trap.
Stored in the @code{call} field and printed as @samp{/c}.

@findex MEM_POINTER
@cindex @code{mem} and @samp{/f}
@cindex @code{frame_related}, in @code{mem}
@item MEM_POINTER (@var{x})
Nonzero in a @code{mem} if the memory reference holds a pointer.
Stored in the @code{frame_related} field and printed as @samp{/f}.

@findex MEM_READONLY_P
@cindex @code{mem} and @samp{/u}
@cindex @code{unchanging}, in @code{mem}
@item MEM_READONLY_P (@var{x})
Nonzero in a @code{mem}, if the memory is statically allocated and read-only.

Read-only in this context means never modified during the lifetime of the
program, not necessarily in ROM or in write-disabled pages.  A common
example of the later is a shared library's global offset table.  This
table is initialized by the runtime loader, so the memory is technically
writable, but after control is transferred from the runtime loader to the
application, this memory will never be subsequently modified.

Stored in the @code{unchanging} field and printed as @samp{/u}.

@findex PREFETCH_SCHEDULE_BARRIER_P
@cindex @code{prefetch} and @samp{/v}
@cindex @code{volatile}, in @code{prefetch}
@item PREFETCH_SCHEDULE_BARRIER_P (@var{x})
In a @code{prefetch}, indicates that the prefetch is a scheduling barrier.
No other INSNs will be moved over it.
Stored in the @code{volatil} field and printed as @samp{/v}.

@findex REG_FUNCTION_VALUE_P
@cindex @code{reg} and @samp{/i}
@cindex @code{return_val}, 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{return_val} field and printed as
@samp{/i}.

@findex REG_POINTER
@cindex @code{reg} and @samp{/f}
@cindex @code{frame_related}, in @code{reg}
@item REG_POINTER (@var{x})
Nonzero in a @code{reg} if the register holds a pointer.  Stored in the
@code{frame_related} field and printed as @samp{/f}.

@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}.

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 RTL_CONST_CALL_P
@cindex @code{call_insn} and @samp{/u}
@cindex @code{unchanging}, in @code{call_insn}
@item RTL_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 RTL_PURE_CALL_P
@cindex @code{call_insn} and @samp{/i}
@cindex @code{return_val}, in @code{call_insn}
@item RTL_PURE_CALL_P (@var{x})
In a @code{call_insn} indicates that the insn represents a call to a
pure function.  Stored in the @code{return_val} field and printed as
@samp{/i}.

@findex RTL_CONST_OR_PURE_CALL_P
@cindex @code{call_insn} and @samp{/u} or @samp{/i}
@item RTL_CONST_OR_PURE_CALL_P (@var{x})
In a @code{call_insn}, true if @code{RTL_CONST_CALL_P} or
@code{RTL_PURE_CALL_P} is true.

@findex RTL_LOOPING_CONST_OR_PURE_CALL_P
@cindex @code{call_insn} and @samp{/c}
@cindex @code{call}, in @code{call_insn}
@item RTL_LOOPING_CONST_OR_PURE_CALL_P (@var{x})
In a @code{call_insn} indicates that the insn represents a possibly
infinite looping call to a const or pure function.  Stored in the
@code{call} field and printed as @samp{/c}.  Only true if one of
@code{RTL_CONST_CALL_P} or @code{RTL_PURE_CALL_P} is true.

@findex RTX_FRAME_RELATED_P
@cindex @code{insn} and @samp{/f}
@cindex @code{call_insn} and @samp{/f}
@cindex @code{jump_insn} and @samp{/f}
@cindex @code{barrier} and @samp{/f}
@cindex @code{set} and @samp{/f}
@cindex @code{frame_related}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, and @code{set}
@item RTX_FRAME_RELATED_P (@var{x})
Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn},
@code{barrier}, or @code{set} which is part of a function prologue
and sets the stack pointer, sets the frame pointer, or saves a register.
This flag should also be set on an instruction that sets up a temporary
register to use in place of the frame pointer.
Stored in the @code{frame_related} field and printed as @samp{/f}.

In particular, on RISC targets where there are limits on the sizes of
immediate constants, it is sometimes impossible to reach the register
save area directly from the stack pointer.  In that case, a temporary
register is used that is near enough to the register save area, and the
Canonical Frame Address, i.e., DWARF2's logical frame pointer, register
must (temporarily) be changed to be this temporary register.  So, the
instruction that sets this temporary register must be marked as
@code{RTX_FRAME_RELATED_P}.

If the marked instruction is overly complex (defined in terms of what
@code{dwarf2out_frame_debug_expr} can handle), you will also have to
create a @code{REG_FRAME_RELATED_EXPR} note and attach it to the
instruction.  This note should contain a simple expression of the
computation performed by this instruction, i.e., one that
@code{dwarf2out_frame_debug_expr} can handle.

This flag is required for exception handling support on targets with RTL
prologues.

@findex SCHED_GROUP_P
@cindex @code{insn} and @samp{/s}
@cindex @code{call_insn} and @samp{/s}
@cindex @code{jump_insn} and @samp{/s}
@cindex @code{jump_table_data} and @samp{/s}
@cindex @code{in_struct}, in @code{insn}, @code{call_insn}, @code{jump_insn} and @code{jump_table_data}
@item SCHED_GROUP_P (@var{x})
During instruction scheduling, in an @code{insn}, @code{call_insn},
@code{jump_insn} or @code{jump_table_data}, 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}.

@findex SET_IS_RETURN_P
@cindex @code{insn} and @samp{/j}
@cindex @code{jump}, in @code{insn}
@item SET_IS_RETURN_P (@var{x})
For a @code{set}, nonzero if it is for a return.
Stored in the @code{jump} field and printed as @samp{/j}.

@findex SIBLING_CALL_P
@cindex @code{call_insn} and @samp{/j}
@cindex @code{jump}, in @code{call_insn}
@item SIBLING_CALL_P (@var{x})
For a @code{call_insn}, nonzero if the insn is a sibling call.
Stored in the @code{jump} field and printed as @samp{/j}.

@findex STRING_POOL_ADDRESS_P
@cindex @code{symbol_ref} and @samp{/f}
@cindex @code{frame_related}, in @code{symbol_ref}
@item STRING_POOL_ADDRESS_P (@var{x})
For a @code{symbol_ref} expression, nonzero if it addresses this function's
string constant pool.
Stored in the @code{frame_related} field and printed as @samp{/f}.

@findex SUBREG_PROMOTED_UNSIGNED_P
@cindex @code{subreg} and @samp{/u} and @samp{/v}
@cindex @code{unchanging}, in @code{subreg}
@cindex @code{volatil}, in @code{subreg}
@item SUBREG_PROMOTED_UNSIGNED_P (@var{x})
Returns a value greater then zero for a @code{subreg} that has
@code{SUBREG_PROMOTED_VAR_P} nonzero if the object being referenced is kept
zero-extended, zero if it is kept sign-extended, and less then zero if it is
extended some other way via the @code{ptr_extend} instruction.
Stored in the @code{unchanging}
field and @code{volatil} field, printed as @samp{/u} and @samp{/v}.
This macro may only be used to get the value it may not be used to change
the value.  Use @code{SUBREG_PROMOTED_UNSIGNED_SET} to change the value.

@findex SUBREG_PROMOTED_UNSIGNED_SET
@cindex @code{subreg} and @samp{/u}
@cindex @code{unchanging}, in @code{subreg}
@cindex @code{volatil}, in @code{subreg}
@item SUBREG_PROMOTED_UNSIGNED_SET (@var{x})
Set the @code{unchanging} and @code{volatil} fields in a @code{subreg}
to reflect zero, sign, or other extension.  If @code{volatil} is
zero, then @code{unchanging} as nonzero means zero extension and as
zero means sign extension.  If @code{volatil} is nonzero then some
other type of extension was done via the @code{ptr_extend} instruction.

@findex SUBREG_PROMOTED_VAR_P
@cindex @code{subreg} and @samp{/s}
@cindex @code{in_struct}, in @code{subreg}
@item SUBREG_PROMOTED_VAR_P (@var{x})
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 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_WEAK
@cindex @code{symbol_ref} and @samp{/i}
@cindex @code{return_val}, in @code{symbol_ref}
@item SYMBOL_REF_WEAK (@var{x})
In a @code{symbol_ref}, indicates that @var{x} has been declared weak.
Stored in the @code{return_val} field and printed as @samp{/i}.

@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}.

Most uses of @code{SYMBOL_REF_FLAG} are historic and may be subsumed
by @code{SYMBOL_REF_FLAGS}.  Certainly use of @code{SYMBOL_REF_FLAGS}
is mandatory if the target requires more than one bit of storage.
@end table

These are the fields to which the above macros refer:

@table @code
@findex call
@cindex @samp{/c} in RTL dump
@item call
In a @code{mem}, 1 means that the memory reference will not trap.

In a @code{call}, 1 means that this pure or const call may possibly
infinite loop.

In an RTL dump, this flag is represented as @samp{/c}.

@findex frame_related
@cindex @samp{/f} in RTL dump
@item frame_related
In an @code{insn} or @code{set} expression, 1 means that it is part of
a function prologue and sets the stack pointer, sets the frame pointer,
saves a register, or sets up a temporary register to use in place of the
frame pointer.

In @code{reg} expressions, 1 means that the register holds a pointer.

In @code{mem} expressions, 1 means that the memory reference holds a pointer.

In @code{symbol_ref} expressions, 1 means that the reference addresses
this function's string constant pool.

In an RTL dump, this flag is represented as @samp{/f}.

@findex in_struct
@cindex @samp{/s} in RTL dump
@item in_struct
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.  Such a
label that would have been deleted is replaced with a @code{note} of type
@code{NOTE_INSN_DELETED_LABEL}.

In an @code{insn} during dead-code elimination, 1 means that the insn is
dead code.

In an @code{insn} or @code{jump_insn} during reorg for an insn in the
delay slot of a branch,
1 means that this insn is from the target of the branch.

In an @code{insn} during instruction scheduling, 1 means that this insn
must be scheduled as part of a group together with the previous insn.

In an RTL dump, this flag is represented as @samp{/s}.

@findex return_val
@cindex @samp{/i} in RTL dump
@item return_val
In @code{reg} expressions, 1 means the register contains
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.

In @code{symbol_ref} expressions, 1 means the referenced symbol is weak.

In @code{call} expressions, 1 means the call is pure.

In an RTL dump, this flag is represented as @samp{/i}.

@findex jump
@cindex @samp{/j} in RTL dump
@item jump
In a @code{mem} expression, 1 means we should keep the alias set for this
mem unchanged when we access a component.

In a @code{set}, 1 means it is for a return.

In a @code{call_insn}, 1 means it is a sibling call.

In a @code{jump_insn}, 1 means it is a crossing jump.

In an RTL dump, this flag is represented as @samp{/j}.

@findex unchanging
@cindex @samp{/u} in RTL dump
@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 @code{insn} or @code{jump_insn} in the delay slot of a branch
instruction, 1 means an annulling branch should be used.

In a @code{symbol_ref} expression, 1 means that this symbol addresses
something in the per-function constant 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 used
@item used
This flag is used directly (without an access macro) 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}).

For a @code{reg}, it is used directly (without an access macro) by the
leaf register renumbering code to ensure that each register is only
renumbered once.

In a @code{symbol_ref}, it indicates that an external declaration for
the symbol has already been written.

@findex volatil
@cindex @samp{/v} in RTL dump
@cindex volatile memory references
@item volatil
In a @code{mem}, @code{asm_operands}, or @code{asm_input}
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 @code{insn}, 1 means the insn has been deleted.

In @code{label_ref} and @code{reg_label} expressions, 1 means a reference
to a non-local label.

In @code{prefetch} expressions, 1 means that the containing insn is a
scheduling barrier.

In an RTL dump, this flag is represented as @samp{/v}.
@end table

@node Machine Modes
@section Machine Modes
@cindex machine modes

@findex 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{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 BImode
@item BImode
``Bit'' mode represents a single bit, for predicate registers.

@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 OImode
@item OImode
``Octa Integer'' (?) mode represents a thirty-two-byte integer.

@findex XImode
@item XImode
``Hexadeca Integer'' (?) mode represents a sixty-four-byte integer.

@findex QFmode
@item QFmode
``Quarter-Floating'' mode represents a quarter-precision (single byte)
floating point number.

@findex HFmode
@item HFmode
``Half-Floating'' mode represents a half-precision (two byte) floating
point number.

@findex TQFmode
@item TQFmode
``Three-Quarter-Floating'' (?) mode represents a three-quarter-precision
(three byte) floating point number.

@findex SFmode
@item SFmode
``Single Floating'' mode represents a four byte floating point number.
In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
this is a single-precision IEEE floating point number; it can also be
used for double-precision (on processors with 16-bit bytes) and
single-precision VAX and IBM types.

@findex DFmode
@item DFmode
``Double Floating'' mode represents an eight byte floating point number.
In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
this is a double-precision IEEE floating point number.

@findex XFmode
@item XFmode
``Extended Floating'' mode represents an IEEE extended floating point
number.  This mode only has 80 meaningful bits (ten bytes).  Some
processors require such numbers to be padded to twelve bytes, others
to sixteen; this mode is used for either.

@findex SDmode
@item SDmode
``Single Decimal Floating'' mode represents a four byte decimal
floating point number (as distinct from conventional binary floating
point).

@findex DDmode
@item DDmode
``Double Decimal Floating'' mode represents an eight byte decimal
floating point number.

@findex TDmode
@item TDmode
``Tetra Decimal Floating'' mode represents a sixteen byte decimal
floating point number all 128 of whose bits are meaningful.

@findex TFmode
@item TFmode
``Tetra Floating'' mode represents a sixteen byte floating point number
all 128 of whose bits are meaningful.  One common use is the
IEEE quad-precision format.

@findex QQmode
@item QQmode
``Quarter-Fractional'' mode represents a single byte treated as a signed
fractional number.  The default format is ``s.7''.

@findex HQmode
@item HQmode
``Half-Fractional'' mode represents a two-byte signed fractional number.
The default format is ``s.15''.

@findex SQmode
@item SQmode
``Single Fractional'' mode represents a four-byte signed fractional number.
The default format is ``s.31''.

@findex DQmode
@item DQmode
``Double Fractional'' mode represents an eight-byte signed fractional number.
The default format is ``s.63''.

@findex TQmode
@item TQmode
``Tetra Fractional'' mode represents a sixteen-byte signed fractional number.
The default format is ``s.127''.

@findex UQQmode
@item UQQmode
``Unsigned Quarter-Fractional'' mode represents a single byte treated as an
unsigned fractional number.  The default format is ``.8''.

@findex UHQmode
@item UHQmode
``Unsigned Half-Fractional'' mode represents a two-byte unsigned fractional
number.  The default format is ``.16''.

@findex USQmode
@item USQmode
``Unsigned Single Fractional'' mode represents a four-byte unsigned fractional
number.  The default format is ``.32''.

@findex UDQmode
@item UDQmode
``Unsigned Double Fractional'' mode represents an eight-byte unsigned
fractional number.  The default format is ``.64''.

@findex UTQmode
@item UTQmode
``Unsigned Tetra Fractional'' mode represents a sixteen-byte unsigned
fractional number.  The default format is ``.128''.

@findex HAmode
@item HAmode
``Half-Accumulator'' mode represents a two-byte signed accumulator.
The default format is ``s8.7''.

@findex SAmode
@item SAmode
``Single Accumulator'' mode represents a four-byte signed accumulator.
The default format is ``s16.15''.

@findex DAmode
@item DAmode
``Double Accumulator'' mode represents an eight-byte signed accumulator.
The default format is ``s32.31''.

@findex TAmode
@item TAmode
``Tetra Accumulator'' mode represents a sixteen-byte signed accumulator.
The default format is ``s64.63''.

@findex UHAmode
@item UHAmode
``Unsigned Half-Accumulator'' mode represents a two-byte unsigned accumulator.
The default format is ``8.8''.

@findex USAmode
@item USAmode
``Unsigned Single Accumulator'' mode represents a four-byte unsigned
accumulator.  The default format is ``16.16''.

@findex UDAmode
@item UDAmode
``Unsigned Double Accumulator'' mode represents an eight-byte unsigned
accumulator.  The default format is ``32.32''.

@findex UTAmode
@item UTAmode
``Unsigned Tetra Accumulator'' mode represents a sixteen-byte unsigned
accumulator.  The default format is ``64.64''.

@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.  (@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 QCmode
@findex HCmode
@findex SCmode
@findex DCmode
@findex XCmode
@findex TCmode
@item QCmode, HCmode, 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{QFmode},
@code{HFmode}, @code{SFmode}, @code{DFmode}, @code{XFmode}, and
@code{TFmode}, respectively.

@findex CQImode
@findex CHImode
@findex CSImode
@findex CDImode
@findex CTImode
@findex COImode
@findex CPSImode
@item CQImode, CHImode, CSImode, CDImode, CTImode, COImode, CPSImode
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}, @code{OImode}, and @code{PSImode},
respectively.

@findex BND32mode
@findex BND64mode
@item BND32mode BND64mode
These modes stand for bounds for pointer of 32 and 64 bit size respectively.
Mode size is double pointer mode size.
@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{BImode}, @code{QImode},
@code{HImode}, @code{SImode}, @code{DImode}, @code{TImode}, and
@code{OImode}.

@findex MODE_PARTIAL_INT
@item MODE_PARTIAL_INT
The ``partial integer'' modes, @code{PQImode}, @code{PHImode},
@code{PSImode} and @code{PDImode}.

@findex MODE_FLOAT
@item MODE_FLOAT
Floating point modes.  By default these are @code{QFmode},
@code{HFmode}, @code{TQFmode}, @code{SFmode}, @code{DFmode},
@code{XFmode} and @code{TFmode}.

@findex MODE_DECIMAL_FLOAT
@item MODE_DECIMAL_FLOAT
Decimal floating point modes.  By default these are @code{SDmode},
@code{DDmode} and @code{TDmode}.

@findex MODE_FRACT
@item MODE_FRACT
Signed fractional modes.  By default these are @code{QQmode}, @code{HQmode},
@code{SQmode}, @code{DQmode} and @code{TQmode}.

@findex MODE_UFRACT
@item MODE_UFRACT
Unsigned fractional modes.  By default these are @code{UQQmode}, @code{UHQmode},
@code{USQmode}, @code{UDQmode} and @code{UTQmode}.

@findex MODE_ACCUM
@item MODE_ACCUM
Signed accumulator modes.  By default these are @code{HAmode},
@code{SAmode}, @code{DAmode} and @code{TAmode}.

@findex MODE_UACCUM
@item MODE_UACCUM
Unsigned accumulator modes.  By default these are @code{UHAmode},
@code{USAmode}, @code{UDAmode} and @code{UTAmode}.

@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{QCmode},
@code{HCmode}, @code{SCmode}, @code{DCmode}, @code{XCmode}, and
@code{TCmode}.

@findex MODE_CC
@item MODE_CC
Modes representing condition code values.  These are @code{CCmode} plus
any @code{CC_MODE} modes listed in the @file{@var{machine}-modes.def}.
@xref{Jump Patterns},
also see @ref{Condition Code}.

@findex MODE_POINTER_BOUNDS
@item MODE_POINTER_BOUNDS
Pointer bounds modes.  Used to represent values of pointer bounds type.
Operations in these modes may be executed as NOPs depending on hardware
features and environment setup.

@findex MODE_OPAQUE
@item MODE_OPAQUE
This is a mode class for modes that don't want to provide operations
other than register moves, memory moves, loads, stores, and
@code{unspec}s. They have a size and precision and that's all.

@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

@cindex machine mode wrapper classes
@code{machmode.h} also defines various wrapper classes that combine a
@code{machine_mode} with a static assertion that a particular
condition holds.  The classes are:

@table @code
@findex scalar_int_mode
@item scalar_int_mode
A mode that has class @code{MODE_INT} or @code{MODE_PARTIAL_INT}.

@findex scalar_float_mode
@item scalar_float_mode
A mode that has class @code{MODE_FLOAT} or @code{MODE_DECIMAL_FLOAT}.

@findex scalar_mode
@item scalar_mode
A mode that holds a single numerical value.  In practice this means
that the mode is a @code{scalar_int_mode}, is a @code{scalar_float_mode},
or has class @code{MODE_FRACT}, @code{MODE_UFRACT}, @code{MODE_ACCUM},
@code{MODE_UACCUM} or @code{MODE_POINTER_BOUNDS}.

@findex complex_mode
@item complex_mode
A mode that has class @code{MODE_COMPLEX_INT} or @code{MODE_COMPLEX_FLOAT}.

@findex fixed_size_mode
@item fixed_size_mode
A mode whose size is known at compile time.
@end table

Named modes use the most constrained of the available wrapper classes,
if one exists, otherwise they use @code{machine_mode}.  For example,
@code{QImode} is a @code{scalar_int_mode}, @code{SFmode} is a
@code{scalar_float_mode} and @code{BLKmode} is a plain
@code{machine_mode}.  It is possible to refer to any mode as a raw
@code{machine_mode} by adding the @code{E_} prefix, where @code{E}
stands for ``enumeration''.  For example, the raw @code{machine_mode}
names of the modes just mentioned are @code{E_QImode}, @code{E_SFmode}
and @code{E_BLKmode} respectively.

The wrapper classes implicitly convert to @code{machine_mode} and to any
wrapper class that represents a more general condition; for example
@code{scalar_int_mode} and @code{scalar_float_mode} both convert
to @code{scalar_mode} and all three convert to @code{fixed_size_mode}.
The classes act like @code{machine_mode}s that accept only certain
named modes.

@findex opt_mode
@file{machmode.h} also defines a template class @code{opt_mode<@var{T}>}
that holds a @code{T} or nothing, where @code{T} can be either
@code{machine_mode} or one of the wrapper classes above.  The main
operations on an @code{opt_mode<@var{T}>} @var{x} are as follows:

@table @samp
@item @var{x}.exists ()
Return true if @var{x} holds a mode rather than nothing.

@item @var{x}.exists (&@var{y})
Return true if @var{x} holds a mode rather than nothing, storing the
mode in @var{y} if so.  @var{y} must be assignment-compatible with @var{T}.

@item @var{x}.require ()
Assert that @var{x} holds a mode rather than nothing and return that mode.

@item @var{x} = @var{y}
Set @var{x} to @var{y}, where @var{y} is a @var{T} or implicitly converts
to a @var{T}.
@end table

The default constructor sets an @code{opt_mode<@var{T}>} to nothing.
There is also a constructor that takes an initial value of type @var{T}.

It is possible to use the @file{is-a.h} accessors on a @code{machine_mode}
or machine mode wrapper @var{x}:

@table @samp
@findex is_a
@item is_a <@var{T}> (@var{x})
Return true if @var{x} meets the conditions for wrapper class @var{T}.

@item is_a <@var{T}> (@var{x}, &@var{y})
Return true if @var{x} meets the conditions for wrapper class @var{T},
storing it in @var{y} if so.  @var{y} must be assignment-compatible with
@var{T}.

@item as_a <@var{T}> (@var{x})
Assert that @var{x} meets the conditions for wrapper class @var{T}
and return it as a @var{T}.

@item dyn_cast <@var{T}> (@var{x})
Return an @code{opt_mode<@var{T}>} that holds @var{x} if @var{x} meets
the conditions for wrapper class @var{T} and that holds nothing otherwise.
@end table

The purpose of these wrapper classes is to give stronger static type
checking.  For example, if a function takes a @code{scalar_int_mode},
a caller that has a general @code{machine_mode} must either check or
assert that the code is indeed a scalar integer first, using one of
the functions above.

The wrapper classes are normal C++ classes, with user-defined
constructors.  Sometimes it is useful to have a POD version of
the same type, particularly if the type appears in a @code{union}.
The template class @code{pod_mode<@var{T}>} provides a POD version
of wrapper class @var{T}.  It is assignment-compatible with @var{T}
and implicitly converts to both @code{machine_mode} and @var{T}.

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_IBIT
@item GET_MODE_IBIT (@var{m})
Returns the number of integral bits of a datum of fixed-point mode @var{m}.

@findex GET_MODE_FBIT
@item GET_MODE_FBIT (@var{m})
Returns the number of fractional bits of a datum of fixed-point 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

The following 3 variables are defined on every target.   They can be
used to allocate buffers that are guaranteed to be large enough to
hold any value that can be represented on the target.   The first two
can be overridden by defining them in the target's mode.def file,
however, the value must be a constant that can determined very early
in the compilation process.   The third symbol cannot be overridden.

@table @code
@findex BITS_PER_UNIT
@item BITS_PER_UNIT
The number of bits in an addressable storage unit (byte).  If you do
not define this, the default is 8.

@findex MAX_BITSIZE_MODE_ANY_INT
@item MAX_BITSIZE_MODE_ANY_INT
The maximum bitsize of any mode that is used in integer math.  This
should be overridden by the target if it uses large integers as
containers for larger vectors but otherwise never uses the contents to
compute integer values.

@findex MAX_BITSIZE_MODE_ANY_MODE
@item MAX_BITSIZE_MODE_ANY_MODE
The bitsize of the largest mode on the target.  The default value is
the largest mode size given in the mode definition file, which is
always correct for targets whose modes have a fixed size.  Targets
that might increase the size of a mode beyond this default should define
@code{MAX_BITSIZE_MODE_ANY_MODE} to the actual upper limit in
@file{@var{machine}-modes.def}.
@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
@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)}.

Constants generated for modes with fewer bits than in
@code{HOST_WIDE_INT} must be sign extended to full width (e.g., with
@code{gen_int_mode}).  For constants for modes with more bits than in
@code{HOST_WIDE_INT} the implied high order bits of that constant are
copies of the top bit.  Note however that values are neither
inherently signed nor inherently unsigned; where necessary, signedness
is determined by the rtl operation instead.

@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.

@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 @minus{}1, @code{const_true_rtx} and
@code{constm1_rtx} will point to the same object.

@findex const_double
@item (const_double:@var{m} @var{i0} @var{i1} @dots{})
This represents either a floating-point constant of mode @var{m} or
(on older ports that do not define
@code{TARGET_SUPPORTS_WIDE_INT}) 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.  In the latter case, @var{m} will be
@code{VOIDmode}.  For integral values constants for modes with more
bits than twice the number in @code{HOST_WIDE_INT} the implied high
order bits of that constant are copies of the top bit of
@code{CONST_DOUBLE_HIGH}.  Note however that integral values are
neither inherently signed nor inherently unsigned; where necessary,
signedness is determined by the rtl operation instead.

On more modern ports, @code{CONST_DOUBLE} only represents floating
point values.  New ports define @code{TARGET_SUPPORTS_WIDE_INT} to
make this designation.

@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{Floating Point}).  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 const_double_zero
The host dependency for the number of integers used to store a double
value makes it problematic for machine descriptions to use expressions
of code @code{const_double} and therefore a syntactic alias has been
provided:

@smallexample
(const_double_zero:@var{m})
@end smallexample

standing for:

@smallexample
(const_double:@var{m} 0 0 @dots{})
@end smallexample

for matching the floating-point value zero, possibly the only useful one.

@findex CONST_WIDE_INT
@item (const_wide_int:@var{m} @var{nunits} @var{elt0} @dots{})
This contains an array of @code{HOST_WIDE_INT}s that is large enough
to hold any constant that can be represented on the target.  This form
of rtl is only used on targets that define
@code{TARGET_SUPPORTS_WIDE_INT} to be nonzero and then
@code{CONST_DOUBLE}s are only used to hold floating-point values.  If
the target leaves @code{TARGET_SUPPORTS_WIDE_INT} defined as 0,
@code{CONST_WIDE_INT}s are not used and @code{CONST_DOUBLE}s are as
they were before.

The values are stored in a compressed format.  The higher-order
0s or -1s are not represented if they are just the logical sign
extension of the number that is represented.

@findex CONST_WIDE_INT_VEC
@item CONST_WIDE_INT_VEC (@var{code})
Returns the entire array of @code{HOST_WIDE_INT}s that are used to
store the value.  This macro should be rarely used.

@findex CONST_WIDE_INT_NUNITS
@item CONST_WIDE_INT_NUNITS (@var{code})
The number of @code{HOST_WIDE_INT}s used to represent the number.
Note that this generally is smaller than the number of
@code{HOST_WIDE_INT}s implied by the mode size.

@findex CONST_WIDE_INT_ELT
@item CONST_WIDE_INT_ELT (@var{code},@var{i})
Returns the @code{i}th element of the array.   Element 0 is contains
the low order bits of the constant.

@findex const_fixed
@item (const_fixed:@var{m} @dots{})
Represents a fixed-point constant of mode @var{m}.
The operand is a data structure of type @code{struct fixed_value} and
is accessed with the macro @code{CONST_FIXED_VALUE}.  The high part of
data is accessed with @code{CONST_FIXED_VALUE_HIGH}; the low part is
accessed with @code{CONST_FIXED_VALUE_LOW}.

@findex const_poly_int
@item (const_poly_int:@var{m} [@var{c0} @var{c1} @dots{}])
Represents a @code{poly_int}-style polynomial integer with coefficients
@var{c0}, @var{c1}, @dots{}.  The coefficients are @code{wide_int}-based
integers rather than rtxes.  @code{CONST_POLY_INT_COEFFS} gives the
values of individual coefficients (which is mostly only useful in
low-level routines) and @code{const_poly_int_value} gives the full
@code{poly_int} value.

@findex const_vector
@item (const_vector:@var{m} [@var{x0} @var{x1} @dots{}])
Represents a vector constant.  The values in square brackets are
elements of the vector, which are always @code{const_int},
@code{const_wide_int}, @code{const_double} or @code{const_fixed}
expressions.

Each vector constant @var{v} is treated as a specific instance of an
arbitrary-length sequence that itself contains
@samp{CONST_VECTOR_NPATTERNS (@var{v})} interleaved patterns.  Each
pattern has the form:

@smallexample
@{ @var{base0}, @var{base1}, @var{base1} + @var{step}, @var{base1} + @var{step} * 2, @dots{} @}
@end smallexample

The first three elements in each pattern are enough to determine the
values of the other elements.  However, if all @var{step}s are zero,
only the first two elements are needed.  If in addition each @var{base1}
is equal to the corresponding @var{base0}, only the first element in
each pattern is needed.  The number of determining elements per pattern
is given by @samp{CONST_VECTOR_NELTS_PER_PATTERN (@var{v})}.

For example, the constant:

@smallexample
@{ 0, 1, 2, 6, 3, 8, 4, 10, 5, 12, 6, 14, 7, 16, 8, 18 @}
@end smallexample

is interpreted as an interleaving of the sequences:

@smallexample
@{ 0, 2, 3, 4, 5, 6, 7, 8 @}
@{ 1, 6, 8, 10, 12, 14, 16, 18 @}
@end smallexample

where the sequences are represented by the following patterns:

@smallexample
@var{base0} == 0, @var{base1} == 2, @var{step} == 1
@var{base0} == 1, @var{base1} == 6, @var{step} == 2
@end smallexample

In this case:

@smallexample
CONST_VECTOR_NPATTERNS (@var{v}) == 2
CONST_VECTOR_NELTS_PER_PATTERN (@var{v}) == 3
@end smallexample

Thus the first 6 elements (@samp{@{ 0, 1, 2, 6, 3, 8 @}}) are enough
to determine the whole sequence; we refer to them as the ``encoded''
elements.  They are the only elements present in the square brackets
for variable-length @code{const_vector}s (i.e.@: for
@code{const_vector}s whose mode @var{m} has a variable number of
elements).  However, as a convenience to code that needs to handle
both @code{const_vector}s and @code{parallel}s, all elements are
present in the square brackets for fixed-length @code{const_vector}s;
the encoding scheme simply reduces the amount of work involved in
processing constants that follow a regular pattern.

Sometimes this scheme can create two possible encodings of the same
vector.  For example @{ 0, 1 @} could be seen as two patterns with
one element each or one pattern with two elements (@var{base0} and
@var{base1}).  The canonical encoding is always the one with the
fewest patterns or (if both encodings have the same number of
petterns) the one with the fewest encoded elements.

@samp{const_vector_encoding_nelts (@var{v})} gives the total number of
encoded elements in @var{v}, which is 6 in the example above.
@code{CONST_VECTOR_ENCODED_ELT (@var{v}, @var{i})} accesses the value
of encoded element @var{i}.

@samp{CONST_VECTOR_DUPLICATE_P (@var{v})} is true if @var{v} simply contains
repeated instances of @samp{CONST_VECTOR_NPATTERNS (@var{v})} values.  This is
a shorthand for testing @samp{CONST_VECTOR_NELTS_PER_PATTERN (@var{v}) == 1}.

@samp{CONST_VECTOR_STEPPED_P (@var{v})} is true if at least one
pattern in @var{v} has a nonzero step.  This is a shorthand for
testing @samp{CONST_VECTOR_NELTS_PER_PATTERN (@var{v}) == 3}.

@code{CONST_VECTOR_NUNITS (@var{v})} gives the total number of elements
in @var{v}; it is a shorthand for getting the number of units in
@samp{GET_MODE (@var{v})}.

The utility function @code{const_vector_elt} gives the value of an
arbitrary element as an @code{rtx}.  @code{const_vector_int_elt} gives
the same value as a @code{wide_int}.

@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{mode} @var{label})
Represents the value of an assembler label for code.  It contains one
operand, an expression, which must be a @code{code_label} or a @code{note}
of type @code{NOTE_INSN_DELETED_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.

The @code{label_ref} contains a mode, which is usually @code{Pmode}.
Usually that is the only mode for which a label is directly valid.

@findex const
@item (const:@var{m} @var{exp})
Represents a constant that is the result of an assembly-time
arithmetic computation.  The operand, @var{exp}, contains only
@code{const_int}, @code{symbol_ref}, @code{label_ref} or @code{unspec}
expressions, combined with @code{plus} and @code{minus}.  Any such
@code{unspec}s are target-specific and typically represent some form
of relocation operator.  @var{m} should be a valid address mode.

@findex high
@item (high:@var{m} @var{exp})
Represents the high-order bits of @var{exp}.  
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 large immediate values and/or link-time constants such
as global memory addresses.  In the latter case, @var{m} is @code{Pmode}
and @var{exp} is usually a constant expression involving @code{symbol_ref}.
@end table

@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}.  If mode @var{mode} is of
mode class @code{MODE_FLOAT}, it returns a @code{CONST_DOUBLE}
expression in mode @var{mode}.  Otherwise, it returns a
@code{CONST_VECTOR} 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}.  The
@code{CONST1_RTX} and @code{CONST2_RTX} macros are undefined
for vector modes.

@node Regs and Memory
@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 to a nonzero value, this points
to immediately above the first variable on the stack.  Otherwise, it points
to the first variable on the stack.

@cindex @code{TARGET_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{TARGET_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{m1} @var{reg:m2} @var{bytenum})

@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-part @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, the register must be
enclosed in a @code{subreg}.

There are currently three supported types for the first operand of a
@code{subreg}:
@itemize
@item pseudo registers
This is the most common case.  Most @code{subreg}s have pseudo
@code{reg}s as their first operand.

@item mem
@code{subreg}s of @code{mem} were common in earlier versions of GCC and
are still supported.  During the reload pass these are replaced by plain
@code{mem}s.  On machines that do not do instruction scheduling, use of
@code{subreg}s of @code{mem} are still used, but this is no longer
recommended.  Such @code{subreg}s are considered to be
@code{register_operand}s rather than @code{memory_operand}s before and
during reload.  Because of this, the scheduling passes cannot properly
schedule instructions with @code{subreg}s of @code{mem}, so for machines
that do scheduling, @code{subreg}s of @code{mem} should never be used.
To support this, the combine and recog passes have explicit code to
inhibit the creation of @code{subreg}s of @code{mem} when
@code{INSN_SCHEDULING} is defined.

The use of @code{subreg}s of @code{mem} after the reload pass is an area
that is not well understood and should be avoided.  There is still some
code in the compiler to support this, but this code has possibly rotted.
This use of @code{subreg}s is discouraged and will most likely not be
supported in the future.

@item hard registers
It is seldom necessary to wrap hard registers in @code{subreg}s; such
registers would normally reduce to a single @code{reg} rtx.  This use of
@code{subreg}s is discouraged and may not be supported in the future.

@end itemize

@code{subreg}s of @code{subreg}s are not supported.  Using
@code{simplify_gen_subreg} is the recommended way to avoid this problem.

@code{subreg}s come in two distinct flavors, each having its own
usage and rules:

@table @asis
@item Paradoxical subregs
When @var{m1} is strictly wider than @var{m2}, the @code{subreg}
expression is called @dfn{paradoxical}.  The canonical test for this
class of @code{subreg} is:

@smallexample
paradoxical_subreg_p (@var{m1}, @var{m2})
@end smallexample

Paradoxical @code{subreg}s can be used as both lvalues and rvalues.
When used as an lvalue, the low-order bits of the source value
are stored in @var{reg} and the high-order bits are discarded.
When used as an rvalue, the low-order bits of the @code{subreg} are
taken from @var{reg} while the high-order bits may or may not be
defined.

The high-order bits of rvalues are defined in the following circumstances:

@itemize
@item @code{subreg}s of @code{mem}
When @var{m2} is smaller than a word, the macro @code{LOAD_EXTEND_OP},
can control how the high-order bits are defined.

@item @code{subreg} of @code{reg}s
The upper bits are defined when @code{SUBREG_PROMOTED_VAR_P} is true.
@code{SUBREG_PROMOTED_UNSIGNED_P} describes what the upper bits hold.
Such subregs usually represent local variables, register variables
and parameter pseudo variables that have been promoted to a wider mode.

@end itemize

@var{bytenum} is always zero for a paradoxical @code{subreg}, even on
big-endian targets.

For example, the paradoxical @code{subreg}:

@smallexample
(set (subreg:SI (reg:HI @var{x}) 0) @var{y})
@end smallexample

stores the lower 2 bytes of @var{y} in @var{x} and discards the upper
2 bytes.  A subsequent:

@smallexample
(set @var{z} (subreg:SI (reg:HI @var{x}) 0))
@end smallexample

would set the lower two bytes of @var{z} to @var{y} and set the upper
two bytes to an unknown value assuming @code{SUBREG_PROMOTED_VAR_P} is
false.

@item Normal subregs
When @var{m1} is at least as narrow as @var{m2} the @code{subreg}
expression is called @dfn{normal}.

@findex REGMODE_NATURAL_SIZE
Normal @code{subreg}s restrict consideration to certain bits of
@var{reg}.  For this purpose, @var{reg} is divided into
individually-addressable blocks in which each block has:

@smallexample
REGMODE_NATURAL_SIZE (@var{m2})
@end smallexample

bytes.  Usually the value is @code{UNITS_PER_WORD}; that is,
most targets usually treat each word of a register as being
independently addressable.

There are two types of normal @code{subreg}.  If @var{m1} is known
to be no bigger than a block, the @code{subreg} refers to the
least-significant part (or @dfn{lowpart}) of one block of @var{reg}.
If @var{m1} is known to be larger than a block, the @code{subreg} refers
to two or more complete blocks.

When used as an lvalue, @code{subreg} is a block-based accessor.
Storing to a @code{subreg} modifies all the blocks of @var{reg} that
overlap the @code{subreg}, but it leaves the other blocks of @var{reg}
alone.

When storing to a normal @code{subreg} that is smaller than a block,
the other bits of the referenced block are usually left in an undefined
state.  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}
or @code{zero_extract} around the @code{subreg}.

@var{bytenum} must identify the offset of the first byte of the
@code{subreg} from the start of @var{reg}, assuming that @var{reg} is
laid out in memory order.  The memory order of bytes is defined by
two target macros, @code{WORDS_BIG_ENDIAN} and @code{BYTES_BIG_ENDIAN}:

@itemize
@cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
@item
@code{WORDS_BIG_ENDIAN}, if set to 1, says that byte number zero is
part of the most significant word; otherwise, it is part of the least
significant word.

@cindex @code{BYTES_BIG_ENDIAN}, effect on @code{subreg}
@item
@code{BYTES_BIG_ENDIAN}, if set to 1, says that byte number zero is
the most significant byte within a word; otherwise, it is the least
significant byte within a word.
@end itemize

@cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg}
On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with
@code{WORDS_BIG_ENDIAN}.  However, most parts of the compiler treat
floating point values as if they had the same endianness as integer
values.  This works because they handle them solely as a collection of
integer values, with no particular numerical value.  Only real.cc and
the runtime libraries care about @code{FLOAT_WORDS_BIG_ENDIAN}.

Thus,

@smallexample
(subreg:HI (reg:SI @var{x}) 2)
@end smallexample

on a @code{BYTES_BIG_ENDIAN}, @samp{UNITS_PER_WORD == 4} target is the same as

@smallexample
(subreg:HI (reg:SI @var{x}) 0)
@end smallexample

on a little-endian, @samp{UNITS_PER_WORD == 4} target.  Both
@code{subreg}s access the lower two bytes of register @var{x}.

Note that the byte offset is a polynomial integer; it may not be a
compile-time constant on targets with variable-sized modes.  However,
the restrictions above mean that there are only a certain set of
acceptable offsets for a given combination of @var{m1} and @var{m2}.
The compiler can always tell which blocks a valid subreg occupies, and
whether the subreg is a lowpart of a block.

@end table

A @code{MODE_PARTIAL_INT} mode behaves as if it were as wide as the
corresponding @code{MODE_INT} mode, except that it has a number of
undefined bits, which are determined by the precision of the
mode.

For example, on a little-endian target which defines @code{PSImode}
to have a precision of 20 bits:

@smallexample
(subreg:PSI (reg:SI 0) 0)
@end smallexample

accesses the low 20 bits of @samp{(reg:SI 0)}.

@findex REGMODE_NATURAL_SIZE
Continuing with a @code{PSImode} precision of 20 bits, if we assume
@samp{REGMODE_NATURAL_SIZE (DImode) <= 4},
then the following two @code{subreg}s:

@smallexample
(subreg:PSI (reg:DI 0) 0)
(subreg:PSI (reg:DI 0) 4)
@end smallexample

represent accesses to the low 20 bits of the two halves of
@samp{(reg:DI 0)}.

If @samp{REGMODE_NATURAL_SIZE (PSImode) <= 2} then these two @code{subreg}s:

@smallexample
(subreg:HI (reg:PSI 0) 0)
(subreg:HI (reg:PSI 0) 2)
@end smallexample

represent independent 2-byte accesses that together span the whole
of @samp{(reg:PSI 0)}.  Storing to the first @code{subreg} does not
affect the value of the second, and vice versa, so the assignment:

@smallexample
(set (subreg:HI (reg:PSI 0) 0) (reg:HI 4))
@end smallexample

sets the low 16 bits of @samp{(reg:PSI 0)} to @samp{(reg:HI 4)}, and
the high 4 defined bits of @samp{(reg:PSI 0)} retain their
original value.  The behavior here is the same as for
normal @code{subreg}s, when there are no
@code{MODE_PARTIAL_INT} modes involved.

@cindex @code{TARGET_CAN_CHANGE_MODE_CLASS} and subreg semantics
The rules above apply to both pseudo @var{reg}s and hard @var{reg}s.
If the semantics are not correct for particular combinations of
@var{m1}, @var{m2} and hard @var{reg}, the target-specific code
must ensure that those combinations are never used.  For example:

@smallexample
TARGET_CAN_CHANGE_MODE_CLASS (@var{m2}, @var{m1}, @var{class})
@end smallexample

must be false for every class @var{class} that includes @var{reg}.

GCC must be able to determine at compile time whether a subreg is
paradoxical, whether it occupies a whole number of blocks, or whether
it is a lowpart of a block.  This means that certain combinations of
variable-sized mode are not permitted.  For example, if @var{m2}
holds @var{n} @code{SI} values, where @var{n} is greater than zero,
it is not possible to form a @code{DI} @code{subreg} of it; such a
@code{subreg} would be paradoxical when @var{n} is 1 but not when
@var{n} is greater than 1.

@findex SUBREG_REG
@findex SUBREG_BYTE
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_BYTE} macro.

It has been several years since a platform in which
@code{BYTES_BIG_ENDIAN} not equal to @code{WORDS_BIG_ENDIAN} has
been tested.  Anyone wishing to support such a platform in the future
may be confronted with code rot.

@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}).

On some machines, the condition code register is given a register number
and a @code{reg} is used.
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.
For examples, search for @samp{addcc} and @samp{andcc} in @file{sparc.md}.

@findex pc
@cindex program counter
@item (pc)
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} @var{alias})
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.  @var{alias} specifies an alias set for the
reference.  In general two items are in different alias sets if they cannot
reference the same memory address.

The construct @code{(mem:BLK (scratch))} is considered to alias all
other memories.  Thus it may be used as a memory barrier in epilogue
stack deallocation patterns.

@findex concat
@item (concat@var{m} @var{rtx} @var{rtx})
This RTX represents the concatenation of two other RTXs.  This is used
for complex values.  It should only appear in the RTL attached to
declarations and during RTL generation.  It should not appear in the
ordinary insn chain.

@findex concatn
@item (concatn@var{m} [@var{rtx} @dots{}])
This RTX represents the concatenation of all the @var{rtx} to make a
single value.  Like @code{concat}, this should only appear in
declarations, and not in the insn chain.
@end table

@node Arithmetic
@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
@findex ss_plus
@findex us_plus
@cindex RTL sum
@cindex RTL addition
@cindex RTL addition with signed saturation
@cindex RTL addition with unsigned saturation
@item (plus:@var{m} @var{x} @var{y})
@itemx (ss_plus:@var{m} @var{x} @var{y})
@itemx (us_plus:@var{m} @var{x} @var{y})

These three expressions all represent the sum of the values
represented by @var{x} and @var{y} carried out in machine mode
@var{m}.  They differ in their behavior on overflow of integer modes.
@code{plus} wraps round modulo the width of @var{m}; @code{ss_plus}
saturates at the maximum signed value representable in @var{m};
@code{us_plus} saturates at the maximum unsigned value.

@c ??? What happens on overflow of floating point modes?

@findex lo_sum
@item (lo_sum:@var{m} @var{x} @var{y})

This expression represents the sum of @var{x} and the low-order bits
of @var{y}.  It is used with @code{high} (@pxref{Constants}) to
represent the typical two-instruction sequence used in RISC machines to
reference large immediate values and/or link-time constants such
as global memory addresses.  In the latter case, @var{m} is @code{Pmode}
and @var{y} is usually a constant expression involving @code{symbol_ref}.

The number of low order bits is machine-dependent but is
normally the number of bits in mode @var{m} minus the number of
bits set by @code{high}.

@findex minus
@findex ss_minus
@findex us_minus
@cindex RTL difference
@cindex RTL subtraction
@cindex RTL subtraction with signed saturation
@cindex RTL subtraction with unsigned saturation
@item (minus:@var{m} @var{x} @var{y})
@itemx (ss_minus:@var{m} @var{x} @var{y})
@itemx (us_minus:@var{m} @var{x} @var{y})

These three expressions represent the result of subtracting @var{y}
from @var{x}, carried out in mode @var{M}.  Behavior on overflow is
the same as for the three variants of @code{plus} (see above).

@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 cannot 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 @emph{only} way this kind of expression may
validly be used: as a value to be stored in the condition codes, in a
register.  @xref{Comparisons}.

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.  It is some mode in class
@code{MODE_CC}, often @code{CCmode}.  @xref{Condition Code}.  If @var{m}
is @code{CCmode}, the operation returns sufficient
information (in an unspecified format) so that any comparison operator
can be applied to the result of the @code{COMPARE} operation.  For other
modes in class @code{MODE_CC}, the operation only returns a subset of
this information.

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
@findex ss_neg
@findex us_neg
@cindex negation
@cindex negation with signed saturation
@cindex negation with unsigned saturation
@item (neg:@var{m} @var{x})
@itemx (ss_neg:@var{m} @var{x})
@itemx (us_neg:@var{m} @var{x})
These two expressions represent the negation (subtraction from zero) of
the value represented by @var{x}, carried out in mode @var{m}.  They
differ in the behavior on overflow of integer modes.  In the case of
@code{neg}, the negation of the operand may be a number not representable
in mode @var{m}, in which case it is truncated to @var{m}.  @code{ss_neg}
and @code{us_neg} ensure that an out-of-bounds result saturates to the
maximum or minimum signed or unsigned value.

@findex mult
@findex ss_mult
@findex us_mult
@cindex multiplication
@cindex product
@cindex multiplication with signed saturation
@cindex multiplication with unsigned saturation
@item (mult:@var{m} @var{x} @var{y})
@itemx (ss_mult:@var{m} @var{x} @var{y})
@itemx (us_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}.
@code{ss_mult} and @code{us_mult} ensure that an out-of-bounds result
saturates to the maximum or minimum signed or unsigned value.

Some machines support a multiplication that generates a product wider
than the operands.  Write the pattern for this as

@smallexample
(mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
@end smallexample

where @var{m} is wider than the modes of @var{x} and @var{y}, which need
not be the same.

For unsigned widening multiplication, use the same idiom, but with
@code{zero_extend} instead of @code{sign_extend}.

@findex smul_highpart
@findex umul_highpart
@cindex high-part multiplication
@cindex multiplication high part
@item (smul_highpart:@var{m} @var{x} @var{y})
@itemx (umul_highpart:@var{m} @var{x} @var{y})
Represents the high-part multiplication of @var{x} and @var{y} carried
out in machine mode @var{m}.  @code{smul_highpart} returns the high part
of a signed multiplication, @code{umul_highpart} returns the high part
of an unsigned multiplication.

@findex fma
@cindex fused multiply-add
@item (fma:@var{m} @var{x} @var{y} @var{z})
Represents the @code{fma}, @code{fmaf}, and @code{fmal} builtin
functions, which compute @samp{@var{x} * @var{y} + @var{z}}
without doing an intermediate rounding step.

@findex div
@findex ss_div
@cindex division
@cindex signed division
@cindex signed division with signed saturation
@cindex quotient
@item (div:@var{m} @var{x} @var{y})
@itemx (ss_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.
@code{ss_div} ensures that an out-of-bounds result saturates to the maximum
or minimum signed value.

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,

@smallexample
(truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
@end smallexample

@findex udiv
@cindex unsigned division
@cindex unsigned division with unsigned saturation
@cindex division
@item (udiv:@var{m} @var{x} @var{y})
@itemx (us_div:@var{m} @var{x} @var{y})
Like @code{div} but represents unsigned division.
@code{us_div} ensures that an out-of-bounds result saturates to the maximum
or minimum unsigned value.

@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 values in mode @var{m}.
When used with floating point, if both operands are zeros, or if either
operand is @code{NaN}, then it is unspecified which of the two operands
is returned as the result.

@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
@findex ss_ashift
@findex us_ashift
@cindex left shift
@cindex shift
@cindex arithmetic shift
@cindex arithmetic shift with signed saturation
@cindex arithmetic shift with unsigned saturation
@item (ashift:@var{m} @var{x} @var{c})
@itemx (ss_ashift:@var{m} @var{x} @var{c})
@itemx (us_ashift:@var{m} @var{x} @var{c})
These three expressions represent the result of arithmetically shifting @var{x}
left by @var{c} places.  They differ in their behavior on overflow of integer
modes.  An @code{ashift} operation is a plain shift with no special behavior
in case of a change in the sign bit; @code{ss_ashift} and @code{us_ashift}
saturates to the minimum or maximum representable value if any of the bits
shifted out differs from the final sign bit.

@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
@findex ss_abs
@cindex absolute value
@item (abs:@var{m} @var{x})
@item (ss_abs:@var{m} @var{x})
Represents the absolute value of @var{x}, computed in mode @var{m}.
@code{ss_abs} ensures that an out-of-bounds result saturates to the
maximum signed value.


@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} must be @var{m}
or @code{VOIDmode}.

@findex clrsb
@item (clrsb:@var{m} @var{x})
Represents the number of redundant leading sign bits in @var{x},
represented as an integer of mode @var{m}, starting at the most
significant bit position.  This is one less than the number of leading
sign bits (either 0 or 1), with no special cases.  The mode of @var{x}
must be @var{m} or @code{VOIDmode}.

@findex clz
@item (clz:@var{m} @var{x})
Represents the number of leading 0-bits in @var{x}, represented as an
integer of mode @var{m}, starting at the most significant bit position.
If @var{x} is zero, the value is determined by
@code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}).  Note that this is one of
the few expressions that is not invariant under widening.  The mode of
@var{x} must be @var{m} or @code{VOIDmode}.

@findex ctz
@item (ctz:@var{m} @var{x})
Represents the number of trailing 0-bits in @var{x}, represented as an
integer of mode @var{m}, starting at the least significant bit position.
If @var{x} is zero, the value is determined by
@code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}).  Except for this case,
@code{ctz(x)} is equivalent to @code{ffs(@var{x}) - 1}.  The mode of
@var{x} must be @var{m} or @code{VOIDmode}.

@findex popcount
@item (popcount:@var{m} @var{x})
Represents the number of 1-bits in @var{x}, represented as an integer of
mode @var{m}.  The mode of @var{x} must be @var{m} or @code{VOIDmode}.

@findex parity
@item (parity:@var{m} @var{x})
Represents the number of 1-bits modulo 2 in @var{x}, represented as an
integer of mode @var{m}.  The mode of @var{x} must be @var{m} or
@code{VOIDmode}.

@findex bswap
@item (bswap:@var{m} @var{x})
Represents the value @var{x} with the order of bytes reversed, carried out
in mode @var{m}, which must be a fixed-point machine mode.
The mode of @var{x} must be @var{m} or @code{VOIDmode}.
@end table

@node Comparisons
@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, for comparison operators
whose results have a `MODE_INT' mode,
@code{FLOAT_STORE_FLAG_VALUE} (@pxref{Misc}) if the relation holds, or
zero if it does not, for comparison operators that return floating-point
values, and a vector of either @code{VECTOR_STORE_FLAG_VALUE} (@pxref{Misc})
if the relation holds, or of zeros if it does not, for comparison operators
that return vector results.
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}.

@cindex condition codes
A comparison operation compares 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.

Usually only one style
of comparisons is supported on a particular machine, but the combine
pass will try to merge operations to produce code like
@code{(eq @var{x} @var{y})},
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 @minus{}1 but not
unsigned greater-than, because @minus{}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})
@code{STORE_FLAG_VALUE} 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})
@code{STORE_FLAG_VALUE} 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})
@code{STORE_FLAG_VALUE} 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 nonzero test, or @var{default} if
none of the tests are nonzero expressions.

This is currently not valid for instruction patterns and is supported only
for insn attributes.  @xref{Insn Attributes}.
@end table

@node Bit-Fields
@section Bit-Fields
@cindex bit-fields

Special expression codes exist to represent bit-field instructions.

@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,
which is the default if none is specified.

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.

A @code{sign_extract} cannot appear as an lvalue, or part thereof,
in RTL.

@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.

Unlike @code{sign_extract}, this type of expressions can be lvalues
in RTL; they may appear on the left side of an assignment, indicating
insertion of a value into the specified bit-field.
@end table

@node Vector Operations
@section Vector Operations
@cindex vector operations

All normal RTL expressions can be used with vector modes; they are
interpreted as operating on each part of the vector independently.
Additionally, there are a few new expressions to describe specific vector
operations.

@table @code
@findex vec_merge
@item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items})
This describes a merge operation between two vectors.  The result is a vector
of mode @var{m}; its elements are selected from either @var{vec1} or
@var{vec2}.  Which elements are selected is described by @var{items}, which
is a bit mask represented by a @code{const_int}; a zero bit indicates the
corresponding element in the result vector is taken from @var{vec2} while
a set bit indicates it is taken from @var{vec1}.

@findex vec_select
@item (vec_select:@var{m} @var{vec1} @var{selection})
This describes an operation that selects parts of a vector.  @var{vec1} is
the source vector, and @var{selection} is a @code{parallel} that contains a
@code{const_int} (or another expression, if the selection can be made at
runtime) for each of the subparts of the result vector, giving the number of
the source subpart that should be stored into it.  The result mode @var{m} is
either the submode for a single element of @var{vec1} (if only one subpart is
selected), or another vector mode with that element submode (if multiple
subparts are selected).

@findex vec_concat
@item (vec_concat:@var{m} @var{x1} @var{x2})
Describes a vector concat operation.  The result is a concatenation of the
vectors or scalars @var{x1} and @var{x2}; its length is the sum of the
lengths of the two inputs.

@findex vec_duplicate
@item (vec_duplicate:@var{m} @var{x})
This operation converts a scalar into a vector or a small vector into a
larger one by duplicating the input values.  The output vector mode must have
the same submodes as the input vector mode or the scalar modes, and the
number of output parts must be an integer multiple of the number of input
parts.

@findex vec_series
@item (vec_series:@var{m} @var{base} @var{step})
This operation creates a vector in which element @var{i} is equal to
@samp{@var{base} + @var{i}*@var{step}}.  @var{m} must be a vector integer mode.
@end table

@node Conversions
@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

@smallexample
(plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
@end smallexample

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 ss_truncate
@item (ss_truncate:@var{m} @var{x})
Represents the result of truncating the value @var{x}
to machine mode @var{m}, using signed saturation in the case of
overflow.  Both @var{m} and the mode of @var{x} must be fixed-point
modes.

@findex us_truncate
@item (us_truncate:@var{m} @var{x})
Represents the result of truncating the value @var{x}
to machine mode @var{m}, using unsigned saturation in the case of
overflow.  Both @var{m} and the mode of @var{x} must be fixed-point
modes.

@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 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.

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 fract_convert
@item (fract_convert:@var{m} @var{x})
Represents the result of converting fixed-point value @var{x} to
fixed-point mode @var{m}, signed integer value @var{x} to
fixed-point mode @var{m}, floating-point value @var{x} to
fixed-point mode @var{m}, fixed-point value @var{x} to integer mode @var{m}
regarded as signed, or fixed-point value @var{x} to floating-point mode @var{m}.
When overflows or underflows happen, the results are undefined.

@findex sat_fract
@item (sat_fract:@var{m} @var{x})
Represents the result of converting fixed-point value @var{x} to
fixed-point mode @var{m}, signed integer value @var{x} to
fixed-point mode @var{m}, or floating-point value @var{x} to
fixed-point mode @var{m}.
When overflows or underflows happen, the results are saturated to the
maximum or the minimum.

@findex unsigned_fract_convert
@item (unsigned_fract_convert:@var{m} @var{x})
Represents the result of converting fixed-point value @var{x} to
integer mode @var{m} regarded as unsigned, or unsigned integer value @var{x} to
fixed-point mode @var{m}.
When overflows or underflows happen, the results are undefined.

@findex unsigned_sat_fract
@item (unsigned_sat_fract:@var{m} @var{x})
Represents the result of converting unsigned integer value @var{x} to
fixed-point mode @var{m}.
When overflows or underflows happen, the results are saturated to the
maximum or the minimum.
@end table

@node RTL Declarations
@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 smaller than @samp{REGMODE_NATURAL_SIZE (@var{n})}.
@end table

@node Side Effects
@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},
@code{strict_low_part} or @code{zero_extract}), @code{mem}, @code{pc},
or @code{parallel}.

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.

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 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.

If @var{lval} is a @code{zero_extract}, then the referenced part of
the bit-field (a memory or register reference) specified by the
@code{zero_extract} is given the value @var{x} and the rest of the
bit-field is not changed.  Note that @code{sign_extract} cannot
appear in @var{lval}.

If @var{lval} is a @code{parallel}, it is used to represent the case of
a function returning a structure in multiple registers.  Each element
of the @code{parallel} is an @code{expr_list} whose first operand is a
@code{reg} and whose second operand is a @code{const_int} representing the
offset (in bytes) into the structure at which the data in that register
corresponds.  The first element may be null to indicate that the structure
is also passed partly in memory.

@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.

If @var{lval} is not @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 VAXen.  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 simple_return
@item (simple_return)
Like @code{(return)}, but truly represents only a function return, while
@code{(return)} may represent an insn that also performs other functions
of the function epilogue.  Like @code{(return)}, this may also occur in
conditional jumps.

@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}, @code{parallel} 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))} or
@code{(mem:BLK (scratch))}, it means that all memory
locations must be presumed clobbered.  If @var{x} is a @code{parallel},
it has the same meaning as a @code{parallel} in a @code{set} expression.

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 if it is a hard register clobber.  For pseudo-register clobber,
the register allocator and the reload pass do not assign the same hard
register to the clobber and the input operands if there is an insn
alternative containing the @samp{&} constraint (@pxref{Modifiers}) for
the clobber and the hard register is in register classes of the
clobber in the alternative.  You can clobber either a specific hard
register, a pseudo register, or a @code{scratch} expression; in the
latter two cases, GCC 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.

In some situations, it may be tempting to add a @code{use} of a
register in a @code{parallel} to describe a situation where the value
of a special register will modify the behavior of the instruction.
A hypothetical example might be a pattern for an addition that can
either wrap around or use saturating addition depending on the value
of a special control register:

@smallexample
(parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
                                       (reg:SI 4)] 0))
           (use (reg:SI 1))])
@end smallexample

@noindent

This will not work, several of the optimizers only look at expressions
locally; it is very likely that if you have multiple insns with
identical inputs to the @code{unspec}, they will be optimized away even
if register 1 changes in between.

This means that @code{use} can @emph{only} be used to describe
that the register is live.  You should think twice before adding
@code{use} statements, more often you will want to use @code{unspec}
instead.  The @code{use} RTX is most commonly useful to describe that
a fixed register is implicitly used in an insn.  It is also safe to use
in patterns where the compiler knows for other reasons that the result
of the whole pattern is variable, such as @samp{cpymem@var{m}} or
@samp{call} patterns.

During the reload phase, an insn that has a @code{use} as pattern
can carry a reg_equal note.  These @code{use} insns will be deleted
before the reload phase exits.

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{simple_return}, @code{clobber} or @code{use}.

``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,

@smallexample
(parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
           (set (mem:SI (reg:SI 1)) (reg:SI 1))])
@end smallexample

@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:

@smallexample
(parallel [(set (reg:CC CC_REG) (reg:SI 34))
           (set (pc) (if_then_else
                        (eq (reg:CC CC_REG) (const_int 0))
                        (label_ref @dots{})
                        (pc)))])
@end smallexample

@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.

@findex cond_exec
@item (cond_exec [@var{cond} @var{expr}])
Represents a conditionally executed expression.  The @var{expr} is
executed only if the @var{cond} is nonzero.  The @var{cond} expression
must not have side-effects, but the @var{expr} may very well have
side-effects.

@findex sequence
@item (sequence [@var{insns} @dots{}])
Represents a sequence of insns.  If a @code{sequence} appears in the
chain of insns, then each of the @var{insns} that appears in the sequence
must be suitable for appearing in the chain of insns, i.e.@: must satisfy
the @code{INSN_P} predicate.

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}.

Some back ends also use @code{sequence} objects for purposes other than
delay-slot groups.  This is not supported in the common parts of the
compiler, which treat such sequences as delay-slot groups.

DWARF2 Call Frame Address (CFA) adjustments are sometimes also expressed
using @code{sequence} objects as the value of a @code{RTX_FRAME_RELATED_P}
note.  This only happens if the CFA adjustments cannot be easily derived
from the pattern of the instruction to which the note is attached.  In
such cases, the value of the note is used instead of best-guesing the
semantics of the instruction.  The back end can attach notes containing
a @code{sequence} of @code{set} patterns that express the effect of the
parent instruction.
@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{}] @var{min} @var{max} @var{flags})
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.  @var{min} and @var{max}
are set up by branch shortening and hold a label with a minimum and a
maximum address, respectively.  @var{flags} indicates the relative
position of @var{base}, @var{min} and @var{max} to the containing insn
and of @var{min} and @var{max} to @var{base}.  See rtl.def for details.

@findex prefetch
@item (prefetch:@var{m} @var{addr} @var{rw} @var{locality})
Represents prefetch of memory at address @var{addr}.
Operand @var{rw} is 1 if the prefetch is for data to be written, 0 otherwise;
targets that do not support write prefetches should treat this as a normal
prefetch.
Operand @var{locality} specifies the amount of temporal locality; 0 if there
is none or 1, 2, or 3 for increasing levels of temporal locality;
targets that do not support locality hints should ignore this.

This insn is used to minimize cache-miss latency by moving data into a
cache before it is accessed.  It should use only non-faulting data prefetch
instructions.
@end table

@node Incdec
@section Embedded Side-Effects on Addresses
@cindex RTL preincrement
@cindex RTL postincrement
@cindex RTL predecrement
@cindex RTL postdecrement

Six 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:

@smallexample
(mem:DF (pre_dec:SI (reg:SI 39)))
@end smallexample

@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.

@findex post_modify
@item (post_modify:@var{m} @var{x} @var{y})

Represents the side effect of setting @var{x} to @var{y} and
represents @var{x} before @var{x} is modified.  @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 expression @var{y} must be one of three forms:
@code{(plus:@var{m} @var{x} @var{z})},
@code{(minus:@var{m} @var{x} @var{z})}, or
@code{(plus:@var{m} @var{x} @var{i})},
where @var{z} is an index register and @var{i} is a constant.

Here is an example of its use:

@smallexample
(mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
                                          (reg:SI 48))))
@end smallexample

This says to modify pseudo register 42 by adding the contents of pseudo
register 48 to it, after the use of what ever 42 points to.

@findex pre_modify
@item (pre_modify:@var{m} @var{x} @var{expr})
Similar except side effects happen before the use.
@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
@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 an @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 Debug Information
@section Variable Location Debug Information in RTL
@cindex Variable Location Debug Information in RTL

Variable tracking relies on @code{MEM_EXPR} and @code{REG_EXPR}
annotations to determine what user variables memory and register
references refer to.

Variable tracking at assignments uses these notes only when they refer
to variables that live at fixed locations (e.g., addressable
variables, global non-automatic variables).  For variables whose
location may vary, it relies on the following types of notes.

@table @code
@findex var_location
@item (var_location:@var{mode} @var{var} @var{exp} @var{stat})
Binds variable @code{var}, a tree, to value @var{exp}, an RTL
expression.  It appears only in @code{NOTE_INSN_VAR_LOCATION} and
@code{DEBUG_INSN}s, with slightly different meanings.  @var{mode}, if
present, represents the mode of @var{exp}, which is useful if it is a
modeless expression.  @var{stat} is only meaningful in notes,
indicating whether the variable is known to be initialized or
uninitialized.

@findex debug_expr
@item (debug_expr:@var{mode} @var{decl})
Stands for the value bound to the @code{DEBUG_EXPR_DECL} @var{decl},
that points back to it, within value expressions in
@code{VAR_LOCATION} nodes.

@findex debug_implicit_ptr
@item (debug_implicit_ptr:@var{mode} @var{decl})
Stands for the location of a @var{decl} that is no longer addressable.

@findex entry_value
@item (entry_value:@var{mode} @var{decl})
Stands for the value a @var{decl} had at the entry point of the
containing function.

@findex debug_parameter_ref
@item (debug_parameter_ref:@var{mode} @var{decl})
Refers to a parameter that was completely optimized out.

@findex debug_marker
@item (debug_marker:@var{mode})
Marks a program location.  With @code{VOIDmode}, it stands for the
beginning of a statement, a recommended inspection point logically after
all prior side effects, and before any subsequent side effects.  With
@code{BLKmode}, it indicates an inline entry point: the lexical block
encoded in the @code{INSN_LOCATION} is the enclosing block that encloses
the inlined function.

@end table

@node Insns
@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,

@smallexample
NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
@end smallexample

@noindent
is always true and if @var{insn} is not the last insn,

@smallexample
PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
@end smallexample

@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}))} if @var{insn} is the last
insn in the @code{sequence} expression.  You can use these expressions
to find the containing @code{sequence} expression.

Every insn has one of the following 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 to
which @code{pc} can be set in that instruction).  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; other jump target labels are recorded
as @code{REG_LABEL_TARGET} notes.  The exception is @code{addr_vec}
and @code{addr_diff_vec}, where @code{JUMP_LABEL} is @code{NULL_RTX}
and the only way to find the labels is to scan the entire body of the
insn.

Return insns count as jumps, but their @code{JUMP_LABEL} is @code{RETURN}
or @code{SIMPLE_RETURN}.

@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}, @code{clobber} and
sometimes @code{set} expressions that denote hard registers and
@code{mem}s used or clobbered by the called function.

A @code{mem} generally points to a stack slot in which arguments passed
to the libcall by reference (@pxref{Register Arguments,
TARGET_PASS_BY_REFERENCE}) are stored.  If the argument is
caller-copied (@pxref{Register Arguments, TARGET_CALLEE_COPIES}),
the stack slot will be mentioned in @code{clobber} and @code{use}
entries; if it's callee-copied, only a @code{use} will appear, and the
@code{mem} may point to addresses that are not stack slots.

Registers occurring inside a @code{clobber} in this list augment
registers specified in @code{CALL_USED_REGISTERS} (@pxref{Register
Basics}).

If the list contains a @code{set} involving two registers, it indicates
that the function returns one of its arguments.  Such a @code{set} may
look like a no-op if the same register holds the argument and the return
value.

@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.

Besides as a @code{code_label}, a label can also be represented as a
@code{note} of type @code{NOTE_INSN_DELETED_LABEL}.

@findex LABEL_NUSES
The field @code{LABEL_NUSES} is only defined once the jump optimization
phase is completed.  It contains the number of times this label is
referenced in the current function.

@findex LABEL_KIND
@findex SET_LABEL_KIND
@findex LABEL_ALT_ENTRY_P
@cindex alternate entry points
The field @code{LABEL_KIND} differentiates four different types of
labels: @code{LABEL_NORMAL}, @code{LABEL_STATIC_ENTRY},
@code{LABEL_GLOBAL_ENTRY}, and @code{LABEL_WEAK_ENTRY}.  The only labels
that do not have type @code{LABEL_NORMAL} are @dfn{alternate entry
points} to the current function.  These may be static (visible only in
the containing translation unit), global (exposed to all translation
units), or weak (global, but can be overridden by another symbol with the
same name).

Much of the compiler treats all four kinds of label identically.  Some
of it needs to know whether or not a label is an alternate entry point;
for this purpose, the macro @code{LABEL_ALT_ENTRY_P} is provided.  It is
equivalent to testing whether @samp{LABEL_KIND (label) == LABEL_NORMAL}.
The only place that cares about the distinction between static, global,
and weak alternate entry points, besides the front-end code that creates
them, is the function @code{output_alternate_entry_point}, in
@file{final.cc}.

To set the kind of a label, use the @code{SET_LABEL_KIND} macro.

@findex jump_table_data
@item jump_table_data
A @code{jump_table_data} insn is a placeholder for the jump-table data
of a @code{casesi} or @code{tablejump} insn.  They are placed after
a @code{tablejump_p} insn.  A @code{jump_table_data} insn is not part o
a basic blockm but it is associated with the basic block that ends with
the @code{tablejump_p} insn.  The @code{PATTERN} of a @code{jump_table_data}
is always either an @code{addr_vec} or an @code{addr_diff_vec}, and a
@code{jump_table_data} insn is always preceded by a @code{code_label}.
The @code{tablejump_p} insn refers to that @code{code_label} via its
@code{JUMP_LABEL}.

@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_DELETED_LABEL
@item NOTE_INSN_DELETED_LABEL
This marks what used to be a @code{code_label}, but was not used for other
purposes than taking its address and was transformed to mark that no
code jumps to it.

@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_EH_REGION_BEG
@findex NOTE_INSN_EH_REGION_END
@item NOTE_INSN_EH_REGION_BEG
@itemx NOTE_INSN_EH_REGION_END
These types of notes indicate the position of the beginning and end of a
level of scoping for exception handling.  @code{NOTE_EH_HANDLER}
identifies which region is associated with these notes.

@findex NOTE_INSN_FUNCTION_BEG
@item NOTE_INSN_FUNCTION_BEG
Appears at the start of the function body, after the function
prologue.

@findex NOTE_INSN_VAR_LOCATION
@findex NOTE_VAR_LOCATION
@item NOTE_INSN_VAR_LOCATION
This note is used to generate variable location debugging information.
It indicates that the user variable in its @code{VAR_LOCATION} operand
is at the location given in the RTL expression, or holds a value that
can be computed by evaluating the RTL expression from that static
point in the program up to the next such note for the same user
variable.

@findex NOTE_INSN_BEGIN_STMT
@item NOTE_INSN_BEGIN_STMT
This note is used to generate @code{is_stmt} markers in line number
debugging information.  It indicates the beginning of a user
statement.

@findex NOTE_INSN_INLINE_ENTRY
@item NOTE_INSN_INLINE_ENTRY
This note is used to generate @code{entry_pc} for inlined subroutines in
debugging information.  It indicates an inspection point at which all
arguments for the inlined function have been bound, and before its first
statement.

@end table

These codes are printed symbolically when they appear in debugging dumps.

@findex debug_insn
@findex INSN_VAR_LOCATION
@item debug_insn
The expression code @code{debug_insn} is used for pseudo-instructions
that hold debugging information for variable tracking at assignments
(see @option{-fvar-tracking-assignments} option).  They are the RTL
representation of @code{GIMPLE_DEBUG} statements
(@ref{@code{GIMPLE_DEBUG}}), with a @code{VAR_LOCATION} operand that
binds a user variable tree to an RTL representation of the
@code{value} in the corresponding statement.  A @code{DEBUG_EXPR} in
it stands for the value bound to the corresponding
@code{DEBUG_EXPR_DECL}.

@code{GIMPLE_DEBUG_BEGIN_STMT} and @code{GIMPLE_DEBUG_INLINE_ENTRY} are
expanded to RTL as a @code{DEBUG_INSN} with a @code{DEBUG_MARKER}
@code{PATTERN}; the difference is the RTL mode: the former's
@code{DEBUG_MARKER} is @code{VOIDmode}, whereas the latter is
@code{BLKmode}; information about the inlined function can be taken from
the lexical block encoded in the @code{INSN_LOCATION}.  These
@code{DEBUG_INSN}s, that do not carry @code{VAR_LOCATION} information,
just @code{DEBUG_MARKER}s, can be detected by testing
@code{DEBUG_MARKER_INSN_P}, whereas those that do can be recognized as
@code{DEBUG_BIND_INSN_P}.

Throughout optimization passes, @code{DEBUG_INSN}s are not reordered
with respect to each other, particularly during scheduling.  Binding
information is kept in pseudo-instruction form, so that, unlike notes,
it gets the same treatment and adjustments that regular instructions
would.  It is the variable tracking pass that turns these
pseudo-instructions into @code{NOTE_INSN_VAR_LOCATION},
@code{NOTE_INSN_BEGIN_STMT} and @code{NOTE_INSN_INLINE_ENTRY} notes,
analyzing control flow, value equivalences and changes to registers and
memory referenced in value expressions, propagating the values of debug
temporaries and determining expressions that can be used to compute the
value of each user variable at as many points (ranges, actually) in the
program as possible.

Unlike @code{NOTE_INSN_VAR_LOCATION}, the value expression in an
@code{INSN_VAR_LOCATION} denotes a value at that specific point in the
program, rather than an expression that can be evaluated at any later
point before an overriding @code{VAR_LOCATION} is encountered.  E.g.,
if a user variable is bound to a @code{REG} and then a subsequent insn
modifies the @code{REG}, the note location would keep mapping the user
variable to the register across the insn, whereas the insn location
would keep the variable bound to the value, so that the variable
tracking pass would emit another location note for the variable at the
point in which the register is modified.

@end table

@cindex @code{TImode}, in @code{insn}
@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.

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.

The second Haifa scheduling pass, for targets that can multiple issue,
sets the mode of an insn to @code{TImode} when it is believed that the
instruction begins an issue group.  That is, when the instruction
cannot issue simultaneously with the previous.  This may be relied on
by later passes, in particular machine-dependent reorg.

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{simple_return}, @code{asm_input},
@code{asm_output}, @code{addr_vec}, @code{addr_diff_vec},
@code{trap_if}, @code{unspec}, @code{unspec_volatile},
@code{parallel}, @code{cond_exec}, 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 @minus{}1 if the matching has not yet been attempted.

Such matching is never attempted and this field remains @minus{}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 REG_NOTES
@item REG_NOTES (@var{i})
A list (chain of @code{expr_list}, @code{insn_list} and @code{int_list}
expressions) giving miscellaneous information about the insn.  It is often
information pertaining to the registers used in this insn.
@end table

The @code{REG_NOTES} field of an insn is a chain that includes
@code{expr_list} and @code{int_list} expressions as well as @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.

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.

It does not follow that the register @var{op} has no useful value after
this insn since @var{op} is not necessarily modified by this insn.
Rather, no subsequent instruction uses the contents of @var{op}.

@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_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 by special looping instructions
that terminate when the register goes negative.

The @code{REG_NONNEG} note is added only to @samp{doloop_end}
insns, if its pattern uses a @code{ge} condition.

@findex REG_LABEL_OPERAND
@item REG_LABEL_OPERAND
This insn uses @var{op}, a @code{code_label} or a @code{note} of type
@code{NOTE_INSN_DELETED_LABEL}, but is not a @code{jump_insn}, or it
is a @code{jump_insn} that refers to the operand as an ordinary
operand.  The label may still eventually be a jump target, but if so
in an indirect jump in a subsequent insn.  The presence of this note
allows jump optimization to be aware that @var{op} is, in fact, being
used, and flow optimization to build an accurate flow graph.

@findex REG_LABEL_TARGET
@item REG_LABEL_TARGET
This insn is a @code{jump_insn} but not an @code{addr_vec} or
@code{addr_diff_vec}.  It uses @var{op}, a @code{code_label} as a
direct or indirect jump target.  Its purpose is similar to that of
@code{REG_LABEL_OPERAND}.  This note is only present if the insn has
multiple targets; the last label in the insn (in the highest numbered
insn-field) goes into the @code{JUMP_LABEL} field and does not have a
@code{REG_LABEL_TARGET} note.  @xref{Insns, JUMP_LABEL}.

@findex REG_SETJMP
@item REG_SETJMP
Appears attached to each @code{CALL_INSN} to @code{setjmp} or a
related function.
@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} or
@code{zero_extract} expression, the note refers to the register that
is contained in its first operand.

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.

A @code{REG_EQUIV} note is also used on an instruction which copies a
register parameter into a pseudo-register at entry to a function, if
there is a stack slot where that parameter could be stored.  Although
other insns may set the pseudo-register, it is valid for the compiler to
replace the pseudo-register by stack slot throughout the function,
provided the compiler ensures that the stack slot is properly
initialized by making the replacement in the initial copy instruction as
well.  This is used on machines for which the calling convention
allocates stack space for register parameters.  See
@code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}.

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 their 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.
@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_DEP_TRUE
@item REG_DEP_TRUE
This indicates a true dependence (a read after write dependence).

@findex REG_DEP_OUTPUT
@item REG_DEP_OUTPUT
This indicates an output dependence (a write after write dependence).

@findex REG_DEP_ANTI
@item REG_DEP_ANTI
This indicates an anti dependence (a write after read dependence).

@end table

These notes describe information gathered from gcov profile data.  They
are stored in the @code{REG_NOTES} field of an insn.

@table @code
@findex REG_BR_PROB
@item REG_BR_PROB
This is used to specify the ratio of branches to non-branches of a
branch insn according to the profile data.  The note is represented
as an @code{int_list} expression whose integer value is an encoding
of @code{profile_probability} type.  @code{profile_probability} provide
member function @code{from_reg_br_prob_note} and @code{to_reg_br_prob_note}
to extract and store the probability into the RTL encoding.

@findex REG_BR_PRED
@item REG_BR_PRED
These notes are found in JUMP insns after delayed branch scheduling
has taken place.  They indicate both the direction and the likelihood
of the JUMP@.  The format is a bitmask of ATTR_FLAG_* values.

@findex REG_FRAME_RELATED_EXPR
@item REG_FRAME_RELATED_EXPR
This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression
is used in place of the actual insn pattern.  This is done in cases where
the pattern is either complex or misleading.
@end table

The note @code{REG_CALL_NOCF_CHECK} is used in conjunction with the
@option{-fcf-protection=branch} option.  The note is set if a
@code{nocf_check} attribute is specified for a function type or a
pointer to function type.  The note is stored in the @code{REG_NOTES}
field of an insn.

@table @code
@findex REG_CALL_NOCF_CHECK
@item REG_CALL_NOCF_CHECK
Users have control through the @code{nocf_check} attribute to identify
which calls to a function should be skipped from control-flow instrumentation
when the option @option{-fcf-protection=branch} is specified.  The compiler
puts a @code{REG_CALL_NOCF_CHECK} note on each @code{CALL_INSN} instruction
that has a function type marked with a @code{nocf_check} attribute.
@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
@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:

@smallexample
(call (mem:@var{fm} @var{addr}) @var{nbytes})
@end smallexample

@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:

@smallexample
(set (reg:@var{m} @var{r})
     (call (mem:@var{fm} @var{addr}) @var{nbytes}))
@end smallexample

@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 in 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 RTL SSA
@section On-the-Side SSA Form for RTL
@cindex SSA, RTL form
@cindex RTL SSA

The patterns of an individual RTL instruction describe which registers
are inputs to that instruction and which registers are outputs from
that instruction.  However, it is often useful to know where the
definition of a register input comes from and where the result of
a register output is used.  One way of obtaining this information
is to use the RTL SSA form, which provides a Static Single Assignment
representation of the RTL instructions.

The RTL SSA code is located in the @file{rtl-ssa} subdirectory of the GCC
source tree.  This section only gives a brief overview of it; please
see the comments in the source code for more details.

@menu
* Using RTL SSA::             What a pass needs to do to use the RTL SSA form
* RTL SSA Instructions::      How instructions are represented and organized
* RTL SSA Basic Blocks::      How instructions are grouped into blocks
* RTL SSA Resources::         How registers and memory are represented
* RTL SSA Accesses::          How register and memory accesses are represented
* RTL SSA Phi Nodes::         How multiple sources are combined into one
* RTL SSA Access Lists::      How accesses are chained together
* Changing RTL Instructions:: How to use the RTL SSA framework to change insns
@end menu

@node Using RTL SSA
@subsection Using RTL SSA in a pass

A pass that wants to use the RTL SSA form should start with the following:

@smallexample
#define INCLUDE_ALGORITHM
#define INCLUDE_FUNCTIONAL
#include "config.h"
#include "system.h"
#include "coretypes.h"
#include "backend.h"
#include "rtl.h"
#include "df.h"
#include "rtl-ssa.h"
@end smallexample

All the RTL SSA code is contained in the @code{rtl_ssa} namespace,
so most passes will then want to do:

@smallexample
using namespace rtl_ssa;
@end smallexample

However, this is purely a matter of taste, and the examples in the rest of
this section do not require it.

The RTL SSA represention is an optional on-the-side feature that applies
on top of the normal RTL instructions.  It is currently local to individual
RTL passes and is not maintained across passes.

However, in order to allow the RTL SSA information to be preserved across
passes in future, @samp{crtl->ssa} points to the current function's
SSA form (if any).  Passes that want to use the RTL SSA form should
first do:

@smallexample
crtl->ssa = new rtl_ssa::function_info (@var{fn});
@end smallexample

where @var{fn} is the function that the pass is processing.
(Passes that are @code{using namespace rtl_ssa} do not need
the @samp{rtl_ssa::}.)

Once the pass has finished with the SSA form, it should do the following:

@smallexample
free_dominance_info (CDI_DOMINATORS);
if (crtl->ssa->perform_pending_updates ())
  cleanup_cfg (0);

delete crtl->ssa;
crtl->ssa = nullptr;
@end smallexample

The @code{free_dominance_info} call is necessary because
dominance information is not currently maintained between RTL passes.
The next two lines commit any changes to the RTL instructions that
were queued for later; see the comment above the declaration of
@code{perform_pending_updates} for details.  The final two lines
discard the RTL SSA form and free the associated memory.

@node RTL SSA Instructions
@subsection RTL SSA Instructions

@cindex RPO
@cindex reverse postorder
@cindex instructions, RTL SSA
@findex rtl_ssa::insn_info
RTL SSA instructions are represented by an @code{rtl_ssa::insn_info}.
These instructions are chained together in a single list that follows
a reverse postorder (RPO) traversal of the function.  This means that
if any path through the function can execute an instruction @var{I1}
and then later execute an instruction @var{I2} for the first time,
@var{I1} appears before @var{I2} in the list@footnote{Note that this
order is different from the order of the underlying RTL instructions,
which follow machine code order instead.}.

Two RTL SSA instructions can be compared to find which instruction
occurs earlier than the other in the RPO@.  One way to do this is
to use the C++ comparison operators, such as:

@example
*@var{insn1} < *@var{insn2}
@end example

Another way is to use the @code{compare_with} function:

@example
@var{insn1}->compare_with (@var{insn2})
@end example

This expression is greater than zero if @var{insn1} comes after @var{insn2}
in the RPO, less than zero if @var{insn1} comes before @var{insn2} in the
RPO, or zero if @var{insn1} and @var{insn2} are the same.  This order is
maintained even if instructions are added to the function or moved around.

The main purpose of @code{rtl_ssa::insn_info} is to hold
SSA information about an instruction.  However, it also caches
certain properties of the instruction, such as whether it is an
inline assembly instruction, whether it has volatile accesses, and so on.

@node RTL SSA Basic Blocks
@subsection RTL SSA Basic Blocks

@cindex basic blocks, RTL SSA
@findex basic_block
@findex rtl_ssa::bb_info
RTL SSA instructions (@pxref{RTL SSA Instructions}) are organized into
basic blocks, with each block being represented by an @code{rtl_ssa:bb_info}.
There is a one-to-one mapping between these @code{rtl_ssa:bb_info}
structures and the underlying CFG @code{basic_block} structures
(@pxref{Basic Blocks}).

@cindex ``real'' instructions, RTL SSA
@anchor{real RTL SSA insns}
If a CFG basic block @var{bb} contains an RTL instruction @var{insn},
the RTL SSA represenation of @var{bb} also contains an RTL SSA representation
of @var{insn}@footnote{Note that this excludes non-instruction things like
@code{note}s and @code{barrier}s that also appear in the chain of RTL
instructions.}.  Within RTL SSA, these instructions are referred to as
``real'' instructions.  These real instructions fall into two groups:
debug instructions and nondebug instructions.  Only nondebug instructions
should affect code generation decisions.

In addition, each RTL SSA basic block has two ``artificial''
instructions: a ``head'' instruction that comes before all the real
instructions and an ``end'' instruction that comes after all real
instructions.  These instructions exist to represent things that
are conceptually defined or used at the start and end of a basic block.
The instructions always exist, even if they do not currently do anything.

Like instructions, these blocks are chained together in a reverse
postorder.  This list includes the entry block (which always comes
first) and the exit block (which always comes last).

@cindex extended basic blocks, RTL SSA
@findex rtl_ssa::ebb_info
RTL SSA basic blocks are chained together into ``extended basic blocks''
(EBBs), represented by an @code{rtl_ssa::ebb_info}.  Extended basic
blocks contain one or more basic blocks.  They have the property
that if a block @var{bby} comes immediately after a block @var{bbx}
in an EBB, then @var{bby} can only be reached by @var{bbx}; in other words,
@var{bbx} is the sole predecessor of @var{bby}.

Each extended basic block starts with an artificial ``phi node''
instruction.  This instruction defines all phi nodes for the EBB
(@pxref{RTL SSA Phi Nodes}).  (Individual blocks in an EBB do not
need phi nodes because their live values can only come from one source.)

The contents of a function are therefore represented using a
four-level hierarchy:

@itemize @bullet
@item
functions (@code{rtl_ssa::function_info}), which contain @dots{}

@item
extended basic blocks (@code{rtl_ssa::ebb_info}), which contain @dots{}

@item
basic blocks (@code{rtl_ssa::bb_info}), which contain @dots{}

@item
instructions (@code{rtl_ssa::insn_info})
@end itemize

In dumps, a basic block is identified as @code{bb@var{n}}, where @var{n}
is the index of the associated CFG @code{basic_block} structure.
An EBB is in turn identified by the index of its first block.
For example, an EBB that contains @samp{bb10}, @code{bb5}, @code{bb6}
and @code{bb9} is identified as @var{ebb10}.

@node RTL SSA Resources
@subsection RTL SSA Resources

The RTL SSA form tracks two types of ``resource'': registers and memory.
Each hard and pseudo register is a separate resource.  Memory is a
single unified resource, like it is in GIMPLE (@pxref{GIMPLE}).

Each resource has a unique identifier.  The unique identifier for a
register is simply its register number.  The unique identifier for
memory is a special register number called @code{MEM_REGNO}.

Since resource numbers so closely match register numbers, it is sometimes
convenient to refer to them simply as register numbers, or ``regnos''
for short.  However, the RTL SSA form also provides an abstraction
of resources in the form of @code{rtl_ssa::resource_info}.
This is a lightweight class that records both the regno of a resource
and the @code{machine_mode} that the resource has (@pxref{Machine Modes}).
It has functions for testing whether a resource is a register or memory.
In principle it could be extended to other kinds of resource in future.

@node RTL SSA Accesses
@subsection RTL SSA Register and Memory Accesses

In the RTL SSA form, most reads or writes of a resource are
represented as a @code{rtl_ssa::access_info}@footnote{The exceptions
are call clobbers, which are generally represented separately.
See the comment above @code{rtl_ssa::insn_info} for details.}.
These @code{rtl_ssa::access_info}s are organized into the following
class hierarchy:

@findex rtl_ssa::access_info
@findex rtl_ssa::use_info
@findex rtl_ssa::def_info
@findex rtl_ssa::clobber_info
@findex rtl_ssa::set_info
@findex rtl_ssa::phi_info
@smallexample
rtl_ssa::access_info
  |
  +-- rtl_ssa::use_info
  |
  +-- rtl_ssa::def_info
        |
        +-- rtl_ssa::clobber_info
        |
        +-- rtl_ssa::set_info
              |
              +-- rtl_ssa::phi_info
@end smallexample

A @code{rtl_ssa::use_info} represents a read or use of a resource and
a @code{rtl_ssa::def_info} represents a write or definition of a resource.
As in the main RTL representation, there are two basic types of
definition: clobbers and sets.  The difference is that a clobber
leaves the register with an unspecified value that cannot be used
or relied on by later instructions, while a set leaves the register
with a known value that later instructions could use if they wanted to.
A @code{rtl_ssa::clobber_info} represents a clobber and
a @code{rtl_ssa::set_info} represent a set.

Each @code{rtl_ssa::use_info} records which single @code{rtl_ssa::set_info}
provides the value of the resource; this is null if the resource is
completely undefined at the point of use.  Each @code{rtl_ssa::set_info}
in turn records all the @code{rtl_ssa::use_info}s that use its value.

If a value of a resource can come from multiple sources,
a @code{rtl_ssa::phi_info} brings those multiple sources together
into a single definition (@pxref{RTL SSA Phi Nodes}).

@node RTL SSA Phi Nodes
@subsection RTL SSA Phi Nodes

@cindex phi nodes, RTL SSA
@findex rtl_ssa::phi_info
If a resource is live on entry to an extended basic block and if the
resource's value can come from multiple sources, the extended basic block
has a ``phi node'' that collects together these multiple sources.
The phi node conceptually has one input for each incoming edge of
the extended basic block, with the input specifying the value of
the resource on that edge.  For example, suppose a function contains
the following RTL:

@smallexample
;; Basic block bb3
@dots{}
(set (reg:SI R1) (const_int 0))  ;; A
(set (pc) (label_ref bb5))

;; Basic block bb4
@dots{}
(set (reg:SI R1) (const_int 1))  ;; B
;; Fall through

;; Basic block bb5
;; preds: bb3, bb4
;; live in: R1 @dots{}
(code_label bb5)
@dots{}
(set (reg:SI @var{R2})
     (plus:SI (reg:SI R1) @dots{}))  ;; C
@end smallexample

The value of R1 on entry to block 5 can come from either A or B@.
The extended basic block that contains block 5 would therefore have a
phi node with two inputs: the first input would have the value of
R1 defined by A and the second input would have the value of
R1 defined by B@.  This phi node would then provide the value of
R1 for C (assuming that R1 does not change again between
the start of block 5 and C).

Since RTL is not a ``native'' SSA representation, these phi nodes
simply collect together definitions that already exist.  Each input
to a phi node for a resource @var{R} is itself a definition of
resource @var{R} (or is null if the resource is completely
undefined for a particular incoming edge).  This is in contrast
to a native SSA representation like GIMPLE, where the phi inputs
can be arbitrary expressions.  As a result, RTL SSA phi nodes
never involve ``hidden'' moves: all moves are instead explicit.

Phi nodes are represented as a @code{rtl_ssa::phi_node}.
Each input to a phi node is represented as an @code{rtl_ssa::use_info}.

@node RTL SSA Access Lists
@subsection RTL SSA Access Lists

All the definitions of a resource are chained together in reverse postorder.
In general, this list can contain an arbitrary mix of both sets
(@code{rtl_ssa::set_info}) and clobbers (@code{rtl_ssa::clobber_info}).
However, it is often useful to skip over all intervening clobbers
of a resource in order to find the next set.  The list is constructed
in such a way that this can be done in amortized constant time.

All uses (@code{rtl_ssa::use_info}) of a given set are also chained
together into a list.  This list of uses is divided into three parts:

@enumerate
@item
uses by ``real'' nondebug instructions (@pxref{real RTL SSA insns})

@item
uses by real debug instructions

@item
uses by phi nodes (@pxref{RTL SSA Phi Nodes})
@end enumerate

The first and second parts individually follow reverse postorder.
The third part has no particular order.

@cindex degenerate phi node, RTL SSA
The last use by a real nondebug instruction always comes earlier in
the reverse postorder than the next definition of the resource (if any).
This means that the accesses follow a linear sequence of the form:

@itemize @bullet
@item
first definition of resource R

@itemize @bullet
@item
first use by a real nondebug instruction of the first definition of resource R

@item
@dots{}

@item
last use by a real nondebug instruction of the first definition of resource R
@end itemize

@item
second definition of resource R

@itemize @bullet
@item
first use by a real nondebug instruction of the second definition of resource R

@item
@dots{}

@item
last use by a real nondebug instruction of the second definition of resource R
@end itemize

@item
@dots{}

@item
last definition of resource R

@itemize @bullet
@item
first use by a real nondebug instruction of the last definition of resource R

@item
@dots{}

@item
last use by a real nondebug instruction of the last definition of resource R
@end itemize
@end itemize

(Note that clobbers never have uses; only sets do.)

This linear view is easy to achieve when there is only a single definition
of a resource, which is commonly true for pseudo registers.  However,
things are more complex  if code has a structure like the following:

@smallexample
// ebb2, bb2
R = @var{va};        // A
if (@dots{})
  @{
    // ebb2, bb3
    use1 (R);  // B
    @dots{}
    R = @var{vc};    // C
  @}
else
  @{
    // ebb4, bb4
    use2 (R);  // D
  @}
@end smallexample

The list of accesses would begin as follows:

@itemize @bullet
@item
definition of R by A

@itemize @bullet
@item
use of A's definition of R by B
@end itemize

@item
definition of R by C
@end itemize

The next access to R is in D, but the value of R that D uses comes from
A rather than C@.

This is resolved by adding a phi node for @code{ebb4}.  All inputs to this
phi node have the same value, which in the example above is A's definition
of R@.  In other circumstances, it would not be necessary to create a phi
node when all inputs are equal, so these phi nodes are referred to as
``degenerate'' phi nodes.

The full list of accesses to R is therefore:

@itemize @bullet
@item
definition of R by A

@itemize @bullet
@item
use of A's definition of R by B
@end itemize

@item
definition of R by C

@item
definition of R by ebb4's phi instruction, with the input coming from A

@itemize @bullet
@item
use of the ebb4's R phi definition of R by B
@end itemize
@end itemize

Note that A's definition is also used by ebb4's phi node, but this
use belongs to the third part of the use list described above and
so does not form part of the linear sequence.

It is possible to ``look through'' any degenerate phi to the ultimate
definition using the function @code{look_through_degenerate_phi}.
Note that the input to a degenerate phi is never itself provided
by a degenerate phi.

At present, the SSA form takes this principle one step further
and guarantees that, for any given resource @var{res}, one of the
following is true:

@itemize
@item
The resource has a single definition @var{def}, which is not a phi node.
Excluding uses of undefined registers, all uses of @var{res} by real
nondebug instructions use the value provided by @var{def}.

@item
Excluding uses of undefined registers, all uses of @var{res} use
values provided by definitions that occur earlier in the same
extended basic block.  These definitions might come from phi nodes
or from real instructions.
@end itemize

@node Changing RTL Instructions
@subsection Using the RTL SSA framework to change instructions

@findex rtl_ssa::insn_change
There are various routines that help to change a single RTL instruction
or a group of RTL instructions while keeping the RTL SSA form up-to-date.
This section first describes the process for changing a single instruction,
then goes on to describe the differences when changing multiple instructions.

@menu
* Changing One RTL SSA Instruction::
* Changing Multiple RTL SSA Instructions::
@end menu

@node Changing One RTL SSA Instruction
@subsubsection Changing One RTL SSA Instruction

Before making a change, passes should first use a statement like the
following:

@smallexample
auto attempt = crtl->ssa->new_change_attempt ();
@end smallexample

Here, @code{attempt} is an RAII object that should remain in scope
for the entire change attempt.  It automatically frees temporary
memory related to the changes when it goes out of scope.

Next, the pass should create an @code{rtl_ssa::insn_change} object
for the instruction that it wants to change.  This object specifies
several things:

@itemize @bullet
@item
what the instruction's new list of uses should be (@code{new_uses}).
By default this is the same as the instruction's current list of uses.

@item
what the instruction's new list of definitions should be (@code{new_defs}).
By default this is the same as the instruction's current list of
definitions.

@item
where the instruction should be located (@code{move_range}).
This is a range of instructions after which the instruction could
be placed, represented as an @code{rtl_ssa::insn_range}.
By default the instruction must remain at its current position.
@end itemize

If a pass was attempting to change all these properties of an instruction
@code{insn}, it might do something like this:

@smallexample
rtl_ssa::insn_change change (insn);
change.new_defs = @dots{};
change.new_uses = @dots{};
change.move_range = @dots{};
@end smallexample

This @code{rtl_ssa::insn_change} only describes something that the
pass @emph{might} do; at this stage, nothing has actually changed.

As noted above, the default @code{move_range} requires the instruction
to remain where it is.  At the other extreme, it is possible to allow
the instruction to move anywhere within its extended basic block,
provided that all the new uses and definitions can be performed
at the new location.  The way to do this is:

@smallexample
change.move_range = insn->ebb ()->insn_range ();
@end smallexample

In either case, the next step is to make sure that move range is
consistent with the new uses and definitions.  The way to do this is:

@smallexample
if (!rtl_ssa::restrict_movement (change))
  return false;
@end smallexample

This function tries to limit @code{move_range} to a range of instructions
at which @code{new_uses} and @code{new_defs} can be correctly performed.
It returns true on success or false if no suitable location exists.

The pass should also tentatively change the pattern of the instruction
to whatever form the pass wants the instruction to have.  This should use
the facilities provided by @file{recog.cc}.  For example:

@smallexample
rtl_insn *rtl = insn->rtl ();
insn_change_watermark watermark;
validate_change (rtl, &PATTERN (rtl), new_pat, 1);
@end smallexample

will tentatively replace @code{insn}'s pattern with @code{new_pat}.

These changes and the construction of the @code{rtl_ssa::insn_change}
can happen in either order or be interleaved.

After the tentative changes to the instruction are complete,
the pass should check whether the new pattern matches a target
instruction or satisfies the requirements of an inline asm:

@smallexample
if (!rtl_ssa::recog (change))
  return false;
@end smallexample

This step might change the instruction pattern further in order to
make it match.  It might also add new definitions or restrict the range
of the move.  For example, if the new pattern did not match in its original
form, but could be made to match by adding a clobber of the flags
register, @code{rtl_ssa::recog} will check whether the flags register
is free at an appropriate point.  If so, it will add a clobber of the
flags register to @code{new_defs} and restrict @code{move_range} to
the locations at which the flags register can be safely clobbered.

Even if the proposed new instruction is valid according to
@code{rtl_ssa::recog}, the change might not be worthwhile.
For example, when optimizing for speed, the new instruction might
turn out to be slower than the original one.  When optimizing for
size, the new instruction might turn out to be bigger than the
original one.

Passes should check for this case using @code{change_is_worthwhile}.
For example:

@smallexample
if (!rtl_ssa::change_is_worthwhile (change))
  return false;
@end smallexample

If the change passes this test too then the pass can perform the change using:

@smallexample
confirm_change_group ();
crtl->ssa->change_insn (change);
@end smallexample

Putting all this together, the change has the following form:

@smallexample
auto attempt = crtl->ssa->new_change_attempt ();

rtl_ssa::insn_change change (insn);
change.new_defs = @dots{};
change.new_uses = @dots{};
change.move_range = @dots{};

if (!rtl_ssa::restrict_movement (change))
  return false;

insn_change_watermark watermark;
// Use validate_change etc. to change INSN's pattern.
@dots{}
if (!rtl_ssa::recog (change)
    || !rtl_ssa::change_is_worthwhile (change))
  return false;

confirm_change_group ();
crtl->ssa->change_insn (change);
@end smallexample

@node Changing Multiple RTL SSA Instructions
@subsubsection Changing Multiple RTL SSA Instructions

The process for changing multiple instructions is similar
to the process for changing single instructions
(@pxref{Changing One RTL SSA Instruction}).  The pass should
again start the change attempt with:

@smallexample
auto attempt = crtl->ssa->new_change_attempt ();
@end smallexample

and keep @code{attempt} in scope for the duration of the change
attempt.  It should then construct an @code{rtl_ssa::insn_change}
for each change that it wants to make.

After this, it should combine the changes into a sequence of
@code{rtl_ssa::insn_change} pointers.  This sequence must be in
reverse postorder; the instructions will remain strictly in the
order that the sequence specifies.

For example, if a pass is changing exactly two instructions,
it might do:

@smallexample
rtl_ssa::insn_change *changes[] = @{ &change1, change2 @};
@end smallexample

where @code{change1}'s instruction must come before @code{change2}'s.
Alternatively, if the pass is changing a variable number of
instructions, it might build up the sequence in a
@code{vec<rtl_ssa::insn_change *>}.

By default, @code{rtl_ssa::restrict_movement} assumes that all
instructions other than the one passed to it will remain in their
current positions and will retain their current uses and definitions.
When changing multiple instructions, it is usually more effective
to ignore the other instructions that are changing.  The sequencing
described above ensures that the changing instructions remain
in the correct order with respect to each other.
The way to do this is:

@smallexample
if (!rtl_ssa::restrict_movement (change, insn_is_changing (changes)))
  return false;
@end smallexample

Similarly, when @code{rtl_ssa::restrict_movement} is detecting
whether a register can be clobbered, it by default assumes that
all other instructions will remain in their current positions and
retain their current form.  It is again more effective to ignore
changing instructions (which might, for example, no longer need
to clobber the flags register).  The way to do this is:

@smallexample
if (!rtl_ssa::recog (change, insn_is_changing (changes)))
  return false;
@end smallexample

When changing multiple instructions, the important question is usually
not whether each individual change is worthwhile, but whether the changes
as a whole are worthwhile.  The way to test this is:

@smallexample
if (!rtl_ssa::changes_are_worthwhile (changes))
  return false;
@end smallexample

The process for changing single instructions makes sure that one
@code{rtl_ssa::insn_change} in isolation is valid.  But when changing
multiple instructions, it is also necessary to test whether the
sequence as a whole is valid.  For example, it might be impossible
to satisfy all of the @code{move_range}s at once.

Therefore, once the pass has a sequence of changes that are
individually correct, it should use:

@smallexample
if (!crtl->ssa->verify_insn_changes (changes))
  return false;
@end smallexample

to check whether the sequence as a whole is valid.  If all checks pass,
the final step is:

@smallexample
confirm_change_group ();
crtl->ssa->change_insns (changes);
@end smallexample

Putting all this together, the process for a two-instruction change is:

@smallexample
auto attempt = crtl->ssa->new_change_attempt ();

rtl_ssa::insn_change change (insn1);
change1.new_defs = @dots{};
change1.new_uses = @dots{};
change1.move_range = @dots{};

rtl_ssa::insn_change change (insn2);
change2.new_defs = @dots{};
change2.new_uses = @dots{};
change2.move_range = @dots{};

rtl_ssa::insn_change *changes[] = @{ &change1, change2 @};

auto is_changing = insn_is_changing (changes);
if (!rtl_ssa::restrict_movement (change1, is_changing)
    || !rtl_ssa::restrict_movement (change2, is_changing))
  return false;

insn_change_watermark watermark;
// Use validate_change etc. to change INSN1's and INSN2's patterns.
@dots{}
if (!rtl_ssa::recog (change1, is_changing)
    || !rtl_ssa::recog (change2, is_changing)
    || !rtl_ssa::changes_are_worthwhile (changes)
    || !crtl->ssa->verify_insn_changes (changes))
  return false;

confirm_change_group ();
crtl->ssa->change_insns (changes);
@end smallexample

@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
All @code{const_int} expressions with equal values are shared.

@cindex @code{const_poly_int}, RTL sharing
@item
All @code{const_poly_int} expressions with equal modes and values
are shared.

@cindex @code{pc}, RTL sharing
@item
There is only one @code{pc} 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{const_vector}, RTL sharing
@item
There is only one @code{const_vector} expression with value 0 for
each vector mode, be it an integer or a double constant vector.

@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.cc},
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.  This routine
is defined in @file{read-rtl.cc}.  It is not available in the compiler
itself, only the various programs that generate the compiler back end
from the machine description.

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 GCC@.  This
idea is not feasible.

GCC 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 GCC to a new language front end is with
the ``tree'' data structure, described in the files @file{tree.h} and
@file{tree.def}.  The documentation for this structure (@pxref{GENERIC})
is incomplete.