@c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002,@c 2003, 2004, 2005, 2006, 2007, 2008@c Free Software Foundation, Inc.@c This is part of the GCC manual.@c For copying conditions, see the file gcc.texi.@node RTL@chapter RTL Representation@cindex RTL representation@cindex representation of RTL@cindex Register Transfer Language (RTL)Most of the work of the compiler is done on an intermediate representationcalled register transfer language.  In this language, the instructions to beoutput are described, pretty much one by one, in an algebraic form thatdescribes what the instruction does.RTL is inspired by Lisp lists.  It has both an internal form, made up ofstructures that point at other structures, and a textual form that is usedin the machine description and in printed debugging dumps.  The textualform uses nested parentheses to indicate the pointers in the internal form.@menu* RTL Objects::       Expressions vs vectors vs strings vs integers.* RTL Classes::       Categories of RTL expression objects, and their structure.* Accessors::         Macros to access expression operands or vector elts.* Special Accessors:: Macros to access specific annotations on RTL.* Flags::             Other flags in an RTL expression.* Machine Modes::     Describing the size and format of a datum.* Constants::         Expressions with constant values.* Regs and Memory::   Expressions representing register contents or memory.* Arithmetic::        Expressions representing arithmetic on other expressions.* Comparisons::       Expressions representing comparison of expressions.* Bit-Fields::        Expressions representing bit-fields in memory or reg.* Vector Operations:: Expressions involving vector datatypes.* Conversions::       Extending, truncating, floating or fixing.* RTL Declarations::  Declaring volatility, constancy, etc.* Side Effects::      Expressions for storing in registers, etc.* Incdec::            Embedded side-effects for autoincrement addressing.* Assembler::         Representing @code{asm} with operands.* Insns::             Expression types for entire insns.* Calls::             RTL representation of function call insns.* Sharing::           Some expressions are unique; others *must* be copied.* Reading RTL::       Reading textual RTL from a file.@end menu@node RTL Objects@section RTL Object Types@cindex RTL object types@cindex RTL integers@cindex RTL strings@cindex RTL vectors@cindex RTL expression@cindex RTX (See RTL)RTL uses five kinds of objects: expressions, integers, wide integers,strings and vectors.  Expressions are the most important ones.  An RTLexpression (``RTX'', for short) is a C structure, but it is usuallyreferred to with a pointer; a type that is given the typedef name@code{rtx}.An integer is simply an @code{int}; their written form uses decimaldigits.  A wide integer is an integral object whose type is@code{HOST_WIDE_INT}; their written form uses decimal digits.A string is a sequence of characters.  In core it is represented as a@code{char *} in usual C fashion, and it is written in C syntax as well.However, strings in RTL may never be null.  If you write an empty string ina machine description, it is represented in core as a null pointer ratherthan as a pointer to a null character.  In certain contexts, these nullpointers instead of strings are valid.  Within RTL code, strings are mostcommonly found inside @code{symbol_ref} expressions, but they appear inother contexts in the RTL expressions that make up machine descriptions.In a machine description, strings are normally written with doublequotes, as you would in C@.  However, strings in machine descriptions mayextend over many lines, which is invalid C, and adjacent stringconstants are not concatenated as they are in C@.  Any string constantmay be surrounded with a single set of parentheses.  Sometimes thismakes the machine description easier to read.There is also a special syntax for strings, which can be useful when Ccode is embedded in a machine description.  Wherever a string canappear, it is also valid to write a C-style brace block.  The entirebrace block, including the outermost pair of braces, is considered to bethe string constant.  Double quote characters inside the braces are notspecial.  Therefore, if you write string constants in the C code, youneed not escape each quote character with a backslash.A vector contains an arbitrary number of pointers to expressions.  Thenumber of elements in the vector is explicitly present in the vector.The written form of a vector consists of square brackets(@samp{[@dots{}]}) surrounding the elements, in sequence and withwhitespace separating them.  Vectors of length zero are not created;null pointers are used instead.@cindex expression codes@cindex codes, RTL expression@findex GET_CODE@findex PUT_CODEExpressions are classified by @dfn{expression codes} (also called RTXcodes).  The expression code is a name defined in @file{rtl.def}, which isalso (in uppercase) a C enumeration constant.  The possible expressioncodes and their meanings are machine-independent.  The code of an RTX canbe extracted with the macro @code{GET_CODE (@var{x})} and altered with@code{PUT_CODE (@var{x}, @var{newcode})}.The expression code determines how many operands the expression contains,and what kinds of objects they are.  In RTL, unlike Lisp, you cannot tellby looking at an operand what kind of object it is.  Instead, you must knowfrom its context---from the expression code of the containing expression.For example, in an expression of code @code{subreg}, the first operand isto be regarded as an expression and the second operand as an integer.  Inan expression of code @code{plus}, there are two operands, both of whichare to be regarded as expressions.  In a @code{symbol_ref} expression,there is one operand, which is to be regarded as a string.Expressions are written as parentheses containing the name of theexpression type, its flags and machine mode if any, and then the operandsof the expression (separated by spaces).Expression code names in the @samp{md} file are written in lowercase,but when they appear in C code they are written in uppercase.  In thismanual, they are shown as follows: @code{const_int}.@cindex (nil)@cindex nilIn a few contexts a null pointer is valid where an expression is normallywanted.  The written form of this is @code{(nil)}.@node RTL Classes@section RTL Classes and Formats@cindex RTL classes@cindex classes of RTX codes@cindex RTX codes, classes of@findex GET_RTX_CLASSThe various expression codes are divided into several @dfn{classes},which are represented by single characters.  You can determine the classof an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}.Currently, @file{rtl.def} defines these classes:@table @code@item RTX_OBJAn RTX code that represents an actual object, such as a register(@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}).@code{LO_SUM}) is also included; instead, @code{SUBREG} and@code{STRICT_LOW_PART} are not in this class, but in class @code{x}.@item RTX_CONST_OBJAn RTX code that represents a constant object.  @code{HIGH} is alsoincluded in this class.@item RTX_COMPAREAn RTX code for a non-symmetric comparison, such as @code{GEU} or@code{LT}.@item RTX_COMM_COMPAREAn RTX code for a symmetric (commutative) comparison, such as @code{EQ}or @code{ORDERED}.@item RTX_UNARYAn RTX code for a unary arithmetic operation, such as @code{NEG},@code{NOT}, or @code{ABS}.  This category also includes value extension(sign or zero) and conversions between integer and floating point.@item RTX_COMM_ARITHAn RTX code for a commutative binary operation, such as @code{PLUS} or@code{AND}.  @code{NE} and @code{EQ} are comparisons, so they have class@code{<}.@item RTX_BIN_ARITHAn RTX code for a non-commutative binary operation, such as @code{MINUS},@code{DIV}, or @code{ASHIFTRT}.@item RTX_BITFIELD_OPSAn RTX code for a bit-field operation.  Currently only@code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}.  These have three inputsand are lvalues (so they can be used for insertion as well).@xref{Bit-Fields}.@item RTX_TERNARYAn RTX code for other three input operations.  Currently only@code{IF_THEN_ELSE} and @code{VEC_MERGE}.@item RTX_INSNAn RTX code for an entire instruction:  @code{INSN}, @code{JUMP_INSN}, and@code{CALL_INSN}.  @xref{Insns}.@item RTX_MATCHAn RTX code for something that matches in insns, such as@code{MATCH_DUP}.  These only occur in machine descriptions.@item RTX_AUTOINCAn RTX code for an auto-increment addressing mode, such as@code{POST_INC}.@item RTX_EXTRAAll other RTX codes.  This category includes the remaining codes usedonly in machine descriptions (@code{DEFINE_*}, etc.).  It also includesall the codes describing side effects (@code{SET}, @code{USE},@code{CLOBBER}, etc.) and the non-insns that may appear on an insnchain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}.@code{SUBREG} is also part of this class.@end table@cindex RTL formatFor each expression code, @file{rtl.def} specifies the number ofcontained objects and their kinds using a sequence of characterscalled the @dfn{format} of the expression code.  For example,the format of @code{subreg} is @samp{ei}.@cindex RTL format charactersThese are the most commonly used format characters:@table @code@item eAn expression (actually a pointer to an expression).@item iAn integer.@item wA wide integer.@item sA string.@item EA vector of expressions.@end tableA few other format characters are used occasionally:@table @code@item u@samp{u} is equivalent to @samp{e} except that it is printed differentlyin debugging dumps.  It is used for pointers to insns.@item n@samp{n} is equivalent to @samp{i} except that it is printed differentlyin debugging dumps.  It is used for the line number or code number of a@code{note} insn.@item S@samp{S} indicates a string which is optional.  In the RTL objects incore, @samp{S} is equivalent to @samp{s}, but when the object is read,from an @samp{md} file, the string value of this operand may be omitted.An omitted string is taken to be the null string.@item V@samp{V} indicates a vector which is optional.  In the RTL objects incore, @samp{V} is equivalent to @samp{E}, but when the object is readfrom an @samp{md} file, the vector value of this operand may be omitted.An omitted vector is effectively the same as a vector of no elements.@item B@samp{B} indicates a pointer to basic block structure.@item 0@samp{0} means a slot whose contents do not fit any normal category.@samp{0} slots are not printed at all in dumps, and are often used inspecial ways by small parts of the compiler.@end tableThere are macros to get the number of operands and the formatof an expression code:@table @code@findex GET_RTX_LENGTH@item GET_RTX_LENGTH (@var{code})Number of operands of an RTX of code @var{code}.@findex GET_RTX_FORMAT@item GET_RTX_FORMAT (@var{code})The format of an RTX of code @var{code}, as a C string.@end tableSome classes of RTX codes always have the same format.  For example, itis safe to assume that all comparison operations have format @code{ee}.@table @code@item 1All codes of this class have format @code{e}.@item <@itemx c@itemx 2All codes of these classes have format @code{ee}.@item b@itemx 3All codes of these classes have format @code{eee}.@item iAll codes of this class have formats that begin with @code{iuueiee}.@xref{Insns}.  Note that not all RTL objects linked onto an insn chainare of class @code{i}.@item o@itemx m@itemx xYou can make no assumptions about the format of these codes.@end table@node Accessors@section Access to Operands@cindex accessors@cindex access to operands@cindex operand access@findex XEXP@findex XINT@findex XWINT@findex XSTROperands of expressions are accessed using the macros @code{XEXP},@code{XINT}, @code{XWINT} and @code{XSTR}.  Each of these macros takestwo arguments: an expression-pointer (RTX) and an operand number(counting from zero).  Thus,@smallexampleXEXP (@var{x}, 2)@end smallexample@noindentaccesses operand 2 of expression @var{x}, as an expression.@smallexampleXINT (@var{x}, 2)@end smallexample@noindentaccesses the same operand as an integer.  @code{XSTR}, used in the samefashion, would access it as a string.Any operand can be accessed as an integer, as an expression or as a string.You must choose the correct method of access for the kind of value actuallystored in the operand.  You would do this based on the expression code ofthe containing expression.  That is also how you would know how many