-@c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007, 2008, 2010
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1988-2024 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
* 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
by looking at an operand what kind of object it is. Instead, you must know
from its context---from the expression code of the containing expression.
For example, in an expression of code @code{subreg}, the first operand is
-to be regarded as an expression and the second operand as an integer. In
-an expression of code @code{plus}, there are two operands, both of which
-are to be regarded as expressions. In a @code{symbol_ref} expression,
-there is one operand, which is to be regarded as a string.
+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
@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{x}.
+@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
@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{<}.
+@code{RTX_COMM_COMPARE}.
@item RTX_BIN_ARITH
An RTX code for a non-commutative binary operation, such as @code{MINUS},
@item RTX_AUTOINC
An RTX code for an auto-increment addressing mode, such as
-@code{POST_INC}.
+@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
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{ei}.
+the format of @code{subreg} is @samp{ep}.
@cindex RTL format characters
These are the most commonly used format characters:
@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
is safe to assume that all comparison operations have format @code{ee}.
@table @code
-@item 1
+@item RTX_UNARY
All codes of this class have format @code{e}.
-@item <
-@itemx c
-@itemx 2
+@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 b
-@itemx 3
+@item RTX_BITFIELD_OPS
+@itemx RTX_TERNARY
All codes of these classes have format @code{eee}.
-@item i
+@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{i}.
+are of class @code{RTX_INSN}.
-@item o
-@itemx m
-@itemx x
+@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
the containing expression. That is also how you would know how many
operands there are.
-For example, if @var{x} is a @code{subreg} expression, you know that it has
-two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
-and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you
-would get the address of the expression operand but cast as an integer;
-that might occasionally be useful, but it would be cleaner to write
-@code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also
-compile without error, and would return the second, integer operand cast as
-an expression pointer, which would probably result in a crash when
-accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
-but this will access memory past the end of the expression with
+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
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} as a @code{CONST_INT} rtx.
+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})
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}
perhaps with the help of base registers.
Stored in the @code{unchanging} field and printed as @samp{/u}.
-@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 INSN_ANNULLED_BRANCH_P
@cindex @code{jump_insn} and @samp{/u}
@cindex @code{call_insn} and @samp{/u}
@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{barrier}, and @code{note}
+@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{barrier}, or @code{note},
+@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}.
a reference to a non-local label.
Stored in the @code{volatil} field and printed as @samp{/v}.
-@findex MEM_IN_STRUCT_P
-@cindex @code{mem} and @samp{/s}
-@cindex @code{in_struct}, in @code{mem}
-@item MEM_IN_STRUCT_P (@var{x})
-In @code{mem} expressions, nonzero for reference to an entire structure,
-union or array, or to a component of one. Zero for references to a
-scalar variable or through a pointer to a scalar. If both this flag and
-@code{MEM_SCALAR_P} are clear, then we don't know whether this @code{mem}
-is in a structure or not. Both flags should never be simultaneously set.
-Stored in the @code{in_struct} field and printed as @samp{/s}.
-
@findex MEM_KEEP_ALIAS_SET_P
@cindex @code{mem} and @samp{/j}
@cindex @code{jump}, in @code{mem}
are already in a non-addressable component of an aggregate.
Stored in the @code{jump} field and printed as @samp{/j}.
-@findex MEM_SCALAR_P
-@cindex @code{mem} and @samp{/i}
-@cindex @code{return_val}, in @code{mem}
-@item MEM_SCALAR_P (@var{x})
-In @code{mem} expressions, nonzero for reference to a scalar known not
-to be a member of a structure, union, or array. Zero for such
-references and for indirections through pointers, even pointers pointing
-to scalar types. If both this flag and @code{MEM_IN_STRUCT_P} are clear,
-then we don't know whether this @code{mem} is in a structure or not.
-Both flags should never be simultaneously set.
-Stored in the @code{return_val} field and printed as @samp{/i}.
-
@findex MEM_VOLATILE_P
@cindex @code{mem} and @samp{/v}
@cindex @code{asm_input} and @samp{/v}
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}
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}
This flag is required for exception handling support on targets with RTL
prologues.
-@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 transfered 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 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{in_struct}, in @code{insn}, @code{jump_insn} and @code{call_insn}
+@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} or
-@code{jump_insn}, indicates that the
+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
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.
-
-@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}.
@end table
These are the fields to which the above macros refer:
@findex in_struct
@cindex @samp{/s} in RTL dump
@item in_struct
-In @code{mem} expressions, it is 1 if the memory datum referred to is
-all or part of a structure or array; 0 if it is (or might be) a scalar
-variable. A reference through a C pointer has 0 because the pointer
-might point to a scalar variable. This information allows the compiler
-to determine something about possible cases of aliasing.
-
In @code{reg} expressions, it is 1 if the register has its entire life
contained within the test expression of some loop.
may be used for parameters as well, but this flag is not set on such
uses.
-In @code{mem} expressions, 1 means the memory reference is to a scalar
-known not to be a member of a structure, union, or array.
-
In @code{symbol_ref} expressions, 1 means the referenced symbol is weak.
In @code{call} expressions, 1 means the call is pure.
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
@findex volatil
@cindex @samp{/v} in RTL dump
-@item volatil
@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,
@section Machine Modes
@cindex machine modes
-@findex enum machine_mode
+@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{enum machine_mode}, defined in @file{machmode.def}. Each RTL
+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).
@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)
``Condition Code'' mode represents the value of a condition code, which
is a machine-specific set of bits used to represent the result of a
comparison operation. Other machine-specific modes may also be used for
-the condition code. These modes are not used on machines that use
-@code{cc0} (@pxref{Condition Code}).
+the condition code. (@pxref{Condition Code}).
@findex BLKmode
@item BLKmode
@findex CDImode
@findex CTImode
@findex COImode
-@item CQImode, CHImode, CSImode, CDImode, CTImode, 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}, and @code{OImode},
+@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
@code{HCmode}, @code{SCmode}, @code{DCmode}, @code{XCmode}, and
@code{TCmode}.
-@findex MODE_FUNCTION
-@item MODE_FUNCTION
-Algol or Pascal function variables including a static chain.
-(These are not currently implemented).
-
@findex MODE_CC
@item MODE_CC
Modes representing condition code values. These are @code{CCmode} plus
@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
@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
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
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 @code{HOST_WIDE_INT}
-must be sign extended to full width (e.g., with @code{gen_int_mode}).
+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 const_double
@item (const_double:@var{m} @var{i0} @var{i1} @dots{})
-Represents either a floating-point constant of mode @var{m} or an
-integer constant too large to fit into @code{HOST_BITS_PER_WIDE_INT}
-bits but small enough to fit within twice that number of bits (GCC
-does not provide a mechanism to represent even larger constants). In
-the latter case, @var{m} will be @code{VOIDmode}.
+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
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}.
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 square brackets stand for the vector
-containing the constant elements. @var{x0}, @var{x1} and so on are
-the @code{const_int}, @code{const_double} or @code{const_fixed} elements.
+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})}.
-The number of units in a @code{const_vector} is obtained with the macro
-@code{CONST_VECTOR_NUNITS} as in @code{CONST_VECTOR_NUNITS (@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
-Individual elements in a vector constant are accessed with the macro
-@code{CONST_VECTOR_ELT} as in @code{CONST_VECTOR_ELT (@var{v}, @var{n})}
-where @var{v} is the vector constant and @var{n} is the element
-desired.
+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})
@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}, is an expression that
-contains only constants (@code{const_int}, @code{symbol_ref} and
-@code{label_ref} expressions) combined with @code{plus} and
-@code{minus}. However, not all combinations are valid, since the
-assembler cannot do arbitrary arithmetic on relocatable symbols.
-
-@var{m} should be @code{Pmode}.
+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}, usually a
-@code{symbol_ref}. The number of bits is machine-dependent and is
+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 a global memory location.
-
-@var{m} should be @code{Pmode}.
+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
to immediately above the first variable on the stack. Otherwise, it points
to the first variable on the stack.
-@cindex @code{STARTING_FRAME_OFFSET} and virtual registers
+@cindex @code{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{STARTING_FRAME_OFFSET}.
+@code{TARGET_STARTING_FRAME_OFFSET}.
@findex VIRTUAL_STACK_DYNAMIC_REGNUM
@item VIRTUAL_STACK_DYNAMIC_REGNUM
class of @code{subreg} is:
@smallexample
-GET_MODE_SIZE (@var{m1}) > GET_MODE_SIZE (@var{m2})
+paradoxical_subreg_p (@var{m1}, @var{m2})
@end smallexample
Paradoxical @code{subreg}s can be used as both lvalues and rvalues.
taken from @var{reg} while the high-order bits may or may not be
defined.
-The high-order bits of rvalues are in the following circumstances:
+The high-order bits of rvalues are defined in the following circumstances:
@itemize
@item @code{subreg}s of @code{mem}
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}. There are two cases. If @var{m1} is smaller than a word,
-the @code{subreg} refers to the least-significant part (or
-@dfn{lowpart}) of one word of @var{reg}. If @var{m1} is word-sized or
-greater, the @code{subreg} refers to one or more complete words.
-
-When used as an lvalue, @code{subreg} is a word-based accessor.
-Storing to a @code{subreg} modifies all the words of @var{reg} that
-overlap the @code{subreg}, but it leaves the other words of @var{reg}
+@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 word,
-the other bits of the referenced word are usually left in an undefined
+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}
two target macros, @code{WORDS_BIG_ENDIAN} and @code{BYTES_BIG_ENDIAN}:
@itemize
-@item
@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.
-@item
@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.
@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.c and
+integer values, with no particular numerical value. Only real.cc and
the runtime libraries care about @code{FLOAT_WORDS_BIG_ENDIAN}.
Thus,
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 an unknown
-number of undefined bits. For example:
+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 whole of @samp{(reg:SI 0)}, but the exact relationship
-between the @code{PSImode} value and the @code{SImode} value is not
-defined. If we assume @samp{UNITS_PER_WORD <= 4}, then the following
-two @code{subreg}s:
+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 independent 4-byte accesses to the two halves of
-@samp{(reg:DI 0)}. Both @code{subreg}s have an unknown number
-of undefined bits.
+represent accesses to the low 20 bits of the two halves of
+@samp{(reg:DI 0)}.
-If @samp{UNITS_PER_WORD <= 2} then these two @code{subreg}s:
+If @samp{REGMODE_NATURAL_SIZE (PSImode) <= 2} then these two @code{subreg}s:
@smallexample
(subreg:HI (reg:PSI 0) 0)
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. @samp{(reg:PSI 0)}
-has an unknown number of undefined bits, so the assignment:
+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
-does not guarantee that @samp{(subreg:HI (reg:PSI 0) 0)} has the
-value @samp{(reg:HI 4)}.
+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{CANNOT_CHANGE_MODE_CLASS} and subreg semantics
+@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
-CANNOT_CHANGE_MODE_CLASS (@var{m2}, @var{m1}, @var{class})
+TARGET_CAN_CHANGE_MODE_CLASS (@var{m2}, @var{m1}, @var{class})
@end smallexample
-must be true for every class @var{class} that includes @var{reg}.
+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
@code{scratch} is usually present inside a @code{clobber} operation
(@pxref{Side Effects}).
-@findex cc0
-@cindex condition code register
-@item (cc0)
-This refers to the machine's condition code register. It has no
-operands and may not have a machine mode. There are two ways to use it:
-
-@itemize @bullet
-@item
-To stand for a complete set of condition code flags. This is best on
-most machines, where each comparison sets the entire series of flags.
-
-With this technique, @code{(cc0)} may be validly used in only two
-contexts: as the destination of an assignment (in test and compare
-instructions) and in comparison operators comparing against zero
-(@code{const_int} with value zero; that is to say, @code{const0_rtx}).
-
-@item
-To stand for a single flag that is the result of a single condition.
-This is useful on machines that have only a single flag bit, and in
-which comparison instructions must specify the condition to test.
-
-With this technique, @code{(cc0)} may be validly used in only two
-contexts: as the destination of an assignment (in test and compare
-instructions) where the source is a comparison operator, and as the
-first operand of @code{if_then_else} (in a conditional branch).
-@end itemize
-
-@findex cc0_rtx
-There is only one expression object of code @code{cc0}; it is the
-value of the variable @code{cc0_rtx}. Any attempt to create an
-expression of code @code{cc0} will return @code{cc0_rtx}.
-
-Instructions can set the condition code implicitly. On many machines,
-nearly all instructions set the condition code based on the value that
-they compute or store. It is not necessary to record these actions
-explicitly in the RTL because the machine description includes a
-prescription for recognizing the instructions that do so (by means of
-the macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only
-instructions whose sole purpose is to set the condition code, and
-instructions that use the condition code, need mention @code{(cc0)}.
-
On some machines, the condition code register is given a register number
-and a @code{reg} is used instead of @code{(cc0)}. This is usually the
-preferable approach if only a small subset of instructions modify the
-condition code. Other machines store condition codes in general
+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
-(which would not be @code{(cc0)} in this case). For examples, search
-for @samp{addcc} and @samp{andcc} in @file{sparc.md}.
+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
-@item (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.
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 a global memory location.
+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 a @code{Pmode} item minus the number of
+normally the number of bits in mode @var{m} minus the number of
bits set by @code{high}.
-@var{m} should be @code{Pmode}.
-
@findex minus
@findex ss_minus
@findex us_minus
of comparison. The result is computed without overflow, as if with
infinite precision.
-Of course, machines can't really subtract 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, either
-@code{(cc0)} or a register. @xref{Comparisons}.
+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. If @code{(cc0)} is
-used, it is @code{VOIDmode}. Otherwise it is some mode in class
+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{VOIDmode} or @code{CCmode}, the operation returns sufficient
+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
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 that do a combined multiply of @var{x} and @var{y} and then
-adding to@var{z} without doing an intermediate rounding step.
+functions, which compute @samp{@var{x} * @var{y} + @var{z}}
+without doing an intermediate rounding step.
@findex div
@findex ss_div
@item (ffs:@var{m} @var{x})
Represents one plus the index of the least significant 1-bit in
@var{x}, represented as an integer of mode @var{m}. (The value is
-zero if @var{x} is zero.) The mode of @var{x} need not be @var{m};
-depending on the target machine, various mode combinations may be
-valid.
+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})
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}
-will usually be an integer mode and may differ from @var{m}.
+must be @var{m} or @code{VOIDmode}.
@findex clz
@item (clz:@var{m} @var{x})
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} will usually be an integer mode.
+@var{x} must be @var{m} or @code{VOIDmode}.
@findex ctz
@item (ctz:@var{m} @var{x})
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} will usually be an integer mode.
+@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} will usually be an integer mode.
+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} will usually be an integer
-mode.
+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}.
+
+@findex bitreverse
+@item (bitreverse:@var{m} @var{x})
+Represents the value @var{x} with the order of bits 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}.
+
+@findex copysign
+@item (copysign:@var{m} @var{x} @var{y})
+Represents the value @var{x} with the sign of @var{y}.
+Both @var{x} and @var{y} must have floating point machine mode @var{m}.
@end table
@node Comparisons
@code{VOIDmode}.
@cindex condition codes
-There are two ways that comparison operations may be used. The
-comparison operators may be used to compare the condition codes
-@code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such
-a construct actually refers to the result of the preceding instruction
-in which the condition codes were set. The instruction setting the
-condition code must be adjacent to the instruction using the condition
-code; only @code{note} insns may separate them.
-
-Alternatively, a comparison operation may directly compare two data
+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.
-In the example above, if @code{(cc0)} were last set to
-@code{(compare @var{x} @var{y})}, the comparison operation is
-identical to @code{(eq @var{x} @var{y})}. Usually only one style
+Usually only one style
of comparisons is supported on a particular machine, but the combine
-pass will try to merge the operations to produce the @code{eq} shown
+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,
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} can not appear as an lvalue, or part thereof,
+A @code{sign_extract} cannot appear as an lvalue, or part thereof,
in RTL.
@findex zero_extract
@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} 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).
+@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{vec1} @var{vec2})
+@item (vec_concat:@var{m} @var{x1} @var{x2})
Describes a vector concat operation. The result is a concatenation of the
-vectors @var{vec1} and @var{vec2}; its length is the sum of the lengths of
-the two inputs.
+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{vec})
-This operation converts 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, and the number of output parts must be an integer multiple
-of the number of input parts.
-
+@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
register which is meaningful in mode @var{n}, but is not part of
mode @var{m}, is not to be altered. Normally, an assignment to such
a subreg is allowed to have undefined effects on the rest of the
-register when @var{m} is less than a word.
+register when @var{m} is smaller than @samp{REGMODE_NATURAL_SIZE (@var{n})}.
@end table
@node Side Effects
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},
-@code{parallel}, or @code{cc0}.
+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{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} can not
+bit-field is not changed. Note that @code{sign_extract} cannot
appear in @var{lval}.
-If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
-be either a @code{compare} expression or a value that may have any mode.
-The latter case represents a ``test'' instruction. The expression
-@code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to
-@code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}.
-Use the former expression to save space during the compilation.
-
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{mem}; these unusual patterns are used to represent jumps through
branch tables.
-If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of
+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}.
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
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{movmem@var{m}} or
+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
brackets stand for a vector; the operand of @code{parallel} is a
vector of expressions. @var{x0}, @var{x1} and so on are individual
side effect expressions---expressions of code @code{set}, @code{call},
-@code{return}, @code{clobber} or @code{use}.
+@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
instruction this way:
@smallexample
-(parallel [(set (cc0) (reg:SI 34))
+(parallel [(set (reg:CC CC_REG) (reg:SI 34))
(set (pc) (if_then_else
- (eq (cc0) (const_int 0))
+ (eq (reg:CC CC_REG) (const_int 0))
(label_ref @dots{})
(pc)))])
@end smallexample
whose elements are the operands needed to output the resulting
assembler code---often @code{reg}, @code{mem} or constant expressions.
This would not be well-formed RTL at any other stage in compilation,
-but it is ok then because no further optimization remains to be done.
-However, the definition of the macro @code{NOTICE_UPDATE_CC}, if
-any, must deal with such insns if you define any peephole optimizations.
+but it is OK then because no further optimization remains to be done.
@findex cond_exec
@item (cond_exec [@var{cond} @var{expr}])
@findex sequence
@item (sequence [@var{insns} @dots{}])
-Represents a sequence of insns. Each of the @var{insns} that appears
-in the vector is suitable for appearing in the chain of insns, so it
-must be an @code{insn}, @code{jump_insn}, @code{call_insn},
-@code{code_label}, @code{barrier} or @code{note}.
-
-A @code{sequence} RTX is never placed in an actual insn during RTL
-generation. It represents the sequence of insns that result from a
-@code{define_expand} @emph{before} those insns are passed to
-@code{emit_insn} to insert them in the chain of insns. When actually
-inserted, the individual sub-insns are separated out and the
-@code{sequence} is forgotten.
+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 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
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
and the only way to find the labels is to scan the entire body of the
insn.
-Return insns count as jumps, but since they do not refer to any
-labels, their @code{JUMP_LABEL} is @code{NULL_RTX}.
+Return insns count as jumps, but their @code{JUMP_LABEL} is @code{RETURN}
+or @code{SIMPLE_RETURN}.
@findex call_insn
@item call_insn
@code{call_insn} insns have the same extra fields as @code{insn} insns,
accessed in the same way and in addition contain a field
@code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of
-@code{expr_list} expressions) containing @code{use} and @code{clobber}
-expressions that denote hard registers and @code{MEM}s used or
-clobbered by the called function.
+@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 slots in which arguments passed
+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.
+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}).
-@code{CLOBBER}ed registers 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
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.c}.
+@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
@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_BLOCK_NUMBER}
-identifies which @code{CODE_LABEL} or @code{note} of type
-@code{NOTE_INSN_DELETED_LABEL} is associated with the given region.
-
-@findex NOTE_INSN_LOOP_BEG
-@findex NOTE_INSN_LOOP_END
-@item NOTE_INSN_LOOP_BEG
-@itemx NOTE_INSN_LOOP_END
-These types of notes indicate the position of the beginning and end
-of a @code{while} or @code{for} loop. They enable the loop optimizer
-to find loops quickly.
-
-@findex NOTE_INSN_LOOP_CONT
-@item NOTE_INSN_LOOP_CONT
-Appears at the place in a loop that @code{continue} statements jump to.
-
-@findex NOTE_INSN_LOOP_VTOP
-@item NOTE_INSN_LOOP_VTOP
-This note indicates the place in a loop where the exit test begins for
-those loops in which the exit test has been duplicated. This position
-becomes another virtual start of the loop when considering loop
-invariants.
+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
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.
it stands for the value bound to the corresponding
@code{DEBUG_EXPR_DECL}.
-Throughout optimization passes, 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 var
-location 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.
+@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
@table @code
@findex PATTERN
@item PATTERN (@var{i})
-An expression for the side effect performed by this insn. This must be
-one of the following codes: @code{set}, @code{call}, @code{use},
-@code{clobber}, @code{return}, @code{asm_input}, @code{asm_output},
-@code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec},
-@code{unspec_volatile}, @code{parallel}, @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.
+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})
a symbolic representation that locates the pattern in the @file{md}
file as some small positive or negative offset from a named pattern.
-@findex LOG_LINKS
-@item LOG_LINKS (@var{i})
-A list (chain of @code{insn_list} expressions) giving information about
-dependencies between instructions within a basic block. Neither a jump
-nor a label may come between the related insns. These are only used by
-the schedulers and by combine. This is a deprecated data structure.
-Def-use and use-def chains are now preferred.
-
@findex REG_NOTES
@item REG_NOTES (@var{i})
-A list (chain of @code{expr_list} and @code{insn_list} expressions)
-giving miscellaneous information about the insn. It is often
+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{LOG_LINKS} field of an insn is a chain of @code{insn_list}
-expressions. Each of these has two operands: the first is an insn,
-and the second is another @code{insn_list} expression (the next one in
-the chain). The last @code{insn_list} in the chain has a null pointer
-as second operand. The significant thing about the chain is which
-insns appear in it (as first operands of @code{insn_list}
-expressions). Their order is not significant.
-
-This list is originally set up by the flow analysis pass; it is a null
-pointer until then. Flow only adds links for those data dependencies
-which can be used for instruction combination. For each insn, the flow
-analysis pass adds a link to insns which store into registers values
-that are used for the first time in this insn.
-
-The @code{REG_NOTES} field of an insn is a chain similar to the
-@code{LOG_LINKS} field but it includes @code{expr_list} expressions in
-addition to @code{insn_list} expressions. There are several kinds of
-register notes, which are distinguished by the machine mode, which in a
-register note is really understood as being an @code{enum reg_note}.
+The @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.
Register notes are of three classes: They may say something about an
input to an insn, they may say something about an output of an insn, or
-they may create a linkage between two insns. There are also a set
-of values that are only used in @code{LOG_LINKS}.
+they may create a linkage between two insns.
These register notes annotate inputs to an insn:
@findex REG_NONNEG
@item REG_NONNEG
The register @var{op} is known to have a nonnegative value when this
-insn is reached. This is used so that decrement and branch until zero
-instructions, such as the m68k dbra, can be matched.
+insn is reached. This is used by special looping instructions
+that terminate when the register goes negative.
-The @code{REG_NONNEG} note is added to insns only if the machine
-description has a @samp{decrement_and_branch_until_zero} pattern.
+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
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_CROSSING_JUMP
-@item REG_CROSSING_JUMP
-This insn is a branching instruction (either an unconditional jump or
-an indirect jump) which crosses between hot and cold sections, which
-could potentially be very far apart in the executable. The presence
-of this note 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 REG_SETJMP
@item REG_SETJMP
Appears attached to each @code{CALL_INSN} to @code{setjmp} or a
scope of this equivalence differs between the two types of notes. The
value which the insn explicitly copies into the register may look
different from @var{op}, but they will be equal at run time. If the
-output of the single @code{set} is a @code{strict_low_part} expression,
-the note refers to the register that is contained in @code{SUBREG_REG}
-of the @code{subreg} expression.
+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
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_CC_SETTER
-@findex REG_CC_USER
-@item REG_CC_SETTER
-@itemx REG_CC_USER
-On machines that use @code{cc0}, the insns which set and use @code{cc0}
-set and use @code{cc0} are adjacent. However, when branch delay slot
-filling is done, this may no longer be true. In this case a
-@code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to
-point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will
-be placed on the insn using @code{cc0} to point to the insn setting
-@code{cc0}.
-@end table
-
-These values are only used in the @code{LOG_LINKS} field, and indicate
-the type of dependency that each link represents. Links which indicate
-a data dependence (a read after write dependence) do not use any code,
-they simply have mode @code{VOIDmode}, and are printed without any
-descriptive text.
-
@table @code
@findex REG_DEP_TRUE
@item REG_DEP_TRUE
@end table
These notes describe information gathered from gcov profile data. They
-are stored in the @code{REG_NOTES} field of an insn as an
-@code{expr_list}.
+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 value is stored as a
-value between 0 and REG_BR_PROB_BASE; larger values indicate a higher
-probability that the branch will be taken.
+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
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.
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 (attempt, 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 (attempt, 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_ignoring (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_ignoring (attempt, 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 change1 (insn1);
+change1.new_defs = @dots{};
+change1.new_uses = @dots{};
+change1.move_range = @dots{};
+
+rtl_ssa::insn_change change2 (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_ignoring (change1, is_changing)
+ || !rtl_ssa::restrict_movement_ignoring (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_ignoring (attempt, change1, is_changing)
+ || !rtl_ssa::recog_ignoring (attempt, 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
@item
All @code{const_int} expressions with equal values are shared.
-@cindex @code{pc}, RTL sharing
+@cindex @code{const_poly_int}, RTL sharing
@item
-There is only one @code{pc} expression.
+All @code{const_poly_int} expressions with equal modes and values
+are shared.
-@cindex @code{cc0}, RTL sharing
+@cindex @code{pc}, RTL sharing
@item
-There is only one @code{cc0} expression.
+There is only one @code{pc} expression.
@cindex @code{const_double}, RTL sharing
@item
@item
During initial RTL generation, shared structure is freely introduced.
After all the RTL for a function has been generated, all shared
-structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
+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
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.c}. It is not available in the compiler
+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.
projects / thirdparty / gcc.git / blobdiff