Debian Codegraph @

gcc/doc/rtl.texi

raw
1 @c Copyright (C) 1988-2025 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
4
5 @node RTL
6 @chapter RTL Representation
7 @cindex RTL representation
8 @cindex representation of RTL
9 @cindex Register Transfer Language (RTL)
10
11 The last part of the compiler work is done on a low-level intermediate
12 representation called Register Transfer Language. In this language, the
13 instructions to be output are described, pretty much one by one, in an
14 algebraic form that describes what the instruction does.
15
16 RTL is inspired by Lisp lists. It has both an internal form, made up of
17 structures that point at other structures, and a textual form that is used
18 in the machine description and in printed debugging dumps. The textual
19 form uses nested parentheses to indicate the pointers in the internal form.
20
21 @menu
22 * RTL Objects:: Expressions vs vectors vs strings vs integers.
23 * RTL Classes:: Categories of RTL expression objects, and their structure.
24 * Accessors:: Macros to access expression operands or vector elts.
25 * Special Accessors:: Macros to access specific annotations on RTL.
26 * Flags:: Other flags in an RTL expression.
27 * Machine Modes:: Describing the size and format of a datum.
28 * Constants:: Expressions with constant values.
29 * Regs and Memory:: Expressions representing register contents or memory.
30 * Arithmetic:: Expressions representing arithmetic on other expressions.
31 * Comparisons:: Expressions representing comparison of expressions.
32 * Bit-Fields:: Expressions representing bit-fields in memory or reg.
33 * Vector Operations:: Expressions involving vector datatypes.
34 * Conversions:: Extending, truncating, floating or fixing.
35 * RTL Declarations:: Declaring volatility, constancy, etc.
36 * Side Effects:: Expressions for storing in registers, etc.
37 * Incdec:: Embedded side-effects for autoincrement addressing.
38 * Assembler:: Representing @code{asm} with operands.
39 * Debug Information:: Expressions representing debugging information.
40 * Insns:: Expression types for entire insns.
41 * Calls:: RTL representation of function call insns.
42 * RTL SSA:: An on-the-side SSA form for RTL
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. Note escaped quotes
89 are treated the same as a plain quote character and if you need a escaped
90 quote in a C string, you need an extra backslash to escape the backslash
91 like @code{"a=\\"c\\";"}.
92
93 A vector contains an arbitrary number of pointers to expressions. The
94 number of elements in the vector is explicitly present in the vector.
95 The written form of a vector consists of square brackets
96 (@samp{[@dots{}]}) surrounding the elements, in sequence and with
97 whitespace separating them. Vectors of length zero are not created;
98 null pointers are used instead.
99
100 @cindex expression codes
101 @cindex codes, RTL expression
102 @findex GET_CODE
103 @findex PUT_CODE
104 Expressions are classified by @dfn{expression codes} (also called RTX
105 codes). The expression code is a name defined in @file{rtl.def}, which is
106 also (in uppercase) a C enumeration constant. The possible expression
107 codes and their meanings are machine-independent. The code of an RTX can
108 be extracted with the macro @code{GET_CODE (@var{x})} and altered with
109 @code{PUT_CODE (@var{x}, @var{newcode})}.
110
111 The expression code determines how many operands the expression contains,
112 and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell
113 by looking at an operand what kind of object it is. Instead, you must know
114 from its context---from the expression code of the containing expression.
115 For example, in an expression of code @code{subreg}, the first operand is
116 to be regarded as an expression and the second operand as a polynomial
117 integer. In an expression of code @code{plus}, there are two operands,
118 both of which are to be regarded as expressions. In a @code{symbol_ref}
119 expression, there is one operand, which is to be regarded as a string.
120
121 Expressions are written as parentheses containing the name of the
122 expression type, its flags and machine mode if any, and then the operands
123 of the expression (separated by spaces).
124
125 Expression code names in the @samp{md} file are written in lowercase,
126 but when they appear in C code they are written in uppercase. In this
127 manual, they are shown as follows: @code{const_int}.
128
129 @cindex (nil)
130 @cindex nil
131 In a few contexts a null pointer is valid where an expression is normally
132 wanted. The written form of this is @code{(nil)}.
133
134 @node RTL Classes
135 @section RTL Classes and Formats
136 @cindex RTL classes
137 @cindex classes of RTX codes
138 @cindex RTX codes, classes of
139 @findex GET_RTX_CLASS
140
141 The various expression codes are divided into several @dfn{classes},
142 which are represented by single characters. You can determine the class
143 of an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}.
144 Currently, @file{rtl.def} defines these classes:
145
146 @table @code
147 @item RTX_OBJ
148 An RTX code that represents an actual object, such as a register
149 (@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}).
150 @code{LO_SUM} is also included; instead, @code{SUBREG} and
151 @code{STRICT_LOW_PART} are not in this class, but in class
152 @code{RTX_EXTRA}.
153
154 @item RTX_CONST_OBJ
155 An RTX code that represents a constant object. @code{HIGH} is also
156 included in this class.
157
158 @item RTX_COMPARE
159 An RTX code for a non-symmetric comparison, such as @code{GEU} or
160 @code{LT}.
161
162 @item RTX_COMM_COMPARE
163 An RTX code for a symmetric (commutative) comparison, such as @code{EQ}
164 or @code{ORDERED}.
165
166 @item RTX_UNARY
167 An RTX code for a unary arithmetic operation, such as @code{NEG},
168 @code{NOT}, or @code{ABS}. This category also includes value extension
169 (sign or zero) and conversions between integer and floating point.
170
171 @item RTX_COMM_ARITH
172 An RTX code for a commutative binary operation, such as @code{PLUS} or
173 @code{AND}. @code{NE} and @code{EQ} are comparisons, so they have class
174 @code{RTX_COMM_COMPARE}.
175
176 @item RTX_BIN_ARITH
177 An RTX code for a non-commutative binary operation, such as @code{MINUS},
178 @code{DIV}, or @code{ASHIFTRT}.
179
180 @item RTX_BITFIELD_OPS
181 An RTX code for a bit-field operation. Currently only
182 @code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}. These have three inputs
183 and are lvalues (so they can be used for insertion as well).
184 @xref{Bit-Fields}.
185
186 @item RTX_TERNARY
187 An RTX code for other three input operations. Currently only
188 @code{IF_THEN_ELSE}, @code{VEC_MERGE}, @code{SIGN_EXTRACT},
189 @code{ZERO_EXTRACT}, and @code{FMA}.
190
191 @item RTX_INSN
192 An RTX code for an entire instruction: @code{INSN}, @code{JUMP_INSN}, and
193 @code{CALL_INSN}. @xref{Insns}.
194
195 @item RTX_MATCH
196 An RTX code for something that matches in insns, such as
197 @code{MATCH_DUP}. These only occur in machine descriptions.
198
199 @item RTX_AUTOINC
200 An RTX code for an auto-increment addressing mode, such as
201 @code{POST_INC}. @samp{XEXP (@var{x}, 0)} gives the auto-modified
202 register.
203
204 @item RTX_EXTRA
205 All other RTX codes. This category includes the remaining codes used
206 only in machine descriptions (@code{DEFINE_*}, etc.). It also includes
207 all the codes describing side effects (@code{SET}, @code{USE},
208 @code{CLOBBER}, etc.) and the non-insns that may appear on an insn
209 chain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}.
210 @code{SUBREG} is also part of this class.
211 @end table
212
213 @cindex RTL format
214 For each expression code, @file{rtl.def} specifies the number of
215 contained objects and their kinds using a sequence of characters
216 called the @dfn{format} of the expression code. For example,
217 the format of @code{subreg} is @samp{ep}.
218
219 @cindex RTL format characters
220 These are the most commonly used format characters:
221
222 @table @code
223 @item e
224 An expression (actually a pointer to an expression).
225
226 @item i
227 An integer.
228
229 @item w
230 A wide integer.
231
232 @item s
233 A string.
234
235 @item E
236 A vector of expressions.
237 @end table
238
239 A few other format characters are used occasionally:
240
241 @table @code
242 @item u
243 @samp{u} is equivalent to @samp{e} except that it is printed differently
244 in debugging dumps. It is used for pointers to insns.
245
246 @item n
247 @samp{n} is equivalent to @samp{i} except that it is printed differently
248 in debugging dumps. It is used for the line number or code number of a
249 @code{note} insn.
250
251 @item S
252 @samp{S} indicates a string which is optional. In the RTL objects in
253 core, @samp{S} is equivalent to @samp{s}, but when the object is read,
254 from an @samp{md} file, the string value of this operand may be omitted.
255 An omitted string is taken to be the null string.
256
257 @item V
258 @samp{V} indicates a vector which is optional. In the RTL objects in
259 core, @samp{V} is equivalent to @samp{E}, but when the object is read
260 from an @samp{md} file, the vector value of this operand may be omitted.
261 An omitted vector is effectively the same as a vector of no elements.
262
263 @item B
264 @samp{B} indicates a pointer to basic block structure.
265
266 @item p
267 A polynomial integer. At present this is used only for @code{SUBREG_BYTE}.
268
269 @item 0
270 @samp{0} means a slot whose contents do not fit any normal category.
271 @samp{0} slots are not printed at all in dumps, and are often used in
272 special ways by small parts of the compiler.
273 @end table
274
275 There are macros to get the number of operands and the format
276 of an expression code:
277
278 @table @code
279 @findex GET_RTX_LENGTH
280 @item GET_RTX_LENGTH (@var{code})
281 Number of operands of an RTX of code @var{code}.
282
283 @findex GET_RTX_FORMAT
284 @item GET_RTX_FORMAT (@var{code})
285 The format of an RTX of code @var{code}, as a C string.
286 @end table
287
288 Some classes of RTX codes always have the same format. For example, it
289 is safe to assume that all comparison operations have format @code{ee}.
290
291 @table @code
292 @item RTX_UNARY
293 All codes of this class have format @code{e}.
294
295 @item RTX_BIN_ARITH
296 @itemx RTX_COMM_ARITH
297 @itemx RTX_COMM_COMPARE
298 @itemx RTX_COMPARE
299 All codes of these classes have format @code{ee}.
300
301 @item RTX_BITFIELD_OPS
302 @itemx RTX_TERNARY
303 All codes of these classes have format @code{eee}.
304
305 @item RTX_INSN
306 All codes of this class have formats that begin with @code{iuueiee}.
307 @xref{Insns}. Note that not all RTL objects linked onto an insn chain
308 are of class @code{RTX_INSN}.
309
310 @item RTX_CONST_OBJ
311 @itemx RTX_OBJ
312 @itemx RTX_MATCH
313 @itemx RTX_EXTRA
314 You can make no assumptions about the format of these codes.
315 @end table
316
317 @node Accessors
318 @section Access to Operands
319 @cindex accessors
320 @cindex access to operands
321 @cindex operand access
322
323 @findex XEXP
324 @findex XINT
325 @findex XWINT
326 @findex XSTR
327 Operands of expressions are accessed using the macros @code{XEXP},
328 @code{XINT}, @code{XWINT} and @code{XSTR}. Each of these macros takes
329 two arguments: an expression-pointer (RTX) and an operand number
330 (counting from zero). Thus,
331
332 @smallexample
333 XEXP (@var{x}, 2)
334 @end smallexample
335
336 @noindent
337 accesses operand 2 of expression @var{x}, as an expression.
338
339 @smallexample
340 XINT (@var{x}, 2)
341 @end smallexample
342
343 @noindent
344 accesses the same operand as an integer. @code{XSTR}, used in the same
345 fashion, would access it as a string.
346
347 Any operand can be accessed as an integer, as an expression or as a string.
348 You must choose the correct method of access for the kind of value actually
349 stored in the operand. You would do this based on the expression code of
350 the containing expression. That is also how you would know how many
351 operands there are.
352
353 For example, if @var{x} is an @code{int_list} expression, you know that it has
354 two operands which can be correctly accessed as @code{XINT (@var{x}, 0)}
355 and @code{XEXP (@var{x}, 1)}. Incorrect accesses like
356 @code{XEXP (@var{x}, 0)} and @code{XINT (@var{x}, 1)} would compile,
357 but would trigger an internal compiler error when rtl checking is enabled.
358 Nothing stops you from writing @code{XEXP (@var{x}, 28)} either, but
359 this will access memory past the end of the expression with
360 unpredictable results.
361
362 Access to operands which are vectors is more complicated. You can use the
363 macro @code{XVEC} to get the vector-pointer itself, or the macros
364 @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
365 vector.
366
367 @table @code
368 @findex XVEC
369 @item XVEC (@var{exp}, @var{idx})
370 Access the vector-pointer which is operand number @var{idx} in @var{exp}.
371
372 @findex XVECLEN
373 @item XVECLEN (@var{exp}, @var{idx})
374 Access the length (number of elements) in the vector which is
375 in operand number @var{idx} in @var{exp}. This value is an @code{int}.
376
377 @findex XVECEXP
378 @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
379 Access element number @var{eltnum} in the vector which is
380 in operand number @var{idx} in @var{exp}. This value is an RTX@.
381
382 It is up to you to make sure that @var{eltnum} is not negative
383 and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
384 @end table
385
386 All the macros defined in this section expand into lvalues and therefore
387 can be used to assign the operands, lengths and vector elements as well as
388 to access them.
389
390 @node Special Accessors
391 @section Access to Special Operands
392 @cindex access to special operands
393
394 Some RTL nodes have special annotations associated with them.
395
396 @table @code
397 @item MEM
398 @table @code
399 @findex MEM_ALIAS_SET
400 @item MEM_ALIAS_SET (@var{x})
401 If 0, @var{x} is not in any alias set, and may alias anything. Otherwise,
402 @var{x} can only alias @code{MEM}s in a conflicting alias set. This value
403 is set in a language-dependent manner in the front-end, and should not be
404 altered in the back-end. In some front-ends, these numbers may correspond
405 in some way to types, or other language-level entities, but they need not,
406 and the back-end makes no such assumptions.
407 These set numbers are tested with @code{alias_sets_conflict_p}.
408
409 @findex MEM_EXPR
410 @item MEM_EXPR (@var{x})
411 If this register is known to hold the value of some user-level
412 declaration, this is that tree node. It may also be a
413 @code{COMPONENT_REF}, in which case this is some field reference,
414 and @code{TREE_OPERAND (@var{x}, 0)} contains the declaration,
415 or another @code{COMPONENT_REF}, or null if there is no compile-time
416 object associated with the reference.
417
418 @findex MEM_OFFSET_KNOWN_P
419 @item MEM_OFFSET_KNOWN_P (@var{x})
420 True if the offset of the memory reference from @code{MEM_EXPR} is known.
421 @samp{MEM_OFFSET (@var{x})} provides the offset if so.
422
423 @findex MEM_OFFSET
424 @item MEM_OFFSET (@var{x})
425 The offset from the start of @code{MEM_EXPR}. The value is only valid if
426 @samp{MEM_OFFSET_KNOWN_P (@var{x})} is true.
427
428 @findex MEM_SIZE_KNOWN_P
429 @item MEM_SIZE_KNOWN_P (@var{x})
430 True if the size of the memory reference is known.
431 @samp{MEM_SIZE (@var{x})} provides its size if so.
432
433 @findex MEM_SIZE
434 @item MEM_SIZE (@var{x})
435 The size in bytes of the memory reference.
436 This is mostly relevant for @code{BLKmode} references as otherwise
437 the size is implied by the mode. The value is only valid if
438 @samp{MEM_SIZE_KNOWN_P (@var{x})} is true.
439
440 @findex MEM_ALIGN
441 @item MEM_ALIGN (@var{x})
442 The known alignment in bits of the memory reference.
443
444 @findex MEM_ADDR_SPACE
445 @item MEM_ADDR_SPACE (@var{x})
446 The address space of the memory reference. This will commonly be zero
447 for the generic address space.
448 @end table
449
450 @item REG
451 @table @code
452 @findex ORIGINAL_REGNO
453 @item ORIGINAL_REGNO (@var{x})
454 This field holds the number the register ``originally'' had; for a
455 pseudo register turned into a hard reg this will hold the old pseudo
456 register number.
457
458 @findex REG_EXPR
459 @item REG_EXPR (@var{x})
460 If this register is known to hold the value of some user-level
461 declaration, this is that tree node.
462
463 @findex REG_OFFSET
464 @item REG_OFFSET (@var{x})
465 If this register is known to hold the value of some user-level
466 declaration, this is the offset into that logical storage.
467 @end table
468
469 @item SYMBOL_REF
470 @table @code
471 @findex SYMBOL_REF_DECL
472 @item SYMBOL_REF_DECL (@var{x})
473 If the @code{symbol_ref} @var{x} was created for a @code{VAR_DECL} or
474 a @code{FUNCTION_DECL}, that tree is recorded here. If this value is
475 null, then @var{x} was created by back end code generation routines,
476 and there is no associated front end symbol table entry.
477
478 @code{SYMBOL_REF_DECL} may also point to a tree of class @code{'c'},
479 that is, some sort of constant. In this case, the @code{symbol_ref}
480 is an entry in the per-file constant pool; again, there is no associated
481 front end symbol table entry.
482
483 @findex SYMBOL_REF_CONSTANT
484 @item SYMBOL_REF_CONSTANT (@var{x})
485 If @samp{CONSTANT_POOL_ADDRESS_P (@var{x})} is true, this is the constant
486 pool entry for @var{x}. It is null otherwise.
487
488 @findex SYMBOL_REF_DATA
489 @item SYMBOL_REF_DATA (@var{x})
490 A field of opaque type used to store @code{SYMBOL_REF_DECL} or
491 @code{SYMBOL_REF_CONSTANT}.
492
493 @findex SYMBOL_REF_FLAGS
494 @item SYMBOL_REF_FLAGS (@var{x})
495 In a @code{symbol_ref}, this is used to communicate various predicates
496 about the symbol. Some of these are common enough to be computed by
497 common code, some are specific to the target. The common bits are:
498
499 @table @code
500 @findex SYMBOL_REF_FUNCTION_P
501 @findex SYMBOL_FLAG_FUNCTION
502 @item SYMBOL_FLAG_FUNCTION
503 Set if the symbol refers to a function.
504
505 @findex SYMBOL_REF_LOCAL_P
506 @findex SYMBOL_FLAG_LOCAL
507 @item SYMBOL_FLAG_LOCAL
508 Set if the symbol is local to this ``module''.
509 See @code{TARGET_BINDS_LOCAL_P}.
510
511 @findex SYMBOL_REF_EXTERNAL_P
512 @findex SYMBOL_FLAG_EXTERNAL
513 @item SYMBOL_FLAG_EXTERNAL
514 Set if this symbol is not defined in this translation unit.
515 Note that this is not the inverse of @code{SYMBOL_FLAG_LOCAL}.
516
517 @findex SYMBOL_REF_SMALL_P
518 @findex SYMBOL_FLAG_SMALL
519 @item SYMBOL_FLAG_SMALL
520 Set if the symbol is located in the small data section.
521 See @code{TARGET_IN_SMALL_DATA_P}.
522
523 @findex SYMBOL_FLAG_TLS_SHIFT
524 @findex SYMBOL_REF_TLS_MODEL
525 @item SYMBOL_REF_TLS_MODEL (@var{x})
526 This is a multi-bit field accessor that returns the @code{tls_model}
527 to be used for a thread-local storage symbol. It returns zero for
528 non-thread-local symbols.
529
530 @findex SYMBOL_REF_HAS_BLOCK_INFO_P
531 @findex SYMBOL_FLAG_HAS_BLOCK_INFO
532 @item SYMBOL_FLAG_HAS_BLOCK_INFO
533 Set if the symbol has @code{SYMBOL_REF_BLOCK} and
534 @code{SYMBOL_REF_BLOCK_OFFSET} fields.
535
536 @findex SYMBOL_REF_ANCHOR_P
537 @findex SYMBOL_FLAG_ANCHOR
538 @cindex @option{-fsection-anchors}
539 @item SYMBOL_FLAG_ANCHOR
540 Set if the symbol is used as a section anchor. ``Section anchors''
541 are symbols that have a known position within an @code{object_block}
542 and that can be used to access nearby members of that block.
543 They are used to implement @option{-fsection-anchors}.
544
545 If this flag is set, then @code{SYMBOL_FLAG_HAS_BLOCK_INFO} will be too.
546 @end table
547
548 Bits beginning with @code{SYMBOL_FLAG_MACH_DEP} are available for
549 the target's use.
550 @end table
551
552 @findex SYMBOL_REF_BLOCK
553 @item SYMBOL_REF_BLOCK (@var{x})
554 If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the
555 @samp{object_block} structure to which the symbol belongs,
556 or @code{NULL} if it has not been assigned a block.
557
558 @findex SYMBOL_REF_BLOCK_OFFSET
559 @item SYMBOL_REF_BLOCK_OFFSET (@var{x})
560 If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the offset of @var{x}
561 from the first object in @samp{SYMBOL_REF_BLOCK (@var{x})}. The value is
562 negative if @var{x} has not yet been assigned to a block, or it has not
563 been given an offset within that block.
564 @end table
565
566 @node Flags
567 @section Flags in an RTL Expression
568 @cindex flags in RTL expression
569
570 RTL expressions contain several flags (one-bit bit-fields)
571 that are used in certain types of expression. Most often they
572 are accessed with the following macros, which expand into lvalues.
573
574 @table @code
575 @findex CROSSING_JUMP_P
576 @cindex @code{jump_insn} and @samp{/j}
577 @item CROSSING_JUMP_P (@var{x})
578 Nonzero in a @code{jump_insn} if it crosses between hot and cold sections,
579 which could potentially be very far apart in the executable. The presence
580 of this flag indicates to other optimizations that this branching instruction
581 should not be ``collapsed'' into a simpler branching construct. It is used
582 when the optimization to partition basic blocks into hot and cold sections
583 is turned on.
584
585 @findex CONSTANT_POOL_ADDRESS_P
586 @cindex @code{symbol_ref} and @samp{/u}
587 @cindex @code{unchanging}, in @code{symbol_ref}
588 @item CONSTANT_POOL_ADDRESS_P (@var{x})
589 Nonzero in a @code{symbol_ref} if it refers to part of the current
590 function's constant pool. For most targets these addresses are in a
591 @code{.rodata} section entirely separate from the function, but for
592 some targets the addresses are close to the beginning of the function.
593 In either case GCC assumes these addresses can be addressed directly,
594 perhaps with the help of base registers.
595 Stored in the @code{unchanging} field and printed as @samp{/u}.
596
597 @findex INSN_ANNULLED_BRANCH_P
598 @cindex @code{jump_insn} and @samp{/u}
599 @cindex @code{call_insn} and @samp{/u}
600 @cindex @code{insn} and @samp{/u}
601 @cindex @code{unchanging}, in @code{jump_insn}, @code{call_insn} and @code{insn}
602 @item INSN_ANNULLED_BRANCH_P (@var{x})
603 In a @code{jump_insn}, @code{call_insn}, or @code{insn} indicates
604 that the branch is an annulling one. See the discussion under
605 @code{sequence} below. Stored in the @code{unchanging} field and
606 printed as @samp{/u}.
607
608 @findex INSN_DELETED_P
609 @cindex @code{insn} and @samp{/v}
610 @cindex @code{call_insn} and @samp{/v}
611 @cindex @code{jump_insn} and @samp{/v}
612 @cindex @code{code_label} and @samp{/v}
613 @cindex @code{jump_table_data} and @samp{/v}
614 @cindex @code{barrier} and @samp{/v}
615 @cindex @code{note} and @samp{/v}
616 @cindex @code{volatil}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, @code{jump_table_data}, @code{barrier}, and @code{note}
617 @item INSN_DELETED_P (@var{x})
618 In an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label},
619 @code{jump_table_data}, @code{barrier}, or @code{note},
620 nonzero if the insn has been deleted. Stored in the
621 @code{volatil} field and printed as @samp{/v}.
622
623 @findex INSN_FROM_TARGET_P
624 @cindex @code{insn} and @samp{/s}
625 @cindex @code{jump_insn} and @samp{/s}
626 @cindex @code{call_insn} and @samp{/s}
627 @cindex @code{in_struct}, in @code{insn} and @code{jump_insn} and @code{call_insn}
628 @item INSN_FROM_TARGET_P (@var{x})
629 In an @code{insn} or @code{jump_insn} or @code{call_insn} in a delay
630 slot of a branch, indicates that the insn
631 is from the target of the branch. If the branch insn has
632 @code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if
633 the branch is taken. For annulled branches with
634 @code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the
635 branch is not taken. When @code{INSN_ANNULLED_BRANCH_P} is not set,
636 this insn will always be executed. Stored in the @code{in_struct}
637 field and printed as @samp{/s}.
638
639 @findex LABEL_PRESERVE_P
640 @cindex @code{code_label} and @samp{/i}
641 @cindex @code{note} and @samp{/i}
642 @cindex @code{in_struct}, in @code{code_label} and @code{note}
643 @item LABEL_PRESERVE_P (@var{x})
644 In a @code{code_label} or @code{note}, indicates that the label is referenced by
645 code or data not visible to the RTL of a given function.
646 Labels referenced by a non-local goto will have this bit set. Stored
647 in the @code{in_struct} field and printed as @samp{/s}.
648
649 @findex LABEL_REF_NONLOCAL_P
650 @cindex @code{label_ref} and @samp{/v}
651 @cindex @code{reg_label} and @samp{/v}
652 @cindex @code{volatil}, in @code{label_ref} and @code{reg_label}
653 @item LABEL_REF_NONLOCAL_P (@var{x})
654 In @code{label_ref} and @code{reg_label} expressions, nonzero if this is
655 a reference to a non-local label.
656 Stored in the @code{volatil} field and printed as @samp{/v}.
657
658 @findex MEM_KEEP_ALIAS_SET_P
659 @cindex @code{mem} and @samp{/j}
660 @cindex @code{jump}, in @code{mem}
661 @item MEM_KEEP_ALIAS_SET_P (@var{x})
662 In @code{mem} expressions, 1 if we should keep the alias set for this
663 mem unchanged when we access a component. Set to 1, for example, when we
664 are already in a non-addressable component of an aggregate.
665 Stored in the @code{jump} field and printed as @samp{/j}.
666
667 @findex MEM_VOLATILE_P
668 @cindex @code{mem} and @samp{/v}
669 @cindex @code{asm_input} and @samp{/v}
670 @cindex @code{asm_operands} and @samp{/v}
671 @cindex @code{volatil}, in @code{mem}, @code{asm_operands}, and @code{asm_input}
672 @item MEM_VOLATILE_P (@var{x})
673 In @code{mem}, @code{asm_operands}, and @code{asm_input} expressions,
674 nonzero for volatile memory references.
675 Stored in the @code{volatil} field and printed as @samp{/v}.
676
677 @findex MEM_NOTRAP_P
678 @cindex @code{mem} and @samp{/c}
679 @cindex @code{call}, in @code{mem}
680 @item MEM_NOTRAP_P (@var{x})
681 In @code{mem}, nonzero for memory references that will not trap.
682 Stored in the @code{call} field and printed as @samp{/c}.
683
684 @findex MEM_POINTER
685 @cindex @code{mem} and @samp{/f}
686 @cindex @code{frame_related}, in @code{mem}
687 @item MEM_POINTER (@var{x})
688 Nonzero in a @code{mem} if the memory reference holds a pointer.
689 Stored in the @code{frame_related} field and printed as @samp{/f}.
690
691 @findex MEM_READONLY_P
692 @cindex @code{mem} and @samp{/u}
693 @cindex @code{unchanging}, in @code{mem}
694 @item MEM_READONLY_P (@var{x})
695 Nonzero in a @code{mem}, if the memory is statically allocated and read-only.
696
697 Read-only in this context means never modified during the lifetime of the
698 program, not necessarily in ROM or in write-disabled pages. A common
699 example of the later is a shared library's global offset table. This
700 table is initialized by the runtime loader, so the memory is technically
701 writable, but after control is transferred from the runtime loader to the
702 application, this memory will never be subsequently modified.
703
704 Stored in the @code{unchanging} field and printed as @samp{/u}.
705
706 @findex PREFETCH_SCHEDULE_BARRIER_P
707 @cindex @code{prefetch} and @samp{/v}
708 @cindex @code{volatile}, in @code{prefetch}
709 @item PREFETCH_SCHEDULE_BARRIER_P (@var{x})
710 In a @code{prefetch}, indicates that the prefetch is a scheduling barrier.
711 No other INSNs will be moved over it.
712 Stored in the @code{volatil} field and printed as @samp{/v}.
713
714 @findex REG_FUNCTION_VALUE_P
715 @cindex @code{reg} and @samp{/i}
716 @cindex @code{return_val}, in @code{reg}
717 @item REG_FUNCTION_VALUE_P (@var{x})
718 Nonzero in a @code{reg} if it is the place in which this function's
719 value is going to be returned. (This happens only in a hard
720 register.) Stored in the @code{return_val} field and printed as
721 @samp{/i}.
722
723 @findex REG_POINTER
724 @cindex @code{reg} and @samp{/f}
725 @cindex @code{frame_related}, in @code{reg}
726 @item REG_POINTER (@var{x})
727 Nonzero in a @code{reg} if the register holds a pointer. Stored in the
728 @code{frame_related} field and printed as @samp{/f}.
729
730 @findex REG_USERVAR_P
731 @cindex @code{reg} and @samp{/v}
732 @cindex @code{volatil}, in @code{reg}
733 @item REG_USERVAR_P (@var{x})
734 In a @code{reg}, nonzero if it corresponds to a variable present in
735 the user's source code. Zero for temporaries generated internally by
736 the compiler. Stored in the @code{volatil} field and printed as
737 @samp{/v}.
738
739 The same hard register may be used also for collecting the values of
740 functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
741 in this kind of use.
742
743 @findex RTL_CONST_CALL_P
744 @cindex @code{call_insn} and @samp{/u}
745 @cindex @code{unchanging}, in @code{call_insn}
746 @item RTL_CONST_CALL_P (@var{x})
747 In a @code{call_insn} indicates that the insn represents a call to a
748 const function. Stored in the @code{unchanging} field and printed as
749 @samp{/u}.
750
751 @findex RTL_PURE_CALL_P
752 @cindex @code{call_insn} and @samp{/i}
753 @cindex @code{return_val}, in @code{call_insn}
754 @item RTL_PURE_CALL_P (@var{x})
755 In a @code{call_insn} indicates that the insn represents a call to a
756 pure function. Stored in the @code{return_val} field and printed as
757 @samp{/i}.
758
759 @findex RTL_CONST_OR_PURE_CALL_P
760 @cindex @code{call_insn} and @samp{/u} or @samp{/i}
761 @item RTL_CONST_OR_PURE_CALL_P (@var{x})
762 In a @code{call_insn}, true if @code{RTL_CONST_CALL_P} or
763 @code{RTL_PURE_CALL_P} is true.
764
765 @findex RTL_LOOPING_CONST_OR_PURE_CALL_P
766 @cindex @code{call_insn} and @samp{/c}
767 @cindex @code{call}, in @code{call_insn}
768 @item RTL_LOOPING_CONST_OR_PURE_CALL_P (@var{x})
769 In a @code{call_insn} indicates that the insn represents a possibly
770 infinite looping call to a const or pure function. Stored in the
771 @code{call} field and printed as @samp{/c}. Only true if one of
772 @code{RTL_CONST_CALL_P} or @code{RTL_PURE_CALL_P} is true.
773
774 @findex RTX_FRAME_RELATED_P
775 @cindex @code{insn} and @samp{/f}
776 @cindex @code{call_insn} and @samp{/f}
777 @cindex @code{jump_insn} and @samp{/f}
778 @cindex @code{barrier} and @samp{/f}
779 @cindex @code{set} and @samp{/f}
780 @cindex @code{frame_related}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, and @code{set}
781 @item RTX_FRAME_RELATED_P (@var{x})
782 Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn},
783 @code{barrier}, or @code{set} which is part of a function prologue
784 and sets the stack pointer, sets the frame pointer, or saves a register.
785 This flag should also be set on an instruction that sets up a temporary
786 register to use in place of the frame pointer.
787 Stored in the @code{frame_related} field and printed as @samp{/f}.
788
789 In particular, on RISC targets where there are limits on the sizes of
790 immediate constants, it is sometimes impossible to reach the register
791 save area directly from the stack pointer. In that case, a temporary
792 register is used that is near enough to the register save area, and the
793 Canonical Frame Address, i.e., DWARF2's logical frame pointer, register
794 must (temporarily) be changed to be this temporary register. So, the
795 instruction that sets this temporary register must be marked as
796 @code{RTX_FRAME_RELATED_P}.
797
798 If the marked instruction is overly complex (defined in terms of what
799 @code{dwarf2out_frame_debug_expr} can handle), you will also have to
800 create a @code{REG_FRAME_RELATED_EXPR} note and attach it to the
801 instruction. This note should contain a simple expression of the
802 computation performed by this instruction, i.e., one that
803 @code{dwarf2out_frame_debug_expr} can handle.
804
805 This flag is required for exception handling support on targets with RTL
806 prologues.
807
808 @findex SCHED_GROUP_P
809 @cindex @code{insn} and @samp{/s}
810 @cindex @code{call_insn} and @samp{/s}
811 @cindex @code{jump_insn} and @samp{/s}
812 @cindex @code{jump_table_data} and @samp{/s}
813 @cindex @code{in_struct}, in @code{insn}, @code{call_insn}, @code{jump_insn} and @code{jump_table_data}
814 @item SCHED_GROUP_P (@var{x})
815 During instruction scheduling, in an @code{insn}, @code{call_insn},
816 @code{jump_insn} or @code{jump_table_data}, indicates that the
817 previous insn must be scheduled together with this insn. This is used to
818 ensure that certain groups of instructions will not be split up by the
819 instruction scheduling pass, for example, @code{use} insns before
820 a @code{call_insn} may not be separated from the @code{call_insn}.
821 Stored in the @code{in_struct} field and printed as @samp{/s}.
822
823 @findex SET_IS_RETURN_P
824 @cindex @code{insn} and @samp{/j}
825 @cindex @code{jump}, in @code{insn}
826 @item SET_IS_RETURN_P (@var{x})
827 For a @code{set}, nonzero if it is for a return.
828 Stored in the @code{jump} field and printed as @samp{/j}.
829
830 @findex SIBLING_CALL_P
831 @cindex @code{call_insn} and @samp{/j}
832 @cindex @code{jump}, in @code{call_insn}
833 @item SIBLING_CALL_P (@var{x})
834 For a @code{call_insn}, nonzero if the insn is a sibling call.
835 Stored in the @code{jump} field and printed as @samp{/j}.
836
837 @findex STRING_POOL_ADDRESS_P
838 @cindex @code{symbol_ref} and @samp{/f}
839 @cindex @code{frame_related}, in @code{symbol_ref}
840 @item STRING_POOL_ADDRESS_P (@var{x})
841 For a @code{symbol_ref} expression, nonzero if it addresses this function's
842 string constant pool.
843 Stored in the @code{frame_related} field and printed as @samp{/f}.
844
845 @findex SUBREG_PROMOTED_UNSIGNED_P
846 @cindex @code{subreg} and @samp{/u} and @samp{/v}
847 @cindex @code{unchanging}, in @code{subreg}
848 @cindex @code{volatil}, in @code{subreg}
849 @item SUBREG_PROMOTED_UNSIGNED_P (@var{x})
850 Returns a value greater then zero for a @code{subreg} that has
851 @code{SUBREG_PROMOTED_VAR_P} nonzero if the object being referenced is kept
852 zero-extended, zero if it is kept sign-extended, and less then zero if it is
853 extended some other way via the @code{ptr_extend} instruction.
854 Stored in the @code{unchanging}
855 field and @code{volatil} field, printed as @samp{/u} and @samp{/v}.
856 This macro may only be used to get the value it may not be used to change
857 the value. Use @code{SUBREG_PROMOTED_UNSIGNED_SET} to change the value.
858
859 @findex SUBREG_PROMOTED_UNSIGNED_SET
860 @cindex @code{subreg} and @samp{/u}
861 @cindex @code{unchanging}, in @code{subreg}
862 @cindex @code{volatil}, in @code{subreg}
863 @item SUBREG_PROMOTED_UNSIGNED_SET (@var{x})
864 Set the @code{unchanging} and @code{volatil} fields in a @code{subreg}
865 to reflect zero, sign, or other extension. If @code{volatil} is
866 zero, then @code{unchanging} as nonzero means zero extension and as
867 zero means sign extension. If @code{volatil} is nonzero then some
868 other type of extension was done via the @code{ptr_extend} instruction.
869
870 @findex SUBREG_PROMOTED_VAR_P
871 @cindex @code{subreg} and @samp{/s}
872 @cindex @code{in_struct}, in @code{subreg}
873 @item SUBREG_PROMOTED_VAR_P (@var{x})
874 Nonzero in a @code{subreg} if it was made when accessing an object that
875 was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine
876 description macro (@pxref{Storage Layout}). In this case, the mode of
877 the @code{subreg} is the declared mode of the object and the mode of
878 @code{SUBREG_REG} is the mode of the register that holds the object.
879 Promoted variables are always either sign- or zero-extended to the wider
880 mode on every assignment. Stored in the @code{in_struct} field and
881 printed as @samp{/s}.
882
883 @findex SYMBOL_REF_USED
884 @cindex @code{used}, in @code{symbol_ref}
885 @item SYMBOL_REF_USED (@var{x})
886 In a @code{symbol_ref}, indicates that @var{x} has been used. This is
887 normally only used to ensure that @var{x} is only declared external
888 once. Stored in the @code{used} field.
889
890 @findex SYMBOL_REF_WEAK
891 @cindex @code{symbol_ref} and @samp{/i}
892 @cindex @code{return_val}, in @code{symbol_ref}
893 @item SYMBOL_REF_WEAK (@var{x})
894 In a @code{symbol_ref}, indicates that @var{x} has been declared weak.
895 Stored in the @code{return_val} field and printed as @samp{/i}.
896
897 @findex SYMBOL_REF_FLAG
898 @cindex @code{symbol_ref} and @samp{/v}
899 @cindex @code{volatil}, in @code{symbol_ref}
900 @item SYMBOL_REF_FLAG (@var{x})
901 In a @code{symbol_ref}, this is used as a flag for machine-specific purposes.
902 Stored in the @code{volatil} field and printed as @samp{/v}.
903
904 Most uses of @code{SYMBOL_REF_FLAG} are historic and may be subsumed
905 by @code{SYMBOL_REF_FLAGS}. Certainly use of @code{SYMBOL_REF_FLAGS}
906 is mandatory if the target requires more than one bit of storage.
907 @end table
908
909 These are the fields to which the above macros refer:
910
911 @table @code
912 @findex call
913 @cindex @samp{/c} in RTL dump
914 @item call
915 In a @code{mem}, 1 means that the memory reference will not trap.
916
917 In a @code{call}, 1 means that this pure or const call may possibly
918 infinite loop.
919
920 In an RTL dump, this flag is represented as @samp{/c}.
921
922 @findex frame_related
923 @cindex @samp{/f} in RTL dump
924 @item frame_related
925 In an @code{insn} or @code{set} expression, 1 means that it is part of
926 a function prologue and sets the stack pointer, sets the frame pointer,
927 saves a register, or sets up a temporary register to use in place of the
928 frame pointer.
929
930 In @code{reg} expressions, 1 means that the register holds a pointer.
931
932 In @code{mem} expressions, 1 means that the memory reference holds a pointer.
933
934 In @code{symbol_ref} expressions, 1 means that the reference addresses
935 this function's string constant pool.
936
937 In an RTL dump, this flag is represented as @samp{/f}.
938
939 @findex in_struct
940 @cindex @samp{/s} in RTL dump
941 @item in_struct
942 In @code{reg} expressions, it is 1 if the register has its entire life
943 contained within the test expression of some loop.
944
945 In @code{subreg} expressions, 1 means that the @code{subreg} is accessing
946 an object that has had its mode promoted from a wider mode.
947
948 In @code{label_ref} expressions, 1 means that the referenced label is
949 outside the innermost loop containing the insn in which the @code{label_ref}
950 was found.
951
952 In @code{code_label} expressions, it is 1 if the label may never be deleted.
953 This is used for labels which are the target of non-local gotos. Such a
954 label that would have been deleted is replaced with a @code{note} of type
955 @code{NOTE_INSN_DELETED_LABEL}.
956
957 In an @code{insn} during dead-code elimination, 1 means that the insn is
958 dead code.
959
960 In an @code{insn} or @code{jump_insn} during reorg for an insn in the
961 delay slot of a branch,
962 1 means that this insn is from the target of the branch.
963
964 In an @code{insn} during instruction scheduling, 1 means that this insn
965 must be scheduled as part of a group together with the previous insn.
966
967 In an RTL dump, this flag is represented as @samp{/s}.
968
969 @findex return_val
970 @cindex @samp{/i} in RTL dump
971 @item return_val
972 In @code{reg} expressions, 1 means the register contains
973 the value to be returned by the current function. On
974 machines that pass parameters in registers, the same register number
975 may be used for parameters as well, but this flag is not set on such
976 uses.
977
978 In @code{symbol_ref} expressions, 1 means the referenced symbol is weak.
979
980 In @code{call} expressions, 1 means the call is pure.
981
982 In an RTL dump, this flag is represented as @samp{/i}.
983
984 @findex jump
985 @cindex @samp{/j} in RTL dump
986 @item jump
987 In a @code{mem} expression, 1 means we should keep the alias set for this
988 mem unchanged when we access a component.
989
990 In a @code{set}, 1 means it is for a return.
991
992 In a @code{call_insn}, 1 means it is a sibling call.
993
994 In a @code{jump_insn}, 1 means it is a crossing jump.
995
996 In an RTL dump, this flag is represented as @samp{/j}.
997
998 @findex unchanging
999 @cindex @samp{/u} in RTL dump
1000 @item unchanging
1001 In @code{reg} and @code{mem} expressions, 1 means
1002 that the value of the expression never changes.
1003
1004 In @code{subreg} expressions, it is 1 if the @code{subreg} references an
1005 unsigned object whose mode has been promoted to a wider mode.
1006
1007 In an @code{insn} or @code{jump_insn} in the delay slot of a branch
1008 instruction, 1 means an annulling branch should be used.
1009
1010 In a @code{symbol_ref} expression, 1 means that this symbol addresses
1011 something in the per-function constant pool.
1012
1013 In a @code{call_insn} 1 means that this instruction is a call to a const
1014 function.
1015
1016 In an RTL dump, this flag is represented as @samp{/u}.
1017
1018 @findex used
1019 @item used
1020 This flag is used directly (without an access macro) at the end of RTL
1021 generation for a function, to count the number of times an expression
1022 appears in insns. Expressions that appear more than once are copied,
1023 according to the rules for shared structure (@pxref{Sharing}).
1024
1025 For a @code{reg}, it is used directly (without an access macro) by the
1026 leaf register renumbering code to ensure that each register is only
1027 renumbered once.
1028
1029 In a @code{symbol_ref}, it indicates that an external declaration for
1030 the symbol has already been written.
1031
1032 @findex volatil
1033 @cindex @samp{/v} in RTL dump
1034 @cindex volatile memory references
1035 @item volatil
1036 In a @code{mem}, @code{asm_operands}, or @code{asm_input}
1037 expression, it is 1 if the memory
1038 reference is volatile. Volatile memory references may not be deleted,
1039 reordered or combined.
1040
1041 In a @code{symbol_ref} expression, it is used for machine-specific
1042 purposes.
1043
1044 In a @code{reg} expression, it is 1 if the value is a user-level variable.
1045 0 indicates an internal compiler temporary.
1046
1047 In an @code{insn}, 1 means the insn has been deleted.
1048
1049 In @code{label_ref} and @code{reg_label} expressions, 1 means a reference
1050 to a non-local label.
1051
1052 In @code{prefetch} expressions, 1 means that the containing insn is a
1053 scheduling barrier.
1054
1055 In an RTL dump, this flag is represented as @samp{/v}.
1056 @end table
1057
1058 @node Machine Modes
1059 @section Machine Modes
1060 @cindex machine modes
1061
1062 @findex machine_mode
1063 A machine mode describes a size of data object and the representation used
1064 for it. In the C code, machine modes are represented by an enumeration
1065 type, @code{machine_mode}, defined in @file{machmode.def}. Each RTL
1066 expression has room for a machine mode and so do certain kinds of tree
1067 expressions (declarations and types, to be precise).
1068
1069 In debugging dumps and machine descriptions, the machine mode of an RTL
1070 expression is written after the expression code with a colon to separate
1071 them. The letters @samp{mode} which appear at the end of each machine mode
1072 name are omitted. For example, @code{(reg:SI 38)} is a @code{reg}
1073 expression with machine mode @code{SImode}. If the mode is
1074 @code{VOIDmode}, it is not written at all.
1075
1076 Here is a table of machine modes. The term ``byte'' below refers to an
1077 object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}).
1078
1079 @table @code
1080 @findex BImode
1081 @item BImode
1082 ``Bit'' mode represents a single bit, for predicate registers.
1083
1084 @findex QImode
1085 @item QImode
1086 ``Quarter-Integer'' mode represents a single byte treated as an integer.
1087
1088 @findex HImode
1089 @item HImode
1090 ``Half-Integer'' mode represents a two-byte integer.
1091
1092 @findex PSImode
1093 @item PSImode
1094 ``Partial Single Integer'' mode represents an integer which occupies
1095 four bytes but which doesn't really use all four. On some machines,
1096 this is the right mode to use for pointers.
1097
1098 @findex SImode
1099 @item SImode
1100 ``Single Integer'' mode represents a four-byte integer.
1101
1102 @findex PDImode
1103 @item PDImode
1104 ``Partial Double Integer'' mode represents an integer which occupies
1105 eight bytes but which doesn't really use all eight. On some machines,
1106 this is the right mode to use for certain pointers.
1107
1108 @findex DImode
1109 @item DImode
1110 ``Double Integer'' mode represents an eight-byte integer.
1111
1112 @findex TImode
1113 @item TImode
1114 ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
1115
1116 @findex OImode
1117 @item OImode
1118 ``Octa Integer'' (?) mode represents a thirty-two-byte integer.
1119
1120 @findex XImode
1121 @item XImode
1122 ``Hexadeca Integer'' (?) mode represents a sixty-four-byte integer.
1123
1124 @findex QFmode
1125 @item QFmode
1126 ``Quarter-Floating'' mode represents a quarter-precision (single byte)
1127 floating point number.
1128
1129 @findex HFmode
1130 @item HFmode
1131 ``Half-Floating'' mode represents a half-precision (two byte) floating
1132 point number.
1133
1134 @findex TQFmode
1135 @item TQFmode
1136 ``Three-Quarter-Floating'' (?) mode represents a three-quarter-precision
1137 (three byte) floating point number.
1138
1139 @findex SFmode
1140 @item SFmode
1141 ``Single Floating'' mode represents a four byte floating point number.
1142 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1143 this is a single-precision IEEE floating point number; it can also be
1144 used for double-precision (on processors with 16-bit bytes) and
1145 single-precision VAX and IBM types.
1146
1147 @findex DFmode
1148 @item DFmode
1149 ``Double Floating'' mode represents an eight byte floating point number.
1150 In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1151 this is a double-precision IEEE floating point number.
1152
1153 @findex XFmode
1154 @item XFmode
1155 ``Extended Floating'' mode represents an IEEE extended floating point
1156 number. This mode only has 80 meaningful bits (ten bytes). Some
1157 processors require such numbers to be padded to twelve bytes, others
1158 to sixteen; this mode is used for either.
1159
1160 @findex SDmode
1161 @item SDmode
1162 ``Single Decimal Floating'' mode represents a four byte decimal
1163 floating point number (as distinct from conventional binary floating
1164 point).
1165
1166 @findex DDmode
1167 @item DDmode
1168 ``Double Decimal Floating'' mode represents an eight byte decimal
1169 floating point number.
1170
1171 @findex TDmode
1172 @item TDmode
1173 ``Tetra Decimal Floating'' mode represents a sixteen byte decimal
1174 floating point number all 128 of whose bits are meaningful.
1175
1176 @findex TFmode
1177 @item TFmode
1178 ``Tetra Floating'' mode represents a sixteen byte floating point number
1179 all 128 of whose bits are meaningful. One common use is the
1180 IEEE quad-precision format.
1181
1182 @findex QQmode
1183 @item QQmode
1184 ``Quarter-Fractional'' mode represents a single byte treated as a signed
1185 fractional number. The default format is ``s.7''.
1186
1187 @findex HQmode
1188 @item HQmode
1189 ``Half-Fractional'' mode represents a two-byte signed fractional number.
1190 The default format is ``s.15''.
1191
1192 @findex SQmode
1193 @item SQmode
1194 ``Single Fractional'' mode represents a four-byte signed fractional number.
1195 The default format is ``s.31''.
1196
1197 @findex DQmode
1198 @item DQmode
1199 ``Double Fractional'' mode represents an eight-byte signed fractional number.
1200 The default format is ``s.63''.
1201
1202 @findex TQmode
1203 @item TQmode
1204 ``Tetra Fractional'' mode represents a sixteen-byte signed fractional number.
1205 The default format is ``s.127''.
1206
1207 @findex UQQmode
1208 @item UQQmode
1209 ``Unsigned Quarter-Fractional'' mode represents a single byte treated as an
1210 unsigned fractional number. The default format is ``.8''.
1211
1212 @findex UHQmode
1213 @item UHQmode
1214 ``Unsigned Half-Fractional'' mode represents a two-byte unsigned fractional
1215 number. The default format is ``.16''.
1216
1217 @findex USQmode
1218 @item USQmode
1219 ``Unsigned Single Fractional'' mode represents a four-byte unsigned fractional
1220 number. The default format is ``.32''.
1221
1222 @findex UDQmode
1223 @item UDQmode
1224 ``Unsigned Double Fractional'' mode represents an eight-byte unsigned
1225 fractional number. The default format is ``.64''.
1226
1227 @findex UTQmode
1228 @item UTQmode
1229 ``Unsigned Tetra Fractional'' mode represents a sixteen-byte unsigned
1230 fractional number. The default format is ``.128''.
1231
1232 @findex HAmode
1233 @item HAmode
1234 ``Half-Accumulator'' mode represents a two-byte signed accumulator.
1235 The default format is ``s8.7''.
1236
1237 @findex SAmode
1238 @item SAmode
1239 ``Single Accumulator'' mode represents a four-byte signed accumulator.
1240 The default format is ``s16.15''.
1241
1242 @findex DAmode
1243 @item DAmode
1244 ``Double Accumulator'' mode represents an eight-byte signed accumulator.
1245 The default format is ``s32.31''.
1246
1247 @findex TAmode
1248 @item TAmode
1249 ``Tetra Accumulator'' mode represents a sixteen-byte signed accumulator.
1250 The default format is ``s64.63''.
1251
1252 @findex UHAmode
1253 @item UHAmode
1254 ``Unsigned Half-Accumulator'' mode represents a two-byte unsigned accumulator.
1255 The default format is ``8.8''.
1256
1257 @findex USAmode
1258 @item USAmode
1259 ``Unsigned Single Accumulator'' mode represents a four-byte unsigned
1260 accumulator. The default format is ``16.16''.
1261
1262 @findex UDAmode
1263 @item UDAmode
1264 ``Unsigned Double Accumulator'' mode represents an eight-byte unsigned
1265 accumulator. The default format is ``32.32''.
1266
1267 @findex UTAmode
1268 @item UTAmode
1269 ``Unsigned Tetra Accumulator'' mode represents a sixteen-byte unsigned
1270 accumulator. The default format is ``64.64''.
1271
1272 @findex CCmode
1273 @item CCmode
1274 ``Condition Code'' mode represents the value of a condition code, which
1275 is a machine-specific set of bits used to represent the result of a
1276 comparison operation. Other machine-specific modes may also be used for
1277 the condition code. (@pxref{Condition Code}).
1278
1279 @findex BLKmode
1280 @item BLKmode
1281 ``Block'' mode represents values that are aggregates to which none of
1282 the other modes apply. In RTL, only memory references can have this mode,
1283 and only if they appear in string-move or vector instructions. On machines
1284 which have no such instructions, @code{BLKmode} will not appear in RTL@.
1285
1286 @findex VOIDmode
1287 @item VOIDmode
1288 Void mode means the absence of a mode or an unspecified mode.
1289 For example, RTL expressions of code @code{const_int} have mode
1290 @code{VOIDmode} because they can be taken to have whatever mode the context
1291 requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by
1292 the absence of any mode.
1293
1294 @findex QCmode
1295 @findex HCmode
1296 @findex SCmode
1297 @findex DCmode
1298 @findex XCmode
1299 @findex TCmode
1300 @item QCmode, HCmode, SCmode, DCmode, XCmode, TCmode
1301 These modes stand for a complex number represented as a pair of floating
1302 point values. The floating point values are in @code{QFmode},
1303 @code{HFmode}, @code{SFmode}, @code{DFmode}, @code{XFmode}, and
1304 @code{TFmode}, respectively.
1305
1306 @findex CQImode
1307 @findex CHImode
1308 @findex CSImode
1309 @findex CDImode
1310 @findex CTImode
1311 @findex COImode
1312 @findex CPSImode
1313 @item CQImode, CHImode, CSImode, CDImode, CTImode, COImode, CPSImode
1314 These modes stand for a complex number represented as a pair of integer
1315 values. The integer values are in @code{QImode}, @code{HImode},
1316 @code{SImode}, @code{DImode}, @code{TImode}, @code{OImode}, and @code{PSImode},
1317 respectively.
1318
1319 @findex BND32mode
1320 @findex BND64mode
1321 @item BND32mode BND64mode
1322 These modes stand for bounds for pointer of 32 and 64 bit size respectively.
1323 Mode size is double pointer mode size.
1324 @end table
1325
1326 The machine description defines @code{Pmode} as a C macro which expands
1327 into the machine mode used for addresses. Normally this is the mode
1328 whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines.
1329
1330 The only modes which a machine description @i{must} support are
1331 @code{QImode}, and the modes corresponding to @code{BITS_PER_WORD},
1332 C type @code{float} and C type @code{double}.
1333 The compiler will attempt to use @code{DImode} for 8-byte structures and
1334 unions, but this can be prevented by overriding the definition of
1335 @code{MAX_FIXED_MODE_SIZE}. Alternatively, you can have the compiler
1336 use @code{TImode} for 16-byte structures and unions. Likewise, you can
1337 arrange for the C type @code{short int} to avoid using @code{HImode}.
1338
1339 @cindex mode classes
1340 Very few explicit references to machine modes remain in the compiler and
1341 these few references will soon be removed. Instead, the machine modes
1342 are divided into mode classes. These are represented by the enumeration
1343 type @code{enum mode_class} defined in @file{machmode.h}. The possible
1344 mode classes are:
1345
1346 @table @code
1347 @findex MODE_INT
1348 @item MODE_INT
1349 Integer modes. By default these are @code{BImode}, @code{QImode},
1350 @code{HImode}, @code{SImode}, @code{DImode}, @code{TImode}, and
1351 @code{OImode}.
1352
1353 @findex MODE_PARTIAL_INT
1354 @item MODE_PARTIAL_INT
1355 The ``partial integer'' modes, @code{PQImode}, @code{PHImode},
1356 @code{PSImode} and @code{PDImode}.
1357
1358 @findex MODE_FLOAT
1359 @item MODE_FLOAT
1360 Floating point modes. By default these are @code{QFmode},
1361 @code{HFmode}, @code{TQFmode}, @code{SFmode}, @code{DFmode},
1362 @code{XFmode} and @code{TFmode}.
1363
1364 @findex MODE_DECIMAL_FLOAT
1365 @item MODE_DECIMAL_FLOAT
1366 Decimal floating point modes. By default these are @code{SDmode},
1367 @code{DDmode} and @code{TDmode}.
1368
1369 @findex MODE_FRACT
1370 @item MODE_FRACT
1371 Signed fractional modes. By default these are @code{QQmode}, @code{HQmode},
1372 @code{SQmode}, @code{DQmode} and @code{TQmode}.
1373
1374 @findex MODE_UFRACT
1375 @item MODE_UFRACT
1376 Unsigned fractional modes. By default these are @code{UQQmode}, @code{UHQmode},
1377 @code{USQmode}, @code{UDQmode} and @code{UTQmode}.
1378
1379 @findex MODE_ACCUM
1380 @item MODE_ACCUM
1381 Signed accumulator modes. By default these are @code{HAmode},
1382 @code{SAmode}, @code{DAmode} and @code{TAmode}.
1383
1384 @findex MODE_UACCUM
1385 @item MODE_UACCUM
1386 Unsigned accumulator modes. By default these are @code{UHAmode},
1387 @code{USAmode}, @code{UDAmode} and @code{UTAmode}.
1388
1389 @findex MODE_COMPLEX_INT
1390 @item MODE_COMPLEX_INT
1391 Complex integer modes. (These are not currently implemented).
1392
1393 @findex MODE_COMPLEX_FLOAT
1394 @item MODE_COMPLEX_FLOAT
1395 Complex floating point modes. By default these are @code{QCmode},
1396 @code{HCmode}, @code{SCmode}, @code{DCmode}, @code{XCmode}, and
1397 @code{TCmode}.
1398
1399 @findex MODE_CC
1400 @item MODE_CC
1401 Modes representing condition code values. These are @code{CCmode} plus
1402 any @code{CC_MODE} modes listed in the @file{@var{machine}-modes.def}.
1403 @xref{Jump Patterns},
1404 also see @ref{Condition Code}.
1405
1406 @findex MODE_POINTER_BOUNDS
1407 @item MODE_POINTER_BOUNDS
1408 Pointer bounds modes. Used to represent values of pointer bounds type.
1409 Operations in these modes may be executed as NOPs depending on hardware
1410 features and environment setup.
1411
1412 @findex MODE_OPAQUE
1413 @item MODE_OPAQUE
1414 This is a mode class for modes that don't want to provide operations
1415 other than register moves, memory moves, loads, stores, and
1416 @code{unspec}s. They have a size and precision and that's all.
1417
1418 @findex MODE_RANDOM
1419 @item MODE_RANDOM
1420 This is a catchall mode class for modes which don't fit into the above
1421 classes. Currently @code{VOIDmode} and @code{BLKmode} are in
1422 @code{MODE_RANDOM}.
1423 @end table
1424
1425 @cindex machine mode wrapper classes
1426 @code{machmode.h} also defines various wrapper classes that combine a
1427 @code{machine_mode} with a static assertion that a particular
1428 condition holds. The classes are:
1429
1430 @table @code
1431 @findex scalar_int_mode
1432 @item scalar_int_mode
1433 A mode that has class @code{MODE_INT} or @code{MODE_PARTIAL_INT}.
1434
1435 @findex scalar_float_mode
1436 @item scalar_float_mode
1437 A mode that has class @code{MODE_FLOAT} or @code{MODE_DECIMAL_FLOAT}.
1438
1439 @findex scalar_mode
1440 @item scalar_mode
1441 A mode that holds a single numerical value. In practice this means
1442 that the mode is a @code{scalar_int_mode}, is a @code{scalar_float_mode},
1443 or has class @code{MODE_FRACT}, @code{MODE_UFRACT}, @code{MODE_ACCUM},
1444 @code{MODE_UACCUM} or @code{MODE_POINTER_BOUNDS}.
1445
1446 @findex complex_mode
1447 @item complex_mode
1448 A mode that has class @code{MODE_COMPLEX_INT} or @code{MODE_COMPLEX_FLOAT}.
1449
1450 @findex fixed_size_mode
1451 @item fixed_size_mode
1452 A mode whose size is known at compile time.
1453 @end table
1454
1455 Named modes use the most constrained of the available wrapper classes,
1456 if one exists, otherwise they use @code{machine_mode}. For example,
1457 @code{QImode} is a @code{scalar_int_mode}, @code{SFmode} is a
1458 @code{scalar_float_mode} and @code{BLKmode} is a plain
1459 @code{machine_mode}. It is possible to refer to any mode as a raw
1460 @code{machine_mode} by adding the @code{E_} prefix, where @code{E}
1461 stands for ``enumeration''. For example, the raw @code{machine_mode}
1462 names of the modes just mentioned are @code{E_QImode}, @code{E_SFmode}
1463 and @code{E_BLKmode} respectively.
1464
1465 The wrapper classes implicitly convert to @code{machine_mode} and to any
1466 wrapper class that represents a more general condition; for example
1467 @code{scalar_int_mode} and @code{scalar_float_mode} both convert
1468 to @code{scalar_mode} and all three convert to @code{fixed_size_mode}.
1469 The classes act like @code{machine_mode}s that accept only certain
1470 named modes.
1471
1472 @findex opt_mode
1473 @file{machmode.h} also defines a template class @code{opt_mode<@var{T}>}
1474 that holds a @code{T} or nothing, where @code{T} can be either
1475 @code{machine_mode} or one of the wrapper classes above. The main
1476 operations on an @code{opt_mode<@var{T}>} @var{x} are as follows:
1477
1478 @table @samp
1479 @item @var{x}.exists ()
1480 Return true if @var{x} holds a mode rather than nothing.
1481
1482 @item @var{x}.exists (&@var{y})
1483 Return true if @var{x} holds a mode rather than nothing, storing the
1484 mode in @var{y} if so. @var{y} must be assignment-compatible with @var{T}.
1485
1486 @item @var{x}.require ()
1487 Assert that @var{x} holds a mode rather than nothing and return that mode.
1488
1489 @item @var{x} = @var{y}
1490 Set @var{x} to @var{y}, where @var{y} is a @var{T} or implicitly converts
1491 to a @var{T}.
1492 @end table
1493
1494 The default constructor sets an @code{opt_mode<@var{T}>} to nothing.
1495 There is also a constructor that takes an initial value of type @var{T}.
1496
1497 It is possible to use the @file{is-a.h} accessors on a @code{machine_mode}
1498 or machine mode wrapper @var{x}:
1499
1500 @table @samp
1501 @findex is_a
1502 @item is_a <@var{T}> (@var{x})
1503 Return true if @var{x} meets the conditions for wrapper class @var{T}.
1504
1505 @item is_a <@var{T}> (@var{x}, &@var{y})
1506 Return true if @var{x} meets the conditions for wrapper class @var{T},
1507 storing it in @var{y} if so. @var{y} must be assignment-compatible with
1508 @var{T}.
1509
1510 @item as_a <@var{T}> (@var{x})
1511 Assert that @var{x} meets the conditions for wrapper class @var{T}
1512 and return it as a @var{T}.
1513
1514 @item dyn_cast <@var{T}> (@var{x})
1515 Return an @code{opt_mode<@var{T}>} that holds @var{x} if @var{x} meets
1516 the conditions for wrapper class @var{T} and that holds nothing otherwise.
1517 @end table
1518
1519 The purpose of these wrapper classes is to give stronger static type
1520 checking. For example, if a function takes a @code{scalar_int_mode},
1521 a caller that has a general @code{machine_mode} must either check or
1522 assert that the code is indeed a scalar integer first, using one of
1523 the functions above.
1524
1525 The wrapper classes are normal C++ classes, with user-defined
1526 constructors. Sometimes it is useful to have a POD version of
1527 the same type, particularly if the type appears in a @code{union}.
1528 The template class @code{pod_mode<@var{T}>} provides a POD version
1529 of wrapper class @var{T}. It is assignment-compatible with @var{T}
1530 and implicitly converts to both @code{machine_mode} and @var{T}.
1531
1532 Here are some C macros that relate to machine modes:
1533
1534 @table @code
1535 @findex GET_MODE
1536 @item GET_MODE (@var{x})
1537 Returns the machine mode of the RTX @var{x}.
1538
1539 @findex PUT_MODE
1540 @item PUT_MODE (@var{x}, @var{newmode})
1541 Alters the machine mode of the RTX @var{x} to be @var{newmode}.
1542
1543 @findex NUM_MACHINE_MODES
1544 @item NUM_MACHINE_MODES
1545 Stands for the number of machine modes available on the target
1546 machine. This is one greater than the largest numeric value of any
1547 machine mode.
1548
1549 @findex GET_MODE_NAME
1550 @item GET_MODE_NAME (@var{m})
1551 Returns the name of mode @var{m} as a string.
1552
1553 @findex GET_MODE_CLASS
1554 @item GET_MODE_CLASS (@var{m})
1555 Returns the mode class of mode @var{m}.
1556
1557 @findex GET_MODE_WIDER_MODE
1558 @item GET_MODE_WIDER_MODE (@var{m})
1559 Returns the next wider natural mode. For example, the expression
1560 @code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}.
1561
1562 @findex GET_MODE_SIZE
1563 @item GET_MODE_SIZE (@var{m})
1564 Returns the size in bytes of a datum of mode @var{m}.
1565
1566 @findex GET_MODE_BITSIZE
1567 @item GET_MODE_BITSIZE (@var{m})
1568 Returns the size in bits of a datum of mode @var{m}.
1569
1570 @findex GET_MODE_IBIT
1571 @item GET_MODE_IBIT (@var{m})
1572 Returns the number of integral bits of a datum of fixed-point mode @var{m}.
1573
1574 @findex GET_MODE_FBIT
1575 @item GET_MODE_FBIT (@var{m})
1576 Returns the number of fractional bits of a datum of fixed-point mode @var{m}.
1577
1578 @findex GET_MODE_MASK
1579 @item GET_MODE_MASK (@var{m})
1580 Returns a bitmask containing 1 for all bits in a word that fit within
1581 mode @var{m}. This macro can only be used for modes whose bitsize is
1582 less than or equal to @code{HOST_BITS_PER_INT}.
1583
1584 @findex GET_MODE_ALIGNMENT
1585 @item GET_MODE_ALIGNMENT (@var{m})
1586 Return the required alignment, in bits, for an object of mode @var{m}.
1587
1588 @findex GET_MODE_INNER
1589 @item GET_MODE_INNER (@var{m})
1590 Returns the mode of the basic parts of mode @var{m}. For vector modes
1591 this is the mode of the vector elements. For complex modes it is the
1592 mode of the real and imaginary parts. For other modes it is mode @var{m}
1593 itself.
1594
1595 @findex GET_MODE_UNIT_SIZE
1596 @item GET_MODE_UNIT_SIZE (@var{m})
1597 Returns the size in bytes of the subunits of a datum of mode @var{m}.
1598 This is the same as @code{GET_MODE_SIZE} except in the case of complex
1599 modes. For them, the unit size is the size of the real or imaginary
1600 part.
1601
1602 @findex GET_MODE_NUNITS
1603 @item GET_MODE_NUNITS (@var{m})
1604 Returns the number of units contained in a mode, i.e.,
1605 @code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}.
1606
1607 @findex GET_CLASS_NARROWEST_MODE
1608 @item GET_CLASS_NARROWEST_MODE (@var{c})
1609 Returns the narrowest mode in mode class @var{c}.
1610 @end table
1611
1612 The following 3 variables are defined on every target. They can be
1613 used to allocate buffers that are guaranteed to be large enough to
1614 hold any value that can be represented on the target. The first two
1615 can be overridden by defining them in the target's mode.def file,
1616 however, the value must be a constant that can determined very early
1617 in the compilation process. The third symbol cannot be overridden.
1618
1619 @table @code
1620 @findex BITS_PER_UNIT
1621 @item BITS_PER_UNIT
1622 The number of bits in an addressable storage unit (byte). If you do
1623 not define this, the default is 8.
1624
1625 @findex MAX_BITSIZE_MODE_ANY_INT
1626 @item MAX_BITSIZE_MODE_ANY_INT
1627 The maximum bitsize of any mode that is used in integer math. This
1628 should be overridden by the target if it uses large integers as
1629 containers for larger vectors but otherwise never uses the contents to
1630 compute integer values.
1631
1632 @findex MAX_BITSIZE_MODE_ANY_MODE
1633 @item MAX_BITSIZE_MODE_ANY_MODE
1634 The bitsize of the largest mode on the target. The default value is
1635 the largest mode size given in the mode definition file, which is
1636 always correct for targets whose modes have a fixed size. Targets
1637 that might increase the size of a mode beyond this default should define
1638 @code{MAX_BITSIZE_MODE_ANY_MODE} to the actual upper limit in
1639 @file{@var{machine}-modes.def}.
1640 @end table
1641
1642 @findex byte_mode
1643 @findex word_mode
1644 The global variables @code{byte_mode} and @code{word_mode} contain modes
1645 whose classes are @code{MODE_INT} and whose bitsizes are either
1646 @code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit
1647 machines, these are @code{QImode} and @code{SImode}, respectively.
1648
1649 @node Constants
1650 @section Constant Expression Types
1651 @cindex RTL constants
1652 @cindex RTL constant expression types
1653
1654 The simplest RTL expressions are those that represent constant values.
1655
1656 @table @code
1657 @findex const_int
1658 @item (const_int @var{i})
1659 This type of expression represents the integer value @var{i}. @var{i}
1660 is customarily accessed with the macro @code{INTVAL} as in
1661 @code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}.
1662
1663 Constants generated for modes with fewer bits than in
1664 @code{HOST_WIDE_INT} must be sign extended to full width (e.g., with
1665 @code{gen_int_mode}). For constants for modes with more bits than in
1666 @code{HOST_WIDE_INT} the implied high order bits of that constant are
1667 copies of the top bit. Note however that values are neither
1668 inherently signed nor inherently unsigned; where necessary, signedness
1669 is determined by the rtl operation instead.
1670
1671 @findex const0_rtx
1672 @findex const1_rtx
1673 @findex const2_rtx
1674 @findex constm1_rtx
1675 There is only one expression object for the integer value zero; it is
1676 the value of the variable @code{const0_rtx}. Likewise, the only
1677 expression for integer value one is found in @code{const1_rtx}, the only
1678 expression for integer value two is found in @code{const2_rtx}, and the
1679 only expression for integer value negative one is found in
1680 @code{constm1_rtx}. Any attempt to create an expression of code
1681 @code{const_int} and value zero, one, two or negative one will return
1682 @code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or
1683 @code{constm1_rtx} as appropriate.
1684
1685 @findex const_true_rtx
1686 Similarly, there is only one object for the integer whose value is
1687 @code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If
1688 @code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and
1689 @code{const1_rtx} will point to the same object. If
1690 @code{STORE_FLAG_VALUE} is @minus{}1, @code{const_true_rtx} and
1691 @code{constm1_rtx} will point to the same object.
1692
1693 @findex const_double
1694 @item (const_double:@var{m} @var{i0} @var{i1} @dots{})
1695 This represents either a floating-point constant of mode @var{m} or
1696 (on older ports that do not define
1697 @code{TARGET_SUPPORTS_WIDE_INT}) an integer constant too large to fit
1698 into @code{HOST_BITS_PER_WIDE_INT} bits but small enough to fit within
1699 twice that number of bits. In the latter case, @var{m} will be
1700 @code{VOIDmode}. For integral values constants for modes with more
1701 bits than twice the number in @code{HOST_WIDE_INT} the implied high
1702 order bits of that constant are copies of the top bit of
1703 @code{CONST_DOUBLE_HIGH}. Note however that integral values are
1704 neither inherently signed nor inherently unsigned; where necessary,
1705 signedness is determined by the rtl operation instead.
1706
1707 On more modern ports, @code{CONST_DOUBLE} only represents floating
1708 point values. New ports define @code{TARGET_SUPPORTS_WIDE_INT} to
1709 make this designation.
1710
1711 @findex CONST_DOUBLE_LOW
1712 If @var{m} is @code{VOIDmode}, the bits of the value are stored in
1713 @var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro
1714 @code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}.
1715
1716 If the constant is floating point (regardless of its precision), then
1717 the number of integers used to store the value depends on the size of
1718 @code{REAL_VALUE_TYPE} (@pxref{Floating Point}). The integers
1719 represent a floating point number, but not precisely in the target
1720 machine's or host machine's floating point format. To convert them to
1721 the precise bit pattern used by the target machine, use the macro
1722 @code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}).
1723
1724 @findex const_double_zero
1725 The host dependency for the number of integers used to store a double
1726 value makes it problematic for machine descriptions to use expressions
1727 of code @code{const_double} and therefore a syntactic alias has been
1728 provided:
1729
1730 @smallexample
1731 (const_double_zero:@var{m})
1732 @end smallexample
1733
1734 standing for:
1735
1736 @smallexample
1737 (const_double:@var{m} 0 0 @dots{})
1738 @end smallexample
1739
1740 for matching the floating-point value zero, possibly the only useful one.
1741
1742 @findex CONST_WIDE_INT
1743 @item (const_wide_int:@var{m} @var{nunits} @var{elt0} @dots{})
1744 This contains an array of @code{HOST_WIDE_INT}s that is large enough
1745 to hold any constant that can be represented on the target. This form
1746 of rtl is only used on targets that define
1747 @code{TARGET_SUPPORTS_WIDE_INT} to be nonzero and then
1748 @code{CONST_DOUBLE}s are only used to hold floating-point values. If
1749 the target leaves @code{TARGET_SUPPORTS_WIDE_INT} defined as 0,
1750 @code{CONST_WIDE_INT}s are not used and @code{CONST_DOUBLE}s are as
1751 they were before.
1752
1753 The values are stored in a compressed format. The higher-order
1754 0s or -1s are not represented if they are just the logical sign
1755 extension of the number that is represented.
1756
1757 @findex CONST_WIDE_INT_VEC
1758 @item CONST_WIDE_INT_VEC (@var{code})
1759 Returns the entire array of @code{HOST_WIDE_INT}s that are used to
1760 store the value. This macro should be rarely used.
1761
1762 @findex CONST_WIDE_INT_NUNITS
1763 @item CONST_WIDE_INT_NUNITS (@var{code})
1764 The number of @code{HOST_WIDE_INT}s used to represent the number.
1765 Note that this generally is smaller than the number of
1766 @code{HOST_WIDE_INT}s implied by the mode size.
1767
1768 @findex CONST_WIDE_INT_ELT
1769 @item CONST_WIDE_INT_ELT (@var{code},@var{i})
1770 Returns the @code{i}th element of the array. Element 0 is contains
1771 the low order bits of the constant.
1772
1773 @findex const_fixed
1774 @item (const_fixed:@var{m} @dots{})
1775 Represents a fixed-point constant of mode @var{m}.
1776 The operand is a data structure of type @code{struct fixed_value} and
1777 is accessed with the macro @code{CONST_FIXED_VALUE}. The high part of
1778 data is accessed with @code{CONST_FIXED_VALUE_HIGH}; the low part is
1779 accessed with @code{CONST_FIXED_VALUE_LOW}.
1780
1781 @findex const_poly_int
1782 @item (const_poly_int:@var{m} [@var{c0} @var{c1} @dots{}])
1783 Represents a @code{poly_int}-style polynomial integer with coefficients
1784 @var{c0}, @var{c1}, @dots{}. The coefficients are @code{wide_int}-based
1785 integers rather than rtxes. @code{CONST_POLY_INT_COEFFS} gives the
1786 values of individual coefficients (which is mostly only useful in
1787 low-level routines) and @code{const_poly_int_value} gives the full
1788 @code{poly_int} value.
1789
1790 @findex const_vector
1791 @item (const_vector:@var{m} [@var{x0} @var{x1} @dots{}])
1792 Represents a vector constant. The values in square brackets are
1793 elements of the vector, which are always @code{const_int},
1794 @code{const_wide_int}, @code{const_double} or @code{const_fixed}
1795 expressions.
1796
1797 Each vector constant @var{v} is treated as a specific instance of an
1798 arbitrary-length sequence that itself contains
1799 @samp{CONST_VECTOR_NPATTERNS (@var{v})} interleaved patterns. Each
1800 pattern has the form:
1801
1802 @smallexample
1803 @{ @var{base0}, @var{base1}, @var{base1} + @var{step}, @var{base1} + @var{step} * 2, @dots{} @}
1804 @end smallexample
1805
1806 The first three elements in each pattern are enough to determine the
1807 values of the other elements. However, if all @var{step}s are zero,
1808 only the first two elements are needed. If in addition each @var{base1}
1809 is equal to the corresponding @var{base0}, only the first element in
1810 each pattern is needed. The number of determining elements per pattern
1811 is given by @samp{CONST_VECTOR_NELTS_PER_PATTERN (@var{v})}.
1812
1813 For example, the constant:
1814
1815 @smallexample
1816 @{ 0, 1, 2, 6, 3, 8, 4, 10, 5, 12, 6, 14, 7, 16, 8, 18 @}
1817 @end smallexample
1818
1819 is interpreted as an interleaving of the sequences:
1820
1821 @smallexample
1822 @{ 0, 2, 3, 4, 5, 6, 7, 8 @}
1823 @{ 1, 6, 8, 10, 12, 14, 16, 18 @}
1824 @end smallexample
1825
1826 where the sequences are represented by the following patterns:
1827
1828 @smallexample
1829 @var{base0} == 0, @var{base1} == 2, @var{step} == 1
1830 @var{base0} == 1, @var{base1} == 6, @var{step} == 2
1831 @end smallexample
1832
1833 In this case:
1834
1835 @smallexample
1836 CONST_VECTOR_NPATTERNS (@var{v}) == 2
1837 CONST_VECTOR_NELTS_PER_PATTERN (@var{v}) == 3
1838 @end smallexample
1839
1840 Thus the first 6 elements (@samp{@{ 0, 1, 2, 6, 3, 8 @}}) are enough
1841 to determine the whole sequence; we refer to them as the ``encoded''
1842 elements. They are the only elements present in the square brackets
1843 for variable-length @code{const_vector}s (i.e.@: for
1844 @code{const_vector}s whose mode @var{m} has a variable number of
1845 elements). However, as a convenience to code that needs to handle
1846 both @code{const_vector}s and @code{parallel}s, all elements are
1847 present in the square brackets for fixed-length @code{const_vector}s;
1848 the encoding scheme simply reduces the amount of work involved in
1849 processing constants that follow a regular pattern.
1850
1851 Sometimes this scheme can create two possible encodings of the same
1852 vector. For example @{ 0, 1 @} could be seen as two patterns with
1853 one element each or one pattern with two elements (@var{base0} and
1854 @var{base1}). The canonical encoding is always the one with the
1855 fewest patterns or (if both encodings have the same number of
1856 patterns) the one with the fewest encoded elements.
1857
1858 @samp{const_vector_encoding_nelts (@var{v})} gives the total number of
1859 encoded elements in @var{v}, which is 6 in the example above.
1860 @code{CONST_VECTOR_ENCODED_ELT (@var{v}, @var{i})} accesses the value
1861 of encoded element @var{i}.
1862
1863 @samp{CONST_VECTOR_DUPLICATE_P (@var{v})} is true if @var{v} simply contains
1864 repeated instances of @samp{CONST_VECTOR_NPATTERNS (@var{v})} values. This is
1865 a shorthand for testing @samp{CONST_VECTOR_NELTS_PER_PATTERN (@var{v}) == 1}.
1866
1867 @samp{CONST_VECTOR_STEPPED_P (@var{v})} is true if at least one
1868 pattern in @var{v} has a nonzero step. This is a shorthand for
1869 testing @samp{CONST_VECTOR_NELTS_PER_PATTERN (@var{v}) == 3}.
1870
1871 @code{CONST_VECTOR_NUNITS (@var{v})} gives the total number of elements
1872 in @var{v}; it is a shorthand for getting the number of units in
1873 @samp{GET_MODE (@var{v})}.
1874
1875 The utility function @code{const_vector_elt} gives the value of an
1876 arbitrary element as an @code{rtx}. @code{const_vector_int_elt} gives
1877 the same value as a @code{wide_int}.
1878
1879 @findex const_string
1880 @item (const_string @var{str})
1881 Represents a constant string with value @var{str}. Currently this is
1882 used only for insn attributes (@pxref{Insn Attributes}) since constant
1883 strings in C are placed in memory.
1884
1885 @findex symbol_ref
1886 @item (symbol_ref:@var{mode} @var{symbol})
1887 Represents the value of an assembler label for data. @var{symbol} is
1888 a string that describes the name of the assembler label. If it starts
1889 with a @samp{*}, the label is the rest of @var{symbol} not including
1890 the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed
1891 with @samp{_}.
1892
1893 The @code{symbol_ref} contains a mode, which is usually @code{Pmode}.
1894 Usually that is the only mode for which a symbol is directly valid.
1895
1896 @findex label_ref
1897 @item (label_ref:@var{mode} @var{label})
1898 Represents the value of an assembler label for code. It contains one
1899 operand, an expression, which must be a @code{code_label} or a @code{note}
1900 of type @code{NOTE_INSN_DELETED_LABEL} that appears in the instruction
1901 sequence to identify the place where the label should go.
1902
1903 The reason for using a distinct expression type for code label
1904 references is so that jump optimization can distinguish them.
1905
1906 The @code{label_ref} contains a mode, which is usually @code{Pmode}.
1907 Usually that is the only mode for which a label is directly valid.
1908
1909 @findex const
1910 @item (const:@var{m} @var{exp})
1911 Represents a constant that is the result of an assembly-time
1912 arithmetic computation. The operand, @var{exp}, contains only
1913 @code{const_int}, @code{symbol_ref}, @code{label_ref} or @code{unspec}
1914 expressions, combined with @code{plus} and @code{minus}. Any such
1915 @code{unspec}s are target-specific and typically represent some form
1916 of relocation operator. @var{m} should be a valid address mode.
1917
1918 @findex high
1919 @item (high:@var{m} @var{exp})
1920 Represents the high-order bits of @var{exp}.
1921 The number of bits is machine-dependent and is
1922 normally the number of bits specified in an instruction that initializes
1923 the high order bits of a register. It is used with @code{lo_sum} to
1924 represent the typical two-instruction sequence used in RISC machines to
1925 reference large immediate values and/or link-time constants such
1926 as global memory addresses. In the latter case, @var{m} is @code{Pmode}
1927 and @var{exp} is usually a constant expression involving @code{symbol_ref}.
1928 @end table
1929
1930 @findex CONST0_RTX
1931 @findex CONST1_RTX
1932 @findex CONST2_RTX
1933 The macro @code{CONST0_RTX (@var{mode})} refers to an expression with
1934 value 0 in mode @var{mode}. If mode @var{mode} is of mode class
1935 @code{MODE_INT}, it returns @code{const0_rtx}. If mode @var{mode} is of
1936 mode class @code{MODE_FLOAT}, it returns a @code{CONST_DOUBLE}
1937 expression in mode @var{mode}. Otherwise, it returns a
1938 @code{CONST_VECTOR} expression in mode @var{mode}. Similarly, the macro
1939 @code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in
1940 mode @var{mode} and similarly for @code{CONST2_RTX}. The
1941 @code{CONST1_RTX} and @code{CONST2_RTX} macros are undefined
1942 for vector modes.
1943
1944 @node Regs and Memory
1945 @section Registers and Memory
1946 @cindex RTL register expressions
1947 @cindex RTL memory expressions
1948
1949 Here are the RTL expression types for describing access to machine
1950 registers and to main memory.
1951
1952 @table @code
1953 @findex reg
1954 @cindex hard registers
1955 @cindex pseudo registers
1956 @item (reg:@var{m} @var{n})
1957 For small values of the integer @var{n} (those that are less than
1958 @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
1959 register number @var{n}: a @dfn{hard register}. For larger values of
1960 @var{n}, it stands for a temporary value or @dfn{pseudo register}.
1961 The compiler's strategy is to generate code assuming an unlimited
1962 number of such pseudo registers, and later convert them into hard
1963 registers or into memory references.
1964
1965 @var{m} is the machine mode of the reference. It is necessary because
1966 machines can generally refer to each register in more than one mode.
1967 For example, a register may contain a full word but there may be
1968 instructions to refer to it as a half word or as a single byte, as
1969 well as instructions to refer to it as a floating point number of
1970 various precisions.
1971
1972 Even for a register that the machine can access in only one mode,
1973 the mode must always be specified.
1974
1975 The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
1976 description, since the number of hard registers on the machine is an
1977 invariant characteristic of the machine. Note, however, that not
1978 all of the machine registers must be general registers. All the
1979 machine registers that can be used for storage of data are given
1980 hard register numbers, even those that can be used only in certain
1981 instructions or can hold only certain types of data.
1982
1983 A hard register may be accessed in various modes throughout one
1984 function, but each pseudo register is given a natural mode
1985 and is accessed only in that mode. When it is necessary to describe
1986 an access to a pseudo register using a nonnatural mode, a @code{subreg}
1987 expression is used.
1988
1989 A @code{reg} expression with a machine mode that specifies more than
1990 one word of data may actually stand for several consecutive registers.
1991 If in addition the register number specifies a hardware register, then
1992 it actually represents several consecutive hardware registers starting
1993 with the specified one.
1994
1995 Each pseudo register number used in a function's RTL code is
1996 represented by a unique @code{reg} expression.
1997
1998 @findex FIRST_VIRTUAL_REGISTER
1999 @findex LAST_VIRTUAL_REGISTER
2000 Some pseudo register numbers, those within the range of
2001 @code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only
2002 appear during the RTL generation phase and are eliminated before the
2003 optimization phases. These represent locations in the stack frame that
2004 cannot be determined until RTL generation for the function has been
2005 completed. The following virtual register numbers are defined:
2006
2007 @table @code
2008 @findex VIRTUAL_INCOMING_ARGS_REGNUM
2009 @item VIRTUAL_INCOMING_ARGS_REGNUM
2010 This points to the first word of the incoming arguments passed on the
2011 stack. Normally these arguments are placed there by the caller, but the
2012 callee may have pushed some arguments that were previously passed in
2013 registers.
2014
2015 @cindex @code{FIRST_PARM_OFFSET} and virtual registers
2016 @cindex @code{ARG_POINTER_REGNUM} and virtual registers
2017 When RTL generation is complete, this virtual register is replaced
2018 by the sum of the register given by @code{ARG_POINTER_REGNUM} and the
2019 value of @code{FIRST_PARM_OFFSET}.
2020
2021 @findex VIRTUAL_STACK_VARS_REGNUM
2022 @cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers
2023 @item VIRTUAL_STACK_VARS_REGNUM
2024 If @code{FRAME_GROWS_DOWNWARD} is defined to a nonzero value, this points
2025 to immediately above the first variable on the stack. Otherwise, it points
2026 to the first variable on the stack.
2027
2028 @cindex @code{TARGET_STARTING_FRAME_OFFSET} and virtual registers
2029 @cindex @code{FRAME_POINTER_REGNUM} and virtual registers
2030 @code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the
2031 register given by @code{FRAME_POINTER_REGNUM} and the value
2032 @code{TARGET_STARTING_FRAME_OFFSET}.
2033
2034 @findex VIRTUAL_STACK_DYNAMIC_REGNUM
2035 @item VIRTUAL_STACK_DYNAMIC_REGNUM
2036 This points to the location of dynamically allocated memory on the stack
2037 immediately after the stack pointer has been adjusted by the amount of
2038 memory desired.
2039
2040 @cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers
2041 @cindex @code{STACK_POINTER_REGNUM} and virtual registers
2042 This virtual register is replaced by the sum of the register given by
2043 @code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}.
2044
2045 @findex VIRTUAL_OUTGOING_ARGS_REGNUM
2046 @item VIRTUAL_OUTGOING_ARGS_REGNUM
2047 This points to the location in the stack at which outgoing arguments
2048 should be written when the stack is pre-pushed (arguments pushed using
2049 push insns should always use @code{STACK_POINTER_REGNUM}).
2050
2051 @cindex @code{STACK_POINTER_OFFSET} and virtual registers
2052 This virtual register is replaced by the sum of the register given by
2053 @code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}.
2054 @end table
2055
2056 @findex subreg
2057 @item (subreg:@var{m1} @var{reg:m2} @var{bytenum})
2058
2059 @code{subreg} expressions are used to refer to a register in a machine
2060 mode other than its natural one, or to refer to one register of
2061 a multi-part @code{reg} that actually refers to several registers.
2062
2063 Each pseudo register has a natural mode. If it is necessary to
2064 operate on it in a different mode, the register must be
2065 enclosed in a @code{subreg}.
2066
2067 There are currently three supported types for the first operand of a
2068 @code{subreg}:
2069 @itemize
2070 @item pseudo registers
2071 This is the most common case. Most @code{subreg}s have pseudo
2072 @code{reg}s as their first operand.
2073
2074 @item mem
2075 @code{subreg}s of @code{mem} were common in earlier versions of GCC and
2076 are still supported. During the reload pass these are replaced by plain
2077 @code{mem}s. On machines that do not do instruction scheduling, use of
2078 @code{subreg}s of @code{mem} are still used, but this is no longer
2079 recommended. Such @code{subreg}s are considered to be
2080 @code{register_operand}s rather than @code{memory_operand}s before and
2081 during reload. Because of this, the scheduling passes cannot properly
2082 schedule instructions with @code{subreg}s of @code{mem}, so for machines
2083 that do scheduling, @code{subreg}s of @code{mem} should never be used.
2084 To support this, the combine and recog passes have explicit code to
2085 inhibit the creation of @code{subreg}s of @code{mem} when
2086 @code{INSN_SCHEDULING} is defined.
2087
2088 The use of @code{subreg}s of @code{mem} after the reload pass is an area
2089 that is not well understood and should be avoided. There is still some
2090 code in the compiler to support this, but this code has possibly rotted.
2091 This use of @code{subreg}s is discouraged and will most likely not be
2092 supported in the future.
2093
2094 @item hard registers
2095 It is seldom necessary to wrap hard registers in @code{subreg}s; such
2096 registers would normally reduce to a single @code{reg} rtx. This use of
2097 @code{subreg}s is discouraged and may not be supported in the future.
2098
2099 @end itemize
2100
2101 @code{subreg}s of @code{subreg}s are not supported. Using
2102 @code{simplify_gen_subreg} is the recommended way to avoid this problem.
2103
2104 @code{subreg}s come in two distinct flavors, each having its own
2105 usage and rules:
2106
2107 @table @asis
2108 @item Paradoxical subregs
2109 When @var{m1} is strictly wider than @var{m2}, the @code{subreg}
2110 expression is called @dfn{paradoxical}. The canonical test for this
2111 class of @code{subreg} is:
2112
2113 @smallexample
2114 paradoxical_subreg_p (@var{m1}, @var{m2})
2115 @end smallexample
2116
2117 Paradoxical @code{subreg}s can be used as both lvalues and rvalues.
2118 When used as an lvalue, the low-order bits of the source value
2119 are stored in @var{reg} and the high-order bits are discarded.
2120 When used as an rvalue, the low-order bits of the @code{subreg} are
2121 taken from @var{reg} while the high-order bits may or may not be
2122 defined.
2123
2124 The high-order bits of rvalues are defined in the following circumstances:
2125
2126 @itemize
2127 @item @code{subreg}s of @code{mem}
2128 When @var{m2} is smaller than a word, the macro @code{LOAD_EXTEND_OP},
2129 can control how the high-order bits are defined.
2130
2131 @item @code{subreg} of @code{reg}s
2132 The upper bits are defined when @code{SUBREG_PROMOTED_VAR_P} is true.
2133 @code{SUBREG_PROMOTED_UNSIGNED_P} describes what the upper bits hold.
2134 Such subregs usually represent local variables, register variables
2135 and parameter pseudo variables that have been promoted to a wider mode.
2136
2137 @end itemize
2138
2139 @var{bytenum} is always zero for a paradoxical @code{subreg}, even on
2140 big-endian targets.
2141
2142 For example, the paradoxical @code{subreg}:
2143
2144 @smallexample
2145 (set (subreg:SI (reg:HI @var{x}) 0) @var{y})
2146 @end smallexample
2147
2148 stores the lower 2 bytes of @var{y} in @var{x} and discards the upper
2149 2 bytes. A subsequent:
2150
2151 @smallexample
2152 (set @var{z} (subreg:SI (reg:HI @var{x}) 0))
2153 @end smallexample
2154
2155 would set the lower two bytes of @var{z} to @var{y} and set the upper
2156 two bytes to an unknown value assuming @code{SUBREG_PROMOTED_VAR_P} is
2157 false.
2158
2159 @item Normal subregs
2160 When @var{m1} is at least as narrow as @var{m2} the @code{subreg}
2161 expression is called @dfn{normal}.
2162
2163 @findex REGMODE_NATURAL_SIZE
2164 Normal @code{subreg}s restrict consideration to certain bits of
2165 @var{reg}. For this purpose, @var{reg} is divided into
2166 individually-addressable blocks in which each block has:
2167
2168 @smallexample
2169 REGMODE_NATURAL_SIZE (@var{m2})
2170 @end smallexample
2171
2172 bytes. Usually the value is @code{UNITS_PER_WORD}; that is,
2173 most targets usually treat each word of a register as being
2174 independently addressable.
2175
2176 There are two types of normal @code{subreg}. If @var{m1} is known
2177 to be no bigger than a block, the @code{subreg} refers to the
2178 least-significant part (or @dfn{lowpart}) of one block of @var{reg}.
2179 If @var{m1} is known to be larger than a block, the @code{subreg} refers
2180 to two or more complete blocks.
2181
2182 When used as an lvalue, @code{subreg} is a block-based accessor.
2183 Storing to a @code{subreg} modifies all the blocks of @var{reg} that
2184 overlap the @code{subreg}, but it leaves the other blocks of @var{reg}
2185 alone.
2186
2187 When storing to a normal @code{subreg} that is smaller than a block,
2188 the other bits of the referenced block are usually left in an undefined
2189 state. This laxity makes it easier to generate efficient code for
2190 such instructions. To represent an instruction that preserves all the
2191 bits outside of those in the @code{subreg}, use @code{strict_low_part}
2192 or @code{zero_extract} around the @code{subreg}.
2193
2194 @var{bytenum} must identify the offset of the first byte of the
2195 @code{subreg} from the start of @var{reg}, assuming that @var{reg} is
2196 laid out in memory order. The memory order of bytes is defined by
2197 two target macros, @code{WORDS_BIG_ENDIAN} and @code{BYTES_BIG_ENDIAN}:
2198
2199 @itemize
2200 @cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
2201 @item
2202 @code{WORDS_BIG_ENDIAN}, if set to 1, says that byte number zero is
2203 part of the most significant word; otherwise, it is part of the least
2204 significant word.
2205
2206 @cindex @code{BYTES_BIG_ENDIAN}, effect on @code{subreg}
2207 @item
2208 @code{BYTES_BIG_ENDIAN}, if set to 1, says that byte number zero is
2209 the most significant byte within a word; otherwise, it is the least
2210 significant byte within a word.
2211 @end itemize
2212
2213 @cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg}
2214 On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with
2215 @code{WORDS_BIG_ENDIAN}. However, most parts of the compiler treat
2216 floating point values as if they had the same endianness as integer
2217 values. This works because they handle them solely as a collection of
2218 integer values, with no particular numerical value. Only real.cc and
2219 the runtime libraries care about @code{FLOAT_WORDS_BIG_ENDIAN}.
2220
2221 Thus,
2222
2223 @smallexample
2224 (subreg:HI (reg:SI @var{x}) 2)
2225 @end smallexample
2226
2227 on a @code{BYTES_BIG_ENDIAN}, @samp{UNITS_PER_WORD == 4} target is the same as
2228
2229 @smallexample
2230 (subreg:HI (reg:SI @var{x}) 0)
2231 @end smallexample
2232
2233 on a little-endian, @samp{UNITS_PER_WORD == 4} target. Both
2234 @code{subreg}s access the lower two bytes of register @var{x}.
2235
2236 Note that the byte offset is a polynomial integer; it may not be a
2237 compile-time constant on targets with variable-sized modes. However,
2238 the restrictions above mean that there are only a certain set of
2239 acceptable offsets for a given combination of @var{m1} and @var{m2}.
2240 The compiler can always tell which blocks a valid subreg occupies, and
2241 whether the subreg is a lowpart of a block.
2242
2243 @end table
2244
2245 A @code{MODE_PARTIAL_INT} mode behaves as if it were as wide as the
2246 corresponding @code{MODE_INT} mode, except that it has a number of
2247 undefined bits, which are determined by the precision of the
2248 mode.
2249
2250 For example, on a little-endian target which defines @code{PSImode}
2251 to have a precision of 20 bits:
2252
2253 @smallexample
2254 (subreg:PSI (reg:SI 0) 0)
2255 @end smallexample
2256
2257 accesses the low 20 bits of @samp{(reg:SI 0)}.
2258
2259 @findex REGMODE_NATURAL_SIZE
2260 Continuing with a @code{PSImode} precision of 20 bits, if we assume
2261 @samp{REGMODE_NATURAL_SIZE (DImode) <= 4},
2262 then the following two @code{subreg}s:
2263
2264 @smallexample
2265 (subreg:PSI (reg:DI 0) 0)
2266 (subreg:PSI (reg:DI 0) 4)
2267 @end smallexample
2268
2269 represent accesses to the low 20 bits of the two halves of
2270 @samp{(reg:DI 0)}.
2271
2272 If @samp{REGMODE_NATURAL_SIZE (PSImode) <= 2} then these two @code{subreg}s:
2273
2274 @smallexample
2275 (subreg:HI (reg:PSI 0) 0)
2276 (subreg:HI (reg:PSI 0) 2)
2277 @end smallexample
2278
2279 represent independent 2-byte accesses that together span the whole
2280 of @samp{(reg:PSI 0)}. Storing to the first @code{subreg} does not
2281 affect the value of the second, and vice versa, so the assignment:
2282
2283 @smallexample
2284 (set (subreg:HI (reg:PSI 0) 0) (reg:HI 4))
2285 @end smallexample
2286
2287 sets the low 16 bits of @samp{(reg:PSI 0)} to @samp{(reg:HI 4)}, and
2288 the high 4 defined bits of @samp{(reg:PSI 0)} retain their
2289 original value. The behavior here is the same as for
2290 normal @code{subreg}s, when there are no
2291 @code{MODE_PARTIAL_INT} modes involved.
2292
2293 @cindex @code{TARGET_CAN_CHANGE_MODE_CLASS} and subreg semantics
2294 The rules above apply to both pseudo @var{reg}s and hard @var{reg}s.
2295 If the semantics are not correct for particular combinations of
2296 @var{m1}, @var{m2} and hard @var{reg}, the target-specific code
2297 must ensure that those combinations are never used. For example:
2298
2299 @smallexample
2300 TARGET_CAN_CHANGE_MODE_CLASS (@var{m2}, @var{m1}, @var{class})
2301 @end smallexample
2302
2303 must be false for every class @var{class} that includes @var{reg}.
2304
2305 GCC must be able to determine at compile time whether a subreg is
2306 paradoxical, whether it occupies a whole number of blocks, or whether
2307 it is a lowpart of a block. This means that certain combinations of
2308 variable-sized mode are not permitted. For example, if @var{m2}
2309 holds @var{n} @code{SI} values, where @var{n} is greater than zero,
2310 it is not possible to form a @code{DI} @code{subreg} of it; such a
2311 @code{subreg} would be paradoxical when @var{n} is 1 but not when
2312 @var{n} is greater than 1.
2313
2314 @findex SUBREG_REG
2315 @findex SUBREG_BYTE
2316 The first operand of a @code{subreg} expression is customarily accessed
2317 with the @code{SUBREG_REG} macro and the second operand is customarily
2318 accessed with the @code{SUBREG_BYTE} macro.
2319
2320 It has been several years since a platform in which
2321 @code{BYTES_BIG_ENDIAN} not equal to @code{WORDS_BIG_ENDIAN} has
2322 been tested. Anyone wishing to support such a platform in the future
2323 may be confronted with code rot.
2324
2325 @findex scratch
2326 @cindex scratch operands
2327 @item (scratch:@var{m})
2328 This represents a scratch register that will be required for the
2329 execution of a single instruction and not used subsequently. It is
2330 converted into a @code{reg} by either the local register allocator or
2331 the reload pass.
2332
2333 @code{scratch} is usually present inside a @code{clobber} operation
2334 (@pxref{Side Effects}).
2335
2336 On some machines, the condition code register is given a register number
2337 and a @code{reg} is used.
2338 Other machines store condition codes in general
2339 registers; in such cases a pseudo register should be used.
2340
2341 Some machines, such as the SPARC and RS/6000, have two sets of
2342 arithmetic instructions, one that sets and one that does not set the
2343 condition code. This is best handled by normally generating the
2344 instruction that does not set the condition code, and making a pattern
2345 that both performs the arithmetic and sets the condition code register.
2346 For examples, search for @samp{addcc} and @samp{andcc} in @file{sparc.md}.
2347
2348 @findex pc
2349 @cindex program counter
2350 @item (pc)
2351 This represents the machine's program counter. It has no operands and
2352 may not have a machine mode. @code{(pc)} may be validly used only in
2353 certain specific contexts in jump instructions.
2354
2355 @findex pc_rtx
2356 There is only one expression object of code @code{pc}; it is the value
2357 of the variable @code{pc_rtx}. Any attempt to create an expression of
2358 code @code{pc} will return @code{pc_rtx}.
2359
2360 All instructions that do not jump alter the program counter implicitly
2361 by incrementing it, but there is no need to mention this in the RTL@.
2362
2363 @findex mem
2364 @item (mem:@var{m} @var{addr} @var{alias})
2365 This RTX represents a reference to main memory at an address
2366 represented by the expression @var{addr}. @var{m} specifies how large
2367 a unit of memory is accessed. @var{alias} specifies an alias set for the
2368 reference. In general two items are in different alias sets if they cannot
2369 reference the same memory address.
2370
2371 The construct @code{(mem:BLK (scratch))} is considered to alias all
2372 other memories. Thus it may be used as a memory barrier in epilogue
2373 stack deallocation patterns.
2374
2375 @findex concat
2376 @item (concat@var{m} @var{rtx} @var{rtx})
2377 This RTX represents the concatenation of two other RTXs. This is used
2378 for complex values. It should only appear in the RTL attached to
2379 declarations and during RTL generation. It should not appear in the
2380 ordinary insn chain.
2381
2382 @findex concatn
2383 @item (concatn@var{m} [@var{rtx} @dots{}])
2384 This RTX represents the concatenation of all the @var{rtx} to make a
2385 single value. Like @code{concat}, this should only appear in
2386 declarations, and not in the insn chain.
2387 @end table
2388
2389 @node Arithmetic
2390 @section RTL Expressions for Arithmetic
2391 @cindex arithmetic, in RTL
2392 @cindex math, in RTL
2393 @cindex RTL expressions for arithmetic
2394
2395 Unless otherwise specified, all the operands of arithmetic expressions
2396 must be valid for mode @var{m}. An operand is valid for mode @var{m}
2397 if it has mode @var{m}, or if it is a @code{const_int} or
2398 @code{const_double} and @var{m} is a mode of class @code{MODE_INT}.
2399
2400 For commutative binary operations, constants should be placed in the
2401 second operand.
2402
2403 @table @code
2404 @findex plus
2405 @findex ss_plus
2406 @findex us_plus
2407 @cindex RTL sum
2408 @cindex RTL addition
2409 @cindex RTL addition with signed saturation
2410 @cindex RTL addition with unsigned saturation
2411 @item (plus:@var{m} @var{x} @var{y})
2412 @itemx (ss_plus:@var{m} @var{x} @var{y})
2413 @itemx (us_plus:@var{m} @var{x} @var{y})
2414
2415 These three expressions all represent the sum of the values
2416 represented by @var{x} and @var{y} carried out in machine mode
2417 @var{m}. They differ in their behavior on overflow of integer modes.
2418 @code{plus} wraps round modulo the width of @var{m}; @code{ss_plus}
2419 saturates at the maximum signed value representable in @var{m};
2420 @code{us_plus} saturates at the maximum unsigned value.
2421
2422 @c ??? What happens on overflow of floating point modes?
2423
2424 @findex lo_sum
2425 @item (lo_sum:@var{m} @var{x} @var{y})
2426
2427 This expression represents the sum of @var{x} and the low-order bits
2428 of @var{y}. It is used with @code{high} (@pxref{Constants}) to
2429 represent the typical two-instruction sequence used in RISC machines to
2430 reference large immediate values and/or link-time constants such
2431 as global memory addresses. In the latter case, @var{m} is @code{Pmode}
2432 and @var{y} is usually a constant expression involving @code{symbol_ref}.
2433
2434 The number of low order bits is machine-dependent but is
2435 normally the number of bits in mode @var{m} minus the number of
2436 bits set by @code{high}.
2437
2438 @findex minus
2439 @findex ss_minus
2440 @findex us_minus
2441 @cindex RTL difference
2442 @cindex RTL subtraction
2443 @cindex RTL subtraction with signed saturation
2444 @cindex RTL subtraction with unsigned saturation
2445 @item (minus:@var{m} @var{x} @var{y})
2446 @itemx (ss_minus:@var{m} @var{x} @var{y})
2447 @itemx (us_minus:@var{m} @var{x} @var{y})
2448
2449 These three expressions represent the result of subtracting @var{y}
2450 from @var{x}, carried out in mode @var{M}. Behavior on overflow is
2451 the same as for the three variants of @code{plus} (see above).
2452
2453 @findex compare
2454 @cindex RTL comparison
2455 @item (compare:@var{m} @var{x} @var{y})
2456 Represents the result of subtracting @var{y} from @var{x} for purposes
2457 of comparison. The result is computed without overflow, as if with
2458 infinite precision.
2459
2460 Of course, machines cannot really subtract with infinite precision.
2461 However, they can pretend to do so when only the sign of the result will
2462 be used, which is the case when the result is stored in the condition
2463 code. And that is the @emph{only} way this kind of expression may
2464 validly be used: as a value to be stored in the condition codes, in a
2465 register. @xref{Comparisons}.
2466
2467 The mode @var{m} is not related to the modes of @var{x} and @var{y}, but
2468 instead is the mode of the condition code value. It is some mode in class
2469 @code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}. If @var{m}
2470 is @code{CCmode}, the operation returns sufficient
2471 information (in an unspecified format) so that any comparison operator
2472 can be applied to the result of the @code{COMPARE} operation. For other
2473 modes in class @code{MODE_CC}, the operation only returns a subset of
2474 this information.
2475
2476 Normally, @var{x} and @var{y} must have the same mode. Otherwise,
2477 @code{compare} is valid only if the mode of @var{x} is in class
2478 @code{MODE_INT} and @var{y} is a @code{const_int} or
2479 @code{const_double} with mode @code{VOIDmode}. The mode of @var{x}
2480 determines what mode the comparison is to be done in; thus it must not
2481 be @code{VOIDmode}.
2482
2483 If one of the operands is a constant, it should be placed in the
2484 second operand and the comparison code adjusted as appropriate.
2485
2486 A @code{compare} specifying two @code{VOIDmode} constants is not valid
2487 since there is no way to know in what mode the comparison is to be
2488 performed; the comparison must either be folded during the compilation
2489 or the first operand must be loaded into a register while its mode is
2490 still known.
2491
2492 @findex neg
2493 @findex ss_neg
2494 @findex us_neg
2495 @cindex negation
2496 @cindex negation with signed saturation
2497 @cindex negation with unsigned saturation
2498 @item (neg:@var{m} @var{x})
2499 @itemx (ss_neg:@var{m} @var{x})
2500 @itemx (us_neg:@var{m} @var{x})
2501 These two expressions represent the negation (subtraction from zero) of
2502 the value represented by @var{x}, carried out in mode @var{m}. They
2503 differ in the behavior on overflow of integer modes. In the case of
2504 @code{neg}, the negation of the operand may be a number not representable
2505 in mode @var{m}, in which case it is truncated to @var{m}. @code{ss_neg}
2506 and @code{us_neg} ensure that an out-of-bounds result saturates to the
2507 maximum or minimum signed or unsigned value.
2508
2509 @findex mult
2510 @findex ss_mult
2511 @findex us_mult
2512 @cindex multiplication
2513 @cindex product
2514 @cindex multiplication with signed saturation
2515 @cindex multiplication with unsigned saturation
2516 @item (mult:@var{m} @var{x} @var{y})
2517 @itemx (ss_mult:@var{m} @var{x} @var{y})
2518 @itemx (us_mult:@var{m} @var{x} @var{y})
2519 Represents the signed product of the values represented by @var{x} and
2520 @var{y} carried out in machine mode @var{m}.
2521 @code{ss_mult} and @code{us_mult} ensure that an out-of-bounds result
2522 saturates to the maximum or minimum signed or unsigned value.
2523
2524 Some machines support a multiplication that generates a product wider
2525 than the operands. Write the pattern for this as
2526
2527 @smallexample
2528 (mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
2529 @end smallexample
2530
2531 where @var{m} is wider than the modes of @var{x} and @var{y}, which need
2532 not be the same.
2533
2534 For unsigned widening multiplication, use the same idiom, but with
2535 @code{zero_extend} instead of @code{sign_extend}.
2536
2537 @findex smul_highpart
2538 @findex umul_highpart
2539 @cindex high-part multiplication
2540 @cindex multiplication high part
2541 @item (smul_highpart:@var{m} @var{x} @var{y})
2542 @itemx (umul_highpart:@var{m} @var{x} @var{y})
2543 Represents the high-part multiplication of @var{x} and @var{y} carried
2544 out in machine mode @var{m}. @code{smul_highpart} returns the high part
2545 of a signed multiplication, @code{umul_highpart} returns the high part
2546 of an unsigned multiplication.
2547
2548 @findex fma
2549 @cindex fused multiply-add
2550 @item (fma:@var{m} @var{x} @var{y} @var{z})
2551 Represents the @code{fma}, @code{fmaf}, and @code{fmal} builtin
2552 functions, which compute @samp{@var{x} * @var{y} + @var{z}}
2553 without doing an intermediate rounding step.
2554
2555 @findex div
2556 @findex ss_div
2557 @cindex division
2558 @cindex signed division
2559 @cindex signed division with signed saturation
2560 @cindex quotient
2561 @item (div:@var{m} @var{x} @var{y})
2562 @itemx (ss_div:@var{m} @var{x} @var{y})
2563 Represents the quotient in signed division of @var{x} by @var{y},
2564 carried out in machine mode @var{m}. If @var{m} is a floating point
2565 mode, it represents the exact quotient; otherwise, the integerized
2566 quotient.
2567 @code{ss_div} ensures that an out-of-bounds result saturates to the maximum
2568 or minimum signed value.
2569
2570 Some machines have division instructions in which the operands and
2571 quotient widths are not all the same; you should represent
2572 such instructions using @code{truncate} and @code{sign_extend} as in,
2573
2574 @smallexample
2575 (truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
2576 @end smallexample
2577
2578 @findex udiv
2579 @cindex unsigned division
2580 @cindex unsigned division with unsigned saturation
2581 @cindex division
2582 @item (udiv:@var{m} @var{x} @var{y})
2583 @itemx (us_div:@var{m} @var{x} @var{y})
2584 Like @code{div} but represents unsigned division.
2585 @code{us_div} ensures that an out-of-bounds result saturates to the maximum
2586 or minimum unsigned value.
2587
2588 @findex mod
2589 @findex umod
2590 @cindex remainder
2591 @cindex division
2592 @item (mod:@var{m} @var{x} @var{y})
2593 @itemx (umod:@var{m} @var{x} @var{y})
2594 Like @code{div} and @code{udiv} but represent the remainder instead of
2595 the quotient.
2596
2597 @findex smin
2598 @findex smax
2599 @cindex signed minimum
2600 @cindex signed maximum
2601 @item (smin:@var{m} @var{x} @var{y})
2602 @itemx (smax:@var{m} @var{x} @var{y})
2603 Represents the smaller (for @code{smin}) or larger (for @code{smax}) of
2604 @var{x} and @var{y}, interpreted as signed values in mode @var{m}.
2605 When used with floating point, if both operands are zeros, or if either
2606 operand is @code{NaN}, then it is unspecified which of the two operands
2607 is returned as the result.
2608
2609 @findex umin
2610 @findex umax
2611 @cindex unsigned minimum and maximum
2612 @item (umin:@var{m} @var{x} @var{y})
2613 @itemx (umax:@var{m} @var{x} @var{y})
2614 Like @code{smin} and @code{smax}, but the values are interpreted as unsigned
2615 integers.
2616
2617 @findex not
2618 @cindex complement, bitwise
2619 @cindex bitwise complement
2620 @item (not:@var{m} @var{x})
2621 Represents the bitwise complement of the value represented by @var{x},
2622 carried out in mode @var{m}, which must be a fixed-point machine mode.
2623
2624 @findex and
2625 @cindex logical-and, bitwise
2626 @cindex bitwise logical-and
2627 @item (and:@var{m} @var{x} @var{y})
2628 Represents the bitwise logical-and of the values represented by
2629 @var{x} and @var{y}, carried out in machine mode @var{m}, which must be
2630 a fixed-point machine mode.
2631
2632 @findex ior
2633 @cindex inclusive-or, bitwise
2634 @cindex bitwise inclusive-or
2635 @item (ior:@var{m} @var{x} @var{y})
2636 Represents the bitwise inclusive-or of the values represented by @var{x}
2637 and @var{y}, carried out in machine mode @var{m}, which must be a
2638 fixed-point mode.
2639
2640 @findex xor
2641 @cindex exclusive-or, bitwise
2642 @cindex bitwise exclusive-or
2643 @item (xor:@var{m} @var{x} @var{y})
2644 Represents the bitwise exclusive-or of the values represented by @var{x}
2645 and @var{y}, carried out in machine mode @var{m}, which must be a
2646 fixed-point mode.
2647
2648 @findex ashift
2649 @findex ss_ashift
2650 @findex us_ashift
2651 @cindex left shift
2652 @cindex shift
2653 @cindex arithmetic shift
2654 @cindex arithmetic shift with signed saturation
2655 @cindex arithmetic shift with unsigned saturation
2656 @item (ashift:@var{m} @var{x} @var{c})
2657 @itemx (ss_ashift:@var{m} @var{x} @var{c})
2658 @itemx (us_ashift:@var{m} @var{x} @var{c})
2659 These three expressions represent the result of arithmetically shifting @var{x}
2660 left by @var{c} places. They differ in their behavior on overflow of integer
2661 modes. An @code{ashift} operation is a plain shift with no special behavior
2662 in case of a change in the sign bit; @code{ss_ashift} and @code{us_ashift}
2663 saturates to the minimum or maximum representable value if any of the bits
2664 shifted out differs from the final sign bit.
2665
2666 @var{x} have mode @var{m}, a fixed-point machine mode. @var{c}
2667 be a fixed-point mode or be a constant with mode @code{VOIDmode}; which
2668 mode is determined by the mode called for in the machine description
2669 entry for the left-shift instruction. For example, on the VAX, the mode
2670 of @var{c} is @code{QImode} regardless of @var{m}.
2671
2672 @findex lshiftrt
2673 @cindex right shift
2674 @findex ashiftrt
2675 @item (lshiftrt:@var{m} @var{x} @var{c})
2676 @itemx (ashiftrt:@var{m} @var{x} @var{c})
2677 Like @code{ashift} but for right shift. Unlike the case for left shift,
2678 these two operations are distinct.
2679
2680 @findex rotate
2681 @cindex rotate
2682 @cindex left rotate
2683 @findex rotatert
2684 @cindex right rotate
2685 @item (rotate:@var{m} @var{x} @var{c})
2686 @itemx (rotatert:@var{m} @var{x} @var{c})
2687 Similar but represent left and right rotate. If @var{c} is a constant,
2688 use @code{rotate}.
2689
2690 @findex abs
2691 @findex ss_abs
2692 @cindex absolute value
2693 @item (abs:@var{m} @var{x})
2694 @item (ss_abs:@var{m} @var{x})
2695 Represents the absolute value of @var{x}, computed in mode @var{m}.
2696 @code{ss_abs} ensures that an out-of-bounds result saturates to the
2697 maximum signed value.
2698
2699
2700 @findex sqrt
2701 @cindex square root
2702 @item (sqrt:@var{m} @var{x})
2703 Represents the square root of @var{x}, computed in mode @var{m}.
2704 Most often @var{m} will be a floating point mode.
2705
2706 @findex ffs
2707 @item (ffs:@var{m} @var{x})
2708 Represents one plus the index of the least significant 1-bit in
2709 @var{x}, represented as an integer of mode @var{m}. (The value is
2710 zero if @var{x} is zero.) The mode of @var{x} must be @var{m}
2711 or @code{VOIDmode}.
2712
2713 @findex clrsb
2714 @item (clrsb:@var{m} @var{x})
2715 Represents the number of redundant leading sign bits in @var{x},
2716 represented as an integer of mode @var{m}, starting at the most
2717 significant bit position. This is one less than the number of leading
2718 sign bits (either 0 or 1), with no special cases. The mode of @var{x}
2719 must be @var{m} or @code{VOIDmode}.
2720
2721 @findex clz
2722 @item (clz:@var{m} @var{x})
2723 Represents the number of leading 0-bits in @var{x}, represented as an
2724 integer of mode @var{m}, starting at the most significant bit position.
2725 If @var{x} is zero, the value is determined by
2726 @code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}). Note that this is one of
2727 the few expressions that is not invariant under widening. The mode of
2728 @var{x} must be @var{m} or @code{VOIDmode}.
2729
2730 @findex ctz
2731 @item (ctz:@var{m} @var{x})
2732 Represents the number of trailing 0-bits in @var{x}, represented as an
2733 integer of mode @var{m}, starting at the least significant bit position.
2734 If @var{x} is zero, the value is determined by
2735 @code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}). Except for this case,
2736 @code{ctz(x)} is equivalent to @code{ffs(@var{x}) - 1}. The mode of
2737 @var{x} must be @var{m} or @code{VOIDmode}.
2738
2739 @findex popcount
2740 @item (popcount:@var{m} @var{x})
2741 Represents the number of 1-bits in @var{x}, represented as an integer of
2742 mode @var{m}. The mode of @var{x} must be @var{m} or @code{VOIDmode}.
2743
2744 @findex parity
2745 @item (parity:@var{m} @var{x})
2746 Represents the number of 1-bits modulo 2 in @var{x}, represented as an
2747 integer of mode @var{m}. The mode of @var{x} must be @var{m} or
2748 @code{VOIDmode}.
2749
2750 @findex bswap
2751 @item (bswap:@var{m} @var{x})
2752 Represents the value @var{x} with the order of bytes reversed, carried out
2753 in mode @var{m}, which must be a fixed-point machine mode.
2754 The mode of @var{x} must be @var{m} or @code{VOIDmode}.
2755
2756 @findex bitreverse
2757 @item (bitreverse:@var{m} @var{x})
2758 Represents the value @var{x} with the order of bits reversed, carried out
2759 in mode @var{m}, which must be a fixed-point machine mode.
2760 The mode of @var{x} must be @var{m} or @code{VOIDmode}.
2761
2762 @findex copysign
2763 @item (copysign:@var{m} @var{x} @var{y})
2764 Represents the value @var{x} with the sign of @var{y}.
2765 Both @var{x} and @var{y} must have floating point machine mode @var{m}.
2766 @end table
2767
2768 @node Comparisons
2769 @section Comparison Operations
2770 @cindex RTL comparison operations
2771
2772 Comparison operators test a relation on two operands and are considered
2773 to represent a machine-dependent nonzero value described by, but not
2774 necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
2775 if the relation holds, or zero if it does not, for comparison operators
2776 whose results have a `MODE_INT' mode,
2777 @code{FLOAT_STORE_FLAG_VALUE} (@pxref{Misc}) if the relation holds, or
2778 zero if it does not, for comparison operators that return floating-point
2779 values, and a vector of either @code{VECTOR_STORE_FLAG_VALUE} (@pxref{Misc})
2780 if the relation holds, or of zeros if it does not, for comparison operators
2781 that return vector results.
2782 The mode of the comparison operation is independent of the mode
2783 of the data being compared. If the comparison operation is being tested
2784 (e.g., the first operand of an @code{if_then_else}), the mode must be
2785 @code{VOIDmode}.
2786
2787 @cindex condition codes
2788 A comparison operation compares two data
2789 objects. The mode of the comparison is determined by the operands; they
2790 must both be valid for a common machine mode. A comparison with both
2791 operands constant would be invalid as the machine mode could not be
2792 deduced from it, but such a comparison should never exist in RTL due to
2793 constant folding.
2794
2795 Usually only one style
2796 of comparisons is supported on a particular machine, but the combine
2797 pass will try to merge operations to produce code like
2798 @code{(eq @var{x} @var{y})},
2799 in case it exists in the context of the particular insn involved.
2800
2801 Inequality comparisons come in two flavors, signed and unsigned. Thus,
2802 there are distinct expression codes @code{gt} and @code{gtu} for signed and
2803 unsigned greater-than. These can produce different results for the same
2804 pair of integer values: for example, 1 is signed greater-than @minus{}1 but not
2805 unsigned greater-than, because @minus{}1 when regarded as unsigned is actually
2806 @code{0xffffffff} which is greater than 1.
2807
2808 The signed comparisons are also used for floating point values. Floating
2809 point comparisons are distinguished by the machine modes of the operands.
2810
2811 @table @code
2812 @findex eq
2813 @cindex equal
2814 @item (eq:@var{m} @var{x} @var{y})
2815 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2816 are equal, otherwise 0.
2817
2818 @findex ne
2819 @cindex not equal
2820 @item (ne:@var{m} @var{x} @var{y})
2821 @code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2822 are not equal, otherwise 0.
2823
2824 @findex gt
2825 @cindex greater than
2826 @item (gt:@var{m} @var{x} @var{y})
2827 @code{STORE_FLAG_VALUE} if the @var{x} is greater than @var{y}. If they
2828 are fixed-point, the comparison is done in a signed sense.
2829
2830 @findex gtu
2831 @cindex greater than
2832 @cindex unsigned greater than
2833 @item (gtu:@var{m} @var{x} @var{y})
2834 Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
2835
2836 @findex lt
2837 @cindex less than
2838 @findex ltu
2839 @cindex unsigned less than
2840 @item (lt:@var{m} @var{x} @var{y})
2841 @itemx (ltu:@var{m} @var{x} @var{y})
2842 Like @code{gt} and @code{gtu} but test for ``less than''.
2843
2844 @findex ge
2845 @cindex greater than
2846 @findex geu
2847 @cindex unsigned greater than
2848 @item (ge:@var{m} @var{x} @var{y})
2849 @itemx (geu:@var{m} @var{x} @var{y})
2850 Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
2851
2852 @findex le
2853 @cindex less than or equal
2854 @findex leu
2855 @cindex unsigned less than
2856 @item (le:@var{m} @var{x} @var{y})
2857 @itemx (leu:@var{m} @var{x} @var{y})
2858 Like @code{gt} and @code{gtu} but test for ``less than or equal''.
2859
2860 @findex if_then_else
2861 @item (if_then_else @var{cond} @var{then} @var{else})
2862 This is not a comparison operation but is listed here because it is
2863 always used in conjunction with a comparison operation. To be
2864 precise, @var{cond} is a comparison expression. This expression
2865 represents a choice, according to @var{cond}, between the value
2866 represented by @var{then} and the one represented by @var{else}.
2867
2868 On most machines, @code{if_then_else} expressions are valid only
2869 to express conditional jumps.
2870
2871 @findex cond
2872 @item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
2873 Similar to @code{if_then_else}, but more general. Each of @var{test1},
2874 @var{test2}, @dots{} is performed in turn. The result of this expression is
2875 the @var{value} corresponding to the first nonzero test, or @var{default} if
2876 none of the tests are nonzero expressions.
2877
2878 This is currently not valid for instruction patterns and is supported only
2879 for insn attributes. @xref{Insn Attributes}.
2880 @end table
2881
2882 @node Bit-Fields
2883 @section Bit-Fields
2884 @cindex bit-fields
2885
2886 Special expression codes exist to represent bit-field instructions.
2887
2888 @table @code
2889 @findex sign_extract
2890 @cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
2891 @item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
2892 This represents a reference to a sign-extended bit-field contained or
2893 starting in @var{loc} (a memory or register reference). The bit-field
2894 is @var{size} bits wide and starts at bit @var{pos}. The compilation
2895 option @code{BITS_BIG_ENDIAN} says which end of the memory unit
2896 @var{pos} counts from.
2897
2898 If @var{loc} is in memory, its mode must be a single-byte integer mode.
2899 If @var{loc} is in a register, the mode to use is specified by the
2900 operand of the @code{insv} or @code{extv} pattern
2901 (@pxref{Standard Names}) and is usually a full-word integer mode,
2902 which is the default if none is specified.
2903
2904 The mode of @var{pos} is machine-specific and is also specified
2905 in the @code{insv} or @code{extv} pattern.
2906
2907 The mode @var{m} is the same as the mode that would be used for
2908 @var{loc} if it were a register.
2909
2910 A @code{sign_extract} cannot appear as an lvalue, or part thereof,
2911 in RTL.
2912
2913 @findex zero_extract
2914 @item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
2915 Like @code{sign_extract} but refers to an unsigned or zero-extended
2916 bit-field. The same sequence of bits are extracted, but they
2917 are filled to an entire word with zeros instead of by sign-extension.
2918
2919 Unlike @code{sign_extract}, this type of expressions can be lvalues
2920 in RTL; they may appear on the left side of an assignment, indicating
2921 insertion of a value into the specified bit-field.
2922 @end table
2923
2924 @node Vector Operations
2925 @section Vector Operations
2926 @cindex vector operations
2927
2928 All normal RTL expressions can be used with vector modes; they are
2929 interpreted as operating on each part of the vector independently.
2930 Additionally, there are a few new expressions to describe specific vector
2931 operations.
2932
2933 @table @code
2934 @findex vec_merge
2935 @item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items})
2936 This describes a merge operation between two vectors. The result is a vector
2937 of mode @var{m}; its elements are selected from either @var{vec1} or
2938 @var{vec2}. Which elements are selected is described by @var{items}, which
2939 is a bit mask represented by a @code{const_int}; a zero bit indicates the
2940 corresponding element in the result vector is taken from @var{vec2} while
2941 a set bit indicates it is taken from @var{vec1}.
2942
2943 @findex vec_select
2944 @item (vec_select:@var{m} @var{vec1} @var{selection})
2945 This describes an operation that selects parts of a vector. @var{vec1} is
2946 the source vector, and @var{selection} is a @code{parallel} that contains a
2947 @code{const_int} (or another expression, if the selection can be made at
2948 runtime) for each of the subparts of the result vector, giving the number of
2949 the source subpart that should be stored into it. The result mode @var{m} is
2950 either the submode for a single element of @var{vec1} (if only one subpart is
2951 selected), or another vector mode with that element submode (if multiple
2952 subparts are selected).
2953
2954 @findex vec_concat
2955 @item (vec_concat:@var{m} @var{x1} @var{x2})
2956 Describes a vector concat operation. The result is a concatenation of the
2957 vectors or scalars @var{x1} and @var{x2}; its length is the sum of the
2958 lengths of the two inputs.
2959
2960 @findex vec_duplicate
2961 @item (vec_duplicate:@var{m} @var{x})
2962 This operation converts a scalar into a vector or a small vector into a
2963 larger one by duplicating the input values. The output vector mode must have
2964 the same submodes as the input vector mode or the scalar modes, and the
2965 number of output parts must be an integer multiple of the number of input
2966 parts.
2967
2968 @findex vec_series
2969 @item (vec_series:@var{m} @var{base} @var{step})
2970 This operation creates a vector in which element @var{i} is equal to
2971 @samp{@var{base} + @var{i}*@var{step}}. @var{m} must be a vector integer mode.
2972 @end table
2973
2974 @node Conversions
2975 @section Conversions
2976 @cindex conversions
2977 @cindex machine mode conversions
2978
2979 All conversions between machine modes must be represented by
2980 explicit conversion operations. For example, an expression
2981 which is the sum of a byte and a full word cannot be written as
2982 @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
2983 operation requires two operands of the same machine mode.
2984 Therefore, the byte-sized operand is enclosed in a conversion
2985 operation, as in
2986
2987 @smallexample
2988 (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
2989 @end smallexample
2990
2991 The conversion operation is not a mere placeholder, because there
2992 may be more than one way of converting from a given starting mode
2993 to the desired final mode. The conversion operation code says how
2994 to do it.
2995
2996 For all conversion operations, @var{x} must not be @code{VOIDmode}
2997 because the mode in which to do the conversion would not be known.
2998 The conversion must either be done at compile-time or @var{x}
2999 must be placed into a register.
3000
3001 @table @code
3002 @findex sign_extend
3003 @item (sign_extend:@var{m} @var{x})
3004 Represents the result of sign-extending the value @var{x}
3005 to machine mode @var{m}. @var{m} must be a fixed-point mode
3006 and @var{x} a fixed-point value of a mode narrower than @var{m}.
3007
3008 @findex zero_extend
3009 @item (zero_extend:@var{m} @var{x})
3010 Represents the result of zero-extending the value @var{x}
3011 to machine mode @var{m}. @var{m} must be a fixed-point mode
3012 and @var{x} a fixed-point value of a mode narrower than @var{m}.
3013
3014 @findex float_extend
3015 @item (float_extend:@var{m} @var{x})
3016 Represents the result of extending the value @var{x}
3017 to machine mode @var{m}. @var{m} must be a floating point mode
3018 and @var{x} a floating point value of a mode narrower than @var{m}.
3019
3020 @findex truncate
3021 @item (truncate:@var{m} @var{x})
3022 Represents the result of truncating the value @var{x}
3023 to machine mode @var{m}. @var{m} must be a fixed-point mode
3024 and @var{x} a fixed-point value of a mode wider than @var{m}.
3025
3026 @findex ss_truncate
3027 @item (ss_truncate:@var{m} @var{x})
3028 Represents the result of truncating the value @var{x}
3029 to machine mode @var{m}, using signed saturation in the case of
3030 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
3031 modes.
3032
3033 @findex us_truncate
3034 @item (us_truncate:@var{m} @var{x})
3035 Represents the result of truncating the value @var{x}
3036 to machine mode @var{m}, using unsigned saturation in the case of
3037 overflow. Both @var{m} and the mode of @var{x} must be fixed-point
3038 modes.
3039
3040 @findex float_truncate
3041 @item (float_truncate:@var{m} @var{x})
3042 Represents the result of truncating the value @var{x}
3043 to machine mode @var{m}. @var{m} must be a floating point mode
3044 and @var{x} a floating point value of a mode wider than @var{m}.
3045
3046 @findex float
3047 @item (float:@var{m} @var{x})
3048 Represents the result of converting fixed point value @var{x},
3049 regarded as signed, to floating point mode @var{m}.
3050
3051 @findex unsigned_float
3052 @item (unsigned_float:@var{m} @var{x})
3053 Represents the result of converting fixed point value @var{x},
3054 regarded as unsigned, to floating point mode @var{m}.
3055
3056 @findex fix
3057 @item (fix:@var{m} @var{x})
3058 When @var{m} is a floating-point mode, represents the result of
3059 converting floating point value @var{x} (valid for mode @var{m}) to an
3060 integer, still represented in floating point mode @var{m}, by rounding
3061 towards zero.
3062
3063 When @var{m} is a fixed-point mode, represents the result of
3064 converting floating point value @var{x} to mode @var{m}, regarded as
3065 signed. How rounding is done is not specified, so this operation may
3066 be used validly in compiling C code only for integer-valued operands.
3067
3068 @findex unsigned_fix
3069 @item (unsigned_fix:@var{m} @var{x})
3070 Represents the result of converting floating point value @var{x} to
3071 fixed point mode @var{m}, regarded as unsigned. How rounding is done
3072 is not specified.
3073
3074 @findex fract_convert
3075 @item (fract_convert:@var{m} @var{x})
3076 Represents the result of converting fixed-point value @var{x} to
3077 fixed-point mode @var{m}, signed integer value @var{x} to
3078 fixed-point mode @var{m}, floating-point value @var{x} to
3079 fixed-point mode @var{m}, fixed-point value @var{x} to integer mode @var{m}
3080 regarded as signed, or fixed-point value @var{x} to floating-point mode @var{m}.
3081 When overflows or underflows happen, the results are undefined.
3082
3083 @findex sat_fract
3084 @item (sat_fract:@var{m} @var{x})
3085 Represents the result of converting fixed-point value @var{x} to
3086 fixed-point mode @var{m}, signed integer value @var{x} to
3087 fixed-point mode @var{m}, or floating-point value @var{x} to
3088 fixed-point mode @var{m}.
3089 When overflows or underflows happen, the results are saturated to the
3090 maximum or the minimum.
3091
3092 @findex unsigned_fract_convert
3093 @item (unsigned_fract_convert:@var{m} @var{x})
3094 Represents the result of converting fixed-point value @var{x} to
3095 integer mode @var{m} regarded as unsigned, or unsigned integer value @var{x} to
3096 fixed-point mode @var{m}.
3097 When overflows or underflows happen, the results are undefined.
3098
3099 @findex unsigned_sat_fract
3100 @item (unsigned_sat_fract:@var{m} @var{x})
3101 Represents the result of converting unsigned integer value @var{x} to
3102 fixed-point mode @var{m}.
3103 When overflows or underflows happen, the results are saturated to the
3104 maximum or the minimum.
3105 @end table
3106
3107 @node RTL Declarations
3108 @section Declarations
3109 @cindex RTL declarations
3110 @cindex declarations, RTL
3111
3112 Declaration expression codes do not represent arithmetic operations
3113 but rather state assertions about their operands.
3114
3115 @table @code
3116 @findex strict_low_part
3117 @cindex @code{subreg}, in @code{strict_low_part}
3118 @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
3119 This expression code is used in only one context: as the destination operand of a
3120 @code{set} expression. In addition, the operand of this expression
3121 must be a non-paradoxical @code{subreg} expression.
3122
3123 The presence of @code{strict_low_part} says that the part of the
3124 register which is meaningful in mode @var{n}, but is not part of
3125 mode @var{m}, is not to be altered. Normally, an assignment to such
3126 a subreg is allowed to have undefined effects on the rest of the
3127 register when @var{m} is smaller than @samp{REGMODE_NATURAL_SIZE (@var{n})}.
3128 @end table
3129
3130 @node Side Effects
3131 @section Side Effect Expressions
3132 @cindex RTL side effect expressions
3133
3134 The expression codes described so far represent values, not actions.
3135 But machine instructions never produce values; they are meaningful
3136 only for their side effects on the state of the machine. Special
3137 expression codes are used to represent side effects.
3138
3139 The body of an instruction is always one of these side effect codes;
3140 the codes described above, which represent values, appear only as
3141 the operands of these.
3142
3143 @table @code
3144 @findex set
3145 @item (set @var{lval} @var{x})
3146 Represents the action of storing the value of @var{x} into the place
3147 represented by @var{lval}. @var{lval} must be an expression
3148 representing a place that can be stored in: @code{reg} (or @code{subreg},
3149 @code{strict_low_part} or @code{zero_extract}), @code{mem}, @code{pc},
3150 or @code{parallel}.
3151
3152 If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
3153 machine mode; then @var{x} must be valid for that mode.
3154
3155 If @var{lval} is a @code{reg} whose machine mode is less than the full
3156 width of the register, then it means that the part of the register
3157 specified by the machine mode is given the specified value and the
3158 rest of the register receives an undefined value. Likewise, if
3159 @var{lval} is a @code{subreg} whose machine mode is narrower than
3160 the mode of the register, the rest of the register can be changed in
3161 an undefined way.
3162
3163 If @var{lval} is a @code{strict_low_part} of a subreg, then the part
3164 of the register specified by the machine mode of the @code{subreg} is
3165 given the value @var{x} and the rest of the register is not changed.
3166
3167 If @var{lval} is a @code{zero_extract}, then the referenced part of
3168 the bit-field (a memory or register reference) specified by the
3169 @code{zero_extract} is given the value @var{x} and the rest of the
3170 bit-field is not changed. Note that @code{sign_extract} cannot
3171 appear in @var{lval}.
3172
3173 If @var{lval} is a @code{parallel}, it is used to represent the case of
3174 a function returning a structure in multiple registers. Each element
3175 of the @code{parallel} is an @code{expr_list} whose first operand is a
3176 @code{reg} and whose second operand is a @code{const_int} representing the
3177 offset (in bytes) into the structure at which the data in that register
3178 corresponds. The first element may be null to indicate that the structure
3179 is also passed partly in memory.
3180
3181 @cindex jump instructions and @code{set}
3182 @cindex @code{if_then_else} usage
3183 If @var{lval} is @code{(pc)}, we have a jump instruction, and the
3184 possibilities for @var{x} are very limited. It may be a
3185 @code{label_ref} expression (unconditional jump). It may be an
3186 @code{if_then_else} (conditional jump), in which case either the
3187 second or the third operand must be @code{(pc)} (for the case which
3188 does not jump) and the other of the two must be a @code{label_ref}
3189 (for the case which does jump). @var{x} may also be a @code{mem} or
3190 @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
3191 @code{mem}; these unusual patterns are used to represent jumps through
3192 branch tables.
3193
3194 If @var{lval} is not @code{(pc)}, the mode of
3195 @var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
3196 valid for the mode of @var{lval}.
3197
3198 @findex SET_DEST
3199 @findex SET_SRC
3200 @var{lval} is customarily accessed with the @code{SET_DEST} macro and
3201 @var{x} with the @code{SET_SRC} macro.
3202
3203 @findex return
3204 @item (return)
3205 As the sole expression in a pattern, represents a return from the
3206 current function, on machines where this can be done with one
3207 instruction, such as VAXen. On machines where a multi-instruction
3208 ``epilogue'' must be executed in order to return from the function,
3209 returning is done by jumping to a label which precedes the epilogue, and
3210 the @code{return} expression code is never used.
3211
3212 Inside an @code{if_then_else} expression, represents the value to be
3213 placed in @code{pc} to return to the caller.
3214
3215 Note that an insn pattern of @code{(return)} is logically equivalent to
3216 @code{(set (pc) (return))}, but the latter form is never used.
3217
3218 @findex simple_return
3219 @item (simple_return)
3220 Like @code{(return)}, but truly represents only a function return, while
3221 @code{(return)} may represent an insn that also performs other functions
3222 of the function epilogue. Like @code{(return)}, this may also occur in
3223 conditional jumps.
3224
3225 @findex call
3226 @item (call @var{function} @var{nargs})
3227 Represents a function call. @var{function} is a @code{mem} expression
3228 whose address is the address of the function to be called.
3229 @var{nargs} is an expression which can be used for two purposes: on
3230 some machines it represents the number of bytes of stack argument; on
3231 others, it represents the number of argument registers.
3232
3233 Each machine has a standard machine mode which @var{function} must
3234 have. The machine description defines macro @code{FUNCTION_MODE} to
3235 expand into the requisite mode name. The purpose of this mode is to
3236 specify what kind of addressing is allowed, on machines where the
3237 allowed kinds of addressing depend on the machine mode being
3238 addressed.
3239
3240 @findex clobber
3241 @item (clobber @var{x})
3242 Represents the storing or possible storing of an unpredictable,
3243 undescribed value into @var{x}, which must be a @code{reg},
3244 @code{scratch}, @code{parallel} or @code{mem} expression.
3245
3246 One place this is used is in string instructions that store standard
3247 values into particular hard registers. It may not be worth the
3248 trouble to describe the values that are stored, but it is essential to
3249 inform the compiler that the registers will be altered, lest it
3250 attempt to keep data in them across the string instruction.
3251
3252 If @var{x} is @code{(mem:BLK (const_int 0))} or
3253 @code{(mem:BLK (scratch))}, it means that all memory
3254 locations must be presumed clobbered. If @var{x} is a @code{parallel},
3255 it has the same meaning as a @code{parallel} in a @code{set} expression.
3256
3257 Note that the machine description classifies certain hard registers as
3258 ``call-clobbered''. All function call instructions are assumed by
3259 default to clobber these registers, so there is no need to use
3260 @code{clobber} expressions to indicate this fact. Also, each function
3261 call is assumed to have the potential to alter any memory location,
3262 unless the function is declared @code{const}.
3263
3264 If the last group of expressions in a @code{parallel} are each a
3265 @code{clobber} expression whose arguments are @code{reg} or
3266 @code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
3267 phase can add the appropriate @code{clobber} expressions to an insn it
3268 has constructed when doing so will cause a pattern to be matched.
3269
3270 This feature can be used, for example, on a machine that whose multiply
3271 and add instructions don't use an MQ register but which has an
3272 add-accumulate instruction that does clobber the MQ register. Similarly,
3273 a combined instruction might require a temporary register while the
3274 constituent instructions might not.
3275
3276 When a @code{clobber} expression for a register appears inside a
3277 @code{parallel} with other side effects, the register allocator
3278 guarantees that the register is unoccupied both before and after that
3279 insn if it is a hard register clobber. For pseudo-register clobber,
3280 the register allocator and the reload pass do not assign the same hard
3281 register to the clobber and the input operands if there is an insn
3282 alternative containing the @samp{&} constraint (@pxref{Modifiers}) for
3283 the clobber and the hard register is in register classes of the
3284 clobber in the alternative. You can clobber either a specific hard
3285 register, a pseudo register, or a @code{scratch} expression; in the
3286 latter two cases, GCC will allocate a hard register that is available
3287 there for use as a temporary.
3288
3289 For instructions that require a temporary register, you should use
3290 @code{scratch} instead of a pseudo-register because this will allow the
3291 combiner phase to add the @code{clobber} when required. You do this by
3292 coding (@code{clobber} (@code{match_scratch} @dots{})). If you do
3293 clobber a pseudo register, use one which appears nowhere else---generate
3294 a new one each time. Otherwise, you may confuse CSE@.
3295
3296 There is one other known use for clobbering a pseudo register in a
3297 @code{parallel}: when one of the input operands of the insn is also
3298 clobbered by the insn. In this case, using the same pseudo register in
3299 the clobber and elsewhere in the insn produces the expected results.
3300
3301 @findex use
3302 @item (use @var{x})
3303 Represents the use of the value of @var{x}. It indicates that the
3304 value in @var{x} at this point in the program is needed, even though
3305 it may not be apparent why this is so. Therefore, the compiler will
3306 not attempt to delete previous instructions whose only effect is to
3307 store a value in @var{x}. @var{x} must be a @code{reg} expression.
3308
3309 In some situations, it may be tempting to add a @code{use} of a
3310 register in a @code{parallel} to describe a situation where the value
3311 of a special register will modify the behavior of the instruction.
3312 A hypothetical example might be a pattern for an addition that can
3313 either wrap around or use saturating addition depending on the value
3314 of a special control register:
3315
3316 @smallexample
3317 (parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
3318 (reg:SI 4)] 0))
3319 (use (reg:SI 1))])
3320 @end smallexample
3321
3322 @noindent
3323
3324 This will not work, several of the optimizers only look at expressions
3325 locally; it is very likely that if you have multiple insns with
3326 identical inputs to the @code{unspec}, they will be optimized away even
3327 if register 1 changes in between.
3328
3329 This means that @code{use} can @emph{only} be used to describe
3330 that the register is live. You should think twice before adding
3331 @code{use} statements, more often you will want to use @code{unspec}
3332 instead. The @code{use} RTX is most commonly useful to describe that
3333 a fixed register is implicitly used in an insn. It is also safe to use
3334 in patterns where the compiler knows for other reasons that the result
3335 of the whole pattern is variable, such as @samp{cpymem@var{m}} or
3336 @samp{call} patterns.
3337
3338 During the reload phase, an insn that has a @code{use} as pattern
3339 can carry a reg_equal note. These @code{use} insns will be deleted
3340 before the reload phase exits.
3341
3342 During the delayed branch scheduling phase, @var{x} may be an insn.
3343 This indicates that @var{x} previously was located at this place in the
3344 code and its data dependencies need to be taken into account. These
3345 @code{use} insns will be deleted before the delayed branch scheduling
3346 phase exits.
3347
3348 @findex parallel
3349 @item (parallel [@var{x0} @var{x1} @dots{}])
3350 Represents several side effects performed in parallel. The square
3351 brackets stand for a vector; the operand of @code{parallel} is a
3352 vector of expressions. @var{x0}, @var{x1} and so on are individual
3353 side effect expressions---expressions of code @code{set}, @code{call},
3354 @code{return}, @code{simple_return}, @code{clobber} or @code{use}.
3355
3356 ``In parallel'' means that first all the values used in the individual
3357 side-effects are computed, and second all the actual side-effects are
3358 performed. For example,
3359
3360 @smallexample
3361 (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
3362 (set (mem:SI (reg:SI 1)) (reg:SI 1))])
3363 @end smallexample
3364
3365 @noindent
3366 says unambiguously that the values of hard register 1 and the memory
3367 location addressed by it are interchanged. In both places where
3368 @code{(reg:SI 1)} appears as a memory address it refers to the value
3369 in register 1 @emph{before} the execution of the insn.
3370
3371 It follows that it is @emph{incorrect} to use @code{parallel} and
3372 expect the result of one @code{set} to be available for the next one.
3373 For example, people sometimes attempt to represent a jump-if-zero
3374 instruction this way:
3375
3376 @smallexample
3377 (parallel [(set (reg:CC CC_REG) (reg:SI 34))
3378 (set (pc) (if_then_else
3379 (eq (reg:CC CC_REG) (const_int 0))
3380 (label_ref @dots{})
3381 (pc)))])
3382 @end smallexample
3383
3384 @noindent
3385 But this is incorrect, because it says that the jump condition depends
3386 on the condition code value @emph{before} this instruction, not on the
3387 new value that is set by this instruction.
3388
3389 @cindex peephole optimization, RTL representation
3390 Peephole optimization, which takes place together with final assembly
3391 code output, can produce insns whose patterns consist of a @code{parallel}
3392 whose elements are the operands needed to output the resulting
3393 assembler code---often @code{reg}, @code{mem} or constant expressions.
3394 This would not be well-formed RTL at any other stage in compilation,
3395 but it is OK then because no further optimization remains to be done.
3396
3397 @findex cond_exec
3398 @item (cond_exec [@var{cond} @var{expr}])
3399 Represents a conditionally executed expression. The @var{expr} is
3400 executed only if the @var{cond} is nonzero. The @var{cond} expression
3401 must not have side-effects, but the @var{expr} may very well have
3402 side-effects.
3403
3404 @findex sequence
3405 @item (sequence [@var{insns} @dots{}])
3406 Represents a sequence of insns. If a @code{sequence} appears in the
3407 chain of insns, then each of the @var{insns} that appears in the sequence
3408 must be suitable for appearing in the chain of insns, i.e.@: must satisfy
3409 the @code{INSN_P} predicate.
3410
3411 After delay-slot scheduling is completed, an insn and all the insns that
3412 reside in its delay slots are grouped together into a @code{sequence}.
3413 The insn requiring the delay slot is the first insn in the vector;
3414 subsequent insns are to be placed in the delay slot.
3415
3416 @code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
3417 indicate that a branch insn should be used that will conditionally annul
3418 the effect of the insns in the delay slots. In such a case,
3419 @code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
3420 the branch and should be executed only if the branch is taken; otherwise
3421 the insn should be executed only if the branch is not taken.
3422 @xref{Delay Slots}.
3423
3424 Some back ends also use @code{sequence} objects for purposes other than
3425 delay-slot groups. This is not supported in the common parts of the
3426 compiler, which treat such sequences as delay-slot groups.
3427
3428 DWARF2 Call Frame Address (CFA) adjustments are sometimes also expressed
3429 using @code{sequence} objects as the value of a @code{RTX_FRAME_RELATED_P}
3430 note. This only happens if the CFA adjustments cannot be easily derived
3431 from the pattern of the instruction to which the note is attached. In
3432 such cases, the value of the note is used instead of best-guesing the
3433 semantics of the instruction. The back end can attach notes containing
3434 a @code{sequence} of @code{set} patterns that express the effect of the
3435 parent instruction.
3436 @end table
3437
3438 These expression codes appear in place of a side effect, as the body of
3439 an insn, though strictly speaking they do not always describe side
3440 effects as such:
3441
3442 @table @code
3443 @findex asm_input
3444 @item (asm_input @var{s})
3445 Represents literal assembler code as described by the string @var{s}.
3446
3447 @findex unspec
3448 @findex unspec_volatile
3449 @item (unspec [@var{operands} @dots{}] @var{index})
3450 @itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
3451 Represents a machine-specific operation on @var{operands}. @var{index}
3452 selects between multiple machine-specific operations.
3453 @code{unspec_volatile} is used for volatile operations and operations
3454 that may trap; @code{unspec} is used for other operations.
3455
3456 These codes may appear inside a @code{pattern} of an
3457 insn, inside a @code{parallel}, or inside an expression.
3458
3459 @findex addr_vec
3460 @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
3461 Represents a table of jump addresses. The vector elements @var{lr0},
3462 etc., are @code{label_ref} expressions. The mode @var{m} specifies
3463 how much space is given to each address; normally @var{m} would be
3464 @code{Pmode}.
3465
3466 @findex addr_diff_vec
3467 @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags})
3468 Represents a table of jump addresses expressed as offsets from
3469 @var{base}. The vector elements @var{lr0}, etc., are @code{label_ref}
3470 expressions and so is @var{base}. The mode @var{m} specifies how much
3471 space is given to each address-difference. @var{min} and @var{max}
3472 are set up by branch shortening and hold a label with a minimum and a
3473 maximum address, respectively. @var{flags} indicates the relative
3474 position of @var{base}, @var{min} and @var{max} to the containing insn
3475 and of @var{min} and @var{max} to @var{base}. See rtl.def for details.
3476
3477 @findex prefetch
3478 @item (prefetch:@var{m} @var{addr} @var{rws} @var{locality} @var{cache})
3479 Represents prefetch of memory at address @var{addr}.
3480 Operand @var{rws} is 0 if the prefetch is for data to be read, 1 for being
3481 written; 2 if read shared;
3482 targets that do not support write or read shared prefetches should treat this
3483 as a normal prefetch.
3484 Operand @var{locality} specifies the amount of temporal locality; 0 if there
3485 is none or 1, 2, or 3 for increasing levels of temporal locality;
3486 targets that do not support locality hints should ignore this.
3487
3488 This insn is used to minimize cache-miss latency by moving data into a
3489 cache before it is accessed. It should use only non-faulting data prefetch
3490 instructions.
3491 @end table
3492
3493 @node Incdec
3494 @section Embedded Side-Effects on Addresses
3495 @cindex RTL preincrement
3496 @cindex RTL postincrement
3497 @cindex RTL predecrement
3498 @cindex RTL postdecrement
3499
3500 Six special side-effect expression codes appear as memory addresses.
3501
3502 @table @code
3503 @findex pre_dec
3504 @item (pre_dec:@var{m} @var{x})
3505 Represents the side effect of decrementing @var{x} by a standard
3506 amount and represents also the value that @var{x} has after being
3507 decremented. @var{x} must be a @code{reg} or @code{mem}, but most
3508 machines allow only a @code{reg}. @var{m} must be the machine mode
3509 for pointers on the machine in use. The amount @var{x} is decremented
3510 by is the length in bytes of the machine mode of the containing memory
3511 reference of which this expression serves as the address. Here is an
3512 example of its use:
3513
3514 @smallexample
3515 (mem:DF (pre_dec:SI (reg:SI 39)))
3516 @end smallexample
3517
3518 @noindent
3519 This says to decrement pseudo register 39 by the length of a @code{DFmode}
3520 value and use the result to address a @code{DFmode} value.
3521
3522 @findex pre_inc
3523 @item (pre_inc:@var{m} @var{x})
3524 Similar, but specifies incrementing @var{x} instead of decrementing it.
3525
3526 @findex post_dec
3527 @item (post_dec:@var{m} @var{x})
3528 Represents the same side effect as @code{pre_dec} but a different
3529 value. The value represented here is the value @var{x} has @i{before}
3530 being decremented.
3531
3532 @findex post_inc
3533 @item (post_inc:@var{m} @var{x})
3534 Similar, but specifies incrementing @var{x} instead of decrementing it.
3535
3536 @findex post_modify
3537 @item (post_modify:@var{m} @var{x} @var{y})
3538
3539 Represents the side effect of setting @var{x} to @var{y} and
3540 represents @var{x} before @var{x} is modified. @var{x} must be a
3541 @code{reg} or @code{mem}, but most machines allow only a @code{reg}.
3542 @var{m} must be the machine mode for pointers on the machine in use.
3543
3544 The expression @var{y} must be one of three forms:
3545 @code{(plus:@var{m} @var{x} @var{z})},
3546 @code{(minus:@var{m} @var{x} @var{z})}, or
3547 @code{(plus:@var{m} @var{x} @var{i})},
3548 where @var{z} is an index register and @var{i} is a constant.
3549
3550 Here is an example of its use:
3551
3552 @smallexample
3553 (mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
3554 (reg:SI 48))))
3555 @end smallexample
3556
3557 This says to modify pseudo register 42 by adding the contents of pseudo
3558 register 48 to it, after the use of what ever 42 points to.
3559
3560 @findex pre_modify
3561 @item (pre_modify:@var{m} @var{x} @var{expr})
3562 Similar except side effects happen before the use.
3563 @end table
3564
3565 These embedded side effect expressions must be used with care. Instruction
3566 patterns may not use them. Until the @samp{flow} pass of the compiler,
3567 they may occur only to represent pushes onto the stack. The @samp{flow}
3568 pass finds cases where registers are incremented or decremented in one
3569 instruction and used as an address shortly before or after; these cases are
3570 then transformed to use pre- or post-increment or -decrement.
3571
3572 If a register used as the operand of these expressions is used in
3573 another address in an insn, the original value of the register is used.
3574 Uses of the register outside of an address are not permitted within the
3575 same insn as a use in an embedded side effect expression because such
3576 insns behave differently on different machines and hence must be treated
3577 as ambiguous and disallowed.
3578
3579 An instruction that can be represented with an embedded side effect
3580 could also be represented using @code{parallel} containing an additional
3581 @code{set} to describe how the address register is altered. This is not
3582 done because machines that allow these operations at all typically
3583 allow them wherever a memory address is called for. Describing them as
3584 additional parallel stores would require doubling the number of entries
3585 in the machine description.
3586
3587 @node Assembler
3588 @section Assembler Instructions as Expressions
3589 @cindex assembler instructions in RTL
3590
3591 @cindex @code{asm_operands}, usage
3592 The RTX code @code{asm_operands} represents a value produced by a
3593 user-specified assembler instruction. It is used to represent
3594 an @code{asm} statement with arguments. An @code{asm} statement with
3595 a single output operand, like this:
3596
3597 @smallexample
3598 asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
3599 @end smallexample
3600
3601 @noindent
3602 is represented using a single @code{asm_operands} RTX which represents
3603 the value that is stored in @code{outputvar}:
3604
3605 @smallexample
3606 (set @var{rtx-for-outputvar}
3607 (asm_operands "foo %1,%2,%0" "a" 0
3608 [@var{rtx-for-addition-result} @var{rtx-for-*z}]
3609 [(asm_input:@var{m1} "g")
3610 (asm_input:@var{m2} "di")]))
3611 @end smallexample
3612
3613 @noindent
3614 Here the operands of the @code{asm_operands} RTX are the assembler
3615 template string, the output-operand's constraint, the index-number of the
3616 output operand among the output operands specified, a vector of input
3617 operand RTX's, and a vector of input-operand modes and constraints. The
3618 mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
3619 @code{*z}.
3620
3621 When an @code{asm} statement has multiple output values, its insn has
3622 several such @code{set} RTX's inside of a @code{parallel}. Each @code{set}
3623 contains an @code{asm_operands}; all of these share the same assembler
3624 template and vectors, but each contains the constraint for the respective
3625 output operand. They are also distinguished by the output-operand index
3626 number, which is 0, 1, @dots{} for successive output operands.
3627
3628 @node Debug Information
3629 @section Variable Location Debug Information in RTL
3630 @cindex Variable Location Debug Information in RTL
3631
3632 Variable tracking relies on @code{MEM_EXPR} and @code{REG_EXPR}
3633 annotations to determine what user variables memory and register
3634 references refer to.
3635
3636 Variable tracking at assignments uses these notes only when they refer
3637 to variables that live at fixed locations (e.g., addressable
3638 variables, global non-automatic variables). For variables whose
3639 location may vary, it relies on the following types of notes.
3640
3641 @table @code
3642 @findex var_location
3643 @item (var_location:@var{mode} @var{var} @var{exp} @var{stat})
3644 Binds variable @code{var}, a tree, to value @var{exp}, an RTL
3645 expression. It appears only in @code{NOTE_INSN_VAR_LOCATION} and
3646 @code{DEBUG_INSN}s, with slightly different meanings. @var{mode}, if
3647 present, represents the mode of @var{exp}, which is useful if it is a
3648 modeless expression. @var{stat} is only meaningful in notes,
3649 indicating whether the variable is known to be initialized or
3650 uninitialized.
3651
3652 @findex debug_expr
3653 @item (debug_expr:@var{mode} @var{decl})
3654 Stands for the value bound to the @code{DEBUG_EXPR_DECL} @var{decl},
3655 that points back to it, within value expressions in
3656 @code{VAR_LOCATION} nodes.
3657
3658 @findex debug_implicit_ptr
3659 @item (debug_implicit_ptr:@var{mode} @var{decl})
3660 Stands for the location of a @var{decl} that is no longer addressable.
3661
3662 @findex entry_value
3663 @item (entry_value:@var{mode} @var{decl})
3664 Stands for the value a @var{decl} had at the entry point of the
3665 containing function.
3666
3667 @findex debug_parameter_ref
3668 @item (debug_parameter_ref:@var{mode} @var{decl})
3669 Refers to a parameter that was completely optimized out.
3670
3671 @findex debug_marker
3672 @item (debug_marker:@var{mode})
3673 Marks a program location. With @code{VOIDmode}, it stands for the
3674 beginning of a statement, a recommended inspection point logically after
3675 all prior side effects, and before any subsequent side effects. With
3676 @code{BLKmode}, it indicates an inline entry point: the lexical block
3677 encoded in the @code{INSN_LOCATION} is the enclosing block that encloses
3678 the inlined function.
3679
3680 @end table
3681
3682 @node Insns
3683 @section Insns
3684 @cindex insns
3685
3686 The RTL representation of the code for a function is a doubly-linked
3687 chain of objects called @dfn{insns}. Insns are expressions with
3688 special codes that are used for no other purpose. Some insns are
3689 actual instructions; others represent dispatch tables for @code{switch}
3690 statements; others represent labels to jump to or various sorts of
3691 declarative information.
3692
3693 In addition to its own specific data, each insn must have a unique
3694 id-number that distinguishes it from all other insns in the current
3695 function (after delayed branch scheduling, copies of an insn with the
3696 same id-number may be present in multiple places in a function, but
3697 these copies will always be identical and will only appear inside a
3698 @code{sequence}), and chain pointers to the preceding and following
3699 insns. These three fields occupy the same position in every insn,
3700 independent of the expression code of the insn. They could be accessed
3701 with @code{XEXP} and @code{XINT}, but instead three special macros are
3702 always used:
3703
3704 @table @code
3705 @findex INSN_UID
3706 @item INSN_UID (@var{i})
3707 Accesses the unique id of insn @var{i}.
3708
3709 @findex PREV_INSN
3710 @item PREV_INSN (@var{i})
3711 Accesses the chain pointer to the insn preceding @var{i}.
3712 If @var{i} is the first insn, this is a null pointer.
3713
3714 @findex NEXT_INSN
3715 @item NEXT_INSN (@var{i})
3716 Accesses the chain pointer to the insn following @var{i}.
3717 If @var{i} is the last insn, this is a null pointer.
3718 @end table
3719
3720 @findex get_insns
3721 @findex get_last_insn
3722 The first insn in the chain is obtained by calling @code{get_insns}; the
3723 last insn is the result of calling @code{get_last_insn}. Within the
3724 chain delimited by these insns, the @code{NEXT_INSN} and
3725 @code{PREV_INSN} pointers must always correspond: if @var{insn} is not
3726 the first insn,
3727
3728 @smallexample
3729 NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
3730 @end smallexample
3731
3732 @noindent
3733 is always true and if @var{insn} is not the last insn,
3734
3735 @smallexample
3736 PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
3737 @end smallexample
3738
3739 @noindent
3740 is always true.
3741
3742 After delay slot scheduling, some of the insns in the chain might be
3743 @code{sequence} expressions, which contain a vector of insns. The value
3744 of @code{NEXT_INSN} in all but the last of these insns is the next insn
3745 in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
3746 is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
3747 which it is contained. Similar rules apply for @code{PREV_INSN}.
3748
3749 This means that the above invariants are not necessarily true for insns
3750 inside @code{sequence} expressions. Specifically, if @var{insn} is the
3751 first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
3752 is the insn containing the @code{sequence} expression, as is the value
3753 of @code{PREV_INSN (NEXT_INSN (@var{insn}))} if @var{insn} is the last
3754 insn in the @code{sequence} expression. You can use these expressions
3755 to find the containing @code{sequence} expression.
3756
3757 Every insn has one of the following expression codes:
3758
3759 @table @code
3760 @findex insn
3761 @item insn
3762 The expression code @code{insn} is used for instructions that do not jump
3763 and do not do function calls. @code{sequence} expressions are always
3764 contained in insns with code @code{insn} even if one of those insns
3765 should jump or do function calls.
3766
3767 Insns with code @code{insn} have four additional fields beyond the three
3768 mandatory ones listed above. These four are described in a table below.
3769
3770 @findex jump_insn
3771 @item jump_insn
3772 The expression code @code{jump_insn} is used for instructions that may
3773 jump (or, more generally, may contain @code{label_ref} expressions to
3774 which @code{pc} can be set in that instruction). If there is an
3775 instruction to return from the current function, it is recorded as a
3776 @code{jump_insn}.
3777
3778 @findex JUMP_LABEL
3779 @code{jump_insn} insns have the same extra fields as @code{insn} insns,
3780 accessed in the same way and in addition contain a field
3781 @code{JUMP_LABEL} which is defined once jump optimization has completed.
3782
3783 For simple conditional and unconditional jumps, this field contains
3784 the @code{code_label} to which this insn will (possibly conditionally)
3785 branch. In a more complex jump, @code{JUMP_LABEL} records one of the
3786 labels that the insn refers to; other jump target labels are recorded
3787 as @code{REG_LABEL_TARGET} notes. The exception is @code{addr_vec}
3788 and @code{addr_diff_vec}, where @code{JUMP_LABEL} is @code{NULL_RTX}
3789 and the only way to find the labels is to scan the entire body of the
3790 insn.
3791
3792 Return insns count as jumps, but their @code{JUMP_LABEL} is @code{RETURN}
3793 or @code{SIMPLE_RETURN}.
3794
3795 @findex call_insn
3796 @item call_insn
3797 The expression code @code{call_insn} is used for instructions that may do
3798 function calls. It is important to distinguish these instructions because
3799 they imply that certain registers and memory locations may be altered
3800 unpredictably.
3801
3802 @findex CALL_INSN_FUNCTION_USAGE
3803 @code{call_insn} insns have the same extra fields as @code{insn} insns,
3804 accessed in the same way and in addition contain a field
3805 @code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of
3806 @code{expr_list} expressions) containing @code{use}, @code{clobber} and
3807 sometimes @code{set} expressions that denote hard registers and
3808 @code{mem}s used or clobbered by the called function.
3809
3810 A @code{mem} generally points to a stack slot in which arguments passed
3811 to the libcall by reference (@pxref{Register Arguments,
3812 TARGET_PASS_BY_REFERENCE}) are stored. If the argument is
3813 caller-copied (@pxref{Register Arguments, TARGET_CALLEE_COPIES}),
3814 the stack slot will be mentioned in @code{clobber} and @code{use}
3815 entries; if it's callee-copied, only a @code{use} will appear, and the
3816 @code{mem} may point to addresses that are not stack slots.
3817
3818 Registers occurring inside a @code{clobber} in this list augment
3819 registers specified in @code{CALL_USED_REGISTERS} (@pxref{Register
3820 Basics}).
3821
3822 If the list contains a @code{set} involving two registers, it indicates
3823 that the function returns one of its arguments. Such a @code{set} may
3824 look like a no-op if the same register holds the argument and the return
3825 value.
3826
3827 @findex code_label
3828 @findex CODE_LABEL_NUMBER
3829 @item code_label
3830 A @code{code_label} insn represents a label that a jump insn can jump
3831 to. It contains two special fields of data in addition to the three
3832 standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
3833 number}, a number that identifies this label uniquely among all the
3834 labels in the compilation (not just in the current function).
3835 Ultimately, the label is represented in the assembler output as an
3836 assembler label, usually of the form @samp{L@var{n}} where @var{n} is
3837 the label number.
3838
3839 When a @code{code_label} appears in an RTL expression, it normally
3840 appears within a @code{label_ref} which represents the address of
3841 the label, as a number.
3842
3843 Besides as a @code{code_label}, a label can also be represented as a
3844 @code{note} of type @code{NOTE_INSN_DELETED_LABEL}.
3845
3846 @findex LABEL_NUSES
3847 The field @code{LABEL_NUSES} is only defined once the jump optimization
3848 phase is completed. It contains the number of times this label is
3849 referenced in the current function.
3850
3851 @findex LABEL_KIND
3852 @findex SET_LABEL_KIND
3853 @findex LABEL_ALT_ENTRY_P
3854 @cindex alternate entry points
3855 The field @code{LABEL_KIND} differentiates four different types of
3856 labels: @code{LABEL_NORMAL}, @code{LABEL_STATIC_ENTRY},
3857 @code{LABEL_GLOBAL_ENTRY}, and @code{LABEL_WEAK_ENTRY}. The only labels
3858 that do not have type @code{LABEL_NORMAL} are @dfn{alternate entry
3859 points} to the current function. These may be static (visible only in
3860 the containing translation unit), global (exposed to all translation
3861 units), or weak (global, but can be overridden by another symbol with the
3862 same name).
3863
3864 Much of the compiler treats all four kinds of label identically. Some
3865 of it needs to know whether or not a label is an alternate entry point;
3866 for this purpose, the macro @code{LABEL_ALT_ENTRY_P} is provided. It is
3867 equivalent to testing whether @samp{LABEL_KIND (label) == LABEL_NORMAL}.
3868 The only place that cares about the distinction between static, global,
3869 and weak alternate entry points, besides the front-end code that creates
3870 them, is the function @code{output_alternate_entry_point}, in
3871 @file{final.cc}.
3872
3873 To set the kind of a label, use the @code{SET_LABEL_KIND} macro.
3874
3875 @findex jump_table_data
3876 @item jump_table_data
3877 A @code{jump_table_data} insn is a placeholder for the jump-table data
3878 of a @code{casesi} or @code{tablejump} insn. They are placed after
3879 a @code{tablejump_p} insn. A @code{jump_table_data} insn is not part of
3880 a basic block but it is associated with the basic block that ends with
3881 the @code{tablejump_p} insn. The @code{PATTERN} of a @code{jump_table_data}
3882 is always either an @code{addr_vec} or an @code{addr_diff_vec}, and a
3883 @code{jump_table_data} insn is always preceded by a @code{code_label}.
3884 The @code{tablejump_p} insn refers to that @code{code_label} via its
3885 @code{JUMP_LABEL}.
3886
3887 @findex barrier
3888 @item barrier
3889 Barriers are placed in the instruction stream when control cannot flow
3890 past them. They are placed after unconditional jump instructions to
3891 indicate that the jumps are unconditional and after calls to
3892 @code{volatile} functions, which do not return (e.g., @code{exit}).
3893 They contain no information beyond the three standard fields.
3894
3895 @findex note
3896 @findex NOTE_LINE_NUMBER
3897 @findex NOTE_SOURCE_FILE
3898 @item note
3899 @code{note} insns are used to represent additional debugging and
3900 declarative information. They contain two nonstandard fields, an
3901 integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
3902 string accessed with @code{NOTE_SOURCE_FILE}.
3903
3904 If @code{NOTE_LINE_NUMBER} is positive, the note represents the
3905 position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
3906 that the line came from. These notes control generation of line
3907 number data in the assembler output.
3908
3909 Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
3910 code with one of the following values (and @code{NOTE_SOURCE_FILE}
3911 must contain a null pointer):
3912
3913 @table @code
3914 @findex NOTE_INSN_DELETED
3915 @item NOTE_INSN_DELETED
3916 Such a note is completely ignorable. Some passes of the compiler
3917 delete insns by altering them into notes of this kind.
3918
3919 @findex NOTE_INSN_DELETED_LABEL
3920 @item NOTE_INSN_DELETED_LABEL
3921 This marks what used to be a @code{code_label}, but was not used for other
3922 purposes than taking its address and was transformed to mark that no
3923 code jumps to it.
3924
3925 @findex NOTE_INSN_BLOCK_BEG
3926 @findex NOTE_INSN_BLOCK_END
3927 @item NOTE_INSN_BLOCK_BEG
3928 @itemx NOTE_INSN_BLOCK_END
3929 These types of notes indicate the position of the beginning and end
3930 of a level of scoping of variable names. They control the output
3931 of debugging information.
3932
3933 @findex NOTE_INSN_EH_REGION_BEG
3934 @findex NOTE_INSN_EH_REGION_END
3935 @item NOTE_INSN_EH_REGION_BEG
3936 @itemx NOTE_INSN_EH_REGION_END
3937 These types of notes indicate the position of the beginning and end of a
3938 level of scoping for exception handling. @code{NOTE_EH_HANDLER}
3939 identifies which region is associated with these notes.
3940
3941 @findex NOTE_INSN_FUNCTION_BEG
3942 @item NOTE_INSN_FUNCTION_BEG
3943 Appears at the start of the function body, after the function
3944 prologue.
3945
3946 @findex NOTE_INSN_VAR_LOCATION
3947 @findex NOTE_VAR_LOCATION
3948 @item NOTE_INSN_VAR_LOCATION
3949 This note is used to generate variable location debugging information.
3950 It indicates that the user variable in its @code{VAR_LOCATION} operand
3951 is at the location given in the RTL expression, or holds a value that
3952 can be computed by evaluating the RTL expression from that static
3953 point in the program up to the next such note for the same user
3954 variable.
3955
3956 @findex NOTE_INSN_BEGIN_STMT
3957 @item NOTE_INSN_BEGIN_STMT
3958 This note is used to generate @code{is_stmt} markers in line number
3959 debugging information. It indicates the beginning of a user
3960 statement.
3961
3962 @findex NOTE_INSN_INLINE_ENTRY
3963 @item NOTE_INSN_INLINE_ENTRY
3964 This note is used to generate @code{entry_pc} for inlined subroutines in
3965 debugging information. It indicates an inspection point at which all
3966 arguments for the inlined function have been bound, and before its first
3967 statement.
3968
3969 @end table
3970
3971 These codes are printed symbolically when they appear in debugging dumps.
3972
3973 @findex debug_insn
3974 @findex INSN_VAR_LOCATION
3975 @item debug_insn
3976 The expression code @code{debug_insn} is used for pseudo-instructions
3977 that hold debugging information for variable tracking at assignments
3978 (see @option{-fvar-tracking-assignments} option). They are the RTL
3979 representation of @code{GIMPLE_DEBUG} statements
3980 (@ref{@code{GIMPLE_DEBUG}}), with a @code{VAR_LOCATION} operand that
3981 binds a user variable tree to an RTL representation of the
3982 @code{value} in the corresponding statement. A @code{DEBUG_EXPR} in
3983 it stands for the value bound to the corresponding
3984 @code{DEBUG_EXPR_DECL}.
3985
3986 @code{GIMPLE_DEBUG_BEGIN_STMT} and @code{GIMPLE_DEBUG_INLINE_ENTRY} are
3987 expanded to RTL as a @code{DEBUG_INSN} with a @code{DEBUG_MARKER}
3988 @code{PATTERN}; the difference is the RTL mode: the former's
3989 @code{DEBUG_MARKER} is @code{VOIDmode}, whereas the latter is
3990 @code{BLKmode}; information about the inlined function can be taken from
3991 the lexical block encoded in the @code{INSN_LOCATION}. These
3992 @code{DEBUG_INSN}s, that do not carry @code{VAR_LOCATION} information,
3993 just @code{DEBUG_MARKER}s, can be detected by testing
3994 @code{DEBUG_MARKER_INSN_P}, whereas those that do can be recognized as
3995 @code{DEBUG_BIND_INSN_P}.
3996
3997 Throughout optimization passes, @code{DEBUG_INSN}s are not reordered
3998 with respect to each other, particularly during scheduling. Binding
3999 information is kept in pseudo-instruction form, so that, unlike notes,
4000 it gets the same treatment and adjustments that regular instructions
4001 would. It is the variable tracking pass that turns these
4002 pseudo-instructions into @code{NOTE_INSN_VAR_LOCATION},
4003 @code{NOTE_INSN_BEGIN_STMT} and @code{NOTE_INSN_INLINE_ENTRY} notes,
4004 analyzing control flow, value equivalences and changes to registers and
4005 memory referenced in value expressions, propagating the values of debug
4006 temporaries and determining expressions that can be used to compute the
4007 value of each user variable at as many points (ranges, actually) in the
4008 program as possible.
4009
4010 Unlike @code{NOTE_INSN_VAR_LOCATION}, the value expression in an
4011 @code{INSN_VAR_LOCATION} denotes a value at that specific point in the
4012 program, rather than an expression that can be evaluated at any later
4013 point before an overriding @code{VAR_LOCATION} is encountered. E.g.,
4014 if a user variable is bound to a @code{REG} and then a subsequent insn
4015 modifies the @code{REG}, the note location would keep mapping the user
4016 variable to the register across the insn, whereas the insn location
4017 would keep the variable bound to the value, so that the variable
4018 tracking pass would emit another location note for the variable at the
4019 point in which the register is modified.
4020
4021 @end table
4022
4023 @cindex @code{TImode}, in @code{insn}
4024 @cindex @code{HImode}, in @code{insn}
4025 @cindex @code{QImode}, in @code{insn}
4026 The machine mode of an insn is normally @code{VOIDmode}, but some
4027 phases use the mode for various purposes.
4028
4029 The common subexpression elimination pass sets the mode of an insn to
4030 @code{QImode} when it is the first insn in a block that has already
4031 been processed.
4032
4033 The second Haifa scheduling pass, for targets that can multiple issue,
4034 sets the mode of an insn to @code{TImode} when it is believed that the
4035 instruction begins an issue group. That is, when the instruction
4036 cannot issue simultaneously with the previous. This may be relied on
4037 by later passes, in particular machine-dependent reorg.
4038
4039 Here is a table of the extra fields of @code{insn}, @code{jump_insn}
4040 and @code{call_insn} insns:
4041
4042 @table @code
4043 @findex PATTERN
4044 @item PATTERN (@var{i})
4045 An expression for the side effect performed by this insn. This must
4046 be one of the following codes: @code{set}, @code{call}, @code{use},
4047 @code{clobber}, @code{return}, @code{simple_return}, @code{asm_input},
4048 @code{asm_output}, @code{addr_vec}, @code{addr_diff_vec},
4049 @code{trap_if}, @code{unspec}, @code{unspec_volatile},
4050 @code{parallel}, @code{cond_exec}, or @code{sequence}. If it is a
4051 @code{parallel}, each element of the @code{parallel} must be one these
4052 codes, except that @code{parallel} expressions cannot be nested and
4053 @code{addr_vec} and @code{addr_diff_vec} are not permitted inside a
4054 @code{parallel} expression.
4055
4056 @findex INSN_CODE
4057 @item INSN_CODE (@var{i})
4058 An integer that says which pattern in the machine description matches
4059 this insn, or @minus{}1 if the matching has not yet been attempted.
4060
4061 Such matching is never attempted and this field remains @minus{}1 on an insn
4062 whose pattern consists of a single @code{use}, @code{clobber},
4063 @code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.
4064
4065 @findex asm_noperands
4066 Matching is also never attempted on insns that result from an @code{asm}
4067 statement. These contain at least one @code{asm_operands} expression.
4068 The function @code{asm_noperands} returns a non-negative value for
4069 such insns.
4070
4071 In the debugging output, this field is printed as a number followed by
4072 a symbolic representation that locates the pattern in the @file{md}
4073 file as some small positive or negative offset from a named pattern.
4074
4075 @findex REG_NOTES
4076 @item REG_NOTES (@var{i})
4077 A list (chain of @code{expr_list}, @code{insn_list} and @code{int_list}
4078 expressions) giving miscellaneous information about the insn. It is often
4079 information pertaining to the registers used in this insn.
4080 @end table
4081
4082 The @code{REG_NOTES} field of an insn is a chain that includes
4083 @code{expr_list} and @code{int_list} expressions as well as @code{insn_list}
4084 expressions. There are several
4085 kinds of register notes, which are distinguished by the machine mode, which
4086 in a register note is really understood as being an @code{enum reg_note}.
4087 The first operand @var{op} of the note is data whose meaning depends on
4088 the kind of note.
4089
4090 @findex REG_NOTE_KIND
4091 @findex PUT_REG_NOTE_KIND
4092 The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of
4093 register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND
4094 (@var{x}, @var{newkind})} sets the register note type of @var{x} to be
4095 @var{newkind}.
4096
4097 Register notes are of three classes: They may say something about an
4098 input to an insn, they may say something about an output of an insn, or
4099 they may create a linkage between two insns.
4100
4101 These register notes annotate inputs to an insn:
4102
4103 @table @code
4104 @findex REG_DEAD
4105 @item REG_DEAD
4106 The value in @var{op} dies in this insn; that is to say, altering the
4107 value immediately after this insn would not affect the future behavior
4108 of the program.
4109
4110 It does not follow that the register @var{op} has no useful value after
4111 this insn since @var{op} is not necessarily modified by this insn.
4112 Rather, no subsequent instruction uses the contents of @var{op}.
4113
4114 @findex REG_UNUSED
4115 @item REG_UNUSED
4116 The register @var{op} being set by this insn will not be used in a
4117 subsequent insn. This differs from a @code{REG_DEAD} note, which
4118 indicates that the value in an input will not be used subsequently.
4119 These two notes are independent; both may be present for the same
4120 register.
4121
4122 @findex REG_INC
4123 @item REG_INC
4124 The register @var{op} is incremented (or decremented; at this level
4125 there is no distinction) by an embedded side effect inside this insn.
4126 This means it appears in a @code{post_inc}, @code{pre_inc},
4127 @code{post_dec} or @code{pre_dec} expression.
4128
4129 @findex REG_NONNEG
4130 @item REG_NONNEG
4131 The register @var{op} is known to have a nonnegative value when this
4132 insn is reached. This is used by special looping instructions
4133 that terminate when the register goes negative.
4134
4135 The @code{REG_NONNEG} note is added only to @samp{doloop_end}
4136 insns, if its pattern uses a @code{ge} condition.
4137
4138 @findex REG_LABEL_OPERAND
4139 @item REG_LABEL_OPERAND
4140 This insn uses @var{op}, a @code{code_label} or a @code{note} of type
4141 @code{NOTE_INSN_DELETED_LABEL}, but is not a @code{jump_insn}, or it
4142 is a @code{jump_insn} that refers to the operand as an ordinary
4143 operand. The label may still eventually be a jump target, but if so
4144 in an indirect jump in a subsequent insn. The presence of this note
4145 allows jump optimization to be aware that @var{op} is, in fact, being
4146 used, and flow optimization to build an accurate flow graph.
4147
4148 @findex REG_LABEL_TARGET
4149 @item REG_LABEL_TARGET
4150 This insn is a @code{jump_insn} but not an @code{addr_vec} or
4151 @code{addr_diff_vec}. It uses @var{op}, a @code{code_label} as a
4152 direct or indirect jump target. Its purpose is similar to that of
4153 @code{REG_LABEL_OPERAND}. This note is only present if the insn has
4154 multiple targets; the last label in the insn (in the highest numbered
4155 insn-field) goes into the @code{JUMP_LABEL} field and does not have a
4156 @code{REG_LABEL_TARGET} note. @xref{Insns, JUMP_LABEL}.
4157
4158 @findex REG_SETJMP
4159 @item REG_SETJMP
4160 Appears attached to each @code{CALL_INSN} to @code{setjmp} or a
4161 related function.
4162 @end table
4163
4164 The following notes describe attributes of outputs of an insn:
4165
4166 @table @code
4167 @findex REG_EQUIV
4168 @findex REG_EQUAL
4169 @item REG_EQUIV
4170 @itemx REG_EQUAL
4171 This note is only valid on an insn that sets only one register and
4172 indicates that that register will be equal to @var{op} at run time; the
4173 scope of this equivalence differs between the two types of notes. The
4174 value which the insn explicitly copies into the register may look
4175 different from @var{op}, but they will be equal at run time. If the
4176 output of the single @code{set} is a @code{strict_low_part} or
4177 @code{zero_extract} expression, the note refers to the register that
4178 is contained in its first operand.
4179
4180 For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout
4181 the entire function, and could validly be replaced in all its
4182 occurrences by @var{op}. (``Validly'' here refers to the data flow of
4183 the program; simple replacement may make some insns invalid.) For
4184 example, when a constant is loaded into a register that is never
4185 assigned any other value, this kind of note is used.
4186
4187 When a parameter is copied into a pseudo-register at entry to a function,
4188 a note of this kind records that the register is equivalent to the stack
4189 slot where the parameter was passed. Although in this case the register
4190 may be set by other insns, it is still valid to replace the register
4191 by the stack slot throughout the function.
4192
4193 A @code{REG_EQUIV} note is also used on an instruction which copies a
4194 register parameter into a pseudo-register at entry to a function, if
4195 there is a stack slot where that parameter could be stored. Although
4196 other insns may set the pseudo-register, it is valid for the compiler to
4197 replace the pseudo-register by stack slot throughout the function,
4198 provided the compiler ensures that the stack slot is properly
4199 initialized by making the replacement in the initial copy instruction as
4200 well. This is used on machines for which the calling convention
4201 allocates stack space for register parameters. See
4202 @code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}.
4203
4204 In the case of @code{REG_EQUAL}, the register that is set by this insn
4205 will be equal to @var{op} at run time at the end of this insn but not
4206 necessarily elsewhere in the function. In this case, @var{op}
4207 is typically an arithmetic expression. For example, when a sequence of
4208 insns such as a library call is used to perform an arithmetic operation,
4209 this kind of note is attached to the insn that produces or copies the
4210 final value.
4211
4212 These two notes are used in different ways by the compiler passes.
4213 @code{REG_EQUAL} is used by passes prior to register allocation (such as
4214 common subexpression elimination and loop optimization) to tell them how
4215 to think of that value. @code{REG_EQUIV} notes are used by register
4216 allocation to indicate that there is an available substitute expression
4217 (either a constant or a @code{mem} expression for the location of a
4218 parameter on the stack) that may be used in place of a register if
4219 insufficient registers are available.
4220
4221 Except for stack homes for parameters, which are indicated by a
4222 @code{REG_EQUIV} note and are not useful to the early optimization
4223 passes and pseudo registers that are equivalent to a memory location
4224 throughout their entire life, which is not detected until later in
4225 the compilation, all equivalences are initially indicated by an attached
4226 @code{REG_EQUAL} note. In the early stages of register allocation, a
4227 @code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if
4228 @var{op} is a constant and the insn represents the only set of its
4229 destination register.
4230
4231 Thus, compiler passes prior to register allocation need only check for
4232 @code{REG_EQUAL} notes and passes subsequent to register allocation
4233 need only check for @code{REG_EQUIV} notes.
4234 @end table
4235
4236 These notes describe linkages between insns. They occur in pairs: one
4237 insn has one of a pair of notes that points to a second insn, which has
4238 the inverse note pointing back to the first insn.
4239
4240 @table @code
4241 @findex REG_DEP_TRUE
4242 @item REG_DEP_TRUE
4243 This indicates a true dependence (a read after write dependence).
4244
4245 @findex REG_DEP_OUTPUT
4246 @item REG_DEP_OUTPUT
4247 This indicates an output dependence (a write after write dependence).
4248
4249 @findex REG_DEP_ANTI
4250 @item REG_DEP_ANTI
4251 This indicates an anti dependence (a write after read dependence).
4252
4253 @end table
4254
4255 These notes describe information gathered from gcov profile data. They
4256 are stored in the @code{REG_NOTES} field of an insn.
4257
4258 @table @code
4259 @findex REG_BR_PROB
4260 @item REG_BR_PROB
4261 This is used to specify the ratio of branches to non-branches of a
4262 branch insn according to the profile data. The note is represented
4263 as an @code{int_list} expression whose integer value is an encoding
4264 of @code{profile_probability} type. @code{profile_probability} provide
4265 member function @code{from_reg_br_prob_note} and @code{to_reg_br_prob_note}
4266 to extract and store the probability into the RTL encoding.
4267
4268 @findex REG_BR_PRED
4269 @item REG_BR_PRED
4270 These notes are found in JUMP insns after delayed branch scheduling
4271 has taken place. They indicate both the direction and the likelihood
4272 of the JUMP@. The format is a bitmask of ATTR_FLAG_* values.
4273
4274 @findex REG_FRAME_RELATED_EXPR
4275 @item REG_FRAME_RELATED_EXPR
4276 This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression
4277 is used in place of the actual insn pattern. This is done in cases where
4278 the pattern is either complex or misleading.
4279 @end table
4280
4281 The note @code{REG_CALL_NOCF_CHECK} is used in conjunction with the
4282 @option{-fcf-protection=branch} option. The note is set if a
4283 @code{nocf_check} attribute is specified for a function type or a
4284 pointer to function type. The note is stored in the @code{REG_NOTES}
4285 field of an insn.
4286
4287 @table @code
4288 @findex REG_CALL_NOCF_CHECK
4289 @item REG_CALL_NOCF_CHECK
4290 Users have control through the @code{nocf_check} attribute to identify
4291 which calls to a function should be skipped from control-flow instrumentation
4292 when the option @option{-fcf-protection=branch} is specified. The compiler
4293 puts a @code{REG_CALL_NOCF_CHECK} note on each @code{CALL_INSN} instruction
4294 that has a function type marked with a @code{nocf_check} attribute.
4295 @end table
4296
4297 For convenience, the machine mode in an @code{insn_list} or
4298 @code{expr_list} is printed using these symbolic codes in debugging dumps.
4299
4300 @findex insn_list
4301 @findex expr_list
4302 The only difference between the expression codes @code{insn_list} and
4303 @code{expr_list} is that the first operand of an @code{insn_list} is
4304 assumed to be an insn and is printed in debugging dumps as the insn's
4305 unique id; the first operand of an @code{expr_list} is printed in the
4306 ordinary way as an expression.
4307
4308 @node Calls
4309 @section RTL Representation of Function-Call Insns
4310 @cindex calling functions in RTL
4311 @cindex RTL function-call insns
4312 @cindex function-call insns
4313
4314 Insns that call subroutines have the RTL expression code @code{call_insn}.
4315 These insns must satisfy special rules, and their bodies must use a special
4316 RTL expression code, @code{call}.
4317
4318 @cindex @code{call} usage
4319 A @code{call} expression has two operands, as follows:
4320
4321 @smallexample
4322 (call (mem:@var{fm} @var{addr}) @var{nbytes})
4323 @end smallexample
4324
4325 @noindent
4326 Here @var{nbytes} is an operand that represents the number of bytes of
4327 argument data being passed to the subroutine, @var{fm} is a machine mode
4328 (which must equal as the definition of the @code{FUNCTION_MODE} macro in
4329 the machine description) and @var{addr} represents the address of the
4330 subroutine.
4331
4332 For a subroutine that returns no value, the @code{call} expression as
4333 shown above is the entire body of the insn, except that the insn might
4334 also contain @code{use} or @code{clobber} expressions.
4335
4336 @cindex @code{BLKmode}, and function return values
4337 For a subroutine that returns a value whose mode is not @code{BLKmode},
4338 the value is returned in a hard register. If this register's number is
4339 @var{r}, then the body of the call insn looks like this:
4340
4341 @smallexample
4342 (set (reg:@var{m} @var{r})
4343 (call (mem:@var{fm} @var{addr}) @var{nbytes}))
4344 @end smallexample
4345
4346 @noindent
4347 This RTL expression makes it clear (to the optimizer passes) that the
4348 appropriate register receives a useful value in this insn.
4349
4350 When a subroutine returns a @code{BLKmode} value, it is handled by
4351 passing to the subroutine the address of a place to store the value.
4352 So the call insn itself does not ``return'' any value, and it has the
4353 same RTL form as a call that returns nothing.
4354
4355 On some machines, the call instruction itself clobbers some register,
4356 for example to contain the return address. @code{call_insn} insns
4357 on these machines should have a body which is a @code{parallel}
4358 that contains both the @code{call} expression and @code{clobber}
4359 expressions that indicate which registers are destroyed. Similarly,
4360 if the call instruction requires some register other than the stack
4361 pointer that is not explicitly mentioned in its RTL, a @code{use}
4362 subexpression should mention that register.
4363
4364 Functions that are called are assumed to modify all registers listed in
4365 the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register
4366 Basics}) and, with the exception of @code{const} functions and library
4367 calls, to modify all of memory.
4368
4369 Insns containing just @code{use} expressions directly precede the
4370 @code{call_insn} insn to indicate which registers contain inputs to the
4371 function. Similarly, if registers other than those in
4372 @code{CALL_USED_REGISTERS} are clobbered by the called function, insns
4373 containing a single @code{clobber} follow immediately after the call to
4374 indicate which registers.
4375
4376 @node RTL SSA
4377 @section On-the-Side SSA Form for RTL
4378 @cindex SSA, RTL form
4379 @cindex RTL SSA
4380
4381 The patterns of an individual RTL instruction describe which registers
4382 are inputs to that instruction and which registers are outputs from
4383 that instruction. However, it is often useful to know where the
4384 definition of a register input comes from and where the result of
4385 a register output is used. One way of obtaining this information
4386 is to use the RTL SSA form, which provides a Static Single Assignment
4387 representation of the RTL instructions.
4388
4389 The RTL SSA code is located in the @file{rtl-ssa} subdirectory of the GCC
4390 source tree. This section only gives a brief overview of it; please
4391 see the comments in the source code for more details.
4392
4393 @menu
4394 * Using RTL SSA:: What a pass needs to do to use the RTL SSA form
4395 * RTL SSA Instructions:: How instructions are represented and organized
4396 * RTL SSA Basic Blocks:: How instructions are grouped into blocks
4397 * RTL SSA Resources:: How registers and memory are represented
4398 * RTL SSA Accesses:: How register and memory accesses are represented
4399 * RTL SSA Phi Nodes:: How multiple sources are combined into one
4400 * RTL SSA Access Lists:: How accesses are chained together
4401 * Changing RTL Instructions:: How to use the RTL SSA framework to change insns
4402 @end menu
4403
4404 @node Using RTL SSA
4405 @subsection Using RTL SSA in a pass
4406
4407 A pass that wants to use the RTL SSA form should start with the following:
4408
4409 @smallexample
4410 #define INCLUDE_ALGORITHM
4411 #define INCLUDE_FUNCTIONAL
4412 #define INCLUDE_ARRAY
4413 #include "config.h"
4414 #include "system.h"
4415 #include "coretypes.h"
4416 #include "backend.h"
4417 #include "rtl.h"
4418 #include "df.h"
4419 #include "rtl-ssa.h"
4420 @end smallexample
4421
4422 All the RTL SSA code is contained in the @code{rtl_ssa} namespace,
4423 so most passes will then want to do:
4424
4425 @smallexample
4426 using namespace rtl_ssa;
4427 @end smallexample
4428
4429 However, this is purely a matter of taste, and the examples in the rest of
4430 this section do not require it.
4431
4432 The RTL SSA represention is an optional on-the-side feature that applies
4433 on top of the normal RTL instructions. It is currently local to individual
4434 RTL passes and is not maintained across passes.
4435
4436 However, in order to allow the RTL SSA information to be preserved across
4437 passes in future, @samp{crtl->ssa} points to the current function's
4438 SSA form (if any). Passes that want to use the RTL SSA form should
4439 first do:
4440
4441 @smallexample
4442 crtl->ssa = new rtl_ssa::function_info (@var{fn});
4443 @end smallexample
4444
4445 where @var{fn} is the function that the pass is processing.
4446 (Passes that are @code{using namespace rtl_ssa} do not need
4447 the @samp{rtl_ssa::}.)
4448
4449 Once the pass has finished with the SSA form, it should do the following:
4450
4451 @smallexample
4452 free_dominance_info (CDI_DOMINATORS);
4453 if (crtl->ssa->perform_pending_updates ())
4454 cleanup_cfg (0);
4455
4456 delete crtl->ssa;
4457 crtl->ssa = nullptr;
4458 @end smallexample
4459
4460 The @code{free_dominance_info} call is necessary because
4461 dominance information is not currently maintained between RTL passes.
4462 The next two lines commit any changes to the RTL instructions that
4463 were queued for later; see the comment above the declaration of
4464 @code{perform_pending_updates} for details. The final two lines
4465 discard the RTL SSA form and free the associated memory.
4466
4467 @node RTL SSA Instructions
4468 @subsection RTL SSA Instructions
4469
4470 @cindex RPO
4471 @cindex reverse postorder
4472 @cindex instructions, RTL SSA
4473 @findex rtl_ssa::insn_info
4474 RTL SSA instructions are represented by an @code{rtl_ssa::insn_info}.
4475 These instructions are chained together in a single list that follows
4476 a reverse postorder (RPO) traversal of the function. This means that
4477 if any path through the function can execute an instruction @var{I1}
4478 and then later execute an instruction @var{I2} for the first time,
4479 @var{I1} appears before @var{I2} in the list@footnote{Note that this
4480 order is different from the order of the underlying RTL instructions,
4481 which follow machine code order instead.}.
4482
4483 Two RTL SSA instructions can be compared to find which instruction
4484 occurs earlier than the other in the RPO@. One way to do this is
4485 to use the C++ comparison operators, such as:
4486
4487 @example
4488 *@var{insn1} < *@var{insn2}
4489 @end example
4490
4491 Another way is to use the @code{compare_with} function:
4492
4493 @example
4494 @var{insn1}->compare_with (@var{insn2})
4495 @end example
4496
4497 This expression is greater than zero if @var{insn1} comes after @var{insn2}
4498 in the RPO, less than zero if @var{insn1} comes before @var{insn2} in the
4499 RPO, or zero if @var{insn1} and @var{insn2} are the same. This order is
4500 maintained even if instructions are added to the function or moved around.
4501
4502 The main purpose of @code{rtl_ssa::insn_info} is to hold
4503 SSA information about an instruction. However, it also caches
4504 certain properties of the instruction, such as whether it is an
4505 inline assembly instruction, whether it has volatile accesses, and so on.
4506
4507 @node RTL SSA Basic Blocks
4508 @subsection RTL SSA Basic Blocks
4509
4510 @cindex basic blocks, RTL SSA
4511 @findex basic_block
4512 @findex rtl_ssa::bb_info
4513 RTL SSA instructions (@pxref{RTL SSA Instructions}) are organized into
4514 basic blocks, with each block being represented by an @code{rtl_ssa:bb_info}.
4515 There is a one-to-one mapping between these @code{rtl_ssa:bb_info}
4516 structures and the underlying CFG @code{basic_block} structures
4517 (@pxref{Basic Blocks}).
4518
4519 @cindex ``real'' instructions, RTL SSA
4520 @anchor{real RTL SSA insns}
4521 If a CFG basic block @var{bb} contains an RTL instruction @var{insn},
4522 the RTL SSA represenation of @var{bb} also contains an RTL SSA representation
4523 of @var{insn}@footnote{Note that this excludes non-instruction things like
4524 @code{note}s and @code{barrier}s that also appear in the chain of RTL
4525 instructions.}. Within RTL SSA, these instructions are referred to as
4526 ``real'' instructions. These real instructions fall into two groups:
4527 debug instructions and nondebug instructions. Only nondebug instructions
4528 should affect code generation decisions.
4529
4530 In addition, each RTL SSA basic block has two ``artificial''
4531 instructions: a ``head'' instruction that comes before all the real
4532 instructions and an ``end'' instruction that comes after all real
4533 instructions. These instructions exist to represent things that
4534 are conceptually defined or used at the start and end of a basic block.
4535 The instructions always exist, even if they do not currently do anything.
4536
4537 Like instructions, these blocks are chained together in a reverse
4538 postorder. This list includes the entry block (which always comes
4539 first) and the exit block (which always comes last).
4540
4541 @cindex extended basic blocks, RTL SSA
4542 @findex rtl_ssa::ebb_info
4543 RTL SSA basic blocks are chained together into ``extended basic blocks''
4544 (EBBs), represented by an @code{rtl_ssa::ebb_info}. Extended basic
4545 blocks contain one or more basic blocks. They have the property
4546 that if a block @var{bby} comes immediately after a block @var{bbx}
4547 in an EBB, then @var{bby} can only be reached by @var{bbx}; in other words,
4548 @var{bbx} is the sole predecessor of @var{bby}.
4549
4550 Each extended basic block starts with an artificial ``phi node''
4551 instruction. This instruction defines all phi nodes for the EBB
4552 (@pxref{RTL SSA Phi Nodes}). (Individual blocks in an EBB do not
4553 need phi nodes because their live values can only come from one source.)
4554
4555 The contents of a function are therefore represented using a
4556 four-level hierarchy:
4557
4558 @itemize @bullet
4559 @item
4560 functions (@code{rtl_ssa::function_info}), which contain @dots{}
4561
4562 @item
4563 extended basic blocks (@code{rtl_ssa::ebb_info}), which contain @dots{}
4564
4565 @item
4566 basic blocks (@code{rtl_ssa::bb_info}), which contain @dots{}
4567
4568 @item
4569 instructions (@code{rtl_ssa::insn_info})
4570 @end itemize
4571
4572 In dumps, a basic block is identified as @code{bb@var{n}}, where @var{n}
4573 is the index of the associated CFG @code{basic_block} structure.
4574 An EBB is in turn identified by the index of its first block.
4575 For example, an EBB that contains @samp{bb10}, @code{bb5}, @code{bb6}
4576 and @code{bb9} is identified as @var{ebb10}.
4577
4578 @node RTL SSA Resources
4579 @subsection RTL SSA Resources
4580
4581 The RTL SSA form tracks two types of ``resource'': registers and memory.
4582 Each hard and pseudo register is a separate resource. Memory is a
4583 single unified resource, like it is in GIMPLE (@pxref{GIMPLE}).
4584
4585 Each resource has a unique identifier. The unique identifier for a
4586 register is simply its register number. The unique identifier for
4587 memory is a special register number called @code{MEM_REGNO}.
4588
4589 Since resource numbers so closely match register numbers, it is sometimes
4590 convenient to refer to them simply as register numbers, or ``regnos''
4591 for short. However, the RTL SSA form also provides an abstraction
4592 of resources in the form of @code{rtl_ssa::resource_info}.
4593 This is a lightweight class that records both the regno of a resource
4594 and the @code{machine_mode} that the resource has (@pxref{Machine Modes}).
4595 It has functions for testing whether a resource is a register or memory.
4596 In principle it could be extended to other kinds of resource in future.
4597
4598 @node RTL SSA Accesses
4599 @subsection RTL SSA Register and Memory Accesses
4600
4601 In the RTL SSA form, most reads or writes of a resource are
4602 represented as a @code{rtl_ssa::access_info}@footnote{The exceptions
4603 are call clobbers, which are generally represented separately.
4604 See the comment above @code{rtl_ssa::insn_info} for details.}.
4605 These @code{rtl_ssa::access_info}s are organized into the following
4606 class hierarchy:
4607
4608 @findex rtl_ssa::access_info
4609 @findex rtl_ssa::use_info
4610 @findex rtl_ssa::def_info
4611 @findex rtl_ssa::clobber_info
4612 @findex rtl_ssa::set_info
4613 @findex rtl_ssa::phi_info
4614 @smallexample
4615 rtl_ssa::access_info
4616 |
4617 +-- rtl_ssa::use_info
4618 |
4619 +-- rtl_ssa::def_info
4620 |
4621 +-- rtl_ssa::clobber_info
4622 |
4623 +-- rtl_ssa::set_info
4624 |
4625 +-- rtl_ssa::phi_info
4626 @end smallexample
4627
4628 A @code{rtl_ssa::use_info} represents a read or use of a resource and
4629 a @code{rtl_ssa::def_info} represents a write or definition of a resource.
4630 As in the main RTL representation, there are two basic types of
4631 definition: clobbers and sets. The difference is that a clobber
4632 leaves the register with an unspecified value that cannot be used
4633 or relied on by later instructions, while a set leaves the register
4634 with a known value that later instructions could use if they wanted to.
4635 A @code{rtl_ssa::clobber_info} represents a clobber and
4636 a @code{rtl_ssa::set_info} represent a set.
4637
4638 Each @code{rtl_ssa::use_info} records which single @code{rtl_ssa::set_info}
4639 provides the value of the resource; this is null if the resource is
4640 completely undefined at the point of use. Each @code{rtl_ssa::set_info}
4641 in turn records all the @code{rtl_ssa::use_info}s that use its value.
4642
4643 If a value of a resource can come from multiple sources,
4644 a @code{rtl_ssa::phi_info} brings those multiple sources together
4645 into a single definition (@pxref{RTL SSA Phi Nodes}).
4646
4647 @node RTL SSA Phi Nodes
4648 @subsection RTL SSA Phi Nodes
4649
4650 @cindex phi nodes, RTL SSA
4651 @findex rtl_ssa::phi_info
4652 If a resource is live on entry to an extended basic block and if the
4653 resource's value can come from multiple sources, the extended basic block
4654 has a ``phi node'' that collects together these multiple sources.
4655 The phi node conceptually has one input for each incoming edge of
4656 the extended basic block, with the input specifying the value of
4657 the resource on that edge. For example, suppose a function contains
4658 the following RTL:
4659
4660 @smallexample
4661 ;; Basic block bb3
4662 @dots{}
4663 (set (reg:SI R1) (const_int 0)) ;; A
4664 (set (pc) (label_ref bb5))
4665
4666 ;; Basic block bb4
4667 @dots{}
4668 (set (reg:SI R1) (const_int 1)) ;; B
4669 ;; Fall through
4670
4671 ;; Basic block bb5
4672 ;; preds: bb3, bb4
4673 ;; live in: R1 @dots{}
4674 (code_label bb5)
4675 @dots{}
4676 (set (reg:SI @var{R2})
4677 (plus:SI (reg:SI R1) @dots{})) ;; C
4678 @end smallexample
4679
4680 The value of R1 on entry to block 5 can come from either A or B@.
4681 The extended basic block that contains block 5 would therefore have a
4682 phi node with two inputs: the first input would have the value of
4683 R1 defined by A and the second input would have the value of
4684 R1 defined by B@. This phi node would then provide the value of
4685 R1 for C (assuming that R1 does not change again between
4686 the start of block 5 and C).
4687
4688 Since RTL is not a ``native'' SSA representation, these phi nodes
4689 simply collect together definitions that already exist. Each input
4690 to a phi node for a resource @var{R} is itself a definition of
4691 resource @var{R} (or is null if the resource is completely
4692 undefined for a particular incoming edge). This is in contrast
4693 to a native SSA representation like GIMPLE, where the phi inputs
4694 can be arbitrary expressions. As a result, RTL SSA phi nodes
4695 never involve ``hidden'' moves: all moves are instead explicit.
4696
4697 Phi nodes are represented as a @code{rtl_ssa::phi_node}.
4698 Each input to a phi node is represented as an @code{rtl_ssa::use_info}.
4699
4700 @node RTL SSA Access Lists
4701 @subsection RTL SSA Access Lists
4702
4703 All the definitions of a resource are chained together in reverse postorder.
4704 In general, this list can contain an arbitrary mix of both sets
4705 (@code{rtl_ssa::set_info}) and clobbers (@code{rtl_ssa::clobber_info}).
4706 However, it is often useful to skip over all intervening clobbers
4707 of a resource in order to find the next set. The list is constructed
4708 in such a way that this can be done in amortized constant time.
4709
4710 All uses (@code{rtl_ssa::use_info}) of a given set are also chained
4711 together into a list. This list of uses is divided into three parts:
4712
4713 @enumerate
4714 @item
4715 uses by ``real'' nondebug instructions (@pxref{real RTL SSA insns})
4716
4717 @item
4718 uses by real debug instructions
4719
4720 @item
4721 uses by phi nodes (@pxref{RTL SSA Phi Nodes})
4722 @end enumerate
4723
4724 The first and second parts individually follow reverse postorder.
4725 The third part has no particular order.
4726
4727 @cindex degenerate phi node, RTL SSA
4728 The last use by a real nondebug instruction always comes earlier in
4729 the reverse postorder than the next definition of the resource (if any).
4730 This means that the accesses follow a linear sequence of the form:
4731
4732 @itemize @bullet
4733 @item
4734 first definition of resource R
4735
4736 @itemize @bullet
4737 @item
4738 first use by a real nondebug instruction of the first definition of resource R
4739
4740 @item
4741 @dots{}
4742
4743 @item
4744 last use by a real nondebug instruction of the first definition of resource R
4745 @end itemize
4746
4747 @item
4748 second definition of resource R
4749
4750 @itemize @bullet
4751 @item
4752 first use by a real nondebug instruction of the second definition of resource R
4753
4754 @item
4755 @dots{}
4756
4757 @item
4758 last use by a real nondebug instruction of the second definition of resource R
4759 @end itemize
4760
4761 @item
4762 @dots{}
4763
4764 @item
4765 last definition of resource R
4766
4767 @itemize @bullet
4768 @item
4769 first use by a real nondebug instruction of the last definition of resource R
4770
4771 @item
4772 @dots{}
4773
4774 @item
4775 last use by a real nondebug instruction of the last definition of resource R
4776 @end itemize
4777 @end itemize
4778
4779 (Note that clobbers never have uses; only sets do.)
4780
4781 This linear view is easy to achieve when there is only a single definition
4782 of a resource, which is commonly true for pseudo registers. However,
4783 things are more complex if code has a structure like the following:
4784
4785 @smallexample
4786 // ebb2, bb2
4787 R = @var{va}; // A
4788 if (@dots{})
4789 @{
4790 // ebb2, bb3
4791 use1 (R); // B
4792 @dots{}
4793 R = @var{vc}; // C
4794 @}
4795 else
4796 @{
4797 // ebb4, bb4
4798 use2 (R); // D
4799 @}
4800 @end smallexample
4801
4802 The list of accesses would begin as follows:
4803
4804 @itemize @bullet
4805 @item
4806 definition of R by A
4807
4808 @itemize @bullet
4809 @item
4810 use of A's definition of R by B
4811 @end itemize
4812
4813 @item
4814 definition of R by C
4815 @end itemize
4816
4817 The next access to R is in D, but the value of R that D uses comes from
4818 A rather than C@.
4819
4820 This is resolved by adding a phi node for @code{ebb4}. All inputs to this
4821 phi node have the same value, which in the example above is A's definition
4822 of R@. In other circumstances, it would not be necessary to create a phi
4823 node when all inputs are equal, so these phi nodes are referred to as
4824 ``degenerate'' phi nodes.
4825
4826 The full list of accesses to R is therefore:
4827
4828 @itemize @bullet
4829 @item
4830 definition of R by A
4831
4832 @itemize @bullet
4833 @item
4834 use of A's definition of R by B
4835 @end itemize
4836
4837 @item
4838 definition of R by C
4839
4840 @item
4841 definition of R by ebb4's phi instruction, with the input coming from A
4842
4843 @itemize @bullet
4844 @item
4845 use of the ebb4's R phi definition of R by B
4846 @end itemize
4847 @end itemize
4848
4849 Note that A's definition is also used by ebb4's phi node, but this
4850 use belongs to the third part of the use list described above and
4851 so does not form part of the linear sequence.
4852
4853 It is possible to ``look through'' any degenerate phi to the ultimate
4854 definition using the function @code{look_through_degenerate_phi}.
4855 Note that the input to a degenerate phi is never itself provided
4856 by a degenerate phi.
4857
4858 At present, the SSA form takes this principle one step further
4859 and guarantees that, for any given resource @var{res}, one of the
4860 following is true:
4861
4862 @itemize
4863 @item
4864 The resource has a single definition @var{def}, which is not a phi node.
4865 Excluding uses of undefined registers, all uses of @var{res} by real
4866 nondebug instructions use the value provided by @var{def}.
4867
4868 @item
4869 Excluding uses of undefined registers, all uses of @var{res} use
4870 values provided by definitions that occur earlier in the same
4871 extended basic block. These definitions might come from phi nodes
4872 or from real instructions.
4873 @end itemize
4874
4875 @node Changing RTL Instructions
4876 @subsection Using the RTL SSA framework to change instructions
4877
4878 @findex rtl_ssa::insn_change
4879 There are various routines that help to change a single RTL instruction
4880 or a group of RTL instructions while keeping the RTL SSA form up-to-date.
4881 This section first describes the process for changing a single instruction,
4882 then goes on to describe the differences when changing multiple instructions.
4883
4884 @menu
4885 * Changing One RTL SSA Instruction::
4886 * Changing Multiple RTL SSA Instructions::
4887 @end menu
4888
4889 @node Changing One RTL SSA Instruction
4890 @subsubsection Changing One RTL SSA Instruction
4891
4892 Before making a change, passes should first use a statement like the
4893 following:
4894
4895 @smallexample
4896 auto attempt = crtl->ssa->new_change_attempt ();
4897 @end smallexample
4898
4899 Here, @code{attempt} is an RAII object that should remain in scope
4900 for the entire change attempt. It automatically frees temporary
4901 memory related to the changes when it goes out of scope.
4902
4903 Next, the pass should create an @code{rtl_ssa::insn_change} object
4904 for the instruction that it wants to change. This object specifies
4905 several things:
4906
4907 @itemize @bullet
4908 @item
4909 what the instruction's new list of uses should be (@code{new_uses}).
4910 By default this is the same as the instruction's current list of uses.
4911
4912 @item
4913 what the instruction's new list of definitions should be (@code{new_defs}).
4914 By default this is the same as the instruction's current list of
4915 definitions.
4916
4917 @item
4918 where the instruction should be located (@code{move_range}).
4919 This is a range of instructions after which the instruction could
4920 be placed, represented as an @code{rtl_ssa::insn_range}.
4921 By default the instruction must remain at its current position.
4922 @end itemize
4923
4924 If a pass was attempting to change all these properties of an instruction
4925 @code{insn}, it might do something like this:
4926
4927 @smallexample
4928 rtl_ssa::insn_change change (insn);
4929 change.new_defs = @dots{};
4930 change.new_uses = @dots{};
4931 change.move_range = @dots{};
4932 @end smallexample
4933
4934 This @code{rtl_ssa::insn_change} only describes something that the
4935 pass @emph{might} do; at this stage, nothing has actually changed.
4936
4937 As noted above, the default @code{move_range} requires the instruction
4938 to remain where it is. At the other extreme, it is possible to allow
4939 the instruction to move anywhere within its extended basic block,
4940 provided that all the new uses and definitions can be performed
4941 at the new location. The way to do this is:
4942
4943 @smallexample
4944 change.move_range = insn->ebb ()->insn_range ();
4945 @end smallexample
4946
4947 In either case, the next step is to make sure that move range is
4948 consistent with the new uses and definitions. The way to do this is:
4949
4950 @smallexample
4951 if (!rtl_ssa::restrict_movement (change))
4952 return false;
4953 @end smallexample
4954
4955 This function tries to limit @code{move_range} to a range of instructions
4956 at which @code{new_uses} and @code{new_defs} can be correctly performed.
4957 It returns true on success or false if no suitable location exists.
4958
4959 The pass should also tentatively change the pattern of the instruction
4960 to whatever form the pass wants the instruction to have. This should use
4961 the facilities provided by @file{recog.cc}. For example:
4962
4963 @smallexample
4964 rtl_insn *rtl = insn->rtl ();
4965 insn_change_watermark watermark;
4966 validate_change (rtl, &PATTERN (rtl), new_pat, 1);
4967 @end smallexample
4968
4969 will tentatively replace @code{insn}'s pattern with @code{new_pat}.
4970
4971 These changes and the construction of the @code{rtl_ssa::insn_change}
4972 can happen in either order or be interleaved.
4973
4974 After the tentative changes to the instruction are complete,
4975 the pass should check whether the new pattern matches a target
4976 instruction or satisfies the requirements of an inline asm:
4977
4978 @smallexample
4979 if (!rtl_ssa::recog (attempt, change))
4980 return false;
4981 @end smallexample
4982
4983 This step might change the instruction pattern further in order to
4984 make it match. It might also add new definitions or restrict the range
4985 of the move. For example, if the new pattern did not match in its original
4986 form, but could be made to match by adding a clobber of the flags
4987 register, @code{rtl_ssa::recog} will check whether the flags register
4988 is free at an appropriate point. If so, it will add a clobber of the
4989 flags register to @code{new_defs} and restrict @code{move_range} to
4990 the locations at which the flags register can be safely clobbered.
4991
4992 Even if the proposed new instruction is valid according to
4993 @code{rtl_ssa::recog}, the change might not be worthwhile.
4994 For example, when optimizing for speed, the new instruction might
4995 turn out to be slower than the original one. When optimizing for
4996 size, the new instruction might turn out to be bigger than the
4997 original one.
4998
4999 Passes should check for this case using @code{change_is_worthwhile}.
5000 For example:
5001
5002 @smallexample
5003 if (!rtl_ssa::change_is_worthwhile (change))
5004 return false;
5005 @end smallexample
5006
5007 If the change passes this test too then the pass can perform the change using:
5008
5009 @smallexample
5010 confirm_change_group ();
5011 crtl->ssa->change_insn (change);
5012 @end smallexample
5013
5014 Putting all this together, the change has the following form:
5015
5016 @smallexample
5017 auto attempt = crtl->ssa->new_change_attempt ();
5018
5019 rtl_ssa::insn_change change (insn);
5020 change.new_defs = @dots{};
5021 change.new_uses = @dots{};
5022 change.move_range = @dots{};
5023
5024 if (!rtl_ssa::restrict_movement (change))
5025 return false;
5026
5027 insn_change_watermark watermark;
5028 // Use validate_change etc. to change INSN's pattern.
5029 @dots{}
5030 if (!rtl_ssa::recog (attempt, change)
5031 || !rtl_ssa::change_is_worthwhile (change))
5032 return false;
5033
5034 confirm_change_group ();
5035 crtl->ssa->change_insn (change);
5036 @end smallexample
5037
5038 @node Changing Multiple RTL SSA Instructions
5039 @subsubsection Changing Multiple RTL SSA Instructions
5040
5041 The process for changing multiple instructions is similar
5042 to the process for changing single instructions
5043 (@pxref{Changing One RTL SSA Instruction}). The pass should
5044 again start the change attempt with:
5045
5046 @smallexample
5047 auto attempt = crtl->ssa->new_change_attempt ();
5048 @end smallexample
5049
5050 and keep @code{attempt} in scope for the duration of the change
5051 attempt. It should then construct an @code{rtl_ssa::insn_change}
5052 for each change that it wants to make.
5053
5054 After this, it should combine the changes into a sequence of
5055 @code{rtl_ssa::insn_change} pointers. This sequence must be in
5056 reverse postorder; the instructions will remain strictly in the
5057 order that the sequence specifies.
5058
5059 For example, if a pass is changing exactly two instructions,
5060 it might do:
5061
5062 @smallexample
5063 rtl_ssa::insn_change *changes[] = @{ &change1, &change2 @};
5064 @end smallexample
5065
5066 where @code{change1}'s instruction must come before @code{change2}'s.
5067 Alternatively, if the pass is changing a variable number of
5068 instructions, it might build up the sequence in a
5069 @code{vec<rtl_ssa::insn_change *>}.
5070
5071 By default, @code{rtl_ssa::restrict_movement} assumes that all
5072 instructions other than the one passed to it will remain in their
5073 current positions and will retain their current uses and definitions.
5074 When changing multiple instructions, it is usually more effective
5075 to ignore the other instructions that are changing. The sequencing
5076 described above ensures that the changing instructions remain
5077 in the correct order with respect to each other.
5078 The way to do this is:
5079
5080 @smallexample
5081 if (!rtl_ssa::restrict_movement (change, ignore_changing_insns (changes)))
5082 return false;
5083 @end smallexample
5084
5085 Similarly, when @code{rtl_ssa::restrict_movement} is detecting
5086 whether a register can be clobbered, it by default assumes that
5087 all other instructions will remain in their current positions and
5088 retain their current form. It is again more effective to ignore
5089 changing instructions (which might, for example, no longer need
5090 to clobber the flags register). The way to do this is:
5091
5092 @smallexample
5093 if (!rtl_ssa::recog (attempt, change, ignore_changing_insns (changes)))
5094 return false;
5095 @end smallexample
5096
5097 When changing multiple instructions, the important question is usually
5098 not whether each individual change is worthwhile, but whether the changes
5099 as a whole are worthwhile. The way to test this is:
5100
5101 @smallexample
5102 if (!rtl_ssa::changes_are_worthwhile (changes))
5103 return false;
5104 @end smallexample
5105
5106 The process for changing single instructions makes sure that one
5107 @code{rtl_ssa::insn_change} in isolation is valid. But when changing
5108 multiple instructions, it is also necessary to test whether the
5109 sequence as a whole is valid. For example, it might be impossible
5110 to satisfy all of the @code{move_range}s at once.
5111
5112 Therefore, once the pass has a sequence of changes that are
5113 individually correct, it should use:
5114
5115 @smallexample
5116 if (!crtl->ssa->verify_insn_changes (changes))
5117 return false;
5118 @end smallexample
5119
5120 to check whether the sequence as a whole is valid. If all checks pass,
5121 the final step is:
5122
5123 @smallexample
5124 confirm_change_group ();
5125 crtl->ssa->change_insns (changes);
5126 @end smallexample
5127
5128 Putting all this together, the process for a two-instruction change is:
5129
5130 @smallexample
5131 auto attempt = crtl->ssa->new_change_attempt ();
5132
5133 rtl_ssa::insn_change change1 (insn1);
5134 change1.new_defs = @dots{};
5135 change1.new_uses = @dots{};
5136 change1.move_range = @dots{};
5137
5138 rtl_ssa::insn_change change2 (insn2);
5139 change2.new_defs = @dots{};
5140 change2.new_uses = @dots{};
5141 change2.move_range = @dots{};
5142
5143 rtl_ssa::insn_change *changes[] = @{ &change1, &change2 @};
5144
5145 auto ignore = ignore_changing_insns (changes);
5146 if (!rtl_ssa::restrict_movement (change1, ignore)
5147 || !rtl_ssa::restrict_movement (change2, ignore))
5148 return false;
5149
5150 insn_change_watermark watermark;
5151 // Use validate_change etc. to change INSN1's and INSN2's patterns.
5152 @dots{}
5153 if (!rtl_ssa::recog (attempt, change1, ignore)
5154 || !rtl_ssa::recog (attempt, change2, ignore)
5155 || !rtl_ssa::changes_are_worthwhile (changes)
5156 || !crtl->ssa->verify_insn_changes (changes))
5157 return false;
5158
5159 confirm_change_group ();
5160 crtl->ssa->change_insns (changes);
5161 @end smallexample
5162
5163 @node Sharing
5164 @section Structure Sharing Assumptions
5165 @cindex sharing of RTL components
5166 @cindex RTL structure sharing assumptions
5167
5168 The compiler assumes that certain kinds of RTL expressions are unique;
5169 there do not exist two distinct objects representing the same value.
5170 In other cases, it makes an opposite assumption: that no RTL expression
5171 object of a certain kind appears in more than one place in the
5172 containing structure.
5173
5174 These assumptions refer to a single function; except for the RTL
5175 objects that describe global variables and external functions,
5176 and a few standard objects such as small integer constants,
5177 no RTL objects are common to two functions.
5178
5179 @itemize @bullet
5180 @cindex @code{reg}, RTL sharing
5181 @item
5182 Each pseudo-register has only a single @code{reg} object to represent it,
5183 and therefore only a single machine mode.
5184
5185 @cindex symbolic label
5186 @cindex @code{symbol_ref}, RTL sharing
5187 @item
5188 For any symbolic label, there is only one @code{symbol_ref} object
5189 referring to it.
5190
5191 @cindex @code{const_int}, RTL sharing
5192 @item
5193 All @code{const_int} expressions with equal values are shared.
5194
5195 @cindex @code{const_poly_int}, RTL sharing
5196 @item
5197 All @code{const_poly_int} expressions with equal modes and values
5198 are shared.
5199
5200 @cindex @code{pc}, RTL sharing
5201 @item
5202 There is only one @code{pc} expression.
5203
5204 @cindex @code{const_double}, RTL sharing
5205 @item
5206 There is only one @code{const_double} expression with value 0 for
5207 each floating point mode. Likewise for values 1 and 2.
5208
5209 @cindex @code{const_vector}, RTL sharing
5210 @item
5211 There is only one @code{const_vector} expression with value 0 for
5212 each vector mode, be it an integer or a double constant vector.
5213
5214 @cindex @code{label_ref}, RTL sharing
5215 @cindex @code{scratch}, RTL sharing
5216 @item
5217 No @code{label_ref} or @code{scratch} appears in more than one place in
5218 the RTL structure; in other words, it is safe to do a tree-walk of all
5219 the insns in the function and assume that each time a @code{label_ref}
5220 or @code{scratch} is seen it is distinct from all others that are seen.
5221
5222 @cindex @code{mem}, RTL sharing
5223 @item
5224 Only one @code{mem} object is normally created for each static
5225 variable or stack slot, so these objects are frequently shared in all
5226 the places they appear. However, separate but equal objects for these
5227 variables are occasionally made.
5228
5229 @cindex @code{asm_operands}, RTL sharing
5230 @item
5231 When a single @code{asm} statement has multiple output operands, a
5232 distinct @code{asm_operands} expression is made for each output operand.
5233 However, these all share the vector which contains the sequence of input
5234 operands. This sharing is used later on to test whether two
5235 @code{asm_operands} expressions come from the same statement, so all
5236 optimizations must carefully preserve the sharing if they copy the
5237 vector at all.
5238
5239 @item
5240 No RTL object appears in more than one place in the RTL structure
5241 except as described above. Many passes of the compiler rely on this
5242 by assuming that they can modify RTL objects in place without unwanted
5243 side-effects on other insns.
5244
5245 @findex unshare_all_rtl
5246 @item
5247 During initial RTL generation, shared structure is freely introduced.
5248 After all the RTL for a function has been generated, all shared
5249 structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.cc},
5250 after which the above rules are guaranteed to be followed.
5251
5252 @findex copy_rtx_if_shared
5253 @item
5254 During the combiner pass, shared structure within an insn can exist
5255 temporarily. However, the shared structure is copied before the
5256 combiner is finished with the insn. This is done by calling
5257 @code{copy_rtx_if_shared}, which is a subroutine of
5258 @code{unshare_all_rtl}.
5259 @end itemize
5260
5261 @node Reading RTL
5262 @section Reading RTL
5263
5264 To read an RTL object from a file, call @code{read_rtx}. It takes one
5265 argument, a stdio stream, and returns a single RTL object. This routine
5266 is defined in @file{read-rtl.cc}. It is not available in the compiler
5267 itself, only the various programs that generate the compiler back end
5268 from the machine description.
5269
5270 People frequently have the idea of using RTL stored as text in a file as
5271 an interface between a language front end and the bulk of GCC@. This
5272 idea is not feasible.
5273
5274 GCC was designed to use RTL internally only. Correct RTL for a given
5275 program is very dependent on the particular target machine. And the RTL
5276 does not contain all the information about the program.
5277
5278 The proper way to interface GCC to a new language front end is with
5279 the ``tree'' data structure, described in the files @file{tree.h} and
5280 @file{tree.def}. The documentation for this structure (@pxref{GENERIC})
5281 is incomplete.