\input texinfo  @c -*-texinfo-*-

@settitle Internals of GNU CC

@section RTL Representation

Most of the work of the compiler is done on an intermediate representation
called register tranfer language.  In this language, the instructions
to be output are described, pretty much one by one, in an algebraic form
that describes what the instruction does.

RTL is inspired by Lisp lists.  It has both an internal form, made up
of structures that point at other structures, and a textual form that is
used in the machine description and in printed debugging dumps.  The textual
form uses nested parentheses to indicate the pointers in the internal form.

@subsection RTL Object Types

RTL uses four kinds of objects: expressions, strings, integers and vectors.
Expressions are the most important ones.  An expression is a C structure,
but it is usually referred to with a pointer; a type that is given
the typedef name @code{rtx}.

Expressions are classified by @dfn{expression code}.  The expression
code is a name defined in @file{rtl.def}, which is also a C
enumeration constant.  The possible expression codes and their
meanings are machine-independent.  The code of an rtx can be extracted
with the macro @code{GET_CODE (@var{x})} and altered with
@code{PUT_CODE (@var{x}, @var{newcode})}.

The expression type determines how many operands the expression
contains, and what kinds of objects they are.  In RTL, unlike Lisp,
you cannot tell by looking at an operand what kind of object it is.
Instead, you must know from its context---from the expression code
of the containing expression.  For example, in an expression of code
@code{subreg}, the first operand is to be regarded as an expression
and the second operand as an integer.  In an expression of code
@code{plus}, there are two operands, both of which are to be regarded
as expressions.  In a @code{symbol_ref} expression, there is one operand,
which is to be regarded as a string.

For each expression type @file{rtl.def} specifies the number of contained
objects and their kinds, with four possibilities: @samp{e} for expression
(actually a pointer to an expression), @samp{i} for integer, @samp{s}
for string, and @samp{E} for vector of expressions.  Thus, @code{subreg}
is defined to contain @samp{ei}.

You will also see, used in @file{rtl.def}, the operand-kind characters
@samp{u} and @samp{0}.  @samp{u} is equivalent to @samp{e} except that
it is printed differently in debugging dumps, and @samp{0} means a
slot whose contents do not fit any normal category.  @samp{0}
slots are not printed at all in dumps, and are often used in special
ways by small parts of the compiler.

A vector contains an arbitrary, specified number of pointers to
expressions.  The number of elements in the vector is explicitly
present in the vector.

An integer is simply an @code{int}, and a string is a @code{char *}.
Within rtl code, strings appear only inside @samp{symbol_ref}
expressions, but they appear in other contexts in the rtl expressions
that make up machine descriptions.

@subsection Access to Operands

Operands of expressions are accessed using the macros
@code{XEXP}, @code{XINT} and @code{XSTR}.  Each of these macros
takes two arguments: an expression-pointer and an operand number
(counting from zero).  Thus,

@example
XEXP (x, 2)
@end example

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

@example
XINT (x, 2)
@end example

@noindent
accesses the same operand as an integer.  @code{XSTR}, used in
the same fashion, would access it as a string.

Any operand can be accessed as an integer, as an expression
or as a string.  You must choose the correct method of access
for the kind of value actually stored in the operand.  You would
do this based on the expression code of the containing expression.
That is also how you would know how many operands there are.

For example, if @var{x} is a @samp{subreg} expression, you know that it has
two operands which can be correctly accessed as @code{XEXP (x, 0)} and
@code{XINT (x, 1)}.  If you did @code{XINT (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
(x, 0)}.  @code{XEXP (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 (x, 28)} either, but this will access memory past the
end of the expression with unpredictable results.

Access to operands which are vectors is more complicated.
You can use the macro @code{XVEC} to get the vector-pointer itself,
or the macros @code{XVECEXP} and @code{XVECLEN} to access the
elements and length of a vector.

@table @code
@item XVEC (@var{exp}, @var{idx})
Access the vector-pointer which is operand number @var{idx} in @var{exp}.

@item XVECLEN (@var{exp}, @var{idx})
Access the length (number of elements) in the vector which is
in operand number @var{idx} in @var{exp}.  This value is an @code{int}.

@item XVECLEN (@var{exp}, @var{idx}, @var{eltnum})
Access element number @var{eltnum} in the vector which is
in operand number @var{idx} in @var{exp}.  This value is an @code{rtx}.

It is up to you to make sure that @var{eltnum} is not negative
and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
@end table

All the macros defined in this section expand into lvalues and therefore
can be used to assign the operands, lengths and vector elements as well as
to access them.

@subsection Machine Modes

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}.  Each rtl expression has room for a machine mode
and so do certain kinds of tree expressions (declarations and types, to be
precise).

In debugging dumps and machine descriptions, the machine mode of an RTL
expression is written after the expression code with a colon to separate them.
The letters @samp{mode} which appear at the end of each machine mode name
are omitted.  For example, @code{(reg:SI 38)} is a @samp{reg} expression
with machine mode @code{SImode}.  If the mode is @code{VOIDmode}, it is
not written at all.

Here is a table of machine modes.

@table @code
@item QImode
``Quarter-Integer'' mode represents a single byte treated as an integer.

@item HImode
``Half-Integer'' mode represents a two-byte integer.

@item SImode
``Single Integer'' mode represents a four-byte integer.

@item DImode
``Double Integer'' mode represents an eight-byte integer.

@item TImode
``Tetra Integer'' (?) mode represents a sixteen-byte integer.

@item SFmode
``Single Floating'' mode represents a single-precision (four byte) floating
point number.

@item DFmode
``Double Floating'' mode represents a double-precision (eight byte) floating
point number.

@item TFmode
``Tetra Floating'' mode represents a quadruple-precision (sixteen byte)
floating point number.

@item BLKmode
``Block'' mode represents values that are aggregates to which none of
the other modes apply.  In rtl, only memory references can have this mode,
and only if they appear in string-move or vector instructions.  On machines
which have no such instructions, @code{BLKmode} will not appear in RTL.

@item VOIDmode
Void mode means the absence of a mode or an unspecified mode.
For example, RTL expresslons of code @samp{const_int} have mode
@code{VOIDmode} because they can be taken to have whatever mode the context
requires.  In debugging dumps of RTL, @code{VOIDmode} is expressed by
the absence of any mode.

@item EPmode
``Entry Pointer'' mode is intended to be used for function variables in
Pascal and other block structured languages.  Such values contain
both a function address and a static chain pointer for access to
automatic variables of outer levels.  This mode is only partially
implemented since C does not use it.

@item CSImode@r{, @dots{}}
``Complex Single Integer'' mode stands for a complex number represented
as a pair of @code{SImode} integers.  Any of the integer and floating modes
may have @samp{C} prefixed to its name to obtain a complex number mode.
For example, there are @code{CQImode}, @code{CSFmode}, and @code{CDFmode}.
Since C does not support complex numbers, these machine modes are only
partially implemented.

@item BImode
This is the machine mode of a bit-field in a structure.  It is used
only in the syntax tree, never in RTL, and in the syntax tree it appears
only in declaration nodes.  In C, it appears only in @code{FIELD_DECL}
nodes for structure fields defined with a bit size.
@end table

The machine description defines @code{Pmode} as a C macro which expands
into the machine mode used for addresses.  Normally this is @code{SImode}.

The only modes which a machine description @i{must} support are
@code{QImode}, @code{SImode}, @code{SFmode} and @code{DFmode}.  The
compiler will attempt to use @code{DImode} for two-word structures and
unions, but it would not be hard to program it to avoid this.  Likewise,
you can arrange for the C type @code{short int} to avoid using
@code{HImode}.  In the long term it would be desirable to make the set of
available machine modes machine-dependent and eliminate all assumptions
about specific machine modes or their uses from the machine-independent
code of the compiler.

Here are some C macros that relate to machine modes:

@table @code
@item GET_MODE (@var{x})
Returns the machine mode of the rtx @var{x}.

@item PUT_MODE (@var{x}, @var{newmode})
Alters the machine mode of the rtx @var{x} to be @var{newmode}.

@item GET_MODE_SIZE (@var{m})
Returns the size in bytes of a datum of mode @var{m}.

@item GET_MODE_BITSIZE (@var{m})
Returns the size in bits of a datum of mode @var{m}.
@end table

@subsection Constant Expression Types

The simplest RTL expressions are those that represent constant values.

@table @code
@item (const_int @var{i})
This type of expression represents the integer value @var{i}.  @var{i}
is customarily accessed with the macro @code{INTVAL} as in
@code{INTVAL (exp)}, which is equivalent to @code{XINT (exp, 0)}.

There is only one expression object for the integer value zero;
it is the value of the variable @code{const0_rtx}.  Likewise, the
only expression for integer value one is found in @code{const1_rtx}.
Any attempt to create an expression of code @code{const_int} and
value zero or one will return @code{const0_rtx} or @code{const1_rtx}
as appropriate.

@item (const_double:@var{m} @var{i0} @var{i1})
Represents a floating point constant value of mode @var{m}.  The two integers
@var{i0} and @var{i1} together contain the bits of a @code{double} value.
To convert them to a @code{double}, do

@example
union { double d; int i[2];} u;
u.i[0] = XINT (x, 0);
u.i[1] = XINT (x, 1);
@end example

@noindent
and then refer to @code{u.d}.  The value of the constant is
represented as a double in this fashion even if the value represented
is single-precision.

@item (symbol_ref @var{symbol})
Represents the value of an assembler label for data.  @var{symbol} is
a string that describes the name of the assembler label.  If it starts
with a @samp{*}, the label is the rest of @var{symbol} not including
the @samp{*}.  Otherwise, the label is @var{symbol}, prefixed with
@samp{_}.

@item label_ref
Represents the value of an assembler label for code.  It contains one
operand, an expression, which must be a @code{code_label} that appears in
the instruction sequence to identify the place where the label should go.

The reason for using a distinct expression type for code label references
is so that jump optimization can understand them.

@item (const @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 (@samp{const_int}, @samp{symbol_ref} and
@samp{label_ref} expressions) combined with @samp{plus} and
@samp{minus}.  However, not all combinations are valid, since the
assembler cannot do arbitrary arithmetic on relocatable symbols.
@end table

@subsection Registers and Memory

Here are the RTL expression types for describing access to machine
registers and to main memory.

@table @code
@item (reg:@var{m} @var{n})
For small values of the integer @var{n} (less than
@code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
register number @var{n}: a @dfn{hard register}.  For larger values of
@var{n}, it stands for a temporary value or @dfn{pseudo register}.
The compiler's strategy is to generate code assuming an unlimited
number of such pseudo registers, and later convert them into hard
registers or into memory references.

The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
description, since the number of hard registers on the machine is an
invariant characteristic of the machine.  Note, however, that not
all of the machine registers must be general registers.  All the
machine registers that can be used for storage of data are given
hard register numbers, even those that can be used only in certain
instructions or can hold only certain types of data.

Each pseudo register number used in a function's rtl code is
represented by a unique @samp{reg} expression.

@var{m} is the machine mode of the reference.  It is necessary because
machines can generally refer to each register in more than one mode.
For example, a register may contain a full word but there may be
instructions to refer to it as a half word or as a single byte, as
well as instructions to refer to it as a floating point number of
various precisions.

Even for a register that the machine can access in only one mode,
the mode must always be specified.

A hard register may be accessed in various modes throughout one
function, but each pseudo register is given a natural mode
and is accessed only in that mode.  When it is necessary to describe
an access to a pseudo register using a nonnatural mode, a @samp{subreg}
expression is used.

A @samp{reg} expression with a machine mode that specifies more than
one word of data may actually stand for several consecutive registers.

@item (subreg:@var{m} @var{reg} @var{wordnum})
@samp{subreg} expressions are used to refer to a register in a machine
mode other than its natural one, or to refer to one register of
a multi-word @samp{reg} that actually refers to several registers.

Each pseudo-register has a natural mode.  If it is necessary to
operate on it in a different mode---for example, to perform a fullword
move instruction on a pseudo-register that contains a single byte---
the pseudo-register must be enclosed in a @samp{subreg}.  In such
a case, @var{wordnum} is zero.

The other use of @samp{subreg} is to extract the individual registers
of a multi-register value.  Machine modes such as @code{DImode} and
@code{EPmode} indicate values longer than a word, values which usually
require two consecutive registers.  To access one of the registers,
use a @samp{subreg} with mode @code{SImode} and a @var{wordnum} that
says which register.

The compilation parameter @code{WORDS_BIG_ENDIAN}, if defined, says
that word number zero is the most significant part; otherwise, it is
the least significant part.

Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
using a @samp{subreg}.  On some machines the most significant part of a
@code{DFmode} value does not have the same format as a single-precision
floating value.

@item (cc0)
This refers to the machine's condition code register.  It has no
operands and may not have a machine mode.  It 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}.

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

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

There is only one expression object of code @code{pc}; it is the value of
the variable @code{pc_rtx}.  Any attempt to create an expression of code
@code{pc} will return @code{pc_rtx}.

@item (mem:@var{m} @var{addr})
This rtx represents a reference to main memory at an address
represented by the expression @var{addr}.  @var{m} specifies how
large a unit of memory is accessed.
@end table

@subsection RTL Expressions for Arithmetic

@table @code
@item (plus:@var{m} @var{x} @var{y})
Represents the sum of the values represented by @var{x} and @var{y}
carried out in machine mode @var{m}.  This is valid only if
@var{x} and @var{y} both are valid for mode @var{m}.

@item (minus:@var{m} @var{x} @var{y})
Like @samp{plus} but represents subtraction.

@item (minus @var{x} @var{y})
Represents the result of subtracting @var{y} from @var{x}
for purposes of comparison.  The absence of a machine mode
in the @samp{minus} expression indicates that the result is
computed without overflow, as if with infinite precision.

Of course, machines can't really subtract with infinite precision.
However, they can pretend to do so when only the sign of the
result will be used, which is the case when the result is stored
in @code{(cc0)}.  And that is the only was this kind of expression
may validly be used: as a value to be stored in the condition codes.

@item (neg:@var{m} @var{x})
Represents the negation (subtraction from zero) of the value
represented by @var{x}, carried out in mode @var{m}.  @var{x} must be
valid for mode @var{m}.

@item (mult:@var{m} @var{x} @var{y})
Represents the signed product of the values represented by @var{x} and
@var{y} carried out in machine mode @var{m}.  If
@var{x} and @var{y} are both valid for mode @var{m}, this is ordinary
size-preserving multiplication.  Alteratively, both @var{x} and @var{y}
may be valid for a different, narrower mode.  This represents the
kind of multiplication that generates a product wider than the operands.
Widening multiplication and same-size multiplication are completely
distinct and supported by different machine instructions; machines may
support one but not the other.

@samp{mult} may be used for floating point division as well.
Then @var{m} is a floating point machine mode.

@item (umult:@var{m} @var{x} @var{y})
Like @samp{mult} but represents unsigned multiplication.  It may be
used in both same-size and widening forms, like @samp{mult}.
@samp{umult} is used only for fixed-point division.

@item (div:@var{m} @var{x} @var{y})
Represents the quotient in signed division of @var{x} by @var{y},
carried out in machine mode @var{m}.  If @var{m} is a floating-point
mode, it represents the exact quotient; otherwise, the integerized
quotient.  If @var{x} and @var{y} are both valid for mode @var{m},
this is ordinary size-preserving division.  Some machines have
division instructions in which the operands and quotient widths are
not all the same; such instructions are represented by @samp{div}
expressions in which the machine modes are not all the same.

@item (udiv:@var{m} @var{x} @var{y})
Like @samp{div} but represents unsigned division.

@item (mod:@var{m} @var{x} @var{y})
@itemx (umod:@var{m} @var{x} @var{y})
Like @samp{div} and @samp{udiv} but represent the remainder instead of
the quotient.

@item (not:@var{m} @var{x})
Represents the bitwise complement of the value represented by @var{x},
carried out in mode @var{m}, which must be a fixed-point machine mode.
@var{x} must be valid for mode @var{m}, which must be a fixed-point mode.

@item (and:@var{m} @var{x} @var{y})
Represents the bitwise logical-and of the values represented by
@var{x} and @var{y}, carried out in machine mode @var{m}.  This is
valid only if @var{x} and @var{y} both are valid for mode @var{m},
which must be a fixed-point mode.

@item (ior:@var{m} @var{x} @var{y})
Represents the bitwise inclusive-or of the values represented by
@var{x} and @var{y}, carried out in machine mode @var{m}.  This is
valid only if @var{x} and @var{y} both are valid for mode @var{m},
which must be a fixed-point mode.

@item (xor:@var{m} @var{x} @var{y})
Represents the bitwise exclusive-or of the values represented by
@var{x} and @var{y}, carried out in machine mode @var{m}.  This is
valid only if @var{x} and @var{y} both are valid for mode @var{m},
which must be a fixed-point mode.

@item (lshift:@var{m} @var{x} @var{c})
Represents the result of logically shifting @var{x} left by @var{c}
places.  @var{x} must be valid for the mode @var{m}, a fixed-point
machine mode.  @var{c} must be valid for a fixed-point mode;
which mode is determined by the mode called for in the machine
description entry for the left-shift instruction.

On some machines, negative values of @var{c} may be meaningful; this
is why logical left shift an arithmetic left shift are distinguished.
For example, Vaxes have no right-shift instructions, and right shifts
are represented as left-shift instructions whose counts happen
to be negative constants or else computed (in a previous instruction)
by negation.

@item (ashift:@var{m} @var{x} @var{c})
Like @samp{lshift} but for arithmetic left shift.

@item (lshiftrt:@var{m} @var{x} @var{c})
@itemx (ashiftrt:@var{m} @var{x} @var{c})
Like @samp{lshift} and @samp{ashift} but for right shift.

@item (rotate:@var{m} @var{x} @var{c})
@itemx (rotatert:@var{m} @var{x} @var{c})
Similar but represent left and right rotate.

@item (abs:@var{m} @var{x})
Represents the absolute value of @var{x}, computed in mode @var{m}.
@var{x} must be valid for @var{m}.

@item (sqrt:@var{m} @var{x})
Represents the square root of @var{x}, computed in mode @var{m}.
@var{x} must be valid for @var{m}.  Most often @var{m} will be
a floating point mode.
@end table

@subsection Comparison Operations

Comparison operators test a relation on two operands and are considered to
represent the value 1 if the relation holds, or zero if it does not.  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.

Inequality comparisons come in two flavors, signed and unsigned.  Thus,
there are distinct expression codes @samp{GT} and @samp{GTU} for signed and
unsigned greater-than.  These can produce different results for the same
pair of integer values: for example, 1 is signed greater-than -1 but not
unsigned greater-than, because -1 when regarded as unsigned is actually
0xffffffff which is greater than 1.

The signed comparisons are also used for floating point values.  Floating
point comparisons are distinguished by the machine modes of the operands.

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 above
example stands for 1 if the condition codes were set to say
``zero'' or ``equal'', 0 otherwise.  Although the same comparison
operators are used for this as may be used in other contexts
on actual data, no confusion can result since the machine description
would never allow both kinds of uses in the same context.

@table @code
@item (eq @var{x} @var{y})
1 if the values represented by @var{x} and @var{y} are equal,
otherwise 0.

@item (ne @var{x} @var{y})
1 if the values represented by @var{x} and @var{y} are not equal,
otherwise 0.

@item (gt @var{x} @var{y})
1 if the @var{x} is greater than @var{y}.  If they are fixed-point,
the comparison is done in a signed sense.

@item (gtu @var{x} @var{y})
Like @samp{gt} but does unsigned comparison, on fixed-point numbers only.

@item (lt @var{x} @var{y})
@item (ltu @var{x} @var{y})
Like @samp{gt} and @samp{gtu} but test for ``less than''.

@item (ge @var{x} @var{y})
@item (geu @var{x} @var{y})
Like @samp{gt} and @samp{gtu} but test for ``greater than or equal''.

@item (le @var{x} @var{y})
@item (leu @var{x} @var{y})
Like @samp{gt} and @samp{gtu} but test for ``less than or equal''.

@item (if_then_else @var{cond} @var{then} @var{else})
This is not a comparison operation but is listed here because it is
always used in conjunction with a comparison operation.  To be
precise, @var{cond} is a comparison expression.  This expression
represents a choice, according to @var{cond}, between the value
represented by @var{then} and the one represented by @var{else}.

On most machines, @samp{if_then_else} expressions are valid only
to express conditional jumps.
@end table

@subsection Bit-fields

Special expression codes exist to represent bit-field instructions.
These types of expressions are lvalues in rtl; they may appear
on the left side of a assignment, indicating insertion of a value
into the specified bit field.

@table @code
@item (sign_extract:SI @var{loc} @var{size} @var{pos})
This represents a reference to a sign-extended bit-field contained or
starting in @var{loc} (a memory or register reference).  The bit field
is @var{size} bits wide and starts at bit @var{pos}.  The compilation
switch @code{BITS_BIG_ENDIAN} says which end of the memory unit
@var{pos} counts from.

Which machine modes are valid for @var{loc} depends on the machine,
but typically @var{loc} should be a single byte when in memory
or a full word in a register.

@item (zero_extract:SI @var{loc} @var{pos} @var{size})
Like @samp{sign_extract} but refers to an unsigned or zero-extended
bit field.  The same sequence of bits are extracted, but they
are filled to an entire word with zeros instead of by sign-extension.
@end table

@subsection Conversions

All conversions between machine modes must be represented by
explicit conversion operations.  For example, an expression
which the sum of a byte and a full word cannot be written as
@code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @samp{plus}
operation requires two operands of the same machine mode.
Therefore, the byte-sized operand is enclosed in a conversion
operation, as in

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

The conversion operation is not a mere placeholder, because there
may be more than one way of converting from a given starting mode
to the desired final mode.  The conversion operation code says how
to do it.

@table @code
@item (sign_extend:@var{m} @var{x})
Represents the result of sign-extending the value @var{x}
to machine mode @var{m}.  @var{m} must be a fixed-point mode
and @var{x} a fixed-point value of a mode narrower than @var{m}.

@item (zero_extend:@var{m} @var{x})
Represents the result of zero-extending the value @var{x}
to machine mode @var{m}.  @var{m} must be a fixed-point mode
and @var{x} a fixed-point value of a mode narrower than @var{m}.

@item (float_extend:@var{m} @var{x})
Represents the result of extending the value @var{x}
to machine mode @var{m}.  @var{m} must be a floating point mode
and @var{x} a floating point value of a mode narrower than @var{m}.

@item (truncate:@var{m} @var{x})
Represents the result of truncating the value @var{x}
to machine mode @var{m}.  @var{m} must be a fixed-point mode
and @var{x} a fixed-point value of a mode wider than @var{m}.

@item (float_truncate:@var{m} @var{x})
Represents the result of truncating the value @var{x}
to machine mode @var{m}.  @var{m} must be a floating point mode
and @var{x} a floating point value of a mode wider than @var{m}.

@item (float:@var{m} @var{x})
Represents the result of converting fixed point value @var{x}
to floating point mode @var{m}.

@item (fix:@var{m} @var{x})
Represents the result of converting floating point value @var{x}
to fixed point mode @var{m}.  How rounding is done is not specified.

@end table

@subsection Declarations

Declaration expression codes do not represent arithmetic operations
but rather state assertions about their operands.

@table @code
@item (volatile:@var{m} @var{x})
Represents the same value @var{x} does, but makes the assertion
that it should be treated as a volatile value.  This forbids
coalescing multiple accesses or deleting them even if it would
appear to have no effect on the program.  @var{x} must be a @samp{mem}
expression with mode @var{m}.

@item (unchanging:@var{m} @var{x})
Represents the same value @var{x} does, but makes the assertion
that its value is effectively constant during the execution
of the current function.  This permits references to @var{x}
to be moved freely within the function.  @var{x} must be a @samp{reg}
expression with mode @var{m}.

@item (strict_low_part @var{x})
???
@end table

@subsection Side Effect Expressions

The expression codes described so far represent values, not actions.
But machine instructions never produce values; they are meaningful
only for their side effects on the state of the machine.  Special
expression codes are used to represent side effects.

The body of an instruction is always one of these side effect codes;
the codes described above, which represent values, appear only as
the operands of these.

@table @code
@item (set @var{lval} @var{x})
Represents the action of storing the value of @var{x} into
the place represented by @var{lval}.  @var{lval}
must be an expression representing a place that can be stored in:
@samp{reg}, @samp{mem}, @samp{pc} or @samp{cc0}.

If @var{lval} is a @samp{reg} or @samp{mem}, it has a machine mode;
then @var{x} must be valid for that mode.

If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x}
may have any mode.  This represents a ``test'' or ``compare''
instruction.

If @var{lval} is @code{(pc)}, we have a jump instruction, and the
possibilities for @var{x} are very limited.  It may be a
@samp{label_ref} expression (unconditional jump).  It may be an
@samp{if_then_else} (conditional jump), in which case either the
second or the third operand must be @code{(pc)} (for the case which
does not jump) and the other of the two must be a @samp{label_ref}
(for the case which does jump).  @var{x} may also be a @samp{mem}
or @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @samp{reg}
or a @samp{mem}; these unusual patterns are used to represent
jumps through branch tables.

@item (return)
Represents a return from the current function, on machines where
this can be done with one instruction, such as Vaxen.  On machines
where a multi-instruction ``epilogue'' must be executed in order
to return from the function, returning is done by jumping to a
label which precedes the epilogue, and the @samp{return} expression
code is never used.

@item (call @var{function} @var{nargs})
Represents a function call.  @var{function} is a @samp{mem} expression
whose address is the address of the function to be called.  @var{nargs}
is an expression representing the number of words of argument.

Each machine has a standard machine mode which @var{function} must
have.  The machine descripion defines macro @code{FUNCTION_MODE} to
expand into the requisite mode name.  The purpose of this mode is to
specify what kind of addressing is allowed, on machines where the
allowed kinds of addressing depend on the machine mode being
addressed.

@item (clobber @var{x})
Represents the storing or possible storing of an unpredictable,
undescribed value into @var{x}, which must be a @samp{reg} or
@samp{mem} expression.

One place this is used is in string instructions that store standard
values into particular hard registers.  It may not be worth the
trouble to describe the values that are stored, but it is essential
to inform the compiler that the registers will be altered, lest it
attempt to keep data in them across the string instruction.

@var{x} may also be null---a null C pointer, no expression at all.
Such a @code{(clobber (null))} expression means that all memory
locations must be presumed clobbered.

Note that the machine description classifies certain hard registers as
``call-clobbered''.  All function call instructions are assumed by
default to clobber these registers, so there is no need to use
@samp{clobber} expressions to indicate this fact.  Also, each function
call is assumed to have the potential to alter any memory location.

@item (use @var{x})
Represents the use of the value of @var{x}.  It indicates that
the value in @var{x} at this point in the program is needed,
even though it may not be apparent whythis is so.  Therefore, the
compiler will not attempt to delete instructions whose only
effect is to store a value in @var{x}.  @var{x} must be a @samp{reg}
expression.

@item (parallel [@var{x0} @var{x1} @dots{}])
Represents several side effects performed in parallel.  The square
brackets stand for a vector; the operand of @samp{parallel} is a
vector of expressions.  @var{x0}, @var{x1} and so on are individual
side effects---expressions of code @samp{set}, @samp{call},
@samp{return}, @samp{clobber} or @samp{use}.

``In parallel'' means that first all the values used in
the individual side-effects are computed, and second all the actual
side-effects are performed.  For example,

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

@noindent
says unambiguously that the values of hard register 1 and the memory
location addressed by it are interchanged.  In both places where
@code{(reg:SI 1)} appears as a memory address it refers to the value
in register 1 @i{before} the execution of the instruction.
@end table

Three expression codes appear in place of a side effect, as the body
of an insn, though strictly speaking they do not describe side effects
as such:

@table @code
@item (asm_input @var{s})
Represents literal assembler code as described by the string @var{s}.

@item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
Represents a table of jump addresses.  @var{lr0} etc. are
@samp{label_ref} expressions.  The mode @var{m} specifies how much
space is given to each address; normally @var{m} would be
@code{Pmode}.

@item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}])
Represents a table of jump addresses expressed as offsets from
@var{base}.  @var{lr0} etc. are @samp{label_ref} expressions and so is
@var{base}.  The mode @var{m} specifies how much space is given to
each address-difference.
@end table

@subsection Embedded Side-Effects on Addresses

Four special side-effect expression codes appear as memory addresses.

@table @code
@item (pre_decrement:@var{m} @var{x})
Represents the side effect of decrementing @var{x} by a standard
amount and represents also the value that @var{x} has after being
decremented.  @var{x} must be a @samp{reg} or @samp{mem}, but most
machines allow only a @samp{reg}.  @var{m} must be the machine mode
for pointers on the machine in use.  The amount @var{x} is decrement
by is the length in bytes of the machine mode of the containing memory
reference of which this expression serves as the address.  Here is an
example of its use:

@example
(mem:DF (pre_decrement:SI (reg:SI 39)))
@end example

@noindent
This says to decrement pseudo register 39 by the length of a DFmode
value and use the result to address a DFmode value.

@item (pre_increment:@var{m} @var{x})
Similar, but specifies incrementing @var{x} instead of decrementing it.

@item (post_decrement:@var{m} @var{x})
Represents the same side effect as @samp{pre_decrement} but a different
value.  The value represented here is the value @var{x} has @i{before}
being decremented.

@item (post_increment:@var{m} @var{x})
Similar, but specifies incrementing @var{x} instead of decrementing it.
@end table

These embedded side effect expressions must be used with care.  Instruction
patterns may not use them.  Until the @samp{flow} pass of the compiler,
they may occur only to represent pushes onto the stack.  The @samp{flow}
pass finds cases where registers are incremented or decremented in one
instruction and used as an address shortly before or after; these cases are
then transformed to use pre- or post-increment or -decrement.

An instruction that can be represented with an embedded side effect
could also be represented using @samp{parallel} containing an additional
@samp{set} to describe how the address register is altered.  This is not
done because machines that allow these operations at all typically
allow them wherever a memory address is called for.  Describing them as
additional parallel stores would require doubling the number of entries
in the machine description.

@subsection Instructions

The RTL representation of the code for a function is a doubly-linked
chain of objects called @dfn{insns}.  Insns are expressions with
special codes that are used for no other purpose.  Some insns are
actual instructions; others represent dispatch tables for @code{switch}
statements; others represent labels to jump to or various sorts of
declaratory information.

In addition to its own specific data, each insn must have a unique id number
that distinguishes it from all other insns in the current function, and
chain pointers to the preceding and following insns.  These three fields
occupy the same position in every insn, independent of the expression code
of the insn.  They could be accessed with @code{XEXP} and @code{XINT},
but instead three special macros are always used:

@table @code
@item INSN_UID (@var{i})
Accesses the unique id of insn @var{i}.

@item PREV_INSN (@var{i})
Accesses the chain pointer to the insn preceding @var{i}.
If @var{i} is the first insn, this is a null pointer.

@item NEXT_INSN (@var{i})
Accesses the chain pointer to the insn following @var{i}.
If @var{i} is the last insn, this is a null pointer.
@end table

The @code{NEXT_INSN} and @code{PREV_INSN} pointers must always
correspond: if @var{i} is not the first insn,

@example
NEXT_INSN (PREV_INSN (@var{i})) == @var{i}
@end example

@noindent
is always true.

Every insn has one of the following six expression codes:

@table @code
@item insn
The expression code @samp{insn} is used for instructions that do not jump
and do not do function calls.  Insns with code @samp{insn} have four
additional fields beyond the three mandatory ones listed above.
These four are described in a table below.

@item jump_insn
The expression code @samp{jump_insn} is used for instructions that may jump
(or, more generally, may contain @samp{label_ref} expressions).
@samp{jump_insn} insns have the same extra fields as @samp{insn} insns,
accessed in the same way.

@item call_insn
The expression code @samp{call_insn} is used for instructions that may do
function calls.  It is important to distinguish these instructions because
they imply that certain registers and memory locations may be altered
unpredictably.

@samp{call_insn} insns have the same extra fields as @samp{insn} insns,
accessed in the same way.

@item code_label
A @samp{code_label} insn represents a label that a jump insn can jump to.
It contains one special field of data in addition to the three standard ones.
It is used to hold the @dfn{label number}, a number that identifies this
label uniquely among all the labels in the compilation (not just in the
current function).  Ultimately, the label is represented in the assembler
output as an assembler label @samp{L@var{n}} where @var{n} is the label number.

@item barrier
Barriers are placed in the instruction stream after unconditional
jump instructions to indicate that the jumps are unconditional.
They contain no information beyond the three standard fields.

@item note
@samp{note} insns are used to represent additional debugging and
declaratory information.  They contain two nonstandard fields,
an integer accessed with the macro @code{NOTE_LINE_NUMBER} and
a string accessed with @code{NOTE_SOURCE_FILE}.

If @code{NOTE_LINE_NUMBER} is positive, the note represents the
position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
that the line came from.  These notes control generation of line
number data in the assembler output.

Otherwise, @code{NOTE_LINE_NUMBER} must have one of the following
values (and @code{NOTE_SOURCE_FILE} must contain a null pointer):

@table @code
@item NOTE_INSN_DELETED
Such a note is completely ignorable.  Some passes of the compiler
delete insns by altering them into notes of this kind.

@item NOTE_INSN_BLOCK_BEG
@itemx NOTE_INSN_BLOCK_END
These types of notes indicate the position of the beginning and end
of a level of scoping of variable names.  They control the output
of debugging information.

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

Here is a table of the extra fields of @samp{insn}, @samp{jump_insn}
and @samp{call_insn} insns:

@table @code
@item PATTERN (@var{i})
An expression for the side effect performed by this insn.

@item REG_NOTES (@var{i})
A list (chain of @samp{expr_list} expressions) giving information
about the usage of registers in this insn.  This list is set up by the
@code{flow} pass; it is a null pointer until then.

@item LOG_LINKS (@var{i})
A list (chain of @samp{insn_list} expressions) of previous ``related''
insns: insns which store into registers values that are used for the
first time in this insn.  (An additional constraint is that neither a
jump nor a label may come between the related insns).  This list is
set up by the @code{flow} pass; it is a null pointer until then.

@item INSN_CODE (@var{i})
An integer that says which pattern in the machine description
matches this insn, or -1 if the matching has not yet been attempted.

Such matching is never attempted and this field is not used
on an insn whose pattern consists of a single @samp{use}, @samp{clobber},
@samp{asm}, @samp{addr_vec} or @samp{addr_diff_vec} expression.
@end table

The @code{LOG_LINKS} field of an insn is a chain of @samp{insn_list}
expressions.  Each of these has two operands: the first is an insn,
and the second is another @samp{insn_list} expression (the next one
in the chain).  The last @samp{insn_list} in the chain has a null
pointer as second operand.  The significant thing about the chain
is which insns apepar in it (as first operands of @samp{insn_list}
expressions).  Their order is not significant.

The @code{REG_NOTES} field of an insn is a similar chain but
of @samp{expr_list} expressions instead of @samp{insn_list}.
The first operand is a @samp{reg} rtx.  Its presence in the list
can have three possible meanings, distinguished by a value
that is stored in the machine-mode field of the @samp{expr_list}
because that is a conveniently available space, but that is
not really a machine mode.  These values belong to the C type
@code{enum reg_note} and there are three of them:

@table @code
@item REG_DEAD
The @samp{reg} listed dies in this insn; that is to say, altering
the value immediately after this insn would not affect the future
behavior of the program.

@item REG_INC
The @samp{reg} listed is incremented (or decremented; at this level
there is no distinction) by an embedded side effect inside this insn.

@item REG_CONST
The @samp{reg} listed has a value that never changes.
@end table

(The only difference between the expression codes @samp{insn_list} and
@samp{expr_list} is that the first operand of an @samp{insn_list} is
assumed to be an insn and is printed in debugging dumps as the insn's
unique id; the first operand of an @samp{expr_list} is printed in the
ordinary way as an expression.)

@section Machine Descriptions

A machine description has two parts: a file of instruction patterns
(@file{md} file) and a C header file of macro definitions.

Each instruction pattern contains an incomplete RTL expression,
with pieces to be filled in later, operand constraints that
restrict how the pieces can be filled in, and an output pattern
or C code to generate the assembler output, all wrapped up in
a @samp{define_insn} expression.  The @samp{define_insn}
expression contains four operands:

@enumerate
@item
An optional name.  The presence of a name indicate that this instruction
pattern can perform a certain standard job for the RTL-generation
pass of the compiler.  This pass knows certain names and will use
the instruction patterns with those names, if the names are defined
in the machine description.

The absence of a name is indicated by writing an empty string
where the name should go.  Nameless instruction patterns are never
used for generating RTL code, but they may permit several simpler insns
to be combined later on.

Names that are not thus known and used in RTL-generation have no
effect; they are equivalent to no name at all.

@item
The recognition template.  This is a vector of incomplete RTL
expressions which show what the instruction should look like.  It is
incomplete because it may contain @samp{match_operand} and
@samp{match_dup} expressions that stand for operands of the
instruction.

If the vector has only one element, that element is what the
instruction should look like.  If the vector has multiple elements,
then the instruction looks like a @samp{parallel} expression
containing that many elements as described.

@item
A condition.  This is a string which contains a C expression that is
the final test to decide whether an insn body matches this pattern.

For a named pattern, the condition (if present) may not depend on
the data in the insn being matched, but only the target-machine-type
flags.  The compiler needs to test these conditions during
initialization in order to learn exactly which named instructions are
available in a particular run.

For nameless patterns, the condition is applied only when matching an
individual insn, and only after the insn has matched the pattern's
recognition template.  The insn's operands may be found in the vector
@code{operands}.

@item
A string that says how to output matching insns as assembler code.  In
the simpler case, the string is an output template, much like a
@code{printf} control string.  @samp{%} in the string specifies where
to insert the operands of the instruction; the @samp{%} is followed by
a single-digit operand number.

@samp{%c@var{digit}} can be used to subtitute an operand that is a
constant value without the syntax that normally indicates an immediate
operand.

@samp{%a@var{digit}} can be used to substitute an operand as if it
were a memory reference, with the actual operand treated as the address.
This may be useful when outputting a
``load address'' instruction, because often the assembler syntax for
such an instruction requires you to write the operand as if it were
a memory reference.

The template may generate multiple assembler instructions.
Write the text for the instructions, with @samp{\;} between them.

If the output control string starts with a @samp{*}, then it is not an
output template but rather a piece of C program that should compute a
template.  It should execute a @code{return} statement to return the
template-string you want.  Most such templates use C string literals,
which require doublequote characters to delimit them.  To include
these doublequote characters in the string, prefix each one with
@samp{\}.

The operands may be found in the array @code{operands}, whose C
data type is @code{rtx []}.

It is possible to output an assembler instruction and then go on to
output or compute more of them, using the subroutine
@code{output_asm_insn}.  This receives two arguments: a
template-string and a vector of operands.  The vector may be
@code{operands}, or it may be another array of @code{rtx} that you
declare locally and initialize yourself.
@end enumerate

The recognition template is used also, for named patterns, for
constructing insns.  Construction involves substituting specified
operands into a copy of the template.  Matching involves determining
the values that serve as the operands in the insn being matched.  Both
of these activities are controlled by two special expression types
that direct matching and substitution of the operands.

@table @code
@item (match_operand:@var{m} @var{n} @var{testfn} @var{constraint})
This expression is a placeholder for operand number @var{n} of
the insn.  When constructing an insn, operand number @var{n}
will be substituted at this point.  When matching an insn, whatever
appears at this position in the insn will be taken as operand
number @var{n}; but it must satisfy @var{testfn} or this instruction
pattern will not match at all.

Operand numbers must be chosen consecutively counting from zero in
each instruction pattern.  There may be only one @samp{match_operand}
expression in the pattern for each expression number, and they must
appear in order of increasing expression number.

@var{testfn} is a string that is the name of a C function that accepts
two arguments, a machine mode and an expression.  During matching,
the function will be called with @var{m} as the mode argument
and the putative operand as the other argument.  If it returns zero,
this instruction pattern fails to match.  @var{testfn} may be
an empty string; then it means no test is to be done on the operand.

Most often, @ar{testfn} is @code{"general_operand"}.  It checks
that the putative operand is either a constant, a register or a
memory reference, and that it is valid for mode @var{m}.

@var{constraint} is explained later.

@item (match_dup @var{n})
This expression is also a placeholder for operand number @var{n}.
It is used when the operand needs to appear more than once in the
insn.

In construction, @samp{match_dup} behaves exactly like
@var{match_operand}: the operand is substituted into the insn being
constructed.  But in matching, @samp{match_dup} behaves differently.
It assumes that operand number @var{n} has already been determined by
a @samp{match_operand} apparing earlier in the recognition template,
and it matches only an identical-looking expression.
@end table

