OSDN Git Service

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