OSDN Git Service

* df.h (struct df_ref): Replace 'insn' field with 'insn_info' field.
[pf3gnuchains/gcc-fork.git] / gcc / doc / rtl.texi
1 @c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002,
2 @c 2003, 2004, 2005, 2006, 2007, 2008
3 @c Free Software Foundation, Inc.
4 @c This is part of the GCC manual.
5 @c For copying conditions, see the file gcc.texi.
6
7 @node RTL
8 @chapter RTL Representation
9 @cindex RTL representation
10 @cindex representation of RTL
11 @cindex Register Transfer Language (RTL)
12
13 Most of the work of the compiler is done on an intermediate representation
14 called register transfer language.  In this language, the instructions to be
15 output are described, pretty much one by one, in an algebraic form that
16 describes what the instruction does.
17
18 RTL is inspired by Lisp lists.  It has both an internal form, made up of
19 structures that point at other structures, and a textual form that is used
20 in the machine description and in printed debugging dumps.  The textual
21 form uses nested parentheses to indicate the pointers in the internal form.
22
23 @menu
24 * RTL Objects::       Expressions vs vectors vs strings vs integers.
25 * RTL Classes::       Categories of RTL expression objects, and their structure.
26 * Accessors::         Macros to access expression operands or vector elts.
27 * Special Accessors:: Macros to access specific annotations on RTL.
28 * Flags::             Other flags in an RTL expression.
29 * Machine Modes::     Describing the size and format of a datum.
30 * Constants::         Expressions with constant values.
31 * Regs and Memory::   Expressions representing register contents or memory.
32 * Arithmetic::        Expressions representing arithmetic on other expressions.
33 * Comparisons::       Expressions representing comparison of expressions.
34 * Bit-Fields::        Expressions representing bit-fields in memory or reg.
35 * Vector Operations:: Expressions involving vector datatypes.
36 * Conversions::       Extending, truncating, floating or fixing.
37 * RTL Declarations::  Declaring volatility, constancy, etc.
38 * Side Effects::      Expressions for storing in registers, etc.
39 * Incdec::            Embedded side-effects for autoincrement addressing.
40 * Assembler::         Representing @code{asm} with operands.
41 * Insns::             Expression types for entire insns.
42 * Calls::             RTL representation of function call insns.
43 * Sharing::           Some expressions are unique; others *must* be copied.
44 * Reading RTL::       Reading textual RTL from a file.
45 @end menu
46
47 @node RTL Objects
48 @section RTL Object Types
49 @cindex RTL object types
50
51 @cindex RTL integers
52 @cindex RTL strings
53 @cindex RTL vectors
54 @cindex RTL expression
55 @cindex RTX (See RTL)
56 RTL uses five kinds of objects: expressions, integers, wide integers,
57 strings and vectors.  Expressions are the most important ones.  An RTL
58 expression (``RTX'', for short) is a C structure, but it is usually
59 referred to with a pointer; a type that is given the typedef name
60 @code{rtx}.
61
62 An integer is simply an @code{int}; their written form uses decimal
63 digits.  A wide integer is an integral object whose type is
64 @code{HOST_WIDE_INT}; their written form uses decimal digits.
65
66 A string is a sequence of characters.  In core it is represented as a
67 @code{char *} in usual C fashion, and it is written in C syntax as well.
68 However, strings in RTL may never be null.  If you write an empty string in
69 a machine description, it is represented in core as a null pointer rather
70 than as a pointer to a null character.  In certain contexts, these null
71 pointers instead of strings are valid.  Within RTL code, strings are most
72 commonly found inside @code{symbol_ref} expressions, but they appear in
73 other contexts in the RTL expressions that make up machine descriptions.
74
75 In a machine description, strings are normally written with double
76 quotes, as you would in C@.  However, strings in machine descriptions may
77 extend over many lines, which is invalid C, and adjacent string
78 constants are not concatenated as they are in C@.  Any string constant
79 may be surrounded with a single set of parentheses.  Sometimes this
80 makes the machine description easier to read.
81
82 There is also a special syntax for strings, which can be useful when C
83 code is embedded in a machine description.  Wherever a string can
84 appear, it is also valid to write a C-style brace block.  The entire
85 brace block, including the outermost pair of braces, is considered to be
86 the string constant.  Double quote characters inside the braces are not
87 special.  Therefore, if you write string constants in the C code, you
88 need not escape each quote character with a backslash.
89
90 A vector contains an arbitrary number of pointers to expressions.  The
91 number of elements in the vector is explicitly present in the vector.
92 The written form of a vector consists of square brackets
93 (@samp{[@dots{}]}) surrounding the elements, in sequence and with
94 whitespace separating them.  Vectors of length zero are not created;
95 null pointers are used instead.
96
97 @cindex expression codes
98 @cindex codes, RTL expression
99 @findex GET_CODE
100 @findex PUT_CODE
101 Expressions are classified by @dfn{expression codes} (also called RTX
102 codes).  The expression code is a name defined in @file{rtl.def}, which is
103 also (in uppercase) a C enumeration constant.  The possible expression
104 codes and their meanings are machine-independent.  The code of an RTX can
105 be extracted with the macro @code{GET_CODE (@var{x})} and altered with
106 @code{PUT_CODE (@var{x}, @var{newcode})}.
107
108 The expression code determines how many operands the expression contains,
109 and what kinds of objects they are.  In RTL, unlike Lisp, you cannot tell
110 by looking at an operand what kind of object it is.  Instead, you must know
111 from its context---from the expression code of the containing expression.
112 For example, in an expression of code @code{subreg}, the first operand is
113 to be regarded as an expression and the second operand as an integer.  In
114 an expression of code @code{plus}, there are two operands, both of which
115 are to be regarded as expressions.  In a @code{symbol_ref} expression,
116 there is one operand, which is to be regarded as a string.
117
118 Expressions are written as parentheses containing the name of the
119 expression type, its flags and machine mode if any, and then the operands
120 of the expression (separated by spaces).
121
122 Expression code names in the @samp{md} file are written in lowercase,
123 but when they appear in C code they are written in uppercase.  In this
124 manual, they are shown as follows: @code{const_int}.
125
126 @cindex (nil)
127 @cindex nil
128 In a few contexts a null pointer is valid where an expression is normally
129 wanted.  The written form of this is @code{(nil)}.
130
131 @node RTL Classes
132 @section RTL Classes and Formats
133 @cindex RTL classes
134 @cindex classes of RTX codes
135 @cindex RTX codes, classes of
136 @findex GET_RTX_CLASS
137
138 The various expression codes are divided into several @dfn{classes},
139 which are represented by single characters.  You can determine the class
140 of an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}.
141 Currently, @file{rtl.def} defines these classes:
142
143 @table @code
144 @item RTX_OBJ
145 An RTX code that represents an actual object, such as a register
146 (@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}).
147 @code{LO_SUM}) is also included; instead, @code{SUBREG} and
148 @code{STRICT_LOW_PART} are not in this class, but in class @code{x}.
149
150 @item RTX_CONST_OBJ
151 An RTX code that represents a constant object.  @code{HIGH} is also
152 included in this class.
153
154 @item RTX_COMPARE
155 An RTX code for a non-symmetric comparison, such as @code{GEU} or
156 @code{LT}.
157
158 @item RTX_COMM_COMPARE
159 An RTX code for a symmetric (commutative) comparison, such as @code{EQ}
160 or @code{ORDERED}.
161
162 @item RTX_UNARY
163 An RTX code for a unary arithmetic operation, such as @code{NEG},
164 @code{NOT}, or @code{ABS}.  This category also includes value extension
165 (sign or zero) and conversions between integer and floating point.
166
167 @item RTX_COMM_ARITH
168 An RTX code for a commutative binary operation, such as @code{PLUS} or
169 @code{AND}.  @code{NE} and @code{EQ} are comparisons, so they have class
170 @code{<}.
171
172 @item RTX_BIN_ARITH
173 An RTX code for a non-commutative binary operation, such as @code{MINUS},
174 @code{DIV}, or @code{ASHIFTRT}.
175
176 @item RTX_BITFIELD_OPS
177 An RTX code for a bit-field operation.  Currently only
178 @code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}.  These have three inputs
179 and are lvalues (so they can be used for insertion as well).
180 @xref{Bit-Fields}.
181
182 @item RTX_TERNARY
183 An RTX code for other three input operations.  Currently only
184 @code{IF_THEN_ELSE} and @code{VEC_MERGE}.
185
186 @item RTX_INSN
187 An RTX code for an entire instruction:  @code{INSN}, @code{JUMP_INSN}, and
188 @code{CALL_INSN}.  @xref{Insns}.
189
190 @item RTX_MATCH
191 An RTX code for something that matches in insns, such as
192 @code{MATCH_DUP}.  These only occur in machine descriptions.
193
194 @item RTX_AUTOINC
195 An RTX code for an auto-increment addressing mode, such as
196 @code{POST_INC}.
197
198 @item RTX_EXTRA
199 All other RTX codes.  This category includes the remaining codes used
200 only in machine descriptions (@code{DEFINE_*}, etc.).  It also includes
201 all the codes describing side effects (@code{SET}, @code{USE},
202 @code{CLOBBER}, etc.) and the non-insns that may appear on an insn
203 chain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}.
204 @code{SUBREG} is also part of this class.
205 @end table
206
207 @cindex RTL format
208 For each expression code, @file{rtl.def} specifies the number of
209 contained objects and their kinds using a sequence of characters
210 called the @dfn{format} of the expression code.  For example,
211 the format of @code{subreg} is @samp{ei}.
212
213 @cindex RTL format characters
214 These are the most commonly used format characters:
215
216 @table @code
217 @item e
218 An expression (actually a pointer to an expression).
219
220 @item i
221 An integer.
222
223 @item w
224 A wide integer.
225
226 @item s
227 A string.
228
229 @item E
230 A vector of expressions.
231 @end table
232
233 A few other format characters are used occasionally:
234
235 @table @code
236 @item u
237 @samp{u} is equivalent to @samp{e} except that it is printed differently
238 in debugging dumps.  It is used for pointers to insns.
239
240 @item n
241 @samp{n} is equivalent to @samp{i} except that it is printed differently
242 in debugging dumps.  It is used for the line number or code number of a
243 @code{note} insn.
244
245 @item S
246 @samp{S} indicates a string which is optional.  In the RTL objects in
247 core, @samp{S} is equivalent to @samp{s}, but when the object is read,
248 from an @samp{md} file, the string value of this operand may be omitted.
249 An omitted string is taken to be the null string.
250
251 @item V
252 @samp{V} indicates a vector which is optional.  In the RTL objects in
253 core, @samp{V} is equivalent to @samp{E}, but when the object is read
254 from an @samp{md} file, the vector value of this operand may be omitted.
255 An omitted vector is effectively the same as a vector of no elements.
256
257 @item B
258 @samp{B} indicates a pointer to basic block structure.
259
260 @item 0
261 @samp{0} means a slot whose contents do not fit any normal category.
262 @samp{0} slots are not printed at all in dumps, and are often used in
263 special ways by small parts of the compiler.
264 @end table
265
266 There are macros to get the number of operands and the format
267 of an expression code:
268
269 @table @code
270 @findex GET_RTX_LENGTH
271 @item GET_RTX_LENGTH (@var{code})
272 Number of operands of an RTX of code @var{code}.
273
274 @findex GET_RTX_FORMAT
275 @item GET_RTX_FORMAT (@var{code})
276 The format of an RTX of code @var{code}, as a C string.
277 @end table
278
279 Some classes of RTX codes always have the same format.  For example, it
280 is safe to assume that all comparison operations have format @code{ee}.
281
282 @table @code
283 @item 1
284 All codes of this class have format @code{e}.
285
286 @item <
287 @itemx c
288 @itemx 2
289 All codes of these classes have format @code{ee}.
290
291 @item b
292 @itemx 3
293 All codes of these classes have format @code{eee}.
294
295 @item i
296 All codes of this class have formats that begin with @code{iuueiee}.
297 @xref{Insns}.  Note that not all RTL objects linked onto an insn chain
298 are of class @code{i}.
299
300 @item o
301 @itemx m
302 @itemx x
303 You can make no assumptions about the format of these codes.
304 @end table
305
306 @node Accessors
307 @section Access to Operands
308 @cindex accessors
309 @cindex access to operands
310 @cindex operand access
311
312 @findex XEXP
313 @findex XINT
314 @findex XWINT
315 @findex XSTR
316 Operands of expressions are accessed using the macros @code{XEXP},
317 @code{XINT}, @code{XWINT} and @code{XSTR}.  Each of these macros takes
318 two arguments: an expression-pointer (RTX) and an operand number
319 (counting from zero).  Thus,
320
321 @smallexample
322 XEXP (@var{x}, 2)
323 @end smallexample
324
325 @noindent
326 accesses operand 2 of expression @var{x}, as an expression.
327
328 @smallexample
329 XINT (@var{x}, 2)
330 @end smallexample
331
332 @noindent
333 accesses the same operand as an integer.  @code{XSTR}, used in the same
334 fashion, would access it as a string.
335
336 Any operand can be accessed as an integer, as an expression or as a string.
337 You must choose the correct method of access for the kind of value actually
338 stored in the operand.  You would do this based on the expression code of
339 the containing expression.  That is also how you would know how many
340 operands there are.
341
342 For example, if @var{x} is a @code{subreg} expression, you know that it has
343 two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
344 and @code{XINT (@var{x}, 1)}.  If you did @code{XINT (@var{x}, 0)}, you
345 would get the address of the expression operand but cast as an integer;
346 that might occasionally be useful, but it would be cleaner to write
347 @code{(int) XEXP (@var{x}, 0)}.  @code{XEXP (@var{x}, 1)} would also
348 compile without error, and would return the second, integer operand cast as
349 an expression pointer, which would probably result in a crash when
350 accessed.  Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
351 but this will access memory past the end of the expression with
352 unpredictable results.
353
354 Access to operands which are vectors is more complicated.  You can use the
355 macro @code{XVEC} to get the vector-pointer itself, or the macros
356 @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
357 vector.
358
359 @table @code
360 @findex XVEC
361 @item XVEC (@var{exp}, @var{idx})
362 Access the vector-pointer which is operand number @var{idx} in @var{exp}.
363
364 @findex XVECLEN
365 @item XVECLEN (@var{exp}, @var{idx})
366 Access the length (number of elements) in the vector which is
367 in operand number @var{idx} in @var{exp}.  This value is an @code{int}.
368
369 @findex XVECEXP
370 @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
371 Access element number @var{eltnum} in the vector which is
372 in operand number @var{idx} in @var{exp}.  This value is an RTX@.
373
374 It is up to you to make sure that @var{eltnum} is not negative
375 and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
376 @end table
377
378 All the macros defined in this section expand into lvalues and therefore
379 can be used to assign the operands, lengths and vector elements as well as
380 to access them.
381
382 @node Special Accessors
383 @section Access to Special Operands
384 @cindex access to special operands
385
386 Some RTL nodes have special annotations associated with them.
387
388 @table @code
389 @item MEM
390 @table @code
391 @findex MEM_ALIAS_SET
392 @item MEM_ALIAS_SET (@var{x})
393 If 0, @var{x} is not in any alias set, and may alias anything.  Otherwise,
394 @var{x} can only alias @code{MEM}s in a conflicting alias set.  This value
395 is set in a language-dependent manner in the front-end, and should not be
396 altered in the back-end.  In some front-ends, these numbers may correspond
397 in some way to types, or other language-level entities, but they need not,
398 and the back-end makes no such assumptions.
399 These set numbers are tested with @code{alias_sets_conflict_p}.
400
401 @findex MEM_EXPR
402 @item MEM_EXPR (@var{x})
403 If this register is known to hold the value of some user-level
404 declaration, this is that tree node.  It may also be a
405 @code{COMPONENT_REF}, in which case this is some field reference,
406 and @code{TREE_OPERAND (@var{x}, 0)} contains the declaration,
407 or another @code{COMPONENT_REF}, or null if there is no compile-time
408 object associated with the reference.
409
410 @findex MEM_OFFSET
411 @item MEM_OFFSET (@var{x})
412 The offset from the start of @code{MEM_EXPR} as a @code{CONST_INT} rtx.
413
414 @findex MEM_SIZE
415 @item MEM_SIZE (@var{x})
416 The size in bytes of the memory reference as a @code{CONST_INT} rtx.
417 This is mostly relevant for @code{BLKmode} references as otherwise
418 the size is implied by the mode.
419
420 @findex MEM_ALIGN
421 @item MEM_ALIGN (@var{x})
422 The known alignment in bits of the memory reference.
423 @end table
424
425 @item REG
426 @table @code
427 @findex ORIGINAL_REGNO
428 @item ORIGINAL_REGNO (@var{x})
429 This field holds the number the register ``originally'' had; for a
430 pseudo register turned into a hard reg this will hold the old pseudo
431 register number.
432
433 @findex REG_EXPR
434 @item REG_EXPR (@var{x})
435 If this register is known to hold the value of some user-level
436 declaration, this is that tree node.
437
438 @findex REG_OFFSET
439 @item REG_OFFSET (@var{x})
440 If this register is known to hold the value of some user-level
441 declaration, this is the offset into that logical storage.
442 @end table
443
444 @item SYMBOL_REF
445 @table @code
446 @findex SYMBOL_REF_DECL
447 @item SYMBOL_REF_DECL (@var{x})
448 If the @code{symbol_ref} @var{x} was created for a @code{VAR_DECL} or
449 a @code{FUNCTION_DECL}, that tree is recorded here.  If this value is
450 null, then @var{x} was created by back end code generation routines,
451 and there is no associated front end symbol table entry.
452
453 @code{SYMBOL_REF_DECL} may also point to a tree of class @code{'c'},
454 that is, some sort of constant.  In this case, the @code{symbol_ref}
455 is an entry in the per-file constant pool; again, there is no associated
456 front end symbol table entry.
457
458 @findex SYMBOL_REF_CONSTANT
459 @item SYMBOL_REF_CONSTANT (@var{x})
460 If @samp{CONSTANT_POOL_ADDRESS_P (@var{x})} is true, this is the constant
461 pool entry for @var{x}.  It is null otherwise.
462
463 @findex SYMBOL_REF_DATA
464 @item SYMBOL_REF_DATA (@var{x})
465 A field of opaque type used to store @code{SYMBOL_REF_DECL} or
466 @code{SYMBOL_REF_CONSTANT}.
467
468 @findex SYMBOL_REF_FLAGS
469 @item SYMBOL_REF_FLAGS (@var{x})
470 In a @code{symbol_ref}, this is used to communicate various predicates
471 about the symbol.  Some of these are common enough to be computed by
472 common code, some are specific to the target.  The common bits are:
473
474 @table @code
475 @findex SYMBOL_REF_FUNCTION_P
476 @findex SYMBOL_FLAG_FUNCTION
477 @item SYMBOL_FLAG_FUNCTION
478 Set if the symbol refers to a function.
479
480 @findex SYMBOL_REF_LOCAL_P
481 @findex SYMBOL_FLAG_LOCAL
482 @item SYMBOL_FLAG_LOCAL
483 Set if the symbol is local to this ``module''.
484 See @code{TARGET_BINDS_LOCAL_P}.
485
486 @findex SYMBOL_REF_EXTERNAL_P
487 @findex SYMBOL_FLAG_EXTERNAL
488 @item SYMBOL_FLAG_EXTERNAL
489 Set if this symbol is not defined in this translation unit.
490 Note that this is not the inverse of @code{SYMBOL_FLAG_LOCAL}.
491
492 @findex SYMBOL_REF_SMALL_P
493 @findex SYMBOL_FLAG_SMALL
494 @item SYMBOL_FLAG_SMALL
495 Set if the symbol is located in the small data section.
496 See @code{TARGET_IN_SMALL_DATA_P}.
497
498 @findex SYMBOL_FLAG_TLS_SHIFT
499 @findex SYMBOL_REF_TLS_MODEL
500 @item SYMBOL_REF_TLS_MODEL (@var{x})
501 This is a multi-bit field accessor that returns the @code{tls_model}
502 to be used for a thread-local storage symbol.  It returns zero for
503 non-thread-local symbols.
504
505 @findex SYMBOL_REF_HAS_BLOCK_INFO_P
506 @findex SYMBOL_FLAG_HAS_BLOCK_INFO
507 @item SYMBOL_FLAG_HAS_BLOCK_INFO
508 Set if the symbol has @code{SYMBOL_REF_BLOCK} and
509 @code{SYMBOL_REF_BLOCK_OFFSET} fields.
510
511 @findex SYMBOL_REF_ANCHOR_P
512 @findex SYMBOL_FLAG_ANCHOR
513 @cindex @option{-fsection-anchors}
514 @item SYMBOL_FLAG_ANCHOR
515 Set if the symbol is used as a section anchor.  ``Section anchors''
516 are symbols that have a known position within an @code{object_block}
517 and that can be used to access nearby members of that block.
518 They are used to implement @option{-fsection-anchors}.
519
520 If this flag is set, then @code{SYMBOL_FLAG_HAS_BLOCK_INFO} will be too.
521 @end table
522
523 Bits beginning with @code{SYMBOL_FLAG_MACH_DEP} are available for
524 the target's use.
525 @end table
526
527 @findex SYMBOL_REF_BLOCK
528 @item SYMBOL_REF_BLOCK (@var{x})
529 If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the
530 @samp{object_block} structure to which the symbol belongs,
531 or @code{NULL} if it has not been assigned a block.
532
533 @findex SYMBOL_REF_BLOCK_OFFSET
534 @item SYMBOL_REF_BLOCK_OFFSET (@var{x})
535 If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the offset of @var{x}
536 from the first object in @samp{SYMBOL_REF_BLOCK (@var{x})}.  The value is
537 negative if @var{x} has not yet been assigned to a block, or it has not
538 been given an offset within that block.
539 @end table
540
541 @node Flags
542 @section Flags in an RTL Expression
543 @cindex flags in RTL expression
544
545 RTL expressions contain several flags (one-bit bit-fields)
546 that are used in certain types of expression.  Most often they
547 are accessed with the following macros, which expand into lvalues.
548
549 @table @code
550 @findex CONSTANT_POOL_ADDRESS_P
551 @cindex @code{symbol_ref} and @samp{/u}
552 @cindex @code{unchanging}, in @code{symbol_ref}
553 @item CONSTANT_POOL_ADDRESS_P (@var{x})
554 Nonzero in a @code{symbol_ref} if it refers to part of the current
555 function's constant pool.  For most targets these addresses are in a
556 @code{.rodata} section entirely separate from the function, but for
557 some targets the addresses are close to the beginning of the function.
558 In either case GCC assumes these addresses can be addressed directly,
559 perhaps with the help of base registers.
560 Stored in the @code{unchanging} field and printed as @samp{/u}.
561
562 @findex RTL_CONST_CALL_P
563 @cindex @code{call_insn} and @samp{/u}
564 @cindex @code{unchanging}, in @code{call_insn}
565 @item RTL_CONST_CALL_P (@var{x})
566 In a @code{call_insn} indicates that the insn represents a call to a
567 const function.  Stored in the @code{unchanging} field and printed as
568 @samp{/u}.
569
570 @findex RTL_PURE_CALL_P
571 @cindex @code{call_insn} and @samp{/i}
572 @cindex @code{return_val}, in @code{call_insn}
573 @item RTL_PURE_CALL_P (@var{x})
574 In a @code{call_insn} indicates that the insn represents a call to a
575 pure function.  Stored in the @code{return_val} field and printed as
576 @samp{/i}.
577
578 @findex RTL_CONST_OR_PURE_CALL_P
579 @cindex @code{call_insn} and @samp{/u} or @samp{/i}
580 @item RTL_CONST_OR_PURE_CALL_P (@var{x})
581 In a @code{call_insn}, true if @code{RTL_CONST_CALL_P} or
582 @code{RTL_PURE_CALL_P} is true.
583
584 @findex RTL_LOOPING_CONST_OR_PURE_CALL_P
585 @cindex @code{call_insn} and @samp{/c}
586 @cindex @code{call}, in @code{call_insn}
587 @item RTL_LOOPING_CONST_OR_PURE_CALL_P (@var{x})
588 In a @code{call_insn} indicates that the insn represents a possibly
589 infinite looping call to a const or pure function.  Stored in the
590 @code{call} field and printed as @samp{/c}.  Only true if one of
591 @code{RTL_CONST_CALL_P} or @code{RTL_PURE_CALL_P} is true.
592
593 @findex INSN_ANNULLED_BRANCH_P
594 @cindex @code{jump_insn} and @samp{/u}
595 @cindex @code{call_insn} and @samp{/u}
596 @cindex @code{insn} and @samp{/u}
597 @cindex @code{unchanging}, in @code{jump_insn}, @code{call_insn} and @code{insn}
598 @item INSN_ANNULLED_BRANCH_P (@var{x})
599 In a @code{jump_insn}, @code{call_insn}, or @code{insn} indicates
600 that the branch is an annulling one.  See the discussion under
601 @code{sequence} below.  Stored in the @code{unchanging} field and
602 printed as @samp{/u}.
603
604 @findex INSN_DELETED_P
605 @cindex @code{insn} and @samp{/v}
606 @cindex @code{call_insn} and @samp{/v}
607 @cindex @code{jump_insn} and @samp{/v}
608 @cindex @code{code_label} and @samp{/v}
609 @cindex @code{barrier} and @samp{/v}
610 @cindex @code{note} and @samp{/v}
611 @cindex @code{volatil}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, @code{barrier}, and @code{note}
612 @item INSN_DELETED_P (@var{x})
613 In an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label},
614 @code{barrier}, or @code{note},
615 nonzero if the insn has been deleted.  Stored in the
616 @code{volatil} field and printed as @samp{/v}.
617
618 @findex INSN_FROM_TARGET_P
619 @cindex @code{insn} and @samp{/s}
620 @cindex @code{jump_insn} and @samp{/s}
621 @cindex @code{call_insn} and @samp{/s}
622 @cindex @code{in_struct}, in @code{insn} and @code{jump_insn} and @code{call_insn}
623 @item INSN_FROM_TARGET_P (@var{x})
624 In an @code{insn} or @code{jump_insn} or @code{call_insn} in a delay
625 slot of a branch, indicates that the insn
626 is from the target of the branch.  If the branch insn has
627 @code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if
628 the branch is taken.  For annulled branches with
629 @code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the
630 branch is not taken.  When @code{INSN_ANNULLED_BRANCH_P} is not set,
631 this insn will always be executed.  Stored in the @code{in_struct}
632 field and printed as @samp{/s}.
633
634 @findex LABEL_PRESERVE_P
635 @cindex @code{code_label} and @samp{/i}
636 @cindex @code{note} and @samp{/i}
637 @cindex @code{in_struct}, in @code{code_label} and @code{note}
638 @item LABEL_PRESERVE_P (@var{x})
639 In a @code{code_label} or @code{note}, indicates that the label is referenced by
640 code or data not visible to the RTL of a given function.
641 Labels referenced by a non-local goto will have this bit set.  Stored
642 in the @code{in_struct} field and printed as @samp{/s}.
643
644 @findex LABEL_REF_NONLOCAL_P
645 @cindex @code{label_ref} and @samp{/v}
646 @cindex @code{reg_label} and @samp{/v}
647 @cindex @code{volatil}, in @code{label_ref} and @code{reg_label}
648 @item LABEL_REF_NONLOCAL_P (@var{x})
649 In @code{label_ref} and @code{reg_label} expressions, nonzero if this is
650 a reference to a non-local label.
651 Stored in the @code{volatil} field and printed as @samp{/v}.
652
653 @findex MEM_IN_STRUCT_P
654 @cindex @code{mem} and @samp{/s}
655 @cindex @code{in_struct}, in @code{mem}
656 @item MEM_IN_STRUCT_P (@var{x})
657 In @code{mem} expressions, nonzero for reference to an entire structure,
658 union or array, or to a component of one.  Zero for references to a
659 scalar variable or through a pointer to a scalar.  If both this flag and
660 @code{MEM_SCALAR_P} are clear, then we don't know whether this @code{mem}
661 is in a structure or not.  Both flags should never be simultaneously set.
662 Stored in the @code{in_struct} field and printed as @samp{/s}.
663
664 @findex MEM_KEEP_ALIAS_SET_P
665 @cindex @code{mem} and @samp{/j}
666 @cindex @code{jump}, in @code{mem}
667 @item MEM_KEEP_ALIAS_SET_P (@var{x})
668 In @code{mem} expressions, 1 if we should keep the alias set for this
669 mem unchanged when we access a component.  Set to 1, for example, when we
670 are already in a non-addressable component of an aggregate.
671 Stored in the @code{jump} field and printed as @samp{/j}.
672
673 @findex MEM_SCALAR_P
674 @cindex @code{mem} and @samp{/i}
675 @cindex @code{return_val}, in @code{mem}
676 @item MEM_SCALAR_P (@var{x})
677 In @code{mem} expressions, nonzero for reference to a scalar known not
678 to be a member of a structure, union, or array.  Zero for such
679 references and for indirections through pointers, even pointers pointing
680 to scalar types.  If both this flag and @code{MEM_IN_STRUCT_P} are clear,
681 then we don't know whether this @code{mem} is in a structure or not.
682 Both flags should never be simultaneously set.
683 Stored in the @code{return_val} field and printed as @samp{/i}.
684
685 @findex MEM_VOLATILE_P
686 @cindex @code{mem} and @samp{/v}
687 @cindex @code{asm_input} and @samp{/v}
688 @cindex @code{asm_operands} and @samp{/v}
689 @cindex @code{volatil}, in @code{mem}, @code{asm_operands}, and @code{asm_input}
690 @item MEM_VOLATILE_P (@var{x})
691 In @code{mem}, @code{asm_operands}, and @code{asm_input} expressions,
692 nonzero for volatile memory references.
693 Stored in the @code{volatil} field and printed as @samp{/v}.
694
695 @findex MEM_NOTRAP_P
696 @cindex @code{mem} and @samp{/c}
697 @cindex @code{call}, in @code{mem}
698 @item MEM_NOTRAP_P (@var{x})
699 In @code{mem}, nonzero for memory references that will not trap.
700 Stored in the @code{call} field and printed as @samp{/c}.
701
702 @findex MEM_POINTER
703 @cindex @code{mem} and @samp{/f}
704 @cindex @code{frame_related}, in @code{mem}
705 @item MEM_POINTER (@var{x})
706 Nonzero in a @code{mem} if the memory reference holds a pointer.
707 Stored in the @code{frame_related} field and printed as @samp{/f}.
708
709 @findex REG_FUNCTION_VALUE_P
710 @cindex @code{reg} and @samp{/i}
711 @cindex @code{return_val}, in @code{reg}
712 @item REG_FUNCTION_VALUE_P (@var{x})
713 Nonzero in a @code{reg} if it is the place in which this function's
714 value is going to be returned.  (This happens only in a hard
715 register.)  Stored in the @code{return_val} field and printed as
716 @samp{/i}.
717
718 @findex REG_POINTER
719 @cindex @code{reg} and @samp{/f}
720 @cindex @code{frame_related}, in @code{reg}
721 @item REG_POINTER (@var{x})
722 Nonzero in a @code{reg} if the register holds a pointer.  Stored in the
723 @code{frame_related} field and printed as @samp{/f}.
724
725 @findex REG_USERVAR_P
726 @cindex @code{reg} and @samp{/v}
727 @cindex @code{volatil}, in @code{reg}
728 @item REG_USERVAR_P (@var{x})
729 In a @code{reg}, nonzero if it corresponds to a variable present in
730 the user's source code.  Zero for temporaries generated internally by
731 the compiler.  Stored in the @code{volatil} field and printed as
732 @samp{/v}.
733
734 The same hard register may be used also for collecting the values of
735 functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
736 in this kind of use.
737
738 @findex RTX_FRAME_RELATED_P
739 @cindex @code{insn} and @samp{/f}
740 @cindex @code{call_insn} and @samp{/f}
741 @cindex @code{jump_insn} and @samp{/f}
742 @cindex @code{barrier} and @samp{/f}
743 @cindex @code{set} and @samp{/f}
744 @cindex @code{frame_related}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, and @code{set}
745 @item RTX_FRAME_RELATED_P (@var{x})
746 Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn},
747 @code{barrier}, or @code{set} which is part of a function prologue
748 and sets the stack pointer, sets the frame pointer, or saves a register.
749 This flag should also be set on an instruction that sets up a temporary
750 register to use in place of the frame pointer.
751 Stored in the @code{frame_related} field and printed as @samp{/f}.
752
753 In particular, on RISC targets where there are limits on the sizes of
754 immediate constants, it is sometimes impossible to reach the register
755 save area directly from the stack pointer.  In that case, a temporary
756 register is used that is near enough to the register save area, and the
757 Canonical Frame Address, i.e., DWARF2's logical frame pointer, register
758 must (temporarily) be changed to be this temporary register.  So, the
759 instruction that sets this temporary register must be marked as
760 @code{RTX_FRAME_RELATED_P}.
761
762 If the marked instruction is overly complex (defined in terms of what
763 @code{dwarf2out_frame_debug_expr} can handle), you will also have to
764 create a @code{REG_FRAME_RELATED_EXPR} note and attach it to the
765 instruction.  This note should contain a simple expression of the
766 computation performed by this instruction, i.e., one that
767 @code{dwarf2out_frame_debug_expr} can handle.
768
769 This flag is required for exception handling support on targets with RTL
770 prologues.
771
772 @findex MEM_READONLY_P
773 @cindex @code{mem} and @samp{/u}
774 @cindex @code{unchanging}, in @code{mem}
775 @item MEM_READONLY_P (@var{x})
776 Nonzero in a @code{mem}, if the memory is statically allocated and read-only.
777
778 Read-only in this context means never modified during the lifetime of the
779 program, not necessarily in ROM or in write-disabled pages.  A common
780 example of the later is a shared library's global offset table.  This
781 table is initialized by the runtime loader, so the memory is technically
782 writable, but after control is transfered from the runtime loader to the
783 application, this memory will never be subsequently modified.
784
785 Stored in the @code{unchanging} field and printed as @samp{/u}.
786
787 @findex SCHED_GROUP_P
788 @cindex @code{insn} and @samp{/s}
789 @cindex @code{call_insn} and @samp{/s}
790 @cindex @code{jump_insn} and @samp{/s}
791 @cindex @code{in_struct}, in @code{insn}, @code{jump_insn} and @code{call_insn}
792 @item SCHED_GROUP_P (@var{x})
793 During instruction scheduling, in an @code{insn}, @code{call_insn} or
794 @code{jump_insn}, indicates that the
795 previous insn must be scheduled together with this insn.  This is used to
796 ensure that certain groups of instructions will not be split up by the
797 instruction scheduling pass, for example, @code{use} insns before
798 a @code{call_insn} may not be separated from the @code{call_insn}.
799 Stored in the @code{in_struct} field and printed as @samp{/s}.
800
801 @findex SET_IS_RETURN_P
802 @cindex @code{insn} and @samp{/j}
803 @cindex @code{jump}, in @code{insn}
804 @item SET_IS_RETURN_P (@var{x})
805 For a @code{set}, nonzero if it is for a return.
806 Stored in the @code{jump} field and printed as @samp{/j}.
807
808 @findex SIBLING_CALL_P
809 @cindex @code{call_insn} and @samp{/j}
810 @cindex @code{jump}, in @code{call_insn}
811 @item SIBLING_CALL_P (@var{x})
812 For a @code{call_insn}, nonzero if the insn is a sibling call.
813 Stored in the @code{jump} field and printed as @samp{/j}.
814
815 @findex STRING_POOL_ADDRESS_P
816 @cindex @code{symbol_ref} and @samp{/f}
817 @cindex @code{frame_related}, in @code{symbol_ref}
818 @item STRING_POOL_ADDRESS_P (@var{x})
819 For a @code{symbol_ref} expression, nonzero if it addresses this function's
820 string constant pool.
821 Stored in the @code{frame_related} field and printed as @samp{/f}.
822
823 @findex SUBREG_PROMOTED_UNSIGNED_P
824 @cindex @code{subreg} and @samp{/u} and @samp{/v}
825 @cindex @code{unchanging}, in @code{subreg}
826 @cindex @code{volatil}, in @code{subreg}
827 @item SUBREG_PROMOTED_UNSIGNED_P (@var{x})
828 Returns a value greater then zero for a @code{subreg} that has
829 @code{SUBREG_PROMOTED_VAR_P} nonzero if the object being referenced is kept
830 zero-extended, zero if it is kept sign-extended, and less then zero if it is
831 extended some other way via the @code{ptr_extend} instruction.
832 Stored in the @code{unchanging}
833 field and @code{volatil} field, printed as @samp{/u} and @samp{/v}.
834 This macro may only be used to get the value it may not be used to change
835 the value.  Use @code{SUBREG_PROMOTED_UNSIGNED_SET} to change the value.
836
837 @findex SUBREG_PROMOTED_UNSIGNED_SET
838 @cindex @code{subreg} and @samp{/u}
839 @cindex @code{unchanging}, in @code{subreg}
840 @cindex @code{volatil}, in @code{subreg}
841 @item SUBREG_PROMOTED_UNSIGNED_SET (@var{x})
842 Set the @code{unchanging} and @code{volatil} fields in a @code{subreg}
843 to reflect zero, sign, or other extension.  If @code{volatil} is
844 zero, then @code{unchanging} as nonzero means zero extension and as
845 zero means sign extension.  If @code{volatil} is nonzero then some
846 other type of extension was done via the @code{ptr_extend} instruction.
847
848 @findex SUBREG_PROMOTED_VAR_P
849 @cindex @code{subreg} and @samp{/s}
850 @cindex @code{in_struct}, in @code{subreg}
851 @item SUBREG_PROMOTED_VAR_P (@var{x})
852 Nonzero in a @code{subreg} if it was made when accessing an object that
853 was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine
854 description macro (@pxref{Storage Layout}).  In this case, the mode of
855 the @code{subreg} is the declared mode of the object and the mode of
856 @code{SUBREG_REG} is the mode of the register that holds the object.
857 Promoted variables are always either sign- or zero-extended to the wider
858 mode on every assignment.  Stored in the @code{in_struct} field and
859 printed as @samp{/s}.
860
861 @findex SYMBOL_REF_USED
862 @cindex @code{used}, in @code{symbol_ref}
863 @item SYMBOL_REF_USED (@var{x})
864 In a @code{symbol_ref}, indicates that @var{x} has been used.  This is
865 normally only used to ensure that @var{x} is only declared external
866 once.  Stored in the @code{used} field.
867
868 @findex SYMBOL_REF_WEAK
869 @cindex @code{symbol_ref} and @samp{/i}
870 @cindex @code{return_val}, in @code{symbol_ref}
871 @item SYMBOL_REF_WEAK (@var{x})
872 In a @code{symbol_ref}, indicates that @var{x} has been declared weak.
873 Stored in the @code{return_val} field and printed as @samp{/i}.
874
875 @findex SYMBOL_REF_FLAG
876 @cindex @code{symbol_ref} and @samp{/v}
877 @cindex @code{volatil}, in @code{symbol_ref}
878 @item SYMBOL_REF_FLAG (@var{x})
879 In a @code{symbol_ref}, this is used as a flag for machine-specific purposes.
880 Stored in the @code{volatil} field and printed as @samp{/v}.
881
882 Most uses of @code{SYMBOL_REF_FLAG} are historic and may be subsumed
883 by @code{SYMBOL_REF_FLAGS}.  Certainly use of @code{SYMBOL_REF_FLAGS}
884 is mandatory if the target requires more than one bit of storage.
885 @end table
886
887 These are the fields to which the above macros refer:
888
889 @table @code
890 @findex call
891 @cindex @samp{/c} in RTL dump
892 @item call
893 In a @code{mem}, 1 means that the memory reference will not trap.
894
895 In a @code{call}, 1 means that this pure or const call may possibly
896 infinite loop.
897
898 In an RTL dump, this flag is represented as @samp{/c}.
899
900 @findex frame_related
901 @cindex @samp{/f} in RTL dump
902 @item frame_related
903 In an @code{insn} or @code{set} expression, 1 means that it is part of
904 a function prologue and sets the stack pointer, sets the frame pointer,
905 saves a register, or sets up a temporary register to use in place of the
906 frame pointer.
907
908 In @code{reg} expressions, 1 means that the register holds a pointer.
909
910 In @code{mem} expressions, 1 means that the memory reference holds a pointer.
911
912 In @code{symbol_ref} expressions, 1 means that the reference addresses
913 this function's string constant pool.
914
915 In an RTL dump, this flag is represented as @samp{/f}.
916
917 @findex in_struct
918 @cindex @samp{/s} in RTL dump
919 @item in_struct
920 In @code{mem} expressions, it is 1 if the memory datum referred to is
921 all or part of a structure or array; 0 if it is (or might be) a scalar
922 variable.  A reference through a C pointer has 0 because the pointer
923 might point to a scalar variable.  This information allows the compiler
924 to determine something about possible cases of aliasing.
925
926 In @code{reg} expressions, it is 1 if the register has its entire life
927 contained within the test expression of some loop.
928
929 In @code{subreg} expressions, 1 means that the @code{subreg} is accessing
930 an object that has had its mode promoted from a wider mode.
931
932 In @code{label_ref} expressions, 1 means that the referenced label is
933 outside the innermost loop containing the insn in which the @code{label_ref}
934 was found.
935
936 In @code{code_label} expressions, it is 1 if the label may never be deleted.
937 This is used for labels which are the target of non-local gotos.  Such a
938 label that would have been deleted is replaced with a @code{note} of type
939 @code{NOTE_INSN_DELETED_LABEL}.
940
941 In an @code{insn} during dead-code elimination, 1 means that the insn is
942 dead code.
943
944 In an @code{insn} or @code{jump_insn} during reorg for an insn in the
945 delay slot of a branch,
946 1 means that this insn is from the target of the branch.
947
948 In an @code{insn} during instruction scheduling, 1 means that this insn
949 must be scheduled as part of a group together with the previous insn.
950
951 In an RTL dump, this flag is represented as @samp{/s}.
952
953 @findex return_val
954 @cindex @samp{/i} in RTL dump
955 @item return_val
956 In @code{reg} expressions, 1 means the register contains
957 the value to be returned by the current function.  On
958 machines that pass parameters in registers, the same register number
959 may be used for parameters as well, but this flag is not set on such
960 uses.
961
962 In @code{mem} expressions, 1 means the memory reference is to a scalar
963 known not to be a member of a structure, union, or array.
964
965 In @code{symbol_ref} expressions, 1 means the referenced symbol is weak.
966
967 In @code{call} expressions, 1 means the call is pure.
968
969 In an RTL dump, this flag is represented as @samp{/i}.
970
971 @findex jump
972 @cindex @samp{/j} in RTL dump
973 @item jump
974 In a @code{mem} expression, 1 means we should keep the alias set for this
975 mem unchanged when we access a component.
976
977 In a @code{set}, 1 means it is for a return.
978
979 In a @code{call_insn}, 1 means it is a sibling call.
980
981 In an RTL dump, this flag is represented as @samp{/j}.
982
983 @findex unchanging
984 @cindex @samp{/u} in RTL dump
985 @item unchanging
986 In @code{reg} and @code{mem} expressions, 1 means
987 that the value of the expression never changes.
988
989 In @code{subreg} expressions, it is 1 if the @code{subreg} references an
990 unsigned object whose mode has been promoted to a wider mode.
991
992 In an @code{insn} or @code{jump_insn} in the delay slot of a branch
993 instruction, 1 means an annulling branch should be used.
994
995 In a @code{symbol_ref} expression, 1 means that this symbol addresses
996 something in the per-function constant pool.
997
998 In a @code{call_insn} 1 means that this instruction is a call to a const
999 function.
1000
1001 In an RTL dump, this flag is represented as @samp{/u}.
1002
1003 @findex used
1004 @item used
1005 This flag is used directly (without an access macro) at the end of RTL
1006 generation for a function, to count the number of times an expression
1007 appears in insns.  Expressions that appear more than once are copied,
1008 according to the rules for shared structure (@pxref{Sharing}).
1009
1010 For a @code{reg}, it is used directly (without an access macro) by the
1011 leaf register renumbering code to ensure that each register is only
1012 renumbered once.
1013
1014 In a @code{symbol_ref}, it indicates that an external declaration for
1015 the symbol has already been written.
1016
1017 @findex volatil
1018 @cindex @samp{/v} in RTL dump
1019 @item volatil
1020 @cindex volatile memory references
1021 In a @code{mem}, @code{asm_operands}, or @code{asm_input}
1022 expression, it is 1 if the memory
1023 reference is volatile.  Volatile memory references may not be deleted,
1024 reordered or combined.
1025
1026 In a @code{symbol_ref} expression, it is used for machine-specific
1027 purposes.
1028
1029 In a @code{reg} expression, it is 1 if the value is a user-level variable.
1030 0 indicates an internal compiler temporary.
1031
1032 In an @code{insn}, 1 means the insn has been deleted.
1033
1034 In @code{label_ref} and @code{reg_label} expressions, 1 means a reference
1035 to a non-local label.
1036
1037 In an RTL dump, this flag is represented as @samp{/v}.
1038 @end table
1039
1040 @node Machine Modes
1041 @section Machine Modes
1042 @cindex machine modes
1043
1044 @findex enum machine_mode
1045 A machine mode describes a size of data object and the representation used
1046 for it.  In the C code, machine modes are represented by an enumeration
1047 type, @code{enum machine_mode}, defined in @file{machmode.def}.  Each RTL
1048 expression has room for a machine mode and so do certain kinds of tree
1049 expressions (declarations and types, to be precise).
1050
1051 In debugging dumps and machine descriptions, the machine mode of an RTL
1052 expression is written after the expression code with a colon to separate
1053 them.  The letters @samp{mode} which appear at the end of each machine mode
1054 name are omitted.  For example, @code{(reg:SI 38)} is a @code{reg}
1055 expression with machine mode @code{SImode}.  If the mode is
1056 @code{VOIDmode}, it is not written at all.
1057
1058 Here is a table of machine modes.  The term ``byte'' below refers to an
1059 object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}).
1060
1061 @table @code
1062 @findex BImode
1063 @item BImode
1064 ``Bit'' mode represents a single bit, for predicate registers.
1065
1066 @findex QImode
1067 @item QImode
1068 ``Quarter-Integer'' mode represents a single byte treated as an integer.
1069
1070 @findex HImode
1071 @item HImode
1072 ``Half-Integer'' mode represents a two-byte integer.
1073
1074 @findex PSImode
1075 @item PSImode
1076 ``Partial Single Integer'' mode represents an integer which occupies
1077 four bytes but which doesn't really use all four.  On some machines,
1078 this is the right mode to use for pointers.
1079
1080 @findex SImode
1081 @item SImode
1082 ``Single Integer'' mode represents a four-byte integer.
1083
1084 @findex PDImode
1085 @item PDImode
1086 ``Partial Double Integer'' mode represents an integer which occupies
1087 eight bytes but which doesn't really use all eight.  On some machines,
1088 this is the right mode to use for certain pointers.
1089
1090 @findex DImode
1091 @item DImode
1092 ``Double Integer'' mode represents an eight-byte integer.
1093
1094 @findex TImode
1095 @item TImode
1096 ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
1097
1098 @findex OImode
1099 @item OImode
1100 ``Octa Integer'' (?) mode represents a thirty-two-byte integer.
1101
1102 @findex QFmode
1103 @item QFmode
1104 ``Quarter-Floating'' mode represents a quarter-precision (single byte)
1105 floating point number.
1106
1107 @findex HFmode
1108 @item HFmode
1109 ``Half-Floating'' mode represents a half-precision (two byte) floating
1110 point number.
1111
1112 @findex TQFmode
1113 @item TQFmode
1114 ``Three-Quarter-Floating'' (?) mode represents a three-quarter-precision
1115 (three byte) floating point number.
1116
1117 @findex SFmode
1118 @item SFmode
1119 ``Single Floating'' mode represents a four byte floating point number.
1120 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1121 this is a single-precision IEEE floating point number; it can also be
1122 used for double-precision (on processors with 16-bit bytes) and
1123 single-precision VAX and IBM types.
1124
1125 @findex DFmode
1126 @item DFmode
1127 ``Double Floating'' mode represents an eight byte floating point number.
1128 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1129 this is a double-precision IEEE floating point number.
1130
1131 @findex XFmode
1132 @item XFmode
1133 ``Extended Floating'' mode represents an IEEE extended floating point
1134 number.  This mode only has 80 meaningful bits (ten bytes).  Some
1135 processors require such numbers to be padded to twelve bytes, others
1136 to sixteen; this mode is used for either.
1137
1138 @findex SDmode
1139 @item SDmode
1140 ``Single Decimal Floating'' mode represents a four byte decimal
1141 floating point number (as distinct from conventional binary floating
1142 point).
1143
1144 @findex DDmode
1145 @item DDmode
1146 ``Double Decimal Floating'' mode represents an eight byte decimal
1147 floating point number.
1148
1149 @findex TDmode
1150 @item TDmode
1151 ``Tetra Decimal Floating'' mode represents a sixteen byte decimal
1152 floating point number all 128 of whose bits are meaningful.
1153
1154 @findex TFmode
1155 @item TFmode
1156 ``Tetra Floating'' mode represents a sixteen byte floating point number
1157 all 128 of whose bits are meaningful.  One common use is the
1158 IEEE quad-precision format.
1159
1160 @findex QQmode
1161 @item QQmode
1162 ``Quarter-Fractional'' mode represents a single byte treated as a signed
1163 fractional number.  The default format is ``s.7''.
1164
1165 @findex HQmode
1166 @item HQmode
1167 ``Half-Fractional'' mode represents a two-byte signed fractional number.
1168 The default format is ``s.15''.
1169
1170 @findex SQmode
1171 @item SQmode
1172 ``Single Fractional'' mode represents a four-byte signed fractional number.
1173 The default format is ``s.31''.
1174
1175 @findex DQmode
1176 @item DQmode
1177 ``Double Fractional'' mode represents an eight-byte signed fractional number.
1178 The default format is ``s.63''.
1179
1180 @findex TQmode
1181 @item TQmode
1182 ``Tetra Fractional'' mode represents a sixteen-byte signed fractional number.
1183 The default format is ``s.127''.
1184
1185 @findex UQQmode
1186 @item UQQmode
1187 ``Unsigned Quarter-Fractional'' mode represents a single byte treated as an
1188 unsigned fractional number.  The default format is ``.8''.
1189
1190 @findex UHQmode
1191 @item UHQmode
1192 ``Unsigned Half-Fractional'' mode represents a two-byte unsigned fractional
1193 number.  The default format is ``.16''.
1194
1195 @findex USQmode
1196 @item USQmode
1197 ``Unsigned Single Fractional'' mode represents a four-byte unsigned fractional
1198 number.  The default format is ``.32''.
1199
1200 @findex UDQmode
1201 @item UDQmode
1202 ``Unsigned Double Fractional'' mode represents an eight-byte unsigned
1203 fractional number.  The default format is ``.64''.
1204
1205 @findex UTQmode
1206 @item UTQmode
1207 ``Unsigned Tetra Fractional'' mode represents a sixteen-byte unsigned
1208 fractional number.  The default format is ``.128''.
1209
1210 @findex HAmode
1211 @item HAmode
1212 ``Half-Accumulator'' mode represents a two-byte signed accumulator.
1213 The default format is ``s8.7''.
1214
1215 @findex SAmode
1216 @item SAmode
1217 ``Single Accumulator'' mode represents a four-byte signed accumulator.
1218 The default format is ``s16.15''.
1219
1220 @findex DAmode
1221 @item DAmode
1222 ``Double Accumulator'' mode represents an eight-byte signed accumulator.
1223 The default format is ``s32.31''.
1224
1225 @findex TAmode
1226 @item TAmode
1227 ``Tetra Accumulator'' mode represents a sixteen-byte signed accumulator.
1228 The default format is ``s64.63''.
1229
1230 @findex UHAmode
1231 @item UHAmode
1232 ``Unsigned Half-Accumulator'' mode represents a two-byte unsigned accumulator.
1233 The default format is ``8.8''.
1234
1235 @findex USAmode
1236 @item USAmode
1237 ``Unsigned Single Accumulator'' mode represents a four-byte unsigned
1238 accumulator.  The default format is ``16.16''.
1239
1240 @findex UDAmode
1241 @item UDAmode
1242 ``Unsigned Double Accumulator'' mode represents an eight-byte unsigned
1243 accumulator.  The default format is ``32.32''.
1244
1245 @findex UTAmode
1246 @item UTAmode
1247 ``Unsigned Tetra Accumulator'' mode represents a sixteen-byte unsigned
1248 accumulator.  The default format is ``64.64''.
1249
1250 @findex CCmode
1251 @item CCmode
1252 ``Condition Code'' mode represents the value of a condition code, which
1253 is a machine-specific set of bits used to represent the result of a
1254 comparison operation.  Other machine-specific modes may also be used for
1255 the condition code.  These modes are not used on machines that use
1256 @code{cc0} (see @pxref{Condition Code}).
1257
1258 @findex BLKmode
1259 @item BLKmode
1260 ``Block'' mode represents values that are aggregates to which none of
1261 the other modes apply.  In RTL, only memory references can have this mode,
1262 and only if they appear in string-move or vector instructions.  On machines
1263 which have no such instructions, @code{BLKmode} will not appear in RTL@.
1264
1265 @findex VOIDmode
1266 @item VOIDmode
1267 Void mode means the absence of a mode or an unspecified mode.
1268 For example, RTL expressions of code @code{const_int} have mode
1269 @code{VOIDmode} because they can be taken to have whatever mode the context
1270 requires.  In debugging dumps of RTL, @code{VOIDmode} is expressed by
1271 the absence of any mode.
1272
1273 @findex QCmode
1274 @findex HCmode
1275 @findex SCmode
1276 @findex DCmode
1277 @findex XCmode
1278 @findex TCmode
1279 @item QCmode, HCmode, SCmode, DCmode, XCmode, TCmode
1280 These modes stand for a complex number represented as a pair of floating
1281 point values.  The floating point values are in @code{QFmode},
1282 @code{HFmode}, @code{SFmode}, @code{DFmode}, @code{XFmode}, and
1283 @code{TFmode}, respectively.
1284
1285 @findex CQImode
1286 @findex CHImode
1287 @findex CSImode
1288 @findex CDImode
1289 @findex CTImode
1290 @findex COImode
1291 @item CQImode, CHImode, CSImode, CDImode, CTImode, COImode
1292 These modes stand for a complex number represented as a pair of integer
1293 values.  The integer values are in @code{QImode}, @code{HImode},
1294 @code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode},
1295 respectively.
1296 @end table
1297
1298 The machine description defines @code{Pmode} as a C macro which expands
1299 into the machine mode used for addresses.  Normally this is the mode
1300 whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines.
1301
1302 The only modes which a machine description @i{must} support are
1303 @code{QImode}, and the modes corresponding to @code{BITS_PER_WORD},
1304 @code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}.
1305 The compiler will attempt to use @code{DImode} for 8-byte structures and
1306 unions, but this can be prevented by overriding the definition of
1307 @code{MAX_FIXED_MODE_SIZE}.  Alternatively, you can have the compiler
1308 use @code{TImode} for 16-byte structures and unions.  Likewise, you can
1309 arrange for the C type @code{short int} to avoid using @code{HImode}.
1310
1311 @cindex mode classes
1312 Very few explicit references to machine modes remain in the compiler and
1313 these few references will soon be removed.  Instead, the machine modes
1314 are divided into mode classes.  These are represented by the enumeration
1315 type @code{enum mode_class} defined in @file{machmode.h}.  The possible
1316 mode classes are:
1317
1318 @table @code
1319 @findex MODE_INT
1320 @item MODE_INT
1321 Integer modes.  By default these are @code{BImode}, @code{QImode},
1322 @code{HImode}, @code{SImode}, @code{DImode}, @code{TImode}, and
1323 @code{OImode}.
1324
1325 @findex MODE_PARTIAL_INT
1326 @item MODE_PARTIAL_INT
1327 The ``partial integer'' modes, @code{PQImode}, @code{PHImode},
1328 @code{PSImode} and @code{PDImode}.
1329
1330 @findex MODE_FLOAT
1331 @item MODE_FLOAT
1332 Floating point modes.  By default these are @code{QFmode},
1333 @code{HFmode}, @code{TQFmode}, @code{SFmode}, @code{DFmode},
1334 @code{XFmode} and @code{TFmode}.
1335
1336 @findex MODE_DECIMAL_FLOAT
1337 @item MODE_DECIMAL_FLOAT
1338 Decimal floating point modes.  By default these are @code{SDmode},
1339 @code{DDmode} and @code{TDmode}.
1340
1341 @findex MODE_FRACT
1342 @item MODE_FRACT
1343 Signed fractional modes.  By default these are @code{QQmode}, @code{HQmode},
1344 @code{SQmode}, @code{DQmode} and @code{TQmode}.
1345
1346 @findex MODE_UFRACT
1347 @item MODE_UFRACT
1348 Unsigned fractional modes.  By default these are @code{UQQmode}, @code{UHQmode},
1349 @code{USQmode}, @code{UDQmode} and @code{UTQmode}.
1350
1351 @findex MODE_ACCUM
1352 @item MODE_ACCUM
1353 Signed accumulator modes.  By default these are @code{HAmode},
1354 @code{SAmode}, @code{DAmode} and @code{TAmode}.
1355
1356 @findex MODE_UACCUM
1357 @item MODE_UACCUM
1358 Unsigned accumulator modes.  By default these are @code{UHAmode},
1359 @code{USAmode}, @code{UDAmode} and @code{UTAmode}.
1360
1361 @findex MODE_COMPLEX_INT
1362 @item MODE_COMPLEX_INT
1363 Complex integer modes.  (These are not currently implemented).
1364
1365 @findex MODE_COMPLEX_FLOAT
1366 @item MODE_COMPLEX_FLOAT
1367 Complex floating point modes.  By default these are @code{QCmode},
1368 @code{HCmode}, @code{SCmode}, @code{DCmode}, @code{XCmode}, and
1369 @code{TCmode}.
1370
1371 @findex MODE_FUNCTION
1372 @item MODE_FUNCTION
1373 Algol or Pascal function variables including a static chain.
1374 (These are not currently implemented).
1375
1376 @findex MODE_CC
1377 @item MODE_CC
1378 Modes representing condition code values.  These are @code{CCmode} plus
1379 any @code{CC_MODE} modes listed in the @file{@var{machine}-modes.def}.  
1380 @xref{Jump Patterns},
1381 also see @ref{Condition Code}.
1382
1383 @findex MODE_RANDOM
1384 @item MODE_RANDOM
1385 This is a catchall mode class for modes which don't fit into the above
1386 classes.  Currently @code{VOIDmode} and @code{BLKmode} are in
1387 @code{MODE_RANDOM}.
1388 @end table
1389
1390 Here are some C macros that relate to machine modes:
1391
1392 @table @code
1393 @findex GET_MODE
1394 @item GET_MODE (@var{x})
1395 Returns the machine mode of the RTX @var{x}.
1396
1397 @findex PUT_MODE
1398 @item PUT_MODE (@var{x}, @var{newmode})
1399 Alters the machine mode of the RTX @var{x} to be @var{newmode}.
1400
1401 @findex NUM_MACHINE_MODES
1402 @item NUM_MACHINE_MODES
1403 Stands for the number of machine modes available on the target
1404 machine.  This is one greater than the largest numeric value of any
1405 machine mode.
1406
1407 @findex GET_MODE_NAME
1408 @item GET_MODE_NAME (@var{m})
1409 Returns the name of mode @var{m} as a string.
1410
1411 @findex GET_MODE_CLASS
1412 @item GET_MODE_CLASS (@var{m})
1413 Returns the mode class of mode @var{m}.
1414
1415 @findex GET_MODE_WIDER_MODE
1416 @item GET_MODE_WIDER_MODE (@var{m})
1417 Returns the next wider natural mode.  For example, the expression
1418 @code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}.
1419
1420 @findex GET_MODE_SIZE
1421 @item GET_MODE_SIZE (@var{m})
1422 Returns the size in bytes of a datum of mode @var{m}.
1423
1424 @findex GET_MODE_BITSIZE
1425 @item GET_MODE_BITSIZE (@var{m})
1426 Returns the size in bits of a datum of mode @var{m}.
1427
1428 @findex GET_MODE_IBIT
1429 @item GET_MODE_IBIT (@var{m})
1430 Returns the number of integral bits of a datum of fixed-point mode @var{m}.
1431
1432 @findex GET_MODE_FBIT
1433 @item GET_MODE_FBIT (@var{m})
1434 Returns the number of fractional bits of a datum of fixed-point mode @var{m}.
1435
1436 @findex GET_MODE_MASK
1437 @item GET_MODE_MASK (@var{m})
1438 Returns a bitmask containing 1 for all bits in a word that fit within
1439 mode @var{m}.  This macro can only be used for modes whose bitsize is
1440 less than or equal to @code{HOST_BITS_PER_INT}.
1441
1442 @findex GET_MODE_ALIGNMENT
1443 @item GET_MODE_ALIGNMENT (@var{m})
1444 Return the required alignment, in bits, for an object of mode @var{m}.
1445
1446 @findex GET_MODE_UNIT_SIZE
1447 @item GET_MODE_UNIT_SIZE (@var{m})
1448 Returns the size in bytes of the subunits of a datum of mode @var{m}.
1449 This is the same as @code{GET_MODE_SIZE} except in the case of complex
1450 modes.  For them, the unit size is the size of the real or imaginary
1451 part.
1452
1453 @findex GET_MODE_NUNITS
1454 @item GET_MODE_NUNITS (@var{m})
1455 Returns the number of units contained in a mode, i.e.,
1456 @code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}.
1457
1458 @findex GET_CLASS_NARROWEST_MODE
1459 @item GET_CLASS_NARROWEST_MODE (@var{c})
1460 Returns the narrowest mode in mode class @var{c}.
1461 @end table
1462
1463 @findex byte_mode
1464 @findex word_mode
1465 The global variables @code{byte_mode} and @code{word_mode} contain modes
1466 whose classes are @code{MODE_INT} and whose bitsizes are either
1467 @code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively.  On 32-bit
1468 machines, these are @code{QImode} and @code{SImode}, respectively.
1469
1470 @node Constants
1471 @section Constant Expression Types
1472 @cindex RTL constants
1473 @cindex RTL constant expression types
1474
1475 The simplest RTL expressions are those that represent constant values.
1476
1477 @table @code
1478 @findex const_int
1479 @item (const_int @var{i})
1480 This type of expression represents the integer value @var{i}.  @var{i}
1481 is customarily accessed with the macro @code{INTVAL} as in
1482 @code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}.
1483
1484 Constants generated for modes with fewer bits than @code{HOST_WIDE_INT}
1485 must be sign extended to full width (e.g., with @code{gen_int_mode}).
1486
1487 @findex const0_rtx
1488 @findex const1_rtx
1489 @findex const2_rtx
1490 @findex constm1_rtx
1491 There is only one expression object for the integer value zero; it is
1492 the value of the variable @code{const0_rtx}.  Likewise, the only
1493 expression for integer value one is found in @code{const1_rtx}, the only
1494 expression for integer value two is found in @code{const2_rtx}, and the
1495 only expression for integer value negative one is found in
1496 @code{constm1_rtx}.  Any attempt to create an expression of code
1497 @code{const_int} and value zero, one, two or negative one will return
1498 @code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or
1499 @code{constm1_rtx} as appropriate.
1500
1501 @findex const_true_rtx
1502 Similarly, there is only one object for the integer whose value is
1503 @code{STORE_FLAG_VALUE}.  It is found in @code{const_true_rtx}.  If
1504 @code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and
1505 @code{const1_rtx} will point to the same object.  If
1506 @code{STORE_FLAG_VALUE} is @minus{}1, @code{const_true_rtx} and
1507 @code{constm1_rtx} will point to the same object.
1508
1509 @findex const_double
1510 @item (const_double:@var{m} @var{addr} @var{i0} @var{i1} @dots{})
1511 Represents either a floating-point constant of mode @var{m} or an
1512 integer constant too large to fit into @code{HOST_BITS_PER_WIDE_INT}
1513 bits but small enough to fit within twice that number of bits (GCC
1514 does not provide a mechanism to represent even larger constants).  In
1515 the latter case, @var{m} will be @code{VOIDmode}.
1516
1517 @findex const_fixed
1518 @item (const_fixed:@var{m} @var{addr})
1519 Represents a fixed-point constant of mode @var{m}.
1520 The data structure, which contains data with the size of two
1521 @code{HOST_BITS_PER_WIDE_INT} and the associated fixed-point mode,
1522 is access with the macro @code{CONST_FIXED_VALUE}.  The high part of data
1523 is accessed with @code{CONST_FIXED_VALUE_HIGH}; the low part is accessed
1524 with @code{CONST_FIXED_VALUE_LOW}.
1525
1526 @findex const_vector
1527 @item (const_vector:@var{m} [@var{x0} @var{x1} @dots{}])
1528 Represents a vector constant.  The square brackets stand for the vector
1529 containing the constant elements.  @var{x0}, @var{x1} and so on are
1530 the @code{const_int} or @code{const_double} elements.
1531
1532 The number of units in a @code{const_vector} is obtained with the macro
1533 @code{CONST_VECTOR_NUNITS} as in @code{CONST_VECTOR_NUNITS (@var{v})}.
1534
1535 Individual elements in a vector constant are accessed with the macro
1536 @code{CONST_VECTOR_ELT} as in @code{CONST_VECTOR_ELT (@var{v}, @var{n})}
1537 where @var{v} is the vector constant and @var{n} is the element
1538 desired.
1539
1540 @findex CONST_DOUBLE_MEM
1541 @findex CONST_DOUBLE_CHAIN
1542 @var{addr} is used to contain the @code{mem} expression that corresponds
1543 to the location in memory that at which the constant can be found.  If
1544 it has not been allocated a memory location, but is on the chain of all
1545 @code{const_double} expressions in this compilation (maintained using an
1546 undisplayed field), @var{addr} contains @code{const0_rtx}.  If it is not
1547 on the chain, @var{addr} contains @code{cc0_rtx}.  @var{addr} is
1548 customarily accessed with the macro @code{CONST_DOUBLE_MEM} and the
1549 chain field via @code{CONST_DOUBLE_CHAIN}.
1550
1551 @findex CONST_DOUBLE_LOW
1552 If @var{m} is @code{VOIDmode}, the bits of the value are stored in
1553 @var{i0} and @var{i1}.  @var{i0} is customarily accessed with the macro
1554 @code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}.
1555
1556 If the constant is floating point (regardless of its precision), then
1557 the number of integers used to store the value depends on the size of
1558 @code{REAL_VALUE_TYPE} (@pxref{Floating Point}).  The integers
1559 represent a floating point number, but not precisely in the target
1560 machine's or host machine's floating point format.  To convert them to
1561 the precise bit pattern used by the target machine, use the macro
1562 @code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}).
1563
1564 @findex CONST0_RTX
1565 @findex CONST1_RTX
1566 @findex CONST2_RTX
1567 The macro @code{CONST0_RTX (@var{mode})} refers to an expression with
1568 value 0 in mode @var{mode}.  If mode @var{mode} is of mode class
1569 @code{MODE_INT}, it returns @code{const0_rtx}.  If mode @var{mode} is of
1570 mode class @code{MODE_FLOAT}, it returns a @code{CONST_DOUBLE}
1571 expression in mode @var{mode}.  Otherwise, it returns a
1572 @code{CONST_VECTOR} expression in mode @var{mode}.  Similarly, the macro
1573 @code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in
1574 mode @var{mode} and similarly for @code{CONST2_RTX}.  The
1575 @code{CONST1_RTX} and @code{CONST2_RTX} macros are undefined
1576 for vector modes.
1577
1578 @findex const_string
1579 @item (const_string @var{str})
1580 Represents a constant string with value @var{str}.  Currently this is
1581 used only for insn attributes (@pxref{Insn Attributes}) since constant
1582 strings in C are placed in memory.
1583
1584 @findex symbol_ref
1585 @item (symbol_ref:@var{mode} @var{symbol})
1586 Represents the value of an assembler label for data.  @var{symbol} is
1587 a string that describes the name of the assembler label.  If it starts
1588 with a @samp{*}, the label is the rest of @var{symbol} not including
1589 the @samp{*}.  Otherwise, the label is @var{symbol}, usually prefixed
1590 with @samp{_}.
1591
1592 The @code{symbol_ref} contains a mode, which is usually @code{Pmode}.
1593 Usually that is the only mode for which a symbol is directly valid.
1594
1595 @findex label_ref
1596 @item (label_ref:@var{mode} @var{label})
1597 Represents the value of an assembler label for code.  It contains one
1598 operand, an expression, which must be a @code{code_label} or a @code{note}
1599 of type @code{NOTE_INSN_DELETED_LABEL} that appears in the instruction
1600 sequence to identify the place where the label should go.
1601
1602 The reason for using a distinct expression type for code label
1603 references is so that jump optimization can distinguish them.
1604
1605 The @code{label_ref} contains a mode, which is usually @code{Pmode}.
1606 Usually that is the only mode for which a label is directly valid.
1607
1608 @item (const:@var{m} @var{exp})
1609 Represents a constant that is the result of an assembly-time
1610 arithmetic computation.  The operand, @var{exp}, is an expression that
1611 contains only constants (@code{const_int}, @code{symbol_ref} and
1612 @code{label_ref} expressions) combined with @code{plus} and
1613 @code{minus}.  However, not all combinations are valid, since the
1614 assembler cannot do arbitrary arithmetic on relocatable symbols.
1615
1616 @var{m} should be @code{Pmode}.
1617
1618 @findex high
1619 @item (high:@var{m} @var{exp})
1620 Represents the high-order bits of @var{exp}, usually a
1621 @code{symbol_ref}.  The number of bits is machine-dependent and is
1622 normally the number of bits specified in an instruction that initializes
1623 the high order bits of a register.  It is used with @code{lo_sum} to
1624 represent the typical two-instruction sequence used in RISC machines to
1625 reference a global memory location.
1626
1627 @var{m} should be @code{Pmode}.
1628 @end table
1629
1630 @node Regs and Memory
1631 @section Registers and Memory
1632 @cindex RTL register expressions
1633 @cindex RTL memory expressions
1634
1635 Here are the RTL expression types for describing access to machine
1636 registers and to main memory.
1637
1638 @table @code
1639 @findex reg
1640 @cindex hard registers
1641 @cindex pseudo registers
1642 @item (reg:@var{m} @var{n})
1643 For small values of the integer @var{n} (those that are less than
1644 @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
1645 register number @var{n}: a @dfn{hard register}.  For larger values of
1646 @var{n}, it stands for a temporary value or @dfn{pseudo register}.
1647 The compiler's strategy is to generate code assuming an unlimited
1648 number of such pseudo registers, and later convert them into hard
1649 registers or into memory references.
1650
1651 @var{m} is the machine mode of the reference.  It is necessary because
1652 machines can generally refer to each register in more than one mode.
1653 For example, a register may contain a full word but there may be
1654 instructions to refer to it as a half word or as a single byte, as
1655 well as instructions to refer to it as a floating point number of
1656 various precisions.
1657
1658 Even for a register that the machine can access in only one mode,
1659 the mode must always be specified.
1660
1661 The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
1662 description, since the number of hard registers on the machine is an
1663 invariant characteristic of the machine.  Note, however, that not
1664 all of the machine registers must be general registers.  All the
1665 machine registers that can be used for storage of data are given
1666 hard register numbers, even those that can be used only in certain
1667 instructions or can hold only certain types of data.
1668
1669 A hard register may be accessed in various modes throughout one
1670 function, but each pseudo register is given a natural mode
1671 and is accessed only in that mode.  When it is necessary to describe
1672 an access to a pseudo register using a nonnatural mode, a @code{subreg}
1673 expression is used.
1674
1675 A @code{reg} expression with a machine mode that specifies more than
1676 one word of data may actually stand for several consecutive registers.
1677 If in addition the register number specifies a hardware register, then
1678 it actually represents several consecutive hardware registers starting
1679 with the specified one.
1680
1681 Each pseudo register number used in a function's RTL code is
1682 represented by a unique @code{reg} expression.
1683
1684 @findex FIRST_VIRTUAL_REGISTER
1685 @findex LAST_VIRTUAL_REGISTER
1686 Some pseudo register numbers, those within the range of
1687 @code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only
1688 appear during the RTL generation phase and are eliminated before the
1689 optimization phases.  These represent locations in the stack frame that
1690 cannot be determined until RTL generation for the function has been
1691 completed.  The following virtual register numbers are defined:
1692
1693 @table @code
1694 @findex VIRTUAL_INCOMING_ARGS_REGNUM
1695 @item VIRTUAL_INCOMING_ARGS_REGNUM
1696 This points to the first word of the incoming arguments passed on the
1697 stack.  Normally these arguments are placed there by the caller, but the
1698 callee may have pushed some arguments that were previously passed in
1699 registers.
1700
1701 @cindex @code{FIRST_PARM_OFFSET} and virtual registers
1702 @cindex @code{ARG_POINTER_REGNUM} and virtual registers
1703 When RTL generation is complete, this virtual register is replaced
1704 by the sum of the register given by @code{ARG_POINTER_REGNUM} and the
1705 value of @code{FIRST_PARM_OFFSET}.
1706
1707 @findex VIRTUAL_STACK_VARS_REGNUM
1708 @cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers
1709 @item VIRTUAL_STACK_VARS_REGNUM
1710 If @code{FRAME_GROWS_DOWNWARD} is defined to a nonzero value, this points
1711 to immediately above the first variable on the stack.  Otherwise, it points
1712 to the first variable on the stack.
1713
1714 @cindex @code{STARTING_FRAME_OFFSET} and virtual registers
1715 @cindex @code{FRAME_POINTER_REGNUM} and virtual registers
1716 @code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the
1717 register given by @code{FRAME_POINTER_REGNUM} and the value
1718 @code{STARTING_FRAME_OFFSET}.
1719
1720 @findex VIRTUAL_STACK_DYNAMIC_REGNUM
1721 @item VIRTUAL_STACK_DYNAMIC_REGNUM
1722 This points to the location of dynamically allocated memory on the stack
1723 immediately after the stack pointer has been adjusted by the amount of
1724 memory desired.
1725
1726 @cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers
1727 @cindex @code{STACK_POINTER_REGNUM} and virtual registers
1728 This virtual register is replaced by the sum of the register given by
1729 @code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}.
1730
1731 @findex VIRTUAL_OUTGOING_ARGS_REGNUM
1732 @item VIRTUAL_OUTGOING_ARGS_REGNUM
1733 This points to the location in the stack at which outgoing arguments
1734 should be written when the stack is pre-pushed (arguments pushed using
1735 push insns should always use @code{STACK_POINTER_REGNUM}).
1736
1737 @cindex @code{STACK_POINTER_OFFSET} and virtual registers
1738 This virtual register is replaced by the sum of the register given by
1739 @code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}.
1740 @end table
1741
1742 @findex subreg
1743 @item (subreg:@var{m1} @var{reg:m2} @var{bytenum})
1744
1745 @code{subreg} expressions are used to refer to a register in a machine
1746 mode other than its natural one, or to refer to one register of
1747 a multi-part @code{reg} that actually refers to several registers.
1748
1749 Each pseudo register has a natural mode.  If it is necessary to
1750 operate on it in a different mode, the pseudo register must be
1751 enclosed in a @code{subreg}.  
1752
1753 It is seldom necessary to wrap hard registers in @code{subreg}s; such
1754 registers would normally reduce to a single @code{reg} rtx.  This use of
1755 @code{subregs} is discouraged and may not be supported in the future.
1756
1757 @code{subreg}s come in two distinct flavors, each having its own
1758 usage and rules:
1759
1760 @table @asis
1761 @item Paradoxical subregs
1762 When @var{m1} is strictly wider than @var{m2}, the @code{subreg}
1763 expression is called @dfn{paradoxical}.  The canonical test for this
1764 class of @code{subreg} is:
1765
1766 @smallexample
1767 GET_MODE_SIZE (@var{m1}) > GET_MODE_SIZE (@var{m2})
1768 @end smallexample
1769
1770 Paradoxical @code{subreg}s can be used as both lvalues and rvalues.
1771 When used as an rvalue, the low-order bits of the @code{subreg} are
1772 taken from @var{reg} while the high-order bits are left undefined.
1773 When used as an lvalue, the low-order bits of the source value are
1774 stored in @var{reg} and the high-order bits are discarded.
1775
1776 @var{bytenum} is always zero for a paradoxical @code{subreg}, even on
1777 big-endian targets.
1778
1779 For example, the paradoxical @code{subreg}:
1780
1781 @smallexample
1782 (set (subreg:SI (reg:HI @var{x}) 0) @var{y})
1783 @end smallexample
1784
1785 stores the lower 2 bytes of @var{y} in @var{x} and discards the upper
1786 2 bytes.  A subsequent:
1787
1788 @smallexample
1789 (set @var{z} (subreg:SI (reg:HI @var{x}) 0))
1790 @end smallexample
1791
1792 would set the lower two bytes of @var{z} to @var{y} and set the upper two
1793 bytes to an unknown value.
1794
1795 @item Normal subregs 
1796 When @var{m1} is at least as narrow as @var{m2} the @code{subreg}
1797 expression is called @dfn{normal}.
1798
1799 Normal @code{subreg}s restrict consideration to certain bits of @var{reg}.
1800 There are two cases.  If @var{m1} is smaller than a word, the
1801 @code{subreg} refers to the least-significant part (or @dfn{lowpart})
1802 of one word of @var{reg}.  If @var{m1} is word-sized or greater, the
1803 @code{subreg} refers to one or more complete words.
1804
1805 When used as an lvalue, @code{subreg} is a word-based accessor.
1806 Storing to a @code{subreg} modifies all the words of @var{reg} that
1807 overlap the @code{subreg}, but it leaves the other words of @var{reg}
1808 alone.
1809
1810 When storing to a normal @code{subreg} that is smaller than a word,
1811 the other bits of the referenced word are usually left in an undefined
1812 state.  This laxity makes it easier to generate efficient code for
1813 such instructions.  To represent an instruction that preserves all the
1814 bits outside of those in the @code{subreg}, use @code{strict_low_part}
1815 or @code{zero_extract} around the @code{subreg}.
1816
1817 @var{bytenum} must identify the offset of the first byte of the
1818 @code{subreg} from the start of @var{reg}, assuming that @var{reg} is
1819 laid out in memory order.  The memory order of bytes is defined by
1820 two target macros, @code{WORDS_BIG_ENDIAN} and @code{BYTES_BIG_ENDIAN}:
1821
1822 @itemize
1823 @item
1824 @cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
1825 @code{WORDS_BIG_ENDIAN}, if set to 1, says that byte number zero is
1826 part of the most significant word; otherwise, it is part of the least
1827 significant word.
1828
1829 @item
1830 @cindex @code{BYTES_BIG_ENDIAN}, effect on @code{subreg}
1831 @code{BYTES_BIG_ENDIAN}, if set to 1, says that byte number zero is
1832 the most significant byte within a word; otherwise, it is the least
1833 significant byte within a word.
1834 @end itemize
1835
1836 @cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg}
1837 On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with
1838 @code{WORDS_BIG_ENDIAN}.  However, most parts of the compiler treat
1839 floating point values as if they had the same endianness as integer
1840 values.  This works because they handle them solely as a collection of
1841 integer values, with no particular numerical value.  Only real.c and
1842 the runtime libraries care about @code{FLOAT_WORDS_BIG_ENDIAN}.
1843
1844 Thus, 
1845
1846 @smallexample
1847 (subreg:HI (reg:SI @var{x}) 2)
1848 @end smallexample
1849
1850 on a @code{BYTES_BIG_ENDIAN}, @samp{UNITS_PER_WORD == 4} target is the same as
1851
1852 @smallexample
1853 (subreg:HI (reg:SI @var{x}) 0)
1854 @end smallexample
1855
1856 on a little-endian, @samp{UNITS_PER_WORD == 4} target.  Both
1857 @code{subreg}s access the lower two bytes of register @var{x}.
1858
1859 @end table
1860
1861 A @code{MODE_PARTIAL_INT} mode behaves as if it were as wide as the
1862 corresponding @code{MODE_INT} mode, except that it has an unknown
1863 number of undefined bits.  For example:
1864
1865 @smallexample
1866 (subreg:PSI (reg:SI 0) 0)
1867 @end smallexample
1868
1869 accesses the whole of @samp{(reg:SI 0)}, but the exact relationship
1870 between the @code{PSImode} value and the @code{SImode} value is not
1871 defined.  If we assume @samp{UNITS_PER_WORD <= 4}, then the following
1872 two @code{subreg}s:
1873
1874 @smallexample
1875 (subreg:PSI (reg:DI 0) 0)
1876 (subreg:PSI (reg:DI 0) 4)
1877 @end smallexample
1878
1879 represent independent 4-byte accesses to the two halves of
1880 @samp{(reg:DI 0)}.  Both @code{subreg}s have an unknown number
1881 of undefined bits.
1882
1883 If @samp{UNITS_PER_WORD <= 2} then these two @code{subreg}s:
1884
1885 @smallexample
1886 (subreg:HI (reg:PSI 0) 0)
1887 (subreg:HI (reg:PSI 0) 2)
1888 @end smallexample
1889
1890 represent independent 2-byte accesses that together span the whole
1891 of @samp{(reg:PSI 0)}.  Storing to the first @code{subreg} does not
1892 affect the value of the second, and vice versa.  @samp{(reg:PSI 0)}
1893 has an unknown number of undefined bits, so the assignment:
1894
1895 @smallexample
1896 (set (subreg:HI (reg:PSI 0) 0) (reg:HI 4))
1897 @end smallexample
1898
1899 does not guarantee that @samp{(subreg:HI (reg:PSI 0) 0)} has the
1900 value @samp{(reg:HI 4)}.
1901
1902 @cindex @code{CANNOT_CHANGE_MODE_CLASS} and subreg semantics
1903 The rules above apply to both pseudo @var{reg}s and hard @var{reg}s.
1904 If the semantics are not correct for particular combinations of
1905 @var{m1}, @var{m2} and hard @var{reg}, the target-specific code
1906 must ensure that those combinations are never used.  For example:
1907
1908 @smallexample
1909 CANNOT_CHANGE_MODE_CLASS (@var{m2}, @var{m1}, @var{class})
1910 @end smallexample
1911
1912 must be true for every class @var{class} that includes @var{reg}.
1913
1914 @findex SUBREG_REG
1915 @findex SUBREG_BYTE
1916 The first operand of a @code{subreg} expression is customarily accessed
1917 with the @code{SUBREG_REG} macro and the second operand is customarily
1918 accessed with the @code{SUBREG_BYTE} macro.
1919
1920 @code{subreg}s of @code{subreg}s are not supported.  Using
1921 @code{simplify_gen_subreg} is the recommended way to avoid this problem.
1922
1923 It has been several years since a platform in which
1924 @code{BYTES_BIG_ENDIAN} was not equal to @code{WORDS_BIG_ENDIAN} has
1925 been tested.  Anyone wishing to support such a platform in the future
1926 may be confronted with code rot.
1927
1928 @findex scratch
1929 @cindex scratch operands
1930 @item (scratch:@var{m})
1931 This represents a scratch register that will be required for the
1932 execution of a single instruction and not used subsequently.  It is
1933 converted into a @code{reg} by either the local register allocator or
1934 the reload pass.
1935
1936 @code{scratch} is usually present inside a @code{clobber} operation
1937 (@pxref{Side Effects}).
1938
1939 @findex cc0
1940 @cindex condition code register
1941 @item (cc0)
1942 This refers to the machine's condition code register.  It has no
1943 operands and may not have a machine mode.  There are two ways to use it:
1944
1945 @itemize @bullet
1946 @item
1947 To stand for a complete set of condition code flags.  This is best on
1948 most machines, where each comparison sets the entire series of flags.
1949
1950 With this technique, @code{(cc0)} may be validly used in only two
1951 contexts: as the destination of an assignment (in test and compare
1952 instructions) and in comparison operators comparing against zero
1953 (@code{const_int} with value zero; that is to say, @code{const0_rtx}).
1954
1955 @item
1956 To stand for a single flag that is the result of a single condition.
1957 This is useful on machines that have only a single flag bit, and in
1958 which comparison instructions must specify the condition to test.
1959
1960 With this technique, @code{(cc0)} may be validly used in only two
1961 contexts: as the destination of an assignment (in test and compare
1962 instructions) where the source is a comparison operator, and as the
1963 first operand of @code{if_then_else} (in a conditional branch).
1964 @end itemize
1965
1966 @findex cc0_rtx
1967 There is only one expression object of code @code{cc0}; it is the
1968 value of the variable @code{cc0_rtx}.  Any attempt to create an
1969 expression of code @code{cc0} will return @code{cc0_rtx}.
1970
1971 Instructions can set the condition code implicitly.  On many machines,
1972 nearly all instructions set the condition code based on the value that
1973 they compute or store.  It is not necessary to record these actions
1974 explicitly in the RTL because the machine description includes a
1975 prescription for recognizing the instructions that do so (by means of
1976 the macro @code{NOTICE_UPDATE_CC}).  @xref{Condition Code}.  Only
1977 instructions whose sole purpose is to set the condition code, and
1978 instructions that use the condition code, need mention @code{(cc0)}.
1979
1980 On some machines, the condition code register is given a register number
1981 and a @code{reg} is used instead of @code{(cc0)}.  This is usually the
1982 preferable approach if only a small subset of instructions modify the
1983 condition code.  Other machines store condition codes in general
1984 registers; in such cases a pseudo register should be used.
1985
1986 Some machines, such as the SPARC and RS/6000, have two sets of
1987 arithmetic instructions, one that sets and one that does not set the
1988 condition code.  This is best handled by normally generating the
1989 instruction that does not set the condition code, and making a pattern
1990 that both performs the arithmetic and sets the condition code register
1991 (which would not be @code{(cc0)} in this case).  For examples, search
1992 for @samp{addcc} and @samp{andcc} in @file{sparc.md}.
1993
1994 @findex pc
1995 @item (pc)
1996 @cindex program counter
1997 This represents the machine's program counter.  It has no operands and
1998 may not have a machine mode.  @code{(pc)} may be validly used only in
1999 certain specific contexts in jump instructions.
2000
2001 @findex pc_rtx
2002 There is only one expression object of code @code{pc}; it is the value
2003 of the variable @code{pc_rtx}.  Any attempt to create an expression of
2004 code @code{pc} will return @code{pc_rtx}.
2005
2006 All instructions that do not jump alter the program counter implicitly
2007 by incrementing it, but there is no need to mention this in the RTL@.
2008
2009 @findex mem
2010 @item (mem:@var{m} @var{addr} @var{alias})
2011 This RTX represents a reference to main memory at an address
2012 represented by the expression @var{addr}.  @var{m} specifies how large
2013 a unit of memory is accessed.  @var{alias} specifies an alias set for the
2014 reference.  In general two items are in different alias sets if they cannot
2015 reference the same memory address.
2016
2017 The construct @code{(mem:BLK (scratch))} is considered to alias all
2018 other memories.  Thus it may be used as a memory barrier in epilogue
2019 stack deallocation patterns.
2020
2021 @findex concat
2022 @item (concat@var{m} @var{rtx} @var{rtx})
2023 This RTX represents the concatenation of two other RTXs.  This is used
2024 for complex values.  It should only appear in the RTL attached to
2025 declarations and during RTL generation.  It should not appear in the
2026 ordinary insn chain.
2027
2028 @findex concatn
2029 @item (concatn@var{m} [@var{rtx} @dots{}])
2030 This RTX represents the concatenation of all the @var{rtx} to make a
2031 single value.  Like @code{concat}, this should only appear in
2032 declarations, and not in the insn chain.
2033 @end table
2034
2035 @node Arithmetic
2036 @section RTL Expressions for Arithmetic
2037 @cindex arithmetic, in RTL
2038 @cindex math, in RTL
2039 @cindex RTL expressions for arithmetic
2040
2041 Unless otherwise specified, all the operands of arithmetic expressions
2042 must be valid for mode @var{m}.  An operand is valid for mode @var{m}
2043 if it has mode @var{m}, or if it is a @code{const_int} or
2044 @code{const_double} and @var{m} is a mode of class @code{MODE_INT}.
2045
2046 For commutative binary operations, constants should be placed in the
2047 second operand.
2048
2049 @table @code
2050 @findex plus
2051 @findex ss_plus
2052 @findex us_plus
2053 @cindex RTL sum
2054 @cindex RTL addition
2055 @cindex RTL addition with signed saturation
2056 @cindex RTL addition with unsigned saturation
2057 @item (plus:@var{m} @var{x} @var{y})
2058 @itemx (ss_plus:@var{m} @var{x} @var{y})
2059 @itemx (us_plus:@var{m} @var{x} @var{y})
2060
2061 These three expressions all represent the sum of the values
2062 represented by @var{x} and @var{y} carried out in machine mode
2063 @var{m}.  They differ in their behavior on overflow of integer modes.
2064 @code{plus} wraps round modulo the width of @var{m}; @code{ss_plus}
2065 saturates at the maximum signed value representable in @var{m};
2066 @code{us_plus} saturates at the maximum unsigned value.
2067
2068 @c ??? What happens on overflow of floating point modes?
2069
2070 @findex lo_sum
2071 @item (lo_sum:@var{m} @var{x} @var{y})
2072
2073 This expression represents the sum of @var{x} and the low-order bits
2074 of @var{y}.  It is used with @code{high} (@pxref{Constants}) to
2075 represent the typical two-instruction sequence used in RISC machines
2076 to reference a global memory location.
2077
2078 The number of low order bits is machine-dependent but is
2079 normally the number of bits in a @code{Pmode} item minus the number of
2080 bits set by @code{high}.
2081
2082 @var{m} should be @code{Pmode}.
2083
2084 @findex minus
2085 @findex ss_minus
2086 @findex us_minus
2087 @cindex RTL difference
2088 @cindex RTL subtraction
2089 @cindex RTL subtraction with signed saturation
2090 @cindex RTL subtraction with unsigned saturation
2091 @item (minus:@var{m} @var{x} @var{y})
2092 @itemx (ss_minus:@var{m} @var{x} @var{y})
2093 @itemx (us_minus:@var{m} @var{x} @var{y})
2094
2095 These three expressions represent the result of subtracting @var{y}
2096 from @var{x}, carried out in mode @var{M}.  Behavior on overflow is
2097 the same as for the three variants of @code{plus} (see above).
2098
2099 @findex compare
2100 @cindex RTL comparison
2101 @item (compare:@var{m} @var{x} @var{y})
2102 Represents the result of subtracting @var{y} from @var{x} for purposes
2103 of comparison.  The result is computed without overflow, as if with
2104 infinite precision.
2105
2106 Of course, machines can't really subtract with infinite precision.
2107 However, they can pretend to do so when only the sign of the result will
2108 be used, which is the case when the result is stored in the condition
2109 code.  And that is the @emph{only} way this kind of expression may
2110 validly be used: as a value to be stored in the condition codes, either
2111 @code{(cc0)} or a register.  @xref{Comparisons}.
2112
2113 The mode @var{m} is not related to the modes of @var{x} and @var{y}, but
2114 instead is the mode of the condition code value.  If @code{(cc0)} is
2115 used, it is @code{VOIDmode}.  Otherwise it is some mode in class
2116 @code{MODE_CC}, often @code{CCmode}.  @xref{Condition Code}.  If @var{m}
2117 is @code{VOIDmode} or @code{CCmode}, the operation returns sufficient
2118 information (in an unspecified format) so that any comparison operator
2119 can be applied to the result of the @code{COMPARE} operation.  For other
2120 modes in class @code{MODE_CC}, the operation only returns a subset of
2121 this information.
2122
2123 Normally, @var{x} and @var{y} must have the same mode.  Otherwise,
2124 @code{compare} is valid only if the mode of @var{x} is in class
2125 @code{MODE_INT} and @var{y} is a @code{const_int} or
2126 @code{const_double} with mode @code{VOIDmode}.  The mode of @var{x}
2127 determines what mode the comparison is to be done in; thus it must not
2128 be @code{VOIDmode}.
2129
2130 If one of the operands is a constant, it should be placed in the
2131 second operand and the comparison code adjusted as appropriate.
2132
2133 A @code{compare} specifying two @code{VOIDmode} constants is not valid
2134 since there is no way to know in what mode the comparison is to be
2135 performed; the comparison must either be folded during the compilation
2136 or the first operand must be loaded into a register while its mode is
2137 still known.
2138
2139 @findex neg
2140 @findex ss_neg
2141 @findex us_neg
2142 @cindex negation
2143 @cindex negation with signed saturation
2144 @cindex negation with unsigned saturation
2145 @item (neg:@var{m} @var{x})
2146 @itemx (ss_neg:@var{m} @var{x})
2147 @itemx (us_neg:@var{m} @var{x})
2148 These two expressions represent the negation (subtraction from zero) of
2149 the value represented by @var{x}, carried out in mode @var{m}.  They
2150 differ in the behavior on overflow of integer modes.  In the case of
2151 @code{neg}, the negation of the operand may be a number not representable
2152 in mode @var{m}, in which case it is truncated to @var{m}.  @code{ss_neg}
2153 and @code{us_neg} ensure that an out-of-bounds result saturates to the
2154 maximum or minimum signed or unsigned value.
2155
2156 @findex mult
2157 @findex ss_mult
2158 @findex us_mult
2159 @cindex multiplication
2160 @cindex product
2161 @cindex multiplication with signed saturation
2162 @cindex multiplication with unsigned saturation
2163 @item (mult:@var{m} @var{x} @var{y})
2164 @itemx (ss_mult:@var{m} @var{x} @var{y})
2165 @itemx (us_mult:@var{m} @var{x} @var{y})
2166 Represents the signed product of the values represented by @var{x} and
2167 @var{y} carried out in machine mode @var{m}.
2168 @code{ss_mult} and @code{us_mult} ensure that an out-of-bounds result
2169 saturates to the maximum or minimum signed or unsigned value.
2170
2171 Some machines support a multiplication that generates a product wider
2172 than the operands.  Write the pattern for this as
2173
2174 @smallexample
2175 (mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
2176 @end smallexample
2177
2178 where @var{m} is wider than the modes of @var{x} and @var{y}, which need
2179 not be the same.
2180
2181 For unsigned widening multiplication, use the same idiom, but with
2182 @code{zero_extend} instead of @code{sign_extend}.
2183
2184 @findex div
2185 @findex ss_div
2186 @cindex division
2187 @cindex signed division
2188 @cindex signed division with signed saturation
2189 @cindex quotient
2190 @item (div:@var{m} @var{x} @var{y})
2191 @itemx (ss_div:@var{m} @var{x} @var{y})
2192 Represents the quotient in signed division of @var{x} by @var{y},
2193 carried out in machine mode @var{m}.  If @var{m} is a floating point
2194 mode, it represents the exact quotient; otherwise, the integerized
2195 quotient.
2196 @code{ss_div} ensures that an out-of-bounds result saturates to the maximum
2197 or minimum signed value.
2198
2199 Some machines have division instructions in which the operands and
2200 quotient widths are not all the same; you should represent
2201 such instructions using @code{truncate} and @code{sign_extend} as in,
2202
2203 @smallexample
2204 (truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
2205 @end smallexample
2206
2207 @findex udiv
2208 @cindex unsigned division
2209 @cindex unsigned division with unsigned saturation
2210 @cindex division
2211 @item (udiv:@var{m} @var{x} @var{y})
2212 @itemx (us_div:@var{m} @var{x} @var{y})
2213 Like @code{div} but represents unsigned division.
2214 @code{us_div} ensures that an out-of-bounds result saturates to the maximum
2215 or minimum unsigned value.
2216
2217 @findex mod
2218 @findex umod
2219 @cindex remainder
2220 @cindex division
2221 @item (mod:@var{m} @var{x} @var{y})
2222 @itemx (umod:@var{m} @var{x} @var{y})
2223 Like @code{div} and @code{udiv} but represent the remainder instead of
2224 the quotient.
2225
2226 @findex smin
2227 @findex smax
2228 @cindex signed minimum
2229 @cindex signed maximum
2230 @item (smin:@var{m} @var{x} @var{y})
2231 @itemx (smax:@var{m} @var{x} @var{y})
2232 Represents the smaller (for @code{smin}) or larger (for @code{smax}) of
2233 @var{x} and @var{y}, interpreted as signed values in mode @var{m}.
2234 When used with floating point, if both operands are zeros, or if either
2235 operand is @code{NaN}, then it is unspecified which of the two operands
2236 is returned as the result.
2237
2238 @findex umin
2239 @findex umax
2240 @cindex unsigned minimum and maximum
2241 @item (umin:@var{m} @var{x} @var{y})
2242 @itemx (umax:@var{m} @var{x} @var{y})
2243 Like @code{smin} and @code{smax}, but the values are interpreted as unsigned
2244 integers.
2245
2246 @findex not
2247 @cindex complement, bitwise
2248 @cindex bitwise complement
2249 @item (not:@var{m} @var{x})
2250 Represents the bitwise complement of the value represented by @var{x},
2251 carried out in mode @var{m}, which must be a fixed-point machine mode.
2252
2253 @findex and
2254 @cindex logical-and, bitwise
2255 @cindex bitwise logical-and
2256 @item (and:@var{m} @var{x} @var{y})
2257 Represents the bitwise logical-and of the values represented by
2258 @var{x} and @var{y}, carried out in machine mode @var{m}, which must be
2259 a fixed-point machine mode.
2260
2261 @findex ior
2262 @cindex inclusive-or, bitwise
2263 @cindex bitwise inclusive-or
2264 @item (ior:@var{m} @var{x} @var{y})
2265 Represents the bitwise inclusive-or of the values represented by @var{x}
2266 and @var{y}, carried out in machine mode @var{m}, which must be a
2267 fixed-point mode.
2268
2269 @findex xor
2270 @cindex exclusive-or, bitwise
2271 @cindex bitwise exclusive-or
2272 @item (xor:@var{m} @var{x} @var{y})
2273 Represents the bitwise exclusive-or of the values represented by @var{x}
2274 and @var{y}, carried out in machine mode @var{m}, which must be a
2275 fixed-point mode.
2276
2277 @findex ashift
2278 @findex ss_ashift
2279 @findex us_ashift
2280 @cindex left shift
2281 @cindex shift
2282 @cindex arithmetic shift
2283 @cindex arithmetic shift with signed saturation
2284 @cindex arithmetic shift with unsigned saturation
2285 @item (ashift:@var{m} @var{x} @var{c})
2286 @itemx (ss_ashift:@var{m} @var{x} @var{c})
2287 @itemx (us_ashift:@var{m} @var{x} @var{c})
2288 These three expressions represent the result of arithmetically shifting @var{x}
2289 left by @var{c} places.  They differ in their behavior on overflow of integer
2290 modes.  An @code{ashift} operation is a plain shift with no special behavior
2291 in case of a change in the sign bit; @code{ss_ashift} and @code{us_ashift}
2292 saturates to the minimum or maximum representable value if any of the bits
2293 shifted out differs from the final sign bit.
2294
2295 @var{x} have mode @var{m}, a fixed-point machine mode.  @var{c}
2296 be a fixed-point mode or be a constant with mode @code{VOIDmode}; which
2297 mode is determined by the mode called for in the machine description
2298 entry for the left-shift instruction.  For example, on the VAX, the mode
2299 of @var{c} is @code{QImode} regardless of @var{m}.
2300
2301 @findex lshiftrt
2302 @cindex right shift
2303 @findex ashiftrt
2304 @item (lshiftrt:@var{m} @var{x} @var{c})
2305 @itemx (ashiftrt:@var{m} @var{x} @var{c})
2306 Like @code{ashift} but for right shift.  Unlike the case for left shift,
2307 these two operations are distinct.
2308
2309 @findex rotate
2310 @cindex rotate
2311 @cindex left rotate
2312 @findex rotatert
2313 @cindex right rotate
2314 @item (rotate:@var{m} @var{x} @var{c})
2315 @itemx (rotatert:@var{m} @var{x} @var{c})
2316 Similar but represent left and right rotate.  If @var{c} is a constant,
2317 use @code{rotate}.
2318
2319 @findex abs
2320 @cindex absolute value
2321 @item (abs:@var{m} @var{x})
2322 Represents the absolute value of @var{x}, computed in mode @var{m}.
2323
2324 @findex sqrt
2325 @cindex square root
2326 @item (sqrt:@var{m} @var{x})
2327 Represents the square root of @var{x}, computed in mode @var{m}.
2328 Most often @var{m} will be a floating point mode.
2329
2330 @findex ffs
2331 @item (ffs:@var{m} @var{x})
2332 Represents one plus the index of the least significant 1-bit in
2333 @var{x}, represented as an integer of mode @var{m}.  (The value is
2334 zero if @var{x} is zero.)  The mode of @var{x} need not be @var{m};
2335 depending on the target machine, various mode combinations may be
2336 valid.
2337
2338 @findex clz
2339 @item (clz:@var{m} @var{x})
2340 Represents the number of leading 0-bits in @var{x}, represented as an
2341 integer of mode @var{m}, starting at the most significant bit position.
2342 If @var{x} is zero, the value is determined by
2343 @code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}).  Note that this is one of
2344 the few expressions that is not invariant under widening.  The mode of
2345 @var{x} will usually be an integer mode.
2346
2347 @findex ctz
2348 @item (ctz:@var{m} @var{x})
2349 Represents the number of trailing 0-bits in @var{x}, represented as an
2350 integer of mode @var{m}, starting at the least significant bit position.
2351 If @var{x} is zero, the value is determined by
2352 @code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}).  Except for this case,
2353 @code{ctz(x)} is equivalent to @code{ffs(@var{x}) - 1}.  The mode of
2354 @var{x} will usually be an integer mode.
2355
2356 @findex popcount
2357 @item (popcount:@var{m} @var{x})
2358 Represents the number of 1-bits in @var{x}, represented as an integer of
2359 mode @var{m}.  The mode of @var{x} will usually be an integer mode.
2360
2361 @findex parity
2362 @item (parity:@var{m} @var{x})
2363 Represents the number of 1-bits modulo 2 in @var{x}, represented as an
2364 integer of mode @var{m}.  The mode of @var{x} will usually be an integer
2365 mode.
2366
2367 @findex bswap
2368 @item (bswap:@var{m} @var{x})
2369 Represents the value @var{x} with the order of bytes reversed, carried out
2370 in mode @var{m}, which must be a fixed-point machine mode.
2371 @end table
2372
2373 @node Comparisons
2374 @section Comparison Operations
2375 @cindex RTL comparison operations
2376
2377 Comparison operators test a relation on two operands and are considered
2378 to represent a machine-dependent nonzero value described by, but not
2379 necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
2380 if the relation holds, or zero if it does not, for comparison operators
2381 whose results have a `MODE_INT' mode,
2382 @code{FLOAT_STORE_FLAG_VALUE} (@pxref{Misc}) if the relation holds, or
2383 zero if it does not, for comparison operators that return floating-point
2384 values, and a vector of either @code{VECTOR_STORE_FLAG_VALUE} (@pxref{Misc})
2385 if the relation holds, or of zeros if it does not, for comparison operators
2386 that return vector results.
2387 The mode of the comparison operation is independent of the mode
2388 of the data being compared.  If the comparison operation is being tested
2389 (e.g., the first operand of an @code{if_then_else}), the mode must be
2390 @code{VOIDmode}.
2391
2392 @cindex condition codes
2393 There are two ways that comparison operations may be used.  The
2394 comparison operators may be used to compare the condition codes
2395 @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}.  Such
2396 a construct actually refers to the result of the preceding instruction
2397 in which the condition codes were set.  The instruction setting the
2398 condition code must be adjacent to the instruction using the condition
2399 code; only @code{note} insns may separate them.
2400
2401 Alternatively, a comparison operation may directly compare two data
2402 objects.  The mode of the comparison is determined by the operands; they
2403 must both be valid for a common machine mode.  A comparison with both
2404 operands constant would be invalid as the machine mode could not be
2405 deduced from it, but such a comparison should never exist in RTL due to
2406 constant folding.
2407
2408 In the example above, if @code{(cc0)} were last set to
2409 @code{(compare @var{x} @var{y})}, the comparison operation is
2410 identical to @code{(eq @var{x} @var{y})}.  Usually only one style
2411 of comparisons is supported on a particular machine, but the combine
2412 pass will try to merge the operations to produce the @code{eq} shown
2413 in case it exists in the context of the particular insn involved.
2414
2415 Inequality comparisons come in two flavors, signed and unsigned.  Thus,
2416 there are distinct expression codes @code{gt} and @code{gtu} for signed and
2417 unsigned greater-than.  These can produce different results for the same
2418 pair of integer values: for example, 1 is signed greater-than @minus{}1 but not
2419 unsigned greater-than, because @minus{}1 when regarded as unsigned is actually
2420 @code{0xffffffff} which is greater than 1.
2421
2422 The signed comparisons are also used for floating point values.  Floating
2423 point comparisons are distinguished by the machine modes of the operands.
2424
2425 @table @code
2426 @findex eq
2427 @cindex equal
2428 @item (eq:@var{m} @var{x} @var{y})
2429 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2430 are equal, otherwise 0.
2431
2432 @findex ne
2433 @cindex not equal
2434 @item (ne:@var{m} @var{x} @var{y})
2435 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2436 are not equal, otherwise 0.
2437
2438 @findex gt
2439 @cindex greater than
2440 @item (gt:@var{m} @var{x} @var{y})
2441 @code{STORE_FLAG_VALUE} if the @var{x} is greater than @var{y}.  If they
2442 are fixed-point, the comparison is done in a signed sense.
2443
2444 @findex gtu
2445 @cindex greater than
2446 @cindex unsigned greater than
2447 @item (gtu:@var{m} @var{x} @var{y})
2448 Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
2449
2450 @findex lt
2451 @cindex less than
2452 @findex ltu
2453 @cindex unsigned less than
2454 @item (lt:@var{m} @var{x} @var{y})
2455 @itemx (ltu:@var{m} @var{x} @var{y})
2456 Like @code{gt} and @code{gtu} but test for ``less than''.
2457
2458 @findex ge
2459 @cindex greater than
2460 @findex geu
2461 @cindex unsigned greater than
2462 @item (ge:@var{m} @var{x} @var{y})
2463 @itemx (geu:@var{m} @var{x} @var{y})
2464 Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
2465
2466 @findex le
2467 @cindex less than or equal
2468 @findex leu
2469 @cindex unsigned less than
2470 @item (le:@var{m} @var{x} @var{y})
2471 @itemx (leu:@var{m} @var{x} @var{y})
2472 Like @code{gt} and @code{gtu} but test for ``less than or equal''.
2473
2474 @findex if_then_else
2475 @item (if_then_else @var{cond} @var{then} @var{else})
2476 This is not a comparison operation but is listed here because it is
2477 always used in conjunction with a comparison operation.  To be
2478 precise, @var{cond} is a comparison expression.  This expression
2479 represents a choice, according to @var{cond}, between the value
2480 represented by @var{then} and the one represented by @var{else}.
2481
2482 On most machines, @code{if_then_else} expressions are valid only
2483 to express conditional jumps.
2484
2485 @findex cond
2486 @item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
2487 Similar to @code{if_then_else}, but more general.  Each of @var{test1},
2488 @var{test2}, @dots{} is performed in turn.  The result of this expression is
2489 the @var{value} corresponding to the first nonzero test, or @var{default} if
2490 none of the tests are nonzero expressions.
2491
2492 This is currently not valid for instruction patterns and is supported only
2493 for insn attributes.  @xref{Insn Attributes}.
2494 @end table
2495
2496 @node Bit-Fields
2497 @section Bit-Fields
2498 @cindex bit-fields
2499
2500 Special expression codes exist to represent bit-field instructions.
2501
2502 @table @code
2503 @findex sign_extract
2504 @cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
2505 @item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
2506 This represents a reference to a sign-extended bit-field contained or
2507 starting in @var{loc} (a memory or register reference).  The bit-field
2508 is @var{size} bits wide and starts at bit @var{pos}.  The compilation
2509 option @code{BITS_BIG_ENDIAN} says which end of the memory unit
2510 @var{pos} counts from.
2511
2512 If @var{loc} is in memory, its mode must be a single-byte integer mode.
2513 If @var{loc} is in a register, the mode to use is specified by the
2514 operand of the @code{insv} or @code{extv} pattern
2515 (@pxref{Standard Names}) and is usually a full-word integer mode,
2516 which is the default if none is specified.
2517
2518 The mode of @var{pos} is machine-specific and is also specified
2519 in the @code{insv} or @code{extv} pattern.
2520
2521 The mode @var{m} is the same as the mode that would be used for
2522 @var{loc} if it were a register.
2523
2524 A @code{sign_extract} can not appear as an lvalue, or part thereof,
2525 in RTL.
2526
2527 @findex zero_extract
2528 @item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
2529 Like @code{sign_extract} but refers to an unsigned or zero-extended
2530 bit-field.  The same sequence of bits are extracted, but they
2531 are filled to an entire word with zeros instead of by sign-extension.
2532
2533 Unlike @code{sign_extract}, this type of expressions can be lvalues
2534 in RTL; they may appear on the left side of an assignment, indicating
2535 insertion of a value into the specified bit-field.
2536 @end table
2537
2538 @node Vector Operations
2539 @section Vector Operations
2540 @cindex vector operations
2541
2542 All normal RTL expressions can be used with vector modes; they are
2543 interpreted as operating on each part of the vector independently.
2544 Additionally, there are a few new expressions to describe specific vector
2545 operations.
2546
2547 @table @code
2548 @findex vec_merge
2549 @item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items})
2550 This describes a merge operation between two vectors.  The result is a vector
2551 of mode @var{m}; its elements are selected from either @var{vec1} or
2552 @var{vec2}.  Which elements are selected is described by @var{items}, which
2553 is a bit mask represented by a @code{const_int}; a zero bit indicates the
2554 corresponding element in the result vector is taken from @var{vec2} while
2555 a set bit indicates it is taken from @var{vec1}.
2556
2557 @findex vec_select
2558 @item (vec_select:@var{m} @var{vec1} @var{selection})
2559 This describes an operation that selects parts of a vector.  @var{vec1} is
2560 the source vector, @var{selection} is a @code{parallel} that contains a
2561 @code{const_int} for each of the subparts of the result vector, giving the
2562 number of the source subpart that should be stored into it.
2563
2564 @findex vec_concat
2565 @item (vec_concat:@var{m} @var{vec1} @var{vec2})
2566 Describes a vector concat operation.  The result is a concatenation of the
2567 vectors @var{vec1} and @var{vec2}; its length is the sum of the lengths of
2568 the two inputs.
2569
2570 @findex vec_duplicate
2571 @item (vec_duplicate:@var{m} @var{vec})
2572 This operation converts a small vector into a larger one by duplicating the
2573 input values.  The output vector mode must have the same submodes as the
2574 input vector mode, and the number of output parts must be an integer multiple
2575 of the number of input parts.
2576
2577 @end table
2578
2579 @node Conversions
2580 @section Conversions
2581 @cindex conversions
2582 @cindex machine mode conversions
2583
2584 All conversions between machine modes must be represented by
2585 explicit conversion operations.  For example, an expression
2586 which is the sum of a byte and a full word cannot be written as
2587 @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
2588 operation requires two operands of the same machine mode.
2589 Therefore, the byte-sized operand is enclosed in a conversion
2590 operation, as in
2591
2592 @smallexample
2593 (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
2594 @end smallexample
2595
2596 The conversion operation is not a mere placeholder, because there
2597 may be more than one way of converting from a given starting mode
2598 to the desired final mode.  The conversion operation code says how
2599 to do it.
2600
2601 For all conversion operations, @var{x} must not be @code{VOIDmode}
2602 because the mode in which to do the conversion would not be known.
2603 The conversion must either be done at compile-time or @var{x}
2604 must be placed into a register.
2605
2606 @table @code
2607 @findex sign_extend
2608 @item (sign_extend:@var{m} @var{x})
2609 Represents the result of sign-extending the value @var{x}
2610 to machine mode @var{m}.  @var{m} must be a fixed-point mode
2611 and @var{x} a fixed-point value of a mode narrower than @var{m}.
2612
2613 @findex zero_extend
2614 @item (zero_extend:@var{m} @var{x})
2615 Represents the result of zero-extending the value @var{x}
2616 to machine mode @var{m}.  @var{m} must be a fixed-point mode
2617 and @var{x} a fixed-point value of a mode narrower than @var{m}.
2618
2619 @findex float_extend
2620 @item (float_extend:@var{m} @var{x})
2621 Represents the result of extending the value @var{x}
2622 to machine mode @var{m}.  @var{m} must be a floating point mode
2623 and @var{x} a floating point value of a mode narrower than @var{m}.
2624
2625 @findex truncate
2626 @item (truncate:@var{m} @var{x})
2627 Represents the result of truncating the value @var{x}
2628 to machine mode @var{m}.  @var{m} must be a fixed-point mode
2629 and @var{x} a fixed-point value of a mode wider than @var{m}.
2630
2631 @findex ss_truncate
2632 @item (ss_truncate:@var{m} @var{x})
2633 Represents the result of truncating the value @var{x}
2634 to machine mode @var{m}, using signed saturation in the case of
2635 overflow.  Both @var{m} and the mode of @var{x} must be fixed-point
2636 modes.
2637
2638 @findex us_truncate
2639 @item (us_truncate:@var{m} @var{x})
2640 Represents the result of truncating the value @var{x}
2641 to machine mode @var{m}, using unsigned saturation in the case of
2642 overflow.  Both @var{m} and the mode of @var{x} must be fixed-point
2643 modes.
2644
2645 @findex float_truncate
2646 @item (float_truncate:@var{m} @var{x})
2647 Represents the result of truncating the value @var{x}
2648 to machine mode @var{m}.  @var{m} must be a floating point mode
2649 and @var{x} a floating point value of a mode wider than @var{m}.
2650
2651 @findex float
2652 @item (float:@var{m} @var{x})
2653 Represents the result of converting fixed point value @var{x},
2654 regarded as signed, to floating point mode @var{m}.
2655
2656 @findex unsigned_float
2657 @item (unsigned_float:@var{m} @var{x})
2658 Represents the result of converting fixed point value @var{x},
2659 regarded as unsigned, to floating point mode @var{m}.
2660
2661 @findex fix
2662 @item (fix:@var{m} @var{x})
2663 When @var{m} is a fixed point mode, represents the result of
2664 converting floating point value @var{x} to mode @var{m}, regarded as
2665 signed.  How rounding is done is not specified, so this operation may
2666 be used validly in compiling C code only for integer-valued operands.
2667
2668 @findex unsigned_fix
2669 @item (unsigned_fix:@var{m} @var{x})
2670 Represents the result of converting floating point value @var{x} to
2671 fixed point mode @var{m}, regarded as unsigned.  How rounding is done
2672 is not specified.
2673
2674 @findex fix
2675 @item (fix:@var{m} @var{x})
2676 When @var{m} is a floating point mode, represents the result of
2677 converting floating point value @var{x} (valid for mode @var{m}) to an
2678 integer, still represented in floating point mode @var{m}, by rounding
2679 towards zero.
2680
2681 @findex fract_convert
2682 @item (fract_convert:@var{m} @var{x})
2683 Represents the result of converting fixed-point value @var{x} to
2684 fixed-point mode @var{m}, signed integer value @var{x} to
2685 fixed-point mode @var{m}, floating-point value @var{x} to
2686 fixed-point mode @var{m}, fixed-point value @var{x} to integer mode @var{m}
2687 regarded as signed, or fixed-point value @var{x} to floating-point mode @var{m}.
2688 When overflows or underflows happen, the results are undefined.
2689
2690 @findex sat_fract
2691 @item (sat_fract:@var{m} @var{x})
2692 Represents the result of converting fixed-point value @var{x} to
2693 fixed-point mode @var{m}, signed integer value @var{x} to
2694 fixed-point mode @var{m}, or floating-point value @var{x} to
2695 fixed-point mode @var{m}.
2696 When overflows or underflows happen, the results are saturated to the
2697 maximum or the minimum.
2698
2699 @findex unsigned_fract_convert
2700 @item (unsigned_fract_convert:@var{m} @var{x})
2701 Represents the result of converting fixed-point value @var{x} to
2702 integer mode @var{m} regarded as unsigned, or unsigned integer value @var{x} to
2703 fixed-point mode @var{m}.
2704 When overflows or underflows happen, the results are undefined.
2705
2706 @findex unsigned_sat_fract
2707 @item (unsigned_sat_fract:@var{m} @var{x})
2708 Represents the result of converting unsigned integer value @var{x} to
2709 fixed-point mode @var{m}.
2710 When overflows or underflows happen, the results are saturated to the
2711 maximum or the minimum.
2712 @end table
2713
2714 @node RTL Declarations
2715 @section Declarations
2716 @cindex RTL declarations
2717 @cindex declarations, RTL
2718
2719 Declaration expression codes do not represent arithmetic operations
2720 but rather state assertions about their operands.
2721
2722 @table @code
2723 @findex strict_low_part
2724 @cindex @code{subreg}, in @code{strict_low_part}
2725 @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
2726 This expression code is used in only one context: as the destination operand of a
2727 @code{set} expression.  In addition, the operand of this expression
2728 must be a non-paradoxical @code{subreg} expression.
2729
2730 The presence of @code{strict_low_part} says that the part of the
2731 register which is meaningful in mode @var{n}, but is not part of
2732 mode @var{m}, is not to be altered.  Normally, an assignment to such
2733 a subreg is allowed to have undefined effects on the rest of the
2734 register when @var{m} is less than a word.
2735 @end table
2736
2737 @node Side Effects
2738 @section Side Effect Expressions
2739 @cindex RTL side effect expressions
2740
2741 The expression codes described so far represent values, not actions.
2742 But machine instructions never produce values; they are meaningful
2743 only for their side effects on the state of the machine.  Special
2744 expression codes are used to represent side effects.
2745
2746 The body of an instruction is always one of these side effect codes;
2747 the codes described above, which represent values, appear only as
2748 the operands of these.
2749
2750 @table @code
2751 @findex set
2752 @item (set @var{lval} @var{x})
2753 Represents the action of storing the value of @var{x} into the place
2754 represented by @var{lval}.  @var{lval} must be an expression
2755 representing a place that can be stored in: @code{reg} (or @code{subreg},
2756 @code{strict_low_part} or @code{zero_extract}), @code{mem}, @code{pc},
2757 @code{parallel}, or @code{cc0}.
2758
2759 If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
2760 machine mode; then @var{x} must be valid for that mode.
2761
2762 If @var{lval} is a @code{reg} whose machine mode is less than the full
2763 width of the register, then it means that the part of the register
2764 specified by the machine mode is given the specified value and the
2765 rest of the register receives an undefined value.  Likewise, if
2766 @var{lval} is a @code{subreg} whose machine mode is narrower than
2767 the mode of the register, the rest of the register can be changed in
2768 an undefined way.
2769
2770 If @var{lval} is a @code{strict_low_part} of a subreg, then the part
2771 of the register specified by the machine mode of the @code{subreg} is
2772 given the value @var{x} and the rest of the register is not changed.
2773
2774 If @var{lval} is a @code{zero_extract}, then the referenced part of
2775 the bit-field (a memory or register reference) specified by the
2776 @code{zero_extract} is given the value @var{x} and the rest of the
2777 bit-field is not changed.  Note that @code{sign_extract} can not
2778 appear in @var{lval}.
2779
2780 If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
2781 be either a @code{compare} expression or a value that may have any mode.
2782 The latter case represents a ``test'' instruction.  The expression
2783 @code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to
2784 @code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}.
2785 Use the former expression to save space during the compilation.
2786
2787 If @var{lval} is a @code{parallel}, it is used to represent the case of
2788 a function returning a structure in multiple registers.  Each element
2789 of the @code{parallel} is an @code{expr_list} whose first operand is a
2790 @code{reg} and whose second operand is a @code{const_int} representing the
2791 offset (in bytes) into the structure at which the data in that register
2792 corresponds.  The first element may be null to indicate that the structure
2793 is also passed partly in memory.
2794
2795 @cindex jump instructions and @code{set}
2796 @cindex @code{if_then_else} usage
2797 If @var{lval} is @code{(pc)}, we have a jump instruction, and the
2798 possibilities for @var{x} are very limited.  It may be a
2799 @code{label_ref} expression (unconditional jump).  It may be an
2800 @code{if_then_else} (conditional jump), in which case either the
2801 second or the third operand must be @code{(pc)} (for the case which
2802 does not jump) and the other of the two must be a @code{label_ref}
2803 (for the case which does jump).  @var{x} may also be a @code{mem} or
2804 @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
2805 @code{mem}; these unusual patterns are used to represent jumps through
2806 branch tables.
2807
2808 If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of
2809 @var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
2810 valid for the mode of @var{lval}.
2811
2812 @findex SET_DEST
2813 @findex SET_SRC
2814 @var{lval} is customarily accessed with the @code{SET_DEST} macro and
2815 @var{x} with the @code{SET_SRC} macro.
2816
2817 @findex return
2818 @item (return)
2819 As the sole expression in a pattern, represents a return from the
2820 current function, on machines where this can be done with one
2821 instruction, such as VAXen.  On machines where a multi-instruction
2822 ``epilogue'' must be executed in order to return from the function,
2823 returning is done by jumping to a label which precedes the epilogue, and
2824 the @code{return} expression code is never used.
2825
2826 Inside an @code{if_then_else} expression, represents the value to be
2827 placed in @code{pc} to return to the caller.
2828
2829 Note that an insn pattern of @code{(return)} is logically equivalent to
2830 @code{(set (pc) (return))}, but the latter form is never used.
2831
2832 @findex call
2833 @item (call @var{function} @var{nargs})
2834 Represents a function call.  @var{function} is a @code{mem} expression
2835 whose address is the address of the function to be called.
2836 @var{nargs} is an expression which can be used for two purposes: on
2837 some machines it represents the number of bytes of stack argument; on
2838 others, it represents the number of argument registers.
2839
2840 Each machine has a standard machine mode which @var{function} must
2841 have.  The machine description defines macro @code{FUNCTION_MODE} to
2842 expand into the requisite mode name.  The purpose of this mode is to
2843 specify what kind of addressing is allowed, on machines where the
2844 allowed kinds of addressing depend on the machine mode being
2845 addressed.
2846
2847 @findex clobber
2848 @item (clobber @var{x})
2849 Represents the storing or possible storing of an unpredictable,
2850 undescribed value into @var{x}, which must be a @code{reg},
2851 @code{scratch}, @code{parallel} or @code{mem} expression.
2852
2853 One place this is used is in string instructions that store standard
2854 values into particular hard registers.  It may not be worth the
2855 trouble to describe the values that are stored, but it is essential to
2856 inform the compiler that the registers will be altered, lest it
2857 attempt to keep data in them across the string instruction.
2858
2859 If @var{x} is @code{(mem:BLK (const_int 0))} or
2860 @code{(mem:BLK (scratch))}, it means that all memory
2861 locations must be presumed clobbered.  If @var{x} is a @code{parallel},
2862 it has the same meaning as a @code{parallel} in a @code{set} expression.
2863
2864 Note that the machine description classifies certain hard registers as
2865 ``call-clobbered''.  All function call instructions are assumed by
2866 default to clobber these registers, so there is no need to use
2867 @code{clobber} expressions to indicate this fact.  Also, each function
2868 call is assumed to have the potential to alter any memory location,
2869 unless the function is declared @code{const}.
2870
2871 If the last group of expressions in a @code{parallel} are each a
2872 @code{clobber} expression whose arguments are @code{reg} or
2873 @code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
2874 phase can add the appropriate @code{clobber} expressions to an insn it
2875 has constructed when doing so will cause a pattern to be matched.
2876
2877 This feature can be used, for example, on a machine that whose multiply
2878 and add instructions don't use an MQ register but which has an
2879 add-accumulate instruction that does clobber the MQ register.  Similarly,
2880 a combined instruction might require a temporary register while the
2881 constituent instructions might not.
2882
2883 When a @code{clobber} expression for a register appears inside a
2884 @code{parallel} with other side effects, the register allocator
2885 guarantees that the register is unoccupied both before and after that
2886 insn.  However, the reload phase may allocate a register used for one of
2887 the inputs unless the @samp{&} constraint is specified for the selected
2888 alternative (@pxref{Modifiers}).  You can clobber either a specific hard
2889 register, a pseudo register, or a @code{scratch} expression; in the
2890 latter two cases, GCC will allocate a hard register that is available
2891 there for use as a temporary.
2892
2893 For instructions that require a temporary register, you should use
2894 @code{scratch} instead of a pseudo-register because this will allow the
2895 combiner phase to add the @code{clobber} when required.  You do this by
2896 coding (@code{clobber} (@code{match_scratch} @dots{})).  If you do
2897 clobber a pseudo register, use one which appears nowhere else---generate
2898 a new one each time.  Otherwise, you may confuse CSE@.
2899
2900 There is one other known use for clobbering a pseudo register in a
2901 @code{parallel}: when one of the input operands of the insn is also
2902 clobbered by the insn.  In this case, using the same pseudo register in
2903 the clobber and elsewhere in the insn produces the expected results.
2904
2905 @findex use
2906 @item (use @var{x})
2907 Represents the use of the value of @var{x}.  It indicates that the
2908 value in @var{x} at this point in the program is needed, even though
2909 it may not be apparent why this is so.  Therefore, the compiler will
2910 not attempt to delete previous instructions whose only effect is to
2911 store a value in @var{x}.  @var{x} must be a @code{reg} expression.
2912
2913 In some situations, it may be tempting to add a @code{use} of a
2914 register in a @code{parallel} to describe a situation where the value
2915 of a special register will modify the behavior of the instruction.
2916 An hypothetical example might be a pattern for an addition that can
2917 either wrap around or use saturating addition depending on the value
2918 of a special control register:
2919
2920 @smallexample
2921 (parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
2922                                        (reg:SI 4)] 0))
2923            (use (reg:SI 1))])
2924 @end smallexample
2925
2926 @noindent
2927
2928 This will not work, several of the optimizers only look at expressions
2929 locally; it is very likely that if you have multiple insns with
2930 identical inputs to the @code{unspec}, they will be optimized away even
2931 if register 1 changes in between.
2932
2933 This means that @code{use} can @emph{only} be used to describe
2934 that the register is live.  You should think twice before adding
2935 @code{use} statements, more often you will want to use @code{unspec}
2936 instead.  The @code{use} RTX is most commonly useful to describe that
2937 a fixed register is implicitly used in an insn.  It is also safe to use
2938 in patterns where the compiler knows for other reasons that the result
2939 of the whole pattern is variable, such as @samp{movmem@var{m}} or
2940 @samp{call} patterns.
2941
2942 During the reload phase, an insn that has a @code{use} as pattern
2943 can carry a reg_equal note.  These @code{use} insns will be deleted
2944 before the reload phase exits.
2945
2946 During the delayed branch scheduling phase, @var{x} may be an insn.
2947 This indicates that @var{x} previously was located at this place in the
2948 code and its data dependencies need to be taken into account.  These
2949 @code{use} insns will be deleted before the delayed branch scheduling
2950 phase exits.
2951
2952 @findex parallel
2953 @item (parallel [@var{x0} @var{x1} @dots{}])
2954 Represents several side effects performed in parallel.  The square
2955 brackets stand for a vector; the operand of @code{parallel} is a
2956 vector of expressions.  @var{x0}, @var{x1} and so on are individual
2957 side effect expressions---expressions of code @code{set}, @code{call},
2958 @code{return}, @code{clobber} or @code{use}.
2959
2960 ``In parallel'' means that first all the values used in the individual
2961 side-effects are computed, and second all the actual side-effects are
2962 performed.  For example,
2963
2964 @smallexample
2965 (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
2966            (set (mem:SI (reg:SI 1)) (reg:SI 1))])
2967 @end smallexample
2968
2969 @noindent
2970 says unambiguously that the values of hard register 1 and the memory
2971 location addressed by it are interchanged.  In both places where
2972 @code{(reg:SI 1)} appears as a memory address it refers to the value
2973 in register 1 @emph{before} the execution of the insn.
2974
2975 It follows that it is @emph{incorrect} to use @code{parallel} and
2976 expect the result of one @code{set} to be available for the next one.
2977 For example, people sometimes attempt to represent a jump-if-zero
2978 instruction this way:
2979
2980 @smallexample
2981 (parallel [(set (cc0) (reg:SI 34))
2982            (set (pc) (if_then_else
2983                         (eq (cc0) (const_int 0))
2984                         (label_ref @dots{})
2985                         (pc)))])
2986 @end smallexample
2987
2988 @noindent
2989 But this is incorrect, because it says that the jump condition depends
2990 on the condition code value @emph{before} this instruction, not on the
2991 new value that is set by this instruction.
2992
2993 @cindex peephole optimization, RTL representation
2994 Peephole optimization, which takes place together with final assembly
2995 code output, can produce insns whose patterns consist of a @code{parallel}
2996 whose elements are the operands needed to output the resulting
2997 assembler code---often @code{reg}, @code{mem} or constant expressions.
2998 This would not be well-formed RTL at any other stage in compilation,
2999 but it is ok then because no further optimization remains to be done.
3000 However, the definition of the macro @code{NOTICE_UPDATE_CC}, if
3001 any, must deal with such insns if you define any peephole optimizations.
3002
3003 @findex cond_exec
3004 @item (cond_exec [@var{cond} @var{expr}])
3005 Represents a conditionally executed expression.  The @var{expr} is
3006 executed only if the @var{cond} is nonzero.  The @var{cond} expression
3007 must not have side-effects, but the @var{expr} may very well have
3008 side-effects.
3009
3010 @findex sequence
3011 @item (sequence [@var{insns} @dots{}])
3012 Represents a sequence of insns.  Each of the @var{insns} that appears
3013 in the vector is suitable for appearing in the chain of insns, so it
3014 must be an @code{insn}, @code{jump_insn}, @code{call_insn},
3015 @code{code_label}, @code{barrier} or @code{note}.
3016
3017 A @code{sequence} RTX is never placed in an actual insn during RTL
3018 generation.  It represents the sequence of insns that result from a
3019 @code{define_expand} @emph{before} those insns are passed to
3020 @code{emit_insn} to insert them in the chain of insns.  When actually
3021 inserted, the individual sub-insns are separated out and the
3022 @code{sequence} is forgotten.
3023
3024 After delay-slot scheduling is completed, an insn and all the insns that
3025 reside in its delay slots are grouped together into a @code{sequence}.
3026 The insn requiring the delay slot is the first insn in the vector;
3027 subsequent insns are to be placed in the delay slot.
3028
3029 @code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
3030 indicate that a branch insn should be used that will conditionally annul
3031 the effect of the insns in the delay slots.  In such a case,
3032 @code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
3033 the branch and should be executed only if the branch is taken; otherwise
3034 the insn should be executed only if the branch is not taken.
3035 @xref{Delay Slots}.
3036 @end table
3037
3038 These expression codes appear in place of a side effect, as the body of
3039 an insn, though strictly speaking they do not always describe side
3040 effects as such:
3041
3042 @table @code
3043 @findex asm_input
3044 @item (asm_input @var{s})
3045 Represents literal assembler code as described by the string @var{s}.
3046
3047 @findex unspec
3048 @findex unspec_volatile
3049 @item (unspec [@var{operands} @dots{}] @var{index})
3050 @itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
3051 Represents a machine-specific operation on @var{operands}.  @var{index}
3052 selects between multiple machine-specific operations.
3053 @code{unspec_volatile} is used for volatile operations and operations
3054 that may trap; @code{unspec} is used for other operations.
3055
3056 These codes may appear inside a @code{pattern} of an
3057 insn, inside a @code{parallel}, or inside an expression.
3058
3059 @findex addr_vec
3060 @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
3061 Represents a table of jump addresses.  The vector elements @var{lr0},
3062 etc., are @code{label_ref} expressions.  The mode @var{m} specifies
3063 how much space is given to each address; normally @var{m} would be
3064 @code{Pmode}.
3065
3066 @findex addr_diff_vec
3067 @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags})
3068 Represents a table of jump addresses expressed as offsets from
3069 @var{base}.  The vector elements @var{lr0}, etc., are @code{label_ref}
3070 expressions and so is @var{base}.  The mode @var{m} specifies how much
3071 space is given to each address-difference.  @var{min} and @var{max}
3072 are set up by branch shortening and hold a label with a minimum and a
3073 maximum address, respectively.  @var{flags} indicates the relative
3074 position of @var{base}, @var{min} and @var{max} to the containing insn
3075 and of @var{min} and @var{max} to @var{base}.  See rtl.def for details.
3076
3077 @findex prefetch
3078 @item (prefetch:@var{m} @var{addr} @var{rw} @var{locality})
3079 Represents prefetch of memory at address @var{addr}.
3080 Operand @var{rw} is 1 if the prefetch is for data to be written, 0 otherwise;
3081 targets that do not support write prefetches should treat this as a normal
3082 prefetch.
3083 Operand @var{locality} specifies the amount of temporal locality; 0 if there
3084 is none or 1, 2, or 3 for increasing levels of temporal locality;
3085 targets that do not support locality hints should ignore this.
3086
3087 This insn is used to minimize cache-miss latency by moving data into a
3088 cache before it is accessed.  It should use only non-faulting data prefetch
3089 instructions.
3090 @end table
3091
3092 @node Incdec
3093 @section Embedded Side-Effects on Addresses
3094 @cindex RTL preincrement
3095 @cindex RTL postincrement
3096 @cindex RTL predecrement
3097 @cindex RTL postdecrement
3098
3099 Six special side-effect expression codes appear as memory addresses.
3100
3101 @table @code
3102 @findex pre_dec
3103 @item (pre_dec:@var{m} @var{x})
3104 Represents the side effect of decrementing @var{x} by a standard
3105 amount and represents also the value that @var{x} has after being
3106 decremented.  @var{x} must be a @code{reg} or @code{mem}, but most
3107 machines allow only a @code{reg}.  @var{m} must be the machine mode
3108 for pointers on the machine in use.  The amount @var{x} is decremented
3109 by is the length in bytes of the machine mode of the containing memory
3110 reference of which this expression serves as the address.  Here is an
3111 example of its use:
3112
3113 @smallexample
3114 (mem:DF (pre_dec:SI (reg:SI 39)))
3115 @end smallexample
3116
3117 @noindent
3118 This says to decrement pseudo register 39 by the length of a @code{DFmode}
3119 value and use the result to address a @code{DFmode} value.
3120
3121 @findex pre_inc
3122 @item (pre_inc:@var{m} @var{x})
3123 Similar, but specifies incrementing @var{x} instead of decrementing it.
3124
3125 @findex post_dec
3126 @item (post_dec:@var{m} @var{x})
3127 Represents the same side effect as @code{pre_dec} but a different
3128 value.  The value represented here is the value @var{x} has @i{before}
3129 being decremented.
3130
3131 @findex post_inc
3132 @item (post_inc:@var{m} @var{x})
3133 Similar, but specifies incrementing @var{x} instead of decrementing it.
3134
3135 @findex post_modify
3136 @item (post_modify:@var{m} @var{x} @var{y})
3137
3138 Represents the side effect of setting @var{x} to @var{y} and
3139 represents @var{x} before @var{x} is modified.  @var{x} must be a
3140 @code{reg} or @code{mem}, but most machines allow only a @code{reg}.
3141 @var{m} must be the machine mode for pointers on the machine in use.
3142
3143 The expression @var{y} must be one of three forms:
3144 @table @code
3145 @code{(plus:@var{m} @var{x} @var{z})},
3146 @code{(minus:@var{m} @var{x} @var{z})}, or
3147 @code{(plus:@var{m} @var{x} @var{i})},
3148 @end table
3149 where @var{z} is an index register and @var{i} is a constant.
3150
3151 Here is an example of its use:
3152
3153 @smallexample
3154 (mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
3155                                           (reg:SI 48))))
3156 @end smallexample
3157
3158 This says to modify pseudo register 42 by adding the contents of pseudo
3159 register 48 to it, after the use of what ever 42 points to.
3160
3161 @findex pre_modify
3162 @item (pre_modify:@var{m} @var{x} @var{expr})
3163 Similar except side effects happen before the use.
3164 @end table
3165
3166 These embedded side effect expressions must be used with care.  Instruction
3167 patterns may not use them.  Until the @samp{flow} pass of the compiler,
3168 they may occur only to represent pushes onto the stack.  The @samp{flow}
3169 pass finds cases where registers are incremented or decremented in one
3170 instruction and used as an address shortly before or after; these cases are
3171 then transformed to use pre- or post-increment or -decrement.
3172
3173 If a register used as the operand of these expressions is used in
3174 another address in an insn, the original value of the register is used.
3175 Uses of the register outside of an address are not permitted within the
3176 same insn as a use in an embedded side effect expression because such
3177 insns behave differently on different machines and hence must be treated
3178 as ambiguous and disallowed.
3179
3180 An instruction that can be represented with an embedded side effect
3181 could also be represented using @code{parallel} containing an additional
3182 @code{set} to describe how the address register is altered.  This is not
3183 done because machines that allow these operations at all typically
3184 allow them wherever a memory address is called for.  Describing them as
3185 additional parallel stores would require doubling the number of entries
3186 in the machine description.
3187
3188 @node Assembler
3189 @section Assembler Instructions as Expressions
3190 @cindex assembler instructions in RTL
3191
3192 @cindex @code{asm_operands}, usage
3193 The RTX code @code{asm_operands} represents a value produced by a
3194 user-specified assembler instruction.  It is used to represent
3195 an @code{asm} statement with arguments.  An @code{asm} statement with
3196 a single output operand, like this:
3197
3198 @smallexample
3199 asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
3200 @end smallexample
3201
3202 @noindent
3203 is represented using a single @code{asm_operands} RTX which represents
3204 the value that is stored in @code{outputvar}:
3205
3206 @smallexample
3207 (set @var{rtx-for-outputvar}
3208      (asm_operands "foo %1,%2,%0" "a" 0
3209                    [@var{rtx-for-addition-result} @var{rtx-for-*z}]
3210                    [(asm_input:@var{m1} "g")
3211                     (asm_input:@var{m2} "di")]))
3212 @end smallexample
3213
3214 @noindent
3215 Here the operands of the @code{asm_operands} RTX are the assembler
3216 template string, the output-operand's constraint, the index-number of the
3217 output operand among the output operands specified, a vector of input
3218 operand RTX's, and a vector of input-operand modes and constraints.  The
3219 mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
3220 @code{*z}.
3221
3222 When an @code{asm} statement has multiple output values, its insn has
3223 several such @code{set} RTX's inside of a @code{parallel}.  Each @code{set}
3224 contains a @code{asm_operands}; all of these share the same assembler
3225 template and vectors, but each contains the constraint for the respective
3226 output operand.  They are also distinguished by the output-operand index
3227 number, which is 0, 1, @dots{} for successive output operands.
3228
3229 @node Insns
3230 @section Insns
3231 @cindex insns
3232
3233 The RTL representation of the code for a function is a doubly-linked
3234 chain of objects called @dfn{insns}.  Insns are expressions with
3235 special codes that are used for no other purpose.  Some insns are
3236 actual instructions; others represent dispatch tables for @code{switch}
3237 statements; others represent labels to jump to or various sorts of
3238 declarative information.
3239
3240 In addition to its own specific data, each insn must have a unique
3241 id-number that distinguishes it from all other insns in the current
3242 function (after delayed branch scheduling, copies of an insn with the
3243 same id-number may be present in multiple places in a function, but
3244 these copies will always be identical and will only appear inside a
3245 @code{sequence}), and chain pointers to the preceding and following
3246 insns.  These three fields occupy the same position in every insn,
3247 independent of the expression code of the insn.  They could be accessed
3248 with @code{XEXP} and @code{XINT}, but instead three special macros are
3249 always used:
3250
3251 @table @code
3252 @findex INSN_UID
3253 @item INSN_UID (@var{i})
3254 Accesses the unique id of insn @var{i}.
3255
3256 @findex PREV_INSN
3257 @item PREV_INSN (@var{i})
3258 Accesses the chain pointer to the insn preceding @var{i}.
3259 If @var{i} is the first insn, this is a null pointer.
3260
3261 @findex NEXT_INSN
3262 @item NEXT_INSN (@var{i})
3263 Accesses the chain pointer to the insn following @var{i}.
3264 If @var{i} is the last insn, this is a null pointer.
3265 @end table
3266
3267 @findex get_insns
3268 @findex get_last_insn
3269 The first insn in the chain is obtained by calling @code{get_insns}; the
3270 last insn is the result of calling @code{get_last_insn}.  Within the
3271 chain delimited by these insns, the @code{NEXT_INSN} and
3272 @code{PREV_INSN} pointers must always correspond: if @var{insn} is not
3273 the first insn,
3274
3275 @smallexample
3276 NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
3277 @end smallexample
3278
3279 @noindent
3280 is always true and if @var{insn} is not the last insn,
3281
3282 @smallexample
3283 PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
3284 @end smallexample
3285
3286 @noindent
3287 is always true.
3288
3289 After delay slot scheduling, some of the insns in the chain might be
3290 @code{sequence} expressions, which contain a vector of insns.  The value
3291 of @code{NEXT_INSN} in all but the last of these insns is the next insn
3292 in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
3293 is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
3294 which it is contained.  Similar rules apply for @code{PREV_INSN}.
3295
3296 This means that the above invariants are not necessarily true for insns
3297 inside @code{sequence} expressions.  Specifically, if @var{insn} is the
3298 first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
3299 is the insn containing the @code{sequence} expression, as is the value
3300 of @code{PREV_INSN (NEXT_INSN (@var{insn}))} if @var{insn} is the last
3301 insn in the @code{sequence} expression.  You can use these expressions
3302 to find the containing @code{sequence} expression.
3303
3304 Every insn has one of the following six expression codes:
3305
3306 @table @code
3307 @findex insn
3308 @item insn
3309 The expression code @code{insn} is used for instructions that do not jump
3310 and do not do function calls.  @code{sequence} expressions are always
3311 contained in insns with code @code{insn} even if one of those insns
3312 should jump or do function calls.
3313
3314 Insns with code @code{insn} have four additional fields beyond the three
3315 mandatory ones listed above.  These four are described in a table below.
3316
3317 @findex jump_insn
3318 @item jump_insn
3319 The expression code @code{jump_insn} is used for instructions that may
3320 jump (or, more generally, may contain @code{label_ref} expressions to
3321 which @code{pc} can be set in that instruction).  If there is an
3322 instruction to return from the current function, it is recorded as a
3323 @code{jump_insn}.
3324
3325 @findex JUMP_LABEL
3326 @code{jump_insn} insns have the same extra fields as @code{insn} insns,
3327 accessed in the same way and in addition contain a field
3328 @code{JUMP_LABEL} which is defined once jump optimization has completed.
3329
3330 For simple conditional and unconditional jumps, this field contains
3331 the @code{code_label} to which this insn will (possibly conditionally)
3332 branch.  In a more complex jump, @code{JUMP_LABEL} records one of the
3333 labels that the insn refers to; other jump target labels are recorded
3334 as @code{REG_LABEL_TARGET} notes.  The exception is @code{addr_vec}
3335 and @code{addr_diff_vec}, where @code{JUMP_LABEL} is @code{NULL_RTX}
3336 and the only way to find the labels is to scan the entire body of the
3337 insn.
3338
3339 Return insns count as jumps, but since they do not refer to any
3340 labels, their @code{JUMP_LABEL} is @code{NULL_RTX}.
3341
3342 @findex call_insn
3343 @item call_insn
3344 The expression code @code{call_insn} is used for instructions that may do
3345 function calls.  It is important to distinguish these instructions because
3346 they imply that certain registers and memory locations may be altered
3347 unpredictably.
3348
3349 @findex CALL_INSN_FUNCTION_USAGE
3350 @code{call_insn} insns have the same extra fields as @code{insn} insns,
3351 accessed in the same way and in addition contain a field
3352 @code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of
3353 @code{expr_list} expressions) containing @code{use} and @code{clobber}
3354 expressions that denote hard registers and @code{MEM}s used or
3355 clobbered by the called function.
3356
3357 A @code{MEM} generally points to a stack slots in which arguments passed
3358 to the libcall by reference (@pxref{Register Arguments,
3359 TARGET_PASS_BY_REFERENCE}) are stored.  If the argument is
3360 caller-copied (@pxref{Register Arguments, TARGET_CALLEE_COPIES}),
3361 the stack slot will be mentioned in @code{CLOBBER} and @code{USE}
3362 entries; if it's callee-copied, only a @code{USE} will appear, and the
3363 @code{MEM} may point to addresses that are not stack slots.
3364
3365 @code{CLOBBER}ed registers in this list augment registers specified in
3366 @code{CALL_USED_REGISTERS} (@pxref{Register Basics}).
3367
3368 @findex code_label
3369 @findex CODE_LABEL_NUMBER
3370 @item code_label
3371 A @code{code_label} insn represents a label that a jump insn can jump
3372 to.  It contains two special fields of data in addition to the three
3373 standard ones.  @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
3374 number}, a number that identifies this label uniquely among all the
3375 labels in the compilation (not just in the current function).
3376 Ultimately, the label is represented in the assembler output as an
3377 assembler label, usually of the form @samp{L@var{n}} where @var{n} is
3378 the label number.
3379
3380 When a @code{code_label} appears in an RTL expression, it normally
3381 appears within a @code{label_ref} which represents the address of
3382 the label, as a number.
3383
3384 Besides as a @code{code_label}, a label can also be represented as a
3385 @code{note} of type @code{NOTE_INSN_DELETED_LABEL}.
3386
3387 @findex LABEL_NUSES
3388 The field @code{LABEL_NUSES} is only defined once the jump optimization
3389 phase is completed.  It contains the number of times this label is
3390 referenced in the current function.
3391
3392 @findex LABEL_KIND
3393 @findex SET_LABEL_KIND
3394 @findex LABEL_ALT_ENTRY_P
3395 @cindex alternate entry points
3396 The field @code{LABEL_KIND} differentiates four different types of
3397 labels: @code{LABEL_NORMAL}, @code{LABEL_STATIC_ENTRY},
3398 @code{LABEL_GLOBAL_ENTRY}, and @code{LABEL_WEAK_ENTRY}.  The only labels
3399 that do not have type @code{LABEL_NORMAL} are @dfn{alternate entry
3400 points} to the current function.  These may be static (visible only in
3401 the containing translation unit), global (exposed to all translation
3402 units), or weak (global, but can be overridden by another symbol with the
3403 same name).
3404
3405 Much of the compiler treats all four kinds of label identically.  Some
3406 of it needs to know whether or not a label is an alternate entry point;
3407 for this purpose, the macro @code{LABEL_ALT_ENTRY_P} is provided.  It is
3408 equivalent to testing whether @samp{LABEL_KIND (label) == LABEL_NORMAL}.
3409 The only place that cares about the distinction between static, global,
3410 and weak alternate entry points, besides the front-end code that creates
3411 them, is the function @code{output_alternate_entry_point}, in
3412 @file{final.c}.
3413
3414 To set the kind of a label, use the @code{SET_LABEL_KIND} macro.
3415
3416 @findex barrier
3417 @item barrier
3418 Barriers are placed in the instruction stream when control cannot flow
3419 past them.  They are placed after unconditional jump instructions to
3420 indicate that the jumps are unconditional and after calls to
3421 @code{volatile} functions, which do not return (e.g., @code{exit}).
3422 They contain no information beyond the three standard fields.
3423
3424 @findex note
3425 @findex NOTE_LINE_NUMBER
3426 @findex NOTE_SOURCE_FILE
3427 @item note
3428 @code{note} insns are used to represent additional debugging and
3429 declarative information.  They contain two nonstandard fields, an
3430 integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
3431 string accessed with @code{NOTE_SOURCE_FILE}.
3432
3433 If @code{NOTE_LINE_NUMBER} is positive, the note represents the
3434 position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
3435 that the line came from.  These notes control generation of line
3436 number data in the assembler output.
3437
3438 Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
3439 code with one of the following values (and @code{NOTE_SOURCE_FILE}
3440 must contain a null pointer):
3441
3442 @table @code
3443 @findex NOTE_INSN_DELETED
3444 @item NOTE_INSN_DELETED
3445 Such a note is completely ignorable.  Some passes of the compiler
3446 delete insns by altering them into notes of this kind.
3447
3448 @findex NOTE_INSN_DELETED_LABEL
3449 @item NOTE_INSN_DELETED_LABEL
3450 This marks what used to be a @code{code_label}, but was not used for other
3451 purposes than taking its address and was transformed to mark that no
3452 code jumps to it.
3453
3454 @findex NOTE_INSN_BLOCK_BEG
3455 @findex NOTE_INSN_BLOCK_END
3456 @item NOTE_INSN_BLOCK_BEG
3457 @itemx NOTE_INSN_BLOCK_END
3458 These types of notes indicate the position of the beginning and end
3459 of a level of scoping of variable names.  They control the output
3460 of debugging information.
3461
3462 @findex NOTE_INSN_EH_REGION_BEG
3463 @findex NOTE_INSN_EH_REGION_END
3464 @item NOTE_INSN_EH_REGION_BEG
3465 @itemx NOTE_INSN_EH_REGION_END
3466 These types of notes indicate the position of the beginning and end of a
3467 level of scoping for exception handling.  @code{NOTE_BLOCK_NUMBER}
3468 identifies which @code{CODE_LABEL} or @code{note} of type
3469 @code{NOTE_INSN_DELETED_LABEL} is associated with the given region.
3470
3471 @findex NOTE_INSN_LOOP_BEG
3472 @findex NOTE_INSN_LOOP_END
3473 @item NOTE_INSN_LOOP_BEG
3474 @itemx NOTE_INSN_LOOP_END
3475 These types of notes indicate the position of the beginning and end
3476 of a @code{while} or @code{for} loop.  They enable the loop optimizer
3477 to find loops quickly.
3478
3479 @findex NOTE_INSN_LOOP_CONT
3480 @item NOTE_INSN_LOOP_CONT
3481 Appears at the place in a loop that @code{continue} statements jump to.
3482
3483 @findex NOTE_INSN_LOOP_VTOP
3484 @item NOTE_INSN_LOOP_VTOP
3485 This note indicates the place in a loop where the exit test begins for
3486 those loops in which the exit test has been duplicated.  This position
3487 becomes another virtual start of the loop when considering loop
3488 invariants.
3489
3490 @findex NOTE_INSN_FUNCTION_BEG
3491 @item NOTE_INSN_FUNCTION_BEG
3492 Appears at the start of the function body, after the function
3493 prologue.
3494
3495 @end table
3496
3497 These codes are printed symbolically when they appear in debugging dumps.
3498 @end table
3499
3500 @cindex @code{TImode}, in @code{insn}
3501 @cindex @code{HImode}, in @code{insn}
3502 @cindex @code{QImode}, in @code{insn}
3503 The machine mode of an insn is normally @code{VOIDmode}, but some
3504 phases use the mode for various purposes.
3505
3506 The common subexpression elimination pass sets the mode of an insn to
3507 @code{QImode} when it is the first insn in a block that has already
3508 been processed.
3509
3510 The second Haifa scheduling pass, for targets that can multiple issue,
3511 sets the mode of an insn to @code{TImode} when it is believed that the
3512 instruction begins an issue group.  That is, when the instruction
3513 cannot issue simultaneously with the previous.  This may be relied on
3514 by later passes, in particular machine-dependent reorg.
3515
3516 Here is a table of the extra fields of @code{insn}, @code{jump_insn}
3517 and @code{call_insn} insns:
3518
3519 @table @code
3520 @findex PATTERN
3521 @item PATTERN (@var{i})
3522 An expression for the side effect performed by this insn.  This must be
3523 one of the following codes: @code{set}, @code{call}, @code{use},
3524 @code{clobber}, @code{return}, @code{asm_input}, @code{asm_output},
3525 @code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec},
3526 @code{unspec_volatile}, @code{parallel}, @code{cond_exec}, or @code{sequence}.  If it is a @code{parallel},
3527 each element of the @code{parallel} must be one these codes, except that
3528 @code{parallel} expressions cannot be nested and @code{addr_vec} and
3529 @code{addr_diff_vec} are not permitted inside a @code{parallel} expression.
3530
3531 @findex INSN_CODE
3532 @item INSN_CODE (@var{i})
3533 An integer that says which pattern in the machine description matches
3534 this insn, or @minus{}1 if the matching has not yet been attempted.
3535
3536 Such matching is never attempted and this field remains @minus{}1 on an insn
3537 whose pattern consists of a single @code{use}, @code{clobber},
3538 @code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.
3539
3540 @findex asm_noperands
3541 Matching is also never attempted on insns that result from an @code{asm}
3542 statement.  These contain at least one @code{asm_operands} expression.
3543 The function @code{asm_noperands} returns a non-negative value for
3544 such insns.
3545
3546 In the debugging output, this field is printed as a number followed by
3547 a symbolic representation that locates the pattern in the @file{md}
3548 file as some small positive or negative offset from a named pattern.
3549
3550 @findex LOG_LINKS
3551 @item LOG_LINKS (@var{i})
3552 A list (chain of @code{insn_list} expressions) giving information about
3553 dependencies between instructions within a basic block.  Neither a jump
3554 nor a label may come between the related insns.  These are only used by
3555 the schedulers and by combine.  This is a deprecated data structure.
3556 Def-use and use-def chains are now preferred. 
3557
3558 @findex REG_NOTES
3559 @item REG_NOTES (@var{i})
3560 A list (chain of @code{expr_list} and @code{insn_list} expressions)
3561 giving miscellaneous information about the insn.  It is often
3562 information pertaining to the registers used in this insn.
3563 @end table
3564
3565 The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
3566 expressions.  Each of these has two operands: the first is an insn,
3567 and the second is another @code{insn_list} expression (the next one in
3568 the chain).  The last @code{insn_list} in the chain has a null pointer
3569 as second operand.  The significant thing about the chain is which
3570 insns appear in it (as first operands of @code{insn_list}
3571 expressions).  Their order is not significant.
3572
3573 This list is originally set up by the flow analysis pass; it is a null
3574 pointer until then.  Flow only adds links for those data dependencies
3575 which can be used for instruction combination.  For each insn, the flow
3576 analysis pass adds a link to insns which store into registers values
3577 that are used for the first time in this insn.
3578
3579 The @code{REG_NOTES} field of an insn is a chain similar to the
3580 @code{LOG_LINKS} field but it includes @code{expr_list} expressions in
3581 addition to @code{insn_list} expressions.  There are several kinds of
3582 register notes, which are distinguished by the machine mode, which in a
3583 register note is really understood as being an @code{enum reg_note}.
3584 The first operand @var{op} of the note is data whose meaning depends on
3585 the kind of note.
3586
3587 @findex REG_NOTE_KIND
3588 @findex PUT_REG_NOTE_KIND
3589 The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of
3590 register note.  Its counterpart, the macro @code{PUT_REG_NOTE_KIND
3591 (@var{x}, @var{newkind})} sets the register note type of @var{x} to be
3592 @var{newkind}.
3593
3594 Register notes are of three classes: They may say something about an
3595 input to an insn, they may say something about an output of an insn, or
3596 they may create a linkage between two insns.  There are also a set
3597 of values that are only used in @code{LOG_LINKS}.
3598
3599 These register notes annotate inputs to an insn:
3600
3601 @table @code
3602 @findex REG_DEAD
3603 @item REG_DEAD
3604 The value in @var{op} dies in this insn; that is to say, altering the
3605 value immediately after this insn would not affect the future behavior
3606 of the program.
3607
3608 It does not follow that the register @var{op} has no useful value after
3609 this insn since @var{op} is not necessarily modified by this insn.
3610 Rather, no subsequent instruction uses the contents of @var{op}.
3611
3612 @findex REG_UNUSED
3613 @item REG_UNUSED
3614 The register @var{op} being set by this insn will not be used in a
3615 subsequent insn.  This differs from a @code{REG_DEAD} note, which
3616 indicates that the value in an input will not be used subsequently.
3617 These two notes are independent; both may be present for the same
3618 register.
3619
3620 @findex REG_INC
3621 @item REG_INC
3622 The register @var{op} is incremented (or decremented; at this level
3623 there is no distinction) by an embedded side effect inside this insn.
3624 This means it appears in a @code{post_inc}, @code{pre_inc},
3625 @code{post_dec} or @code{pre_dec} expression.
3626
3627 @findex REG_NONNEG
3628 @item REG_NONNEG
3629 The register @var{op} is known to have a nonnegative value when this
3630 insn is reached.  This is used so that decrement and branch until zero
3631 instructions, such as the m68k dbra, can be matched.
3632
3633 The @code{REG_NONNEG} note is added to insns only if the machine
3634 description has a @samp{decrement_and_branch_until_zero} pattern.
3635
3636 @findex REG_LABEL_OPERAND
3637 @item REG_LABEL_OPERAND
3638 This insn uses @var{op}, a @code{code_label} or a @code{note} of type
3639 @code{NOTE_INSN_DELETED_LABEL}, but is not a @code{jump_insn}, or it
3640 is a @code{jump_insn} that refers to the operand as an ordinary
3641 operand.  The label may still eventually be a jump target, but if so
3642 in an indirect jump in a subsequent insn.  The presence of this note
3643 allows jump optimization to be aware that @var{op} is, in fact, being
3644 used, and flow optimization to build an accurate flow graph.