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