Return to rtl.texi CVS log

Up to [Apple XNU] / GNUtools / cc

Annotation of GNUtools/cc/rtl.texi, revision 1.1

1.1     ! root        1: @c Copyright (C) 1988, 1989, 1992 Free Software Foundation, Inc.
        !             2: @c This is part of the GCC manual.
        !             3: @c For copying conditions, see the file gcc.texi.
        !             4: 
        !             5: @node RTL
        !             6: @chapter RTL Representation
        !             7: @cindex RTL representation
        !             8: @cindex representation of RTL
        !             9: @cindex Register Transfer Language (RTL)
        !            10: 
        !            11: Most of the work of the compiler is done on an intermediate representation
        !            12: called register transfer language.  In this language, the instructions to be
        !            13: output are described, pretty much one by one, in an algebraic form that
        !            14: describes what the instruction does.
        !            15: 
        !            16: RTL is inspired by Lisp lists.  It has both an internal form, made up of
        !            17: structures that point at other structures, and a textual form that is used
        !            18: in the machine description and in printed debugging dumps.  The textual
        !            19: form uses nested parentheses to indicate the pointers in the internal form.
        !            20: 
        !            21: @menu
        !            22: * RTL Objects::       Expressions vs vectors vs strings vs integers.
        !            23: * Accessors::         Macros to access expression operands or vector elts.
        !            24: * Flags::             Other flags in an RTL expression.
        !            25: * Machine Modes::     Describing the size and format of a datum.
        !            26: * Constants::         Expressions with constant values.
        !            27: * Regs and Memory::   Expressions representing register contents or memory.
        !            28: * Arithmetic::        Expressions representing arithmetic on other expressions.
        !            29: * Comparisons::       Expressions representing comparison of expressions.
        !            30: * Bit Fields::        Expressions representing bitfields in memory or reg.
        !            31: * Conversions::       Extending, truncating, floating or fixing.
        !            32: * RTL Declarations::  Declaring volatility, constancy, etc.
        !            33: * Side Effects::      Expressions for storing in registers, etc.
        !            34: * Incdec::            Embedded side-effects for autoincrement addressing.
        !            35: * Assembler::         Representing @code{asm} with operands.
        !            36: * Insns::             Expression types for entire insns.
        !            37: * Calls::             RTL representation of function call insns.
        !            38: * Sharing::           Some expressions are unique; others *must* be copied.
        !            39: * Reading RTL::       Reading textual RTL from a file.
        !            40: @end menu
        !            41: 
        !            42: @node RTL Objects, Accessors, RTL, RTL
        !            43: @section RTL Object Types
        !            44: @cindex RTL object types
        !            45: 
        !            46: @cindex RTL integers
        !            47: @cindex RTL strings
        !            48: @cindex RTL vectors
        !            49: @cindex RTL expression
        !            50: @cindex RTX (See RTL)
        !            51: RTL uses five kinds of objects: expressions, integers, wide integers,
        !            52: strings and vectors.  Expressions are the most important ones.  An RTL
        !            53: expression (``RTX'', for short) is a C structure, but it is usually
        !            54: referred to with a pointer; a type that is given the typedef name
        !            55: @code{rtx}.
        !            56: 
        !            57: An integer is simply an @code{int}; their written form uses decimal digits.
        !            58: A wide integer is an integral object whose type is @code{HOST_WIDE_INT}
        !            59: (@pxref{Config}); their written form uses decimal digits.
        !            60: 
        !            61: A string is a sequence of characters.  In core it is represented as a
        !            62: @code{char *} in usual C fashion, and it is written in C syntax as well.
        !            63: However, strings in RTL may never be null.  If you write an empty string in
        !            64: a machine description, it is represented in core as a null pointer rather
        !            65: than as a pointer to a null character.  In certain contexts, these null
        !            66: pointers instead of strings are valid.  Within RTL code, strings are most
        !            67: commonly found inside @code{symbol_ref} expressions, but they appear in
        !            68: other contexts in the RTL expressions that make up machine descriptions.  
        !            69: 
        !            70: A vector contains an arbitrary number of pointers to expressions.  The
        !            71: number of elements in the vector is explicitly present in the vector.
        !            72: The written form of a vector consists of square brackets
        !            73: (@samp{[@dots{}]}) surrounding the elements, in sequence and with
        !            74: whitespace separating them.  Vectors of length zero are not created;
        !            75: null pointers are used instead.
        !            76: 
        !            77: @cindex expression codes
        !            78: @cindex codes, RTL expression
        !            79: @findex GET_CODE
        !            80: @findex PUT_CODE
        !            81: Expressions are classified by @dfn{expression codes} (also called RTX
        !            82: codes).  The expression code is a name defined in @file{rtl.def}, which is
        !            83: also (in upper case) a C enumeration constant.  The possible expression
        !            84: codes and their meanings are machine-independent.  The code of an RTX can
        !            85: be extracted with the macro @code{GET_CODE (@var{x})} and altered with
        !            86: @code{PUT_CODE (@var{x}, @var{newcode})}.
        !            87: 
        !            88: The expression code determines how many operands the expression contains,
        !            89: and what kinds of objects they are.  In RTL, unlike Lisp, you cannot tell
        !            90: by looking at an operand what kind of object it is.  Instead, you must know
        !            91: from its context---from the expression code of the containing expression.
        !            92: For example, in an expression of code @code{subreg}, the first operand is
        !            93: to be regarded as an expression and the second operand as an integer.  In
        !            94: an expression of code @code{plus}, there are two operands, both of which
        !            95: are to be regarded as expressions.  In a @code{symbol_ref} expression,
        !            96: there is one operand, which is to be regarded as a string.
        !            97: 
        !            98: Expressions are written as parentheses containing the name of the
        !            99: expression type, its flags and machine mode if any, and then the operands
        !           100: of the expression (separated by spaces).
        !           101: 
        !           102: Expression code names in the @samp{md} file are written in lower case,
        !           103: but when they appear in C code they are written in upper case.  In this
        !           104: manual, they are shown as follows: @code{const_int}.
        !           105: 
        !           106: @cindex (nil)
        !           107: @cindex nil
        !           108: In a few contexts a null pointer is valid where an expression is normally
        !           109: wanted.  The written form of this is @code{(nil)}.
        !           110: 
        !           111: @node Accessors, Flags, RTL Objects, RTL
        !           112: @section Access to Operands
        !           113: @cindex accessors
        !           114: @cindex access to operands
        !           115: @cindex operand access
        !           116: 
        !           117: @cindex RTL format
        !           118: For each expression type @file{rtl.def} specifies the number of
        !           119: contained objects and their kinds, with four possibilities: @samp{e} for
        !           120: expression (actually a pointer to an expression), @samp{i} for integer,
        !           121: @samp{w} for wide integer, @samp{s} for string, and @samp{E} for vector
        !           122: of expressions.  The sequence of letters for an expression code is
        !           123: called its @dfn{format}.  Thus, the format of @code{subreg} is
        !           124: @samp{ei}.@refill
        !           125: 
        !           126: @cindex RTL format characters
        !           127: A few other format characters are used occasionally:
        !           128: 
        !           129: @table @code
        !           130: @item u
        !           131: @samp{u} is equivalent to @samp{e} except that it is printed differently
        !           132: in debugging dumps.  It is used for pointers to insns.
        !           133: 
        !           134: @item n
        !           135: @samp{n} is equivalent to @samp{i} except that it is printed differently
        !           136: in debugging dumps.  It is used for the line number or code number of a
        !           137: @code{note} insn.
        !           138: 
        !           139: @item S
        !           140: @samp{S} indicates a string which is optional.  In the RTL objects in
        !           141: core, @samp{S} is equivalent to @samp{s}, but when the object is read,
        !           142: from an @samp{md} file, the string value of this operand may be omitted.
        !           143: An omitted string is taken to be the null string.
        !           144: 
        !           145: @item V
        !           146: @samp{V} indicates a vector which is optional.  In the RTL objects in
        !           147: core, @samp{V} is equivalent to @samp{E}, but when the object is read
        !           148: from an @samp{md} file, the vector value of this operand may be omitted.
        !           149: An omitted vector is effectively the same as a vector of no elements.
        !           150: 
        !           151: @item 0
        !           152: @samp{0} means a slot whose contents do not fit any normal category.
        !           153: @samp{0} slots are not printed at all in dumps, and are often used in
        !           154: special ways by small parts of the compiler.
        !           155: @end table
        !           156: 
        !           157: There are macros to get the number of operands, the format, and the
        !           158: class of an expression code:
        !           159: 
        !           160: @table @code
        !           161: @findex GET_RTX_LENGTH
        !           162: @item GET_RTX_LENGTH (@var{code})
        !           163: Number of operands of an RTX of code @var{code}.
        !           164: 
        !           165: @findex GET_RTX_FORMAT
        !           166: @item GET_RTX_FORMAT (@var{code})
        !           167: The format of an RTX of code @var{code}, as a C string.
        !           168: 
        !           169: @findex GET_RTX_CLASS
        !           170: @cindex classes of RTX codes
        !           171: @item GET_RTX_CLASS (@var{code})
        !           172: A single character representing the type of RTX operation that code
        !           173: @var{code} performs.
        !           174: 
        !           175: The following classes are defined:
        !           176: 
        !           177: @table @code
        !           178: @item o
        !           179: An RTX code that represents an actual object, such as @code{reg} or
        !           180: @code{mem}.  @code{subreg} is not in this class.
        !           181: 
        !           182: @item <
        !           183: An RTX code for a comparison.  The codes in this class are
        !           184: @code{NE}, @code{EQ}, @code{LE}, @code{LT}, @code{GE}, @code{GT},
        !           185: @code{LEU}, @code{LTU}, @code{GEU}, @code{GTU}.@refill
        !           186: 
        !           187: @item 1
        !           188: An RTX code for a unary arithmetic operation, such as @code{neg}.
        !           189: 
        !           190: @item c
        !           191: An RTX code for a commutative binary operation, other than @code{NE}
        !           192: and @code{EQ} (which have class @samp{<}).
        !           193: 
        !           194: @item 2
        !           195: An RTX code for a noncommutative binary operation, such as @code{MINUS}.
        !           196: 
        !           197: @item b
        !           198: An RTX code for a bitfield operation, either @code{ZERO_EXTRACT} or
        !           199: @code{SIGN_EXTRACT}.
        !           200: 
        !           201: @item 3
        !           202: An RTX code for other three input operations, such as @code{IF_THEN_ELSE}.
        !           203: 
        !           204: @item i
        !           205: An RTX code for a machine insn (@code{INSN}, @code{JUMP_INSN}, and
        !           206: @code{CALL_INSN}).@refill
        !           207: 
        !           208: @item m
        !           209: An RTX code for something that matches in insns, such as @code{MATCH_DUP}.
        !           210: 
        !           211: @item x
        !           212: All other RTX codes.
        !           213: @end table
        !           214: @end table
        !           215: 
        !           216: @findex XEXP
        !           217: @findex XINT
        !           218: @findex XWINT
        !           219: @findex XSTR
        !           220: Operands of expressions are accessed using the macros @code{XEXP},
        !           221: @code{XINT}, @code{XWINT} and @code{XSTR}.  Each of these macros takes
        !           222: two arguments: an expression-pointer (RTX) and an operand number
        !           223: (counting from zero).  Thus,@refill
        !           224: 
        !           225: @example
        !           226: XEXP (@var{x}, 2)
        !           227: @end example
        !           228: 
        !           229: @noindent
        !           230: accesses operand 2 of expression @var{x}, as an expression.
        !           231: 
        !           232: @example
        !           233: XINT (@var{x}, 2)
        !           234: @end example
        !           235: 
        !           236: @noindent
        !           237: accesses the same operand as an integer.  @code{XSTR}, used in the same
        !           238: fashion, would access it as a string.
        !           239: 
        !           240: Any operand can be accessed as an integer, as an expression or as a string.
        !           241: You must choose the correct method of access for the kind of value actually
        !           242: stored in the operand.  You would do this based on the expression code of
        !           243: the containing expression.  That is also how you would know how many
        !           244: operands there are.
        !           245: 
        !           246: For example, if @var{x} is a @code{subreg} expression, you know that it has
        !           247: two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
        !           248: and @code{XINT (@var{x}, 1)}.  If you did @code{XINT (@var{x}, 0)}, you
        !           249: would get the address of the expression operand but cast as an integer;
        !           250: that might occasionally be useful, but it would be cleaner to write
        !           251: @code{(int) XEXP (@var{x}, 0)}.  @code{XEXP (@var{x}, 1)} would also
        !           252: compile without error, and would return the second, integer operand cast as
        !           253: an expression pointer, which would probably result in a crash when
        !           254: accessed.  Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
        !           255: but this will access memory past the end of the expression with
        !           256: unpredictable results.@refill
        !           257: 
        !           258: Access to operands which are vectors is more complicated.  You can use the
        !           259: macro @code{XVEC} to get the vector-pointer itself, or the macros
        !           260: @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
        !           261: vector.
        !           262: 
        !           263: @table @code
        !           264: @findex XVEC
        !           265: @item XVEC (@var{exp}, @var{idx})
        !           266: Access the vector-pointer which is operand number @var{idx} in @var{exp}.
        !           267: 
        !           268: @findex XVECLEN
        !           269: @item XVECLEN (@var{exp}, @var{idx})
        !           270: Access the length (number of elements) in the vector which is
        !           271: in operand number @var{idx} in @var{exp}.  This value is an @code{int}.
        !           272: 
        !           273: @findex XVECEXP
        !           274: @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
        !           275: Access element number @var{eltnum} in the vector which is
        !           276: in operand number @var{idx} in @var{exp}.  This value is an RTX.
        !           277: 
        !           278: It is up to you to make sure that @var{eltnum} is not negative
        !           279: and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
        !           280: @end table
        !           281: 
        !           282: All the macros defined in this section expand into lvalues and therefore
        !           283: can be used to assign the operands, lengths and vector elements as well as
        !           284: to access them.
        !           285: 
        !           286: @node Flags, Machine Modes, Accessors, RTL
        !           287: @section Flags in an RTL Expression
        !           288: @cindex flags in RTL expression
        !           289: 
        !           290: RTL expressions contain several flags (one-bit bitfields) that are used
        !           291: in certain types of expression.  Most often they are accessed with the
        !           292: following macros:
        !           293: 
        !           294: @table @code
        !           295: @findex MEM_VOLATILE_P
        !           296: @cindex @code{mem} and @samp{/v}
        !           297: @cindex @code{volatil}, in @code{mem}
        !           298: @cindex @samp{/v} in RTL dump
        !           299: @item MEM_VOLATILE_P (@var{x})
        !           300: In @code{mem} expressions, nonzero for volatile memory references.
        !           301: Stored in the @code{volatil} field and printed as @samp{/v}.
        !           302: 
        !           303: @findex MEM_IN_STRUCT_P
        !           304: @cindex @code{mem} and @samp{/s}
        !           305: @cindex @code{in_struct}, in @code{mem}
        !           306: @cindex @samp{/s} in RTL dump
        !           307: @item MEM_IN_STRUCT_P (@var{x})
        !           308: In @code{mem} expressions, nonzero for reference to an entire
        !           309: structure, union or array, or to a component of one.  Zero for
        !           310: references to a scalar variable or through a pointer to a scalar.
        !           311: Stored in the @code{in_struct} field and printed as @samp{/s}.
        !           312: 
        !           313: @findex REG_LOOP_TEST_P
        !           314: @cindex @code{reg} and @samp{/s}
        !           315: @cindex @code{in_struct}, in @code{reg}
        !           316: @item REG_LOOP_TEST_P
        !           317: In @code{reg} expressions, nonzero if this register's entire life is
        !           318: contained in the exit test code for some loop.  Stored in the
        !           319: @code{in_struct} field and printed as @samp{/s}.
        !           320: 
        !           321: @findex REG_USERVAR_P 
        !           322: @cindex @code{reg} and @samp{/v}
        !           323: @cindex @code{volatil}, in @code{reg}
        !           324: @item REG_USERVAR_P (@var{x})
        !           325: In a @code{reg}, nonzero if it corresponds to a variable present in
        !           326: the user's source code.  Zero for temporaries generated internally by
        !           327: the compiler.  Stored in the @code{volatil} field and printed as
        !           328: @samp{/v}.
        !           329: 
        !           330: @cindex @samp{/i} in RTL dump
        !           331: @findex REG_FUNCTION_VALUE_P 
        !           332: @cindex @code{reg} and @samp{/i}
        !           333: @cindex @code{integrated}, in @code{reg}
        !           334: @item REG_FUNCTION_VALUE_P (@var{x})
        !           335: Nonzero in a @code{reg} if it is the place in which this function's
        !           336: value is going to be returned.  (This happens only in a hard
        !           337: register.)  Stored in the @code{integrated} field and printed as
        !           338: @samp{/i}.
        !           339: 
        !           340: The same hard register may be used also for collecting the values of
        !           341: functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
        !           342: in this kind of use.
        !           343: 
        !           344: @findex SUBREG_PROMOTED_VAR_P
        !           345: @cindex @code{subreg} and @samp{/s}
        !           346: @cindex @code{in_struct}, in @code{subreg}
        !           347: @item SUBREG_PROMOTED_VAR_P
        !           348: Nonzero in a @code{subreg} if it was made when accessing an object that
        !           349: was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine
        !           350: description macro (@pxref{Storage Layout}).  In this case, the mode of
        !           351: the @code{subreg} is the declared mode of the object and the mode of
        !           352: @code{SUBREG_REG} is the mode of the register that holds the object.
        !           353: Promoted variables are always either sign- or zero-extended to the wider
        !           354: mode on every assignment.  Stored in the @code{in_struct} field and
        !           355: printed as @samp{/s}.
        !           356: 
        !           357: @findex SUBREG_PROMOTED_UNSIGNED_P
        !           358: @cindex @code{subreg} and @samp{/u}
        !           359: @cindex @code{unchanging}, in @code{subreg}
        !           360: @item SUBREG_PROMOTED_UNSIGNED_P
        !           361: Nonzero in a @code{subreg} that has @code{SUBREG_PROMOTED_VAR_P} nonzero
        !           362: if the object being referenced is kept zero-extended and zero if it
        !           363: is kept sign-extended.  Stored in the @code{unchanging} field and
        !           364: printed as @samp{/u}.
        !           365: 
        !           366: @findex RTX_UNCHANGING_P 
        !           367: @cindex @code{reg} and @samp{/u}
        !           368: @cindex @code{mem} and @samp{/u}
        !           369: @cindex @code{unchanging}, in @code{reg} and @code{mem}
        !           370: @cindex @samp{/u} in RTL dump
        !           371: @item RTX_UNCHANGING_P (@var{x})
        !           372: Nonzero in a @code{reg} or @code{mem} if the value is not changed.
        !           373: (This flag is not set for memory references via pointers to constants.
        !           374: Such pointers only guarantee that the object will not be changed
        !           375: explicitly by the current function.  The object might be changed by
        !           376: other functions or by aliasing.)  Stored in the
        !           377: @code{unchanging} field and printed as @samp{/u}.
        !           378: 
        !           379: @findex RTX_INTEGRATED_P 
        !           380: @cindex @code{integrated}, in @code{insn}
        !           381: @item RTX_INTEGRATED_P (@var{insn})
        !           382: Nonzero in an insn if it resulted from an in-line function call.
        !           383: Stored in the @code{integrated} field and printed as @samp{/i}.  This
        !           384: may be deleted; nothing currently depends on it.
        !           385: 
        !           386: @findex SYMBOL_REF_USED
        !           387: @cindex @code{used}, in @code{symbol_ref}
        !           388: @item SYMBOL_REF_USED (@var{x})
        !           389: In a @code{symbol_ref}, indicates that @var{x} has been used.  This is
        !           390: normally only used to ensure that @var{x} is only declared external
        !           391: once.  Stored in the @code{used} field.
        !           392: 
        !           393: @findex SYMBOL_REF_FLAG
        !           394: @cindex @code{symbol_ref} and @samp{/v}
        !           395: @cindex @code{volatil}, in @code{symbol_ref}
        !           396: @item SYMBOL_REF_FLAG (@var{x})
        !           397: In a @code{symbol_ref}, this is used as a flag for machine-specific purposes.
        !           398: Stored in the @code{volatil} field and printed as @samp{/v}.
        !           399: 
        !           400: @findex LABEL_OUTSIDE_LOOP_P
        !           401: @cindex @code{label_ref} and @samp{/s}
        !           402: @cindex @code{in_struct}, in @code{label_ref}
        !           403: @item LABEL_OUTSIDE_LOOP_P
        !           404: In @code{label_ref} expressions, nonzero if this is a reference to a
        !           405: label that is outside the innermost loop containing the reference to the
        !           406: label.  Stored in the @code{in_struct} field and printed as @samp{/s}.
        !           407: 
        !           408: @findex INSN_DELETED_P 
        !           409: @cindex @code{volatil}, in @code{insn}
        !           410: @item INSN_DELETED_P (@var{insn})
        !           411: In an insn, nonzero if the insn has been deleted.  Stored in the
        !           412: @code{volatil} field and printed as @samp{/v}.
        !           413: 
        !           414: @findex INSN_ANNULLED_BRANCH_P
        !           415: @cindex @code{insn} and @samp{/u}
        !           416: @cindex @code{unchanging}, in @code{insn}
        !           417: @item INSN_ANNULLED_BRANCH_P (@var{insn})
        !           418: In an @code{insn} in the delay slot of a branch insn, indicates that an
        !           419: annulling branch should be used.  See the discussion under
        !           420: @code{sequence} below.  Stored in the @code{unchanging} field and printed
        !           421: as @samp{/u}.
        !           422: 
        !           423: @findex INSN_FROM_TARGET_P
        !           424: @cindex @code{insn} and @samp{/s}
        !           425: @cindex @code{in_struct}, in @code{insn}
        !           426: @cindex @samp{/s} in RTL dump
        !           427: @item INSN_FROM_TARGET_P (@var{insn})
        !           428: In an @code{insn} in a delay slot of a branch, indicates that the insn
        !           429: is from the target of the branch.  If the branch insn has
        !           430: @code{INSN_ANNULLED_BRANCH_P} set, this insn should only be executed if
        !           431: the branch is taken.  For annulled branches with this bit clear, the
        !           432: insn should be executed only if the branch is not taken.  Stored in the
        !           433: @code{in_struct} field and printed as @samp{/s}.
        !           434: 
        !           435: @findex CONSTANT_POOL_ADDRESS_P 
        !           436: @cindex @code{symbol_ref} and @samp{/u}
        !           437: @cindex @code{unchanging}, in @code{symbol_ref}
        !           438: @item CONSTANT_POOL_ADDRESS_P (@var{x})
        !           439: Nonzero in a @code{symbol_ref} if it refers to part of the current
        !           440: function's ``constants pool''.  These are addresses close to the
        !           441: beginning of the function, and GNU CC assumes they can be addressed
        !           442: directly (perhaps with the help of base registers).  Stored in the
        !           443: @code{unchanging} field and printed as @samp{/u}.
        !           444: 
        !           445: @findex CONST_CALL_P
        !           446: @cindex @code{call_insn} and @samp{/u}
        !           447: @cindex @code{unchanging}, in @code{call_insn}
        !           448: @item CONST_CALL_P (@var{x})
        !           449: In a @code{call_insn}, indicates that the insn represents a call to a const
        !           450: function.  Stored in the @code{unchanging} field and printed as @samp{/u}.
        !           451: 
        !           452: @findex LABEL_PRESERVE_P
        !           453: @cindex @code{code_label} and @samp{/i}
        !           454: @cindex @code{in_struct}, in @code{code_label}
        !           455: @item LABEL_PRESERVE_P (@var{x})
        !           456: In a @code{code_label}, indicates that the label can never be deleted.
        !           457: Labels referenced by a non-local goto will have this bit set.  Stored
        !           458: in the @code{in_struct} field and printed as @samp{/s}.
        !           459: 
        !           460: @findex SCHED_GROUP_P
        !           461: @cindex @code{insn} and @samp{/i}
        !           462: @cindex @code{in_struct}, in @code{insn}
        !           463: @item SCHED_GROUP_P (@var{insn})
        !           464: During instruction scheduling, in an insn, indicates that the previous insn
        !           465: must be scheduled together with this insn.  This is used to ensure that
        !           466: certain groups of instructions will not be split up by the instruction
        !           467: scheduling pass, for example, @code{use} insns before a @code{call_insn} may
        !           468: not be separated from the @code{call_insn}.  Stored in the @code{in_struct}
        !           469: field and printed as @samp{/s}.
        !           470: @end table
        !           471: 
        !           472: These are the fields which the above macros refer to:
        !           473: 
        !           474: @table @code
        !           475: @findex used
        !           476: @item used
        !           477: Normally, this flag is used only momentarily, at the end of RTL
        !           478: generation for a function, to count the number of times an expression
        !           479: appears in insns.  Expressions that appear more than once are copied,
        !           480: according to the rules for shared structure (@pxref{Sharing}).
        !           481: 
        !           482: In a @code{symbol_ref}, it indicates that an external declaration for
        !           483: the symbol has already been written.
        !           484: 
        !           485: In a @code{reg}, it is used by the leaf register renumbering code to ensure
        !           486: that each register is only renumbered once.
        !           487: 
        !           488: @findex volatil
        !           489: @item volatil
        !           490: This flag is used in @code{mem}, @code{symbol_ref} and @code{reg}
        !           491: expressions and in insns.  In RTL dump files, it is printed as
        !           492: @samp{/v}.
        !           493: 
        !           494: @cindex volatile memory references
        !           495: In a @code{mem} expression, it is 1 if the memory reference is volatile.
        !           496: Volatile memory references may not be deleted, reordered or combined.
        !           497: 
        !           498: In a @code{symbol_ref} expression, it is used for machine-specific 
        !           499: purposes.
        !           500: 
        !           501: In a @code{reg} expression, it is 1 if the value is a user-level variable.
        !           502: 0 indicates an internal compiler temporary.
        !           503: 
        !           504: In an insn, 1 means the insn has been deleted.
        !           505: 
        !           506: @findex in_struct
        !           507: @item in_struct
        !           508: In @code{mem} expressions, it is 1 if the memory datum referred to is
        !           509: all or part of a structure or array; 0 if it is (or might be) a scalar
        !           510: variable.  A reference through a C pointer has 0 because the pointer
        !           511: might point to a scalar variable.  This information allows the compiler
        !           512: to determine something about possible cases of aliasing.
        !           513: 
        !           514: In an insn in the delay slot of a branch, 1 means that this insn is from
        !           515: the target of the branch.
        !           516: 
        !           517: During instruction scheduling, in an insn, 1 means that this insn must be
        !           518: scheduled as part of a group together with the previous insn.
        !           519: 
        !           520: In @code{reg} expressions, it is 1 if the register has its entire life
        !           521: contained within the test expression of some loop.
        !           522: 
        !           523: In @code{subreg} expressions, 1 means that the @code{subreg} is accessing
        !           524: an object that has had its mode promoted from a wider mode.
        !           525: 
        !           526: In @code{label_ref} expressions, 1 means that the referenced label is
        !           527: outside the innermost loop containing the insn in which the @code{label_ref}
        !           528: was found.
        !           529: 
        !           530: In @code{code_label} expressions, it is 1 if the label may never be deleted.
        !           531: This is used for labels which are the target of non-local gotos.
        !           532: 
        !           533: In an RTL dump, this flag is represented as @samp{/s}.
        !           534: 
        !           535: @findex unchanging
        !           536: @item unchanging
        !           537: In @code{reg} and @code{mem} expressions, 1 means
        !           538: that the value of the expression never changes.
        !           539: 
        !           540: In @code{subreg} expressions, it is 1 if the @code{subreg} references an
        !           541: unsigned object whose mode has been promoted to a wider mode.
        !           542: 
        !           543: In an insn, 1 means that this is an annulling branch.
        !           544: 
        !           545: In a @code{symbol_ref} expression, 1 means that this symbol addresses
        !           546: something in the per-function constants pool.
        !           547: 
        !           548: In a @code{call_insn}, 1 means that this instruction is a call to a
        !           549: const function.
        !           550: 
        !           551: In an RTL dump, this flag is represented as @samp{/u}.
        !           552: 
        !           553: @findex integrated
        !           554: @item integrated
        !           555: In some kinds of expressions, including insns, this flag means the
        !           556: rtl was produced by procedure integration.
        !           557: 
        !           558: In a @code{reg} expression, this flag indicates the register
        !           559: containing the value to be returned by the current function.  On
        !           560: machines that pass parameters in registers, the same register number
        !           561: may be used for parameters as well, but this flag is not set on such
        !           562: uses.
        !           563: @end table
        !           564: 
        !           565: @node Machine Modes, Constants, Flags, RTL
        !           566: @section Machine Modes
        !           567: @cindex machine modes
        !           568: 
        !           569: @findex enum machine_mode
        !           570: A machine mode describes a size of data object and the representation used
        !           571: for it.  In the C code, machine modes are represented by an enumeration
        !           572: type, @code{enum machine_mode}, defined in @file{machmode.def}.  Each RTL
        !           573: expression has room for a machine mode and so do certain kinds of tree
        !           574: expressions (declarations and types, to be precise).
        !           575: 
        !           576: In debugging dumps and machine descriptions, the machine mode of an RTL
        !           577: expression is written after the expression code with a colon to separate
        !           578: them.  The letters @samp{mode} which appear at the end of each machine mode
        !           579: name are omitted.  For example, @code{(reg:SI 38)} is a @code{reg}
        !           580: expression with machine mode @code{SImode}.  If the mode is
        !           581: @code{VOIDmode}, it is not written at all.
        !           582: 
        !           583: Here is a table of machine modes.  The term ``byte'' below refers to an
        !           584: object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}).
        !           585: 
        !           586: @table @code
        !           587: @findex QImode
        !           588: @item QImode
        !           589: ``Quarter-Integer'' mode represents a single byte treated as an integer.
        !           590: 
        !           591: @findex HImode
        !           592: @item HImode
        !           593: ``Half-Integer'' mode represents a two-byte integer.
        !           594: 
        !           595: @findex PSImode
        !           596: @item PSImode
        !           597: ``Partial Single Integer'' mode represents an integer which occupies
        !           598: four bytes but which doesn't really use all four.  On some machines,
        !           599: this is the right mode to use for pointers.
        !           600: 
        !           601: @findex SImode
        !           602: @item SImode
        !           603: ``Single Integer'' mode represents a four-byte integer.
        !           604: 
        !           605: @findex PDImode
        !           606: @item PDImode
        !           607: ``Partial Double Integer'' mode represents an integer which occupies
        !           608: eight bytes but which doesn't really use all eight.  On some machines,
        !           609: this is the right mode to use for certain pointers.
        !           610: 
        !           611: @findex DImode
        !           612: @item DImode
        !           613: ``Double Integer'' mode represents an eight-byte integer.
        !           614: 
        !           615: @findex TImode
        !           616: @item TImode
        !           617: ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
        !           618: 
        !           619: @findex SFmode
        !           620: @item SFmode
        !           621: ``Single Floating'' mode represents a single-precision (four byte) floating
        !           622: point number.
        !           623: 
        !           624: @findex DFmode
        !           625: @item DFmode
        !           626: ``Double Floating'' mode represents a double-precision (eight byte) floating
        !           627: point number.
        !           628: 
        !           629: @findex XFmode
        !           630: @item XFmode
        !           631: ``Extended Floating'' mode represents a triple-precision (twelve byte)
        !           632: floating point number.  This mode is used for IEEE extended floating
        !           633: point.
        !           634: 
        !           635: @findex TFmode
        !           636: @item TFmode
        !           637: ``Tetra Floating'' mode represents a quadruple-precision (sixteen byte)
        !           638: floating point number.
        !           639: 
        !           640: @findex CCmode
        !           641: @item CCmode
        !           642: ``Condition Code'' mode represents the value of a condition code, which
        !           643: is a machine-specific set of bits used to represent the result of a
        !           644: comparison operation.  Other machine-specific modes may also be used for
        !           645: the condition code.  These modes are not used on machines that use
        !           646: @code{cc0} (see @pxref{Condition Code}).
        !           647: 
        !           648: @findex BLKmode
        !           649: @item BLKmode
        !           650: ``Block'' mode represents values that are aggregates to which none of
        !           651: the other modes apply.  In RTL, only memory references can have this mode,
        !           652: and only if they appear in string-move or vector instructions.  On machines
        !           653: which have no such instructions, @code{BLKmode} will not appear in RTL.
        !           654: 
        !           655: @findex VOIDmode
        !           656: @item VOIDmode
        !           657: Void mode means the absence of a mode or an unspecified mode.
        !           658: For example, RTL expressions of code @code{const_int} have mode
        !           659: @code{VOIDmode} because they can be taken to have whatever mode the context
        !           660: requires.  In debugging dumps of RTL, @code{VOIDmode} is expressed by
        !           661: the absence of any mode.
        !           662: 
        !           663: @findex SCmode
        !           664: @findex DCmode
        !           665: @findex XCmode
        !           666: @findex TCmode
        !           667: @item SCmode, DCmode, XCmode, TCmode
        !           668: These modes stand for a complex number represented as a pair of floating
        !           669: point values.  The floating point values are in @code{SFmode},
        !           670: @code{DFmode}, @code{XFmode}, and @code{TFmode}, respectively.
        !           671: 
        !           672: @findex CQImode
        !           673: @findex CHImode
        !           674: @findex CSImode
        !           675: @findex CDImode
        !           676: @findex CTImode
        !           677: @findex COImode
        !           678: @item CQImode, CHImode, CSImode, CDImode, CTImode, COImode
        !           679: These modes stand for a complex number represented as a pair of integer
        !           680: values.  The integer values are in @code{QImode}, @code{HImode},
        !           681: @code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode},
        !           682: respectively.
        !           683: @end table
        !           684: 
        !           685: The machine description defines @code{Pmode} as a C macro which expands
        !           686: into the machine mode used for addresses.  Normally this is the mode
        !           687: whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines.
        !           688: 
        !           689: The only modes which a machine description @i{must} support are
        !           690: @code{QImode}, and the modes corresponding to @code{BITS_PER_WORD},
        !           691: @code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}.
        !           692: The compiler will attempt to use @code{DImode} for 8-byte structures and
        !           693: unions, but this can be prevented by overriding the definition of
        !           694: @code{MAX_FIXED_MODE_SIZE}.  Alternatively, you can have the compiler
        !           695: use @code{TImode} for 16-byte structures and unions.  Likewise, you can
        !           696: arrange for the C type @code{short int} to avoid using @code{HImode}.
        !           697: 
        !           698: @cindex mode classes
        !           699: Very few explicit references to machine modes remain in the compiler and
        !           700: these few references will soon be removed.  Instead, the machine modes
        !           701: are divided into mode classes.  These are represented by the enumeration
        !           702: type @code{enum mode_class} defined in @file{machmode.h}.  The possible
        !           703: mode classes are:
        !           704: 
        !           705: @table @code
        !           706: @findex MODE_INT
        !           707: @item MODE_INT
        !           708: Integer modes.  By default these are @code{QImode}, @code{HImode},
        !           709: @code{SImode}, @code{DImode}, and @code{TImode}.
        !           710: 
        !           711: @findex MODE_PARTIAL_INT
        !           712: @item MODE_PARTIAL_INT
        !           713: The ``partial integer'' modes, @code{PSImode} and @code{PDImode}.
        !           714: 
        !           715: @findex MODE_FLOAT
        !           716: @item MODE_FLOAT
        !           717: floating point modes.  By default these are @code{SFmode}, @code{DFmode},
        !           718: @code{XFmode} and @code{TFmode}.
        !           719: 
        !           720: @findex MODE_COMPLEX_INT
        !           721: @item MODE_COMPLEX_INT
        !           722: Complex integer modes.  (These are not currently implemented).
        !           723: 
        !           724: @findex MODE_COMPLEX_FLOAT
        !           725: @item MODE_COMPLEX_FLOAT
        !           726: Complex floating point modes.  By default these are @code{SCmode},
        !           727: @code{DCmode}, @code{XCmode}, and @code{TCmode}.
        !           728: 
        !           729: @findex MODE_FUNCTION
        !           730: @item MODE_FUNCTION
        !           731: Algol or Pascal function variables including a static chain.
        !           732: (These are not currently implemented).
        !           733: 
        !           734: @findex MODE_CC
        !           735: @item MODE_CC
        !           736: Modes representing condition code values.  These are @code{CCmode} plus
        !           737: any modes listed in the @code{EXTRA_CC_MODES} macro.  @xref{Jump Patterns},
        !           738: also see @ref{Condition Code}.
        !           739: 
        !           740: @findex MODE_RANDOM
        !           741: @item MODE_RANDOM
        !           742: This is a catchall mode class for modes which don't fit into the above
        !           743: classes.  Currently @code{VOIDmode} and @code{BLKmode} are in
        !           744: @code{MODE_RANDOM}.
        !           745: @end table
        !           746: 
        !           747: Here are some C macros that relate to machine modes:
        !           748: 
        !           749: @table @code
        !           750: @findex GET_MODE
        !           751: @item GET_MODE (@var{x})
        !           752: Returns the machine mode of the RTX @var{x}.
        !           753: 
        !           754: @findex PUT_MODE
        !           755: @item PUT_MODE (@var{x}, @var{newmode})
        !           756: Alters the machine mode of the RTX @var{x} to be @var{newmode}.
        !           757: 
        !           758: @findex NUM_MACHINE_MODES
        !           759: @item NUM_MACHINE_MODES
        !           760: Stands for the number of machine modes available on the target
        !           761: machine.  This is one greater than the largest numeric value of any
        !           762: machine mode.
        !           763: 
        !           764: @findex GET_MODE_NAME
        !           765: @item GET_MODE_NAME (@var{m})
        !           766: Returns the name of mode @var{m} as a string.
        !           767: 
        !           768: @findex GET_MODE_CLASS
        !           769: @item GET_MODE_CLASS (@var{m})
        !           770: Returns the mode class of mode @var{m}.
        !           771: 
        !           772: @findex GET_MODE_WIDER_MODE
        !           773: @item GET_MODE_WIDER_MODE (@var{m})
        !           774: Returns the next wider natural mode.  For example, the expression
        !           775: @code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}.
        !           776: 
        !           777: @findex GET_MODE_SIZE
        !           778: @item GET_MODE_SIZE (@var{m})
        !           779: Returns the size in bytes of a datum of mode @var{m}.
        !           780: 
        !           781: @findex GET_MODE_BITSIZE
        !           782: @item GET_MODE_BITSIZE (@var{m})
        !           783: Returns the size in bits of a datum of mode @var{m}.
        !           784: 
        !           785: @findex GET_MODE_MASK
        !           786: @item GET_MODE_MASK (@var{m})
        !           787: Returns a bitmask containing 1 for all bits in a word that fit within
        !           788: mode @var{m}.  This macro can only be used for modes whose bitsize is
        !           789: less than or equal to @code{HOST_BITS_PER_INT}.
        !           790: 
        !           791: @findex GET_MODE_ALIGNMENT
        !           792: @item GET_MODE_ALIGNMENT (@var{m)})
        !           793: Return the required alignment, in bits, for an object of mode @var{m}.
        !           794: 
        !           795: @findex GET_MODE_UNIT_SIZE
        !           796: @item GET_MODE_UNIT_SIZE (@var{m})
        !           797: Returns the size in bytes of the subunits of a datum of mode @var{m}.
        !           798: This is the same as @code{GET_MODE_SIZE} except in the case of complex
        !           799: modes.  For them, the unit size is the size of the real or imaginary
        !           800: part.
        !           801: 
        !           802: @findex GET_MODE_NUNITS
        !           803: @item GET_MODE_NUNITS (@var{m})
        !           804: Returns the number of units contained in a mode, i.e.,
        !           805: @code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}.
        !           806: 
        !           807: @findex GET_CLASS_NARROWEST_MODE
        !           808: @item GET_CLASS_NARROWEST_MODE (@var{c})
        !           809: Returns the narrowest mode in mode class @var{c}.
        !           810: @end table
        !           811: 
        !           812: @findex byte_mode
        !           813: @findex word_mode
        !           814: The global variables @code{byte_mode} and @code{word_mode} contain modes
        !           815: whose classes are @code{MODE_INT} and whose bitsizes are either
        !           816: @code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively.  On 32-bit
        !           817: machines, these are @code{QImode} and @code{SImode}, respectively.
        !           818: 
        !           819: @node Constants, Regs and Memory, Machine Modes, RTL
        !           820: @section Constant Expression Types
        !           821: @cindex RTL constants
        !           822: @cindex RTL constant expression types
        !           823: 
        !           824: The simplest RTL expressions are those that represent constant values.
        !           825: 
        !           826: @table @code
        !           827: @findex const_int
        !           828: @item (const_int @var{i})
        !           829: This type of expression represents the integer value @var{i}.  @var{i}
        !           830: is customarily accessed with the macro @code{INTVAL} as in
        !           831: @code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}.
        !           832: 
        !           833: @findex const0_rtx
        !           834: @findex const1_rtx
        !           835: @findex const2_rtx
        !           836: @findex constm1_rtx
        !           837: There is only one expression object for the integer value zero; it is
        !           838: the value of the variable @code{const0_rtx}.  Likewise, the only
        !           839: expression for integer value one is found in @code{const1_rtx}, the only
        !           840: expression for integer value two is found in @code{const2_rtx}, and the
        !           841: only expression for integer value negative one is found in
        !           842: @code{constm1_rtx}.  Any attempt to create an expression of code
        !           843: @code{const_int} and value zero, one, two or negative one will return
        !           844: @code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or
        !           845: @code{constm1_rtx} as appropriate.@refill
        !           846: 
        !           847: @findex const_true_rtx
        !           848: Similarly, there is only one object for the integer whose value is
        !           849: @code{STORE_FLAG_VALUE}.  It is found in @code{const_true_rtx}.  If
        !           850: @code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and
        !           851: @code{const1_rtx} will point to the same object.  If
        !           852: @code{STORE_FLAG_VALUE} is -1, @code{const_true_rtx} and
        !           853: @code{constm1_rtx} will point to the same object.@refill
        !           854: 
        !           855: @findex const_double
        !           856: @item (const_double:@var{m} @var{addr} @var{i0} @var{i1} @dots{})
        !           857: Represents either a floating-point constant of mode @var{m} or an
        !           858: integer constant too large to fit into @code{HOST_BITS_PER_WIDE_INT}
        !           859: bits but small enough to fit within twice that number of bits (GNU CC
        !           860: does not provide a mechanism to represent even larger constants).  In
        !           861: the latter case, @var{m} will be @code{VOIDmode}.
        !           862: 
        !           863: @findex CONST_DOUBLE_MEM
        !           864: @findex CONST_DOUBLE_CHAIN
        !           865: @var{addr} is used to contain the @code{mem} expression that corresponds
        !           866: to the location in memory that at which the constant can be found.  If
        !           867: it has not been allocated a memory location, but is on the chain of all
        !           868: @code{const_double} expressions in this compilation (maintained using an
        !           869: undisplayed field), @var{addr} contains @code{const0_rtx}.  If it is not
        !           870: on the chain, @var{addr} contains @code{cc0_rtx}.  @var{addr} is
        !           871: customarily accessed with the macro @code{CONST_DOUBLE_MEM} and the
        !           872: chain field via @code{CONST_DOUBLE_CHAIN}.@refill
        !           873: 
        !           874: @findex CONST_DOUBLE_LOW
        !           875: If @var{m} is @code{VOIDmode}, the bits of the value are stored in
        !           876: @var{i0} and @var{i1}.  @var{i0} is customarily accessed with the macro
        !           877: @code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}.
        !           878: 
        !           879: If the constant is floating point (regardless of its precision), then
        !           880: the number of integers used to store the value depends on the size of
        !           881: @code{REAL_VALUE_TYPE} (@pxref{Cross-compilation}).  The integers
        !           882: represent a floating point number, but not precisely in the target
        !           883: machine's or host machine's floating point format.  To convert them to
        !           884: the precise bit pattern used by the target machine, use the macro
        !           885: @code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}).
        !           886: 
        !           887: @findex CONST0_RTX
        !           888: @findex CONST1_RTX
        !           889: @findex CONST2_RTX
        !           890: The macro @code{CONST0_RTX (@var{mode})} refers to an expression with
        !           891: value 0 in mode @var{mode}.  If mode @var{mode} is of mode class
        !           892: @code{MODE_INT}, it returns @code{const0_rtx}.  Otherwise, it returns a
        !           893: @code{CONST_DOUBLE} expression in mode @var{mode}.  Similarly, the macro
        !           894: @code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in
        !           895: mode @var{mode} and similarly for @code{CONST2_RTX}.
        !           896: 
        !           897: @findex const_string
        !           898: @item (const_string @var{str})
        !           899: Represents a constant string with value @var{str}.  Currently this is
        !           900: used only for insn attributes (@pxref{Insn Attributes}) since constant
        !           901: strings in C are placed in memory.
        !           902: 
        !           903: @findex symbol_ref
        !           904: @item (symbol_ref:@var{mode} @var{symbol})
        !           905: Represents the value of an assembler label for data.  @var{symbol} is
        !           906: a string that describes the name of the assembler label.  If it starts
        !           907: with a @samp{*}, the label is the rest of @var{symbol} not including
        !           908: the @samp{*}.  Otherwise, the label is @var{symbol}, usually prefixed
        !           909: with @samp{_}.
        !           910: 
        !           911: The @code{symbol_ref} contains a mode, which is usually @code{Pmode}.
        !           912: Usually that is the only mode for which a symbol is directly valid.
        !           913: 
        !           914: @findex label_ref
        !           915: @item (label_ref @var{label})
        !           916: Represents the value of an assembler label for code.  It contains one
        !           917: operand, an expression, which must be a @code{code_label} that appears
        !           918: in the instruction sequence to identify the place where the label
        !           919: should go.
        !           920: 
        !           921: The reason for using a distinct expression type for code label
        !           922: references is so that jump optimization can distinguish them.
        !           923: 
        !           924: @item (const:@var{m} @var{exp})
        !           925: Represents a constant that is the result of an assembly-time
        !           926: arithmetic computation.  The operand, @var{exp}, is an expression that
        !           927: contains only constants (@code{const_int}, @code{symbol_ref} and
        !           928: @code{label_ref} expressions) combined with @code{plus} and
        !           929: @code{minus}.  However, not all combinations are valid, since the
        !           930: assembler cannot do arbitrary arithmetic on relocatable symbols.
        !           931: 
        !           932: @var{m} should be @code{Pmode}.
        !           933: 
        !           934: @findex high
        !           935: @item (high:@var{m} @var{exp})
        !           936: Represents the high-order bits of @var{exp}, usually a
        !           937: @code{symbol_ref}.  The number of bits is machine-dependent and is
        !           938: normally the number of bits specified in an instruction that initializes
        !           939: the high order bits of a register.  It is used with @code{lo_sum} to
        !           940: represent the typical two-instruction sequence used in RISC machines to
        !           941: reference a global memory location.
        !           942: 
        !           943: @var{m} should be @code{Pmode}.
        !           944: @end table
        !           945: 
        !           946: @node Regs and Memory, Arithmetic, Constants, RTL
        !           947: @section Registers and Memory
        !           948: @cindex RTL register expressions
        !           949: @cindex RTL memory expressions
        !           950: 
        !           951: Here are the RTL expression types for describing access to machine
        !           952: registers and to main memory.
        !           953: 
        !           954: @table @code
        !           955: @findex reg
        !           956: @cindex hard registers
        !           957: @cindex pseudo registers
        !           958: @item (reg:@var{m} @var{n})
        !           959: For small values of the integer @var{n} (those that are less than
        !           960: @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
        !           961: register number @var{n}: a @dfn{hard register}.  For larger values of
        !           962: @var{n}, it stands for a temporary value or @dfn{pseudo register}.
        !           963: The compiler's strategy is to generate code assuming an unlimited
        !           964: number of such pseudo registers, and later convert them into hard
        !           965: registers or into memory references.
        !           966: 
        !           967: @var{m} is the machine mode of the reference.  It is necessary because
        !           968: machines can generally refer to each register in more than one mode.
        !           969: For example, a register may contain a full word but there may be
        !           970: instructions to refer to it as a half word or as a single byte, as
        !           971: well as instructions to refer to it as a floating point number of
        !           972: various precisions.
        !           973: 
        !           974: Even for a register that the machine can access in only one mode,
        !           975: the mode must always be specified.
        !           976: 
        !           977: The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
        !           978: description, since the number of hard registers on the machine is an
        !           979: invariant characteristic of the machine.  Note, however, that not
        !           980: all of the machine registers must be general registers.  All the
        !           981: machine registers that can be used for storage of data are given
        !           982: hard register numbers, even those that can be used only in certain
        !           983: instructions or can hold only certain types of data.
        !           984: 
        !           985: A hard register may be accessed in various modes throughout one
        !           986: function, but each pseudo register is given a natural mode
        !           987: and is accessed only in that mode.  When it is necessary to describe
        !           988: an access to a pseudo register using a nonnatural mode, a @code{subreg}
        !           989: expression is used.
        !           990: 
        !           991: A @code{reg} expression with a machine mode that specifies more than
        !           992: one word of data may actually stand for several consecutive registers.
        !           993: If in addition the register number specifies a hardware register, then
        !           994: it actually represents several consecutive hardware registers starting
        !           995: with the specified one.
        !           996: 
        !           997: Each pseudo register number used in a function's RTL code is
        !           998: represented by a unique @code{reg} expression.
        !           999: 
        !          1000: @findex FIRST_VIRTUAL_REGISTER
        !          1001: @findex LAST_VIRTUAL_REGISTER
        !          1002: Some pseudo register numbers, those within the range of
        !          1003: @code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only
        !          1004: appear during the RTL generation phase and are eliminated before the
        !          1005: optimization phases.  These represent locations in the stack frame that
        !          1006: cannot be determined until RTL generation for the function has been
        !          1007: completed.  The following virtual register numbers are defined:
        !          1008: 
        !          1009: @table @code
        !          1010: @findex VIRTUAL_INCOMING_ARGS_REGNUM
        !          1011: @item VIRTUAL_INCOMING_ARGS_REGNUM
        !          1012: This points to the first word of the incoming arguments passed on the
        !          1013: stack.  Normally these arguments are placed there by the caller, but the
        !          1014: callee may have pushed some arguments that were previously passed in
        !          1015: registers.
        !          1016: 
        !          1017: @cindex @code{FIRST_PARM_OFFSET} and virtual registers
        !          1018: @cindex @code{ARG_POINTER_REGNUM} and virtual registers
        !          1019: When RTL generation is complete, this virtual register is replaced
        !          1020: by the sum of the register given by @code{ARG_POINTER_REGNUM} and the
        !          1021: value of @code{FIRST_PARM_OFFSET}.
        !          1022: 
        !          1023: @findex VIRTUAL_STACK_VARS_REGNUM
        !          1024: @cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers
        !          1025: @item VIRTUAL_STACK_VARS_REGNUM
        !          1026: If @code{FRAME_GROWS_DOWNWARD} is defined, this points to immediately
        !          1027: above the first variable on the stack.  Otherwise, it points to the
        !          1028: first variable on the stack.
        !          1029: 
        !          1030: @cindex @code{STARTING_FRAME_OFFSET} and virtual registers
        !          1031: @cindex @code{FRAME_POINTER_REGNUM} and virtual registers
        !          1032: @code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the
        !          1033: register given by @code{FRAME_POINTER_REGNUM} and the value
        !          1034: @code{STARTING_FRAME_OFFSET}.
        !          1035: 
        !          1036: @findex VIRTUAL_STACK_DYNAMIC_REGNUM
        !          1037: @item VIRTUAL_STACK_DYNAMIC_REGNUM
        !          1038: This points to the location of dynamically allocated memory on the stack
        !          1039: immediately after the stack pointer has been adjusted by the amount of
        !          1040: memory desired.
        !          1041: 
        !          1042: @cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers
        !          1043: @cindex @code{STACK_POINTER_REGNUM} and virtual registers
        !          1044: This virtual register is replaced by the sum of the register given by
        !          1045: @code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}.
        !          1046: 
        !          1047: @findex VIRTUAL_OUTGOING_ARGS_REGNUM
        !          1048: @item VIRTUAL_OUTGOING_ARGS_REGNUM
        !          1049: This points to the location in the stack at which outgoing arguments
        !          1050: should be written when the stack is pre-pushed (arguments pushed using
        !          1051: push insns should always use @code{STACK_POINTER_REGNUM}).
        !          1052: 
        !          1053: @cindex @code{STACK_POINTER_OFFSET} and virtual registers
        !          1054: This virtual register is replaced by the sum of the register given by
        !          1055: @code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}.
        !          1056: @end table
        !          1057: 
        !          1058: @findex subreg
        !          1059: @item (subreg:@var{m} @var{reg} @var{wordnum})
        !          1060: @code{subreg} expressions are used to refer to a register in a machine
        !          1061: mode other than its natural one, or to refer to one register of
        !          1062: a multi-word @code{reg} that actually refers to several registers.
        !          1063: 
        !          1064: Each pseudo-register has a natural mode.  If it is necessary to
        !          1065: operate on it in a different mode---for example, to perform a fullword
        !          1066: move instruction on a pseudo-register that contains a single
        !          1067: byte---the pseudo-register must be enclosed in a @code{subreg}.  In
        !          1068: such a case, @var{wordnum} is zero.
        !          1069: 
        !          1070: Usually @var{m} is at least as narrow as the mode of @var{reg}, in which
        !          1071: case it is restricting consideration to only the bits of @var{reg} that
        !          1072: are in @var{m}.
        !          1073: 
        !          1074: Sometimes @var{m} is wider than the mode of @var{reg}.  These
        !          1075: @code{subreg} expressions are often called @dfn{paradoxical}.  They are
        !          1076: used in cases where we want to refer to an object in a wider mode but do
        !          1077: not care what value the additional bits have.  The reload pass ensures
        !          1078: that paradoxical references are only made to hard registers.
        !          1079: 
        !          1080: The other use of @code{subreg} is to extract the individual registers of
        !          1081: a multi-register value.  Machine modes such as @code{DImode} and
        !          1082: @code{TImode} can indicate values longer than a word, values which
        !          1083: usually require two or more consecutive registers.  To access one of the
        !          1084: registers, use a @code{subreg} with mode @code{SImode} and a
        !          1085: @var{wordnum} that says which register.
        !          1086: 
        !          1087: Storing in a non-paradoxical @code{subreg} has undefined results for
        !          1088: bits belonging to the same word as the @code{subreg}.  This laxity makes
        !          1089: it easier to generate efficient code for such instructions.  To
        !          1090: represent an instruction that preserves all the bits outside of those in
        !          1091: the @code{subreg}, use @code{strict_low_part} around the @code{subreg}.
        !          1092: 
        !          1093: @cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
        !          1094: The compilation parameter @code{WORDS_BIG_ENDIAN}, if set to 1, says
        !          1095: that word number zero is the most significant part; otherwise, it is
        !          1096: the least significant part.
        !          1097: 
        !          1098: @cindex combiner pass
        !          1099: @cindex reload pass
        !          1100: @cindex @code{subreg}, special reload handling
        !          1101: Between the combiner pass and the reload pass, it is possible to have a
        !          1102: paradoxical @code{subreg} which contains a @code{mem} instead of a
        !          1103: @code{reg} as its first operand.  After the reload pass, it is also
        !          1104: possible to have a non-paradoxical @code{subreg} which contains a
        !          1105: @code{mem}; this usually occurs when the @code{mem} is a stack slot
        !          1106: which replaced a pseudo register.
        !          1107: 
        !          1108: Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
        !          1109: using a @code{subreg}.  On some machines the most significant part of a
        !          1110: @code{DFmode} value does not have the same format as a single-precision
        !          1111: floating value.
        !          1112: 
        !          1113: It is also not valid to access a single word of a multi-word value in a
        !          1114: hard register when less registers can hold the value than would be
        !          1115: expected from its size.  For example, some 32-bit machines have
        !          1116: floating-point registers that can hold an entire @code{DFmode} value.
        !          1117: If register 10 were such a register @code{(subreg:SI (reg:DF 10) 1)}
        !          1118: would be invalid because there is no way to convert that reference to
        !          1119: a single machine register.  The reload pass prevents @code{subreg}
        !          1120: expressions such as these from being formed.
        !          1121: 
        !          1122: @findex SUBREG_REG
        !          1123: @findex SUBREG_WORD
        !          1124: The first operand of a @code{subreg} expression is customarily accessed 
        !          1125: with the @code{SUBREG_REG} macro and the second operand is customarily
        !          1126: accessed with the @code{SUBREG_WORD} macro.
        !          1127: 
        !          1128: @findex scratch
        !          1129: @cindex scratch operands
        !          1130: @item (scratch:@var{m})
        !          1131: This represents a scratch register that will be required for the
        !          1132: execution of a single instruction and not used subsequently.  It is
        !          1133: converted into a @code{reg} by either the local register allocator or
        !          1134: the reload pass.
        !          1135: 
        !          1136: @code{scratch} is usually present inside a @code{clobber} operation
        !          1137: (@pxref{Side Effects}).
        !          1138: 
        !          1139: @findex cc0
        !          1140: @cindex condition code register
        !          1141: @item (cc0)
        !          1142: This refers to the machine's condition code register.  It has no
        !          1143: operands and may not have a machine mode.  There are two ways to use it:
        !          1144: 
        !          1145: @itemize @bullet
        !          1146: @item
        !          1147: To stand for a complete set of condition code flags.  This is best on
        !          1148: most machines, where each comparison sets the entire series of flags.
        !          1149: 
        !          1150: With this technique, @code{(cc0)} may be validly used in only two
        !          1151: contexts: as the destination of an assignment (in test and compare
        !          1152: instructions) and in comparison operators comparing against zero
        !          1153: (@code{const_int} with value zero; that is to say, @code{const0_rtx}).
        !          1154: 
        !          1155: @item
        !          1156: To stand for a single flag that is the result of a single condition.
        !          1157: This is useful on machines that have only a single flag bit, and in
        !          1158: which comparison instructions must specify the condition to test.
        !          1159: 
        !          1160: With this technique, @code{(cc0)} may be validly used in only two
        !          1161: contexts: as the destination of an assignment (in test and compare
        !          1162: instructions) where the source is a comparison operator, and as the
        !          1163: first operand of @code{if_then_else} (in a conditional branch).
        !          1164: @end itemize
        !          1165: 
        !          1166: @findex cc0_rtx
        !          1167: There is only one expression object of code @code{cc0}; it is the
        !          1168: value of the variable @code{cc0_rtx}.  Any attempt to create an
        !          1169: expression of code @code{cc0} will return @code{cc0_rtx}.
        !          1170: 
        !          1171: Instructions can set the condition code implicitly.  On many machines,
        !          1172: nearly all instructions set the condition code based on the value that
        !          1173: they compute or store.  It is not necessary to record these actions
        !          1174: explicitly in the RTL because the machine description includes a
        !          1175: prescription for recognizing the instructions that do so (by means of
        !          1176: the macro @code{NOTICE_UPDATE_CC}).  @xref{Condition Code}.  Only
        !          1177: instructions whose sole purpose is to set the condition code, and
        !          1178: instructions that use the condition code, need mention @code{(cc0)}.
        !          1179: 
        !          1180: On some machines, the condition code register is given a register number
        !          1181: and a @code{reg} is used instead of @code{(cc0)}.  This is usually the
        !          1182: preferable approach if only a small subset of instructions modify the
        !          1183: condition code.  Other machines store condition codes in general
        !          1184: registers; in such cases a pseudo register should be used.
        !          1185: 
        !          1186: Some machines, such as the Sparc and RS/6000, have two sets of
        !          1187: arithmetic instructions, one that sets and one that does not set the
        !          1188: condition code.  This is best handled by normally generating the
        !          1189: instruction that does not set the condition code, and making a pattern
        !          1190: that both performs the arithmetic and sets the condition code register
        !          1191: (which would not be @code{(cc0)} in this case).  For examples, search
        !          1192: for @samp{addcc} and @samp{andcc} in @file{sparc.md}.
        !          1193: 
        !          1194: @findex pc
        !          1195: @item (pc)
        !          1196: @cindex program counter
        !          1197: This represents the machine's program counter.  It has no operands and
        !          1198: may not have a machine mode.  @code{(pc)} may be validly used only in
        !          1199: certain specific contexts in jump instructions.
        !          1200: 
        !          1201: @findex pc_rtx
        !          1202: There is only one expression object of code @code{pc}; it is the value
        !          1203: of the variable @code{pc_rtx}.  Any attempt to create an expression of
        !          1204: code @code{pc} will return @code{pc_rtx}.
        !          1205: 
        !          1206: All instructions that do not jump alter the program counter implicitly
        !          1207: by incrementing it, but there is no need to mention this in the RTL.
        !          1208: 
        !          1209: @findex mem
        !          1210: @item (mem:@var{m} @var{addr})
        !          1211: This RTX represents a reference to main memory at an address
        !          1212: represented by the expression @var{addr}.  @var{m} specifies how large
        !          1213: a unit of memory is accessed.
        !          1214: @end table
        !          1215: 
        !          1216: @node Arithmetic, Comparisons, Regs and Memory, RTL
        !          1217: @section RTL Expressions for Arithmetic
        !          1218: @cindex arithmetic, in RTL
        !          1219: @cindex math, in RTL
        !          1220: @cindex RTL expressions for arithmetic
        !          1221: 
        !          1222: Unless otherwise specified, all the operands of arithmetic expressions
        !          1223: must be valid for mode @var{m}.  An operand is valid for mode @var{m}
        !          1224: if it has mode @var{m}, or if it is a @code{const_int} or
        !          1225: @code{const_double} and @var{m} is a mode of class @code{MODE_INT}.
        !          1226: 
        !          1227: For commutative binary operations, constants should be placed in the
        !          1228: second operand.
        !          1229: 
        !          1230: @table @code
        !          1231: @findex plus
        !          1232: @cindex RTL addition
        !          1233: @cindex RTL sum
        !          1234: @item (plus:@var{m} @var{x} @var{y})
        !          1235: Represents the sum of the values represented by @var{x} and @var{y}
        !          1236: carried out in machine mode @var{m}. 
        !          1237: 
        !          1238: @findex lo_sum
        !          1239: @item (lo_sum:@var{m} @var{x} @var{y})
        !          1240: Like @code{plus}, except that it represents that sum of @var{x} and the
        !          1241: low-order bits of @var{y}.  The number of low order bits is
        !          1242: machine-dependent but is normally the number of bits in a @code{Pmode}
        !          1243: item minus the number of bits set by the @code{high} code
        !          1244: (@pxref{Constants}).
        !          1245: 
        !          1246: @var{m} should be @code{Pmode}.
        !          1247: 
        !          1248: @findex minus
        !          1249: @cindex RTL subtraction
        !          1250: @cindex RTL difference
        !          1251: @item (minus:@var{m} @var{x} @var{y})
        !          1252: Like @code{plus} but represents subtraction.
        !          1253: 
        !          1254: @findex compare
        !          1255: @cindex RTL comparison
        !          1256: @item (compare:@var{m} @var{x} @var{y})
        !          1257: Represents the result of subtracting @var{y} from @var{x} for purposes
        !          1258: of comparison.  The result is computed without overflow, as if with
        !          1259: infinite precision.
        !          1260: 
        !          1261: Of course, machines can't really subtract with infinite precision.
        !          1262: However, they can pretend to do so when only the sign of the
        !          1263: result will be used, which is the case when the result is stored
        !          1264: in the condition code.   And that is the only way this kind of expression
        !          1265: may validly be used: as a value to be stored in the condition codes.
        !          1266: 
        !          1267: The mode @var{m} is not related to the modes of @var{x} and @var{y},
        !          1268: but instead is the mode of the condition code value.  If @code{(cc0)}
        !          1269: is used, it is @code{VOIDmode}.  Otherwise it is some mode in class
        !          1270: @code{MODE_CC}, often @code{CCmode}.  @xref{Condition Code}.
        !          1271: 
        !          1272: Normally, @var{x} and @var{y} must have the same mode.  Otherwise,
        !          1273: @code{compare} is valid only if the mode of @var{x} is in class
        !          1274: @code{MODE_INT} and @var{y} is a @code{const_int} or
        !          1275: @code{const_double} with mode @code{VOIDmode}.  The mode of @var{x}
        !          1276: determines what mode the comparison is to be done in; thus it must not
        !          1277: be @code{VOIDmode}.
        !          1278: 
        !          1279: If one of the operands is a constant, it should be placed in the
        !          1280: second operand and the comparison code adjusted as appropriate.  
        !          1281: 
        !          1282: A @code{compare} specifying two @code{VOIDmode} constants is not valid
        !          1283: since there is no way to know in what mode the comparison is to be
        !          1284: performed; the comparison must either be folded during the compilation
        !          1285: or the first operand must be loaded into a register while its mode is
        !          1286: still known.
        !          1287: 
        !          1288: @findex neg
        !          1289: @item (neg:@var{m} @var{x})
        !          1290: Represents the negation (subtraction from zero) of the value represented
        !          1291: by @var{x}, carried out in mode @var{m}.
        !          1292: 
        !          1293: @findex mult
        !          1294: @cindex multiplication
        !          1295: @cindex product
        !          1296: @item (mult:@var{m} @var{x} @var{y})
        !          1297: Represents the signed product of the values represented by @var{x} and
        !          1298: @var{y} carried out in machine mode @var{m}.
        !          1299: 
        !          1300: Some machines support a multiplication that generates a product wider
        !          1301: than the operands.  Write the pattern for this as
        !          1302: 
        !          1303: @example
        !          1304: (mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
        !          1305: @end example
        !          1306: 
        !          1307: where @var{m} is wider than the modes of @var{x} and @var{y}, which need
        !          1308: not be the same.
        !          1309: 
        !          1310: Write patterns for unsigned widening multiplication similarly using
        !          1311: @code{zero_extend}.
        !          1312: 
        !          1313: @findex div
        !          1314: @cindex division
        !          1315: @cindex signed division
        !          1316: @cindex quotient
        !          1317: @item (div:@var{m} @var{x} @var{y})
        !          1318: Represents the quotient in signed division of @var{x} by @var{y},
        !          1319: carried out in machine mode @var{m}.  If @var{m} is a floating point
        !          1320: mode, it represents the exact quotient; otherwise, the integerized
        !          1321: quotient.
        !          1322: 
        !          1323: Some machines have division instructions in which the operands and
        !          1324: quotient widths are not all the same; you should represent 
        !          1325: such instructions using @code{truncate} and @code{sign_extend} as in,
        !          1326: 
        !          1327: @example
        !          1328: (truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
        !          1329: @end example
        !          1330: 
        !          1331: @findex udiv
        !          1332: @cindex unsigned division
        !          1333: @cindex division
        !          1334: @item (udiv:@var{m} @var{x} @var{y})
        !          1335: Like @code{div} but represents unsigned division.
        !          1336: 
        !          1337: @findex mod
        !          1338: @findex umod
        !          1339: @cindex remainder
        !          1340: @cindex division
        !          1341: @item (mod:@var{m} @var{x} @var{y})
        !          1342: @itemx (umod:@var{m} @var{x} @var{y})
        !          1343: Like @code{div} and @code{udiv} but represent the remainder instead of
        !          1344: the quotient.
        !          1345: 
        !          1346: @findex smin
        !          1347: @findex smax
        !          1348: @cindex signed minimum
        !          1349: @cindex signed maximum
        !          1350: @item (smin:@var{m} @var{x} @var{y})
        !          1351: @itemx (smax:@var{m} @var{x} @var{y})
        !          1352: Represents the smaller (for @code{smin}) or larger (for @code{smax}) of
        !          1353: @var{x} and @var{y}, interpreted as signed integers in mode @var{m}.
        !          1354: 
        !          1355: @findex umin
        !          1356: @findex umax
        !          1357: @cindex unsigned minimum and maximum
        !          1358: @item (umin:@var{m} @var{x} @var{y})
        !          1359: @itemx (umax:@var{m} @var{x} @var{y})
        !          1360: Like @code{smin} and @code{smax}, but the values are interpreted as unsigned
        !          1361: integers.
        !          1362: 
        !          1363: @findex not
        !          1364: @cindex complement, bitwise
        !          1365: @cindex bitwise complement
        !          1366: @item (not:@var{m} @var{x})
        !          1367: Represents the bitwise complement of the value represented by @var{x},
        !          1368: carried out in mode @var{m}, which must be a fixed-point machine mode.
        !          1369: 
        !          1370: @findex and
        !          1371: @cindex logical-and, bitwise
        !          1372: @cindex bitwise logical-and
        !          1373: @item (and:@var{m} @var{x} @var{y})
        !          1374: Represents the bitwise logical-and of the values represented by
        !          1375: @var{x} and @var{y}, carried out in machine mode @var{m}, which must be
        !          1376: a fixed-point machine mode.
        !          1377: 
        !          1378: @findex ior
        !          1379: @cindex inclusive-or, bitwise
        !          1380: @cindex bitwise inclusive-or
        !          1381: @item (ior:@var{m} @var{x} @var{y})
        !          1382: Represents the bitwise inclusive-or of the values represented by @var{x}
        !          1383: and @var{y}, carried out in machine mode @var{m}, which must be a
        !          1384: fixed-point mode.
        !          1385: 
        !          1386: @findex xor
        !          1387: @cindex exclusive-or, bitwise
        !          1388: @cindex bitwise exclusive-or
        !          1389: @item (xor:@var{m} @var{x} @var{y})
        !          1390: Represents the bitwise exclusive-or of the values represented by @var{x}
        !          1391: and @var{y}, carried out in machine mode @var{m}, which must be a
        !          1392: fixed-point mode.
        !          1393: 
        !          1394: @findex ashift
        !          1395: @cindex left shift
        !          1396: @cindex shift
        !          1397: @cindex arithmetic shift
        !          1398: @item (ashift:@var{m} @var{x} @var{c})
        !          1399: Represents the result of arithmetically shifting @var{x} left by @var{c}
        !          1400: places.  @var{x} have mode @var{m}, a fixed-point machine mode.  @var{c}
        !          1401: be a fixed-point mode or be a constant with mode @code{VOIDmode}; which
        !          1402: mode is determined by the mode called for in the machine description
        !          1403: entry for the left-shift instruction.  For example, on the Vax, the mode
        !          1404: of @var{c} is @code{QImode} regardless of @var{m}.
        !          1405: 
        !          1406: @findex lshift
        !          1407: @cindex left shift
        !          1408: @cindex logical shift
        !          1409: @item (lshift:@var{m} @var{x} @var{c})
        !          1410: Like @code{ashift} but for logical left shift.  @code{ashift} and
        !          1411: @code{lshift} are identical operations; we customarily use @code{ashift}
        !          1412: for both.
        !          1413: 
        !          1414: @findex lshiftrt
        !          1415: @cindex right shift
        !          1416: @findex ashiftrt
        !          1417: @item (lshiftrt:@var{m} @var{x} @var{c})
        !          1418: @itemx (ashiftrt:@var{m} @var{x} @var{c})
        !          1419: Like @code{lshift} and @code{ashift} but for right shift.  Unlike
        !          1420: the case for left shift, these two operations are distinct.
        !          1421: 
        !          1422: @findex rotate
        !          1423: @cindex rotate 
        !          1424: @cindex left rotate
        !          1425: @findex rotatert
        !          1426: @cindex right rotate
        !          1427: @item (rotate:@var{m} @var{x} @var{c})
        !          1428: @itemx (rotatert:@var{m} @var{x} @var{c})
        !          1429: Similar but represent left and right rotate.  If @var{c} is a constant,
        !          1430: use @code{rotate}.
        !          1431: 
        !          1432: @findex abs
        !          1433: @cindex absolute value
        !          1434: @item (abs:@var{m} @var{x})
        !          1435: Represents the absolute value of @var{x}, computed in mode @var{m}.
        !          1436: 
        !          1437: @findex sqrt
        !          1438: @cindex square root
        !          1439: @item (sqrt:@var{m} @var{x})
        !          1440: Represents the square root of @var{x}, computed in mode @var{m}.
        !          1441: Most often @var{m} will be a floating point mode.
        !          1442: 
        !          1443: @findex ffs
        !          1444: @item (ffs:@var{m} @var{x})
        !          1445: Represents one plus the index of the least significant 1-bit in
        !          1446: @var{x}, represented as an integer of mode @var{m}.  (The value is
        !          1447: zero if @var{x} is zero.)  The mode of @var{x} need not be @var{m};
        !          1448: depending on the target machine, various mode combinations may be
        !          1449: valid.
        !          1450: @end table
        !          1451: 
        !          1452: @node Comparisons, Bit Fields, Arithmetic, RTL
        !          1453: @section Comparison Operations
        !          1454: @cindex RTL comparison operations
        !          1455: 
        !          1456: Comparison operators test a relation on two operands and are considered
        !          1457: to represent a machine-dependent nonzero value described by, but not
        !          1458: necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
        !          1459: if the relation holds, or zero if it does not.  The mode of the
        !          1460: comparison operation is independent of the mode of the data being
        !          1461: compared.  If the comparison operation is being tested (e.g., the first
        !          1462: operand of an @code{if_then_else}), the mode must be @code{VOIDmode}.
        !          1463: If the comparison operation is producing data to be stored in some
        !          1464: variable, the mode must be in class @code{MODE_INT}.  All comparison
        !          1465: operations producing data must use the same mode, which is
        !          1466: machine-specific.
        !          1467: 
        !          1468: @cindex condition codes
        !          1469: There are two ways that comparison operations may be used.  The
        !          1470: comparison operators may be used to compare the condition codes
        !          1471: @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}.  Such
        !          1472: a construct actually refers to the result of the preceding instruction
        !          1473: in which the condition codes were set.  The instructing setting the
        !          1474: condition code must be adjacent to the instruction using the condition
        !          1475: code; only @code{note} insns may separate them.
        !          1476: 
        !          1477: Alternatively, a comparison operation may directly compare two data
        !          1478: objects.  The mode of the comparison is determined by the operands; they
        !          1479: must both be valid for a common machine mode.  A comparison with both
        !          1480: operands constant would be invalid as the machine mode could not be
        !          1481: deduced from it, but such a comparison should never exist in RTL due to
        !          1482: constant folding.
        !          1483: 
        !          1484: In the example above, if @code{(cc0)} were last set to
        !          1485: @code{(compare @var{x} @var{y})}, the comparison operation is
        !          1486: identical to @code{(eq @var{x} @var{y})}.  Usually only one style
        !          1487: of comparisons is supported on a particular machine, but the combine
        !          1488: pass will try to merge the operations to produce the @code{eq} shown
        !          1489: in case it exists in the context of the particular insn involved.
        !          1490: 
        !          1491: Inequality comparisons come in two flavors, signed and unsigned.  Thus,
        !          1492: there are distinct expression codes @code{gt} and @code{gtu} for signed and
        !          1493: unsigned greater-than.  These can produce different results for the same
        !          1494: pair of integer values: for example, 1 is signed greater-than -1 but not
        !          1495: unsigned greater-than, because -1 when regarded as unsigned is actually
        !          1496: @code{0xffffffff} which is greater than 1.
        !          1497: 
        !          1498: The signed comparisons are also used for floating point values.  Floating
        !          1499: point comparisons are distinguished by the machine modes of the operands.
        !          1500: 
        !          1501: @table @code
        !          1502: @findex eq
        !          1503: @cindex equal
        !          1504: @item (eq:@var{m} @var{x} @var{y})
        !          1505: 1 if the values represented by @var{x} and @var{y} are equal,
        !          1506: otherwise 0.
        !          1507: 
        !          1508: @findex ne
        !          1509: @cindex not equal
        !          1510: @item (ne:@var{m} @var{x} @var{y})
        !          1511: 1 if the values represented by @var{x} and @var{y} are not equal,
        !          1512: otherwise 0.
        !          1513: 
        !          1514: @findex gt
        !          1515: @cindex greater than
        !          1516: @item (gt:@var{m} @var{x} @var{y})
        !          1517: 1 if the @var{x} is greater than @var{y}.  If they are fixed-point,
        !          1518: the comparison is done in a signed sense.
        !          1519: 
        !          1520: @findex gtu
        !          1521: @cindex greater than
        !          1522: @cindex unsigned greater than
        !          1523: @item (gtu:@var{m} @var{x} @var{y})
        !          1524: Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
        !          1525: 
        !          1526: @findex lt
        !          1527: @cindex less than
        !          1528: @findex ltu
        !          1529: @cindex unsigned less than
        !          1530: @item (lt:@var{m} @var{x} @var{y})
        !          1531: @itemx (ltu:@var{m} @var{x} @var{y})
        !          1532: Like @code{gt} and @code{gtu} but test for ``less than''.
        !          1533: 
        !          1534: @findex ge
        !          1535: @cindex greater than
        !          1536: @findex geu
        !          1537: @cindex unsigned greater than
        !          1538: @item (ge:@var{m} @var{x} @var{y})
        !          1539: @itemx (geu:@var{m} @var{x} @var{y})
        !          1540: Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
        !          1541: 
        !          1542: @findex le
        !          1543: @cindex less than or equal
        !          1544: @findex leu
        !          1545: @cindex unsigned less than
        !          1546: @item (le:@var{m} @var{x} @var{y})
        !          1547: @itemx (leu:@var{m} @var{x} @var{y})
        !          1548: Like @code{gt} and @code{gtu} but test for ``less than or equal''.
        !          1549: 
        !          1550: @findex if_then_else
        !          1551: @item (if_then_else @var{cond} @var{then} @var{else})
        !          1552: This is not a comparison operation but is listed here because it is
        !          1553: always used in conjunction with a comparison operation.  To be
        !          1554: precise, @var{cond} is a comparison expression.  This expression
        !          1555: represents a choice, according to @var{cond}, between the value
        !          1556: represented by @var{then} and the one represented by @var{else}.
        !          1557: 
        !          1558: On most machines, @code{if_then_else} expressions are valid only
        !          1559: to express conditional jumps.
        !          1560: 
        !          1561: @findex cond
        !          1562: @item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
        !          1563: Similar to @code{if_then_else}, but more general.  Each of @var{test1},
        !          1564: @var{test2}, @dots{} is performed in turn.  The result of this expression is
        !          1565: the @var{value} corresponding to the first non-zero test, or @var{default} if
        !          1566: none of the tests are non-zero expressions.
        !          1567: 
        !          1568: This is currently not valid for instruction patterns and is supported only
        !          1569: for insn attributes.  @xref{Insn Attributes}.
        !          1570: @end table
        !          1571: 
        !          1572: @node Bit Fields, Conversions, Comparisons, RTL
        !          1573: @section Bit Fields
        !          1574: @cindex bit fields
        !          1575: 
        !          1576: Special expression codes exist to represent bitfield instructions.
        !          1577: These types of expressions are lvalues in RTL; they may appear
        !          1578: on the left side of an assignment, indicating insertion of a value
        !          1579: into the specified bit field.
        !          1580: 
        !          1581: @table @code
        !          1582: @findex sign_extract
        !          1583: @cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
        !          1584: @item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
        !          1585: This represents a reference to a sign-extended bit field contained or
        !          1586: starting in @var{loc} (a memory or register reference).  The bit field
        !          1587: is @var{size} bits wide and starts at bit @var{pos}.  The compilation
        !          1588: option @code{BITS_BIG_ENDIAN} says which end of the memory unit
        !          1589: @var{pos} counts from.
        !          1590: 
        !          1591: If @var{loc} is in memory, its mode must be a single-byte integer mode.
        !          1592: If @var{loc} is in a register, the mode to use is specified by the
        !          1593: operand of the @code{insv} or @code{extv} pattern
        !          1594: (@pxref{Standard Names}) and is usually a full-word integer mode.
        !          1595: 
        !          1596: The mode of @var{pos} is machine-specific and is also specified
        !          1597: in the @code{insv} or @code{extv} pattern.
        !          1598: 
        !          1599: The mode @var{m} is the same as the mode that would be used for
        !          1600: @var{loc} if it were a register.
        !          1601: 
        !          1602: @findex zero_extract
        !          1603: @item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
        !          1604: Like @code{sign_extract} but refers to an unsigned or zero-extended
        !          1605: bit field.  The same sequence of bits are extracted, but they
        !          1606: are filled to an entire word with zeros instead of by sign-extension.
        !          1607: @end table
        !          1608: 
        !          1609: @node Conversions, RTL Declarations, Bit Fields, RTL
        !          1610: @section Conversions
        !          1611: @cindex conversions
        !          1612: @cindex machine mode conversions
        !          1613: 
        !          1614: All conversions between machine modes must be represented by
        !          1615: explicit conversion operations.  For example, an expression
        !          1616: which is the sum of a byte and a full word cannot be written as
        !          1617: @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
        !          1618: operation requires two operands of the same machine mode.
        !          1619: Therefore, the byte-sized operand is enclosed in a conversion
        !          1620: operation, as in
        !          1621: 
        !          1622: @example
        !          1623: (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
        !          1624: @end example
        !          1625: 
        !          1626: The conversion operation is not a mere placeholder, because there
        !          1627: may be more than one way of converting from a given starting mode
        !          1628: to the desired final mode.  The conversion operation code says how
        !          1629: to do it.
        !          1630: 
        !          1631: For all conversion operations, @var{x} must not be @code{VOIDmode}
        !          1632: because the mode in which to do the conversion would not be known.
        !          1633: The conversion must either be done at compile-time or @var{x}
        !          1634: must be placed into a register.
        !          1635: 
        !          1636: @table @code
        !          1637: @findex sign_extend
        !          1638: @item (sign_extend:@var{m} @var{x})
        !          1639: Represents the result of sign-extending the value @var{x}
        !          1640: to machine mode @var{m}.  @var{m} must be a fixed-point mode
        !          1641: and @var{x} a fixed-point value of a mode narrower than @var{m}.
        !          1642: 
        !          1643: @findex zero_extend
        !          1644: @item (zero_extend:@var{m} @var{x})
        !          1645: Represents the result of zero-extending the value @var{x}
        !          1646: to machine mode @var{m}.  @var{m} must be a fixed-point mode
        !          1647: and @var{x} a fixed-point value of a mode narrower than @var{m}.
        !          1648: 
        !          1649: @findex float_extend
        !          1650: @item (float_extend:@var{m} @var{x})
        !          1651: Represents the result of extending the value @var{x}
        !          1652: to machine mode @var{m}.  @var{m} must be a floating point mode
        !          1653: and @var{x} a floating point value of a mode narrower than @var{m}.
        !          1654: 
        !          1655: @findex truncate
        !          1656: @item (truncate:@var{m} @var{x})
        !          1657: Represents the result of truncating the value @var{x}
        !          1658: to machine mode @var{m}.  @var{m} must be a fixed-point mode
        !          1659: and @var{x} a fixed-point value of a mode wider than @var{m}.
        !          1660: 
        !          1661: @findex float_truncate
        !          1662: @item (float_truncate:@var{m} @var{x})
        !          1663: Represents the result of truncating the value @var{x}
        !          1664: to machine mode @var{m}.  @var{m} must be a floating point mode
        !          1665: and @var{x} a floating point value of a mode wider than @var{m}.
        !          1666: 
        !          1667: @findex float
        !          1668: @item (float:@var{m} @var{x})
        !          1669: Represents the result of converting fixed point value @var{x},
        !          1670: regarded as signed, to floating point mode @var{m}.
        !          1671: 
        !          1672: @findex unsigned_float
        !          1673: @item (unsigned_float:@var{m} @var{x})
        !          1674: Represents the result of converting fixed point value @var{x},
        !          1675: regarded as unsigned, to floating point mode @var{m}.
        !          1676: 
        !          1677: @findex fix
        !          1678: @item (fix:@var{m} @var{x})
        !          1679: When @var{m} is a fixed point mode, represents the result of
        !          1680: converting floating point value @var{x} to mode @var{m}, regarded as
        !          1681: signed.  How rounding is done is not specified, so this operation may
        !          1682: be used validly in compiling C code only for integer-valued operands.
        !          1683: 
        !          1684: @findex unsigned_fix
        !          1685: @item (unsigned_fix:@var{m} @var{x})
        !          1686: Represents the result of converting floating point value @var{x} to
        !          1687: fixed point mode @var{m}, regarded as unsigned.  How rounding is done
        !          1688: is not specified.
        !          1689: 
        !          1690: @findex fix
        !          1691: @item (fix:@var{m} @var{x})
        !          1692: When @var{m} is a floating point mode, represents the result of
        !          1693: converting floating point value @var{x} (valid for mode @var{m}) to an
        !          1694: integer, still represented in floating point mode @var{m}, by rounding
        !          1695: towards zero.
        !          1696: @end table
        !          1697: 
        !          1698: @node RTL Declarations, Side Effects, Conversions, RTL
        !          1699: @section Declarations
        !          1700: @cindex RTL declarations
        !          1701: @cindex declarations, RTL
        !          1702: 
        !          1703: Declaration expression codes do not represent arithmetic operations
        !          1704: but rather state assertions about their operands.
        !          1705: 
        !          1706: @table @code
        !          1707: @findex strict_low_part
        !          1708: @cindex @code{subreg}, in @code{strict_low_part}
        !          1709: @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
        !          1710: This expression code is used in only one context: as the destination operand of a
        !          1711: @code{set} expression.  In addition, the operand of this expression
        !          1712: must be a non-paradoxical @code{subreg} expression.
        !          1713: 
        !          1714: The presence of @code{strict_low_part} says that the part of the
        !          1715: register which is meaningful in mode @var{n}, but is not part of
        !          1716: mode @var{m}, is not to be altered.  Normally, an assignment to such
        !          1717: a subreg is allowed to have undefined effects on the rest of the
        !          1718: register when @var{m} is less than a word.
        !          1719: @end table
        !          1720: 
        !          1721: @node Side Effects, Incdec, RTL Declarations, RTL
        !          1722: @section Side Effect Expressions
        !          1723: @cindex RTL side effect expressions
        !          1724: 
        !          1725: The expression codes described so far represent values, not actions.
        !          1726: But machine instructions never produce values; they are meaningful
        !          1727: only for their side effects on the state of the machine.  Special
        !          1728: expression codes are used to represent side effects.
        !          1729: 
        !          1730: The body of an instruction is always one of these side effect codes;
        !          1731: the codes described above, which represent values, appear only as
        !          1732: the operands of these.
        !          1733: 
        !          1734: @table @code
        !          1735: @findex set
        !          1736: @item (set @var{lval} @var{x})
        !          1737: Represents the action of storing the value of @var{x} into the place
        !          1738: represented by @var{lval}.  @var{lval} must be an expression
        !          1739: representing a place that can be stored in: @code{reg} (or
        !          1740: @code{subreg} or @code{strict_low_part}), @code{mem}, @code{pc} or
        !          1741: @code{cc0}.@refill
        !          1742: 
        !          1743: If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
        !          1744: machine mode; then @var{x} must be valid for that mode.@refill
        !          1745: 
        !          1746: If @var{lval} is a @code{reg} whose machine mode is less than the full
        !          1747: width of the register, then it means that the part of the register
        !          1748: specified by the machine mode is given the specified value and the
        !          1749: rest of the register receives an undefined value.  Likewise, if
        !          1750: @var{lval} is a @code{subreg} whose machine mode is narrower than
        !          1751: the mode of the register, the rest of the register can be changed in
        !          1752: an undefined way.
        !          1753: 
        !          1754: If @var{lval} is a @code{strict_low_part} of a @code{subreg}, then the
        !          1755: part of the register specified by the machine mode of the
        !          1756: @code{subreg} is given the value @var{x} and the rest of the register
        !          1757: is not changed.@refill
        !          1758: 
        !          1759: If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
        !          1760: be either a @code{compare} expression or a value that may have any mode.
        !          1761: The latter case represents a ``test'' instruction.  The expression
        !          1762: @code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to
        !          1763: @code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}.
        !          1764: Use the former expression to save space during the compilation.
        !          1765: 
        !          1766: @cindex jump instructions and @code{set}
        !          1767: @cindex @code{if_then_else} usage
        !          1768: If @var{lval} is @code{(pc)}, we have a jump instruction, and the
        !          1769: possibilities for @var{x} are very limited.  It may be a
        !          1770: @code{label_ref} expression (unconditional jump).  It may be an
        !          1771: @code{if_then_else} (conditional jump), in which case either the
        !          1772: second or the third operand must be @code{(pc)} (for the case which
        !          1773: does not jump) and the other of the two must be a @code{label_ref}
        !          1774: (for the case which does jump).  @var{x} may also be a @code{mem} or
        !          1775: @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
        !          1776: @code{mem}; these unusual patterns are used to represent jumps through
        !          1777: branch tables.@refill
        !          1778: 
        !          1779: If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of
        !          1780: @var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
        !          1781: valid for the mode of @var{lval}.
        !          1782: 
        !          1783: @findex SET_DEST
        !          1784: @findex SET_SRC
        !          1785: @var{lval} is customarily accessed with the @code{SET_DEST} macro and 
        !          1786: @var{x} with the @code{SET_SRC} macro.
        !          1787: 
        !          1788: @findex return
        !          1789: @item (return)
        !          1790: As the sole expression in a pattern, represents a return from the
        !          1791: current function, on machines where this can be done with one
        !          1792: instruction, such as Vaxes.  On machines where a multi-instruction
        !          1793: ``epilogue'' must be executed in order to return from the function,
        !          1794: returning is done by jumping to a label which precedes the epilogue, and
        !          1795: the @code{return} expression code is never used.
        !          1796: 
        !          1797: Inside an @code{if_then_else} expression, represents the value to be
        !          1798: placed in @code{pc} to return to the caller.
        !          1799: 
        !          1800: Note that an insn pattern of @code{(return)} is logically equivalent to
        !          1801: @code{(set (pc) (return))}, but the latter form is never used.
        !          1802: 
        !          1803: @findex call
        !          1804: @item (call @var{function} @var{nargs})
        !          1805: Represents a function call.  @var{function} is a @code{mem} expression
        !          1806: whose address is the address of the function to be called.
        !          1807: @var{nargs} is an expression which can be used for two purposes: on
        !          1808: some machines it represents the number of bytes of stack argument; on
        !          1809: others, it represents the number of argument registers.
        !          1810: 
        !          1811: Each machine has a standard machine mode which @var{function} must
        !          1812: have.  The machine description defines macro @code{FUNCTION_MODE} to
        !          1813: expand into the requisite mode name.  The purpose of this mode is to
        !          1814: specify what kind of addressing is allowed, on machines where the
        !          1815: allowed kinds of addressing depend on the machine mode being
        !          1816: addressed.
        !          1817: 
        !          1818: @findex clobber
        !          1819: @item (clobber @var{x})
        !          1820: Represents the storing or possible storing of an unpredictable,
        !          1821: undescribed value into @var{x}, which must be a @code{reg},
        !          1822: @code{scratch} or @code{mem} expression.
        !          1823: 
        !          1824: One place this is used is in string instructions that store standard
        !          1825: values into particular hard registers.  It may not be worth the
        !          1826: trouble to describe the values that are stored, but it is essential to
        !          1827: inform the compiler that the registers will be altered, lest it
        !          1828: attempt to keep data in them across the string instruction.
        !          1829: 
        !          1830: If @var{x} is @code{(mem:BLK (const_int 0))}, it means that all memory
        !          1831: locations must be presumed clobbered.
        !          1832: 
        !          1833: Note that the machine description classifies certain hard registers as
        !          1834: ``call-clobbered''.  All function call instructions are assumed by
        !          1835: default to clobber these registers, so there is no need to use
        !          1836: @code{clobber} expressions to indicate this fact.  Also, each function
        !          1837: call is assumed to have the potential to alter any memory location,
        !          1838: unless the function is declared @code{const}.
        !          1839: 
        !          1840: If the last group of expressions in a @code{parallel} are each a
        !          1841: @code{clobber} expression whose arguments are @code{reg} or
        !          1842: @code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
        !          1843: phase can add the appropriate @code{clobber} expressions to an insn it
        !          1844: has constructed when doing so will cause a pattern to be matched.
        !          1845: 
        !          1846: This feature can be used, for example, on a machine that whose multiply
        !          1847: and add instructions don't use an MQ register but which has an
        !          1848: add-accumulate instruction that does clobber the MQ register.  Similarly,
        !          1849: a combined instruction might require a temporary register while the
        !          1850: constituent instructions might not.
        !          1851: 
        !          1852: When a @code{clobber} expression for a register appears inside a
        !          1853: @code{parallel} with other side effects, the register allocator
        !          1854: guarantees that the register is unoccupied both before and after that
        !          1855: insn.  However, the reload phase may allocate a register used for one of
        !          1856: the inputs unless the @samp{&} constraint is specified for the selected
        !          1857: alternative (@pxref{Modifiers}).  You can clobber either a specific hard
        !          1858: register, a pseudo register, or a @code{scratch} expression; in the
        !          1859: latter two cases, GNU CC will allocate a hard register that is available
        !          1860: there for use as a temporary.
        !          1861: 
        !          1862: For instructions that require a temporary register, you should use
        !          1863: @code{scratch} instead of a pseudo-register because this will allow the
        !          1864: combiner phase to add the @code{clobber} when required.  You do this by
        !          1865: coding (@code{clobber} (@code{match_scratch} @dots{})).  If you do
        !          1866: clobber a pseudo register, use one which appears nowhere else---generate
        !          1867: a new one each time.  Otherwise, you may confuse CSE.
        !          1868: 
        !          1869: There is one other known use for clobbering a pseudo register in a
        !          1870: @code{parallel}: when one of the input operands of the insn is also
        !          1871: clobbered by the insn.  In this case, using the same pseudo register in
        !          1872: the clobber and elsewhere in the insn produces the expected results.
        !          1873: 
        !          1874: @findex use
        !          1875: @item (use @var{x})
        !          1876: Represents the use of the value of @var{x}.  It indicates that the
        !          1877: value in @var{x} at this point in the program is needed, even though
        !          1878: it may not be apparent why this is so.  Therefore, the compiler will
        !          1879: not attempt to delete previous instructions whose only effect is to
        !          1880: store a value in @var{x}.  @var{x} must be a @code{reg} expression.
        !          1881: 
        !          1882: During the delayed branch scheduling phase, @var{x} may be an insn.
        !          1883: This indicates that @var{x} previously was located at this place in the
        !          1884: code and its data dependencies need to be taken into account.  These
        !          1885: @code{use} insns will be deleted before the delayed branch scheduling
        !          1886: phase exits.
        !          1887: 
        !          1888: @findex parallel
        !          1889: @item (parallel [@var{x0} @var{x1} @dots{}])
        !          1890: Represents several side effects performed in parallel.  The square
        !          1891: brackets stand for a vector; the operand of @code{parallel} is a
        !          1892: vector of expressions.  @var{x0}, @var{x1} and so on are individual
        !          1893: side effect expressions---expressions of code @code{set}, @code{call},
        !          1894: @code{return}, @code{clobber} or @code{use}.@refill
        !          1895: 
        !          1896: ``In parallel'' means that first all the values used in the individual
        !          1897: side-effects are computed, and second all the actual side-effects are
        !          1898: performed.  For example,
        !          1899: 
        !          1900: @example
        !          1901: (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
        !          1902:            (set (mem:SI (reg:SI 1)) (reg:SI 1))])
        !          1903: @end example
        !          1904: 
        !          1905: @noindent
        !          1906: says unambiguously that the values of hard register 1 and the memory
        !          1907: location addressed by it are interchanged.  In both places where
        !          1908: @code{(reg:SI 1)} appears as a memory address it refers to the value
        !          1909: in register 1 @emph{before} the execution of the insn.
        !          1910: 
        !          1911: It follows that it is @emph{incorrect} to use @code{parallel} and
        !          1912: expect the result of one @code{set} to be available for the next one.
        !          1913: For example, people sometimes attempt to represent a jump-if-zero
        !          1914: instruction this way:
        !          1915: 
        !          1916: @example
        !          1917: (parallel [(set (cc0) (reg:SI 34))
        !          1918:            (set (pc) (if_then_else
        !          1919:                         (eq (cc0) (const_int 0))
        !          1920:                         (label_ref @dots{})
        !          1921:                         (pc)))])
        !          1922: @end example
        !          1923: 
        !          1924: @noindent
        !          1925: But this is incorrect, because it says that the jump condition depends
        !          1926: on the condition code value @emph{before} this instruction, not on the
        !          1927: new value that is set by this instruction.
        !          1928: 
        !          1929: @cindex peephole optimization, RTL representation
        !          1930: Peephole optimization, which takes place together with final assembly
        !          1931: code output, can produce insns whose patterns consist of a @code{parallel}
        !          1932: whose elements are the operands needed to output the resulting
        !          1933: assembler code---often @code{reg}, @code{mem} or constant expressions.
        !          1934: This would not be well-formed RTL at any other stage in compilation,
        !          1935: but it is ok then because no further optimization remains to be done.
        !          1936: However, the definition of the macro @code{NOTICE_UPDATE_CC}, if
        !          1937: any, must deal with such insns if you define any peephole optimizations.
        !          1938: 
        !          1939: @findex sequence
        !          1940: @item (sequence [@var{insns} @dots{}])
        !          1941: Represents a sequence of insns.  Each of the @var{insns} that appears
        !          1942: in the vector is suitable for appearing in the chain of insns, so it
        !          1943: must be an @code{insn}, @code{jump_insn}, @code{call_insn},
        !          1944: @code{code_label}, @code{barrier} or @code{note}.
        !          1945: 
        !          1946: A @code{sequence} RTX is never placed in an actual insn during RTL
        !          1947: generation.  It represents the sequence of insns that result from a
        !          1948: @code{define_expand} @emph{before} those insns are passed to
        !          1949: @code{emit_insn} to insert them in the chain of insns.  When actually
        !          1950: inserted, the individual sub-insns are separated out and the
        !          1951: @code{sequence} is forgotten.
        !          1952: 
        !          1953: After delay-slot scheduling is completed, an insn and all the insns that
        !          1954: reside in its delay slots are grouped together into a @code{sequence}.
        !          1955: The insn requiring the delay slot is the first insn in the vector;
        !          1956: subsequent insns are to be placed in the delay slot.
        !          1957: 
        !          1958: @code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
        !          1959: indicate that a branch insn should be used that will conditionally annul
        !          1960: the effect of the insns in the delay slots.  In such a case,
        !          1961: @code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
        !          1962: the branch and should be executed only if the branch is taken; otherwise
        !          1963: the insn should be executed only if the branch is not taken.
        !          1964: @xref{Delay Slots}.
        !          1965: @end table
        !          1966: 
        !          1967: These expression codes appear in place of a side effect, as the body of
        !          1968: an insn, though strictly speaking they do not always describe side
        !          1969: effects as such:
        !          1970: 
        !          1971: @table @code
        !          1972: @findex asm_input
        !          1973: @item (asm_input @var{s})
        !          1974: Represents literal assembler code as described by the string @var{s}.
        !          1975: 
        !          1976: @findex unspec
        !          1977: @findex unspec_volatile
        !          1978: @item (unspec [@var{operands} @dots{}] @var{index})
        !          1979: @itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
        !          1980: Represents a machine-specific operation on @var{operands}.  @var{index}
        !          1981: selects between multiple machine-specific operations.
        !          1982: @code{unspec_volatile} is used for volatile operations and operations
        !          1983: that may trap; @code{unspec} is used for other operations.
        !          1984: 
        !          1985: These codes may appear inside a @code{pattern} of an
        !          1986: insn, inside a @code{parallel}, or inside an expression.
        !          1987: 
        !          1988: @findex addr_vec
        !          1989: @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
        !          1990: Represents a table of jump addresses.  The vector elements @var{lr0},
        !          1991: etc., are @code{label_ref} expressions.  The mode @var{m} specifies
        !          1992: how much space is given to each address; normally @var{m} would be
        !          1993: @code{Pmode}.
        !          1994: 
        !          1995: @findex addr_diff_vec
        !          1996: @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}])
        !          1997: Represents a table of jump addresses expressed as offsets from
        !          1998: @var{base}.  The vector elements @var{lr0}, etc., are @code{label_ref}
        !          1999: expressions and so is @var{base}.  The mode @var{m} specifies how much
        !          2000: space is given to each address-difference.@refill
        !          2001: @end table
        !          2002: 
        !          2003: @node Incdec, Assembler, Side Effects, RTL
        !          2004: @section Embedded Side-Effects on Addresses
        !          2005: @cindex RTL preincrement
        !          2006: @cindex RTL postincrement
        !          2007: @cindex RTL predecrement
        !          2008: @cindex RTL postdecrement
        !          2009: 
        !          2010: Four special side-effect expression codes appear as memory addresses.
        !          2011: 
        !          2012: @table @code
        !          2013: @findex pre_dec
        !          2014: @item (pre_dec:@var{m} @var{x})
        !          2015: Represents the side effect of decrementing @var{x} by a standard
        !          2016: amount and represents also the value that @var{x} has after being
        !          2017: decremented.  @var{x} must be a @code{reg} or @code{mem}, but most
        !          2018: machines allow only a @code{reg}.  @var{m} must be the machine mode
        !          2019: for pointers on the machine in use.  The amount @var{x} is decremented
        !          2020: by is the length in bytes of the machine mode of the containing memory
        !          2021: reference of which this expression serves as the address.  Here is an
        !          2022: example of its use:@refill
        !          2023: 
        !          2024: @example
        !          2025: (mem:DF (pre_dec:SI (reg:SI 39)))
        !          2026: @end example
        !          2027: 
        !          2028: @noindent
        !          2029: This says to decrement pseudo register 39 by the length of a @code{DFmode}
        !          2030: value and use the result to address a @code{DFmode} value.
        !          2031: 
        !          2032: @findex pre_inc
        !          2033: @item (pre_inc:@var{m} @var{x})
        !          2034: Similar, but specifies incrementing @var{x} instead of decrementing it.
        !          2035: 
        !          2036: @findex post_dec
        !          2037: @item (post_dec:@var{m} @var{x})
        !          2038: Represents the same side effect as @code{pre_dec} but a different
        !          2039: value.  The value represented here is the value @var{x} has @i{before}
        !          2040: being decremented.
        !          2041: 
        !          2042: @findex post_inc
        !          2043: @item (post_inc:@var{m} @var{x})
        !          2044: Similar, but specifies incrementing @var{x} instead of decrementing it.
        !          2045: @end table
        !          2046: 
        !          2047: These embedded side effect expressions must be used with care.  Instruction
        !          2048: patterns may not use them.  Until the @samp{flow} pass of the compiler,
        !          2049: they may occur only to represent pushes onto the stack.  The @samp{flow}
        !          2050: pass finds cases where registers are incremented or decremented in one
        !          2051: instruction and used as an address shortly before or after; these cases are
        !          2052: then transformed to use pre- or post-increment or -decrement.
        !          2053: 
        !          2054: If a register used as the operand of these expressions is used in
        !          2055: another address in an insn, the original value of the register is used.
        !          2056: Uses of the register outside of an address are not permitted within the
        !          2057: same insn as a use in an embedded side effect expression because such
        !          2058: insns behave differently on different machines and hence must be treated
        !          2059: as ambiguous and disallowed.
        !          2060: 
        !          2061: An instruction that can be represented with an embedded side effect
        !          2062: could also be represented using @code{parallel} containing an additional
        !          2063: @code{set} to describe how the address register is altered.  This is not
        !          2064: done because machines that allow these operations at all typically
        !          2065: allow them wherever a memory address is called for.  Describing them as
        !          2066: additional parallel stores would require doubling the number of entries
        !          2067: in the machine description.
        !          2068: 
        !          2069: @node Assembler, Insns, Incdec, RTL
        !          2070: @section Assembler Instructions as Expressions
        !          2071: @cindex assembler instructions in RTL
        !          2072: 
        !          2073: @cindex @code{asm_operands}, usage
        !          2074: The RTX code @code{asm_operands} represents a value produced by a
        !          2075: user-specified assembler instruction.  It is used to represent
        !          2076: an @code{asm} statement with arguments.  An @code{asm} statement with
        !          2077: a single output operand, like this:
        !          2078: 
        !          2079: @smallexample
        !          2080: asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
        !          2081: @end smallexample
        !          2082: 
        !          2083: @noindent
        !          2084: is represented using a single @code{asm_operands} RTX which represents
        !          2085: the value that is stored in @code{outputvar}:
        !          2086: 
        !          2087: @smallexample
        !          2088: (set @var{rtx-for-outputvar}
        !          2089:      (asm_operands "foo %1,%2,%0" "a" 0
        !          2090:                    [@var{rtx-for-addition-result} @var{rtx-for-*z}]
        !          2091:                    [(asm_input:@var{m1} "g")
        !          2092:                     (asm_input:@var{m2} "di")]))
        !          2093: @end smallexample
        !          2094: 
        !          2095: @noindent
        !          2096: Here the operands of the @code{asm_operands} RTX are the assembler
        !          2097: template string, the output-operand's constraint, the index-number of the
        !          2098: output operand among the output operands specified, a vector of input
        !          2099: operand RTX's, and a vector of input-operand modes and constraints.  The
        !          2100: mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
        !          2101: @code{*z}.
        !          2102: 
        !          2103: When an @code{asm} statement has multiple output values, its insn has
        !          2104: several such @code{set} RTX's inside of a @code{parallel}.  Each @code{set}
        !          2105: contains a @code{asm_operands}; all of these share the same assembler
        !          2106: template and vectors, but each contains the constraint for the respective
        !          2107: output operand.  They are also distinguished by the output-operand index
        !          2108: number, which is 0, 1, @dots{} for successive output operands.
        !          2109: 
        !          2110: @node Insns, Calls, Assembler, RTL
        !          2111: @section Insns
        !          2112: @cindex insns
        !          2113: 
        !          2114: The RTL representation of the code for a function is a doubly-linked
        !          2115: chain of objects called @dfn{insns}.  Insns are expressions with
        !          2116: special codes that are used for no other purpose.  Some insns are
        !          2117: actual instructions; others represent dispatch tables for @code{switch}
        !          2118: statements; others represent labels to jump to or various sorts of
        !          2119: declarative information.
        !          2120: 
        !          2121: In addition to its own specific data, each insn must have a unique
        !          2122: id-number that distinguishes it from all other insns in the current
        !          2123: function (after delayed branch scheduling, copies of an insn with the
        !          2124: same id-number may be present in multiple places in a function, but
        !          2125: these copies will always be identical and will only appear inside a
        !          2126: @code{sequence}), and chain pointers to the preceding and following
        !          2127: insns.  These three fields occupy the same position in every insn,
        !          2128: independent of the expression code of the insn.  They could be accessed
        !          2129: with @code{XEXP} and @code{XINT}, but instead three special macros are
        !          2130: always used:
        !          2131: 
        !          2132: @table @code
        !          2133: @findex INSN_UID
        !          2134: @item INSN_UID (@var{i})
        !          2135: Accesses the unique id of insn @var{i}.
        !          2136: 
        !          2137: @findex PREV_INSN
        !          2138: @item PREV_INSN (@var{i})
        !          2139: Accesses the chain pointer to the insn preceding @var{i}.
        !          2140: If @var{i} is the first insn, this is a null pointer.
        !          2141: 
        !          2142: @findex NEXT_INSN
        !          2143: @item NEXT_INSN (@var{i})
        !          2144: Accesses the chain pointer to the insn following @var{i}.
        !          2145: If @var{i} is the last insn, this is a null pointer.
        !          2146: @end table
        !          2147: 
        !          2148: @findex get_insns
        !          2149: @findex get_last_insn
        !          2150: The first insn in the chain is obtained by calling @code{get_insns}; the
        !          2151: last insn is the result of calling @code{get_last_insn}.  Within the
        !          2152: chain delimited by these insns, the @code{NEXT_INSN} and
        !          2153: @code{PREV_INSN} pointers must always correspond: if @var{insn} is not
        !          2154: the first insn,
        !          2155: 
        !          2156: @example
        !          2157: NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
        !          2158: @end example
        !          2159: 
        !          2160: @noindent
        !          2161: is always true and if @var{insn} is not the last insn,
        !          2162: 
        !          2163: @example
        !          2164: PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
        !          2165: @end example
        !          2166: 
        !          2167: @noindent
        !          2168: is always true.
        !          2169: 
        !          2170: After delay slot scheduling, some of the insns in the chain might be
        !          2171: @code{sequence} expressions, which contain a vector of insns.  The value
        !          2172: of @code{NEXT_INSN} in all but the last of these insns is the next insn
        !          2173: in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
        !          2174: is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
        !          2175: which it is contained.  Similar rules apply for @code{PREV_INSN}.
        !          2176: 
        !          2177: This means that the above invariants are not necessarily true for insns
        !          2178: inside @code{sequence} expressions.  Specifically, if @var{insn} is the
        !          2179: first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
        !          2180: is the insn containing the @code{sequence} expression, as is the value
        !          2181: of @code{PREV_INSN (NEXT_INSN (@var{insn}))} is @var{insn} is the last
        !          2182: insn in the @code{sequence} expression.  You can use these expressions
        !          2183: to find the containing @code{sequence} expression.@refill
        !          2184: 
        !          2185: Every insn has one of the following six expression codes:
        !          2186: 
        !          2187: @table @code
        !          2188: @findex insn
        !          2189: @item insn
        !          2190: The expression code @code{insn} is used for instructions that do not jump
        !          2191: and do not do function calls.  @code{sequence} expressions are always
        !          2192: contained in insns with code @code{insn} even if one of those insns
        !          2193: should jump or do function calls.
        !          2194: 
        !          2195: Insns with code @code{insn} have four additional fields beyond the three
        !          2196: mandatory ones listed above.  These four are described in a table below.
        !          2197: 
        !          2198: @findex jump_insn
        !          2199: @item jump_insn
        !          2200: The expression code @code{jump_insn} is used for instructions that may
        !          2201: jump (or, more generally, may contain @code{label_ref} expressions).  If
        !          2202: there is an instruction to return from the current function, it is
        !          2203: recorded as a @code{jump_insn}.
        !          2204: 
        !          2205: @findex JUMP_LABEL
        !          2206: @code{jump_insn} insns have the same extra fields as @code{insn} insns,
        !          2207: accessed in the same way and in addition contains a field
        !          2208: @code{JUMP_LABEL} which is defined once jump optimization has completed.
        !          2209: 
        !          2210: For simple conditional and unconditional jumps, this field contains the
        !          2211: @code{code_label} to which this insn will (possibly conditionally)
        !          2212: branch.  In a more complex jump, @code{JUMP_LABEL} records one of the
        !          2213: labels that the insn refers to; the only way to find the others
        !          2214: is to scan the entire body of the insn.
        !          2215: 
        !          2216: Return insns count as jumps, but since they do not refer to any labels,
        !          2217: they have zero in the @code{JUMP_LABEL} field.
        !          2218: 
        !          2219: @findex call_insn
        !          2220: @item call_insn
        !          2221: The expression code @code{call_insn} is used for instructions that may do
        !          2222: function calls.  It is important to distinguish these instructions because
        !          2223: they imply that certain registers and memory locations may be altered
        !          2224: unpredictably.
        !          2225: 
        !          2226: A @code{call_insn} insn may be preceded by insns that contain a single
        !          2227: @code{use} expression and be followed by insns the contain a single
        !          2228: @code{clobber} expression.  If so, these @code{use} and @code{clobber}
        !          2229: expressions are treated as being part of the function call.
        !          2230: There must not even be a @code{note} between the @code{call_insn} and
        !          2231: the @code{use} or @code{clobber} insns for this special treatment to
        !          2232: take place.  This is somewhat of a kludge and will be removed in a later
        !          2233: version of GNU CC.
        !          2234: 
        !          2235: @code{call_insn} insns have the same extra fields as @code{insn} insns,
        !          2236: accessed in the same way.
        !          2237: 
        !          2238: @findex code_label
        !          2239: @findex CODE_LABEL_NUMBER
        !          2240: @item code_label
        !          2241: A @code{code_label} insn represents a label that a jump insn can jump
        !          2242: to.  It contains two special fields of data in addition to the three
        !          2243: standard ones.  @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
        !          2244: number}, a number that identifies this label uniquely among all the
        !          2245: labels in the compilation (not just in the current function).
        !          2246: Ultimately, the label is represented in the assembler output as an
        !          2247: assembler label, usually of the form @samp{L@var{n}} where @var{n} is
        !          2248: the label number.
        !          2249: 
        !          2250: When a @code{code_label} appears in an RTL expression, it normally
        !          2251: appears within a @code{label_ref} which represents the address of
        !          2252: the label, as a number.
        !          2253: 
        !          2254: @findex LABEL_NUSES
        !          2255: The field @code{LABEL_NUSES} is only defined once the jump optimization
        !          2256: phase is completed and contains the number of times this label is
        !          2257: referenced in the current function.
        !          2258: 
        !          2259: @findex barrier
        !          2260: @item barrier
        !          2261: Barriers are placed in the instruction stream when control cannot flow
        !          2262: past them.  They are placed after unconditional jump instructions to
        !          2263: indicate that the jumps are unconditional and after calls to
        !          2264: @code{volatile} functions, which do not return (e.g., @code{exit}).
        !          2265: They contain no information beyond the three standard fields.
        !          2266: 
        !          2267: @findex note
        !          2268: @findex NOTE_LINE_NUMBER
        !          2269: @findex NOTE_SOURCE_FILE
        !          2270: @item note
        !          2271: @code{note} insns are used to represent additional debugging and
        !          2272: declarative information.  They contain two nonstandard fields, an
        !          2273: integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
        !          2274: string accessed with @code{NOTE_SOURCE_FILE}.
        !          2275: 
        !          2276: If @code{NOTE_LINE_NUMBER} is positive, the note represents the
        !          2277: position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
        !          2278: that the line came from.  These notes control generation of line
        !          2279: number data in the assembler output.
        !          2280: 
        !          2281: Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
        !          2282: code with one of the following values (and @code{NOTE_SOURCE_FILE}
        !          2283: must contain a null pointer):
        !          2284: 
        !          2285: @table @code
        !          2286: @findex NOTE_INSN_DELETED
        !          2287: @item NOTE_INSN_DELETED
        !          2288: Such a note is completely ignorable.  Some passes of the compiler
        !          2289: delete insns by altering them into notes of this kind.
        !          2290: 
        !          2291: @findex NOTE_INSN_BLOCK_BEG
        !          2292: @findex NOTE_INSN_BLOCK_END
        !          2293: @item NOTE_INSN_BLOCK_BEG
        !          2294: @itemx NOTE_INSN_BLOCK_END
        !          2295: These types of notes indicate the position of the beginning and end
        !          2296: of a level of scoping of variable names.  They control the output
        !          2297: of debugging information.
        !          2298: 
        !          2299: @findex NOTE_INSN_LOOP_BEG
        !          2300: @findex NOTE_INSN_LOOP_END
        !          2301: @item NOTE_INSN_LOOP_BEG
        !          2302: @itemx NOTE_INSN_LOOP_END
        !          2303: These types of notes indicate the position of the beginning and end
        !          2304: of a @code{while} or @code{for} loop.  They enable the loop optimizer
        !          2305: to find loops quickly.
        !          2306: 
        !          2307: @findex NOTE_INSN_LOOP_CONT
        !          2308: @item NOTE_INSN_LOOP_CONT
        !          2309: Appears at the place in a loop that @code{continue} statements jump to.
        !          2310: 
        !          2311: @findex NOTE_INSN_LOOP_VTOP
        !          2312: @item NOTE_INSN_LOOP_VTOP
        !          2313: This note indicates the place in a loop where the exit test begins for
        !          2314: those loops in which the exit test has been duplicated.  This position
        !          2315: becomes another virtual start of the loop when considering loop
        !          2316: invariants. 
        !          2317: 
        !          2318: @findex NOTE_INSN_FUNCTION_END
        !          2319: @item NOTE_INSN_FUNCTION_END
        !          2320: Appears near the end of the function body, just before the label that
        !          2321: @code{return} statements jump to (on machine where a single instruction
        !          2322: does not suffice for returning).  This note may be deleted by jump
        !          2323: optimization.
        !          2324: 
        !          2325: @findex NOTE_INSN_SETJMP
        !          2326: @item NOTE_INSN_SETJMP
        !          2327: Appears following each call to @code{setjmp} or a related function.
        !          2328: @end table
        !          2329: 
        !          2330: These codes are printed symbolically when they appear in debugging dumps.
        !          2331: @end table
        !          2332: 
        !          2333: @cindex @code{HImode}, in @code{insn}
        !          2334: @cindex @code{QImode}, in @code{insn}
        !          2335: The machine mode of an insn is normally @code{VOIDmode}, but some
        !          2336: phases use the mode for various purposes; for example, the reload pass
        !          2337: sets it to @code{HImode} if the insn needs reloading but not register
        !          2338: elimination and @code{QImode} if both are required.  The common
        !          2339: subexpression elimination pass sets the mode of an insn to @code{QImode}
        !          2340: when it is the first insn in a block that has already been processed.
        !          2341: 
        !          2342: Here is a table of the extra fields of @code{insn}, @code{jump_insn}
        !          2343: and @code{call_insn} insns:
        !          2344: 
        !          2345: @table @code
        !          2346: @findex PATTERN
        !          2347: @item PATTERN (@var{i})
        !          2348: An expression for the side effect performed by this insn.  This must be
        !          2349: one of the following codes: @code{set}, @code{call}, @code{use},
        !          2350: @code{clobber}, @code{return}, @code{asm_input}, @code{asm_output},
        !          2351: @code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec},
        !          2352: @code{unspec_volatile}, @code{parallel}, or @code{sequence}.  If it is a @code{parallel},
        !          2353: each element of the @code{parallel} must be one these codes, except that
        !          2354: @code{parallel} expressions cannot be nested and @code{addr_vec} and
        !          2355: @code{addr_diff_vec} are not permitted inside a @code{parallel} expression.
        !          2356: 
        !          2357: @findex INSN_CODE
        !          2358: @item INSN_CODE (@var{i})
        !          2359: An integer that says which pattern in the machine description matches
        !          2360: this insn, or -1 if the matching has not yet been attempted.
        !          2361: 
        !          2362: Such matching is never attempted and this field remains -1 on an insn
        !          2363: whose pattern consists of a single @code{use}, @code{clobber},
        !          2364: @code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.
        !          2365: 
        !          2366: @findex asm_noperands
        !          2367: Matching is also never attempted on insns that result from an @code{asm}
        !          2368: statement.  These contain at least one @code{asm_operands} expression.
        !          2369: The function @code{asm_noperands} returns a non-negative value for
        !          2370: such insns.
        !          2371: 
        !          2372: In the debugging output, this field is printed as a number followed by
        !          2373: a symbolic representation that locates the pattern in the @file{md}
        !          2374: file as some small positive or negative offset from a named pattern.
        !          2375: 
        !          2376: @findex LOG_LINKS
        !          2377: @item LOG_LINKS (@var{i})
        !          2378: A list (chain of @code{insn_list} expressions) giving information about
        !          2379: dependencies between instructions within a basic block.  Neither a jump
        !          2380: nor a label may come between the related insns.
        !          2381: 
        !          2382: @findex REG_NOTES
        !          2383: @item REG_NOTES (@var{i})
        !          2384: A list (chain of @code{expr_list} and @code{insn_list} expressions)
        !          2385: giving miscellaneous information about the insn.  It is often information
        !          2386: pertaining to the registers used in this insn.
        !          2387: @end table
        !          2388: 
        !          2389: The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
        !          2390: expressions.  Each of these has two operands: the first is an insn,
        !          2391: and the second is another @code{insn_list} expression (the next one in
        !          2392: the chain).  The last @code{insn_list} in the chain has a null pointer
        !          2393: as second operand.  The significant thing about the chain is which
        !          2394: insns appear in it (as first operands of @code{insn_list}
        !          2395: expressions).  Their order is not significant.
        !          2396: 
        !          2397: This list is originally set up by the flow analysis pass; it is a null
        !          2398: pointer until then.  Flow only adds links for those data dependencies
        !          2399: which can be used for instruction combination.  For each insn, the flow
        !          2400: analysis pass adds a link to insns which store into registers values
        !          2401: that are used for the first time in this insn.  The instruction
        !          2402: scheduling pass adds extra links so that every dependence will be
        !          2403: represented.  Links represent data dependencies, antidependencies and
        !          2404: output dependencies; the machine mode of the link distinguishes these
        !          2405: three types: antidependencies have mode @code{REG_DEP_ANTI}, output
        !          2406: dependencies have mode @code{REG_DEP_OUTPUT}, and data dependencies have
        !          2407: mode @code{VOIDmode}.
        !          2408: 
        !          2409: The @code{REG_NOTES} field of an insn is a chain similar to the
        !          2410: @code{LOG_LINKS} field but it includes @code{expr_list} expressions in
        !          2411: addition to @code{insn_list} expressions.  There are several kinds
        !          2412: of register notes, which are distinguished by the machine mode, which
        !          2413: in a register note is really understood as being an @code{enum reg_note}.
        !          2414: The first operand @var{op} of the note is data whose meaning depends on
        !          2415: the kind of note. 
        !          2416: 
        !          2417: @findex REG_NOTE_KIND
        !          2418: @findex PUT_REG_NOTE_KIND
        !          2419: The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of
        !          2420: register note.  Its counterpart, the macro @code{PUT_REG_NOTE_KIND
        !          2421: (@var{x}, @var{newkind})} sets the register note type of @var{x} to be
        !          2422: @var{newkind}.
        !          2423: 
        !          2424: Register notes are of three classes: They may say something about an
        !          2425: input to an insn, they may say something about an output of an insn, or
        !          2426: they may create a linkage between two insns.  There are also a set
        !          2427: of values that are only used in @code{LOG_LINKS}.
        !          2428: 
        !          2429: These register notes annotate inputs to an insn:
        !          2430: 
        !          2431: @table @code
        !          2432: @findex REG_DEAD 
        !          2433: @item REG_DEAD
        !          2434: The value in @var{op} dies in this insn; that is to say, altering the
        !          2435: value immediately after this insn would not affect the future behavior
        !          2436: of the program.  
        !          2437: 
        !          2438: This does not necessarily mean that the register @var{op} has no useful
        !          2439: value after this insn since it may also be an output of the insn.  In
        !          2440: such a case, however, a @code{REG_DEAD} note would be redundant and is
        !          2441: usually not present until after the reload pass, but no code relies on
        !          2442: this fact.
        !          2443: 
        !          2444: @findex REG_INC
        !          2445: @item REG_INC
        !          2446: The register @var{op} is incremented (or decremented; at this level
        !          2447: there is no distinction) by an embedded side effect inside this insn.
        !          2448: This means it appears in a @code{post_inc}, @code{pre_inc},
        !          2449: @code{post_dec} or @code{pre_dec} expression.
        !          2450: 
        !          2451: @findex REG_NONNEG
        !          2452: @item REG_NONNEG
        !          2453: The register @var{op} is known to have a nonnegative value when this
        !          2454: insn is reached.  This is used so that decrement and branch until zero
        !          2455: instructions, such as the m68k dbra, can be matched.
        !          2456: 
        !          2457: The @code{REG_NONNEG} note is added to insns only if the machine
        !          2458: description has a @samp{decrement_and_branch_until_zero} pattern.
        !          2459: 
        !          2460: @findex REG_NO_CONFLICT
        !          2461: @item REG_NO_CONFLICT
        !          2462: This insn does not cause a conflict between @var{op} and the item
        !          2463: being set by this insn even though it might appear that it does.
        !          2464: In other words, if the destination register and @var{op} could
        !          2465: otherwise be assigned the same register, this insn does not
        !          2466: prevent that assignment.
        !          2467: 
        !          2468: Insns with this note are usually part of a block that begins with a
        !          2469: @code{clobber} insn specifying a multi-word pseudo register (which will
        !          2470: be the output of the block), a group of insns that each set one word of
        !          2471: the value and have the @code{REG_NO_CONFLICT} note attached, and a final
        !          2472: insn that copies the output to itself with an attached @code{REG_EQUAL}
        !          2473: note giving the expression being computed.  This block is encapsulated
        !          2474: with @code{REG_LIBCALL} and @code{REG_RETVAL} notes on the first and
        !          2475: last insns, respectively.
        !          2476: 
        !          2477: @findex REG_LABEL
        !          2478: @item REG_LABEL
        !          2479: This insn uses @var{op}, a @code{code_label}, but is not a
        !          2480: @code{jump_insn}.  The presence of this note allows jump optimization to
        !          2481: be aware that @var{op} is, in fact, being used.
        !          2482: @end table
        !          2483: 
        !          2484: The following notes describe attributes of outputs of an insn:
        !          2485: 
        !          2486: @table @code
        !          2487: @findex REG_EQUIV
        !          2488: @findex REG_EQUAL
        !          2489: @item REG_EQUIV
        !          2490: @itemx REG_EQUAL
        !          2491: This note is only valid on an insn that sets only one register and
        !          2492: indicates that that register will be equal to @var{op} at run time; the
        !          2493: scope of this equivalence differs between the two types of notes.  The
        !          2494: value which the insn explicitly copies into the register may look
        !          2495: different from @var{op}, but they will be equal at run time.  If the
        !          2496: output of the single @code{set} is a @code{strict_low_part} expression,
        !          2497: the note refers to the register that is contained in @code{SUBREG_REG}
        !          2498: of the @code{subreg} expression.
        !          2499:  
        !          2500: For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout
        !          2501: the entire function, and could validly be replaced in all its
        !          2502: occurrences by @var{op}.  (``Validly'' here refers to the data flow of
        !          2503: the program; simple replacement may make some insns invalid.)  For
        !          2504: example, when a constant is loaded into a register that is never
        !          2505: assigned any other value, this kind of note is used.
        !          2506: 
        !          2507: When a parameter is copied into a pseudo-register at entry to a function,
        !          2508: a note of this kind records that the register is equivalent to the stack
        !          2509: slot where the parameter was passed.  Although in this case the register
        !          2510: may be set by other insns, it is still valid to replace the register
        !          2511: by the stack slot throughout the function.
        !          2512: 
        !          2513: In the case of @code{REG_EQUAL}, the register that is set by this insn
        !          2514: will be equal to @var{op} at run time at the end of this insn but not
        !          2515: necessarily elsewhere in the function.  In this case, @var{op}
        !          2516: is typically an arithmetic expression.  For example, when a sequence of
        !          2517: insns such as a library call is used to perform an arithmetic operation,
        !          2518: this kind of note is attached to the insn that produces or copies the
        !          2519: final value.
        !          2520: 
        !          2521: These two notes are used in different ways by the compiler passes.
        !          2522: @code{REG_EQUAL} is used by passes prior to register allocation (such as
        !          2523: common subexpression elimination and loop optimization) to tell them how
        !          2524: to think of that value.  @code{REG_EQUIV} notes are used by register
        !          2525: allocation to indicate that there is an available substitute expression
        !          2526: (either a constant or a @code{mem} expression for the location of a
        !          2527: parameter on the stack) that may be used in place of a register if
        !          2528: insufficient registers are available.
        !          2529: 
        !          2530: Except for stack homes for parameters, which are indicated by a
        !          2531: @code{REG_EQUIV} note and are not useful to the early optimization
        !          2532: passes and pseudo registers that are equivalent to a memory location
        !          2533: throughout there entire life, which is not detected until later in
        !          2534: the compilation, all equivalences are initially indicated by an attached
        !          2535: @code{REG_EQUAL} note.  In the early stages of register allocation, a
        !          2536: @code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if
        !          2537: @var{op} is a constant and the insn represents the only set of its
        !          2538: destination register.
        !          2539: 
        !          2540: Thus, compiler passes prior to register allocation need only check for
        !          2541: @code{REG_EQUAL} notes and passes subsequent to register allocation
        !          2542: need only check for @code{REG_EQUIV} notes.
        !          2543: 
        !          2544: @findex REG_UNUSED
        !          2545: @item REG_UNUSED
        !          2546: The register @var{op} being set by this insn will not be used in a
        !          2547: subsequent insn.  This differs from a @code{REG_DEAD} note, which
        !          2548: indicates that the value in an input will not be used subsequently.
        !          2549: These two notes are independent; both may be present for the same
        !          2550: register.
        !          2551: 
        !          2552: @findex REG_WAS_0
        !          2553: @item REG_WAS_0
        !          2554: The single output of this insn contained zero before this insn.
        !          2555: @var{op} is the insn that set it to zero.  You can rely on this note if
        !          2556: it is present and @var{op} has not been deleted or turned into a @code{note};
        !          2557: its absence implies nothing.
        !          2558: @end table
        !          2559: 
        !          2560: These notes describe linkages between insns.  They occur in pairs: one
        !          2561: insn has one of a pair of notes that points to a second insn, which has
        !          2562: the inverse note pointing back to the first insn.
        !          2563: 
        !          2564: @table @code
        !          2565: @findex REG_RETVAL
        !          2566: @item REG_RETVAL
        !          2567: This insn copies the value of a multi-insn sequence (for example, a
        !          2568: library call), and @var{op} is the first insn of the sequence (for a
        !          2569: library call, the first insn that was generated to set up the arguments
        !          2570: for the library call).
        !          2571: 
        !          2572: Loop optimization uses this note to treat such a sequence as a single
        !          2573: operation for code motion purposes and flow analysis uses this note to
        !          2574: delete such sequences whose results are dead.
        !          2575: 
        !          2576: A @code{REG_EQUAL} note will also usually be attached to this insn to 
        !          2577: provide the expression being computed by the sequence.
        !          2578: 
        !          2579: @findex REG_LIBCALL
        !          2580: @item REG_LIBCALL
        !          2581: This is the inverse of @code{REG_RETVAL}: it is placed on the first
        !          2582: insn of a multi-insn sequence, and it points to the last one.
        !          2583: 
        !          2584: @findex REG_CC_SETTER
        !          2585: @findex REG_CC_USER
        !          2586: @item REG_CC_SETTER
        !          2587: @itemx REG_CC_USER
        !          2588: On machines that use @code{cc0}, the insns which set and use @code{cc0}
        !          2589: set and use @code{cc0} are adjacent.  However, when branch delay slot
        !          2590: filling is done, this may no longer be true.  In this case a
        !          2591: @code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to
        !          2592: point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will
        !          2593: be placed on the insn using @code{cc0} to point to the insn setting
        !          2594: @code{cc0}.@refill
        !          2595: @end table
        !          2596: 
        !          2597: These values are only used in the @code{LOG_LINKS} field, and indicate
        !          2598: the type of dependency that each link represents.  Links which indicate
        !          2599: a data dependence (a read after write dependence) do not use any code,
        !          2600: they simply have mode @code{VOIDmode}, and are printed without any
        !          2601: descriptive text.
        !          2602: 
        !          2603: @table @code
        !          2604: @findex REG_DEP_ANTI
        !          2605: @item REG_DEP_ANTI
        !          2606: This indicates an anti dependence (a write after read dependence).
        !          2607: 
        !          2608: @findex REG_DEP_OUTPUT
        !          2609: @item REG_DEP_OUTPUT
        !          2610: This indicates an output dependence (a write after write dependence).
        !          2611: @end table
        !          2612: 
        !          2613: For convenience, the machine mode in an @code{insn_list} or
        !          2614: @code{expr_list} is printed using these symbolic codes in debugging dumps.
        !          2615: 
        !          2616: @findex insn_list
        !          2617: @findex expr_list
        !          2618: The only difference between the expression codes @code{insn_list} and
        !          2619: @code{expr_list} is that the first operand of an @code{insn_list} is
        !          2620: assumed to be an insn and is printed in debugging dumps as the insn's
        !          2621: unique id; the first operand of an @code{expr_list} is printed in the
        !          2622: ordinary way as an expression.
        !          2623: 
        !          2624: @node Calls, Sharing, Insns, RTL
        !          2625: @section RTL Representation of Function-Call Insns
        !          2626: @cindex calling functions in RTL
        !          2627: @cindex RTL function-call insns
        !          2628: @cindex function-call insns
        !          2629: 
        !          2630: Insns that call subroutines have the RTL expression code @code{call_insn}.
        !          2631: These insns must satisfy special rules, and their bodies must use a special
        !          2632: RTL expression code, @code{call}.
        !          2633: 
        !          2634: @cindex @code{call} usage
        !          2635: A @code{call} expression has two operands, as follows:
        !          2636: 
        !          2637: @example
        !          2638: (call (mem:@var{fm} @var{addr}) @var{nbytes})
        !          2639: @end example
        !          2640: 
        !          2641: @noindent
        !          2642: Here @var{nbytes} is an operand that represents the number of bytes of
        !          2643: argument data being passed to the subroutine, @var{fm} is a machine mode
        !          2644: (which must equal as the definition of the @code{FUNCTION_MODE} macro in
        !          2645: the machine description) and @var{addr} represents the address of the
        !          2646: subroutine.
        !          2647: 
        !          2648: For a subroutine that returns no value, the @code{call} expression as
        !          2649: shown above is the entire body of the insn, except that the insn might
        !          2650: also contain @code{use} or @code{clobber} expressions.
        !          2651: 
        !          2652: @cindex @code{BLKmode}, and function return values
        !          2653: For a subroutine that returns a value whose mode is not @code{BLKmode},
        !          2654: the value is returned in a hard register.  If this register's number is
        !          2655: @var{r}, then the body of the call insn looks like this:
        !          2656: 
        !          2657: @example
        !          2658: (set (reg:@var{m} @var{r})
        !          2659:      (call (mem:@var{fm} @var{addr}) @var{nbytes}))
        !          2660: @end example
        !          2661: 
        !          2662: @noindent
        !          2663: This RTL expression makes it clear (to the optimizer passes) that the
        !          2664: appropriate register receives a useful value in this insn.
        !          2665: 
        !          2666: When a subroutine returns a @code{BLKmode} value, it is handled by
        !          2667: passing to the subroutine the address of a place to store the value.
        !          2668: So the call insn itself does not ``return'' any value, and it has the
        !          2669: same RTL form as a call that returns nothing.
        !          2670: 
        !          2671: On some machines, the call instruction itself clobbers some register,
        !          2672: for example to contain the return address.  @code{call_insn} insns
        !          2673: on these machines should have a body which is a @code{parallel}
        !          2674: that contains both the @code{call} expression and @code{clobber}
        !          2675: expressions that indicate which registers are destroyed.  Similarly,
        !          2676: if the call instruction requires some register other than the stack
        !          2677: pointer that is not explicitly mentioned it its RTL, a @code{use}
        !          2678: subexpression should mention that register.
        !          2679: 
        !          2680: Functions that are called are assumed to modify all registers listed in
        !          2681: the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register
        !          2682: Basics}) and, with the exception of @code{const} functions and library
        !          2683: calls, to modify all of memory.
        !          2684: 
        !          2685: Insns containing just @code{use} expressions directly precede the
        !          2686: @code{call_insn} insn to indicate which registers contain inputs to the
        !          2687: function.  Similarly, if registers other than those in
        !          2688: @code{CALL_USED_REGISTERS} are clobbered by the called function, insns
        !          2689: containing a single @code{clobber} follow immediately after the call to
        !          2690: indicate which registers.
        !          2691: 
        !          2692: @node Sharing
        !          2693: @section Structure Sharing Assumptions
        !          2694: @cindex sharing of RTL components
        !          2695: @cindex RTL structure sharing assumptions
        !          2696: 
        !          2697: The compiler assumes that certain kinds of RTL expressions are unique;
        !          2698: there do not exist two distinct objects representing the same value.
        !          2699: In other cases, it makes an opposite assumption: that no RTL expression
        !          2700: object of a certain kind appears in more than one place in the
        !          2701: containing structure.
        !          2702: 
        !          2703: These assumptions refer to a single function; except for the RTL
        !          2704: objects that describe global variables and external functions,
        !          2705: and a few standard objects such as small integer constants,
        !          2706: no RTL objects are common to two functions.
        !          2707: 
        !          2708: @itemize @bullet
        !          2709: @cindex @code{reg}, RTL sharing
        !          2710: @item
        !          2711: Each pseudo-register has only a single @code{reg} object to represent it,
        !          2712: and therefore only a single machine mode.
        !          2713: 
        !          2714: @cindex symbolic label
        !          2715: @cindex @code{symbol_ref}, RTL sharing
        !          2716: @item
        !          2717: For any symbolic label, there is only one @code{symbol_ref} object
        !          2718: referring to it.
        !          2719: 
        !          2720: @cindex @code{const_int}, RTL sharing
        !          2721: @item
        !          2722: There is only one @code{const_int} expression with value 0, only
        !          2723: one with value 1, and only one with value @minus{}1.
        !          2724: Some other integer values are also stored uniquely.
        !          2725: 
        !          2726: @cindex @code{pc}, RTL sharing
        !          2727: @item
        !          2728: There is only one @code{pc} expression.
        !          2729: 
        !          2730: @cindex @code{cc0}, RTL sharing
        !          2731: @item
        !          2732: There is only one @code{cc0} expression.
        !          2733: 
        !          2734: @cindex @code{const_double}, RTL sharing
        !          2735: @item
        !          2736: There is only one @code{const_double} expression with value 0 for
        !          2737: each floating point mode.  Likewise for values 1 and 2.
        !          2738: 
        !          2739: @cindex @code{label_ref}, RTL sharing
        !          2740: @cindex @code{scratch}, RTL sharing
        !          2741: @item
        !          2742: No @code{label_ref} or @code{scratch} appears in more than one place in
        !          2743: the RTL structure; in other words, it is safe to do a tree-walk of all
        !          2744: the insns in the function and assume that each time a @code{label_ref}
        !          2745: or @code{scratch} is seen it is distinct from all others that are seen.
        !          2746: 
        !          2747: @cindex @code{mem}, RTL sharing
        !          2748: @item
        !          2749: Only one @code{mem} object is normally created for each static
        !          2750: variable or stack slot, so these objects are frequently shared in all
        !          2751: the places they appear.  However, separate but equal objects for these
        !          2752: variables are occasionally made.
        !          2753: 
        !          2754: @cindex @code{asm_operands}, RTL sharing
        !          2755: @item
        !          2756: When a single @code{asm} statement has multiple output operands, a
        !          2757: distinct @code{asm_operands} expression is made for each output operand.
        !          2758: However, these all share the vector which contains the sequence of input
        !          2759: operands.  This sharing is used later on to test whether two
        !          2760: @code{asm_operands} expressions come from the same statement, so all
        !          2761: optimizations must carefully preserve the sharing if they copy the
        !          2762: vector at all.
        !          2763: 
        !          2764: @item
        !          2765: No RTL object appears in more than one place in the RTL structure
        !          2766: except as described above.  Many passes of the compiler rely on this
        !          2767: by assuming that they can modify RTL objects in place without unwanted
        !          2768: side-effects on other insns.
        !          2769: 
        !          2770: @findex unshare_all_rtl
        !          2771: @item
        !          2772: During initial RTL generation, shared structure is freely introduced.
        !          2773: After all the RTL for a function has been generated, all shared
        !          2774: structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
        !          2775: after which the above rules are guaranteed to be followed.
        !          2776: 
        !          2777: @findex copy_rtx_if_shared
        !          2778: @item
        !          2779: During the combiner pass, shared structure within an insn can exist
        !          2780: temporarily.  However, the shared structure is copied before the
        !          2781: combiner is finished with the insn.  This is done by calling
        !          2782: @code{copy_rtx_if_shared}, which is a subroutine of
        !          2783: @code{unshare_all_rtl}.
        !          2784: @end itemize
        !          2785: 
        !          2786: @node Reading RTL
        !          2787: @section Reading RTL
        !          2788: 
        !          2789: To read an RTL object from a file, call @code{read_rtx}.  It takes one
        !          2790: argument, a stdio stream, and returns a single RTL object.
        !          2791: 
        !          2792: Reading RTL from a file is very slow.  This is no currently not a
        !          2793: problem because reading RTL occurs only as part of building the
        !          2794: compiler.
        !          2795: 
        !          2796: People frequently have the idea of using RTL stored as text in a file as
        !          2797: an interface between a language front end and the bulk of GNU CC.  This
        !          2798: idea is not feasible.
        !          2799: 
        !          2800: GNU CC was designed to use RTL internally only.  Correct RTL for a given
        !          2801: program is very dependent on the particular target machine.  And the RTL
        !          2802: does not contain all the information about the program.
        !          2803: 
        !          2804: The proper way to interface GNU CC to a new language front end is with
        !          2805: the ``tree'' data structure.  There is no manual for this data
        !          2806: structure, but it is described in the files @file{tree.h} and
        !          2807: @file{tree.def}.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.