rtl.texi revision 259563
1169689Skan@c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002, 2169689Skan@c 2003, 2004, 2005 390075Sobrien@c Free Software Foundation, Inc. 490075Sobrien@c This is part of the GCC manual. 590075Sobrien@c For copying conditions, see the file gcc.texi. 690075Sobrien 790075Sobrien@node RTL 890075Sobrien@chapter RTL Representation 990075Sobrien@cindex RTL representation 1090075Sobrien@cindex representation of RTL 1190075Sobrien@cindex Register Transfer Language (RTL) 1290075Sobrien 1390075SobrienMost of the work of the compiler is done on an intermediate representation 1490075Sobriencalled register transfer language. In this language, the instructions to be 1590075Sobrienoutput are described, pretty much one by one, in an algebraic form that 1690075Sobriendescribes what the instruction does. 1790075Sobrien 1890075SobrienRTL is inspired by Lisp lists. It has both an internal form, made up of 1990075Sobrienstructures that point at other structures, and a textual form that is used 2090075Sobrienin the machine description and in printed debugging dumps. The textual 2190075Sobrienform uses nested parentheses to indicate the pointers in the internal form. 2290075Sobrien 2390075Sobrien@menu 2490075Sobrien* RTL Objects:: Expressions vs vectors vs strings vs integers. 2590075Sobrien* RTL Classes:: Categories of RTL expression objects, and their structure. 2690075Sobrien* Accessors:: Macros to access expression operands or vector elts. 27132718Skan* Special Accessors:: Macros to access specific annotations on RTL. 2890075Sobrien* Flags:: Other flags in an RTL expression. 2990075Sobrien* Machine Modes:: Describing the size and format of a datum. 3090075Sobrien* Constants:: Expressions with constant values. 3190075Sobrien* Regs and Memory:: Expressions representing register contents or memory. 3290075Sobrien* Arithmetic:: Expressions representing arithmetic on other expressions. 3390075Sobrien* Comparisons:: Expressions representing comparison of expressions. 3490075Sobrien* Bit-Fields:: Expressions representing bit-fields in memory or reg. 3590075Sobrien* Vector Operations:: Expressions involving vector datatypes. 3690075Sobrien* Conversions:: Extending, truncating, floating or fixing. 3790075Sobrien* RTL Declarations:: Declaring volatility, constancy, etc. 3890075Sobrien* Side Effects:: Expressions for storing in registers, etc. 3990075Sobrien* Incdec:: Embedded side-effects for autoincrement addressing. 4090075Sobrien* Assembler:: Representing @code{asm} with operands. 4190075Sobrien* Insns:: Expression types for entire insns. 4290075Sobrien* Calls:: RTL representation of function call insns. 4390075Sobrien* Sharing:: Some expressions are unique; others *must* be copied. 4490075Sobrien* Reading RTL:: Reading textual RTL from a file. 4590075Sobrien@end menu 4690075Sobrien 4790075Sobrien@node RTL Objects 4890075Sobrien@section RTL Object Types 4990075Sobrien@cindex RTL object types 5090075Sobrien 5190075Sobrien@cindex RTL integers 5290075Sobrien@cindex RTL strings 5390075Sobrien@cindex RTL vectors 5490075Sobrien@cindex RTL expression 5590075Sobrien@cindex RTX (See RTL) 5690075SobrienRTL uses five kinds of objects: expressions, integers, wide integers, 5790075Sobrienstrings and vectors. Expressions are the most important ones. An RTL 5890075Sobrienexpression (``RTX'', for short) is a C structure, but it is usually 5990075Sobrienreferred to with a pointer; a type that is given the typedef name 6090075Sobrien@code{rtx}. 6190075Sobrien 6290075SobrienAn integer is simply an @code{int}; their written form uses decimal 6390075Sobriendigits. A wide integer is an integral object whose type is 6490075Sobrien@code{HOST_WIDE_INT}; their written form uses decimal digits. 6590075Sobrien 6690075SobrienA string is a sequence of characters. In core it is represented as a 6790075Sobrien@code{char *} in usual C fashion, and it is written in C syntax as well. 6890075SobrienHowever, strings in RTL may never be null. If you write an empty string in 6990075Sobriena machine description, it is represented in core as a null pointer rather 7090075Sobrienthan as a pointer to a null character. In certain contexts, these null 7190075Sobrienpointers instead of strings are valid. Within RTL code, strings are most 7290075Sobriencommonly found inside @code{symbol_ref} expressions, but they appear in 7390075Sobrienother contexts in the RTL expressions that make up machine descriptions. 7490075Sobrien 7590075SobrienIn a machine description, strings are normally written with double 76169689Skanquotes, as you would in C@. However, strings in machine descriptions may 7790075Sobrienextend over many lines, which is invalid C, and adjacent string 78169689Skanconstants are not concatenated as they are in C@. Any string constant 7990075Sobrienmay be surrounded with a single set of parentheses. Sometimes this 8090075Sobrienmakes the machine description easier to read. 8190075Sobrien 8290075SobrienThere is also a special syntax for strings, which can be useful when C 8390075Sobriencode is embedded in a machine description. Wherever a string can 8490075Sobrienappear, it is also valid to write a C-style brace block. The entire 8590075Sobrienbrace block, including the outermost pair of braces, is considered to be 8690075Sobrienthe string constant. Double quote characters inside the braces are not 8790075Sobrienspecial. Therefore, if you write string constants in the C code, you 8890075Sobrienneed not escape each quote character with a backslash. 8990075Sobrien 9090075SobrienA vector contains an arbitrary number of pointers to expressions. The 9190075Sobriennumber of elements in the vector is explicitly present in the vector. 9290075SobrienThe written form of a vector consists of square brackets 9390075Sobrien(@samp{[@dots{}]}) surrounding the elements, in sequence and with 9490075Sobrienwhitespace separating them. Vectors of length zero are not created; 9590075Sobriennull pointers are used instead. 9690075Sobrien 9790075Sobrien@cindex expression codes 9890075Sobrien@cindex codes, RTL expression 9990075Sobrien@findex GET_CODE 10090075Sobrien@findex PUT_CODE 10190075SobrienExpressions are classified by @dfn{expression codes} (also called RTX 10290075Sobriencodes). The expression code is a name defined in @file{rtl.def}, which is 103132718Skanalso (in uppercase) a C enumeration constant. The possible expression 10490075Sobriencodes and their meanings are machine-independent. The code of an RTX can 10590075Sobrienbe extracted with the macro @code{GET_CODE (@var{x})} and altered with 10690075Sobrien@code{PUT_CODE (@var{x}, @var{newcode})}. 10790075Sobrien 10890075SobrienThe expression code determines how many operands the expression contains, 10990075Sobrienand what kinds of objects they are. In RTL, unlike Lisp, you cannot tell 11090075Sobrienby looking at an operand what kind of object it is. Instead, you must know 11190075Sobrienfrom its context---from the expression code of the containing expression. 11290075SobrienFor example, in an expression of code @code{subreg}, the first operand is 11390075Sobriento be regarded as an expression and the second operand as an integer. In 11490075Sobrienan expression of code @code{plus}, there are two operands, both of which 11590075Sobrienare to be regarded as expressions. In a @code{symbol_ref} expression, 11690075Sobrienthere is one operand, which is to be regarded as a string. 11790075Sobrien 11890075SobrienExpressions are written as parentheses containing the name of the 11990075Sobrienexpression type, its flags and machine mode if any, and then the operands 12090075Sobrienof the expression (separated by spaces). 12190075Sobrien 122132718SkanExpression code names in the @samp{md} file are written in lowercase, 123132718Skanbut when they appear in C code they are written in uppercase. In this 12490075Sobrienmanual, they are shown as follows: @code{const_int}. 12590075Sobrien 12690075Sobrien@cindex (nil) 12790075Sobrien@cindex nil 12890075SobrienIn a few contexts a null pointer is valid where an expression is normally 12990075Sobrienwanted. The written form of this is @code{(nil)}. 13090075Sobrien 13190075Sobrien@node RTL Classes 13290075Sobrien@section RTL Classes and Formats 13390075Sobrien@cindex RTL classes 13490075Sobrien@cindex classes of RTX codes 13590075Sobrien@cindex RTX codes, classes of 13690075Sobrien@findex GET_RTX_CLASS 13790075Sobrien 13890075SobrienThe various expression codes are divided into several @dfn{classes}, 13990075Sobrienwhich are represented by single characters. You can determine the class 14090075Sobrienof an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}. 141169689SkanCurrently, @file{rtl.def} defines these classes: 14290075Sobrien 14390075Sobrien@table @code 144169689Skan@item RTX_OBJ 14590075SobrienAn RTX code that represents an actual object, such as a register 14690075Sobrien(@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}). 147169689Skan@code{LO_SUM}) is also included; instead, @code{SUBREG} and 148169689Skan@code{STRICT_LOW_PART} are not in this class, but in class @code{x}. 14990075Sobrien 150169689Skan@item RTX_CONST_OBJ 151169689SkanAn RTX code that represents a constant object. @code{HIGH} is also 152169689Skanincluded in this class. 15390075Sobrien 154169689Skan@item RTX_COMPARE 155169689SkanAn RTX code for a non-symmetric comparison, such as @code{GEU} or 156169689Skan@code{LT}. 157169689Skan 158169689Skan@item RTX_COMM_COMPARE 159169689SkanAn RTX code for a symmetric (commutative) comparison, such as @code{EQ} 160169689Skanor @code{ORDERED}. 161169689Skan 162169689Skan@item RTX_UNARY 16390075SobrienAn RTX code for a unary arithmetic operation, such as @code{NEG}, 16490075Sobrien@code{NOT}, or @code{ABS}. This category also includes value extension 16590075Sobrien(sign or zero) and conversions between integer and floating point. 16690075Sobrien 167169689Skan@item RTX_COMM_ARITH 16890075SobrienAn RTX code for a commutative binary operation, such as @code{PLUS} or 16990075Sobrien@code{AND}. @code{NE} and @code{EQ} are comparisons, so they have class 17090075Sobrien@code{<}. 17190075Sobrien 172169689Skan@item RTX_BIN_ARITH 17390075SobrienAn RTX code for a non-commutative binary operation, such as @code{MINUS}, 17490075Sobrien@code{DIV}, or @code{ASHIFTRT}. 17590075Sobrien 176169689Skan@item RTX_BITFIELD_OPS 17790075SobrienAn RTX code for a bit-field operation. Currently only 17890075Sobrien@code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}. These have three inputs 17990075Sobrienand are lvalues (so they can be used for insertion as well). 18090075Sobrien@xref{Bit-Fields}. 18190075Sobrien 182169689Skan@item RTX_TERNARY 18390075SobrienAn RTX code for other three input operations. Currently only 184169689Skan@code{IF_THEN_ELSE} and @code{VEC_MERGE}. 18590075Sobrien 186169689Skan@item RTX_INSN 18790075SobrienAn RTX code for an entire instruction: @code{INSN}, @code{JUMP_INSN}, and 18890075Sobrien@code{CALL_INSN}. @xref{Insns}. 18990075Sobrien 190169689Skan@item RTX_MATCH 19190075SobrienAn RTX code for something that matches in insns, such as 19290075Sobrien@code{MATCH_DUP}. These only occur in machine descriptions. 19390075Sobrien 194169689Skan@item RTX_AUTOINC 19590075SobrienAn RTX code for an auto-increment addressing mode, such as 19690075Sobrien@code{POST_INC}. 19790075Sobrien 198169689Skan@item RTX_EXTRA 19990075SobrienAll other RTX codes. This category includes the remaining codes used 20090075Sobrienonly in machine descriptions (@code{DEFINE_*}, etc.). It also includes 20190075Sobrienall the codes describing side effects (@code{SET}, @code{USE}, 20290075Sobrien@code{CLOBBER}, etc.) and the non-insns that may appear on an insn 20390075Sobrienchain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}. 204169689Skan@code{SUBREG} is also part of this class. 20590075Sobrien@end table 20690075Sobrien 20790075Sobrien@cindex RTL format 20890075SobrienFor each expression code, @file{rtl.def} specifies the number of 20990075Sobriencontained objects and their kinds using a sequence of characters 21090075Sobriencalled the @dfn{format} of the expression code. For example, 21190075Sobrienthe format of @code{subreg} is @samp{ei}. 21290075Sobrien 21390075Sobrien@cindex RTL format characters 21490075SobrienThese are the most commonly used format characters: 21590075Sobrien 21690075Sobrien@table @code 21790075Sobrien@item e 21890075SobrienAn expression (actually a pointer to an expression). 21990075Sobrien 22090075Sobrien@item i 22190075SobrienAn integer. 22290075Sobrien 22390075Sobrien@item w 22490075SobrienA wide integer. 22590075Sobrien 22690075Sobrien@item s 22790075SobrienA string. 22890075Sobrien 22990075Sobrien@item E 23090075SobrienA vector of expressions. 23190075Sobrien@end table 23290075Sobrien 23390075SobrienA few other format characters are used occasionally: 23490075Sobrien 23590075Sobrien@table @code 23690075Sobrien@item u 23790075Sobrien@samp{u} is equivalent to @samp{e} except that it is printed differently 23890075Sobrienin debugging dumps. It is used for pointers to insns. 23990075Sobrien 24090075Sobrien@item n 24190075Sobrien@samp{n} is equivalent to @samp{i} except that it is printed differently 24290075Sobrienin debugging dumps. It is used for the line number or code number of a 24390075Sobrien@code{note} insn. 24490075Sobrien 24590075Sobrien@item S 24690075Sobrien@samp{S} indicates a string which is optional. In the RTL objects in 24790075Sobriencore, @samp{S} is equivalent to @samp{s}, but when the object is read, 24890075Sobrienfrom an @samp{md} file, the string value of this operand may be omitted. 24990075SobrienAn omitted string is taken to be the null string. 25090075Sobrien 25190075Sobrien@item V 25290075Sobrien@samp{V} indicates a vector which is optional. In the RTL objects in 25390075Sobriencore, @samp{V} is equivalent to @samp{E}, but when the object is read 25490075Sobrienfrom an @samp{md} file, the vector value of this operand may be omitted. 25590075SobrienAn omitted vector is effectively the same as a vector of no elements. 25690075Sobrien 257117395Skan@item B 258117395Skan@samp{B} indicates a pointer to basic block structure. 259117395Skan 26090075Sobrien@item 0 26190075Sobrien@samp{0} means a slot whose contents do not fit any normal category. 26290075Sobrien@samp{0} slots are not printed at all in dumps, and are often used in 26390075Sobrienspecial ways by small parts of the compiler. 26490075Sobrien@end table 26590075Sobrien 26690075SobrienThere are macros to get the number of operands and the format 26790075Sobrienof an expression code: 26890075Sobrien 26990075Sobrien@table @code 27090075Sobrien@findex GET_RTX_LENGTH 27190075Sobrien@item GET_RTX_LENGTH (@var{code}) 27290075SobrienNumber of operands of an RTX of code @var{code}. 27390075Sobrien 27490075Sobrien@findex GET_RTX_FORMAT 27590075Sobrien@item GET_RTX_FORMAT (@var{code}) 27690075SobrienThe format of an RTX of code @var{code}, as a C string. 27790075Sobrien@end table 27890075Sobrien 27990075SobrienSome classes of RTX codes always have the same format. For example, it 28090075Sobrienis safe to assume that all comparison operations have format @code{ee}. 28190075Sobrien 28290075Sobrien@table @code 28390075Sobrien@item 1 28490075SobrienAll codes of this class have format @code{e}. 28590075Sobrien 28690075Sobrien@item < 28790075Sobrien@itemx c 28890075Sobrien@itemx 2 28990075SobrienAll codes of these classes have format @code{ee}. 29090075Sobrien 29190075Sobrien@item b 29290075Sobrien@itemx 3 29390075SobrienAll codes of these classes have format @code{eee}. 29490075Sobrien 29590075Sobrien@item i 29690075SobrienAll codes of this class have formats that begin with @code{iuueiee}. 29790075Sobrien@xref{Insns}. Note that not all RTL objects linked onto an insn chain 29890075Sobrienare of class @code{i}. 29990075Sobrien 30090075Sobrien@item o 30190075Sobrien@itemx m 30290075Sobrien@itemx x 30390075SobrienYou can make no assumptions about the format of these codes. 30490075Sobrien@end table 30590075Sobrien 30690075Sobrien@node Accessors 30790075Sobrien@section Access to Operands 30890075Sobrien@cindex accessors 30990075Sobrien@cindex access to operands 31090075Sobrien@cindex operand access 31190075Sobrien 31290075Sobrien@findex XEXP 31390075Sobrien@findex XINT 31490075Sobrien@findex XWINT 31590075Sobrien@findex XSTR 31690075SobrienOperands of expressions are accessed using the macros @code{XEXP}, 31790075Sobrien@code{XINT}, @code{XWINT} and @code{XSTR}. Each of these macros takes 31890075Sobrientwo arguments: an expression-pointer (RTX) and an operand number 31990075Sobrien(counting from zero). Thus, 32090075Sobrien 321132718Skan@smallexample 32290075SobrienXEXP (@var{x}, 2) 323132718Skan@end smallexample 32490075Sobrien 32590075Sobrien@noindent 32690075Sobrienaccesses operand 2 of expression @var{x}, as an expression. 32790075Sobrien 328132718Skan@smallexample 32990075SobrienXINT (@var{x}, 2) 330132718Skan@end smallexample 33190075Sobrien 33290075Sobrien@noindent 33390075Sobrienaccesses the same operand as an integer. @code{XSTR}, used in the same 33490075Sobrienfashion, would access it as a string. 33590075Sobrien 33690075SobrienAny operand can be accessed as an integer, as an expression or as a string. 33790075SobrienYou must choose the correct method of access for the kind of value actually 33890075Sobrienstored in the operand. You would do this based on the expression code of 33990075Sobrienthe containing expression. That is also how you would know how many 34090075Sobrienoperands there are. 34190075Sobrien 34290075SobrienFor example, if @var{x} is a @code{subreg} expression, you know that it has 34390075Sobrientwo operands which can be correctly accessed as @code{XEXP (@var{x}, 0)} 34490075Sobrienand @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you 34590075Sobrienwould get the address of the expression operand but cast as an integer; 34690075Sobrienthat might occasionally be useful, but it would be cleaner to write 34790075Sobrien@code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also 34890075Sobriencompile without error, and would return the second, integer operand cast as 34990075Sobrienan expression pointer, which would probably result in a crash when 35090075Sobrienaccessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either, 35190075Sobrienbut this will access memory past the end of the expression with 35290075Sobrienunpredictable results. 35390075Sobrien 35490075SobrienAccess to operands which are vectors is more complicated. You can use the 35590075Sobrienmacro @code{XVEC} to get the vector-pointer itself, or the macros 35690075Sobrien@code{XVECEXP} and @code{XVECLEN} to access the elements and length of a 35790075Sobrienvector. 35890075Sobrien 35990075Sobrien@table @code 36090075Sobrien@findex XVEC 36190075Sobrien@item XVEC (@var{exp}, @var{idx}) 36290075SobrienAccess the vector-pointer which is operand number @var{idx} in @var{exp}. 36390075Sobrien 36490075Sobrien@findex XVECLEN 36590075Sobrien@item XVECLEN (@var{exp}, @var{idx}) 36690075SobrienAccess the length (number of elements) in the vector which is 36790075Sobrienin operand number @var{idx} in @var{exp}. This value is an @code{int}. 36890075Sobrien 36990075Sobrien@findex XVECEXP 37090075Sobrien@item XVECEXP (@var{exp}, @var{idx}, @var{eltnum}) 37190075SobrienAccess element number @var{eltnum} in the vector which is 37290075Sobrienin operand number @var{idx} in @var{exp}. This value is an RTX@. 37390075Sobrien 37490075SobrienIt is up to you to make sure that @var{eltnum} is not negative 37590075Sobrienand is less than @code{XVECLEN (@var{exp}, @var{idx})}. 37690075Sobrien@end table 37790075Sobrien 37890075SobrienAll the macros defined in this section expand into lvalues and therefore 37990075Sobriencan be used to assign the operands, lengths and vector elements as well as 38090075Sobriento access them. 38190075Sobrien 382132718Skan@node Special Accessors 383132718Skan@section Access to Special Operands 384132718Skan@cindex access to special operands 385132718Skan 386132718SkanSome RTL nodes have special annotations associated with them. 387132718Skan 388132718Skan@table @code 389132718Skan@item MEM 390132718Skan@table @code 391132718Skan@findex MEM_ALIAS_SET 392132718Skan@item MEM_ALIAS_SET (@var{x}) 393132718SkanIf 0, @var{x} is not in any alias set, and may alias anything. Otherwise, 394132718Skan@var{x} can only alias @code{MEM}s in a conflicting alias set. This value 395132718Skanis set in a language-dependent manner in the front-end, and should not be 396132718Skanaltered in the back-end. In some front-ends, these numbers may correspond 397132718Skanin some way to types, or other language-level entities, but they need not, 398132718Skanand the back-end makes no such assumptions. 399132718SkanThese set numbers are tested with @code{alias_sets_conflict_p}. 400132718Skan 401132718Skan@findex MEM_EXPR 402132718Skan@item MEM_EXPR (@var{x}) 403132718SkanIf this register is known to hold the value of some user-level 404132718Skandeclaration, this is that tree node. It may also be a 405132718Skan@code{COMPONENT_REF}, in which case this is some field reference, 406132718Skanand @code{TREE_OPERAND (@var{x}, 0)} contains the declaration, 407132718Skanor another @code{COMPONENT_REF}, or null if there is no compile-time 408132718Skanobject associated with the reference. 409132718Skan 410132718Skan@findex MEM_OFFSET 411132718Skan@item MEM_OFFSET (@var{x}) 412132718SkanThe offset from the start of @code{MEM_EXPR} as a @code{CONST_INT} rtx. 413132718Skan 414132718Skan@findex MEM_SIZE 415132718Skan@item MEM_SIZE (@var{x}) 416132718SkanThe size in bytes of the memory reference as a @code{CONST_INT} rtx. 417132718SkanThis is mostly relevant for @code{BLKmode} references as otherwise 418132718Skanthe size is implied by the mode. 419132718Skan 420132718Skan@findex MEM_ALIGN 421132718Skan@item MEM_ALIGN (@var{x}) 422132718SkanThe known alignment in bits of the memory reference. 423132718Skan@end table 424132718Skan 425132718Skan@item REG 426132718Skan@table @code 427132718Skan@findex ORIGINAL_REGNO 428132718Skan@item ORIGINAL_REGNO (@var{x}) 429132718SkanThis field holds the number the register ``originally'' had; for a 430132718Skanpseudo register turned into a hard reg this will hold the old pseudo 431132718Skanregister number. 432132718Skan 433132718Skan@findex REG_EXPR 434132718Skan@item REG_EXPR (@var{x}) 435132718SkanIf this register is known to hold the value of some user-level 436132718Skandeclaration, this is that tree node. 437132718Skan 438132718Skan@findex REG_OFFSET 439132718Skan@item REG_OFFSET (@var{x}) 440132718SkanIf this register is known to hold the value of some user-level 441132718Skandeclaration, this is the offset into that logical storage. 442132718Skan@end table 443132718Skan 444132718Skan@item SYMBOL_REF 445132718Skan@table @code 446132718Skan@findex SYMBOL_REF_DECL 447132718Skan@item SYMBOL_REF_DECL (@var{x}) 448132718SkanIf the @code{symbol_ref} @var{x} was created for a @code{VAR_DECL} or 449132718Skana @code{FUNCTION_DECL}, that tree is recorded here. If this value is 450132718Skannull, then @var{x} was created by back end code generation routines, 451132718Skanand there is no associated front end symbol table entry. 452132718Skan 453132718Skan@code{SYMBOL_REF_DECL} may also point to a tree of class @code{'c'}, 454132718Skanthat is, some sort of constant. In this case, the @code{symbol_ref} 455132718Skanis an entry in the per-file constant pool; again, there is no associated 456132718Skanfront end symbol table entry. 457132718Skan 458169689Skan@findex SYMBOL_REF_CONSTANT 459169689Skan@item SYMBOL_REF_CONSTANT (@var{x}) 460169689SkanIf @samp{CONSTANT_POOL_ADDRESS_P (@var{x})} is true, this is the constant 461169689Skanpool entry for @var{x}. It is null otherwise. 462169689Skan 463169689Skan@findex SYMBOL_REF_DATA 464169689Skan@item SYMBOL_REF_DATA (@var{x}) 465169689SkanA field of opaque type used to store @code{SYMBOL_REF_DECL} or 466169689Skan@code{SYMBOL_REF_CONSTANT}. 467169689Skan 468132718Skan@findex SYMBOL_REF_FLAGS 469132718Skan@item SYMBOL_REF_FLAGS (@var{x}) 470132718SkanIn a @code{symbol_ref}, this is used to communicate various predicates 471132718Skanabout the symbol. Some of these are common enough to be computed by 472132718Skancommon code, some are specific to the target. The common bits are: 473132718Skan 474132718Skan@table @code 475132718Skan@findex SYMBOL_REF_FUNCTION_P 476132718Skan@findex SYMBOL_FLAG_FUNCTION 477132718Skan@item SYMBOL_FLAG_FUNCTION 478132718SkanSet if the symbol refers to a function. 479132718Skan 480132718Skan@findex SYMBOL_REF_LOCAL_P 481132718Skan@findex SYMBOL_FLAG_LOCAL 482132718Skan@item SYMBOL_FLAG_LOCAL 483132718SkanSet if the symbol is local to this ``module''. 484132718SkanSee @code{TARGET_BINDS_LOCAL_P}. 485132718Skan 486132718Skan@findex SYMBOL_REF_EXTERNAL_P 487132718Skan@findex SYMBOL_FLAG_EXTERNAL 488132718Skan@item SYMBOL_FLAG_EXTERNAL 489132718SkanSet if this symbol is not defined in this translation unit. 490132718SkanNote that this is not the inverse of @code{SYMBOL_FLAG_LOCAL}. 491132718Skan 492132718Skan@findex SYMBOL_REF_SMALL_P 493132718Skan@findex SYMBOL_FLAG_SMALL 494132718Skan@item SYMBOL_FLAG_SMALL 495132718SkanSet if the symbol is located in the small data section. 496132718SkanSee @code{TARGET_IN_SMALL_DATA_P}. 497132718Skan 498132718Skan@findex SYMBOL_FLAG_TLS_SHIFT 499132718Skan@findex SYMBOL_REF_TLS_MODEL 500132718Skan@item SYMBOL_REF_TLS_MODEL (@var{x}) 501132718SkanThis is a multi-bit field accessor that returns the @code{tls_model} 502132718Skanto be used for a thread-local storage symbol. It returns zero for 503132718Skannon-thread-local symbols. 504169689Skan 505169689Skan@findex SYMBOL_REF_HAS_BLOCK_INFO_P 506169689Skan@findex SYMBOL_FLAG_HAS_BLOCK_INFO 507169689Skan@item SYMBOL_FLAG_HAS_BLOCK_INFO 508169689SkanSet if the symbol has @code{SYMBOL_REF_BLOCK} and 509169689Skan@code{SYMBOL_REF_BLOCK_OFFSET} fields. 510169689Skan 511169689Skan@findex SYMBOL_REF_ANCHOR_P 512169689Skan@findex SYMBOL_FLAG_ANCHOR 513169689Skan@cindex @option{-fsection-anchors} 514169689Skan@item SYMBOL_FLAG_ANCHOR 515169689SkanSet if the symbol is used as a section anchor. ``Section anchors'' 516169689Skanare symbols that have a known position within an @code{object_block} 517169689Skanand that can be used to access nearby members of that block. 518169689SkanThey are used to implement @option{-fsection-anchors}. 519169689Skan 520169689SkanIf this flag is set, then @code{SYMBOL_FLAG_HAS_BLOCK_INFO} will be too. 521132718Skan@end table 522132718Skan 523132718SkanBits beginning with @code{SYMBOL_FLAG_MACH_DEP} are available for 524132718Skanthe target's use. 525132718Skan@end table 526169689Skan 527169689Skan@findex SYMBOL_REF_BLOCK 528169689Skan@item SYMBOL_REF_BLOCK (@var{x}) 529169689SkanIf @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the 530169689Skan@samp{object_block} structure to which the symbol belongs, 531169689Skanor @code{NULL} if it has not been assigned a block. 532169689Skan 533169689Skan@findex SYMBOL_REF_BLOCK_OFFSET 534169689Skan@item SYMBOL_REF_BLOCK_OFFSET (@var{x}) 535169689SkanIf @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the offset of @var{x} 536169689Skanfrom the first object in @samp{SYMBOL_REF_BLOCK (@var{x})}. The value is 537169689Skannegative if @var{x} has not yet been assigned to a block, or it has not 538169689Skanbeen given an offset within that block. 539132718Skan@end table 540132718Skan 54190075Sobrien@node Flags 54290075Sobrien@section Flags in an RTL Expression 54390075Sobrien@cindex flags in RTL expression 54490075Sobrien 54590075SobrienRTL expressions contain several flags (one-bit bit-fields) 54690075Sobrienthat are used in certain types of expression. Most often they 547117395Skanare accessed with the following macros, which expand into lvalues. 54890075Sobrien 54990075Sobrien@table @code 55090075Sobrien@findex CONSTANT_POOL_ADDRESS_P 55190075Sobrien@cindex @code{symbol_ref} and @samp{/u} 55290075Sobrien@cindex @code{unchanging}, in @code{symbol_ref} 55390075Sobrien@item CONSTANT_POOL_ADDRESS_P (@var{x}) 55490075SobrienNonzero in a @code{symbol_ref} if it refers to part of the current 55590075Sobrienfunction's constant pool. For most targets these addresses are in a 55690075Sobrien@code{.rodata} section entirely separate from the function, but for 55790075Sobriensome targets the addresses are close to the beginning of the function. 55890075SobrienIn either case GCC assumes these addresses can be addressed directly, 55990075Sobrienperhaps with the help of base registers. 56090075SobrienStored in the @code{unchanging} field and printed as @samp{/u}. 56190075Sobrien 56290075Sobrien@findex CONST_OR_PURE_CALL_P 56390075Sobrien@cindex @code{call_insn} and @samp{/u} 56490075Sobrien@cindex @code{unchanging}, in @code{call_insn} 56590075Sobrien@item CONST_OR_PURE_CALL_P (@var{x}) 56690075SobrienIn a @code{call_insn}, @code{note}, or an @code{expr_list} for notes, 56790075Sobrienindicates that the insn represents a call to a const or pure function. 56890075SobrienStored in the @code{unchanging} field and printed as @samp{/u}. 56990075Sobrien 57090075Sobrien@findex INSN_ANNULLED_BRANCH_P 571117395Skan@cindex @code{jump_insn} and @samp{/u} 572117395Skan@cindex @code{call_insn} and @samp{/u} 57390075Sobrien@cindex @code{insn} and @samp{/u} 574117395Skan@cindex @code{unchanging}, in @code{jump_insn}, @code{call_insn} and @code{insn} 57590075Sobrien@item INSN_ANNULLED_BRANCH_P (@var{x}) 576117395SkanIn a @code{jump_insn}, @code{call_insn}, or @code{insn} indicates 577117395Skanthat the branch is an annulling one. See the discussion under 578169689Skan@code{sequence} below. Stored in the @code{unchanging} field and 579117395Skanprinted as @samp{/u}. 58090075Sobrien 58190075Sobrien@findex INSN_DELETED_P 58290075Sobrien@cindex @code{insn} and @samp{/v} 583117395Skan@cindex @code{call_insn} and @samp{/v} 584117395Skan@cindex @code{jump_insn} and @samp{/v} 585117395Skan@cindex @code{code_label} and @samp{/v} 586117395Skan@cindex @code{barrier} and @samp{/v} 587117395Skan@cindex @code{note} and @samp{/v} 588117395Skan@cindex @code{volatil}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, @code{barrier}, and @code{note} 58990075Sobrien@item INSN_DELETED_P (@var{x}) 590117395SkanIn an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, 591117395Skan@code{barrier}, or @code{note}, 592117395Skannonzero if the insn has been deleted. Stored in the 59390075Sobrien@code{volatil} field and printed as @samp{/v}. 59490075Sobrien 59590075Sobrien@findex INSN_FROM_TARGET_P 59690075Sobrien@cindex @code{insn} and @samp{/s} 597117395Skan@cindex @code{jump_insn} and @samp{/s} 598117395Skan@cindex @code{call_insn} and @samp{/s} 599117395Skan@cindex @code{in_struct}, in @code{insn} and @code{jump_insn} and @code{call_insn} 60090075Sobrien@item INSN_FROM_TARGET_P (@var{x}) 601117395SkanIn an @code{insn} or @code{jump_insn} or @code{call_insn} in a delay 602117395Skanslot of a branch, indicates that the insn 60390075Sobrienis from the target of the branch. If the branch insn has 60490075Sobrien@code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if 60590075Sobrienthe branch is taken. For annulled branches with 60690075Sobrien@code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the 60790075Sobrienbranch is not taken. When @code{INSN_ANNULLED_BRANCH_P} is not set, 60890075Sobrienthis insn will always be executed. Stored in the @code{in_struct} 60990075Sobrienfield and printed as @samp{/s}. 61090075Sobrien 61190075Sobrien@findex LABEL_PRESERVE_P 61290075Sobrien@cindex @code{code_label} and @samp{/i} 613117395Skan@cindex @code{note} and @samp{/i} 614117395Skan@cindex @code{in_struct}, in @code{code_label} and @code{note} 61590075Sobrien@item LABEL_PRESERVE_P (@var{x}) 616117395SkanIn a @code{code_label} or @code{note}, indicates that the label is referenced by 61790075Sobriencode or data not visible to the RTL of a given function. 61890075SobrienLabels referenced by a non-local goto will have this bit set. Stored 61990075Sobrienin the @code{in_struct} field and printed as @samp{/s}. 62090075Sobrien 62190075Sobrien@findex LABEL_REF_NONLOCAL_P 62290075Sobrien@cindex @code{label_ref} and @samp{/v} 623117395Skan@cindex @code{reg_label} and @samp{/v} 624117395Skan@cindex @code{volatil}, in @code{label_ref} and @code{reg_label} 62590075Sobrien@item LABEL_REF_NONLOCAL_P (@var{x}) 62690075SobrienIn @code{label_ref} and @code{reg_label} expressions, nonzero if this is 62790075Sobriena reference to a non-local label. 62890075SobrienStored in the @code{volatil} field and printed as @samp{/v}. 62990075Sobrien 63090075Sobrien@findex MEM_IN_STRUCT_P 63190075Sobrien@cindex @code{mem} and @samp{/s} 63290075Sobrien@cindex @code{in_struct}, in @code{mem} 63390075Sobrien@item MEM_IN_STRUCT_P (@var{x}) 63490075SobrienIn @code{mem} expressions, nonzero for reference to an entire structure, 63590075Sobrienunion or array, or to a component of one. Zero for references to a 63690075Sobrienscalar variable or through a pointer to a scalar. If both this flag and 63790075Sobrien@code{MEM_SCALAR_P} are clear, then we don't know whether this @code{mem} 63890075Sobrienis in a structure or not. Both flags should never be simultaneously set. 63990075SobrienStored in the @code{in_struct} field and printed as @samp{/s}. 64090075Sobrien 64190075Sobrien@findex MEM_KEEP_ALIAS_SET_P 64290075Sobrien@cindex @code{mem} and @samp{/j} 64390075Sobrien@cindex @code{jump}, in @code{mem} 64490075Sobrien@item MEM_KEEP_ALIAS_SET_P (@var{x}) 64590075SobrienIn @code{mem} expressions, 1 if we should keep the alias set for this 64690075Sobrienmem unchanged when we access a component. Set to 1, for example, when we 64790075Sobrienare already in a non-addressable component of an aggregate. 64890075SobrienStored in the @code{jump} field and printed as @samp{/j}. 64990075Sobrien 65090075Sobrien@findex MEM_SCALAR_P 65190075Sobrien@cindex @code{mem} and @samp{/f} 65290075Sobrien@cindex @code{frame_related}, in @code{mem} 65390075Sobrien@item MEM_SCALAR_P (@var{x}) 65490075SobrienIn @code{mem} expressions, nonzero for reference to a scalar known not 65590075Sobriento be a member of a structure, union, or array. Zero for such 65690075Sobrienreferences and for indirections through pointers, even pointers pointing 65796263Sobriento scalar types. If both this flag and @code{MEM_IN_STRUCT_P} are clear, 65896263Sobrienthen we don't know whether this @code{mem} is in a structure or not. 65996263SobrienBoth flags should never be simultaneously set. 66090075SobrienStored in the @code{frame_related} field and printed as @samp{/f}. 66190075Sobrien 66290075Sobrien@findex MEM_VOLATILE_P 66390075Sobrien@cindex @code{mem} and @samp{/v} 664117395Skan@cindex @code{asm_input} and @samp{/v} 665117395Skan@cindex @code{asm_operands} and @samp{/v} 666117395Skan@cindex @code{volatil}, in @code{mem}, @code{asm_operands}, and @code{asm_input} 66790075Sobrien@item MEM_VOLATILE_P (@var{x}) 668117395SkanIn @code{mem}, @code{asm_operands}, and @code{asm_input} expressions, 669117395Skannonzero for volatile memory references. 67090075SobrienStored in the @code{volatil} field and printed as @samp{/v}. 67190075Sobrien 672132718Skan@findex MEM_NOTRAP_P 673132718Skan@cindex @code{mem} and @samp{/c} 674132718Skan@cindex @code{call}, in @code{mem} 675132718Skan@item MEM_NOTRAP_P (@var{x}) 676132718SkanIn @code{mem}, nonzero for memory references that will not trap. 677132718SkanStored in the @code{call} field and printed as @samp{/c}. 678132718Skan 67990075Sobrien@findex REG_FUNCTION_VALUE_P 68090075Sobrien@cindex @code{reg} and @samp{/i} 68190075Sobrien@cindex @code{integrated}, in @code{reg} 68290075Sobrien@item REG_FUNCTION_VALUE_P (@var{x}) 68390075SobrienNonzero in a @code{reg} if it is the place in which this function's 68490075Sobrienvalue is going to be returned. (This happens only in a hard 68590075Sobrienregister.) Stored in the @code{integrated} field and printed as 68690075Sobrien@samp{/i}. 68790075Sobrien 68890075Sobrien@findex REG_POINTER 68990075Sobrien@cindex @code{reg} and @samp{/f} 69090075Sobrien@cindex @code{frame_related}, in @code{reg} 69190075Sobrien@item REG_POINTER (@var{x}) 69290075SobrienNonzero in a @code{reg} if the register holds a pointer. Stored in the 69390075Sobrien@code{frame_related} field and printed as @samp{/f}. 69490075Sobrien 69590075Sobrien@findex REG_USERVAR_P 69690075Sobrien@cindex @code{reg} and @samp{/v} 69790075Sobrien@cindex @code{volatil}, in @code{reg} 69890075Sobrien@item REG_USERVAR_P (@var{x}) 69990075SobrienIn a @code{reg}, nonzero if it corresponds to a variable present in 70090075Sobrienthe user's source code. Zero for temporaries generated internally by 70190075Sobrienthe compiler. Stored in the @code{volatil} field and printed as 70290075Sobrien@samp{/v}. 70390075Sobrien 70490075SobrienThe same hard register may be used also for collecting the values of 70590075Sobrienfunctions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero 70690075Sobrienin this kind of use. 70790075Sobrien 70890075Sobrien@findex RTX_FRAME_RELATED_P 70990075Sobrien@cindex @code{insn} and @samp{/f} 710117395Skan@cindex @code{call_insn} and @samp{/f} 711117395Skan@cindex @code{jump_insn} and @samp{/f} 712117395Skan@cindex @code{barrier} and @samp{/f} 713117395Skan@cindex @code{set} and @samp{/f} 714117395Skan@cindex @code{frame_related}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, and @code{set} 71590075Sobrien@item RTX_FRAME_RELATED_P (@var{x}) 716117395SkanNonzero in an @code{insn}, @code{call_insn}, @code{jump_insn}, 717117395Skan@code{barrier}, or @code{set} which is part of a function prologue 71890075Sobrienand sets the stack pointer, sets the frame pointer, or saves a register. 71990075SobrienThis flag should also be set on an instruction that sets up a temporary 72090075Sobrienregister to use in place of the frame pointer. 72190075SobrienStored in the @code{frame_related} field and printed as @samp{/f}. 72290075Sobrien 72390075SobrienIn particular, on RISC targets where there are limits on the sizes of 72490075Sobrienimmediate constants, it is sometimes impossible to reach the register 72590075Sobriensave area directly from the stack pointer. In that case, a temporary 72690075Sobrienregister is used that is near enough to the register save area, and the 72790075SobrienCanonical Frame Address, i.e., DWARF2's logical frame pointer, register 72890075Sobrienmust (temporarily) be changed to be this temporary register. So, the 72990075Sobrieninstruction that sets this temporary register must be marked as 73090075Sobrien@code{RTX_FRAME_RELATED_P}. 73190075Sobrien 73290075SobrienIf the marked instruction is overly complex (defined in terms of what 73390075Sobrien@code{dwarf2out_frame_debug_expr} can handle), you will also have to 73490075Sobriencreate a @code{REG_FRAME_RELATED_EXPR} note and attach it to the 73590075Sobrieninstruction. This note should contain a simple expression of the 73690075Sobriencomputation performed by this instruction, i.e., one that 73790075Sobrien@code{dwarf2out_frame_debug_expr} can handle. 73890075Sobrien 73990075SobrienThis flag is required for exception handling support on targets with RTL 74090075Sobrienprologues. 74190075Sobrien 74290075Sobrien@cindex @code{insn} and @samp{/i} 743117395Skan@cindex @code{call_insn} and @samp{/i} 744117395Skan@cindex @code{jump_insn} and @samp{/i} 745117395Skan@cindex @code{barrier} and @samp{/i} 746117395Skan@cindex @code{code_label} and @samp{/i} 747117395Skan@cindex @code{insn_list} and @samp{/i} 748117395Skan@cindex @code{const} and @samp{/i} 749117395Skan@cindex @code{note} and @samp{/i} 750117395Skan@cindex @code{integrated}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, @code{code_label}, @code{insn_list}, @code{const}, and @code{note} 751117395Skan@code{code_label}, @code{insn_list}, @code{const}, or @code{note} if it 75290075Sobrienresulted from an in-line function call. 75390075SobrienStored in the @code{integrated} field and printed as @samp{/i}. 75490075Sobrien 755169689Skan@findex MEM_READONLY_P 75690075Sobrien@cindex @code{mem} and @samp{/u} 757169689Skan@cindex @code{unchanging}, in @code{mem} 758169689Skan@item MEM_READONLY_P (@var{x}) 759169689SkanNonzero in a @code{mem}, if the memory is statically allocated and read-only. 760119256Skan 761169689SkanRead-only in this context means never modified during the lifetime of the 762169689Skanprogram, not necessarily in ROM or in write-disabled pages. A common 763169689Skanexample of the later is a shared library's global offset table. This 764169689Skantable is initialized by the runtime loader, so the memory is technically 765169689Skanwritable, but after control is transfered from the runtime loader to the 766169689Skanapplication, this memory will never be subsequently modified. 767119256Skan 76890075SobrienStored in the @code{unchanging} field and printed as @samp{/u}. 76990075Sobrien 77090075Sobrien@findex SCHED_GROUP_P 771117395Skan@cindex @code{insn} and @samp{/s} 772117395Skan@cindex @code{call_insn} and @samp{/s} 773117395Skan@cindex @code{jump_insn} and @samp{/s} 774117395Skan@cindex @code{in_struct}, in @code{insn}, @code{jump_insn} and @code{call_insn} 77590075Sobrien@item SCHED_GROUP_P (@var{x}) 776117395SkanDuring instruction scheduling, in an @code{insn}, @code{call_insn} or 777117395Skan@code{jump_insn}, indicates that the 77890075Sobrienprevious insn must be scheduled together with this insn. This is used to 77990075Sobrienensure that certain groups of instructions will not be split up by the 78090075Sobrieninstruction scheduling pass, for example, @code{use} insns before 78190075Sobriena @code{call_insn} may not be separated from the @code{call_insn}. 78290075SobrienStored in the @code{in_struct} field and printed as @samp{/s}. 78390075Sobrien 78490075Sobrien@findex SET_IS_RETURN_P 78590075Sobrien@cindex @code{insn} and @samp{/j} 78690075Sobrien@cindex @code{jump}, in @code{insn} 78790075Sobrien@item SET_IS_RETURN_P (@var{x}) 78890075SobrienFor a @code{set}, nonzero if it is for a return. 78990075SobrienStored in the @code{jump} field and printed as @samp{/j}. 79090075Sobrien 79190075Sobrien@findex SIBLING_CALL_P 79290075Sobrien@cindex @code{call_insn} and @samp{/j} 79390075Sobrien@cindex @code{jump}, in @code{call_insn} 79490075Sobrien@item SIBLING_CALL_P (@var{x}) 79590075SobrienFor a @code{call_insn}, nonzero if the insn is a sibling call. 79690075SobrienStored in the @code{jump} field and printed as @samp{/j}. 79790075Sobrien 79890075Sobrien@findex STRING_POOL_ADDRESS_P 79990075Sobrien@cindex @code{symbol_ref} and @samp{/f} 80090075Sobrien@cindex @code{frame_related}, in @code{symbol_ref} 80190075Sobrien@item STRING_POOL_ADDRESS_P (@var{x}) 80290075SobrienFor a @code{symbol_ref} expression, nonzero if it addresses this function's 80390075Sobrienstring constant pool. 80490075SobrienStored in the @code{frame_related} field and printed as @samp{/f}. 80590075Sobrien 80690075Sobrien@findex SUBREG_PROMOTED_UNSIGNED_P 807117395Skan@cindex @code{subreg} and @samp{/u} and @samp{/v} 80890075Sobrien@cindex @code{unchanging}, in @code{subreg} 809117395Skan@cindex @code{volatil}, in @code{subreg} 81090075Sobrien@item SUBREG_PROMOTED_UNSIGNED_P (@var{x}) 811117395SkanReturns a value greater then zero for a @code{subreg} that has 812117395Skan@code{SUBREG_PROMOTED_VAR_P} nonzero if the object being referenced is kept 813117395Skanzero-extended, zero if it is kept sign-extended, and less then zero if it is 814117395Skanextended some other way via the @code{ptr_extend} instruction. 815117395SkanStored in the @code{unchanging} 816117395Skanfield and @code{volatil} field, printed as @samp{/u} and @samp{/v}. 817117395SkanThis macro may only be used to get the value it may not be used to change 818117395Skanthe value. Use @code{SUBREG_PROMOTED_UNSIGNED_SET} to change the value. 81990075Sobrien 820117395Skan@findex SUBREG_PROMOTED_UNSIGNED_SET 821117395Skan@cindex @code{subreg} and @samp{/u} 822117395Skan@cindex @code{unchanging}, in @code{subreg} 823117395Skan@cindex @code{volatil}, in @code{subreg} 824117395Skan@item SUBREG_PROMOTED_UNSIGNED_SET (@var{x}) 825117395SkanSet the @code{unchanging} and @code{volatil} fields in a @code{subreg} 826117395Skanto reflect zero, sign, or other extension. If @code{volatil} is 827117395Skanzero, then @code{unchanging} as nonzero means zero extension and as 828169689Skanzero means sign extension. If @code{volatil} is nonzero then some 829117395Skanother type of extension was done via the @code{ptr_extend} instruction. 830117395Skan 83190075Sobrien@findex SUBREG_PROMOTED_VAR_P 83290075Sobrien@cindex @code{subreg} and @samp{/s} 83390075Sobrien@cindex @code{in_struct}, in @code{subreg} 83490075Sobrien@item SUBREG_PROMOTED_VAR_P (@var{x}) 83590075SobrienNonzero in a @code{subreg} if it was made when accessing an object that 83690075Sobrienwas promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine 83790075Sobriendescription macro (@pxref{Storage Layout}). In this case, the mode of 83890075Sobrienthe @code{subreg} is the declared mode of the object and the mode of 83990075Sobrien@code{SUBREG_REG} is the mode of the register that holds the object. 84090075SobrienPromoted variables are always either sign- or zero-extended to the wider 84190075Sobrienmode on every assignment. Stored in the @code{in_struct} field and 84290075Sobrienprinted as @samp{/s}. 84390075Sobrien 84490075Sobrien@findex SYMBOL_REF_USED 84590075Sobrien@cindex @code{used}, in @code{symbol_ref} 84690075Sobrien@item SYMBOL_REF_USED (@var{x}) 84790075SobrienIn a @code{symbol_ref}, indicates that @var{x} has been used. This is 84890075Sobriennormally only used to ensure that @var{x} is only declared external 84990075Sobrienonce. Stored in the @code{used} field. 85090075Sobrien 85190075Sobrien@findex SYMBOL_REF_WEAK 85290075Sobrien@cindex @code{symbol_ref} and @samp{/i} 85390075Sobrien@cindex @code{integrated}, in @code{symbol_ref} 85490075Sobrien@item SYMBOL_REF_WEAK (@var{x}) 85590075SobrienIn a @code{symbol_ref}, indicates that @var{x} has been declared weak. 85690075SobrienStored in the @code{integrated} field and printed as @samp{/i}. 857119256Skan 858119256Skan@findex SYMBOL_REF_FLAG 859119256Skan@cindex @code{symbol_ref} and @samp{/v} 860119256Skan@cindex @code{volatil}, in @code{symbol_ref} 861119256Skan@item SYMBOL_REF_FLAG (@var{x}) 862119256SkanIn a @code{symbol_ref}, this is used as a flag for machine-specific purposes. 863119256SkanStored in the @code{volatil} field and printed as @samp{/v}. 864119256Skan 865119256SkanMost uses of @code{SYMBOL_REF_FLAG} are historic and may be subsumed 866119256Skanby @code{SYMBOL_REF_FLAGS}. Certainly use of @code{SYMBOL_REF_FLAGS} 867119256Skanis mandatory if the target requires more than one bit of storage. 86890075Sobrien@end table 86990075Sobrien 87090075SobrienThese are the fields to which the above macros refer: 87190075Sobrien 87290075Sobrien@table @code 87390075Sobrien@findex call 87490075Sobrien@cindex @samp{/c} in RTL dump 87590075Sobrien@item call 876132718SkanIn a @code{mem}, 1 means that the memory reference will not trap. 87790075Sobrien 87890075SobrienIn an RTL dump, this flag is represented as @samp{/c}. 87990075Sobrien 88090075Sobrien@findex frame_related 88190075Sobrien@cindex @samp{/f} in RTL dump 88290075Sobrien@item frame_related 88390075SobrienIn an @code{insn} or @code{set} expression, 1 means that it is part of 88490075Sobriena function prologue and sets the stack pointer, sets the frame pointer, 88590075Sobriensaves a register, or sets up a temporary register to use in place of the 88690075Sobrienframe pointer. 88790075Sobrien 88890075SobrienIn @code{reg} expressions, 1 means that the register holds a pointer. 88990075Sobrien 89090075SobrienIn @code{symbol_ref} expressions, 1 means that the reference addresses 89190075Sobrienthis function's string constant pool. 89290075Sobrien 89390075SobrienIn @code{mem} expressions, 1 means that the reference is to a scalar. 89490075Sobrien 89590075SobrienIn an RTL dump, this flag is represented as @samp{/f}. 89690075Sobrien 89790075Sobrien@findex in_struct 89890075Sobrien@cindex @samp{/s} in RTL dump 89990075Sobrien@item in_struct 90090075SobrienIn @code{mem} expressions, it is 1 if the memory datum referred to is 90190075Sobrienall or part of a structure or array; 0 if it is (or might be) a scalar 90290075Sobrienvariable. A reference through a C pointer has 0 because the pointer 90390075Sobrienmight point to a scalar variable. This information allows the compiler 90490075Sobriento determine something about possible cases of aliasing. 90590075Sobrien 90690075SobrienIn @code{reg} expressions, it is 1 if the register has its entire life 90790075Sobriencontained within the test expression of some loop. 90890075Sobrien 90990075SobrienIn @code{subreg} expressions, 1 means that the @code{subreg} is accessing 91090075Sobrienan object that has had its mode promoted from a wider mode. 91190075Sobrien 91290075SobrienIn @code{label_ref} expressions, 1 means that the referenced label is 91390075Sobrienoutside the innermost loop containing the insn in which the @code{label_ref} 91490075Sobrienwas found. 91590075Sobrien 91690075SobrienIn @code{code_label} expressions, it is 1 if the label may never be deleted. 91790075SobrienThis is used for labels which are the target of non-local gotos. Such a 91890075Sobrienlabel that would have been deleted is replaced with a @code{note} of type 91990075Sobrien@code{NOTE_INSN_DELETED_LABEL}. 92090075Sobrien 92190075SobrienIn an @code{insn} during dead-code elimination, 1 means that the insn is 92290075Sobriendead code. 92390075Sobrien 924117395SkanIn an @code{insn} or @code{jump_insn} during reorg for an insn in the 925117395Skandelay slot of a branch, 92690075Sobrien1 means that this insn is from the target of the branch. 92790075Sobrien 92890075SobrienIn an @code{insn} during instruction scheduling, 1 means that this insn 92990075Sobrienmust be scheduled as part of a group together with the previous insn. 93090075Sobrien 93190075SobrienIn an RTL dump, this flag is represented as @samp{/s}. 93290075Sobrien 93390075Sobrien@findex integrated 93490075Sobrien@cindex @samp{/i} in RTL dump 93590075Sobrien@item integrated 93690075SobrienIn an @code{insn}, @code{insn_list}, or @code{const}, 1 means the RTL was 93790075Sobrienproduced by procedure integration. 93890075Sobrien 93990075SobrienIn @code{reg} expressions, 1 means the register contains 94090075Sobrienthe value to be returned by the current function. On 94190075Sobrienmachines that pass parameters in registers, the same register number 94290075Sobrienmay be used for parameters as well, but this flag is not set on such 94390075Sobrienuses. 94490075Sobrien 94590075SobrienIn @code{symbol_ref} expressions, 1 means the referenced symbol is weak. 94690075Sobrien 94790075SobrienIn an RTL dump, this flag is represented as @samp{/i}. 94890075Sobrien 94990075Sobrien@findex jump 95090075Sobrien@cindex @samp{/j} in RTL dump 95190075Sobrien@item jump 95290075SobrienIn a @code{mem} expression, 1 means we should keep the alias set for this 95390075Sobrienmem unchanged when we access a component. 95490075Sobrien 95590075SobrienIn a @code{set}, 1 means it is for a return. 95690075Sobrien 95790075SobrienIn a @code{call_insn}, 1 means it is a sibling call. 95890075Sobrien 95990075SobrienIn an RTL dump, this flag is represented as @samp{/j}. 96090075Sobrien 96190075Sobrien@findex unchanging 96290075Sobrien@cindex @samp{/u} in RTL dump 96390075Sobrien@item unchanging 96490075SobrienIn @code{reg} and @code{mem} expressions, 1 means 96590075Sobrienthat the value of the expression never changes. 96690075Sobrien 96790075SobrienIn @code{subreg} expressions, it is 1 if the @code{subreg} references an 96890075Sobrienunsigned object whose mode has been promoted to a wider mode. 96990075Sobrien 970117395SkanIn an @code{insn} or @code{jump_insn} in the delay slot of a branch 971117395Skaninstruction, 1 means an annulling branch should be used. 97290075Sobrien 97390075SobrienIn a @code{symbol_ref} expression, 1 means that this symbol addresses 97490075Sobriensomething in the per-function constant pool. 97590075Sobrien 97690075SobrienIn a @code{call_insn}, @code{note}, or an @code{expr_list} of notes, 97790075Sobrien1 means that this instruction is a call to a const or pure function. 97890075Sobrien 97990075SobrienIn an RTL dump, this flag is represented as @samp{/u}. 98090075Sobrien 98190075Sobrien@findex used 98290075Sobrien@item used 98390075SobrienThis flag is used directly (without an access macro) at the end of RTL 98490075Sobriengeneration for a function, to count the number of times an expression 98590075Sobrienappears in insns. Expressions that appear more than once are copied, 98690075Sobrienaccording to the rules for shared structure (@pxref{Sharing}). 98790075Sobrien 98890075SobrienFor a @code{reg}, it is used directly (without an access macro) by the 98990075Sobrienleaf register renumbering code to ensure that each register is only 99090075Sobrienrenumbered once. 99190075Sobrien 99290075SobrienIn a @code{symbol_ref}, it indicates that an external declaration for 99390075Sobrienthe symbol has already been written. 99490075Sobrien 99590075Sobrien@findex volatil 99690075Sobrien@cindex @samp{/v} in RTL dump 99790075Sobrien@item volatil 99890075Sobrien@cindex volatile memory references 999117395SkanIn a @code{mem}, @code{asm_operands}, or @code{asm_input} 1000117395Skanexpression, it is 1 if the memory 100190075Sobrienreference is volatile. Volatile memory references may not be deleted, 100290075Sobrienreordered or combined. 100390075Sobrien 100490075SobrienIn a @code{symbol_ref} expression, it is used for machine-specific 100590075Sobrienpurposes. 100690075Sobrien 100790075SobrienIn a @code{reg} expression, it is 1 if the value is a user-level variable. 100890075Sobrien0 indicates an internal compiler temporary. 100990075Sobrien 101090075SobrienIn an @code{insn}, 1 means the insn has been deleted. 101190075Sobrien 101290075SobrienIn @code{label_ref} and @code{reg_label} expressions, 1 means a reference 101390075Sobriento a non-local label. 101490075Sobrien 101590075SobrienIn an RTL dump, this flag is represented as @samp{/v}. 101690075Sobrien@end table 101790075Sobrien 101890075Sobrien@node Machine Modes 101990075Sobrien@section Machine Modes 102090075Sobrien@cindex machine modes 102190075Sobrien 102290075Sobrien@findex enum machine_mode 102390075SobrienA machine mode describes a size of data object and the representation used 102490075Sobrienfor it. In the C code, machine modes are represented by an enumeration 102590075Sobrientype, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL 102690075Sobrienexpression has room for a machine mode and so do certain kinds of tree 102790075Sobrienexpressions (declarations and types, to be precise). 102890075Sobrien 102990075SobrienIn debugging dumps and machine descriptions, the machine mode of an RTL 103090075Sobrienexpression is written after the expression code with a colon to separate 103190075Sobrienthem. The letters @samp{mode} which appear at the end of each machine mode 103290075Sobrienname are omitted. For example, @code{(reg:SI 38)} is a @code{reg} 103390075Sobrienexpression with machine mode @code{SImode}. If the mode is 103490075Sobrien@code{VOIDmode}, it is not written at all. 103590075Sobrien 103690075SobrienHere is a table of machine modes. The term ``byte'' below refers to an 103790075Sobrienobject of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}). 103890075Sobrien 103990075Sobrien@table @code 104090075Sobrien@findex BImode 104190075Sobrien@item BImode 104290075Sobrien``Bit'' mode represents a single bit, for predicate registers. 104390075Sobrien 104490075Sobrien@findex QImode 104590075Sobrien@item QImode 104690075Sobrien``Quarter-Integer'' mode represents a single byte treated as an integer. 104790075Sobrien 104890075Sobrien@findex HImode 104990075Sobrien@item HImode 105090075Sobrien``Half-Integer'' mode represents a two-byte integer. 105190075Sobrien 105290075Sobrien@findex PSImode 105390075Sobrien@item PSImode 105490075Sobrien``Partial Single Integer'' mode represents an integer which occupies 105590075Sobrienfour bytes but which doesn't really use all four. On some machines, 105690075Sobrienthis is the right mode to use for pointers. 105790075Sobrien 105890075Sobrien@findex SImode 105990075Sobrien@item SImode 106090075Sobrien``Single Integer'' mode represents a four-byte integer. 106190075Sobrien 106290075Sobrien@findex PDImode 106390075Sobrien@item PDImode 106490075Sobrien``Partial Double Integer'' mode represents an integer which occupies 106590075Sobrieneight bytes but which doesn't really use all eight. On some machines, 106690075Sobrienthis is the right mode to use for certain pointers. 106790075Sobrien 106890075Sobrien@findex DImode 106990075Sobrien@item DImode 107090075Sobrien``Double Integer'' mode represents an eight-byte integer. 107190075Sobrien 107290075Sobrien@findex TImode 107390075Sobrien@item TImode 107490075Sobrien``Tetra Integer'' (?) mode represents a sixteen-byte integer. 107590075Sobrien 107690075Sobrien@findex OImode 107790075Sobrien@item OImode 107890075Sobrien``Octa Integer'' (?) mode represents a thirty-two-byte integer. 107990075Sobrien 108090075Sobrien@findex QFmode 108190075Sobrien@item QFmode 108290075Sobrien``Quarter-Floating'' mode represents a quarter-precision (single byte) 108390075Sobrienfloating point number. 108490075Sobrien 108590075Sobrien@findex HFmode 108690075Sobrien@item HFmode 108790075Sobrien``Half-Floating'' mode represents a half-precision (two byte) floating 108890075Sobrienpoint number. 108990075Sobrien 109090075Sobrien@findex TQFmode 109190075Sobrien@item TQFmode 109290075Sobrien``Three-Quarter-Floating'' (?) mode represents a three-quarter-precision 109390075Sobrien(three byte) floating point number. 109490075Sobrien 109590075Sobrien@findex SFmode 109690075Sobrien@item SFmode 109790075Sobrien``Single Floating'' mode represents a four byte floating point number. 109890075SobrienIn the common case, of a processor with IEEE arithmetic and 8-bit bytes, 109990075Sobrienthis is a single-precision IEEE floating point number; it can also be 110090075Sobrienused for double-precision (on processors with 16-bit bytes) and 110190075Sobriensingle-precision VAX and IBM types. 110290075Sobrien 110390075Sobrien@findex DFmode 110490075Sobrien@item DFmode 110590075Sobrien``Double Floating'' mode represents an eight byte floating point number. 110690075SobrienIn the common case, of a processor with IEEE arithmetic and 8-bit bytes, 110790075Sobrienthis is a double-precision IEEE floating point number. 110890075Sobrien 110990075Sobrien@findex XFmode 111090075Sobrien@item XFmode 1111169689Skan``Extended Floating'' mode represents an IEEE extended floating point 1112169689Skannumber. This mode only has 80 meaningful bits (ten bytes). Some 1113169689Skanprocessors require such numbers to be padded to twelve bytes, others 1114169689Skanto sixteen; this mode is used for either. 111590075Sobrien 1116169689Skan@findex SDmode 1117169689Skan@item SDmode 1118169689Skan``Single Decimal Floating'' mode represents a four byte decimal 1119169689Skanfloating point number (as distinct from conventional binary floating 1120169689Skanpoint). 1121169689Skan 1122169689Skan@findex DDmode 1123169689Skan@item DDmode 1124169689Skan``Double Decimal Floating'' mode represents an eight byte decimal 1125169689Skanfloating point number. 1126169689Skan 1127169689Skan@findex TDmode 1128169689Skan@item TDmode 1129169689Skan``Tetra Decimal Floating'' mode represents a sixteen byte decimal 1130169689Skanfloating point number all 128 of whose bits are meaningful. 1131169689Skan 113290075Sobrien@findex TFmode 113390075Sobrien@item TFmode 1134169689Skan``Tetra Floating'' mode represents a sixteen byte floating point number 1135169689Skanall 128 of whose bits are meaningful. One common use is the 1136169689SkanIEEE quad-precision format. 113790075Sobrien 113890075Sobrien@findex CCmode 113990075Sobrien@item CCmode 114090075Sobrien``Condition Code'' mode represents the value of a condition code, which 114190075Sobrienis a machine-specific set of bits used to represent the result of a 114290075Sobriencomparison operation. Other machine-specific modes may also be used for 114390075Sobrienthe condition code. These modes are not used on machines that use 114490075Sobrien@code{cc0} (see @pxref{Condition Code}). 114590075Sobrien 114690075Sobrien@findex BLKmode 114790075Sobrien@item BLKmode 114890075Sobrien``Block'' mode represents values that are aggregates to which none of 114990075Sobrienthe other modes apply. In RTL, only memory references can have this mode, 115090075Sobrienand only if they appear in string-move or vector instructions. On machines 115190075Sobrienwhich have no such instructions, @code{BLKmode} will not appear in RTL@. 115290075Sobrien 115390075Sobrien@findex VOIDmode 115490075Sobrien@item VOIDmode 115590075SobrienVoid mode means the absence of a mode or an unspecified mode. 115690075SobrienFor example, RTL expressions of code @code{const_int} have mode 115790075Sobrien@code{VOIDmode} because they can be taken to have whatever mode the context 115890075Sobrienrequires. In debugging dumps of RTL, @code{VOIDmode} is expressed by 115990075Sobrienthe absence of any mode. 116090075Sobrien 116190075Sobrien@findex QCmode 116290075Sobrien@findex HCmode 116390075Sobrien@findex SCmode 116490075Sobrien@findex DCmode 116590075Sobrien@findex XCmode 116690075Sobrien@findex TCmode 116790075Sobrien@item QCmode, HCmode, SCmode, DCmode, XCmode, TCmode 116890075SobrienThese modes stand for a complex number represented as a pair of floating 116990075Sobrienpoint values. The floating point values are in @code{QFmode}, 117090075Sobrien@code{HFmode}, @code{SFmode}, @code{DFmode}, @code{XFmode}, and 117190075Sobrien@code{TFmode}, respectively. 117290075Sobrien 117390075Sobrien@findex CQImode 117490075Sobrien@findex CHImode 117590075Sobrien@findex CSImode 117690075Sobrien@findex CDImode 117790075Sobrien@findex CTImode 117890075Sobrien@findex COImode 117990075Sobrien@item CQImode, CHImode, CSImode, CDImode, CTImode, COImode 118090075SobrienThese modes stand for a complex number represented as a pair of integer 118190075Sobrienvalues. The integer values are in @code{QImode}, @code{HImode}, 118290075Sobrien@code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode}, 118390075Sobrienrespectively. 118490075Sobrien@end table 118590075Sobrien 118690075SobrienThe machine description defines @code{Pmode} as a C macro which expands 118790075Sobrieninto the machine mode used for addresses. Normally this is the mode 118890075Sobrienwhose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines. 118990075Sobrien 119090075SobrienThe only modes which a machine description @i{must} support are 119190075Sobrien@code{QImode}, and the modes corresponding to @code{BITS_PER_WORD}, 119290075Sobrien@code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}. 119390075SobrienThe compiler will attempt to use @code{DImode} for 8-byte structures and 119490075Sobrienunions, but this can be prevented by overriding the definition of 119590075Sobrien@code{MAX_FIXED_MODE_SIZE}. Alternatively, you can have the compiler 119690075Sobrienuse @code{TImode} for 16-byte structures and unions. Likewise, you can 119790075Sobrienarrange for the C type @code{short int} to avoid using @code{HImode}. 119890075Sobrien 119990075Sobrien@cindex mode classes 120090075SobrienVery few explicit references to machine modes remain in the compiler and 120190075Sobrienthese few references will soon be removed. Instead, the machine modes 120290075Sobrienare divided into mode classes. These are represented by the enumeration 120390075Sobrientype @code{enum mode_class} defined in @file{machmode.h}. The possible 120490075Sobrienmode classes are: 120590075Sobrien 120690075Sobrien@table @code 120790075Sobrien@findex MODE_INT 120890075Sobrien@item MODE_INT 120990075SobrienInteger modes. By default these are @code{BImode}, @code{QImode}, 121090075Sobrien@code{HImode}, @code{SImode}, @code{DImode}, @code{TImode}, and 121190075Sobrien@code{OImode}. 121290075Sobrien 121390075Sobrien@findex MODE_PARTIAL_INT 121490075Sobrien@item MODE_PARTIAL_INT 121590075SobrienThe ``partial integer'' modes, @code{PQImode}, @code{PHImode}, 121690075Sobrien@code{PSImode} and @code{PDImode}. 121790075Sobrien 121890075Sobrien@findex MODE_FLOAT 121990075Sobrien@item MODE_FLOAT 122090075SobrienFloating point modes. By default these are @code{QFmode}, 122190075Sobrien@code{HFmode}, @code{TQFmode}, @code{SFmode}, @code{DFmode}, 122290075Sobrien@code{XFmode} and @code{TFmode}. 122390075Sobrien 1224169689Skan@findex MODE_DECIMAL_FLOAT 1225169689Skan@item MODE_DECIMAL_FLOAT 1226169689SkanDecimal floating point modes. By default these are @code{SDmode}, 1227169689Skan@code{DDmode} and @code{TDmode}. 1228169689Skan 122990075Sobrien@findex MODE_COMPLEX_INT 123090075Sobrien@item MODE_COMPLEX_INT 123190075SobrienComplex integer modes. (These are not currently implemented). 123290075Sobrien 123390075Sobrien@findex MODE_COMPLEX_FLOAT 123490075Sobrien@item MODE_COMPLEX_FLOAT 123590075SobrienComplex floating point modes. By default these are @code{QCmode}, 123690075Sobrien@code{HCmode}, @code{SCmode}, @code{DCmode}, @code{XCmode}, and 123790075Sobrien@code{TCmode}. 123890075Sobrien 123990075Sobrien@findex MODE_FUNCTION 124090075Sobrien@item MODE_FUNCTION 124190075SobrienAlgol or Pascal function variables including a static chain. 124290075Sobrien(These are not currently implemented). 124390075Sobrien 124490075Sobrien@findex MODE_CC 124590075Sobrien@item MODE_CC 124690075SobrienModes representing condition code values. These are @code{CCmode} plus 1247169689Skanany @code{CC_MODE} modes listed in the @file{@var{machine}-modes.def}. 1248169689Skan@xref{Jump Patterns}, 124990075Sobrienalso see @ref{Condition Code}. 125090075Sobrien 125190075Sobrien@findex MODE_RANDOM 125290075Sobrien@item MODE_RANDOM 125390075SobrienThis is a catchall mode class for modes which don't fit into the above 125490075Sobrienclasses. Currently @code{VOIDmode} and @code{BLKmode} are in 125590075Sobrien@code{MODE_RANDOM}. 125690075Sobrien@end table 125790075Sobrien 125890075SobrienHere are some C macros that relate to machine modes: 125990075Sobrien 126090075Sobrien@table @code 126190075Sobrien@findex GET_MODE 126290075Sobrien@item GET_MODE (@var{x}) 126390075SobrienReturns the machine mode of the RTX @var{x}. 126490075Sobrien 126590075Sobrien@findex PUT_MODE 126690075Sobrien@item PUT_MODE (@var{x}, @var{newmode}) 126790075SobrienAlters the machine mode of the RTX @var{x} to be @var{newmode}. 126890075Sobrien 126990075Sobrien@findex NUM_MACHINE_MODES 127090075Sobrien@item NUM_MACHINE_MODES 127190075SobrienStands for the number of machine modes available on the target 127290075Sobrienmachine. This is one greater than the largest numeric value of any 127390075Sobrienmachine mode. 127490075Sobrien 127590075Sobrien@findex GET_MODE_NAME 127690075Sobrien@item GET_MODE_NAME (@var{m}) 127790075SobrienReturns the name of mode @var{m} as a string. 127890075Sobrien 127990075Sobrien@findex GET_MODE_CLASS 128090075Sobrien@item GET_MODE_CLASS (@var{m}) 128190075SobrienReturns the mode class of mode @var{m}. 128290075Sobrien 128390075Sobrien@findex GET_MODE_WIDER_MODE 128490075Sobrien@item GET_MODE_WIDER_MODE (@var{m}) 128590075SobrienReturns the next wider natural mode. For example, the expression 128690075Sobrien@code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}. 128790075Sobrien 128890075Sobrien@findex GET_MODE_SIZE 128990075Sobrien@item GET_MODE_SIZE (@var{m}) 129090075SobrienReturns the size in bytes of a datum of mode @var{m}. 129190075Sobrien 129290075Sobrien@findex GET_MODE_BITSIZE 129390075Sobrien@item GET_MODE_BITSIZE (@var{m}) 129490075SobrienReturns the size in bits of a datum of mode @var{m}. 129590075Sobrien 129690075Sobrien@findex GET_MODE_MASK 129790075Sobrien@item GET_MODE_MASK (@var{m}) 129890075SobrienReturns a bitmask containing 1 for all bits in a word that fit within 129990075Sobrienmode @var{m}. This macro can only be used for modes whose bitsize is 130090075Sobrienless than or equal to @code{HOST_BITS_PER_INT}. 130190075Sobrien 130290075Sobrien@findex GET_MODE_ALIGNMENT 130390075Sobrien@item GET_MODE_ALIGNMENT (@var{m}) 130490075SobrienReturn the required alignment, in bits, for an object of mode @var{m}. 130590075Sobrien 130690075Sobrien@findex GET_MODE_UNIT_SIZE 130790075Sobrien@item GET_MODE_UNIT_SIZE (@var{m}) 130890075SobrienReturns the size in bytes of the subunits of a datum of mode @var{m}. 130990075SobrienThis is the same as @code{GET_MODE_SIZE} except in the case of complex 131090075Sobrienmodes. For them, the unit size is the size of the real or imaginary 131190075Sobrienpart. 131290075Sobrien 131390075Sobrien@findex GET_MODE_NUNITS 131490075Sobrien@item GET_MODE_NUNITS (@var{m}) 131590075SobrienReturns the number of units contained in a mode, i.e., 131690075Sobrien@code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}. 131790075Sobrien 131890075Sobrien@findex GET_CLASS_NARROWEST_MODE 131990075Sobrien@item GET_CLASS_NARROWEST_MODE (@var{c}) 132090075SobrienReturns the narrowest mode in mode class @var{c}. 132190075Sobrien@end table 132290075Sobrien 132390075Sobrien@findex byte_mode 132490075Sobrien@findex word_mode 132590075SobrienThe global variables @code{byte_mode} and @code{word_mode} contain modes 132690075Sobrienwhose classes are @code{MODE_INT} and whose bitsizes are either 132790075Sobrien@code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit 132890075Sobrienmachines, these are @code{QImode} and @code{SImode}, respectively. 132990075Sobrien 133090075Sobrien@node Constants 133190075Sobrien@section Constant Expression Types 133290075Sobrien@cindex RTL constants 133390075Sobrien@cindex RTL constant expression types 133490075Sobrien 133590075SobrienThe simplest RTL expressions are those that represent constant values. 133690075Sobrien 133790075Sobrien@table @code 133890075Sobrien@findex const_int 133990075Sobrien@item (const_int @var{i}) 134090075SobrienThis type of expression represents the integer value @var{i}. @var{i} 134190075Sobrienis customarily accessed with the macro @code{INTVAL} as in 134290075Sobrien@code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}. 134390075Sobrien 1344169689SkanConstants generated for modes with fewer bits than @code{HOST_WIDE_INT} 1345169689Skanmust be sign extended to full width (e.g., with @code{gen_int_mode}). 1346169689Skan 134790075Sobrien@findex const0_rtx 134890075Sobrien@findex const1_rtx 134990075Sobrien@findex const2_rtx 135090075Sobrien@findex constm1_rtx 135190075SobrienThere is only one expression object for the integer value zero; it is 135290075Sobrienthe value of the variable @code{const0_rtx}. Likewise, the only 135390075Sobrienexpression for integer value one is found in @code{const1_rtx}, the only 135490075Sobrienexpression for integer value two is found in @code{const2_rtx}, and the 135590075Sobrienonly expression for integer value negative one is found in 135690075Sobrien@code{constm1_rtx}. Any attempt to create an expression of code 135790075Sobrien@code{const_int} and value zero, one, two or negative one will return 135890075Sobrien@code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or 135990075Sobrien@code{constm1_rtx} as appropriate. 136090075Sobrien 136190075Sobrien@findex const_true_rtx 136290075SobrienSimilarly, there is only one object for the integer whose value is 136390075Sobrien@code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If 136490075Sobrien@code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and 136590075Sobrien@code{const1_rtx} will point to the same object. If 136690075Sobrien@code{STORE_FLAG_VALUE} is @minus{}1, @code{const_true_rtx} and 136790075Sobrien@code{constm1_rtx} will point to the same object. 136890075Sobrien 136990075Sobrien@findex const_double 137090075Sobrien@item (const_double:@var{m} @var{addr} @var{i0} @var{i1} @dots{}) 137190075SobrienRepresents either a floating-point constant of mode @var{m} or an 137290075Sobrieninteger constant too large to fit into @code{HOST_BITS_PER_WIDE_INT} 137390075Sobrienbits but small enough to fit within twice that number of bits (GCC 137490075Sobriendoes not provide a mechanism to represent even larger constants). In 137590075Sobrienthe latter case, @var{m} will be @code{VOIDmode}. 137690075Sobrien 137796263Sobrien@findex const_vector 137896263Sobrien@item (const_vector:@var{m} [@var{x0} @var{x1} @dots{}]) 137996263SobrienRepresents a vector constant. The square brackets stand for the vector 138096263Sobriencontaining the constant elements. @var{x0}, @var{x1} and so on are 138196263Sobrienthe @code{const_int} or @code{const_double} elements. 138296263Sobrien 138396263SobrienThe number of units in a @code{const_vector} is obtained with the macro 138496263Sobrien@code{CONST_VECTOR_NUNITS} as in @code{CONST_VECTOR_NUNITS (@var{v})}. 138596263Sobrien 138696263SobrienIndividual elements in a vector constant are accessed with the macro 138796263Sobrien@code{CONST_VECTOR_ELT} as in @code{CONST_VECTOR_ELT (@var{v}, @var{n})} 138896263Sobrienwhere @var{v} is the vector constant and @var{n} is the element 138996263Sobriendesired. 139096263Sobrien 139190075Sobrien@findex CONST_DOUBLE_MEM 139290075Sobrien@findex CONST_DOUBLE_CHAIN 139390075Sobrien@var{addr} is used to contain the @code{mem} expression that corresponds 139490075Sobriento the location in memory that at which the constant can be found. If 139590075Sobrienit has not been allocated a memory location, but is on the chain of all 139690075Sobrien@code{const_double} expressions in this compilation (maintained using an 139790075Sobrienundisplayed field), @var{addr} contains @code{const0_rtx}. If it is not 139890075Sobrienon the chain, @var{addr} contains @code{cc0_rtx}. @var{addr} is 139990075Sobriencustomarily accessed with the macro @code{CONST_DOUBLE_MEM} and the 140090075Sobrienchain field via @code{CONST_DOUBLE_CHAIN}. 140190075Sobrien 140290075Sobrien@findex CONST_DOUBLE_LOW 140390075SobrienIf @var{m} is @code{VOIDmode}, the bits of the value are stored in 140490075Sobrien@var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro 140590075Sobrien@code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}. 140690075Sobrien 140790075SobrienIf the constant is floating point (regardless of its precision), then 140890075Sobrienthe number of integers used to store the value depends on the size of 1409117395Skan@code{REAL_VALUE_TYPE} (@pxref{Floating Point}). The integers 141090075Sobrienrepresent a floating point number, but not precisely in the target 141190075Sobrienmachine's or host machine's floating point format. To convert them to 141290075Sobrienthe precise bit pattern used by the target machine, use the macro 141390075Sobrien@code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}). 141490075Sobrien 141590075Sobrien@findex CONST0_RTX 141690075Sobrien@findex CONST1_RTX 141790075Sobrien@findex CONST2_RTX 141890075SobrienThe macro @code{CONST0_RTX (@var{mode})} refers to an expression with 141990075Sobrienvalue 0 in mode @var{mode}. If mode @var{mode} is of mode class 142096263Sobrien@code{MODE_INT}, it returns @code{const0_rtx}. If mode @var{mode} is of 142196263Sobrienmode class @code{MODE_FLOAT}, it returns a @code{CONST_DOUBLE} 142296263Sobrienexpression in mode @var{mode}. Otherwise, it returns a 142396263Sobrien@code{CONST_VECTOR} expression in mode @var{mode}. Similarly, the macro 142490075Sobrien@code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in 142596263Sobrienmode @var{mode} and similarly for @code{CONST2_RTX}. The 142696263Sobrien@code{CONST1_RTX} and @code{CONST2_RTX} macros are undefined 142796263Sobrienfor vector modes. 142890075Sobrien 142990075Sobrien@findex const_string 143090075Sobrien@item (const_string @var{str}) 143190075SobrienRepresents a constant string with value @var{str}. Currently this is 143290075Sobrienused only for insn attributes (@pxref{Insn Attributes}) since constant 143390075Sobrienstrings in C are placed in memory. 143490075Sobrien 143590075Sobrien@findex symbol_ref 143690075Sobrien@item (symbol_ref:@var{mode} @var{symbol}) 143790075SobrienRepresents the value of an assembler label for data. @var{symbol} is 143890075Sobriena string that describes the name of the assembler label. If it starts 143990075Sobrienwith a @samp{*}, the label is the rest of @var{symbol} not including 144090075Sobrienthe @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed 144190075Sobrienwith @samp{_}. 144290075Sobrien 144390075SobrienThe @code{symbol_ref} contains a mode, which is usually @code{Pmode}. 144490075SobrienUsually that is the only mode for which a symbol is directly valid. 144590075Sobrien 144690075Sobrien@findex label_ref 1447169689Skan@item (label_ref:@var{mode} @var{label}) 144890075SobrienRepresents the value of an assembler label for code. It contains one 144990075Sobrienoperand, an expression, which must be a @code{code_label} or a @code{note} 145090075Sobrienof type @code{NOTE_INSN_DELETED_LABEL} that appears in the instruction 145190075Sobriensequence to identify the place where the label should go. 145290075Sobrien 145390075SobrienThe reason for using a distinct expression type for code label 145490075Sobrienreferences is so that jump optimization can distinguish them. 145590075Sobrien 1456169689SkanThe @code{label_ref} contains a mode, which is usually @code{Pmode}. 1457169689SkanUsually that is the only mode for which a label is directly valid. 1458169689Skan 145990075Sobrien@item (const:@var{m} @var{exp}) 146090075SobrienRepresents a constant that is the result of an assembly-time 146190075Sobrienarithmetic computation. The operand, @var{exp}, is an expression that 146290075Sobriencontains only constants (@code{const_int}, @code{symbol_ref} and 146390075Sobrien@code{label_ref} expressions) combined with @code{plus} and 146490075Sobrien@code{minus}. However, not all combinations are valid, since the 146590075Sobrienassembler cannot do arbitrary arithmetic on relocatable symbols. 146690075Sobrien 146790075Sobrien@var{m} should be @code{Pmode}. 146890075Sobrien 146990075Sobrien@findex high 147090075Sobrien@item (high:@var{m} @var{exp}) 147190075SobrienRepresents the high-order bits of @var{exp}, usually a 147290075Sobrien@code{symbol_ref}. The number of bits is machine-dependent and is 147390075Sobriennormally the number of bits specified in an instruction that initializes 147490075Sobrienthe high order bits of a register. It is used with @code{lo_sum} to 147590075Sobrienrepresent the typical two-instruction sequence used in RISC machines to 147690075Sobrienreference a global memory location. 147790075Sobrien 147890075Sobrien@var{m} should be @code{Pmode}. 147990075Sobrien@end table 148090075Sobrien 148190075Sobrien@node Regs and Memory 148290075Sobrien@section Registers and Memory 148390075Sobrien@cindex RTL register expressions 148490075Sobrien@cindex RTL memory expressions 148590075Sobrien 148690075SobrienHere are the RTL expression types for describing access to machine 148790075Sobrienregisters and to main memory. 148890075Sobrien 148990075Sobrien@table @code 149090075Sobrien@findex reg 149190075Sobrien@cindex hard registers 149290075Sobrien@cindex pseudo registers 149390075Sobrien@item (reg:@var{m} @var{n}) 149490075SobrienFor small values of the integer @var{n} (those that are less than 149590075Sobrien@code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine 149690075Sobrienregister number @var{n}: a @dfn{hard register}. For larger values of 149790075Sobrien@var{n}, it stands for a temporary value or @dfn{pseudo register}. 149890075SobrienThe compiler's strategy is to generate code assuming an unlimited 149990075Sobriennumber of such pseudo registers, and later convert them into hard 150090075Sobrienregisters or into memory references. 150190075Sobrien 150290075Sobrien@var{m} is the machine mode of the reference. It is necessary because 150390075Sobrienmachines can generally refer to each register in more than one mode. 150490075SobrienFor example, a register may contain a full word but there may be 150590075Sobrieninstructions to refer to it as a half word or as a single byte, as 150690075Sobrienwell as instructions to refer to it as a floating point number of 150790075Sobrienvarious precisions. 150890075Sobrien 150990075SobrienEven for a register that the machine can access in only one mode, 151090075Sobrienthe mode must always be specified. 151190075Sobrien 151290075SobrienThe symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine 151390075Sobriendescription, since the number of hard registers on the machine is an 151490075Sobrieninvariant characteristic of the machine. Note, however, that not 151590075Sobrienall of the machine registers must be general registers. All the 151690075Sobrienmachine registers that can be used for storage of data are given 151790075Sobrienhard register numbers, even those that can be used only in certain 151890075Sobrieninstructions or can hold only certain types of data. 151990075Sobrien 152090075SobrienA hard register may be accessed in various modes throughout one 152190075Sobrienfunction, but each pseudo register is given a natural mode 152290075Sobrienand is accessed only in that mode. When it is necessary to describe 152390075Sobrienan access to a pseudo register using a nonnatural mode, a @code{subreg} 152490075Sobrienexpression is used. 152590075Sobrien 152690075SobrienA @code{reg} expression with a machine mode that specifies more than 152790075Sobrienone word of data may actually stand for several consecutive registers. 152890075SobrienIf in addition the register number specifies a hardware register, then 152990075Sobrienit actually represents several consecutive hardware registers starting 153090075Sobrienwith the specified one. 153190075Sobrien 153290075SobrienEach pseudo register number used in a function's RTL code is 153390075Sobrienrepresented by a unique @code{reg} expression. 153490075Sobrien 153590075Sobrien@findex FIRST_VIRTUAL_REGISTER 153690075Sobrien@findex LAST_VIRTUAL_REGISTER 153790075SobrienSome pseudo register numbers, those within the range of 153890075Sobrien@code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only 153990075Sobrienappear during the RTL generation phase and are eliminated before the 154090075Sobrienoptimization phases. These represent locations in the stack frame that 154190075Sobriencannot be determined until RTL generation for the function has been 154290075Sobriencompleted. The following virtual register numbers are defined: 154390075Sobrien 154490075Sobrien@table @code 154590075Sobrien@findex VIRTUAL_INCOMING_ARGS_REGNUM 154690075Sobrien@item VIRTUAL_INCOMING_ARGS_REGNUM 154790075SobrienThis points to the first word of the incoming arguments passed on the 154890075Sobrienstack. Normally these arguments are placed there by the caller, but the 154990075Sobriencallee may have pushed some arguments that were previously passed in 155090075Sobrienregisters. 155190075Sobrien 155290075Sobrien@cindex @code{FIRST_PARM_OFFSET} and virtual registers 155390075Sobrien@cindex @code{ARG_POINTER_REGNUM} and virtual registers 155490075SobrienWhen RTL generation is complete, this virtual register is replaced 155590075Sobrienby the sum of the register given by @code{ARG_POINTER_REGNUM} and the 155690075Sobrienvalue of @code{FIRST_PARM_OFFSET}. 155790075Sobrien 155890075Sobrien@findex VIRTUAL_STACK_VARS_REGNUM 155990075Sobrien@cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers 156090075Sobrien@item VIRTUAL_STACK_VARS_REGNUM 1561169689SkanIf @code{FRAME_GROWS_DOWNWARD} is defined to a nonzero value, this points 1562169689Skanto immediately above the first variable on the stack. Otherwise, it points 1563169689Skanto the first variable on the stack. 156490075Sobrien 156590075Sobrien@cindex @code{STARTING_FRAME_OFFSET} and virtual registers 156690075Sobrien@cindex @code{FRAME_POINTER_REGNUM} and virtual registers 156790075Sobrien@code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the 156890075Sobrienregister given by @code{FRAME_POINTER_REGNUM} and the value 156990075Sobrien@code{STARTING_FRAME_OFFSET}. 157090075Sobrien 157190075Sobrien@findex VIRTUAL_STACK_DYNAMIC_REGNUM 157290075Sobrien@item VIRTUAL_STACK_DYNAMIC_REGNUM 157390075SobrienThis points to the location of dynamically allocated memory on the stack 157490075Sobrienimmediately after the stack pointer has been adjusted by the amount of 157590075Sobrienmemory desired. 157690075Sobrien 157790075Sobrien@cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers 157890075Sobrien@cindex @code{STACK_POINTER_REGNUM} and virtual registers 157990075SobrienThis virtual register is replaced by the sum of the register given by 158090075Sobrien@code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}. 158190075Sobrien 158290075Sobrien@findex VIRTUAL_OUTGOING_ARGS_REGNUM 158390075Sobrien@item VIRTUAL_OUTGOING_ARGS_REGNUM 158490075SobrienThis points to the location in the stack at which outgoing arguments 158590075Sobrienshould be written when the stack is pre-pushed (arguments pushed using 158690075Sobrienpush insns should always use @code{STACK_POINTER_REGNUM}). 158790075Sobrien 158890075Sobrien@cindex @code{STACK_POINTER_OFFSET} and virtual registers 158990075SobrienThis virtual register is replaced by the sum of the register given by 159090075Sobrien@code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}. 159190075Sobrien@end table 159290075Sobrien 159390075Sobrien@findex subreg 159490075Sobrien@item (subreg:@var{m} @var{reg} @var{bytenum}) 159590075Sobrien@code{subreg} expressions are used to refer to a register in a machine 159690075Sobrienmode other than its natural one, or to refer to one register of 159790075Sobriena multi-part @code{reg} that actually refers to several registers. 159890075Sobrien 159990075SobrienEach pseudo-register has a natural mode. If it is necessary to 160090075Sobrienoperate on it in a different mode---for example, to perform a fullword 160190075Sobrienmove instruction on a pseudo-register that contains a single 160290075Sobrienbyte---the pseudo-register must be enclosed in a @code{subreg}. In 160390075Sobriensuch a case, @var{bytenum} is zero. 160490075Sobrien 160590075SobrienUsually @var{m} is at least as narrow as the mode of @var{reg}, in which 160690075Sobriencase it is restricting consideration to only the bits of @var{reg} that 160790075Sobrienare in @var{m}. 160890075Sobrien 160990075SobrienSometimes @var{m} is wider than the mode of @var{reg}. These 161090075Sobrien@code{subreg} expressions are often called @dfn{paradoxical}. They are 161190075Sobrienused in cases where we want to refer to an object in a wider mode but do 161290075Sobriennot care what value the additional bits have. The reload pass ensures 161390075Sobrienthat paradoxical references are only made to hard registers. 161490075Sobrien 161590075SobrienThe other use of @code{subreg} is to extract the individual registers of 161690075Sobriena multi-register value. Machine modes such as @code{DImode} and 161790075Sobrien@code{TImode} can indicate values longer than a word, values which 161890075Sobrienusually require two or more consecutive registers. To access one of the 161990075Sobrienregisters, use a @code{subreg} with mode @code{SImode} and a 162090075Sobrien@var{bytenum} offset that says which register. 162190075Sobrien 162290075SobrienStoring in a non-paradoxical @code{subreg} has undefined results for 162390075Sobrienbits belonging to the same word as the @code{subreg}. This laxity makes 162490075Sobrienit easier to generate efficient code for such instructions. To 162590075Sobrienrepresent an instruction that preserves all the bits outside of those in 162690075Sobrienthe @code{subreg}, use @code{strict_low_part} around the @code{subreg}. 162790075Sobrien 162890075Sobrien@cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg} 162990075SobrienThe compilation parameter @code{WORDS_BIG_ENDIAN}, if set to 1, says 163090075Sobrienthat byte number zero is part of the most significant word; otherwise, 163190075Sobrienit is part of the least significant word. 163290075Sobrien 163390075Sobrien@cindex @code{BYTES_BIG_ENDIAN}, effect on @code{subreg} 163490075SobrienThe compilation parameter @code{BYTES_BIG_ENDIAN}, if set to 1, says 163590075Sobrienthat byte number zero is the most significant byte within a word; 163690075Sobrienotherwise, it is the least significant byte within a word. 163790075Sobrien 163890075Sobrien@cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg} 163990075SobrienOn a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with 164090075Sobrien@code{WORDS_BIG_ENDIAN}. 164190075SobrienHowever, most parts of the compiler treat floating point values as if 164290075Sobrienthey had the same endianness as integer values. This works because 164390075Sobrienthey handle them solely as a collection of integer values, with no 164490075Sobrienparticular numerical value. Only real.c and the runtime libraries 164590075Sobriencare about @code{FLOAT_WORDS_BIG_ENDIAN}. 164690075Sobrien 164790075Sobrien@cindex combiner pass 164890075Sobrien@cindex reload pass 164990075Sobrien@cindex @code{subreg}, special reload handling 165090075SobrienBetween the combiner pass and the reload pass, it is possible to have a 165190075Sobrienparadoxical @code{subreg} which contains a @code{mem} instead of a 165290075Sobrien@code{reg} as its first operand. After the reload pass, it is also 165390075Sobrienpossible to have a non-paradoxical @code{subreg} which contains a 165490075Sobrien@code{mem}; this usually occurs when the @code{mem} is a stack slot 165590075Sobrienwhich replaced a pseudo register. 165690075Sobrien 165790075SobrienNote that it is not valid to access a @code{DFmode} value in @code{SFmode} 165890075Sobrienusing a @code{subreg}. On some machines the most significant part of a 165990075Sobrien@code{DFmode} value does not have the same format as a single-precision 166090075Sobrienfloating value. 166190075Sobrien 166290075SobrienIt is also not valid to access a single word of a multi-word value in a 166390075Sobrienhard register when less registers can hold the value than would be 166490075Sobrienexpected from its size. For example, some 32-bit machines have 166590075Sobrienfloating-point registers that can hold an entire @code{DFmode} value. 1666169689SkanIf register 10 were such a register @code{(subreg:SI (reg:DF 10) 4)} 166790075Sobrienwould be invalid because there is no way to convert that reference to 166890075Sobriena single machine register. The reload pass prevents @code{subreg} 166990075Sobrienexpressions such as these from being formed. 167090075Sobrien 167190075Sobrien@findex SUBREG_REG 167290075Sobrien@findex SUBREG_BYTE 167390075SobrienThe first operand of a @code{subreg} expression is customarily accessed 167490075Sobrienwith the @code{SUBREG_REG} macro and the second operand is customarily 167590075Sobrienaccessed with the @code{SUBREG_BYTE} macro. 167690075Sobrien 167790075Sobrien@findex scratch 167890075Sobrien@cindex scratch operands 167990075Sobrien@item (scratch:@var{m}) 168090075SobrienThis represents a scratch register that will be required for the 168190075Sobrienexecution of a single instruction and not used subsequently. It is 168290075Sobrienconverted into a @code{reg} by either the local register allocator or 168390075Sobrienthe reload pass. 168490075Sobrien 168590075Sobrien@code{scratch} is usually present inside a @code{clobber} operation 168690075Sobrien(@pxref{Side Effects}). 168790075Sobrien 168890075Sobrien@findex cc0 168990075Sobrien@cindex condition code register 169090075Sobrien@item (cc0) 169190075SobrienThis refers to the machine's condition code register. It has no 169290075Sobrienoperands and may not have a machine mode. There are two ways to use it: 169390075Sobrien 169490075Sobrien@itemize @bullet 169590075Sobrien@item 169690075SobrienTo stand for a complete set of condition code flags. This is best on 169790075Sobrienmost machines, where each comparison sets the entire series of flags. 169890075Sobrien 169990075SobrienWith this technique, @code{(cc0)} may be validly used in only two 170090075Sobriencontexts: as the destination of an assignment (in test and compare 170190075Sobrieninstructions) and in comparison operators comparing against zero 170290075Sobrien(@code{const_int} with value zero; that is to say, @code{const0_rtx}). 170390075Sobrien 170490075Sobrien@item 170590075SobrienTo stand for a single flag that is the result of a single condition. 170690075SobrienThis is useful on machines that have only a single flag bit, and in 170790075Sobrienwhich comparison instructions must specify the condition to test. 170890075Sobrien 170990075SobrienWith this technique, @code{(cc0)} may be validly used in only two 171090075Sobriencontexts: as the destination of an assignment (in test and compare 171190075Sobrieninstructions) where the source is a comparison operator, and as the 171290075Sobrienfirst operand of @code{if_then_else} (in a conditional branch). 171390075Sobrien@end itemize 171490075Sobrien 171590075Sobrien@findex cc0_rtx 171690075SobrienThere is only one expression object of code @code{cc0}; it is the 171790075Sobrienvalue of the variable @code{cc0_rtx}. Any attempt to create an 171890075Sobrienexpression of code @code{cc0} will return @code{cc0_rtx}. 171990075Sobrien 172090075SobrienInstructions can set the condition code implicitly. On many machines, 172190075Sobriennearly all instructions set the condition code based on the value that 172290075Sobrienthey compute or store. It is not necessary to record these actions 172390075Sobrienexplicitly in the RTL because the machine description includes a 172490075Sobrienprescription for recognizing the instructions that do so (by means of 172590075Sobrienthe macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only 172690075Sobrieninstructions whose sole purpose is to set the condition code, and 172790075Sobrieninstructions that use the condition code, need mention @code{(cc0)}. 172890075Sobrien 172990075SobrienOn some machines, the condition code register is given a register number 173090075Sobrienand a @code{reg} is used instead of @code{(cc0)}. This is usually the 173190075Sobrienpreferable approach if only a small subset of instructions modify the 173290075Sobriencondition code. Other machines store condition codes in general 173390075Sobrienregisters; in such cases a pseudo register should be used. 173490075Sobrien 1735117395SkanSome machines, such as the SPARC and RS/6000, have two sets of 173690075Sobrienarithmetic instructions, one that sets and one that does not set the 173790075Sobriencondition code. This is best handled by normally generating the 173890075Sobrieninstruction that does not set the condition code, and making a pattern 173990075Sobrienthat both performs the arithmetic and sets the condition code register 174090075Sobrien(which would not be @code{(cc0)} in this case). For examples, search 174190075Sobrienfor @samp{addcc} and @samp{andcc} in @file{sparc.md}. 174290075Sobrien 174390075Sobrien@findex pc 174490075Sobrien@item (pc) 174590075Sobrien@cindex program counter 174690075SobrienThis represents the machine's program counter. It has no operands and 174790075Sobrienmay not have a machine mode. @code{(pc)} may be validly used only in 174890075Sobriencertain specific contexts in jump instructions. 174990075Sobrien 175090075Sobrien@findex pc_rtx 175190075SobrienThere is only one expression object of code @code{pc}; it is the value 175290075Sobrienof the variable @code{pc_rtx}. Any attempt to create an expression of 175390075Sobriencode @code{pc} will return @code{pc_rtx}. 175490075Sobrien 175590075SobrienAll instructions that do not jump alter the program counter implicitly 175690075Sobrienby incrementing it, but there is no need to mention this in the RTL@. 175790075Sobrien 175890075Sobrien@findex mem 175990075Sobrien@item (mem:@var{m} @var{addr} @var{alias}) 176090075SobrienThis RTX represents a reference to main memory at an address 176190075Sobrienrepresented by the expression @var{addr}. @var{m} specifies how large 176290075Sobriena unit of memory is accessed. @var{alias} specifies an alias set for the 176390075Sobrienreference. In general two items are in different alias sets if they cannot 176490075Sobrienreference the same memory address. 176590075Sobrien 1766117395SkanThe construct @code{(mem:BLK (scratch))} is considered to alias all 1767117395Skanother memories. Thus it may be used as a memory barrier in epilogue 1768117395Skanstack deallocation patterns. 1769117395Skan 177090075Sobrien@findex addressof 177190075Sobrien@item (addressof:@var{m} @var{reg}) 177290075SobrienThis RTX represents a request for the address of register @var{reg}. Its mode 177390075Sobrienis always @code{Pmode}. If there are any @code{addressof} 177490075Sobrienexpressions left in the function after CSE, @var{reg} is forced into the 177590075Sobrienstack and the @code{addressof} expression is replaced with a @code{plus} 177690075Sobrienexpression for the address of its stack slot. 177790075Sobrien@end table 177890075Sobrien 177990075Sobrien@node Arithmetic 178090075Sobrien@section RTL Expressions for Arithmetic 178190075Sobrien@cindex arithmetic, in RTL 178290075Sobrien@cindex math, in RTL 178390075Sobrien@cindex RTL expressions for arithmetic 178490075Sobrien 178590075SobrienUnless otherwise specified, all the operands of arithmetic expressions 178690075Sobrienmust be valid for mode @var{m}. An operand is valid for mode @var{m} 178790075Sobrienif it has mode @var{m}, or if it is a @code{const_int} or 178890075Sobrien@code{const_double} and @var{m} is a mode of class @code{MODE_INT}. 178990075Sobrien 179090075SobrienFor commutative binary operations, constants should be placed in the 179190075Sobriensecond operand. 179290075Sobrien 179390075Sobrien@table @code 179490075Sobrien@findex plus 1795169689Skan@findex ss_plus 1796169689Skan@findex us_plus 1797169689Skan@cindex RTL sum 179890075Sobrien@cindex RTL addition 1799169689Skan@cindex RTL addition with signed saturation 1800169689Skan@cindex RTL addition with unsigned saturation 180190075Sobrien@item (plus:@var{m} @var{x} @var{y}) 1802169689Skan@itemx (ss_plus:@var{m} @var{x} @var{y}) 1803169689Skan@itemx (us_plus:@var{m} @var{x} @var{y}) 180490075Sobrien 1805169689SkanThese three expressions all represent the sum of the values 1806169689Skanrepresented by @var{x} and @var{y} carried out in machine mode 1807169689Skan@var{m}. They differ in their behavior on overflow of integer modes. 1808169689Skan@code{plus} wraps round modulo the width of @var{m}; @code{ss_plus} 1809169689Skansaturates at the maximum signed value representable in @var{m}; 1810169689Skan@code{us_plus} saturates at the maximum unsigned value. 1811169689Skan 1812169689Skan@c ??? What happens on overflow of floating point modes? 1813169689Skan 181490075Sobrien@findex lo_sum 181590075Sobrien@item (lo_sum:@var{m} @var{x} @var{y}) 181690075Sobrien 1817169689SkanThis expression represents the sum of @var{x} and the low-order bits 1818169689Skanof @var{y}. It is used with @code{high} (@pxref{Constants}) to 1819169689Skanrepresent the typical two-instruction sequence used in RISC machines 1820169689Skanto reference a global memory location. 1821169689Skan 1822169689SkanThe number of low order bits is machine-dependent but is 1823169689Skannormally the number of bits in a @code{Pmode} item minus the number of 1824169689Skanbits set by @code{high}. 1825169689Skan 182690075Sobrien@var{m} should be @code{Pmode}. 182790075Sobrien 182890075Sobrien@findex minus 1829169689Skan@findex ss_minus 1830169689Skan@findex us_minus 1831169689Skan@cindex RTL difference 183290075Sobrien@cindex RTL subtraction 1833169689Skan@cindex RTL subtraction with signed saturation 1834169689Skan@cindex RTL subtraction with unsigned saturation 183590075Sobrien@item (minus:@var{m} @var{x} @var{y}) 1836169689Skan@itemx (ss_minus:@var{m} @var{x} @var{y}) 1837169689Skan@itemx (us_minus:@var{m} @var{x} @var{y}) 183890075Sobrien 1839169689SkanThese three expressions represent the result of subtracting @var{y} 1840169689Skanfrom @var{x}, carried out in mode @var{M}. Behavior on overflow is 1841169689Skanthe same as for the three variants of @code{plus} (see above). 184290075Sobrien 184390075Sobrien@findex compare 184490075Sobrien@cindex RTL comparison 184590075Sobrien@item (compare:@var{m} @var{x} @var{y}) 184690075SobrienRepresents the result of subtracting @var{y} from @var{x} for purposes 184790075Sobrienof comparison. The result is computed without overflow, as if with 184890075Sobrieninfinite precision. 184990075Sobrien 185090075SobrienOf course, machines can't really subtract with infinite precision. 185190075SobrienHowever, they can pretend to do so when only the sign of the result will 185290075Sobrienbe used, which is the case when the result is stored in the condition 185390075Sobriencode. And that is the @emph{only} way this kind of expression may 185490075Sobrienvalidly be used: as a value to be stored in the condition codes, either 185590075Sobrien@code{(cc0)} or a register. @xref{Comparisons}. 185690075Sobrien 185790075SobrienThe mode @var{m} is not related to the modes of @var{x} and @var{y}, but 185890075Sobrieninstead is the mode of the condition code value. If @code{(cc0)} is 185990075Sobrienused, it is @code{VOIDmode}. Otherwise it is some mode in class 186090075Sobrien@code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}. If @var{m} 186190075Sobrienis @code{VOIDmode} or @code{CCmode}, the operation returns sufficient 186290075Sobrieninformation (in an unspecified format) so that any comparison operator 186390075Sobriencan be applied to the result of the @code{COMPARE} operation. For other 186490075Sobrienmodes in class @code{MODE_CC}, the operation only returns a subset of 186590075Sobrienthis information. 186690075Sobrien 186790075SobrienNormally, @var{x} and @var{y} must have the same mode. Otherwise, 186890075Sobrien@code{compare} is valid only if the mode of @var{x} is in class 186990075Sobrien@code{MODE_INT} and @var{y} is a @code{const_int} or 187090075Sobrien@code{const_double} with mode @code{VOIDmode}. The mode of @var{x} 187190075Sobriendetermines what mode the comparison is to be done in; thus it must not 187290075Sobrienbe @code{VOIDmode}. 187390075Sobrien 187490075SobrienIf one of the operands is a constant, it should be placed in the 187590075Sobriensecond operand and the comparison code adjusted as appropriate. 187690075Sobrien 187790075SobrienA @code{compare} specifying two @code{VOIDmode} constants is not valid 187890075Sobriensince there is no way to know in what mode the comparison is to be 187990075Sobrienperformed; the comparison must either be folded during the compilation 188090075Sobrienor the first operand must be loaded into a register while its mode is 188190075Sobrienstill known. 188290075Sobrien 188390075Sobrien@findex neg 1884169689Skan@findex ss_neg 1885169689Skan@cindex negation 1886169689Skan@cindex negation with signed saturation 188790075Sobrien@item (neg:@var{m} @var{x}) 1888169689Skan@itemx (ss_neg:@var{m} @var{x}) 1889169689SkanThese two expressions represent the negation (subtraction from zero) of 1890169689Skanthe value represented by @var{x}, carried out in mode @var{m}. They 1891169689Skandiffer in the behavior on overflow of integer modes. In the case of 1892169689Skan@code{neg}, the negation of the operand may be a number not representable 1893169689Skanin mode @var{m}, in which case it is truncated to @var{m}. @code{ss_neg} 1894169689Skanensures that an out-of-bounds result saturates to the maximum or minimum 1895169689Skanrepresentable value. 189690075Sobrien 189790075Sobrien@findex mult 189890075Sobrien@cindex multiplication 189990075Sobrien@cindex product 190090075Sobrien@item (mult:@var{m} @var{x} @var{y}) 190190075SobrienRepresents the signed product of the values represented by @var{x} and 190290075Sobrien@var{y} carried out in machine mode @var{m}. 190390075Sobrien 190490075SobrienSome machines support a multiplication that generates a product wider 190590075Sobrienthan the operands. Write the pattern for this as 190690075Sobrien 1907132718Skan@smallexample 190890075Sobrien(mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y})) 1909132718Skan@end smallexample 191090075Sobrien 191190075Sobrienwhere @var{m} is wider than the modes of @var{x} and @var{y}, which need 191290075Sobriennot be the same. 191390075Sobrien 191490075SobrienFor unsigned widening multiplication, use the same idiom, but with 191590075Sobrien@code{zero_extend} instead of @code{sign_extend}. 191690075Sobrien 191790075Sobrien@findex div 191890075Sobrien@cindex division 191990075Sobrien@cindex signed division 192090075Sobrien@cindex quotient 192190075Sobrien@item (div:@var{m} @var{x} @var{y}) 192290075SobrienRepresents the quotient in signed division of @var{x} by @var{y}, 192390075Sobriencarried out in machine mode @var{m}. If @var{m} is a floating point 192490075Sobrienmode, it represents the exact quotient; otherwise, the integerized 192590075Sobrienquotient. 192690075Sobrien 192790075SobrienSome machines have division instructions in which the operands and 192890075Sobrienquotient widths are not all the same; you should represent 192990075Sobriensuch instructions using @code{truncate} and @code{sign_extend} as in, 193090075Sobrien 1931132718Skan@smallexample 193290075Sobrien(truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y}))) 1933132718Skan@end smallexample 193490075Sobrien 193590075Sobrien@findex udiv 193690075Sobrien@cindex unsigned division 193790075Sobrien@cindex division 193890075Sobrien@item (udiv:@var{m} @var{x} @var{y}) 193990075SobrienLike @code{div} but represents unsigned division. 194090075Sobrien 194190075Sobrien@findex mod 194290075Sobrien@findex umod 194390075Sobrien@cindex remainder 194490075Sobrien@cindex division 194590075Sobrien@item (mod:@var{m} @var{x} @var{y}) 194690075Sobrien@itemx (umod:@var{m} @var{x} @var{y}) 194790075SobrienLike @code{div} and @code{udiv} but represent the remainder instead of 194890075Sobrienthe quotient. 194990075Sobrien 195090075Sobrien@findex smin 195190075Sobrien@findex smax 195290075Sobrien@cindex signed minimum 195390075Sobrien@cindex signed maximum 195490075Sobrien@item (smin:@var{m} @var{x} @var{y}) 195590075Sobrien@itemx (smax:@var{m} @var{x} @var{y}) 195690075SobrienRepresents the smaller (for @code{smin}) or larger (for @code{smax}) of 1957169689Skan@var{x} and @var{y}, interpreted as signed values in mode @var{m}. 1958169689SkanWhen used with floating point, if both operands are zeros, or if either 1959169689Skanoperand is @code{NaN}, then it is unspecified which of the two operands 1960169689Skanis returned as the result. 196190075Sobrien 196290075Sobrien@findex umin 196390075Sobrien@findex umax 196490075Sobrien@cindex unsigned minimum and maximum 196590075Sobrien@item (umin:@var{m} @var{x} @var{y}) 196690075Sobrien@itemx (umax:@var{m} @var{x} @var{y}) 196790075SobrienLike @code{smin} and @code{smax}, but the values are interpreted as unsigned 196890075Sobrienintegers. 196990075Sobrien 197090075Sobrien@findex not 197190075Sobrien@cindex complement, bitwise 197290075Sobrien@cindex bitwise complement 197390075Sobrien@item (not:@var{m} @var{x}) 197490075SobrienRepresents the bitwise complement of the value represented by @var{x}, 197590075Sobriencarried out in mode @var{m}, which must be a fixed-point machine mode. 197690075Sobrien 197790075Sobrien@findex and 197890075Sobrien@cindex logical-and, bitwise 197990075Sobrien@cindex bitwise logical-and 198090075Sobrien@item (and:@var{m} @var{x} @var{y}) 198190075SobrienRepresents the bitwise logical-and of the values represented by 198290075Sobrien@var{x} and @var{y}, carried out in machine mode @var{m}, which must be 198390075Sobriena fixed-point machine mode. 198490075Sobrien 198590075Sobrien@findex ior 198690075Sobrien@cindex inclusive-or, bitwise 198790075Sobrien@cindex bitwise inclusive-or 198890075Sobrien@item (ior:@var{m} @var{x} @var{y}) 198990075SobrienRepresents the bitwise inclusive-or of the values represented by @var{x} 199090075Sobrienand @var{y}, carried out in machine mode @var{m}, which must be a 199190075Sobrienfixed-point mode. 199290075Sobrien 199390075Sobrien@findex xor 199490075Sobrien@cindex exclusive-or, bitwise 199590075Sobrien@cindex bitwise exclusive-or 199690075Sobrien@item (xor:@var{m} @var{x} @var{y}) 199790075SobrienRepresents the bitwise exclusive-or of the values represented by @var{x} 199890075Sobrienand @var{y}, carried out in machine mode @var{m}, which must be a 199990075Sobrienfixed-point mode. 200090075Sobrien 200190075Sobrien@findex ashift 2002169689Skan@findex ss_ashift 200390075Sobrien@cindex left shift 200490075Sobrien@cindex shift 200590075Sobrien@cindex arithmetic shift 2006169689Skan@cindex arithmetic shift with signed saturation 200790075Sobrien@item (ashift:@var{m} @var{x} @var{c}) 2008169689Skan@itemx (ss_ashift:@var{m} @var{x} @var{c}) 2009169689SkanThese two expressions represent the result of arithmetically shifting @var{x} 2010169689Skanleft by @var{c} places. They differ in their behavior on overflow of integer 2011169689Skanmodes. An @code{ashift} operation is a plain shift with no special behavior 2012169689Skanin case of a change in the sign bit; @code{ss_ashift} saturates to the minimum 2013169689Skanor maximum representable value if any of the bits shifted out differs from the 2014169689Skanfinal sign bit. 2015169689Skan 2016169689Skan@var{x} have mode @var{m}, a fixed-point machine mode. @var{c} 201790075Sobrienbe a fixed-point mode or be a constant with mode @code{VOIDmode}; which 201890075Sobrienmode is determined by the mode called for in the machine description 201990075Sobrienentry for the left-shift instruction. For example, on the VAX, the mode 202090075Sobrienof @var{c} is @code{QImode} regardless of @var{m}. 202190075Sobrien 202290075Sobrien@findex lshiftrt 202390075Sobrien@cindex right shift 202490075Sobrien@findex ashiftrt 202590075Sobrien@item (lshiftrt:@var{m} @var{x} @var{c}) 202690075Sobrien@itemx (ashiftrt:@var{m} @var{x} @var{c}) 202790075SobrienLike @code{ashift} but for right shift. Unlike the case for left shift, 202890075Sobrienthese two operations are distinct. 202990075Sobrien 203090075Sobrien@findex rotate 203190075Sobrien@cindex rotate 203290075Sobrien@cindex left rotate 203390075Sobrien@findex rotatert 203490075Sobrien@cindex right rotate 203590075Sobrien@item (rotate:@var{m} @var{x} @var{c}) 203690075Sobrien@itemx (rotatert:@var{m} @var{x} @var{c}) 203790075SobrienSimilar but represent left and right rotate. If @var{c} is a constant, 203890075Sobrienuse @code{rotate}. 203990075Sobrien 204090075Sobrien@findex abs 204190075Sobrien@cindex absolute value 204290075Sobrien@item (abs:@var{m} @var{x}) 204390075SobrienRepresents the absolute value of @var{x}, computed in mode @var{m}. 204490075Sobrien 204590075Sobrien@findex sqrt 204690075Sobrien@cindex square root 204790075Sobrien@item (sqrt:@var{m} @var{x}) 204890075SobrienRepresents the square root of @var{x}, computed in mode @var{m}. 204990075SobrienMost often @var{m} will be a floating point mode. 205090075Sobrien 205190075Sobrien@findex ffs 205290075Sobrien@item (ffs:@var{m} @var{x}) 205390075SobrienRepresents one plus the index of the least significant 1-bit in 205490075Sobrien@var{x}, represented as an integer of mode @var{m}. (The value is 205590075Sobrienzero if @var{x} is zero.) The mode of @var{x} need not be @var{m}; 205690075Sobriendepending on the target machine, various mode combinations may be 205790075Sobrienvalid. 2058132718Skan 2059132718Skan@findex clz 2060132718Skan@item (clz:@var{m} @var{x}) 2061132718SkanRepresents the number of leading 0-bits in @var{x}, represented as an 2062132718Skaninteger of mode @var{m}, starting at the most significant bit position. 2063132718SkanIf @var{x} is zero, the value is determined by 2064132718Skan@code{CLZ_DEFINED_VALUE_AT_ZERO}. Note that this is one of 2065132718Skanthe few expressions that is not invariant under widening. The mode of 2066132718Skan@var{x} will usually be an integer mode. 2067132718Skan 2068132718Skan@findex ctz 2069132718Skan@item (ctz:@var{m} @var{x}) 2070132718SkanRepresents the number of trailing 0-bits in @var{x}, represented as an 2071132718Skaninteger of mode @var{m}, starting at the least significant bit position. 2072132718SkanIf @var{x} is zero, the value is determined by 2073132718Skan@code{CTZ_DEFINED_VALUE_AT_ZERO}. Except for this case, 2074132718Skan@code{ctz(x)} is equivalent to @code{ffs(@var{x}) - 1}. The mode of 2075132718Skan@var{x} will usually be an integer mode. 2076132718Skan 2077132718Skan@findex popcount 2078132718Skan@item (popcount:@var{m} @var{x}) 2079132718SkanRepresents the number of 1-bits in @var{x}, represented as an integer of 2080132718Skanmode @var{m}. The mode of @var{x} will usually be an integer mode. 2081132718Skan 2082132718Skan@findex parity 2083132718Skan@item (parity:@var{m} @var{x}) 2084132718SkanRepresents the number of 1-bits modulo 2 in @var{x}, represented as an 2085132718Skaninteger of mode @var{m}. The mode of @var{x} will usually be an integer 2086132718Skanmode. 2087259563Spfg 2088259563Spfg@findex bswap 2089259563Spfg@item (bswap:@var{m} @var{x}) 2090259563SpfgRepresents the value @var{x} with the order of bytes reversed, carried out 2091259563Spfgin mode @var{m}, which must be a fixed-point machine mode. 209290075Sobrien@end table 209390075Sobrien 209490075Sobrien@node Comparisons 209590075Sobrien@section Comparison Operations 209690075Sobrien@cindex RTL comparison operations 209790075Sobrien 209890075SobrienComparison operators test a relation on two operands and are considered 209990075Sobriento represent a machine-dependent nonzero value described by, but not 210090075Sobriennecessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc}) 2101117395Skanif the relation holds, or zero if it does not, for comparison operators 2102169689Skanwhose results have a `MODE_INT' mode, 2103117395Skan@code{FLOAT_STORE_FLAG_VALUE} (@pxref{Misc}) if the relation holds, or 2104117395Skanzero if it does not, for comparison operators that return floating-point 2105169689Skanvalues, and a vector of either @code{VECTOR_STORE_FLAG_VALUE} (@pxref{Misc}) 2106169689Skanif the relation holds, or of zeros if it does not, for comparison operators 2107169689Skanthat return vector results. 2108169689SkanThe mode of the comparison operation is independent of the mode 2109117395Skanof the data being compared. If the comparison operation is being tested 2110117395Skan(e.g., the first operand of an @code{if_then_else}), the mode must be 2111117395Skan@code{VOIDmode}. 211290075Sobrien 211390075Sobrien@cindex condition codes 211490075SobrienThere are two ways that comparison operations may be used. The 211590075Sobriencomparison operators may be used to compare the condition codes 211690075Sobrien@code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such 211790075Sobriena construct actually refers to the result of the preceding instruction 211890075Sobrienin which the condition codes were set. The instruction setting the 211990075Sobriencondition code must be adjacent to the instruction using the condition 212090075Sobriencode; only @code{note} insns may separate them. 212190075Sobrien 212290075SobrienAlternatively, a comparison operation may directly compare two data 212390075Sobrienobjects. The mode of the comparison is determined by the operands; they 212490075Sobrienmust both be valid for a common machine mode. A comparison with both 212590075Sobrienoperands constant would be invalid as the machine mode could not be 212690075Sobriendeduced from it, but such a comparison should never exist in RTL due to 212790075Sobrienconstant folding. 212890075Sobrien 212990075SobrienIn the example above, if @code{(cc0)} were last set to 213090075Sobrien@code{(compare @var{x} @var{y})}, the comparison operation is 213190075Sobrienidentical to @code{(eq @var{x} @var{y})}. Usually only one style 213290075Sobrienof comparisons is supported on a particular machine, but the combine 213390075Sobrienpass will try to merge the operations to produce the @code{eq} shown 213490075Sobrienin case it exists in the context of the particular insn involved. 213590075Sobrien 213690075SobrienInequality comparisons come in two flavors, signed and unsigned. Thus, 213790075Sobrienthere are distinct expression codes @code{gt} and @code{gtu} for signed and 213890075Sobrienunsigned greater-than. These can produce different results for the same 213990075Sobrienpair of integer values: for example, 1 is signed greater-than @minus{}1 but not 214090075Sobrienunsigned greater-than, because @minus{}1 when regarded as unsigned is actually 214190075Sobrien@code{0xffffffff} which is greater than 1. 214290075Sobrien 214390075SobrienThe signed comparisons are also used for floating point values. Floating 214490075Sobrienpoint comparisons are distinguished by the machine modes of the operands. 214590075Sobrien 214690075Sobrien@table @code 214790075Sobrien@findex eq 214890075Sobrien@cindex equal 214990075Sobrien@item (eq:@var{m} @var{x} @var{y}) 215090075Sobrien@code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y} 215190075Sobrienare equal, otherwise 0. 215290075Sobrien 215390075Sobrien@findex ne 215490075Sobrien@cindex not equal 215590075Sobrien@item (ne:@var{m} @var{x} @var{y}) 215690075Sobrien@code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y} 215790075Sobrienare not equal, otherwise 0. 215890075Sobrien 215990075Sobrien@findex gt 216090075Sobrien@cindex greater than 216190075Sobrien@item (gt:@var{m} @var{x} @var{y}) 216290075Sobrien@code{STORE_FLAG_VALUE} if the @var{x} is greater than @var{y}. If they 216390075Sobrienare fixed-point, the comparison is done in a signed sense. 216490075Sobrien 216590075Sobrien@findex gtu 216690075Sobrien@cindex greater than 216790075Sobrien@cindex unsigned greater than 216890075Sobrien@item (gtu:@var{m} @var{x} @var{y}) 216990075SobrienLike @code{gt} but does unsigned comparison, on fixed-point numbers only. 217090075Sobrien 217190075Sobrien@findex lt 217290075Sobrien@cindex less than 217390075Sobrien@findex ltu 217490075Sobrien@cindex unsigned less than 217590075Sobrien@item (lt:@var{m} @var{x} @var{y}) 217690075Sobrien@itemx (ltu:@var{m} @var{x} @var{y}) 217790075SobrienLike @code{gt} and @code{gtu} but test for ``less than''. 217890075Sobrien 217990075Sobrien@findex ge 218090075Sobrien@cindex greater than 218190075Sobrien@findex geu 218290075Sobrien@cindex unsigned greater than 218390075Sobrien@item (ge:@var{m} @var{x} @var{y}) 218490075Sobrien@itemx (geu:@var{m} @var{x} @var{y}) 218590075SobrienLike @code{gt} and @code{gtu} but test for ``greater than or equal''. 218690075Sobrien 218790075Sobrien@findex le 218890075Sobrien@cindex less than or equal 218990075Sobrien@findex leu 219090075Sobrien@cindex unsigned less than 219190075Sobrien@item (le:@var{m} @var{x} @var{y}) 219290075Sobrien@itemx (leu:@var{m} @var{x} @var{y}) 219390075SobrienLike @code{gt} and @code{gtu} but test for ``less than or equal''. 219490075Sobrien 219590075Sobrien@findex if_then_else 219690075Sobrien@item (if_then_else @var{cond} @var{then} @var{else}) 219790075SobrienThis is not a comparison operation but is listed here because it is 219890075Sobrienalways used in conjunction with a comparison operation. To be 219990075Sobrienprecise, @var{cond} is a comparison expression. This expression 220090075Sobrienrepresents a choice, according to @var{cond}, between the value 220190075Sobrienrepresented by @var{then} and the one represented by @var{else}. 220290075Sobrien 220390075SobrienOn most machines, @code{if_then_else} expressions are valid only 220490075Sobriento express conditional jumps. 220590075Sobrien 220690075Sobrien@findex cond 220790075Sobrien@item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default}) 220890075SobrienSimilar to @code{if_then_else}, but more general. Each of @var{test1}, 220990075Sobrien@var{test2}, @dots{} is performed in turn. The result of this expression is 221090075Sobrienthe @var{value} corresponding to the first nonzero test, or @var{default} if 221190075Sobriennone of the tests are nonzero expressions. 221290075Sobrien 221390075SobrienThis is currently not valid for instruction patterns and is supported only 221490075Sobrienfor insn attributes. @xref{Insn Attributes}. 221590075Sobrien@end table 221690075Sobrien 221790075Sobrien@node Bit-Fields 221890075Sobrien@section Bit-Fields 221990075Sobrien@cindex bit-fields 222090075Sobrien 222190075SobrienSpecial expression codes exist to represent bit-field instructions. 222290075Sobrien 222390075Sobrien@table @code 222490075Sobrien@findex sign_extract 222590075Sobrien@cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract} 222690075Sobrien@item (sign_extract:@var{m} @var{loc} @var{size} @var{pos}) 222790075SobrienThis represents a reference to a sign-extended bit-field contained or 222890075Sobrienstarting in @var{loc} (a memory or register reference). The bit-field 222990075Sobrienis @var{size} bits wide and starts at bit @var{pos}. The compilation 223090075Sobrienoption @code{BITS_BIG_ENDIAN} says which end of the memory unit 223190075Sobrien@var{pos} counts from. 223290075Sobrien 223390075SobrienIf @var{loc} is in memory, its mode must be a single-byte integer mode. 223490075SobrienIf @var{loc} is in a register, the mode to use is specified by the 223590075Sobrienoperand of the @code{insv} or @code{extv} pattern 223690075Sobrien(@pxref{Standard Names}) and is usually a full-word integer mode, 223790075Sobrienwhich is the default if none is specified. 223890075Sobrien 223990075SobrienThe mode of @var{pos} is machine-specific and is also specified 224090075Sobrienin the @code{insv} or @code{extv} pattern. 224190075Sobrien 224290075SobrienThe mode @var{m} is the same as the mode that would be used for 224390075Sobrien@var{loc} if it were a register. 224490075Sobrien 2245169689SkanA @code{sign_extract} can not appear as an lvalue, or part thereof, 2246169689Skanin RTL. 2247169689Skan 224890075Sobrien@findex zero_extract 224990075Sobrien@item (zero_extract:@var{m} @var{loc} @var{size} @var{pos}) 225090075SobrienLike @code{sign_extract} but refers to an unsigned or zero-extended 225190075Sobrienbit-field. The same sequence of bits are extracted, but they 225290075Sobrienare filled to an entire word with zeros instead of by sign-extension. 2253169689Skan 2254169689SkanUnlike @code{sign_extract}, this type of expressions can be lvalues 2255169689Skanin RTL; they may appear on the left side of an assignment, indicating 2256169689Skaninsertion of a value into the specified bit-field. 225790075Sobrien@end table 225890075Sobrien 225990075Sobrien@node Vector Operations 226090075Sobrien@section Vector Operations 226190075Sobrien@cindex vector operations 226290075Sobrien 226390075SobrienAll normal RTL expressions can be used with vector modes; they are 226490075Sobrieninterpreted as operating on each part of the vector independently. 226590075SobrienAdditionally, there are a few new expressions to describe specific vector 226690075Sobrienoperations. 226790075Sobrien 226890075Sobrien@table @code 226990075Sobrien@findex vec_merge 227090075Sobrien@item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items}) 227190075SobrienThis describes a merge operation between two vectors. The result is a vector 227290075Sobrienof mode @var{m}; its elements are selected from either @var{vec1} or 227390075Sobrien@var{vec2}. Which elements are selected is described by @var{items}, which 227490075Sobrienis a bit mask represented by a @code{const_int}; a zero bit indicates the 227590075Sobriencorresponding element in the result vector is taken from @var{vec2} while 227690075Sobriena set bit indicates it is taken from @var{vec1}. 227790075Sobrien 227890075Sobrien@findex vec_select 227990075Sobrien@item (vec_select:@var{m} @var{vec1} @var{selection}) 228090075SobrienThis describes an operation that selects parts of a vector. @var{vec1} is 228190075Sobrienthe source vector, @var{selection} is a @code{parallel} that contains a 228290075Sobrien@code{const_int} for each of the subparts of the result vector, giving the 228390075Sobriennumber of the source subpart that should be stored into it. 228490075Sobrien 228590075Sobrien@findex vec_concat 228690075Sobrien@item (vec_concat:@var{m} @var{vec1} @var{vec2}) 228790075SobrienDescribes a vector concat operation. The result is a concatenation of the 228890075Sobrienvectors @var{vec1} and @var{vec2}; its length is the sum of the lengths of 228990075Sobrienthe two inputs. 229090075Sobrien 229190075Sobrien@findex vec_duplicate 229290075Sobrien@item (vec_duplicate:@var{m} @var{vec}) 229390075SobrienThis operation converts a small vector into a larger one by duplicating the 229490075Sobrieninput values. The output vector mode must have the same submodes as the 229590075Sobrieninput vector mode, and the number of output parts must be an integer multiple 229690075Sobrienof the number of input parts. 229790075Sobrien 229890075Sobrien@end table 229990075Sobrien 230090075Sobrien@node Conversions 230190075Sobrien@section Conversions 230290075Sobrien@cindex conversions 230390075Sobrien@cindex machine mode conversions 230490075Sobrien 230590075SobrienAll conversions between machine modes must be represented by 230690075Sobrienexplicit conversion operations. For example, an expression 230790075Sobrienwhich is the sum of a byte and a full word cannot be written as 230890075Sobrien@code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus} 230990075Sobrienoperation requires two operands of the same machine mode. 231090075SobrienTherefore, the byte-sized operand is enclosed in a conversion 231190075Sobrienoperation, as in 231290075Sobrien 2313132718Skan@smallexample 231490075Sobrien(plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80)) 2315132718Skan@end smallexample 231690075Sobrien 231790075SobrienThe conversion operation is not a mere placeholder, because there 231890075Sobrienmay be more than one way of converting from a given starting mode 231990075Sobriento the desired final mode. The conversion operation code says how 232090075Sobriento do it. 232190075Sobrien 232290075SobrienFor all conversion operations, @var{x} must not be @code{VOIDmode} 232390075Sobrienbecause the mode in which to do the conversion would not be known. 232490075SobrienThe conversion must either be done at compile-time or @var{x} 232590075Sobrienmust be placed into a register. 232690075Sobrien 232790075Sobrien@table @code 232890075Sobrien@findex sign_extend 232990075Sobrien@item (sign_extend:@var{m} @var{x}) 233090075SobrienRepresents the result of sign-extending the value @var{x} 233190075Sobriento machine mode @var{m}. @var{m} must be a fixed-point mode 233290075Sobrienand @var{x} a fixed-point value of a mode narrower than @var{m}. 233390075Sobrien 233490075Sobrien@findex zero_extend 233590075Sobrien@item (zero_extend:@var{m} @var{x}) 233690075SobrienRepresents the result of zero-extending the value @var{x} 233790075Sobriento machine mode @var{m}. @var{m} must be a fixed-point mode 233890075Sobrienand @var{x} a fixed-point value of a mode narrower than @var{m}. 233990075Sobrien 234090075Sobrien@findex float_extend 234190075Sobrien@item (float_extend:@var{m} @var{x}) 234290075SobrienRepresents the result of extending the value @var{x} 234390075Sobriento machine mode @var{m}. @var{m} must be a floating point mode 234490075Sobrienand @var{x} a floating point value of a mode narrower than @var{m}. 234590075Sobrien 234690075Sobrien@findex truncate 234790075Sobrien@item (truncate:@var{m} @var{x}) 234890075SobrienRepresents the result of truncating the value @var{x} 234990075Sobriento machine mode @var{m}. @var{m} must be a fixed-point mode 235090075Sobrienand @var{x} a fixed-point value of a mode wider than @var{m}. 235190075Sobrien 235290075Sobrien@findex ss_truncate 235390075Sobrien@item (ss_truncate:@var{m} @var{x}) 235490075SobrienRepresents the result of truncating the value @var{x} 235590075Sobriento machine mode @var{m}, using signed saturation in the case of 235690075Sobrienoverflow. Both @var{m} and the mode of @var{x} must be fixed-point 235790075Sobrienmodes. 235890075Sobrien 235990075Sobrien@findex us_truncate 236090075Sobrien@item (us_truncate:@var{m} @var{x}) 236190075SobrienRepresents the result of truncating the value @var{x} 236290075Sobriento machine mode @var{m}, using unsigned saturation in the case of 236390075Sobrienoverflow. Both @var{m} and the mode of @var{x} must be fixed-point 236490075Sobrienmodes. 236590075Sobrien 236690075Sobrien@findex float_truncate 236790075Sobrien@item (float_truncate:@var{m} @var{x}) 236890075SobrienRepresents the result of truncating the value @var{x} 236990075Sobriento machine mode @var{m}. @var{m} must be a floating point mode 237090075Sobrienand @var{x} a floating point value of a mode wider than @var{m}. 237190075Sobrien 237290075Sobrien@findex float 237390075Sobrien@item (float:@var{m} @var{x}) 237490075SobrienRepresents the result of converting fixed point value @var{x}, 237590075Sobrienregarded as signed, to floating point mode @var{m}. 237690075Sobrien 237790075Sobrien@findex unsigned_float 237890075Sobrien@item (unsigned_float:@var{m} @var{x}) 237990075SobrienRepresents the result of converting fixed point value @var{x}, 238090075Sobrienregarded as unsigned, to floating point mode @var{m}. 238190075Sobrien 238290075Sobrien@findex fix 238390075Sobrien@item (fix:@var{m} @var{x}) 238490075SobrienWhen @var{m} is a fixed point mode, represents the result of 238590075Sobrienconverting floating point value @var{x} to mode @var{m}, regarded as 238690075Sobriensigned. How rounding is done is not specified, so this operation may 238790075Sobrienbe used validly in compiling C code only for integer-valued operands. 238890075Sobrien 238990075Sobrien@findex unsigned_fix 239090075Sobrien@item (unsigned_fix:@var{m} @var{x}) 239190075SobrienRepresents the result of converting floating point value @var{x} to 239290075Sobrienfixed point mode @var{m}, regarded as unsigned. How rounding is done 239390075Sobrienis not specified. 239490075Sobrien 239590075Sobrien@findex fix 239690075Sobrien@item (fix:@var{m} @var{x}) 239790075SobrienWhen @var{m} is a floating point mode, represents the result of 239890075Sobrienconverting floating point value @var{x} (valid for mode @var{m}) to an 239990075Sobrieninteger, still represented in floating point mode @var{m}, by rounding 240090075Sobrientowards zero. 240190075Sobrien@end table 240290075Sobrien 240390075Sobrien@node RTL Declarations 240490075Sobrien@section Declarations 240590075Sobrien@cindex RTL declarations 240690075Sobrien@cindex declarations, RTL 240790075Sobrien 240890075SobrienDeclaration expression codes do not represent arithmetic operations 240990075Sobrienbut rather state assertions about their operands. 241090075Sobrien 241190075Sobrien@table @code 241290075Sobrien@findex strict_low_part 241390075Sobrien@cindex @code{subreg}, in @code{strict_low_part} 241490075Sobrien@item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0)) 241590075SobrienThis expression code is used in only one context: as the destination operand of a 241690075Sobrien@code{set} expression. In addition, the operand of this expression 241790075Sobrienmust be a non-paradoxical @code{subreg} expression. 241890075Sobrien 241990075SobrienThe presence of @code{strict_low_part} says that the part of the 242090075Sobrienregister which is meaningful in mode @var{n}, but is not part of 242190075Sobrienmode @var{m}, is not to be altered. Normally, an assignment to such 242290075Sobriena subreg is allowed to have undefined effects on the rest of the 242390075Sobrienregister when @var{m} is less than a word. 242490075Sobrien@end table 242590075Sobrien 242690075Sobrien@node Side Effects 242790075Sobrien@section Side Effect Expressions 242890075Sobrien@cindex RTL side effect expressions 242990075Sobrien 243090075SobrienThe expression codes described so far represent values, not actions. 243190075SobrienBut machine instructions never produce values; they are meaningful 243290075Sobrienonly for their side effects on the state of the machine. Special 243390075Sobrienexpression codes are used to represent side effects. 243490075Sobrien 243590075SobrienThe body of an instruction is always one of these side effect codes; 243690075Sobrienthe codes described above, which represent values, appear only as 243790075Sobrienthe operands of these. 243890075Sobrien 243990075Sobrien@table @code 244090075Sobrien@findex set 244190075Sobrien@item (set @var{lval} @var{x}) 244290075SobrienRepresents the action of storing the value of @var{x} into the place 244390075Sobrienrepresented by @var{lval}. @var{lval} must be an expression 2444119256Skanrepresenting a place that can be stored in: @code{reg} (or @code{subreg}, 2445119256Skan@code{strict_low_part} or @code{zero_extract}), @code{mem}, @code{pc}, 2446119256Skan@code{parallel}, or @code{cc0}. 244790075Sobrien 244890075SobrienIf @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a 244990075Sobrienmachine mode; then @var{x} must be valid for that mode. 245090075Sobrien 245190075SobrienIf @var{lval} is a @code{reg} whose machine mode is less than the full 245290075Sobrienwidth of the register, then it means that the part of the register 245390075Sobrienspecified by the machine mode is given the specified value and the 245490075Sobrienrest of the register receives an undefined value. Likewise, if 245590075Sobrien@var{lval} is a @code{subreg} whose machine mode is narrower than 245690075Sobrienthe mode of the register, the rest of the register can be changed in 245790075Sobrienan undefined way. 245890075Sobrien 2459169689SkanIf @var{lval} is a @code{strict_low_part} of a subreg, then the part 2460169689Skanof the register specified by the machine mode of the @code{subreg} is 2461169689Skangiven the value @var{x} and the rest of the register is not changed. 246290075Sobrien 2463169689SkanIf @var{lval} is a @code{zero_extract}, then the referenced part of 2464169689Skanthe bit-field (a memory or register reference) specified by the 2465169689Skan@code{zero_extract} is given the value @var{x} and the rest of the 2466169689Skanbit-field is not changed. Note that @code{sign_extract} can not 2467169689Skanappear in @var{lval}. 2468169689Skan 246990075SobrienIf @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may 247090075Sobrienbe either a @code{compare} expression or a value that may have any mode. 247190075SobrienThe latter case represents a ``test'' instruction. The expression 247290075Sobrien@code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to 247390075Sobrien@code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}. 247490075SobrienUse the former expression to save space during the compilation. 247590075Sobrien 247690075SobrienIf @var{lval} is a @code{parallel}, it is used to represent the case of 247790075Sobriena function returning a structure in multiple registers. Each element 247890075Sobrienof the @code{parallel} is an @code{expr_list} whose first operand is a 247990075Sobrien@code{reg} and whose second operand is a @code{const_int} representing the 248090075Sobrienoffset (in bytes) into the structure at which the data in that register 248190075Sobriencorresponds. The first element may be null to indicate that the structure 248290075Sobrienis also passed partly in memory. 248390075Sobrien 248490075Sobrien@cindex jump instructions and @code{set} 248590075Sobrien@cindex @code{if_then_else} usage 248690075SobrienIf @var{lval} is @code{(pc)}, we have a jump instruction, and the 248790075Sobrienpossibilities for @var{x} are very limited. It may be a 248890075Sobrien@code{label_ref} expression (unconditional jump). It may be an 248990075Sobrien@code{if_then_else} (conditional jump), in which case either the 249090075Sobriensecond or the third operand must be @code{(pc)} (for the case which 249190075Sobriendoes not jump) and the other of the two must be a @code{label_ref} 249290075Sobrien(for the case which does jump). @var{x} may also be a @code{mem} or 249390075Sobrien@code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a 249490075Sobrien@code{mem}; these unusual patterns are used to represent jumps through 249590075Sobrienbranch tables. 249690075Sobrien 249790075SobrienIf @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of 249890075Sobrien@var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be 249990075Sobrienvalid for the mode of @var{lval}. 250090075Sobrien 250190075Sobrien@findex SET_DEST 250290075Sobrien@findex SET_SRC 250390075Sobrien@var{lval} is customarily accessed with the @code{SET_DEST} macro and 250490075Sobrien@var{x} with the @code{SET_SRC} macro. 250590075Sobrien 250690075Sobrien@findex return 250790075Sobrien@item (return) 250890075SobrienAs the sole expression in a pattern, represents a return from the 250990075Sobriencurrent function, on machines where this can be done with one 251090075Sobrieninstruction, such as VAXen. On machines where a multi-instruction 251190075Sobrien``epilogue'' must be executed in order to return from the function, 251290075Sobrienreturning is done by jumping to a label which precedes the epilogue, and 251390075Sobrienthe @code{return} expression code is never used. 251490075Sobrien 251590075SobrienInside an @code{if_then_else} expression, represents the value to be 251690075Sobrienplaced in @code{pc} to return to the caller. 251790075Sobrien 251890075SobrienNote that an insn pattern of @code{(return)} is logically equivalent to 251990075Sobrien@code{(set (pc) (return))}, but the latter form is never used. 252090075Sobrien 252190075Sobrien@findex call 252290075Sobrien@item (call @var{function} @var{nargs}) 252390075SobrienRepresents a function call. @var{function} is a @code{mem} expression 252490075Sobrienwhose address is the address of the function to be called. 252590075Sobrien@var{nargs} is an expression which can be used for two purposes: on 252690075Sobriensome machines it represents the number of bytes of stack argument; on 252790075Sobrienothers, it represents the number of argument registers. 252890075Sobrien 252990075SobrienEach machine has a standard machine mode which @var{function} must 253090075Sobrienhave. The machine description defines macro @code{FUNCTION_MODE} to 253190075Sobrienexpand into the requisite mode name. The purpose of this mode is to 253290075Sobrienspecify what kind of addressing is allowed, on machines where the 253390075Sobrienallowed kinds of addressing depend on the machine mode being 253490075Sobrienaddressed. 253590075Sobrien 253690075Sobrien@findex clobber 253790075Sobrien@item (clobber @var{x}) 253890075SobrienRepresents the storing or possible storing of an unpredictable, 253990075Sobrienundescribed value into @var{x}, which must be a @code{reg}, 254090075Sobrien@code{scratch}, @code{parallel} or @code{mem} expression. 254190075Sobrien 254290075SobrienOne place this is used is in string instructions that store standard 254390075Sobrienvalues into particular hard registers. It may not be worth the 254490075Sobrientrouble to describe the values that are stored, but it is essential to 254590075Sobrieninform the compiler that the registers will be altered, lest it 254690075Sobrienattempt to keep data in them across the string instruction. 254790075Sobrien 2548132718SkanIf @var{x} is @code{(mem:BLK (const_int 0))} or 2549117395Skan@code{(mem:BLK (scratch))}, it means that all memory 255090075Sobrienlocations must be presumed clobbered. If @var{x} is a @code{parallel}, 255190075Sobrienit has the same meaning as a @code{parallel} in a @code{set} expression. 255290075Sobrien 255390075SobrienNote that the machine description classifies certain hard registers as 255490075Sobrien``call-clobbered''. All function call instructions are assumed by 255590075Sobriendefault to clobber these registers, so there is no need to use 255690075Sobrien@code{clobber} expressions to indicate this fact. Also, each function 255790075Sobriencall is assumed to have the potential to alter any memory location, 255890075Sobrienunless the function is declared @code{const}. 255990075Sobrien 256090075SobrienIf the last group of expressions in a @code{parallel} are each a 256190075Sobrien@code{clobber} expression whose arguments are @code{reg} or 256290075Sobrien@code{match_scratch} (@pxref{RTL Template}) expressions, the combiner 256390075Sobrienphase can add the appropriate @code{clobber} expressions to an insn it 256490075Sobrienhas constructed when doing so will cause a pattern to be matched. 256590075Sobrien 256690075SobrienThis feature can be used, for example, on a machine that whose multiply 256790075Sobrienand add instructions don't use an MQ register but which has an 256890075Sobrienadd-accumulate instruction that does clobber the MQ register. Similarly, 256990075Sobriena combined instruction might require a temporary register while the 257090075Sobrienconstituent instructions might not. 257190075Sobrien 257290075SobrienWhen a @code{clobber} expression for a register appears inside a 257390075Sobrien@code{parallel} with other side effects, the register allocator 257490075Sobrienguarantees that the register is unoccupied both before and after that 257590075Sobrieninsn. However, the reload phase may allocate a register used for one of 257690075Sobrienthe inputs unless the @samp{&} constraint is specified for the selected 257790075Sobrienalternative (@pxref{Modifiers}). You can clobber either a specific hard 257890075Sobrienregister, a pseudo register, or a @code{scratch} expression; in the 257990075Sobrienlatter two cases, GCC will allocate a hard register that is available 258090075Sobrienthere for use as a temporary. 258190075Sobrien 258290075SobrienFor instructions that require a temporary register, you should use 258390075Sobrien@code{scratch} instead of a pseudo-register because this will allow the 258490075Sobriencombiner phase to add the @code{clobber} when required. You do this by 258590075Sobriencoding (@code{clobber} (@code{match_scratch} @dots{})). If you do 258690075Sobrienclobber a pseudo register, use one which appears nowhere else---generate 258790075Sobriena new one each time. Otherwise, you may confuse CSE@. 258890075Sobrien 258990075SobrienThere is one other known use for clobbering a pseudo register in a 259090075Sobrien@code{parallel}: when one of the input operands of the insn is also 259190075Sobrienclobbered by the insn. In this case, using the same pseudo register in 259290075Sobrienthe clobber and elsewhere in the insn produces the expected results. 259390075Sobrien 259490075Sobrien@findex use 259590075Sobrien@item (use @var{x}) 259690075SobrienRepresents the use of the value of @var{x}. It indicates that the 259790075Sobrienvalue in @var{x} at this point in the program is needed, even though 259890075Sobrienit may not be apparent why this is so. Therefore, the compiler will 259990075Sobriennot attempt to delete previous instructions whose only effect is to 260090075Sobrienstore a value in @var{x}. @var{x} must be a @code{reg} expression. 260190075Sobrien 260290075SobrienIn some situations, it may be tempting to add a @code{use} of a 260390075Sobrienregister in a @code{parallel} to describe a situation where the value 260490075Sobrienof a special register will modify the behavior of the instruction. 260590075SobrienAn hypothetical example might be a pattern for an addition that can 260690075Sobrieneither wrap around or use saturating addition depending on the value 260790075Sobrienof a special control register: 260890075Sobrien 2609103445Skan@smallexample 261096263Sobrien(parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3) 261190075Sobrien (reg:SI 4)] 0)) 261290075Sobrien (use (reg:SI 1))]) 2613103445Skan@end smallexample 261490075Sobrien 261590075Sobrien@noindent 261690075Sobrien 261790075SobrienThis will not work, several of the optimizers only look at expressions 261890075Sobrienlocally; it is very likely that if you have multiple insns with 261990075Sobrienidentical inputs to the @code{unspec}, they will be optimized away even 262090075Sobrienif register 1 changes in between. 262190075Sobrien 262290075SobrienThis means that @code{use} can @emph{only} be used to describe 262390075Sobrienthat the register is live. You should think twice before adding 262490075Sobrien@code{use} statements, more often you will want to use @code{unspec} 262590075Sobrieninstead. The @code{use} RTX is most commonly useful to describe that 262690075Sobriena fixed register is implicitly used in an insn. It is also safe to use 262790075Sobrienin patterns where the compiler knows for other reasons that the result 2628169689Skanof the whole pattern is variable, such as @samp{movmem@var{m}} or 262990075Sobrien@samp{call} patterns. 263090075Sobrien 263190075SobrienDuring the reload phase, an insn that has a @code{use} as pattern 263290075Sobriencan carry a reg_equal note. These @code{use} insns will be deleted 263390075Sobrienbefore the reload phase exits. 263490075Sobrien 263590075SobrienDuring the delayed branch scheduling phase, @var{x} may be an insn. 263690075SobrienThis indicates that @var{x} previously was located at this place in the 263790075Sobriencode and its data dependencies need to be taken into account. These 263890075Sobrien@code{use} insns will be deleted before the delayed branch scheduling 263990075Sobrienphase exits. 264090075Sobrien 264190075Sobrien@findex parallel 264290075Sobrien@item (parallel [@var{x0} @var{x1} @dots{}]) 264390075SobrienRepresents several side effects performed in parallel. The square 264490075Sobrienbrackets stand for a vector; the operand of @code{parallel} is a 264590075Sobrienvector of expressions. @var{x0}, @var{x1} and so on are individual 264690075Sobrienside effect expressions---expressions of code @code{set}, @code{call}, 264790075Sobrien@code{return}, @code{clobber} or @code{use}. 264890075Sobrien 264990075Sobrien``In parallel'' means that first all the values used in the individual 265090075Sobrienside-effects are computed, and second all the actual side-effects are 265190075Sobrienperformed. For example, 265290075Sobrien 2653132718Skan@smallexample 265490075Sobrien(parallel [(set (reg:SI 1) (mem:SI (reg:SI 1))) 265590075Sobrien (set (mem:SI (reg:SI 1)) (reg:SI 1))]) 2656132718Skan@end smallexample 265790075Sobrien 265890075Sobrien@noindent 265990075Sobriensays unambiguously that the values of hard register 1 and the memory 266090075Sobrienlocation addressed by it are interchanged. In both places where 266190075Sobrien@code{(reg:SI 1)} appears as a memory address it refers to the value 266290075Sobrienin register 1 @emph{before} the execution of the insn. 266390075Sobrien 266490075SobrienIt follows that it is @emph{incorrect} to use @code{parallel} and 266590075Sobrienexpect the result of one @code{set} to be available for the next one. 266690075SobrienFor example, people sometimes attempt to represent a jump-if-zero 266790075Sobrieninstruction this way: 266890075Sobrien 2669132718Skan@smallexample 267090075Sobrien(parallel [(set (cc0) (reg:SI 34)) 267190075Sobrien (set (pc) (if_then_else 267290075Sobrien (eq (cc0) (const_int 0)) 267390075Sobrien (label_ref @dots{}) 267490075Sobrien (pc)))]) 2675132718Skan@end smallexample 267690075Sobrien 267790075Sobrien@noindent 267890075SobrienBut this is incorrect, because it says that the jump condition depends 267990075Sobrienon the condition code value @emph{before} this instruction, not on the 268090075Sobriennew value that is set by this instruction. 268190075Sobrien 268290075Sobrien@cindex peephole optimization, RTL representation 268390075SobrienPeephole optimization, which takes place together with final assembly 268490075Sobriencode output, can produce insns whose patterns consist of a @code{parallel} 268590075Sobrienwhose elements are the operands needed to output the resulting 268690075Sobrienassembler code---often @code{reg}, @code{mem} or constant expressions. 268790075SobrienThis would not be well-formed RTL at any other stage in compilation, 268890075Sobrienbut it is ok then because no further optimization remains to be done. 268990075SobrienHowever, the definition of the macro @code{NOTICE_UPDATE_CC}, if 269090075Sobrienany, must deal with such insns if you define any peephole optimizations. 269190075Sobrien 269290075Sobrien@findex cond_exec 269390075Sobrien@item (cond_exec [@var{cond} @var{expr}]) 269490075SobrienRepresents a conditionally executed expression. The @var{expr} is 269590075Sobrienexecuted only if the @var{cond} is nonzero. The @var{cond} expression 269690075Sobrienmust not have side-effects, but the @var{expr} may very well have 269790075Sobrienside-effects. 269890075Sobrien 269990075Sobrien@findex sequence 270090075Sobrien@item (sequence [@var{insns} @dots{}]) 270190075SobrienRepresents a sequence of insns. Each of the @var{insns} that appears 270290075Sobrienin the vector is suitable for appearing in the chain of insns, so it 270390075Sobrienmust be an @code{insn}, @code{jump_insn}, @code{call_insn}, 270490075Sobrien@code{code_label}, @code{barrier} or @code{note}. 270590075Sobrien 270690075SobrienA @code{sequence} RTX is never placed in an actual insn during RTL 270790075Sobriengeneration. It represents the sequence of insns that result from a 270890075Sobrien@code{define_expand} @emph{before} those insns are passed to 270990075Sobrien@code{emit_insn} to insert them in the chain of insns. When actually 271090075Sobrieninserted, the individual sub-insns are separated out and the 271190075Sobrien@code{sequence} is forgotten. 271290075Sobrien 271390075SobrienAfter delay-slot scheduling is completed, an insn and all the insns that 271490075Sobrienreside in its delay slots are grouped together into a @code{sequence}. 271590075SobrienThe insn requiring the delay slot is the first insn in the vector; 271690075Sobriensubsequent insns are to be placed in the delay slot. 271790075Sobrien 271890075Sobrien@code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to 271990075Sobrienindicate that a branch insn should be used that will conditionally annul 272090075Sobrienthe effect of the insns in the delay slots. In such a case, 272190075Sobrien@code{INSN_FROM_TARGET_P} indicates that the insn is from the target of 272290075Sobrienthe branch and should be executed only if the branch is taken; otherwise 272390075Sobrienthe insn should be executed only if the branch is not taken. 272490075Sobrien@xref{Delay Slots}. 272590075Sobrien@end table 272690075Sobrien 272790075SobrienThese expression codes appear in place of a side effect, as the body of 272890075Sobrienan insn, though strictly speaking they do not always describe side 272990075Sobrieneffects as such: 273090075Sobrien 273190075Sobrien@table @code 273290075Sobrien@findex asm_input 273390075Sobrien@item (asm_input @var{s}) 273490075SobrienRepresents literal assembler code as described by the string @var{s}. 273590075Sobrien 273690075Sobrien@findex unspec 273790075Sobrien@findex unspec_volatile 273890075Sobrien@item (unspec [@var{operands} @dots{}] @var{index}) 273990075Sobrien@itemx (unspec_volatile [@var{operands} @dots{}] @var{index}) 274090075SobrienRepresents a machine-specific operation on @var{operands}. @var{index} 274190075Sobrienselects between multiple machine-specific operations. 274290075Sobrien@code{unspec_volatile} is used for volatile operations and operations 274390075Sobrienthat may trap; @code{unspec} is used for other operations. 274490075Sobrien 274590075SobrienThese codes may appear inside a @code{pattern} of an 274690075Sobrieninsn, inside a @code{parallel}, or inside an expression. 274790075Sobrien 274890075Sobrien@findex addr_vec 274990075Sobrien@item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}]) 275090075SobrienRepresents a table of jump addresses. The vector elements @var{lr0}, 275190075Sobrienetc., are @code{label_ref} expressions. The mode @var{m} specifies 275290075Sobrienhow much space is given to each address; normally @var{m} would be 275390075Sobrien@code{Pmode}. 275490075Sobrien 275590075Sobrien@findex addr_diff_vec 275690075Sobrien@item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags}) 275790075SobrienRepresents a table of jump addresses expressed as offsets from 275890075Sobrien@var{base}. The vector elements @var{lr0}, etc., are @code{label_ref} 275990075Sobrienexpressions and so is @var{base}. The mode @var{m} specifies how much 276090075Sobrienspace is given to each address-difference. @var{min} and @var{max} 276190075Sobrienare set up by branch shortening and hold a label with a minimum and a 276290075Sobrienmaximum address, respectively. @var{flags} indicates the relative 276390075Sobrienposition of @var{base}, @var{min} and @var{max} to the containing insn 276490075Sobrienand of @var{min} and @var{max} to @var{base}. See rtl.def for details. 276590075Sobrien 276690075Sobrien@findex prefetch 276790075Sobrien@item (prefetch:@var{m} @var{addr} @var{rw} @var{locality}) 276890075SobrienRepresents prefetch of memory at address @var{addr}. 276990075SobrienOperand @var{rw} is 1 if the prefetch is for data to be written, 0 otherwise; 277090075Sobrientargets that do not support write prefetches should treat this as a normal 277190075Sobrienprefetch. 277290075SobrienOperand @var{locality} specifies the amount of temporal locality; 0 if there 277390075Sobrienis none or 1, 2, or 3 for increasing levels of temporal locality; 277490075Sobrientargets that do not support locality hints should ignore this. 277590075Sobrien 277690075SobrienThis insn is used to minimize cache-miss latency by moving data into a 277790075Sobriencache before it is accessed. It should use only non-faulting data prefetch 277890075Sobrieninstructions. 277990075Sobrien@end table 278090075Sobrien 278190075Sobrien@node Incdec 278290075Sobrien@section Embedded Side-Effects on Addresses 278390075Sobrien@cindex RTL preincrement 278490075Sobrien@cindex RTL postincrement 278590075Sobrien@cindex RTL predecrement 278690075Sobrien@cindex RTL postdecrement 278790075Sobrien 278890075SobrienSix special side-effect expression codes appear as memory addresses. 278990075Sobrien 279090075Sobrien@table @code 279190075Sobrien@findex pre_dec 279290075Sobrien@item (pre_dec:@var{m} @var{x}) 279390075SobrienRepresents the side effect of decrementing @var{x} by a standard 279490075Sobrienamount and represents also the value that @var{x} has after being 279590075Sobriendecremented. @var{x} must be a @code{reg} or @code{mem}, but most 279690075Sobrienmachines allow only a @code{reg}. @var{m} must be the machine mode 279790075Sobrienfor pointers on the machine in use. The amount @var{x} is decremented 279890075Sobrienby is the length in bytes of the machine mode of the containing memory 279990075Sobrienreference of which this expression serves as the address. Here is an 280090075Sobrienexample of its use: 280190075Sobrien 2802132718Skan@smallexample 280390075Sobrien(mem:DF (pre_dec:SI (reg:SI 39))) 2804132718Skan@end smallexample 280590075Sobrien 280690075Sobrien@noindent 280790075SobrienThis says to decrement pseudo register 39 by the length of a @code{DFmode} 280890075Sobrienvalue and use the result to address a @code{DFmode} value. 280990075Sobrien 281090075Sobrien@findex pre_inc 281190075Sobrien@item (pre_inc:@var{m} @var{x}) 281290075SobrienSimilar, but specifies incrementing @var{x} instead of decrementing it. 281390075Sobrien 281490075Sobrien@findex post_dec 281590075Sobrien@item (post_dec:@var{m} @var{x}) 281690075SobrienRepresents the same side effect as @code{pre_dec} but a different 281790075Sobrienvalue. The value represented here is the value @var{x} has @i{before} 281890075Sobrienbeing decremented. 281990075Sobrien 282090075Sobrien@findex post_inc 282190075Sobrien@item (post_inc:@var{m} @var{x}) 282290075SobrienSimilar, but specifies incrementing @var{x} instead of decrementing it. 282390075Sobrien 282490075Sobrien@findex post_modify 282590075Sobrien@item (post_modify:@var{m} @var{x} @var{y}) 282690075Sobrien 282790075SobrienRepresents the side effect of setting @var{x} to @var{y} and 282890075Sobrienrepresents @var{x} before @var{x} is modified. @var{x} must be a 282990075Sobrien@code{reg} or @code{mem}, but most machines allow only a @code{reg}. 283090075Sobrien@var{m} must be the machine mode for pointers on the machine in use. 283190075Sobrien 283290075SobrienThe expression @var{y} must be one of three forms: 283390075Sobrien@table @code 283490075Sobrien@code{(plus:@var{m} @var{x} @var{z})}, 283590075Sobrien@code{(minus:@var{m} @var{x} @var{z})}, or 283690075Sobrien@code{(plus:@var{m} @var{x} @var{i})}, 283790075Sobrien@end table 283890075Sobrienwhere @var{z} is an index register and @var{i} is a constant. 283990075Sobrien 284090075SobrienHere is an example of its use: 284190075Sobrien 2842103445Skan@smallexample 284390075Sobrien(mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42) 284490075Sobrien (reg:SI 48)))) 2845103445Skan@end smallexample 284690075Sobrien 284790075SobrienThis says to modify pseudo register 42 by adding the contents of pseudo 284890075Sobrienregister 48 to it, after the use of what ever 42 points to. 284990075Sobrien 2850117395Skan@findex pre_modify 285190075Sobrien@item (pre_modify:@var{m} @var{x} @var{expr}) 285290075SobrienSimilar except side effects happen before the use. 285390075Sobrien@end table 285490075Sobrien 285590075SobrienThese embedded side effect expressions must be used with care. Instruction 285690075Sobrienpatterns may not use them. Until the @samp{flow} pass of the compiler, 285790075Sobrienthey may occur only to represent pushes onto the stack. The @samp{flow} 285890075Sobrienpass finds cases where registers are incremented or decremented in one 285990075Sobrieninstruction and used as an address shortly before or after; these cases are 286090075Sobrienthen transformed to use pre- or post-increment or -decrement. 286190075Sobrien 286290075SobrienIf a register used as the operand of these expressions is used in 286390075Sobrienanother address in an insn, the original value of the register is used. 286490075SobrienUses of the register outside of an address are not permitted within the 286590075Sobriensame insn as a use in an embedded side effect expression because such 286690075Sobrieninsns behave differently on different machines and hence must be treated 286790075Sobrienas ambiguous and disallowed. 286890075Sobrien 286990075SobrienAn instruction that can be represented with an embedded side effect 287090075Sobriencould also be represented using @code{parallel} containing an additional 287190075Sobrien@code{set} to describe how the address register is altered. This is not 287290075Sobriendone because machines that allow these operations at all typically 287390075Sobrienallow them wherever a memory address is called for. Describing them as 287490075Sobrienadditional parallel stores would require doubling the number of entries 287590075Sobrienin the machine description. 287690075Sobrien 287790075Sobrien@node Assembler 287890075Sobrien@section Assembler Instructions as Expressions 287990075Sobrien@cindex assembler instructions in RTL 288090075Sobrien 288190075Sobrien@cindex @code{asm_operands}, usage 288290075SobrienThe RTX code @code{asm_operands} represents a value produced by a 288390075Sobrienuser-specified assembler instruction. It is used to represent 288490075Sobrienan @code{asm} statement with arguments. An @code{asm} statement with 288590075Sobriena single output operand, like this: 288690075Sobrien 288790075Sobrien@smallexample 288890075Sobrienasm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z)); 288990075Sobrien@end smallexample 289090075Sobrien 289190075Sobrien@noindent 289290075Sobrienis represented using a single @code{asm_operands} RTX which represents 289390075Sobrienthe value that is stored in @code{outputvar}: 289490075Sobrien 289590075Sobrien@smallexample 289690075Sobrien(set @var{rtx-for-outputvar} 289790075Sobrien (asm_operands "foo %1,%2,%0" "a" 0 289890075Sobrien [@var{rtx-for-addition-result} @var{rtx-for-*z}] 289990075Sobrien [(asm_input:@var{m1} "g") 290090075Sobrien (asm_input:@var{m2} "di")])) 290190075Sobrien@end smallexample 290290075Sobrien 290390075Sobrien@noindent 290490075SobrienHere the operands of the @code{asm_operands} RTX are the assembler 290590075Sobrientemplate string, the output-operand's constraint, the index-number of the 290690075Sobrienoutput operand among the output operands specified, a vector of input 290790075Sobrienoperand RTX's, and a vector of input-operand modes and constraints. The 290890075Sobrienmode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of 290990075Sobrien@code{*z}. 291090075Sobrien 291190075SobrienWhen an @code{asm} statement has multiple output values, its insn has 291290075Sobrienseveral such @code{set} RTX's inside of a @code{parallel}. Each @code{set} 291390075Sobriencontains a @code{asm_operands}; all of these share the same assembler 291490075Sobrientemplate and vectors, but each contains the constraint for the respective 291590075Sobrienoutput operand. They are also distinguished by the output-operand index 291690075Sobriennumber, which is 0, 1, @dots{} for successive output operands. 291790075Sobrien 291890075Sobrien@node Insns 291990075Sobrien@section Insns 292090075Sobrien@cindex insns 292190075Sobrien 292290075SobrienThe RTL representation of the code for a function is a doubly-linked 292390075Sobrienchain of objects called @dfn{insns}. Insns are expressions with 292490075Sobrienspecial codes that are used for no other purpose. Some insns are 292590075Sobrienactual instructions; others represent dispatch tables for @code{switch} 292690075Sobrienstatements; others represent labels to jump to or various sorts of 292790075Sobriendeclarative information. 292890075Sobrien 292990075SobrienIn addition to its own specific data, each insn must have a unique 293090075Sobrienid-number that distinguishes it from all other insns in the current 293190075Sobrienfunction (after delayed branch scheduling, copies of an insn with the 293290075Sobriensame id-number may be present in multiple places in a function, but 293390075Sobrienthese copies will always be identical and will only appear inside a 293490075Sobrien@code{sequence}), and chain pointers to the preceding and following 293590075Sobrieninsns. These three fields occupy the same position in every insn, 293690075Sobrienindependent of the expression code of the insn. They could be accessed 293790075Sobrienwith @code{XEXP} and @code{XINT}, but instead three special macros are 293890075Sobrienalways used: 293990075Sobrien 294090075Sobrien@table @code 294190075Sobrien@findex INSN_UID 294290075Sobrien@item INSN_UID (@var{i}) 294390075SobrienAccesses the unique id of insn @var{i}. 294490075Sobrien 294590075Sobrien@findex PREV_INSN 294690075Sobrien@item PREV_INSN (@var{i}) 294790075SobrienAccesses the chain pointer to the insn preceding @var{i}. 294890075SobrienIf @var{i} is the first insn, this is a null pointer. 294990075Sobrien 295090075Sobrien@findex NEXT_INSN 295190075Sobrien@item NEXT_INSN (@var{i}) 295290075SobrienAccesses the chain pointer to the insn following @var{i}. 295390075SobrienIf @var{i} is the last insn, this is a null pointer. 295490075Sobrien@end table 295590075Sobrien 295690075Sobrien@findex get_insns 295790075Sobrien@findex get_last_insn 295890075SobrienThe first insn in the chain is obtained by calling @code{get_insns}; the 295990075Sobrienlast insn is the result of calling @code{get_last_insn}. Within the 296090075Sobrienchain delimited by these insns, the @code{NEXT_INSN} and 296190075Sobrien@code{PREV_INSN} pointers must always correspond: if @var{insn} is not 296290075Sobrienthe first insn, 296390075Sobrien 2964132718Skan@smallexample 296590075SobrienNEXT_INSN (PREV_INSN (@var{insn})) == @var{insn} 2966132718Skan@end smallexample 296790075Sobrien 296890075Sobrien@noindent 296990075Sobrienis always true and if @var{insn} is not the last insn, 297090075Sobrien 2971132718Skan@smallexample 297290075SobrienPREV_INSN (NEXT_INSN (@var{insn})) == @var{insn} 2973132718Skan@end smallexample 297490075Sobrien 297590075Sobrien@noindent 297690075Sobrienis always true. 297790075Sobrien 297890075SobrienAfter delay slot scheduling, some of the insns in the chain might be 297990075Sobrien@code{sequence} expressions, which contain a vector of insns. The value 298090075Sobrienof @code{NEXT_INSN} in all but the last of these insns is the next insn 298190075Sobrienin the vector; the value of @code{NEXT_INSN} of the last insn in the vector 298290075Sobrienis the same as the value of @code{NEXT_INSN} for the @code{sequence} in 298390075Sobrienwhich it is contained. Similar rules apply for @code{PREV_INSN}. 298490075Sobrien 298590075SobrienThis means that the above invariants are not necessarily true for insns 298690075Sobrieninside @code{sequence} expressions. Specifically, if @var{insn} is the 298790075Sobrienfirst insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))} 298890075Sobrienis the insn containing the @code{sequence} expression, as is the value 298990075Sobrienof @code{PREV_INSN (NEXT_INSN (@var{insn}))} if @var{insn} is the last 299090075Sobrieninsn in the @code{sequence} expression. You can use these expressions 299190075Sobriento find the containing @code{sequence} expression. 299290075Sobrien 299390075SobrienEvery insn has one of the following six expression codes: 299490075Sobrien 299590075Sobrien@table @code 299690075Sobrien@findex insn 299790075Sobrien@item insn 299890075SobrienThe expression code @code{insn} is used for instructions that do not jump 299990075Sobrienand do not do function calls. @code{sequence} expressions are always 300090075Sobriencontained in insns with code @code{insn} even if one of those insns 300190075Sobrienshould jump or do function calls. 300290075Sobrien 300390075SobrienInsns with code @code{insn} have four additional fields beyond the three 300490075Sobrienmandatory ones listed above. These four are described in a table below. 300590075Sobrien 300690075Sobrien@findex jump_insn 300790075Sobrien@item jump_insn 300890075SobrienThe expression code @code{jump_insn} is used for instructions that may 300990075Sobrienjump (or, more generally, may contain @code{label_ref} expressions). If 301090075Sobrienthere is an instruction to return from the current function, it is 301190075Sobrienrecorded as a @code{jump_insn}. 301290075Sobrien 301390075Sobrien@findex JUMP_LABEL 301490075Sobrien@code{jump_insn} insns have the same extra fields as @code{insn} insns, 301590075Sobrienaccessed in the same way and in addition contain a field 301690075Sobrien@code{JUMP_LABEL} which is defined once jump optimization has completed. 301790075Sobrien 301890075SobrienFor simple conditional and unconditional jumps, this field contains 301990075Sobrienthe @code{code_label} to which this insn will (possibly conditionally) 302090075Sobrienbranch. In a more complex jump, @code{JUMP_LABEL} records one of the 302190075Sobrienlabels that the insn refers to; the only way to find the others is to 302290075Sobrienscan the entire body of the insn. In an @code{addr_vec}, 302390075Sobrien@code{JUMP_LABEL} is @code{NULL_RTX}. 302490075Sobrien 302590075SobrienReturn insns count as jumps, but since they do not refer to any 302690075Sobrienlabels, their @code{JUMP_LABEL} is @code{NULL_RTX}. 302790075Sobrien 302890075Sobrien@findex call_insn 302990075Sobrien@item call_insn 303090075SobrienThe expression code @code{call_insn} is used for instructions that may do 303190075Sobrienfunction calls. It is important to distinguish these instructions because 303290075Sobrienthey imply that certain registers and memory locations may be altered 303390075Sobrienunpredictably. 303490075Sobrien 303590075Sobrien@findex CALL_INSN_FUNCTION_USAGE 303690075Sobrien@code{call_insn} insns have the same extra fields as @code{insn} insns, 303790075Sobrienaccessed in the same way and in addition contain a field 303890075Sobrien@code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of 303990075Sobrien@code{expr_list} expressions) containing @code{use} and @code{clobber} 304090075Sobrienexpressions that denote hard registers and @code{MEM}s used or 304190075Sobrienclobbered by the called function. 304290075Sobrien 304390075SobrienA @code{MEM} generally points to a stack slots in which arguments passed 304490075Sobriento the libcall by reference (@pxref{Register Arguments, 3045169689SkanTARGET_PASS_BY_REFERENCE}) are stored. If the argument is 3046169689Skancaller-copied (@pxref{Register Arguments, TARGET_CALLEE_COPIES}), 304790075Sobrienthe stack slot will be mentioned in @code{CLOBBER} and @code{USE} 304890075Sobrienentries; if it's callee-copied, only a @code{USE} will appear, and the 3049169689Skan@code{MEM} may point to addresses that are not stack slots. 305090075Sobrien 305190075Sobrien@code{CLOBBER}ed registers in this list augment registers specified in 305290075Sobrien@code{CALL_USED_REGISTERS} (@pxref{Register Basics}). 305390075Sobrien 305490075Sobrien@findex code_label 305590075Sobrien@findex CODE_LABEL_NUMBER 305690075Sobrien@item code_label 305790075SobrienA @code{code_label} insn represents a label that a jump insn can jump 305890075Sobriento. It contains two special fields of data in addition to the three 305990075Sobrienstandard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label 306090075Sobriennumber}, a number that identifies this label uniquely among all the 306190075Sobrienlabels in the compilation (not just in the current function). 306290075SobrienUltimately, the label is represented in the assembler output as an 306390075Sobrienassembler label, usually of the form @samp{L@var{n}} where @var{n} is 306490075Sobrienthe label number. 306590075Sobrien 306690075SobrienWhen a @code{code_label} appears in an RTL expression, it normally 306790075Sobrienappears within a @code{label_ref} which represents the address of 306890075Sobrienthe label, as a number. 306990075Sobrien 307090075SobrienBesides as a @code{code_label}, a label can also be represented as a 307190075Sobrien@code{note} of type @code{NOTE_INSN_DELETED_LABEL}. 307290075Sobrien 307390075Sobrien@findex LABEL_NUSES 307490075SobrienThe field @code{LABEL_NUSES} is only defined once the jump optimization 3075117395Skanphase is completed. It contains the number of times this label is 307690075Sobrienreferenced in the current function. 307790075Sobrien 3078117395Skan@findex LABEL_KIND 3079117395Skan@findex SET_LABEL_KIND 3080117395Skan@findex LABEL_ALT_ENTRY_P 3081117395Skan@cindex alternate entry points 3082117395SkanThe field @code{LABEL_KIND} differentiates four different types of 3083117395Skanlabels: @code{LABEL_NORMAL}, @code{LABEL_STATIC_ENTRY}, 3084117395Skan@code{LABEL_GLOBAL_ENTRY}, and @code{LABEL_WEAK_ENTRY}. The only labels 3085117395Skanthat do not have type @code{LABEL_NORMAL} are @dfn{alternate entry 3086117395Skanpoints} to the current function. These may be static (visible only in 3087117395Skanthe containing translation unit), global (exposed to all translation 3088117395Skanunits), or weak (global, but can be overridden by another symbol with the 3089117395Skansame name). 309090075Sobrien 3091117395SkanMuch of the compiler treats all four kinds of label identically. Some 3092117395Skanof it needs to know whether or not a label is an alternate entry point; 3093117395Skanfor this purpose, the macro @code{LABEL_ALT_ENTRY_P} is provided. It is 3094117395Skanequivalent to testing whether @samp{LABEL_KIND (label) == LABEL_NORMAL}. 3095117395SkanThe only place that cares about the distinction between static, global, 3096117395Skanand weak alternate entry points, besides the front-end code that creates 3097117395Skanthem, is the function @code{output_alternate_entry_point}, in 3098117395Skan@file{final.c}. 3099117395Skan 3100117395SkanTo set the kind of a label, use the @code{SET_LABEL_KIND} macro. 3101117395Skan 310290075Sobrien@findex barrier 310390075Sobrien@item barrier 310490075SobrienBarriers are placed in the instruction stream when control cannot flow 310590075Sobrienpast them. They are placed after unconditional jump instructions to 310690075Sobrienindicate that the jumps are unconditional and after calls to 310790075Sobrien@code{volatile} functions, which do not return (e.g., @code{exit}). 310890075SobrienThey contain no information beyond the three standard fields. 310990075Sobrien 311090075Sobrien@findex note 311190075Sobrien@findex NOTE_LINE_NUMBER 311290075Sobrien@findex NOTE_SOURCE_FILE 311390075Sobrien@item note 311490075Sobrien@code{note} insns are used to represent additional debugging and 311590075Sobriendeclarative information. They contain two nonstandard fields, an 311690075Sobrieninteger which is accessed with the macro @code{NOTE_LINE_NUMBER} and a 311790075Sobrienstring accessed with @code{NOTE_SOURCE_FILE}. 311890075Sobrien 311990075SobrienIf @code{NOTE_LINE_NUMBER} is positive, the note represents the 312090075Sobrienposition of a source line and @code{NOTE_SOURCE_FILE} is the source file name 312190075Sobrienthat the line came from. These notes control generation of line 312290075Sobriennumber data in the assembler output. 312390075Sobrien 312490075SobrienOtherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a 312590075Sobriencode with one of the following values (and @code{NOTE_SOURCE_FILE} 312690075Sobrienmust contain a null pointer): 312790075Sobrien 312890075Sobrien@table @code 312990075Sobrien@findex NOTE_INSN_DELETED 313090075Sobrien@item NOTE_INSN_DELETED 313190075SobrienSuch a note is completely ignorable. Some passes of the compiler 313290075Sobriendelete insns by altering them into notes of this kind. 313390075Sobrien 313490075Sobrien@findex NOTE_INSN_DELETED_LABEL 313590075Sobrien@item NOTE_INSN_DELETED_LABEL 313690075SobrienThis marks what used to be a @code{code_label}, but was not used for other 313790075Sobrienpurposes than taking its address and was transformed to mark that no 313890075Sobriencode jumps to it. 313990075Sobrien 314090075Sobrien@findex NOTE_INSN_BLOCK_BEG 314190075Sobrien@findex NOTE_INSN_BLOCK_END 314290075Sobrien@item NOTE_INSN_BLOCK_BEG 314390075Sobrien@itemx NOTE_INSN_BLOCK_END 314490075SobrienThese types of notes indicate the position of the beginning and end 314590075Sobrienof a level of scoping of variable names. They control the output 314690075Sobrienof debugging information. 314790075Sobrien 314890075Sobrien@findex NOTE_INSN_EH_REGION_BEG 314990075Sobrien@findex NOTE_INSN_EH_REGION_END 315090075Sobrien@item NOTE_INSN_EH_REGION_BEG 315190075Sobrien@itemx NOTE_INSN_EH_REGION_END 315290075SobrienThese types of notes indicate the position of the beginning and end of a 315390075Sobrienlevel of scoping for exception handling. @code{NOTE_BLOCK_NUMBER} 315490075Sobrienidentifies which @code{CODE_LABEL} or @code{note} of type 315590075Sobrien@code{NOTE_INSN_DELETED_LABEL} is associated with the given region. 315690075Sobrien 315790075Sobrien@findex NOTE_INSN_LOOP_BEG 315890075Sobrien@findex NOTE_INSN_LOOP_END 315990075Sobrien@item NOTE_INSN_LOOP_BEG 316090075Sobrien@itemx NOTE_INSN_LOOP_END 316190075SobrienThese types of notes indicate the position of the beginning and end 316290075Sobrienof a @code{while} or @code{for} loop. They enable the loop optimizer 316390075Sobriento find loops quickly. 316490075Sobrien 316590075Sobrien@findex NOTE_INSN_LOOP_CONT 316690075Sobrien@item NOTE_INSN_LOOP_CONT 316790075SobrienAppears at the place in a loop that @code{continue} statements jump to. 316890075Sobrien 316990075Sobrien@findex NOTE_INSN_LOOP_VTOP 317090075Sobrien@item NOTE_INSN_LOOP_VTOP 317190075SobrienThis note indicates the place in a loop where the exit test begins for 317290075Sobrienthose loops in which the exit test has been duplicated. This position 317390075Sobrienbecomes another virtual start of the loop when considering loop 317490075Sobrieninvariants. 317590075Sobrien 3176169689Skan@findex NOTE_INSN_FUNCTION_BEG 3177169689Skan@item NOTE_INSN_FUNCTION_BEG 3178169689SkanAppears at the start of the function body, after the function 3179169689Skanprologue. 3180169689Skan 318190075Sobrien@findex NOTE_INSN_FUNCTION_END 318290075Sobrien@item NOTE_INSN_FUNCTION_END 318390075SobrienAppears near the end of the function body, just before the label that 318490075Sobrien@code{return} statements jump to (on machine where a single instruction 318590075Sobriendoes not suffice for returning). This note may be deleted by jump 318690075Sobrienoptimization. 318790075Sobrien 318890075Sobrien@end table 318990075Sobrien 319090075SobrienThese codes are printed symbolically when they appear in debugging dumps. 319190075Sobrien@end table 319290075Sobrien 319390075Sobrien@cindex @code{TImode}, in @code{insn} 319490075Sobrien@cindex @code{HImode}, in @code{insn} 319590075Sobrien@cindex @code{QImode}, in @code{insn} 319690075SobrienThe machine mode of an insn is normally @code{VOIDmode}, but some 319790075Sobrienphases use the mode for various purposes. 319890075Sobrien 319990075SobrienThe common subexpression elimination pass sets the mode of an insn to 320090075Sobrien@code{QImode} when it is the first insn in a block that has already 320190075Sobrienbeen processed. 320290075Sobrien 320390075SobrienThe second Haifa scheduling pass, for targets that can multiple issue, 320490075Sobriensets the mode of an insn to @code{TImode} when it is believed that the 320590075Sobrieninstruction begins an issue group. That is, when the instruction 320690075Sobriencannot issue simultaneously with the previous. This may be relied on 320790075Sobrienby later passes, in particular machine-dependent reorg. 320890075Sobrien 320990075SobrienHere is a table of the extra fields of @code{insn}, @code{jump_insn} 321090075Sobrienand @code{call_insn} insns: 321190075Sobrien 321290075Sobrien@table @code 321390075Sobrien@findex PATTERN 321490075Sobrien@item PATTERN (@var{i}) 321590075SobrienAn expression for the side effect performed by this insn. This must be 321690075Sobrienone of the following codes: @code{set}, @code{call}, @code{use}, 321790075Sobrien@code{clobber}, @code{return}, @code{asm_input}, @code{asm_output}, 321890075Sobrien@code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec}, 321990075Sobrien@code{unspec_volatile}, @code{parallel}, @code{cond_exec}, or @code{sequence}. If it is a @code{parallel}, 322090075Sobrieneach element of the @code{parallel} must be one these codes, except that 322190075Sobrien@code{parallel} expressions cannot be nested and @code{addr_vec} and 322290075Sobrien@code{addr_diff_vec} are not permitted inside a @code{parallel} expression. 322390075Sobrien 322490075Sobrien@findex INSN_CODE 322590075Sobrien@item INSN_CODE (@var{i}) 322690075SobrienAn integer that says which pattern in the machine description matches 322790075Sobrienthis insn, or @minus{}1 if the matching has not yet been attempted. 322890075Sobrien 322990075SobrienSuch matching is never attempted and this field remains @minus{}1 on an insn 323090075Sobrienwhose pattern consists of a single @code{use}, @code{clobber}, 323190075Sobrien@code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression. 323290075Sobrien 323390075Sobrien@findex asm_noperands 323490075SobrienMatching is also never attempted on insns that result from an @code{asm} 323590075Sobrienstatement. These contain at least one @code{asm_operands} expression. 323690075SobrienThe function @code{asm_noperands} returns a non-negative value for 323790075Sobriensuch insns. 323890075Sobrien 323990075SobrienIn the debugging output, this field is printed as a number followed by 324090075Sobriena symbolic representation that locates the pattern in the @file{md} 324190075Sobrienfile as some small positive or negative offset from a named pattern. 324290075Sobrien 324390075Sobrien@findex LOG_LINKS 324490075Sobrien@item LOG_LINKS (@var{i}) 324590075SobrienA list (chain of @code{insn_list} expressions) giving information about 324690075Sobriendependencies between instructions within a basic block. Neither a jump 324790075Sobriennor a label may come between the related insns. 324890075Sobrien 324990075Sobrien@findex REG_NOTES 325090075Sobrien@item REG_NOTES (@var{i}) 325190075SobrienA list (chain of @code{expr_list} and @code{insn_list} expressions) 325290075Sobriengiving miscellaneous information about the insn. It is often 325390075Sobrieninformation pertaining to the registers used in this insn. 325490075Sobrien@end table 325590075Sobrien 325690075SobrienThe @code{LOG_LINKS} field of an insn is a chain of @code{insn_list} 325790075Sobrienexpressions. Each of these has two operands: the first is an insn, 325890075Sobrienand the second is another @code{insn_list} expression (the next one in 325990075Sobrienthe chain). The last @code{insn_list} in the chain has a null pointer 326090075Sobrienas second operand. The significant thing about the chain is which 326190075Sobrieninsns appear in it (as first operands of @code{insn_list} 326290075Sobrienexpressions). Their order is not significant. 326390075Sobrien 326490075SobrienThis list is originally set up by the flow analysis pass; it is a null 326590075Sobrienpointer until then. Flow only adds links for those data dependencies 326690075Sobrienwhich can be used for instruction combination. For each insn, the flow 326790075Sobrienanalysis pass adds a link to insns which store into registers values 326890075Sobrienthat are used for the first time in this insn. The instruction 326990075Sobrienscheduling pass adds extra links so that every dependence will be 327090075Sobrienrepresented. Links represent data dependencies, antidependencies and 327190075Sobrienoutput dependencies; the machine mode of the link distinguishes these 327290075Sobrienthree types: antidependencies have mode @code{REG_DEP_ANTI}, output 327390075Sobriendependencies have mode @code{REG_DEP_OUTPUT}, and data dependencies have 327490075Sobrienmode @code{VOIDmode}. 327590075Sobrien 327690075SobrienThe @code{REG_NOTES} field of an insn is a chain similar to the 327790075Sobrien@code{LOG_LINKS} field but it includes @code{expr_list} expressions in 327890075Sobrienaddition to @code{insn_list} expressions. There are several kinds of 327990075Sobrienregister notes, which are distinguished by the machine mode, which in a 328090075Sobrienregister note is really understood as being an @code{enum reg_note}. 328190075SobrienThe first operand @var{op} of the note is data whose meaning depends on 328290075Sobrienthe kind of note. 328390075Sobrien 328490075Sobrien@findex REG_NOTE_KIND 328590075Sobrien@findex PUT_REG_NOTE_KIND 328690075SobrienThe macro @code{REG_NOTE_KIND (@var{x})} returns the kind of 328790075Sobrienregister note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND 328890075Sobrien(@var{x}, @var{newkind})} sets the register note type of @var{x} to be 328990075Sobrien@var{newkind}. 329090075Sobrien 329190075SobrienRegister notes are of three classes: They may say something about an 329290075Sobrieninput to an insn, they may say something about an output of an insn, or 329390075Sobrienthey may create a linkage between two insns. There are also a set 329490075Sobrienof values that are only used in @code{LOG_LINKS}. 329590075Sobrien 329690075SobrienThese register notes annotate inputs to an insn: 329790075Sobrien 329890075Sobrien@table @code 329990075Sobrien@findex REG_DEAD 330090075Sobrien@item REG_DEAD 330190075SobrienThe value in @var{op} dies in this insn; that is to say, altering the 330290075Sobrienvalue immediately after this insn would not affect the future behavior 330390075Sobrienof the program. 330490075Sobrien 330590075SobrienIt does not follow that the register @var{op} has no useful value after 330690075Sobrienthis insn since @var{op} is not necessarily modified by this insn. 330790075SobrienRather, no subsequent instruction uses the contents of @var{op}. 330890075Sobrien 330990075Sobrien@findex REG_UNUSED 331090075Sobrien@item REG_UNUSED 331190075SobrienThe register @var{op} being set by this insn will not be used in a 331290075Sobriensubsequent insn. This differs from a @code{REG_DEAD} note, which 331390075Sobrienindicates that the value in an input will not be used subsequently. 331490075SobrienThese two notes are independent; both may be present for the same 331590075Sobrienregister. 331690075Sobrien 331790075Sobrien@findex REG_INC 331890075Sobrien@item REG_INC 331990075SobrienThe register @var{op} is incremented (or decremented; at this level 332090075Sobrienthere is no distinction) by an embedded side effect inside this insn. 332190075SobrienThis means it appears in a @code{post_inc}, @code{pre_inc}, 332290075Sobrien@code{post_dec} or @code{pre_dec} expression. 332390075Sobrien 332490075Sobrien@findex REG_NONNEG 332590075Sobrien@item REG_NONNEG 332690075SobrienThe register @var{op} is known to have a nonnegative value when this 332790075Sobrieninsn is reached. This is used so that decrement and branch until zero 332890075Sobrieninstructions, such as the m68k dbra, can be matched. 332990075Sobrien 333090075SobrienThe @code{REG_NONNEG} note is added to insns only if the machine 333190075Sobriendescription has a @samp{decrement_and_branch_until_zero} pattern. 333290075Sobrien 333390075Sobrien@findex REG_NO_CONFLICT 333490075Sobrien@item REG_NO_CONFLICT 333590075SobrienThis insn does not cause a conflict between @var{op} and the item 333690075Sobrienbeing set by this insn even though it might appear that it does. 333790075SobrienIn other words, if the destination register and @var{op} could 333890075Sobrienotherwise be assigned the same register, this insn does not 333990075Sobrienprevent that assignment. 334090075Sobrien 334190075SobrienInsns with this note are usually part of a block that begins with a 334290075Sobrien@code{clobber} insn specifying a multi-word pseudo register (which will 334390075Sobrienbe the output of the block), a group of insns that each set one word of 334490075Sobrienthe value and have the @code{REG_NO_CONFLICT} note attached, and a final 334590075Sobrieninsn that copies the output to itself with an attached @code{REG_EQUAL} 334690075Sobriennote giving the expression being computed. This block is encapsulated 334790075Sobrienwith @code{REG_LIBCALL} and @code{REG_RETVAL} notes on the first and 334890075Sobrienlast insns, respectively. 334990075Sobrien 335090075Sobrien@findex REG_LABEL 335190075Sobrien@item REG_LABEL 335290075SobrienThis insn uses @var{op}, a @code{code_label} or a @code{note} of type 335390075Sobrien@code{NOTE_INSN_DELETED_LABEL}, but is not a 335490075Sobrien@code{jump_insn}, or it is a @code{jump_insn} that required the label to 335590075Sobrienbe held in a register. The presence of this note allows jump 335690075Sobrienoptimization to be aware that @var{op} is, in fact, being used, and flow 335790075Sobrienoptimization to build an accurate flow graph. 3358169689Skan 3359169689Skan@findex REG_CROSSING_JUMP 3360169689Skan@item REG_CROSSING_JUMP 3361169689SkanThis insn is an branching instruction (either an unconditional jump or 3362169689Skanan indirect jump) which crosses between hot and cold sections, which 3363169689Skancould potentially be very far apart in the executable. The presence 3364169689Skanof this note indicates to other optimizations that this this branching 3365169689Skaninstruction should not be ``collapsed'' into a simpler branching 3366169689Skanconstruct. It is used when the optimization to partition basic blocks 3367169689Skaninto hot and cold sections is turned on. 3368169689Skan 3369169689Skan@findex REG_SETJMP 3370169689Skan@item REG_SETJMP 3371169689SkanAppears attached to each @code{CALL_INSN} to @code{setjmp} or a 3372169689Skanrelated function. 337390075Sobrien@end table 337490075Sobrien 337590075SobrienThe following notes describe attributes of outputs of an insn: 337690075Sobrien 337790075Sobrien@table @code 337890075Sobrien@findex REG_EQUIV 337990075Sobrien@findex REG_EQUAL 338090075Sobrien@item REG_EQUIV 338190075Sobrien@itemx REG_EQUAL 338290075SobrienThis note is only valid on an insn that sets only one register and 338390075Sobrienindicates that that register will be equal to @var{op} at run time; the 338490075Sobrienscope of this equivalence differs between the two types of notes. The 338590075Sobrienvalue which the insn explicitly copies into the register may look 338690075Sobriendifferent from @var{op}, but they will be equal at run time. If the 338790075Sobrienoutput of the single @code{set} is a @code{strict_low_part} expression, 338890075Sobrienthe note refers to the register that is contained in @code{SUBREG_REG} 338990075Sobrienof the @code{subreg} expression. 339090075Sobrien 339190075SobrienFor @code{REG_EQUIV}, the register is equivalent to @var{op} throughout 339290075Sobrienthe entire function, and could validly be replaced in all its 339390075Sobrienoccurrences by @var{op}. (``Validly'' here refers to the data flow of 339490075Sobrienthe program; simple replacement may make some insns invalid.) For 339590075Sobrienexample, when a constant is loaded into a register that is never 339690075Sobrienassigned any other value, this kind of note is used. 339790075Sobrien 339890075SobrienWhen a parameter is copied into a pseudo-register at entry to a function, 339990075Sobriena note of this kind records that the register is equivalent to the stack 340090075Sobrienslot where the parameter was passed. Although in this case the register 340190075Sobrienmay be set by other insns, it is still valid to replace the register 340290075Sobrienby the stack slot throughout the function. 340390075Sobrien 340490075SobrienA @code{REG_EQUIV} note is also used on an instruction which copies a 340590075Sobrienregister parameter into a pseudo-register at entry to a function, if 340690075Sobrienthere is a stack slot where that parameter could be stored. Although 340790075Sobrienother insns may set the pseudo-register, it is valid for the compiler to 340890075Sobrienreplace the pseudo-register by stack slot throughout the function, 340990075Sobrienprovided the compiler ensures that the stack slot is properly 341090075Sobrieninitialized by making the replacement in the initial copy instruction as 341190075Sobrienwell. This is used on machines for which the calling convention 341290075Sobrienallocates stack space for register parameters. See 341390075Sobrien@code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}. 341490075Sobrien 341590075SobrienIn the case of @code{REG_EQUAL}, the register that is set by this insn 341690075Sobrienwill be equal to @var{op} at run time at the end of this insn but not 341790075Sobriennecessarily elsewhere in the function. In this case, @var{op} 341890075Sobrienis typically an arithmetic expression. For example, when a sequence of 341990075Sobrieninsns such as a library call is used to perform an arithmetic operation, 342090075Sobrienthis kind of note is attached to the insn that produces or copies the 342190075Sobrienfinal value. 342290075Sobrien 342390075SobrienThese two notes are used in different ways by the compiler passes. 342490075Sobrien@code{REG_EQUAL} is used by passes prior to register allocation (such as 342590075Sobriencommon subexpression elimination and loop optimization) to tell them how 342690075Sobriento think of that value. @code{REG_EQUIV} notes are used by register 342790075Sobrienallocation to indicate that there is an available substitute expression 342890075Sobrien(either a constant or a @code{mem} expression for the location of a 342990075Sobrienparameter on the stack) that may be used in place of a register if 343090075Sobrieninsufficient registers are available. 343190075Sobrien 343290075SobrienExcept for stack homes for parameters, which are indicated by a 343390075Sobrien@code{REG_EQUIV} note and are not useful to the early optimization 343490075Sobrienpasses and pseudo registers that are equivalent to a memory location 343590075Sobrienthroughout their entire life, which is not detected until later in 343690075Sobrienthe compilation, all equivalences are initially indicated by an attached 343790075Sobrien@code{REG_EQUAL} note. In the early stages of register allocation, a 343890075Sobrien@code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if 343990075Sobrien@var{op} is a constant and the insn represents the only set of its 344090075Sobriendestination register. 344190075Sobrien 344290075SobrienThus, compiler passes prior to register allocation need only check for 344390075Sobrien@code{REG_EQUAL} notes and passes subsequent to register allocation 344490075Sobrienneed only check for @code{REG_EQUIV} notes. 344590075Sobrien@end table 344690075Sobrien 344790075SobrienThese notes describe linkages between insns. They occur in pairs: one 344890075Sobrieninsn has one of a pair of notes that points to a second insn, which has 344990075Sobrienthe inverse note pointing back to the first insn. 345090075Sobrien 345190075Sobrien@table @code 345290075Sobrien@findex REG_RETVAL 345390075Sobrien@item REG_RETVAL 345490075SobrienThis insn copies the value of a multi-insn sequence (for example, a 345590075Sobrienlibrary call), and @var{op} is the first insn of the sequence (for a 345690075Sobrienlibrary call, the first insn that was generated to set up the arguments 345790075Sobrienfor the library call). 345890075Sobrien 345990075SobrienLoop optimization uses this note to treat such a sequence as a single 346090075Sobrienoperation for code motion purposes and flow analysis uses this note to 346190075Sobriendelete such sequences whose results are dead. 346290075Sobrien 346390075SobrienA @code{REG_EQUAL} note will also usually be attached to this insn to 346490075Sobrienprovide the expression being computed by the sequence. 346590075Sobrien 346690075SobrienThese notes will be deleted after reload, since they are no longer 346790075Sobrienaccurate or useful. 346890075Sobrien 346990075Sobrien@findex REG_LIBCALL 347090075Sobrien@item REG_LIBCALL 347190075SobrienThis is the inverse of @code{REG_RETVAL}: it is placed on the first 347290075Sobrieninsn of a multi-insn sequence, and it points to the last one. 347390075Sobrien 347490075SobrienThese notes are deleted after reload, since they are no longer useful or 347590075Sobrienaccurate. 347690075Sobrien 347790075Sobrien@findex REG_CC_SETTER 347890075Sobrien@findex REG_CC_USER 347990075Sobrien@item REG_CC_SETTER 348090075Sobrien@itemx REG_CC_USER 348190075SobrienOn machines that use @code{cc0}, the insns which set and use @code{cc0} 348290075Sobrienset and use @code{cc0} are adjacent. However, when branch delay slot 348390075Sobrienfilling is done, this may no longer be true. In this case a 348490075Sobrien@code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to 348590075Sobrienpoint to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will 348690075Sobrienbe placed on the insn using @code{cc0} to point to the insn setting 348790075Sobrien@code{cc0}. 348890075Sobrien@end table 348990075Sobrien 349090075SobrienThese values are only used in the @code{LOG_LINKS} field, and indicate 349190075Sobrienthe type of dependency that each link represents. Links which indicate 349290075Sobriena data dependence (a read after write dependence) do not use any code, 349390075Sobrienthey simply have mode @code{VOIDmode}, and are printed without any 349490075Sobriendescriptive text. 349590075Sobrien 349690075Sobrien@table @code 349790075Sobrien@findex REG_DEP_ANTI 349890075Sobrien@item REG_DEP_ANTI 349990075SobrienThis indicates an anti dependence (a write after read dependence). 350090075Sobrien 350190075Sobrien@findex REG_DEP_OUTPUT 350290075Sobrien@item REG_DEP_OUTPUT 350390075SobrienThis indicates an output dependence (a write after write dependence). 350490075Sobrien@end table 350590075Sobrien 350690075SobrienThese notes describe information gathered from gcov profile data. They 350790075Sobrienare stored in the @code{REG_NOTES} field of an insn as an 350890075Sobrien@code{expr_list}. 350990075Sobrien 351090075Sobrien@table @code 351190075Sobrien@findex REG_BR_PROB 351290075Sobrien@item REG_BR_PROB 351390075SobrienThis is used to specify the ratio of branches to non-branches of a 351490075Sobrienbranch insn according to the profile data. The value is stored as a 351590075Sobrienvalue between 0 and REG_BR_PROB_BASE; larger values indicate a higher 351690075Sobrienprobability that the branch will be taken. 351790075Sobrien 351890075Sobrien@findex REG_BR_PRED 351990075Sobrien@item REG_BR_PRED 352090075SobrienThese notes are found in JUMP insns after delayed branch scheduling 352190075Sobrienhas taken place. They indicate both the direction and the likelihood 352290075Sobrienof the JUMP@. The format is a bitmask of ATTR_FLAG_* values. 352390075Sobrien 352490075Sobrien@findex REG_FRAME_RELATED_EXPR 352590075Sobrien@item REG_FRAME_RELATED_EXPR 352690075SobrienThis is used on an RTX_FRAME_RELATED_P insn wherein the attached expression 352790075Sobrienis used in place of the actual insn pattern. This is done in cases where 352890075Sobrienthe pattern is either complex or misleading. 352990075Sobrien@end table 353090075Sobrien 353190075SobrienFor convenience, the machine mode in an @code{insn_list} or 353290075Sobrien@code{expr_list} is printed using these symbolic codes in debugging dumps. 353390075Sobrien 353490075Sobrien@findex insn_list 353590075Sobrien@findex expr_list 353690075SobrienThe only difference between the expression codes @code{insn_list} and 353790075Sobrien@code{expr_list} is that the first operand of an @code{insn_list} is 353890075Sobrienassumed to be an insn and is printed in debugging dumps as the insn's 353990075Sobrienunique id; the first operand of an @code{expr_list} is printed in the 354090075Sobrienordinary way as an expression. 354190075Sobrien 354290075Sobrien@node Calls 354390075Sobrien@section RTL Representation of Function-Call Insns 354490075Sobrien@cindex calling functions in RTL 354590075Sobrien@cindex RTL function-call insns 354690075Sobrien@cindex function-call insns 354790075Sobrien 354890075SobrienInsns that call subroutines have the RTL expression code @code{call_insn}. 354990075SobrienThese insns must satisfy special rules, and their bodies must use a special 355090075SobrienRTL expression code, @code{call}. 355190075Sobrien 355290075Sobrien@cindex @code{call} usage 355390075SobrienA @code{call} expression has two operands, as follows: 355490075Sobrien 3555132718Skan@smallexample 355690075Sobrien(call (mem:@var{fm} @var{addr}) @var{nbytes}) 3557132718Skan@end smallexample 355890075Sobrien 355990075Sobrien@noindent 356090075SobrienHere @var{nbytes} is an operand that represents the number of bytes of 356190075Sobrienargument data being passed to the subroutine, @var{fm} is a machine mode 356290075Sobrien(which must equal as the definition of the @code{FUNCTION_MODE} macro in 356390075Sobrienthe machine description) and @var{addr} represents the address of the 356490075Sobriensubroutine. 356590075Sobrien 356690075SobrienFor a subroutine that returns no value, the @code{call} expression as 356790075Sobrienshown above is the entire body of the insn, except that the insn might 356890075Sobrienalso contain @code{use} or @code{clobber} expressions. 356990075Sobrien 357090075Sobrien@cindex @code{BLKmode}, and function return values 357190075SobrienFor a subroutine that returns a value whose mode is not @code{BLKmode}, 357290075Sobrienthe value is returned in a hard register. If this register's number is 357390075Sobrien@var{r}, then the body of the call insn looks like this: 357490075Sobrien 3575132718Skan@smallexample 357690075Sobrien(set (reg:@var{m} @var{r}) 357790075Sobrien (call (mem:@var{fm} @var{addr}) @var{nbytes})) 3578132718Skan@end smallexample 357990075Sobrien 358090075Sobrien@noindent 358190075SobrienThis RTL expression makes it clear (to the optimizer passes) that the 358290075Sobrienappropriate register receives a useful value in this insn. 358390075Sobrien 358490075SobrienWhen a subroutine returns a @code{BLKmode} value, it is handled by 358590075Sobrienpassing to the subroutine the address of a place to store the value. 358690075SobrienSo the call insn itself does not ``return'' any value, and it has the 358790075Sobriensame RTL form as a call that returns nothing. 358890075Sobrien 358990075SobrienOn some machines, the call instruction itself clobbers some register, 359090075Sobrienfor example to contain the return address. @code{call_insn} insns 359190075Sobrienon these machines should have a body which is a @code{parallel} 359290075Sobrienthat contains both the @code{call} expression and @code{clobber} 359390075Sobrienexpressions that indicate which registers are destroyed. Similarly, 359490075Sobrienif the call instruction requires some register other than the stack 3595169689Skanpointer that is not explicitly mentioned in its RTL, a @code{use} 359690075Sobriensubexpression should mention that register. 359790075Sobrien 359890075SobrienFunctions that are called are assumed to modify all registers listed in 359990075Sobrienthe configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register 360090075SobrienBasics}) and, with the exception of @code{const} functions and library 360190075Sobriencalls, to modify all of memory. 360290075Sobrien 360390075SobrienInsns containing just @code{use} expressions directly precede the 360490075Sobrien@code{call_insn} insn to indicate which registers contain inputs to the 360590075Sobrienfunction. Similarly, if registers other than those in 360690075Sobrien@code{CALL_USED_REGISTERS} are clobbered by the called function, insns 360790075Sobriencontaining a single @code{clobber} follow immediately after the call to 360890075Sobrienindicate which registers. 360990075Sobrien 361090075Sobrien@node Sharing 361190075Sobrien@section Structure Sharing Assumptions 361290075Sobrien@cindex sharing of RTL components 361390075Sobrien@cindex RTL structure sharing assumptions 361490075Sobrien 361590075SobrienThe compiler assumes that certain kinds of RTL expressions are unique; 361690075Sobrienthere do not exist two distinct objects representing the same value. 361790075SobrienIn other cases, it makes an opposite assumption: that no RTL expression 361890075Sobrienobject of a certain kind appears in more than one place in the 361990075Sobriencontaining structure. 362090075Sobrien 362190075SobrienThese assumptions refer to a single function; except for the RTL 362290075Sobrienobjects that describe global variables and external functions, 362390075Sobrienand a few standard objects such as small integer constants, 362490075Sobrienno RTL objects are common to two functions. 362590075Sobrien 362690075Sobrien@itemize @bullet 362790075Sobrien@cindex @code{reg}, RTL sharing 362890075Sobrien@item 362990075SobrienEach pseudo-register has only a single @code{reg} object to represent it, 363090075Sobrienand therefore only a single machine mode. 363190075Sobrien 363290075Sobrien@cindex symbolic label 363390075Sobrien@cindex @code{symbol_ref}, RTL sharing 363490075Sobrien@item 363590075SobrienFor any symbolic label, there is only one @code{symbol_ref} object 363690075Sobrienreferring to it. 363790075Sobrien 363890075Sobrien@cindex @code{const_int}, RTL sharing 363990075Sobrien@item 364090075SobrienAll @code{const_int} expressions with equal values are shared. 364190075Sobrien 364290075Sobrien@cindex @code{pc}, RTL sharing 364390075Sobrien@item 364490075SobrienThere is only one @code{pc} expression. 364590075Sobrien 364690075Sobrien@cindex @code{cc0}, RTL sharing 364790075Sobrien@item 364890075SobrienThere is only one @code{cc0} expression. 364990075Sobrien 365090075Sobrien@cindex @code{const_double}, RTL sharing 365190075Sobrien@item 365290075SobrienThere is only one @code{const_double} expression with value 0 for 365390075Sobrieneach floating point mode. Likewise for values 1 and 2. 365490075Sobrien 365596263Sobrien@cindex @code{const_vector}, RTL sharing 365696263Sobrien@item 365796263SobrienThere is only one @code{const_vector} expression with value 0 for 365896263Sobrieneach vector mode, be it an integer or a double constant vector. 365996263Sobrien 366090075Sobrien@cindex @code{label_ref}, RTL sharing 366190075Sobrien@cindex @code{scratch}, RTL sharing 366290075Sobrien@item 366390075SobrienNo @code{label_ref} or @code{scratch} appears in more than one place in 366490075Sobrienthe RTL structure; in other words, it is safe to do a tree-walk of all 366590075Sobrienthe insns in the function and assume that each time a @code{label_ref} 366690075Sobrienor @code{scratch} is seen it is distinct from all others that are seen. 366790075Sobrien 366890075Sobrien@cindex @code{mem}, RTL sharing 366990075Sobrien@item 367090075SobrienOnly one @code{mem} object is normally created for each static 367190075Sobrienvariable or stack slot, so these objects are frequently shared in all 367290075Sobrienthe places they appear. However, separate but equal objects for these 367390075Sobrienvariables are occasionally made. 367490075Sobrien 367590075Sobrien@cindex @code{asm_operands}, RTL sharing 367690075Sobrien@item 367790075SobrienWhen a single @code{asm} statement has multiple output operands, a 367890075Sobriendistinct @code{asm_operands} expression is made for each output operand. 367990075SobrienHowever, these all share the vector which contains the sequence of input 368090075Sobrienoperands. This sharing is used later on to test whether two 368190075Sobrien@code{asm_operands} expressions come from the same statement, so all 368290075Sobrienoptimizations must carefully preserve the sharing if they copy the 368390075Sobrienvector at all. 368490075Sobrien 368590075Sobrien@item 368690075SobrienNo RTL object appears in more than one place in the RTL structure 368790075Sobrienexcept as described above. Many passes of the compiler rely on this 368890075Sobrienby assuming that they can modify RTL objects in place without unwanted 368990075Sobrienside-effects on other insns. 369090075Sobrien 369190075Sobrien@findex unshare_all_rtl 369290075Sobrien@item 369390075SobrienDuring initial RTL generation, shared structure is freely introduced. 369490075SobrienAfter all the RTL for a function has been generated, all shared 369590075Sobrienstructure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c}, 369690075Sobrienafter which the above rules are guaranteed to be followed. 369790075Sobrien 369890075Sobrien@findex copy_rtx_if_shared 369990075Sobrien@item 370090075SobrienDuring the combiner pass, shared structure within an insn can exist 370190075Sobrientemporarily. However, the shared structure is copied before the 370290075Sobriencombiner is finished with the insn. This is done by calling 370390075Sobrien@code{copy_rtx_if_shared}, which is a subroutine of 370490075Sobrien@code{unshare_all_rtl}. 370590075Sobrien@end itemize 370690075Sobrien 370790075Sobrien@node Reading RTL 370890075Sobrien@section Reading RTL 370990075Sobrien 371090075SobrienTo read an RTL object from a file, call @code{read_rtx}. It takes one 371190075Sobrienargument, a stdio stream, and returns a single RTL object. This routine 371290075Sobrienis defined in @file{read-rtl.c}. It is not available in the compiler 371390075Sobrienitself, only the various programs that generate the compiler back end 371490075Sobrienfrom the machine description. 371590075Sobrien 371690075SobrienPeople frequently have the idea of using RTL stored as text in a file as 371790075Sobrienan interface between a language front end and the bulk of GCC@. This 371890075Sobrienidea is not feasible. 371990075Sobrien 372090075SobrienGCC was designed to use RTL internally only. Correct RTL for a given 372190075Sobrienprogram is very dependent on the particular target machine. And the RTL 372290075Sobriendoes not contain all the information about the program. 372390075Sobrien 372490075SobrienThe proper way to interface GCC to a new language front end is with 372590075Sobrienthe ``tree'' data structure, described in the files @file{tree.h} and 372690075Sobrien@file{tree.def}. The documentation for this structure (@pxref{Trees}) 372790075Sobrienis incomplete. 3728