]>
Commit | Line | Data |
---|---|---|
747215f1 | 1 | @c Copyright (C) 1988, 89, 92, 94, 97, 1998, 1999 Free Software Foundation, Inc. |
89045fd1 JL |
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 | Most of the work of the compiler is done on an intermediate representation | |
12 | called register transfer language. In this language, the instructions to be | |
13 | output are described, pretty much one by one, in an algebraic form that | |
14 | 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. | |
b89d20aa | 23 | * RTL Classes:: Categories of RTL expresion objects, and their structure. |
89045fd1 JL |
24 | * Accessors:: Macros to access expression operands or vector elts. |
25 | * Flags:: Other flags in an RTL expression. | |
26 | * Machine Modes:: Describing the size and format of a datum. | |
27 | * Constants:: Expressions with constant values. | |
28 | * Regs and Memory:: Expressions representing register contents or memory. | |
29 | * Arithmetic:: Expressions representing arithmetic on other expressions. | |
30 | * Comparisons:: Expressions representing comparison of expressions. | |
31 | * Bit Fields:: Expressions representing bitfields in memory or reg. | |
32 | * Conversions:: Extending, truncating, floating or fixing. | |
33 | * RTL Declarations:: Declaring volatility, constancy, etc. | |
34 | * Side Effects:: Expressions for storing in registers, etc. | |
35 | * Incdec:: Embedded side-effects for autoincrement addressing. | |
36 | * Assembler:: Representing @code{asm} with operands. | |
37 | * Insns:: Expression types for entire insns. | |
38 | * Calls:: RTL representation of function call insns. | |
39 | * Sharing:: Some expressions are unique; others *must* be copied. | |
40 | * Reading RTL:: Reading textual RTL from a file. | |
41 | @end menu | |
42 | ||
4404ce28 | 43 | @node RTL Objects |
89045fd1 JL |
44 | @section RTL Object Types |
45 | @cindex RTL object types | |
46 | ||
47 | @cindex RTL integers | |
48 | @cindex RTL strings | |
49 | @cindex RTL vectors | |
50 | @cindex RTL expression | |
51 | @cindex RTX (See RTL) | |
52 | RTL uses five kinds of objects: expressions, integers, wide integers, | |
53 | strings and vectors. Expressions are the most important ones. An RTL | |
54 | expression (``RTX'', for short) is a C structure, but it is usually | |
55 | referred to with a pointer; a type that is given the typedef name | |
56 | @code{rtx}. | |
57 | ||
58 | An integer is simply an @code{int}; their written form uses decimal digits. | |
59 | A wide integer is an integral object whose type is @code{HOST_WIDE_INT} | |
60 | (@pxref{Config}); their written form uses decimal digits. | |
61 | ||
62 | A string is a sequence of characters. In core it is represented as a | |
63 | @code{char *} in usual C fashion, and it is written in C syntax as well. | |
64 | However, strings in RTL may never be null. If you write an empty string in | |
65 | a machine description, it is represented in core as a null pointer rather | |
66 | than as a pointer to a null character. In certain contexts, these null | |
67 | pointers instead of strings are valid. Within RTL code, strings are most | |
68 | commonly found inside @code{symbol_ref} expressions, but they appear in | |
69 | other contexts in the RTL expressions that make up machine descriptions. | |
70 | ||
71 | A vector contains an arbitrary number of pointers to expressions. The | |
72 | number of elements in the vector is explicitly present in the vector. | |
73 | The written form of a vector consists of square brackets | |
74 | (@samp{[@dots{}]}) surrounding the elements, in sequence and with | |
75 | whitespace separating them. Vectors of length zero are not created; | |
76 | null pointers are used instead. | |
77 | ||
78 | @cindex expression codes | |
79 | @cindex codes, RTL expression | |
80 | @findex GET_CODE | |
81 | @findex PUT_CODE | |
82 | Expressions are classified by @dfn{expression codes} (also called RTX | |
83 | codes). The expression code is a name defined in @file{rtl.def}, which is | |
84 | also (in upper case) a C enumeration constant. The possible expression | |
85 | codes and their meanings are machine-independent. The code of an RTX can | |
86 | be extracted with the macro @code{GET_CODE (@var{x})} and altered with | |
87 | @code{PUT_CODE (@var{x}, @var{newcode})}. | |
88 | ||
89 | The expression code determines how many operands the expression contains, | |
90 | and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell | |
91 | by looking at an operand what kind of object it is. Instead, you must know | |
92 | from its context---from the expression code of the containing expression. | |
93 | For example, in an expression of code @code{subreg}, the first operand is | |
94 | to be regarded as an expression and the second operand as an integer. In | |
95 | an expression of code @code{plus}, there are two operands, both of which | |
96 | are to be regarded as expressions. In a @code{symbol_ref} expression, | |
97 | there is one operand, which is to be regarded as a string. | |
98 | ||
99 | Expressions are written as parentheses containing the name of the | |
100 | expression type, its flags and machine mode if any, and then the operands | |
101 | of the expression (separated by spaces). | |
102 | ||
103 | Expression code names in the @samp{md} file are written in lower case, | |
104 | but when they appear in C code they are written in upper case. In this | |
105 | manual, they are shown as follows: @code{const_int}. | |
106 | ||
107 | @cindex (nil) | |
108 | @cindex nil | |
109 | In a few contexts a null pointer is valid where an expression is normally | |
110 | wanted. The written form of this is @code{(nil)}. | |
111 | ||
4404ce28 | 112 | @node RTL Classes |
b89d20aa ZW |
113 | @section RTL Classes and Formats |
114 | @cindex RTL classes | |
115 | @cindex classes of RTX codes | |
116 | @cindex RTX codes, classes of | |
117 | @findex GET_RTX_CLASS | |
118 | ||
119 | The various expression codes are divided into several @dfn{classes}, | |
120 | which are represented by single characters. You can determine the class | |
121 | of an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}. | |
122 | Currently, @file{rtx.def} defines these classes: | |
123 | ||
124 | @table @code | |
125 | @item o | |
126 | An RTX code that represents an actual object, such as a register | |
127 | (@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}). | |
128 | Constants and basic transforms on objects (@code{ADDRESSOF}, | |
129 | @code{HIGH}, @code{LO_SUM}) are also included. Note that @code{SUBREG} | |
130 | and @code{STRICT_LOW_PART} are not in this class, but in class @code{x}. | |
131 | ||
132 | @item < | |
133 | An RTX code for a comparison, such as @code{NE} or @code{LT}. | |
134 | ||
135 | @item 1 | |
136 | An RTX code for a unary arithmetic operation, such as @code{NEG}, | |
137 | @code{NOT}, or @code{ABS}. This category also includes value extension | |
138 | (sign or zero) and conversions between integer and floating point. | |
139 | ||
140 | @item c | |
141 | An RTX code for a commutative binary operation, such as @code{PLUS} or | |
142 | @code{AND}. @code{NE} and @code{EQ} are comparisons, so they have class | |
143 | @code{<}. | |
144 | ||
145 | @item 2 | |
146 | An RTX code for a non-commutative binary operation, such as @code{MINUS}, | |
147 | @code{DIV}, or @code{ASHIFTRT}. | |
148 | ||
149 | @item b | |
150 | An RTX code for a bitfield operation. Currently only | |
151 | @code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}. These have three inputs | |
152 | and are lvalues (so they can be used for insertion as well). @xref{Bit | |
153 | Fields}. | |
154 | ||
155 | @item 3 | |
156 | An RTX code for other three input operations. Currently only | |
157 | @code{IF_THEN_ELSE}. | |
158 | ||
159 | @item i | |
160 | An RTX code for an entire instruction: @code{INSN}, @code{JUMP_INSN}, and | |
161 | @code{CALL_INSN}. @xref{Insns}. | |
162 | ||
163 | @item m | |
164 | An RTX code for something that matches in insns, such as | |
165 | @code{MATCH_DUP}. These only occur in machine descriptions. | |
166 | ||
167 | @item x | |
168 | All other RTX codes. This category includes the remaining codes used | |
169 | only in machine descriptions (@code{DEFINE_*}, etc.). It also includes | |
170 | all the codes describing side effects (@code{SET}, @code{USE}, | |
171 | @code{CLOBBER}, etc.) and the non-insns that may appear on an insn | |
172 | chain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}. | |
173 | @end table | |
89045fd1 JL |
174 | |
175 | @cindex RTL format | |
176 | For each expression type @file{rtl.def} specifies the number of | |
177 | contained objects and their kinds, with four possibilities: @samp{e} for | |
178 | expression (actually a pointer to an expression), @samp{i} for integer, | |
179 | @samp{w} for wide integer, @samp{s} for string, and @samp{E} for vector | |
180 | of expressions. The sequence of letters for an expression code is | |
b89d20aa | 181 | called its @dfn{format}. For example, the format of @code{subreg} is |
89045fd1 JL |
182 | @samp{ei}.@refill |
183 | ||
184 | @cindex RTL format characters | |
185 | A few other format characters are used occasionally: | |
186 | ||
187 | @table @code | |
188 | @item u | |
189 | @samp{u} is equivalent to @samp{e} except that it is printed differently | |
190 | in debugging dumps. It is used for pointers to insns. | |
191 | ||
192 | @item n | |
193 | @samp{n} is equivalent to @samp{i} except that it is printed differently | |
194 | in debugging dumps. It is used for the line number or code number of a | |
195 | @code{note} insn. | |
196 | ||
197 | @item S | |
198 | @samp{S} indicates a string which is optional. In the RTL objects in | |
199 | core, @samp{S} is equivalent to @samp{s}, but when the object is read, | |
200 | from an @samp{md} file, the string value of this operand may be omitted. | |
201 | An omitted string is taken to be the null string. | |
202 | ||
203 | @item V | |
204 | @samp{V} indicates a vector which is optional. In the RTL objects in | |
205 | core, @samp{V} is equivalent to @samp{E}, but when the object is read | |
206 | from an @samp{md} file, the vector value of this operand may be omitted. | |
207 | An omitted vector is effectively the same as a vector of no elements. | |
208 | ||
209 | @item 0 | |
210 | @samp{0} means a slot whose contents do not fit any normal category. | |
211 | @samp{0} slots are not printed at all in dumps, and are often used in | |
212 | special ways by small parts of the compiler. | |
213 | @end table | |
214 | ||
b89d20aa ZW |
215 | There are macros to get the number of operands and the format |
216 | of an expression code: | |
89045fd1 JL |
217 | |
218 | @table @code | |
219 | @findex GET_RTX_LENGTH | |
220 | @item GET_RTX_LENGTH (@var{code}) | |
221 | Number of operands of an RTX of code @var{code}. | |
222 | ||
223 | @findex GET_RTX_FORMAT | |
224 | @item GET_RTX_FORMAT (@var{code}) | |
225 | The format of an RTX of code @var{code}, as a C string. | |
b89d20aa | 226 | @end table |
89045fd1 | 227 | |
b89d20aa ZW |
228 | Some classes of RTX codes always have the same format. For example, it |
229 | is safe to assume that all comparison operations have format @code{ee}. | |
89045fd1 JL |
230 | |
231 | @table @code | |
89045fd1 | 232 | @item 1 |
b89d20aa | 233 | All codes of this class have format @code{e}. |
89045fd1 | 234 | |
b89d20aa ZW |
235 | @item < |
236 | @itemx c | |
237 | @itemx 2 | |
238 | All codes of these classes have format @code{ee}. | |
89045fd1 JL |
239 | |
240 | @item b | |
b89d20aa ZW |
241 | @itemx 3 |
242 | All codes of these classes have format @code{eee}. | |
89045fd1 JL |
243 | |
244 | @item i | |
b89d20aa ZW |
245 | All codes of this class have formats that begin with @code{iuueiee}. |
246 | @xref{Insns}. Note that not all RTL objects linked onto an insn chain | |
247 | are of class @code{i}. | |
89045fd1 | 248 | |
b89d20aa ZW |
249 | @item o |
250 | @itemx m | |
251 | @itemx x | |
252 | You can make no assumptions about the format of these codes. | |
89045fd1 JL |
253 | @end table |
254 | ||
4404ce28 | 255 | @node Accessors |
b89d20aa ZW |
256 | @section Access to Operands |
257 | @cindex accessors | |
258 | @cindex access to operands | |
259 | @cindex operand access | |
260 | ||
89045fd1 JL |
261 | @findex XEXP |
262 | @findex XINT | |
263 | @findex XWINT | |
264 | @findex XSTR | |
265 | Operands of expressions are accessed using the macros @code{XEXP}, | |
266 | @code{XINT}, @code{XWINT} and @code{XSTR}. Each of these macros takes | |
267 | two arguments: an expression-pointer (RTX) and an operand number | |
268 | (counting from zero). Thus,@refill | |
269 | ||
270 | @example | |
271 | XEXP (@var{x}, 2) | |
272 | @end example | |
273 | ||
274 | @noindent | |
275 | accesses operand 2 of expression @var{x}, as an expression. | |
276 | ||
277 | @example | |
278 | XINT (@var{x}, 2) | |
279 | @end example | |
280 | ||
281 | @noindent | |
282 | accesses the same operand as an integer. @code{XSTR}, used in the same | |
283 | fashion, would access it as a string. | |
284 | ||
285 | Any operand can be accessed as an integer, as an expression or as a string. | |
286 | You must choose the correct method of access for the kind of value actually | |
287 | stored in the operand. You would do this based on the expression code of | |
288 | the containing expression. That is also how you would know how many | |
289 | operands there are. | |
290 | ||
291 | For example, if @var{x} is a @code{subreg} expression, you know that it has | |
292 | two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)} | |
293 | and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you | |
294 | would get the address of the expression operand but cast as an integer; | |
295 | that might occasionally be useful, but it would be cleaner to write | |
296 | @code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also | |
297 | compile without error, and would return the second, integer operand cast as | |
298 | an expression pointer, which would probably result in a crash when | |
299 | accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either, | |
300 | but this will access memory past the end of the expression with | |
301 | unpredictable results.@refill | |
302 | ||
303 | Access to operands which are vectors is more complicated. You can use the | |
304 | macro @code{XVEC} to get the vector-pointer itself, or the macros | |
305 | @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a | |
306 | vector. | |
307 | ||
308 | @table @code | |
309 | @findex XVEC | |
310 | @item XVEC (@var{exp}, @var{idx}) | |
311 | Access the vector-pointer which is operand number @var{idx} in @var{exp}. | |
312 | ||
313 | @findex XVECLEN | |
314 | @item XVECLEN (@var{exp}, @var{idx}) | |
315 | Access the length (number of elements) in the vector which is | |
316 | in operand number @var{idx} in @var{exp}. This value is an @code{int}. | |
317 | ||
318 | @findex XVECEXP | |
319 | @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum}) | |
320 | Access element number @var{eltnum} in the vector which is | |
321 | in operand number @var{idx} in @var{exp}. This value is an RTX. | |
322 | ||
323 | It is up to you to make sure that @var{eltnum} is not negative | |
324 | and is less than @code{XVECLEN (@var{exp}, @var{idx})}. | |
325 | @end table | |
326 | ||
327 | All the macros defined in this section expand into lvalues and therefore | |
328 | can be used to assign the operands, lengths and vector elements as well as | |
329 | to access them. | |
330 | ||
4404ce28 | 331 | @node Flags |
89045fd1 JL |
332 | @section Flags in an RTL Expression |
333 | @cindex flags in RTL expression | |
334 | ||
41472af8 MM |
335 | RTL expressions contain several flags (one-bit bitfields) and other |
336 | values that are used in certain types of expression. Most often they | |
337 | are accessed with the following macros: | |
89045fd1 JL |
338 | |
339 | @table @code | |
340 | @findex MEM_VOLATILE_P | |
341 | @cindex @code{mem} and @samp{/v} | |
342 | @cindex @code{volatil}, in @code{mem} | |
343 | @cindex @samp{/v} in RTL dump | |
344 | @item MEM_VOLATILE_P (@var{x}) | |
345 | In @code{mem} expressions, nonzero for volatile memory references. | |
346 | Stored in the @code{volatil} field and printed as @samp{/v}. | |
347 | ||
348 | @findex MEM_IN_STRUCT_P | |
349 | @cindex @code{mem} and @samp{/s} | |
350 | @cindex @code{in_struct}, in @code{mem} | |
351 | @cindex @samp{/s} in RTL dump | |
352 | @item MEM_IN_STRUCT_P (@var{x}) | |
c6df88cb MM |
353 | In @code{mem} expressions, nonzero for reference to an entire structure, |
354 | union or array, or to a component of one. Zero for references to a | |
355 | scalar variable or through a pointer to a scalar. Stored in the | |
356 | @code{in_struct} field and printed as @samp{/s}. If both this flag and | |
357 | MEM_SCALAR_P are clear, then we don't know whether this MEM is in a | |
358 | structure or not. Both flags should never be simultaneously set. | |
359 | ||
360 | @findex MEM_SCALAR_P | |
361 | @cindex @code{mem} and @samp{/f} | |
362 | @cindex @code{frame_related}, in@code{mem} | |
363 | @cindex @samp{/f} in RTL dump | |
364 | @item MEM_SCALAR_P (@var{x}) | |
365 | In @code{mem} expressions, nonzero for reference to a scalar known not | |
366 | to be a member of a structure, union, or array. Zero for such | |
367 | references and for indirections through pointers, even pointers pointing | |
368 | to scalar types. If both this flag and MEM_STRUCT_P are clear, then we | |
369 | don't know whether this MEM is in a structure or not. Both flags should | |
370 | never be simultaneously set. | |
89045fd1 | 371 | |
41472af8 MM |
372 | @findex MEM_ALIAS_SET |
373 | @item MEM_ALIAS_SET (@var{x}) | |
374 | In @code{mem} expressions, the alias set to which @var{x} belongs. If | |
375 | zero, @var{x} is not in any alias set, and may alias anything. If | |
376 | nonzero, @var{x} may only alias objects in the same alias set. This | |
377 | value is set (in a language-specific manner) by the front-end. This | |
378 | field is not a bit-field; it is in an integer, found as the second | |
379 | argument to the @code{mem}. | |
380 | ||
89045fd1 JL |
381 | @findex REG_LOOP_TEST_P |
382 | @cindex @code{reg} and @samp{/s} | |
383 | @cindex @code{in_struct}, in @code{reg} | |
384 | @item REG_LOOP_TEST_P | |
385 | In @code{reg} expressions, nonzero if this register's entire life is | |
386 | contained in the exit test code for some loop. Stored in the | |
387 | @code{in_struct} field and printed as @samp{/s}. | |
388 | ||
389 | @findex REG_USERVAR_P | |
390 | @cindex @code{reg} and @samp{/v} | |
391 | @cindex @code{volatil}, in @code{reg} | |
392 | @item REG_USERVAR_P (@var{x}) | |
393 | In a @code{reg}, nonzero if it corresponds to a variable present in | |
394 | the user's source code. Zero for temporaries generated internally by | |
395 | the compiler. Stored in the @code{volatil} field and printed as | |
396 | @samp{/v}. | |
397 | ||
398 | @cindex @samp{/i} in RTL dump | |
399 | @findex REG_FUNCTION_VALUE_P | |
400 | @cindex @code{reg} and @samp{/i} | |
401 | @cindex @code{integrated}, in @code{reg} | |
402 | @item REG_FUNCTION_VALUE_P (@var{x}) | |
403 | Nonzero in a @code{reg} if it is the place in which this function's | |
404 | value is going to be returned. (This happens only in a hard | |
405 | register.) Stored in the @code{integrated} field and printed as | |
406 | @samp{/i}. | |
407 | ||
408 | The same hard register may be used also for collecting the values of | |
409 | functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero | |
410 | in this kind of use. | |
411 | ||
412 | @findex SUBREG_PROMOTED_VAR_P | |
413 | @cindex @code{subreg} and @samp{/s} | |
414 | @cindex @code{in_struct}, in @code{subreg} | |
415 | @item SUBREG_PROMOTED_VAR_P | |
416 | Nonzero in a @code{subreg} if it was made when accessing an object that | |
417 | was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine | |
418 | description macro (@pxref{Storage Layout}). In this case, the mode of | |
419 | the @code{subreg} is the declared mode of the object and the mode of | |
420 | @code{SUBREG_REG} is the mode of the register that holds the object. | |
421 | Promoted variables are always either sign- or zero-extended to the wider | |
422 | mode on every assignment. Stored in the @code{in_struct} field and | |
423 | printed as @samp{/s}. | |
424 | ||
425 | @findex SUBREG_PROMOTED_UNSIGNED_P | |
426 | @cindex @code{subreg} and @samp{/u} | |
427 | @cindex @code{unchanging}, in @code{subreg} | |
428 | @item SUBREG_PROMOTED_UNSIGNED_P | |
429 | Nonzero in a @code{subreg} that has @code{SUBREG_PROMOTED_VAR_P} nonzero | |
430 | if the object being referenced is kept zero-extended and zero if it | |
431 | is kept sign-extended. Stored in the @code{unchanging} field and | |
432 | printed as @samp{/u}. | |
433 | ||
434 | @findex RTX_UNCHANGING_P | |
435 | @cindex @code{reg} and @samp{/u} | |
436 | @cindex @code{mem} and @samp{/u} | |
437 | @cindex @code{unchanging}, in @code{reg} and @code{mem} | |
438 | @cindex @samp{/u} in RTL dump | |
439 | @item RTX_UNCHANGING_P (@var{x}) | |
440 | Nonzero in a @code{reg} or @code{mem} if the value is not changed. | |
441 | (This flag is not set for memory references via pointers to constants. | |
442 | Such pointers only guarantee that the object will not be changed | |
443 | explicitly by the current function. The object might be changed by | |
444 | other functions or by aliasing.) Stored in the | |
445 | @code{unchanging} field and printed as @samp{/u}. | |
446 | ||
447 | @findex RTX_INTEGRATED_P | |
448 | @cindex @code{integrated}, in @code{insn} | |
449 | @item RTX_INTEGRATED_P (@var{insn}) | |
450 | Nonzero in an insn if it resulted from an in-line function call. | |
70198e3d | 451 | Stored in the @code{integrated} field and printed as @samp{/i}. |
89045fd1 | 452 | |
2b4b3e5f AM |
453 | @findex RTX_FRAME_RELATED_P |
454 | @item RTX_FRAME_RELATED_P (@var{x}) | |
455 | Nonzero in an insn or expression which is part of a function | |
456 | prologue and sets the stack pointer, sets the frame pointer, or saves a | |
457 | register. This flag is required for exception handling support | |
458 | on targets with RTL prologues. | |
459 | ||
89045fd1 JL |
460 | @findex SYMBOL_REF_USED |
461 | @cindex @code{used}, in @code{symbol_ref} | |
462 | @item SYMBOL_REF_USED (@var{x}) | |
463 | In a @code{symbol_ref}, indicates that @var{x} has been used. This is | |
464 | normally only used to ensure that @var{x} is only declared external | |
465 | once. Stored in the @code{used} field. | |
466 | ||
467 | @findex SYMBOL_REF_FLAG | |
468 | @cindex @code{symbol_ref} and @samp{/v} | |
469 | @cindex @code{volatil}, in @code{symbol_ref} | |
470 | @item SYMBOL_REF_FLAG (@var{x}) | |
471 | In a @code{symbol_ref}, this is used as a flag for machine-specific purposes. | |
472 | Stored in the @code{volatil} field and printed as @samp{/v}. | |
473 | ||
474 | @findex LABEL_OUTSIDE_LOOP_P | |
475 | @cindex @code{label_ref} and @samp{/s} | |
476 | @cindex @code{in_struct}, in @code{label_ref} | |
477 | @item LABEL_OUTSIDE_LOOP_P | |
478 | In @code{label_ref} expressions, nonzero if this is a reference to a | |
479 | label that is outside the innermost loop containing the reference to the | |
480 | label. Stored in the @code{in_struct} field and printed as @samp{/s}. | |
481 | ||
482 | @findex INSN_DELETED_P | |
483 | @cindex @code{volatil}, in @code{insn} | |
484 | @item INSN_DELETED_P (@var{insn}) | |
485 | In an insn, nonzero if the insn has been deleted. Stored in the | |
486 | @code{volatil} field and printed as @samp{/v}. | |
487 | ||
488 | @findex INSN_ANNULLED_BRANCH_P | |
489 | @cindex @code{insn} and @samp{/u} | |
490 | @cindex @code{unchanging}, in @code{insn} | |
491 | @item INSN_ANNULLED_BRANCH_P (@var{insn}) | |
492 | In an @code{insn} in the delay slot of a branch insn, indicates that an | |
493 | annulling branch should be used. See the discussion under | |
494 | @code{sequence} below. Stored in the @code{unchanging} field and printed | |
495 | as @samp{/u}. | |
496 | ||
497 | @findex INSN_FROM_TARGET_P | |
498 | @cindex @code{insn} and @samp{/s} | |
499 | @cindex @code{in_struct}, in @code{insn} | |
500 | @cindex @samp{/s} in RTL dump | |
501 | @item INSN_FROM_TARGET_P (@var{insn}) | |
502 | In an @code{insn} in a delay slot of a branch, indicates that the insn | |
503 | is from the target of the branch. If the branch insn has | |
e5e809f4 JL |
504 | @code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if |
505 | the branch is taken. For annulled branches with | |
506 | @code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the | |
507 | branch is not taken. When @code{INSN_ANNULLED_BRANCH_P} is not set, | |
508 | this insn will always be executed. Stored in the @code{in_struct} | |
509 | field and printed as @samp{/s}. | |
89045fd1 JL |
510 | |
511 | @findex CONSTANT_POOL_ADDRESS_P | |
512 | @cindex @code{symbol_ref} and @samp{/u} | |
513 | @cindex @code{unchanging}, in @code{symbol_ref} | |
514 | @item CONSTANT_POOL_ADDRESS_P (@var{x}) | |
515 | Nonzero in a @code{symbol_ref} if it refers to part of the current | |
516 | function's ``constants pool''. These are addresses close to the | |
517 | beginning of the function, and GNU CC assumes they can be addressed | |
518 | directly (perhaps with the help of base registers). Stored in the | |
519 | @code{unchanging} field and printed as @samp{/u}. | |
520 | ||
521 | @findex CONST_CALL_P | |
522 | @cindex @code{call_insn} and @samp{/u} | |
523 | @cindex @code{unchanging}, in @code{call_insn} | |
524 | @item CONST_CALL_P (@var{x}) | |
525 | In a @code{call_insn}, indicates that the insn represents a call to a const | |
526 | function. Stored in the @code{unchanging} field and printed as @samp{/u}. | |
527 | ||
528 | @findex LABEL_PRESERVE_P | |
529 | @cindex @code{code_label} and @samp{/i} | |
530 | @cindex @code{in_struct}, in @code{code_label} | |
531 | @item LABEL_PRESERVE_P (@var{x}) | |
532 | In a @code{code_label}, indicates that the label can never be deleted. | |
533 | Labels referenced by a non-local goto will have this bit set. Stored | |
534 | in the @code{in_struct} field and printed as @samp{/s}. | |
535 | ||
536 | @findex SCHED_GROUP_P | |
537 | @cindex @code{insn} and @samp{/i} | |
538 | @cindex @code{in_struct}, in @code{insn} | |
539 | @item SCHED_GROUP_P (@var{insn}) | |
540 | During instruction scheduling, in an insn, indicates that the previous insn | |
541 | must be scheduled together with this insn. This is used to ensure that | |
542 | certain groups of instructions will not be split up by the instruction | |
543 | scheduling pass, for example, @code{use} insns before a @code{call_insn} may | |
544 | not be separated from the @code{call_insn}. Stored in the @code{in_struct} | |
545 | field and printed as @samp{/s}. | |
546 | @end table | |
547 | ||
548 | These are the fields which the above macros refer to: | |
549 | ||
550 | @table @code | |
551 | @findex used | |
552 | @item used | |
553 | Normally, this flag is used only momentarily, at the end of RTL | |
554 | generation for a function, to count the number of times an expression | |
555 | appears in insns. Expressions that appear more than once are copied, | |
556 | according to the rules for shared structure (@pxref{Sharing}). | |
557 | ||
558 | In a @code{symbol_ref}, it indicates that an external declaration for | |
559 | the symbol has already been written. | |
560 | ||
561 | In a @code{reg}, it is used by the leaf register renumbering code to ensure | |
562 | that each register is only renumbered once. | |
563 | ||
564 | @findex volatil | |
565 | @item volatil | |
566 | This flag is used in @code{mem}, @code{symbol_ref} and @code{reg} | |
567 | expressions and in insns. In RTL dump files, it is printed as | |
568 | @samp{/v}. | |
569 | ||
570 | @cindex volatile memory references | |
571 | In a @code{mem} expression, it is 1 if the memory reference is volatile. | |
572 | Volatile memory references may not be deleted, reordered or combined. | |
573 | ||
574 | In a @code{symbol_ref} expression, it is used for machine-specific | |
575 | purposes. | |
576 | ||
577 | In a @code{reg} expression, it is 1 if the value is a user-level variable. | |
578 | 0 indicates an internal compiler temporary. | |
579 | ||
580 | In an insn, 1 means the insn has been deleted. | |
581 | ||
582 | @findex in_struct | |
583 | @item in_struct | |
584 | In @code{mem} expressions, it is 1 if the memory datum referred to is | |
585 | all or part of a structure or array; 0 if it is (or might be) a scalar | |
586 | variable. A reference through a C pointer has 0 because the pointer | |
587 | might point to a scalar variable. This information allows the compiler | |
588 | to determine something about possible cases of aliasing. | |
589 | ||
590 | In an insn in the delay slot of a branch, 1 means that this insn is from | |
591 | the target of the branch. | |
592 | ||
593 | During instruction scheduling, in an insn, 1 means that this insn must be | |
594 | scheduled as part of a group together with the previous insn. | |
595 | ||
596 | In @code{reg} expressions, it is 1 if the register has its entire life | |
597 | contained within the test expression of some loop. | |
598 | ||
599 | In @code{subreg} expressions, 1 means that the @code{subreg} is accessing | |
600 | an object that has had its mode promoted from a wider mode. | |
601 | ||
602 | In @code{label_ref} expressions, 1 means that the referenced label is | |
603 | outside the innermost loop containing the insn in which the @code{label_ref} | |
604 | was found. | |
605 | ||
606 | In @code{code_label} expressions, it is 1 if the label may never be deleted. | |
607 | This is used for labels which are the target of non-local gotos. | |
608 | ||
609 | In an RTL dump, this flag is represented as @samp{/s}. | |
610 | ||
611 | @findex unchanging | |
612 | @item unchanging | |
613 | In @code{reg} and @code{mem} expressions, 1 means | |
614 | that the value of the expression never changes. | |
615 | ||
616 | In @code{subreg} expressions, it is 1 if the @code{subreg} references an | |
617 | unsigned object whose mode has been promoted to a wider mode. | |
618 | ||
619 | In an insn, 1 means that this is an annulling branch. | |
620 | ||
621 | In a @code{symbol_ref} expression, 1 means that this symbol addresses | |
622 | something in the per-function constants pool. | |
623 | ||
624 | In a @code{call_insn}, 1 means that this instruction is a call to a | |
625 | const function. | |
626 | ||
627 | In an RTL dump, this flag is represented as @samp{/u}. | |
628 | ||
629 | @findex integrated | |
630 | @item integrated | |
631 | In some kinds of expressions, including insns, this flag means the | |
632 | rtl was produced by procedure integration. | |
633 | ||
634 | In a @code{reg} expression, this flag indicates the register | |
635 | containing the value to be returned by the current function. On | |
636 | machines that pass parameters in registers, the same register number | |
637 | may be used for parameters as well, but this flag is not set on such | |
638 | uses. | |
639 | @end table | |
640 | ||
4404ce28 | 641 | @node Machine Modes |
89045fd1 JL |
642 | @section Machine Modes |
643 | @cindex machine modes | |
644 | ||
645 | @findex enum machine_mode | |
646 | A machine mode describes a size of data object and the representation used | |
647 | for it. In the C code, machine modes are represented by an enumeration | |
648 | type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL | |
649 | expression has room for a machine mode and so do certain kinds of tree | |
650 | expressions (declarations and types, to be precise). | |
651 | ||
652 | In debugging dumps and machine descriptions, the machine mode of an RTL | |
653 | expression is written after the expression code with a colon to separate | |
654 | them. The letters @samp{mode} which appear at the end of each machine mode | |
655 | name are omitted. For example, @code{(reg:SI 38)} is a @code{reg} | |
656 | expression with machine mode @code{SImode}. If the mode is | |
657 | @code{VOIDmode}, it is not written at all. | |
658 | ||
659 | Here is a table of machine modes. The term ``byte'' below refers to an | |
660 | object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}). | |
661 | ||
662 | @table @code | |
663 | @findex QImode | |
664 | @item QImode | |
665 | ``Quarter-Integer'' mode represents a single byte treated as an integer. | |
666 | ||
667 | @findex HImode | |
668 | @item HImode | |
669 | ``Half-Integer'' mode represents a two-byte integer. | |
670 | ||
671 | @findex PSImode | |
672 | @item PSImode | |
673 | ``Partial Single Integer'' mode represents an integer which occupies | |
674 | four bytes but which doesn't really use all four. On some machines, | |
675 | this is the right mode to use for pointers. | |
676 | ||
677 | @findex SImode | |
678 | @item SImode | |
679 | ``Single Integer'' mode represents a four-byte integer. | |
680 | ||
681 | @findex PDImode | |
682 | @item PDImode | |
683 | ``Partial Double Integer'' mode represents an integer which occupies | |
684 | eight bytes but which doesn't really use all eight. On some machines, | |
685 | this is the right mode to use for certain pointers. | |
686 | ||
687 | @findex DImode | |
688 | @item DImode | |
689 | ``Double Integer'' mode represents an eight-byte integer. | |
690 | ||
691 | @findex TImode | |
692 | @item TImode | |
693 | ``Tetra Integer'' (?) mode represents a sixteen-byte integer. | |
694 | ||
695 | @findex SFmode | |
696 | @item SFmode | |
697 | ``Single Floating'' mode represents a single-precision (four byte) floating | |
698 | point number. | |
699 | ||
700 | @findex DFmode | |
701 | @item DFmode | |
702 | ``Double Floating'' mode represents a double-precision (eight byte) floating | |
703 | point number. | |
704 | ||
705 | @findex XFmode | |
706 | @item XFmode | |
707 | ``Extended Floating'' mode represents a triple-precision (twelve byte) | |
708 | floating point number. This mode is used for IEEE extended floating | |
709 | point. On some systems not all bits within these bytes will actually | |
710 | be used. | |
711 | ||
712 | @findex TFmode | |
713 | @item TFmode | |
714 | ``Tetra Floating'' mode represents a quadruple-precision (sixteen byte) | |
715 | floating point number. | |
716 | ||
717 | @findex CCmode | |
718 | @item CCmode | |
719 | ``Condition Code'' mode represents the value of a condition code, which | |
720 | is a machine-specific set of bits used to represent the result of a | |
721 | comparison operation. Other machine-specific modes may also be used for | |
722 | the condition code. These modes are not used on machines that use | |
723 | @code{cc0} (see @pxref{Condition Code}). | |
724 | ||
725 | @findex BLKmode | |
726 | @item BLKmode | |
727 | ``Block'' mode represents values that are aggregates to which none of | |
728 | the other modes apply. In RTL, only memory references can have this mode, | |
729 | and only if they appear in string-move or vector instructions. On machines | |
730 | which have no such instructions, @code{BLKmode} will not appear in RTL. | |
731 | ||
732 | @findex VOIDmode | |
733 | @item VOIDmode | |
734 | Void mode means the absence of a mode or an unspecified mode. | |
735 | For example, RTL expressions of code @code{const_int} have mode | |
736 | @code{VOIDmode} because they can be taken to have whatever mode the context | |
737 | requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by | |
738 | the absence of any mode. | |
739 | ||
740 | @findex SCmode | |
741 | @findex DCmode | |
742 | @findex XCmode | |
743 | @findex TCmode | |
744 | @item SCmode, DCmode, XCmode, TCmode | |
745 | These modes stand for a complex number represented as a pair of floating | |
746 | point values. The floating point values are in @code{SFmode}, | |
747 | @code{DFmode}, @code{XFmode}, and @code{TFmode}, respectively. | |
748 | ||
749 | @findex CQImode | |
750 | @findex CHImode | |
751 | @findex CSImode | |
752 | @findex CDImode | |
753 | @findex CTImode | |
754 | @findex COImode | |
755 | @item CQImode, CHImode, CSImode, CDImode, CTImode, COImode | |
756 | These modes stand for a complex number represented as a pair of integer | |
757 | values. The integer values are in @code{QImode}, @code{HImode}, | |
758 | @code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode}, | |
759 | respectively. | |
760 | @end table | |
761 | ||
762 | The machine description defines @code{Pmode} as a C macro which expands | |
763 | into the machine mode used for addresses. Normally this is the mode | |
764 | whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines. | |
765 | ||
766 | The only modes which a machine description @i{must} support are | |
767 | @code{QImode}, and the modes corresponding to @code{BITS_PER_WORD}, | |
768 | @code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}. | |
769 | The compiler will attempt to use @code{DImode} for 8-byte structures and | |
770 | unions, but this can be prevented by overriding the definition of | |
771 | @code{MAX_FIXED_MODE_SIZE}. Alternatively, you can have the compiler | |
772 | use @code{TImode} for 16-byte structures and unions. Likewise, you can | |
773 | arrange for the C type @code{short int} to avoid using @code{HImode}. | |
774 | ||
775 | @cindex mode classes | |
776 | Very few explicit references to machine modes remain in the compiler and | |
777 | these few references will soon be removed. Instead, the machine modes | |
778 | are divided into mode classes. These are represented by the enumeration | |
779 | type @code{enum mode_class} defined in @file{machmode.h}. The possible | |
780 | mode classes are: | |
781 | ||
782 | @table @code | |
783 | @findex MODE_INT | |
784 | @item MODE_INT | |
785 | Integer modes. By default these are @code{QImode}, @code{HImode}, | |
786 | @code{SImode}, @code{DImode}, and @code{TImode}. | |
787 | ||
788 | @findex MODE_PARTIAL_INT | |
789 | @item MODE_PARTIAL_INT | |
790 | The ``partial integer'' modes, @code{PSImode} and @code{PDImode}. | |
791 | ||
792 | @findex MODE_FLOAT | |
793 | @item MODE_FLOAT | |
794 | floating point modes. By default these are @code{SFmode}, @code{DFmode}, | |
795 | @code{XFmode} and @code{TFmode}. | |
796 | ||
797 | @findex MODE_COMPLEX_INT | |
798 | @item MODE_COMPLEX_INT | |
799 | Complex integer modes. (These are not currently implemented). | |
800 | ||
801 | @findex MODE_COMPLEX_FLOAT | |
802 | @item MODE_COMPLEX_FLOAT | |
803 | Complex floating point modes. By default these are @code{SCmode}, | |
804 | @code{DCmode}, @code{XCmode}, and @code{TCmode}. | |
805 | ||
806 | @findex MODE_FUNCTION | |
807 | @item MODE_FUNCTION | |
808 | Algol or Pascal function variables including a static chain. | |
809 | (These are not currently implemented). | |
810 | ||
811 | @findex MODE_CC | |
812 | @item MODE_CC | |
813 | Modes representing condition code values. These are @code{CCmode} plus | |
814 | any modes listed in the @code{EXTRA_CC_MODES} macro. @xref{Jump Patterns}, | |
815 | also see @ref{Condition Code}. | |
816 | ||
817 | @findex MODE_RANDOM | |
818 | @item MODE_RANDOM | |
819 | This is a catchall mode class for modes which don't fit into the above | |
820 | classes. Currently @code{VOIDmode} and @code{BLKmode} are in | |
821 | @code{MODE_RANDOM}. | |
822 | @end table | |
823 | ||
824 | Here are some C macros that relate to machine modes: | |
825 | ||
826 | @table @code | |
827 | @findex GET_MODE | |
828 | @item GET_MODE (@var{x}) | |
829 | Returns the machine mode of the RTX @var{x}. | |
830 | ||
831 | @findex PUT_MODE | |
832 | @item PUT_MODE (@var{x}, @var{newmode}) | |
833 | Alters the machine mode of the RTX @var{x} to be @var{newmode}. | |
834 | ||
835 | @findex NUM_MACHINE_MODES | |
836 | @item NUM_MACHINE_MODES | |
837 | Stands for the number of machine modes available on the target | |
838 | machine. This is one greater than the largest numeric value of any | |
839 | machine mode. | |
840 | ||
841 | @findex GET_MODE_NAME | |
842 | @item GET_MODE_NAME (@var{m}) | |
843 | Returns the name of mode @var{m} as a string. | |
844 | ||
845 | @findex GET_MODE_CLASS | |
846 | @item GET_MODE_CLASS (@var{m}) | |
847 | Returns the mode class of mode @var{m}. | |
848 | ||
849 | @findex GET_MODE_WIDER_MODE | |
850 | @item GET_MODE_WIDER_MODE (@var{m}) | |
851 | Returns the next wider natural mode. For example, the expression | |
852 | @code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}. | |
853 | ||
854 | @findex GET_MODE_SIZE | |
855 | @item GET_MODE_SIZE (@var{m}) | |
856 | Returns the size in bytes of a datum of mode @var{m}. | |
857 | ||
858 | @findex GET_MODE_BITSIZE | |
859 | @item GET_MODE_BITSIZE (@var{m}) | |
860 | Returns the size in bits of a datum of mode @var{m}. | |
861 | ||
862 | @findex GET_MODE_MASK | |
863 | @item GET_MODE_MASK (@var{m}) | |
864 | Returns a bitmask containing 1 for all bits in a word that fit within | |
865 | mode @var{m}. This macro can only be used for modes whose bitsize is | |
866 | less than or equal to @code{HOST_BITS_PER_INT}. | |
867 | ||
868 | @findex GET_MODE_ALIGNMENT | |
305f3003 | 869 | @item GET_MODE_ALIGNMENT (@var{m}) |
89045fd1 JL |
870 | Return the required alignment, in bits, for an object of mode @var{m}. |
871 | ||
872 | @findex GET_MODE_UNIT_SIZE | |
873 | @item GET_MODE_UNIT_SIZE (@var{m}) | |
874 | Returns the size in bytes of the subunits of a datum of mode @var{m}. | |
875 | This is the same as @code{GET_MODE_SIZE} except in the case of complex | |
876 | modes. For them, the unit size is the size of the real or imaginary | |
877 | part. | |
878 | ||
879 | @findex GET_MODE_NUNITS | |
880 | @item GET_MODE_NUNITS (@var{m}) | |
881 | Returns the number of units contained in a mode, i.e., | |
882 | @code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}. | |
883 | ||
884 | @findex GET_CLASS_NARROWEST_MODE | |
885 | @item GET_CLASS_NARROWEST_MODE (@var{c}) | |
886 | Returns the narrowest mode in mode class @var{c}. | |
887 | @end table | |
888 | ||
889 | @findex byte_mode | |
890 | @findex word_mode | |
891 | The global variables @code{byte_mode} and @code{word_mode} contain modes | |
892 | whose classes are @code{MODE_INT} and whose bitsizes are either | |
893 | @code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit | |
894 | machines, these are @code{QImode} and @code{SImode}, respectively. | |
895 | ||
4404ce28 | 896 | @node Constants |
89045fd1 JL |
897 | @section Constant Expression Types |
898 | @cindex RTL constants | |
899 | @cindex RTL constant expression types | |
900 | ||
901 | The simplest RTL expressions are those that represent constant values. | |
902 | ||
903 | @table @code | |
904 | @findex const_int | |
905 | @item (const_int @var{i}) | |
906 | This type of expression represents the integer value @var{i}. @var{i} | |
907 | is customarily accessed with the macro @code{INTVAL} as in | |
908 | @code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}. | |
909 | ||
910 | @findex const0_rtx | |
911 | @findex const1_rtx | |
912 | @findex const2_rtx | |
913 | @findex constm1_rtx | |
914 | There is only one expression object for the integer value zero; it is | |
915 | the value of the variable @code{const0_rtx}. Likewise, the only | |
916 | expression for integer value one is found in @code{const1_rtx}, the only | |
917 | expression for integer value two is found in @code{const2_rtx}, and the | |
918 | only expression for integer value negative one is found in | |
919 | @code{constm1_rtx}. Any attempt to create an expression of code | |
920 | @code{const_int} and value zero, one, two or negative one will return | |
921 | @code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or | |
922 | @code{constm1_rtx} as appropriate.@refill | |
923 | ||
924 | @findex const_true_rtx | |
925 | Similarly, there is only one object for the integer whose value is | |
926 | @code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If | |
927 | @code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and | |
928 | @code{const1_rtx} will point to the same object. If | |
929 | @code{STORE_FLAG_VALUE} is -1, @code{const_true_rtx} and | |
930 | @code{constm1_rtx} will point to the same object.@refill | |
931 | ||
932 | @findex const_double | |
933 | @item (const_double:@var{m} @var{addr} @var{i0} @var{i1} @dots{}) | |
934 | Represents either a floating-point constant of mode @var{m} or an | |
935 | integer constant too large to fit into @code{HOST_BITS_PER_WIDE_INT} | |
936 | bits but small enough to fit within twice that number of bits (GNU CC | |
937 | does not provide a mechanism to represent even larger constants). In | |
938 | the latter case, @var{m} will be @code{VOIDmode}. | |
939 | ||
940 | @findex CONST_DOUBLE_MEM | |
941 | @findex CONST_DOUBLE_CHAIN | |
942 | @var{addr} is used to contain the @code{mem} expression that corresponds | |
943 | to the location in memory that at which the constant can be found. If | |
944 | it has not been allocated a memory location, but is on the chain of all | |
945 | @code{const_double} expressions in this compilation (maintained using an | |
946 | undisplayed field), @var{addr} contains @code{const0_rtx}. If it is not | |
947 | on the chain, @var{addr} contains @code{cc0_rtx}. @var{addr} is | |
948 | customarily accessed with the macro @code{CONST_DOUBLE_MEM} and the | |
949 | chain field via @code{CONST_DOUBLE_CHAIN}.@refill | |
950 | ||
951 | @findex CONST_DOUBLE_LOW | |
952 | If @var{m} is @code{VOIDmode}, the bits of the value are stored in | |
953 | @var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro | |
954 | @code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}. | |
955 | ||
956 | If the constant is floating point (regardless of its precision), then | |
957 | the number of integers used to store the value depends on the size of | |
958 | @code{REAL_VALUE_TYPE} (@pxref{Cross-compilation}). The integers | |
959 | represent a floating point number, but not precisely in the target | |
960 | machine's or host machine's floating point format. To convert them to | |
961 | the precise bit pattern used by the target machine, use the macro | |
962 | @code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}). | |
963 | ||
964 | @findex CONST0_RTX | |
965 | @findex CONST1_RTX | |
966 | @findex CONST2_RTX | |
967 | The macro @code{CONST0_RTX (@var{mode})} refers to an expression with | |
968 | value 0 in mode @var{mode}. If mode @var{mode} is of mode class | |
969 | @code{MODE_INT}, it returns @code{const0_rtx}. Otherwise, it returns a | |
970 | @code{CONST_DOUBLE} expression in mode @var{mode}. Similarly, the macro | |
971 | @code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in | |
972 | mode @var{mode} and similarly for @code{CONST2_RTX}. | |
973 | ||
974 | @findex const_string | |
975 | @item (const_string @var{str}) | |
976 | Represents a constant string with value @var{str}. Currently this is | |
977 | used only for insn attributes (@pxref{Insn Attributes}) since constant | |
978 | strings in C are placed in memory. | |
979 | ||
980 | @findex symbol_ref | |
981 | @item (symbol_ref:@var{mode} @var{symbol}) | |
982 | Represents the value of an assembler label for data. @var{symbol} is | |
983 | a string that describes the name of the assembler label. If it starts | |
984 | with a @samp{*}, the label is the rest of @var{symbol} not including | |
985 | the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed | |
986 | with @samp{_}. | |
987 | ||
988 | The @code{symbol_ref} contains a mode, which is usually @code{Pmode}. | |
989 | Usually that is the only mode for which a symbol is directly valid. | |
990 | ||
991 | @findex label_ref | |
992 | @item (label_ref @var{label}) | |
993 | Represents the value of an assembler label for code. It contains one | |
994 | operand, an expression, which must be a @code{code_label} that appears | |
995 | in the instruction sequence to identify the place where the label | |
996 | should go. | |
997 | ||
998 | The reason for using a distinct expression type for code label | |
999 | references is so that jump optimization can distinguish them. | |
1000 | ||
1001 | @item (const:@var{m} @var{exp}) | |
1002 | Represents a constant that is the result of an assembly-time | |
1003 | arithmetic computation. The operand, @var{exp}, is an expression that | |
1004 | contains only constants (@code{const_int}, @code{symbol_ref} and | |
1005 | @code{label_ref} expressions) combined with @code{plus} and | |
1006 | @code{minus}. However, not all combinations are valid, since the | |
1007 | assembler cannot do arbitrary arithmetic on relocatable symbols. | |
1008 | ||
1009 | @var{m} should be @code{Pmode}. | |
1010 | ||
1011 | @findex high | |
1012 | @item (high:@var{m} @var{exp}) | |
1013 | Represents the high-order bits of @var{exp}, usually a | |
1014 | @code{symbol_ref}. The number of bits is machine-dependent and is | |
1015 | normally the number of bits specified in an instruction that initializes | |
1016 | the high order bits of a register. It is used with @code{lo_sum} to | |
1017 | represent the typical two-instruction sequence used in RISC machines to | |
1018 | reference a global memory location. | |
1019 | ||
1020 | @var{m} should be @code{Pmode}. | |
1021 | @end table | |
1022 | ||
4404ce28 | 1023 | @node Regs and Memory |
89045fd1 JL |
1024 | @section Registers and Memory |
1025 | @cindex RTL register expressions | |
1026 | @cindex RTL memory expressions | |
1027 | ||
1028 | Here are the RTL expression types for describing access to machine | |
1029 | registers and to main memory. | |
1030 | ||
1031 | @table @code | |
1032 | @findex reg | |
1033 | @cindex hard registers | |
1034 | @cindex pseudo registers | |
1035 | @item (reg:@var{m} @var{n}) | |
1036 | For small values of the integer @var{n} (those that are less than | |
1037 | @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine | |
1038 | register number @var{n}: a @dfn{hard register}. For larger values of | |
1039 | @var{n}, it stands for a temporary value or @dfn{pseudo register}. | |
1040 | The compiler's strategy is to generate code assuming an unlimited | |
1041 | number of such pseudo registers, and later convert them into hard | |
1042 | registers or into memory references. | |
1043 | ||
1044 | @var{m} is the machine mode of the reference. It is necessary because | |
1045 | machines can generally refer to each register in more than one mode. | |
1046 | For example, a register may contain a full word but there may be | |
1047 | instructions to refer to it as a half word or as a single byte, as | |
1048 | well as instructions to refer to it as a floating point number of | |
1049 | various precisions. | |
1050 | ||
1051 | Even for a register that the machine can access in only one mode, | |
1052 | the mode must always be specified. | |
1053 | ||
1054 | The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine | |
1055 | description, since the number of hard registers on the machine is an | |
1056 | invariant characteristic of the machine. Note, however, that not | |
1057 | all of the machine registers must be general registers. All the | |
1058 | machine registers that can be used for storage of data are given | |
1059 | hard register numbers, even those that can be used only in certain | |
1060 | instructions or can hold only certain types of data. | |
1061 | ||
1062 | A hard register may be accessed in various modes throughout one | |
1063 | function, but each pseudo register is given a natural mode | |
1064 | and is accessed only in that mode. When it is necessary to describe | |
1065 | an access to a pseudo register using a nonnatural mode, a @code{subreg} | |
1066 | expression is used. | |
1067 | ||
1068 | A @code{reg} expression with a machine mode that specifies more than | |
1069 | one word of data may actually stand for several consecutive registers. | |
1070 | If in addition the register number specifies a hardware register, then | |
1071 | it actually represents several consecutive hardware registers starting | |
1072 | with the specified one. | |
1073 | ||
1074 | Each pseudo register number used in a function's RTL code is | |
1075 | represented by a unique @code{reg} expression. | |
1076 | ||
1077 | @findex FIRST_VIRTUAL_REGISTER | |
1078 | @findex LAST_VIRTUAL_REGISTER | |
1079 | Some pseudo register numbers, those within the range of | |
1080 | @code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only | |
1081 | appear during the RTL generation phase and are eliminated before the | |
1082 | optimization phases. These represent locations in the stack frame that | |
1083 | cannot be determined until RTL generation for the function has been | |
1084 | completed. The following virtual register numbers are defined: | |
1085 | ||
1086 | @table @code | |
1087 | @findex VIRTUAL_INCOMING_ARGS_REGNUM | |
1088 | @item VIRTUAL_INCOMING_ARGS_REGNUM | |
1089 | This points to the first word of the incoming arguments passed on the | |
1090 | stack. Normally these arguments are placed there by the caller, but the | |
1091 | callee may have pushed some arguments that were previously passed in | |
1092 | registers. | |
1093 | ||
1094 | @cindex @code{FIRST_PARM_OFFSET} and virtual registers | |
1095 | @cindex @code{ARG_POINTER_REGNUM} and virtual registers | |
1096 | When RTL generation is complete, this virtual register is replaced | |
1097 | by the sum of the register given by @code{ARG_POINTER_REGNUM} and the | |
1098 | value of @code{FIRST_PARM_OFFSET}. | |
1099 | ||
1100 | @findex VIRTUAL_STACK_VARS_REGNUM | |
1101 | @cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers | |
1102 | @item VIRTUAL_STACK_VARS_REGNUM | |
1103 | If @code{FRAME_GROWS_DOWNWARD} is defined, this points to immediately | |
1104 | above the first variable on the stack. Otherwise, it points to the | |
1105 | first variable on the stack. | |
1106 | ||
1107 | @cindex @code{STARTING_FRAME_OFFSET} and virtual registers | |
1108 | @cindex @code{FRAME_POINTER_REGNUM} and virtual registers | |
1109 | @code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the | |
1110 | register given by @code{FRAME_POINTER_REGNUM} and the value | |
1111 | @code{STARTING_FRAME_OFFSET}. | |
1112 | ||
1113 | @findex VIRTUAL_STACK_DYNAMIC_REGNUM | |
1114 | @item VIRTUAL_STACK_DYNAMIC_REGNUM | |
1115 | This points to the location of dynamically allocated memory on the stack | |
1116 | immediately after the stack pointer has been adjusted by the amount of | |
1117 | memory desired. | |
1118 | ||
1119 | @cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers | |
1120 | @cindex @code{STACK_POINTER_REGNUM} and virtual registers | |
1121 | This virtual register is replaced by the sum of the register given by | |
1122 | @code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}. | |
1123 | ||
1124 | @findex VIRTUAL_OUTGOING_ARGS_REGNUM | |
1125 | @item VIRTUAL_OUTGOING_ARGS_REGNUM | |
1126 | This points to the location in the stack at which outgoing arguments | |
1127 | should be written when the stack is pre-pushed (arguments pushed using | |
1128 | push insns should always use @code{STACK_POINTER_REGNUM}). | |
1129 | ||
1130 | @cindex @code{STACK_POINTER_OFFSET} and virtual registers | |
1131 | This virtual register is replaced by the sum of the register given by | |
1132 | @code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}. | |
1133 | @end table | |
1134 | ||
1135 | @findex subreg | |
1136 | @item (subreg:@var{m} @var{reg} @var{wordnum}) | |
1137 | @code{subreg} expressions are used to refer to a register in a machine | |
1138 | mode other than its natural one, or to refer to one register of | |
1139 | a multi-word @code{reg} that actually refers to several registers. | |
1140 | ||
1141 | Each pseudo-register has a natural mode. If it is necessary to | |
1142 | operate on it in a different mode---for example, to perform a fullword | |
1143 | move instruction on a pseudo-register that contains a single | |
1144 | byte---the pseudo-register must be enclosed in a @code{subreg}. In | |
1145 | such a case, @var{wordnum} is zero. | |
1146 | ||
1147 | Usually @var{m} is at least as narrow as the mode of @var{reg}, in which | |
1148 | case it is restricting consideration to only the bits of @var{reg} that | |
1149 | are in @var{m}. | |
1150 | ||
1151 | Sometimes @var{m} is wider than the mode of @var{reg}. These | |
1152 | @code{subreg} expressions are often called @dfn{paradoxical}. They are | |
1153 | used in cases where we want to refer to an object in a wider mode but do | |
1154 | not care what value the additional bits have. The reload pass ensures | |
1155 | that paradoxical references are only made to hard registers. | |
1156 | ||
1157 | The other use of @code{subreg} is to extract the individual registers of | |
1158 | a multi-register value. Machine modes such as @code{DImode} and | |
1159 | @code{TImode} can indicate values longer than a word, values which | |
1160 | usually require two or more consecutive registers. To access one of the | |
1161 | registers, use a @code{subreg} with mode @code{SImode} and a | |
1162 | @var{wordnum} that says which register. | |
1163 | ||
1164 | Storing in a non-paradoxical @code{subreg} has undefined results for | |
1165 | bits belonging to the same word as the @code{subreg}. This laxity makes | |
1166 | it easier to generate efficient code for such instructions. To | |
1167 | represent an instruction that preserves all the bits outside of those in | |
1168 | the @code{subreg}, use @code{strict_low_part} around the @code{subreg}. | |
1169 | ||
1170 | @cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg} | |
1171 | The compilation parameter @code{WORDS_BIG_ENDIAN}, if set to 1, says | |
1172 | that word number zero is the most significant part; otherwise, it is | |
1173 | the least significant part. | |
1174 | ||
a6765b81 JR |
1175 | @cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg} |
1176 | On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with | |
1177 | @code{WORDS_BIG_ENDIAN}. | |
1178 | However, most parts of the compiler treat floating point values as if | |
1179 | they had the same endianness as integer values. This works because | |
1180 | they handle them solely as a collection of integer values, with no | |
1181 | particular numerical value. Only real.c and the runtime libraries | |
1182 | care about @code{FLOAT_WORDS_BIG_ENDIAN}. | |
1183 | ||
89045fd1 JL |
1184 | @cindex combiner pass |
1185 | @cindex reload pass | |
1186 | @cindex @code{subreg}, special reload handling | |
1187 | Between the combiner pass and the reload pass, it is possible to have a | |
1188 | paradoxical @code{subreg} which contains a @code{mem} instead of a | |
1189 | @code{reg} as its first operand. After the reload pass, it is also | |
1190 | possible to have a non-paradoxical @code{subreg} which contains a | |
1191 | @code{mem}; this usually occurs when the @code{mem} is a stack slot | |
1192 | which replaced a pseudo register. | |
1193 | ||
1194 | Note that it is not valid to access a @code{DFmode} value in @code{SFmode} | |
1195 | using a @code{subreg}. On some machines the most significant part of a | |
1196 | @code{DFmode} value does not have the same format as a single-precision | |
1197 | floating value. | |
1198 | ||
1199 | It is also not valid to access a single word of a multi-word value in a | |
1200 | hard register when less registers can hold the value than would be | |
1201 | expected from its size. For example, some 32-bit machines have | |
1202 | floating-point registers that can hold an entire @code{DFmode} value. | |
1203 | If register 10 were such a register @code{(subreg:SI (reg:DF 10) 1)} | |
1204 | would be invalid because there is no way to convert that reference to | |
1205 | a single machine register. The reload pass prevents @code{subreg} | |
1206 | expressions such as these from being formed. | |
1207 | ||
1208 | @findex SUBREG_REG | |
1209 | @findex SUBREG_WORD | |
1210 | The first operand of a @code{subreg} expression is customarily accessed | |
1211 | with the @code{SUBREG_REG} macro and the second operand is customarily | |
1212 | accessed with the @code{SUBREG_WORD} macro. | |
1213 | ||
1214 | @findex scratch | |
1215 | @cindex scratch operands | |
1216 | @item (scratch:@var{m}) | |
1217 | This represents a scratch register that will be required for the | |
1218 | execution of a single instruction and not used subsequently. It is | |
1219 | converted into a @code{reg} by either the local register allocator or | |
1220 | the reload pass. | |
1221 | ||
1222 | @code{scratch} is usually present inside a @code{clobber} operation | |
1223 | (@pxref{Side Effects}). | |
1224 | ||
1225 | @findex cc0 | |
1226 | @cindex condition code register | |
1227 | @item (cc0) | |
1228 | This refers to the machine's condition code register. It has no | |
1229 | operands and may not have a machine mode. There are two ways to use it: | |
1230 | ||
1231 | @itemize @bullet | |
1232 | @item | |
1233 | To stand for a complete set of condition code flags. This is best on | |
1234 | most machines, where each comparison sets the entire series of flags. | |
1235 | ||
1236 | With this technique, @code{(cc0)} may be validly used in only two | |
1237 | contexts: as the destination of an assignment (in test and compare | |
1238 | instructions) and in comparison operators comparing against zero | |
1239 | (@code{const_int} with value zero; that is to say, @code{const0_rtx}). | |
1240 | ||
1241 | @item | |
1242 | To stand for a single flag that is the result of a single condition. | |
1243 | This is useful on machines that have only a single flag bit, and in | |
1244 | which comparison instructions must specify the condition to test. | |
1245 | ||
1246 | With this technique, @code{(cc0)} may be validly used in only two | |
1247 | contexts: as the destination of an assignment (in test and compare | |
1248 | instructions) where the source is a comparison operator, and as the | |
1249 | first operand of @code{if_then_else} (in a conditional branch). | |
1250 | @end itemize | |
1251 | ||
1252 | @findex cc0_rtx | |
1253 | There is only one expression object of code @code{cc0}; it is the | |
1254 | value of the variable @code{cc0_rtx}. Any attempt to create an | |
1255 | expression of code @code{cc0} will return @code{cc0_rtx}. | |
1256 | ||
1257 | Instructions can set the condition code implicitly. On many machines, | |
1258 | nearly all instructions set the condition code based on the value that | |
1259 | they compute or store. It is not necessary to record these actions | |
1260 | explicitly in the RTL because the machine description includes a | |
1261 | prescription for recognizing the instructions that do so (by means of | |
1262 | the macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only | |
1263 | instructions whose sole purpose is to set the condition code, and | |
1264 | instructions that use the condition code, need mention @code{(cc0)}. | |
1265 | ||
1266 | On some machines, the condition code register is given a register number | |
1267 | and a @code{reg} is used instead of @code{(cc0)}. This is usually the | |
1268 | preferable approach if only a small subset of instructions modify the | |
1269 | condition code. Other machines store condition codes in general | |
1270 | registers; in such cases a pseudo register should be used. | |
1271 | ||
1272 | Some machines, such as the Sparc and RS/6000, have two sets of | |
1273 | arithmetic instructions, one that sets and one that does not set the | |
1274 | condition code. This is best handled by normally generating the | |
1275 | instruction that does not set the condition code, and making a pattern | |
1276 | that both performs the arithmetic and sets the condition code register | |
1277 | (which would not be @code{(cc0)} in this case). For examples, search | |
1278 | for @samp{addcc} and @samp{andcc} in @file{sparc.md}. | |
1279 | ||
1280 | @findex pc | |
1281 | @item (pc) | |
1282 | @cindex program counter | |
1283 | This represents the machine's program counter. It has no operands and | |
1284 | may not have a machine mode. @code{(pc)} may be validly used only in | |
1285 | certain specific contexts in jump instructions. | |
1286 | ||
1287 | @findex pc_rtx | |
1288 | There is only one expression object of code @code{pc}; it is the value | |
1289 | of the variable @code{pc_rtx}. Any attempt to create an expression of | |
1290 | code @code{pc} will return @code{pc_rtx}. | |
1291 | ||
1292 | All instructions that do not jump alter the program counter implicitly | |
1293 | by incrementing it, but there is no need to mention this in the RTL. | |
1294 | ||
1295 | @findex mem | |
14592a41 | 1296 | @item (mem:@var{m} @var{addr} @var{alias}) |
89045fd1 JL |
1297 | This RTX represents a reference to main memory at an address |
1298 | represented by the expression @var{addr}. @var{m} specifies how large | |
14592a41 DN |
1299 | a unit of memory is accessed. @var{alias} specifies an alias set for the |
1300 | reference. In general two items are in different alias sets if they cannot | |
1301 | reference the same memory address. | |
e9a25f70 JL |
1302 | |
1303 | @findex addressof | |
1304 | @item (addressof:@var{m} @var{reg}) | |
1305 | This RTX represents a request for the address of register @var{reg}. Its mode | |
1306 | is always @code{Pmode}. If there are any @code{addressof} | |
1307 | expressions left in the function after CSE, @var{reg} is forced into the | |
1308 | stack and the @code{addressof} expression is replaced with a @code{plus} | |
1309 | expression for the address of its stack slot. | |
89045fd1 JL |
1310 | @end table |
1311 | ||
4404ce28 | 1312 | @node Arithmetic |
89045fd1 JL |
1313 | @section RTL Expressions for Arithmetic |
1314 | @cindex arithmetic, in RTL | |
1315 | @cindex math, in RTL | |
1316 | @cindex RTL expressions for arithmetic | |
1317 | ||
1318 | Unless otherwise specified, all the operands of arithmetic expressions | |
1319 | must be valid for mode @var{m}. An operand is valid for mode @var{m} | |
1320 | if it has mode @var{m}, or if it is a @code{const_int} or | |
1321 | @code{const_double} and @var{m} is a mode of class @code{MODE_INT}. | |
1322 | ||
1323 | For commutative binary operations, constants should be placed in the | |
1324 | second operand. | |
1325 | ||
1326 | @table @code | |
1327 | @findex plus | |
1328 | @cindex RTL addition | |
1329 | @cindex RTL sum | |
1330 | @item (plus:@var{m} @var{x} @var{y}) | |
1331 | Represents the sum of the values represented by @var{x} and @var{y} | |
1332 | carried out in machine mode @var{m}. | |
1333 | ||
1334 | @findex lo_sum | |
1335 | @item (lo_sum:@var{m} @var{x} @var{y}) | |
1336 | Like @code{plus}, except that it represents that sum of @var{x} and the | |
1337 | low-order bits of @var{y}. The number of low order bits is | |
1338 | machine-dependent but is normally the number of bits in a @code{Pmode} | |
1339 | item minus the number of bits set by the @code{high} code | |
1340 | (@pxref{Constants}). | |
1341 | ||
1342 | @var{m} should be @code{Pmode}. | |
1343 | ||
1344 | @findex minus | |
1345 | @cindex RTL subtraction | |
1346 | @cindex RTL difference | |
1347 | @item (minus:@var{m} @var{x} @var{y}) | |
1348 | Like @code{plus} but represents subtraction. | |
1349 | ||
1350 | @findex compare | |
1351 | @cindex RTL comparison | |
1352 | @item (compare:@var{m} @var{x} @var{y}) | |
1353 | Represents the result of subtracting @var{y} from @var{x} for purposes | |
1354 | of comparison. The result is computed without overflow, as if with | |
1355 | infinite precision. | |
1356 | ||
1357 | Of course, machines can't really subtract with infinite precision. | |
1358 | However, they can pretend to do so when only the sign of the | |
1359 | result will be used, which is the case when the result is stored | |
1360 | in the condition code. And that is the only way this kind of expression | |
1361 | may validly be used: as a value to be stored in the condition codes. | |
1362 | ||
1363 | The mode @var{m} is not related to the modes of @var{x} and @var{y}, | |
1364 | but instead is the mode of the condition code value. If @code{(cc0)} | |
1365 | is used, it is @code{VOIDmode}. Otherwise it is some mode in class | |
1366 | @code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}. | |
1367 | ||
1368 | Normally, @var{x} and @var{y} must have the same mode. Otherwise, | |
1369 | @code{compare} is valid only if the mode of @var{x} is in class | |
1370 | @code{MODE_INT} and @var{y} is a @code{const_int} or | |
1371 | @code{const_double} with mode @code{VOIDmode}. The mode of @var{x} | |
1372 | determines what mode the comparison is to be done in; thus it must not | |
1373 | be @code{VOIDmode}. | |
1374 | ||
1375 | If one of the operands is a constant, it should be placed in the | |
1376 | second operand and the comparison code adjusted as appropriate. | |
1377 | ||
1378 | A @code{compare} specifying two @code{VOIDmode} constants is not valid | |
1379 | since there is no way to know in what mode the comparison is to be | |
1380 | performed; the comparison must either be folded during the compilation | |
1381 | or the first operand must be loaded into a register while its mode is | |
1382 | still known. | |
1383 | ||
1384 | @findex neg | |
1385 | @item (neg:@var{m} @var{x}) | |
1386 | Represents the negation (subtraction from zero) of the value represented | |
1387 | by @var{x}, carried out in mode @var{m}. | |
1388 | ||
1389 | @findex mult | |
1390 | @cindex multiplication | |
1391 | @cindex product | |
1392 | @item (mult:@var{m} @var{x} @var{y}) | |
1393 | Represents the signed product of the values represented by @var{x} and | |
1394 | @var{y} carried out in machine mode @var{m}. | |
1395 | ||
1396 | Some machines support a multiplication that generates a product wider | |
1397 | than the operands. Write the pattern for this as | |
1398 | ||
1399 | @example | |
1400 | (mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y})) | |
1401 | @end example | |
1402 | ||
1403 | where @var{m} is wider than the modes of @var{x} and @var{y}, which need | |
1404 | not be the same. | |
1405 | ||
1406 | Write patterns for unsigned widening multiplication similarly using | |
1407 | @code{zero_extend}. | |
1408 | ||
1409 | @findex div | |
1410 | @cindex division | |
1411 | @cindex signed division | |
1412 | @cindex quotient | |
1413 | @item (div:@var{m} @var{x} @var{y}) | |
1414 | Represents the quotient in signed division of @var{x} by @var{y}, | |
1415 | carried out in machine mode @var{m}. If @var{m} is a floating point | |
1416 | mode, it represents the exact quotient; otherwise, the integerized | |
1417 | quotient. | |
1418 | ||
1419 | Some machines have division instructions in which the operands and | |
1420 | quotient widths are not all the same; you should represent | |
1421 | such instructions using @code{truncate} and @code{sign_extend} as in, | |
1422 | ||
1423 | @example | |
1424 | (truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y}))) | |
1425 | @end example | |
1426 | ||
1427 | @findex udiv | |
1428 | @cindex unsigned division | |
1429 | @cindex division | |
1430 | @item (udiv:@var{m} @var{x} @var{y}) | |
1431 | Like @code{div} but represents unsigned division. | |
1432 | ||
1433 | @findex mod | |
1434 | @findex umod | |
1435 | @cindex remainder | |
1436 | @cindex division | |
1437 | @item (mod:@var{m} @var{x} @var{y}) | |
1438 | @itemx (umod:@var{m} @var{x} @var{y}) | |
1439 | Like @code{div} and @code{udiv} but represent the remainder instead of | |
1440 | the quotient. | |
1441 | ||
1442 | @findex smin | |
1443 | @findex smax | |
1444 | @cindex signed minimum | |
1445 | @cindex signed maximum | |
1446 | @item (smin:@var{m} @var{x} @var{y}) | |
1447 | @itemx (smax:@var{m} @var{x} @var{y}) | |
1448 | Represents the smaller (for @code{smin}) or larger (for @code{smax}) of | |
1449 | @var{x} and @var{y}, interpreted as signed integers in mode @var{m}. | |
1450 | ||
1451 | @findex umin | |
1452 | @findex umax | |
1453 | @cindex unsigned minimum and maximum | |
1454 | @item (umin:@var{m} @var{x} @var{y}) | |
1455 | @itemx (umax:@var{m} @var{x} @var{y}) | |
1456 | Like @code{smin} and @code{smax}, but the values are interpreted as unsigned | |
1457 | integers. | |
1458 | ||
1459 | @findex not | |
1460 | @cindex complement, bitwise | |
1461 | @cindex bitwise complement | |
1462 | @item (not:@var{m} @var{x}) | |
1463 | Represents the bitwise complement of the value represented by @var{x}, | |
1464 | carried out in mode @var{m}, which must be a fixed-point machine mode. | |
1465 | ||
1466 | @findex and | |
1467 | @cindex logical-and, bitwise | |
1468 | @cindex bitwise logical-and | |
1469 | @item (and:@var{m} @var{x} @var{y}) | |
1470 | Represents the bitwise logical-and of the values represented by | |
1471 | @var{x} and @var{y}, carried out in machine mode @var{m}, which must be | |
1472 | a fixed-point machine mode. | |
1473 | ||
1474 | @findex ior | |
1475 | @cindex inclusive-or, bitwise | |
1476 | @cindex bitwise inclusive-or | |
1477 | @item (ior:@var{m} @var{x} @var{y}) | |
1478 | Represents the bitwise inclusive-or of the values represented by @var{x} | |
1479 | and @var{y}, carried out in machine mode @var{m}, which must be a | |
1480 | fixed-point mode. | |
1481 | ||
1482 | @findex xor | |
1483 | @cindex exclusive-or, bitwise | |
1484 | @cindex bitwise exclusive-or | |
1485 | @item (xor:@var{m} @var{x} @var{y}) | |
1486 | Represents the bitwise exclusive-or of the values represented by @var{x} | |
1487 | and @var{y}, carried out in machine mode @var{m}, which must be a | |
1488 | fixed-point mode. | |
1489 | ||
1490 | @findex ashift | |
1491 | @cindex left shift | |
1492 | @cindex shift | |
1493 | @cindex arithmetic shift | |
1494 | @item (ashift:@var{m} @var{x} @var{c}) | |
1495 | Represents the result of arithmetically shifting @var{x} left by @var{c} | |
1496 | places. @var{x} have mode @var{m}, a fixed-point machine mode. @var{c} | |
1497 | be a fixed-point mode or be a constant with mode @code{VOIDmode}; which | |
1498 | mode is determined by the mode called for in the machine description | |
1499 | entry for the left-shift instruction. For example, on the Vax, the mode | |
1500 | of @var{c} is @code{QImode} regardless of @var{m}. | |
1501 | ||
1502 | @findex lshiftrt | |
1503 | @cindex right shift | |
1504 | @findex ashiftrt | |
1505 | @item (lshiftrt:@var{m} @var{x} @var{c}) | |
1506 | @itemx (ashiftrt:@var{m} @var{x} @var{c}) | |
1507 | Like @code{ashift} but for right shift. Unlike the case for left shift, | |
1508 | these two operations are distinct. | |
1509 | ||
1510 | @findex rotate | |
1511 | @cindex rotate | |
1512 | @cindex left rotate | |
1513 | @findex rotatert | |
1514 | @cindex right rotate | |
1515 | @item (rotate:@var{m} @var{x} @var{c}) | |
1516 | @itemx (rotatert:@var{m} @var{x} @var{c}) | |
1517 | Similar but represent left and right rotate. If @var{c} is a constant, | |
1518 | use @code{rotate}. | |
1519 | ||
1520 | @findex abs | |
1521 | @cindex absolute value | |
1522 | @item (abs:@var{m} @var{x}) | |
1523 | Represents the absolute value of @var{x}, computed in mode @var{m}. | |
1524 | ||
1525 | @findex sqrt | |
1526 | @cindex square root | |
1527 | @item (sqrt:@var{m} @var{x}) | |
1528 | Represents the square root of @var{x}, computed in mode @var{m}. | |
1529 | Most often @var{m} will be a floating point mode. | |
1530 | ||
1531 | @findex ffs | |
1532 | @item (ffs:@var{m} @var{x}) | |
1533 | Represents one plus the index of the least significant 1-bit in | |
1534 | @var{x}, represented as an integer of mode @var{m}. (The value is | |
1535 | zero if @var{x} is zero.) The mode of @var{x} need not be @var{m}; | |
1536 | depending on the target machine, various mode combinations may be | |
1537 | valid. | |
1538 | @end table | |
1539 | ||
4404ce28 | 1540 | @node Comparisons |
89045fd1 JL |
1541 | @section Comparison Operations |
1542 | @cindex RTL comparison operations | |
1543 | ||
1544 | Comparison operators test a relation on two operands and are considered | |
1545 | to represent a machine-dependent nonzero value described by, but not | |
1546 | necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc}) | |
1547 | if the relation holds, or zero if it does not. The mode of the | |
1548 | comparison operation is independent of the mode of the data being | |
1549 | compared. If the comparison operation is being tested (e.g., the first | |
1550 | operand of an @code{if_then_else}), the mode must be @code{VOIDmode}. | |
1551 | If the comparison operation is producing data to be stored in some | |
1552 | variable, the mode must be in class @code{MODE_INT}. All comparison | |
1553 | operations producing data must use the same mode, which is | |
1554 | machine-specific. | |
1555 | ||
1556 | @cindex condition codes | |
1557 | There are two ways that comparison operations may be used. The | |
1558 | comparison operators may be used to compare the condition codes | |
1559 | @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such | |
1560 | a construct actually refers to the result of the preceding instruction | |
1561 | in which the condition codes were set. The instructing setting the | |
1562 | condition code must be adjacent to the instruction using the condition | |
1563 | code; only @code{note} insns may separate them. | |
1564 | ||
1565 | Alternatively, a comparison operation may directly compare two data | |
1566 | objects. The mode of the comparison is determined by the operands; they | |
1567 | must both be valid for a common machine mode. A comparison with both | |
1568 | operands constant would be invalid as the machine mode could not be | |
1569 | deduced from it, but such a comparison should never exist in RTL due to | |
1570 | constant folding. | |
1571 | ||
1572 | In the example above, if @code{(cc0)} were last set to | |
1573 | @code{(compare @var{x} @var{y})}, the comparison operation is | |
1574 | identical to @code{(eq @var{x} @var{y})}. Usually only one style | |
1575 | of comparisons is supported on a particular machine, but the combine | |
1576 | pass will try to merge the operations to produce the @code{eq} shown | |
1577 | in case it exists in the context of the particular insn involved. | |
1578 | ||
1579 | Inequality comparisons come in two flavors, signed and unsigned. Thus, | |
1580 | there are distinct expression codes @code{gt} and @code{gtu} for signed and | |
1581 | unsigned greater-than. These can produce different results for the same | |
1582 | pair of integer values: for example, 1 is signed greater-than -1 but not | |
1583 | unsigned greater-than, because -1 when regarded as unsigned is actually | |
1584 | @code{0xffffffff} which is greater than 1. | |
1585 | ||
1586 | The signed comparisons are also used for floating point values. Floating | |
1587 | point comparisons are distinguished by the machine modes of the operands. | |
1588 | ||
1589 | @table @code | |
1590 | @findex eq | |
1591 | @cindex equal | |
1592 | @item (eq:@var{m} @var{x} @var{y}) | |
1593 | 1 if the values represented by @var{x} and @var{y} are equal, | |
1594 | otherwise 0. | |
1595 | ||
1596 | @findex ne | |
1597 | @cindex not equal | |
1598 | @item (ne:@var{m} @var{x} @var{y}) | |
1599 | 1 if the values represented by @var{x} and @var{y} are not equal, | |
1600 | otherwise 0. | |
1601 | ||
1602 | @findex gt | |
1603 | @cindex greater than | |
1604 | @item (gt:@var{m} @var{x} @var{y}) | |
1605 | 1 if the @var{x} is greater than @var{y}. If they are fixed-point, | |
1606 | the comparison is done in a signed sense. | |
1607 | ||
1608 | @findex gtu | |
1609 | @cindex greater than | |
1610 | @cindex unsigned greater than | |
1611 | @item (gtu:@var{m} @var{x} @var{y}) | |
1612 | Like @code{gt} but does unsigned comparison, on fixed-point numbers only. | |
1613 | ||
1614 | @findex lt | |
1615 | @cindex less than | |
1616 | @findex ltu | |
1617 | @cindex unsigned less than | |
1618 | @item (lt:@var{m} @var{x} @var{y}) | |
1619 | @itemx (ltu:@var{m} @var{x} @var{y}) | |
1620 | Like @code{gt} and @code{gtu} but test for ``less than''. | |
1621 | ||
1622 | @findex ge | |
1623 | @cindex greater than | |
1624 | @findex geu | |
1625 | @cindex unsigned greater than | |
1626 | @item (ge:@var{m} @var{x} @var{y}) | |
1627 | @itemx (geu:@var{m} @var{x} @var{y}) | |
1628 | Like @code{gt} and @code{gtu} but test for ``greater than or equal''. | |
1629 | ||
1630 | @findex le | |
1631 | @cindex less than or equal | |
1632 | @findex leu | |
1633 | @cindex unsigned less than | |
1634 | @item (le:@var{m} @var{x} @var{y}) | |
1635 | @itemx (leu:@var{m} @var{x} @var{y}) | |
1636 | Like @code{gt} and @code{gtu} but test for ``less than or equal''. | |
1637 | ||
1638 | @findex if_then_else | |
1639 | @item (if_then_else @var{cond} @var{then} @var{else}) | |
1640 | This is not a comparison operation but is listed here because it is | |
1641 | always used in conjunction with a comparison operation. To be | |
1642 | precise, @var{cond} is a comparison expression. This expression | |
1643 | represents a choice, according to @var{cond}, between the value | |
1644 | represented by @var{then} and the one represented by @var{else}. | |
1645 | ||
1646 | On most machines, @code{if_then_else} expressions are valid only | |
1647 | to express conditional jumps. | |
1648 | ||
1649 | @findex cond | |
1650 | @item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default}) | |
1651 | Similar to @code{if_then_else}, but more general. Each of @var{test1}, | |
1652 | @var{test2}, @dots{} is performed in turn. The result of this expression is | |
1653 | the @var{value} corresponding to the first non-zero test, or @var{default} if | |
1654 | none of the tests are non-zero expressions. | |
1655 | ||
1656 | This is currently not valid for instruction patterns and is supported only | |
1657 | for insn attributes. @xref{Insn Attributes}. | |
1658 | @end table | |
1659 | ||
4404ce28 | 1660 | @node Bit Fields |
89045fd1 JL |
1661 | @section Bit Fields |
1662 | @cindex bit fields | |
1663 | ||
1664 | Special expression codes exist to represent bitfield instructions. | |
1665 | These types of expressions are lvalues in RTL; they may appear | |
1666 | on the left side of an assignment, indicating insertion of a value | |
1667 | into the specified bit field. | |
1668 | ||
1669 | @table @code | |
1670 | @findex sign_extract | |
1671 | @cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract} | |
1672 | @item (sign_extract:@var{m} @var{loc} @var{size} @var{pos}) | |
1673 | This represents a reference to a sign-extended bit field contained or | |
1674 | starting in @var{loc} (a memory or register reference). The bit field | |
1675 | is @var{size} bits wide and starts at bit @var{pos}. The compilation | |
1676 | option @code{BITS_BIG_ENDIAN} says which end of the memory unit | |
1677 | @var{pos} counts from. | |
1678 | ||
1679 | If @var{loc} is in memory, its mode must be a single-byte integer mode. | |
1680 | If @var{loc} is in a register, the mode to use is specified by the | |
1681 | operand of the @code{insv} or @code{extv} pattern | |
1682 | (@pxref{Standard Names}) and is usually a full-word integer mode, | |
1683 | which is the default if none is specified. | |
1684 | ||
1685 | The mode of @var{pos} is machine-specific and is also specified | |
1686 | in the @code{insv} or @code{extv} pattern. | |
1687 | ||
1688 | The mode @var{m} is the same as the mode that would be used for | |
1689 | @var{loc} if it were a register. | |
1690 | ||
1691 | @findex zero_extract | |
1692 | @item (zero_extract:@var{m} @var{loc} @var{size} @var{pos}) | |
1693 | Like @code{sign_extract} but refers to an unsigned or zero-extended | |
1694 | bit field. The same sequence of bits are extracted, but they | |
1695 | are filled to an entire word with zeros instead of by sign-extension. | |
1696 | @end table | |
1697 | ||
4404ce28 | 1698 | @node Conversions |
89045fd1 JL |
1699 | @section Conversions |
1700 | @cindex conversions | |
1701 | @cindex machine mode conversions | |
1702 | ||
1703 | All conversions between machine modes must be represented by | |
1704 | explicit conversion operations. For example, an expression | |
1705 | which is the sum of a byte and a full word cannot be written as | |
1706 | @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus} | |
1707 | operation requires two operands of the same machine mode. | |
1708 | Therefore, the byte-sized operand is enclosed in a conversion | |
1709 | operation, as in | |
1710 | ||
1711 | @example | |
1712 | (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80)) | |
1713 | @end example | |
1714 | ||
1715 | The conversion operation is not a mere placeholder, because there | |
1716 | may be more than one way of converting from a given starting mode | |
1717 | to the desired final mode. The conversion operation code says how | |
1718 | to do it. | |
1719 | ||
1720 | For all conversion operations, @var{x} must not be @code{VOIDmode} | |
1721 | because the mode in which to do the conversion would not be known. | |
1722 | The conversion must either be done at compile-time or @var{x} | |
1723 | must be placed into a register. | |
1724 | ||
1725 | @table @code | |
1726 | @findex sign_extend | |
1727 | @item (sign_extend:@var{m} @var{x}) | |
1728 | Represents the result of sign-extending the value @var{x} | |
1729 | to machine mode @var{m}. @var{m} must be a fixed-point mode | |
1730 | and @var{x} a fixed-point value of a mode narrower than @var{m}. | |
1731 | ||
1732 | @findex zero_extend | |
1733 | @item (zero_extend:@var{m} @var{x}) | |
1734 | Represents the result of zero-extending the value @var{x} | |
1735 | to machine mode @var{m}. @var{m} must be a fixed-point mode | |
1736 | and @var{x} a fixed-point value of a mode narrower than @var{m}. | |
1737 | ||
1738 | @findex float_extend | |
1739 | @item (float_extend:@var{m} @var{x}) | |
1740 | Represents the result of extending the value @var{x} | |
1741 | to machine mode @var{m}. @var{m} must be a floating point mode | |
1742 | and @var{x} a floating point value of a mode narrower than @var{m}. | |
1743 | ||
1744 | @findex truncate | |
1745 | @item (truncate:@var{m} @var{x}) | |
1746 | Represents the result of truncating the value @var{x} | |
1747 | to machine mode @var{m}. @var{m} must be a fixed-point mode | |
1748 | and @var{x} a fixed-point value of a mode wider than @var{m}. | |
1749 | ||
1750 | @findex float_truncate | |
1751 | @item (float_truncate:@var{m} @var{x}) | |
1752 | Represents the result of truncating the value @var{x} | |
1753 | to machine mode @var{m}. @var{m} must be a floating point mode | |
1754 | and @var{x} a floating point value of a mode wider than @var{m}. | |
1755 | ||
1756 | @findex float | |
1757 | @item (float:@var{m} @var{x}) | |
1758 | Represents the result of converting fixed point value @var{x}, | |
1759 | regarded as signed, to floating point mode @var{m}. | |
1760 | ||
1761 | @findex unsigned_float | |
1762 | @item (unsigned_float:@var{m} @var{x}) | |
1763 | Represents the result of converting fixed point value @var{x}, | |
1764 | regarded as unsigned, to floating point mode @var{m}. | |
1765 | ||
1766 | @findex fix | |
1767 | @item (fix:@var{m} @var{x}) | |
1768 | When @var{m} is a fixed point mode, represents the result of | |
1769 | converting floating point value @var{x} to mode @var{m}, regarded as | |
1770 | signed. How rounding is done is not specified, so this operation may | |
1771 | be used validly in compiling C code only for integer-valued operands. | |
1772 | ||
1773 | @findex unsigned_fix | |
1774 | @item (unsigned_fix:@var{m} @var{x}) | |
1775 | Represents the result of converting floating point value @var{x} to | |
1776 | fixed point mode @var{m}, regarded as unsigned. How rounding is done | |
1777 | is not specified. | |
1778 | ||
1779 | @findex fix | |
1780 | @item (fix:@var{m} @var{x}) | |
1781 | When @var{m} is a floating point mode, represents the result of | |
1782 | converting floating point value @var{x} (valid for mode @var{m}) to an | |
1783 | integer, still represented in floating point mode @var{m}, by rounding | |
1784 | towards zero. | |
1785 | @end table | |
1786 | ||
4404ce28 | 1787 | @node RTL Declarations |
89045fd1 JL |
1788 | @section Declarations |
1789 | @cindex RTL declarations | |
1790 | @cindex declarations, RTL | |
1791 | ||
1792 | Declaration expression codes do not represent arithmetic operations | |
1793 | but rather state assertions about their operands. | |
1794 | ||
1795 | @table @code | |
1796 | @findex strict_low_part | |
1797 | @cindex @code{subreg}, in @code{strict_low_part} | |
1798 | @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0)) | |
1799 | This expression code is used in only one context: as the destination operand of a | |
1800 | @code{set} expression. In addition, the operand of this expression | |
1801 | must be a non-paradoxical @code{subreg} expression. | |
1802 | ||
1803 | The presence of @code{strict_low_part} says that the part of the | |
1804 | register which is meaningful in mode @var{n}, but is not part of | |
1805 | mode @var{m}, is not to be altered. Normally, an assignment to such | |
1806 | a subreg is allowed to have undefined effects on the rest of the | |
1807 | register when @var{m} is less than a word. | |
1808 | @end table | |
1809 | ||
4404ce28 | 1810 | @node Side Effects |
89045fd1 JL |
1811 | @section Side Effect Expressions |
1812 | @cindex RTL side effect expressions | |
1813 | ||
1814 | The expression codes described so far represent values, not actions. | |
1815 | But machine instructions never produce values; they are meaningful | |
1816 | only for their side effects on the state of the machine. Special | |
1817 | expression codes are used to represent side effects. | |
1818 | ||
1819 | The body of an instruction is always one of these side effect codes; | |
1820 | the codes described above, which represent values, appear only as | |
1821 | the operands of these. | |
1822 | ||
1823 | @table @code | |
1824 | @findex set | |
1825 | @item (set @var{lval} @var{x}) | |
1826 | Represents the action of storing the value of @var{x} into the place | |
1827 | represented by @var{lval}. @var{lval} must be an expression | |
1828 | representing a place that can be stored in: @code{reg} (or | |
1829 | @code{subreg} or @code{strict_low_part}), @code{mem}, @code{pc} or | |
1830 | @code{cc0}.@refill | |
1831 | ||
1832 | If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a | |
1833 | machine mode; then @var{x} must be valid for that mode.@refill | |
1834 | ||
1835 | If @var{lval} is a @code{reg} whose machine mode is less than the full | |
1836 | width of the register, then it means that the part of the register | |
1837 | specified by the machine mode is given the specified value and the | |
1838 | rest of the register receives an undefined value. Likewise, if | |
1839 | @var{lval} is a @code{subreg} whose machine mode is narrower than | |
1840 | the mode of the register, the rest of the register can be changed in | |
1841 | an undefined way. | |
1842 | ||
1843 | If @var{lval} is a @code{strict_low_part} of a @code{subreg}, then the | |
1844 | part of the register specified by the machine mode of the | |
1845 | @code{subreg} is given the value @var{x} and the rest of the register | |
1846 | is not changed.@refill | |
1847 | ||
1848 | If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may | |
1849 | be either a @code{compare} expression or a value that may have any mode. | |
1850 | The latter case represents a ``test'' instruction. The expression | |
1851 | @code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to | |
1852 | @code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}. | |
1853 | Use the former expression to save space during the compilation. | |
1854 | ||
1855 | @cindex jump instructions and @code{set} | |
1856 | @cindex @code{if_then_else} usage | |
1857 | If @var{lval} is @code{(pc)}, we have a jump instruction, and the | |
1858 | possibilities for @var{x} are very limited. It may be a | |
1859 | @code{label_ref} expression (unconditional jump). It may be an | |
1860 | @code{if_then_else} (conditional jump), in which case either the | |
1861 | second or the third operand must be @code{(pc)} (for the case which | |
1862 | does not jump) and the other of the two must be a @code{label_ref} | |
1863 | (for the case which does jump). @var{x} may also be a @code{mem} or | |
1864 | @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a | |
1865 | @code{mem}; these unusual patterns are used to represent jumps through | |
1866 | branch tables.@refill | |
1867 | ||
1868 | If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of | |
1869 | @var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be | |
1870 | valid for the mode of @var{lval}. | |
1871 | ||
1872 | @findex SET_DEST | |
1873 | @findex SET_SRC | |
1874 | @var{lval} is customarily accessed with the @code{SET_DEST} macro and | |
1875 | @var{x} with the @code{SET_SRC} macro. | |
1876 | ||
1877 | @findex return | |
1878 | @item (return) | |
1879 | As the sole expression in a pattern, represents a return from the | |
1880 | current function, on machines where this can be done with one | |
1881 | instruction, such as Vaxes. On machines where a multi-instruction | |
1882 | ``epilogue'' must be executed in order to return from the function, | |
1883 | returning is done by jumping to a label which precedes the epilogue, and | |
1884 | the @code{return} expression code is never used. | |
1885 | ||
1886 | Inside an @code{if_then_else} expression, represents the value to be | |
1887 | placed in @code{pc} to return to the caller. | |
1888 | ||
1889 | Note that an insn pattern of @code{(return)} is logically equivalent to | |
1890 | @code{(set (pc) (return))}, but the latter form is never used. | |
1891 | ||
1892 | @findex call | |
1893 | @item (call @var{function} @var{nargs}) | |
1894 | Represents a function call. @var{function} is a @code{mem} expression | |
1895 | whose address is the address of the function to be called. | |
1896 | @var{nargs} is an expression which can be used for two purposes: on | |
1897 | some machines it represents the number of bytes of stack argument; on | |
1898 | others, it represents the number of argument registers. | |
1899 | ||
1900 | Each machine has a standard machine mode which @var{function} must | |
1901 | have. The machine description defines macro @code{FUNCTION_MODE} to | |
1902 | expand into the requisite mode name. The purpose of this mode is to | |
1903 | specify what kind of addressing is allowed, on machines where the | |
1904 | allowed kinds of addressing depend on the machine mode being | |
1905 | addressed. | |
1906 | ||
1907 | @findex clobber | |
1908 | @item (clobber @var{x}) | |
1909 | Represents the storing or possible storing of an unpredictable, | |
1910 | undescribed value into @var{x}, which must be a @code{reg}, | |
1911 | @code{scratch} or @code{mem} expression. | |
1912 | ||
1913 | One place this is used is in string instructions that store standard | |
1914 | values into particular hard registers. It may not be worth the | |
1915 | trouble to describe the values that are stored, but it is essential to | |
1916 | inform the compiler that the registers will be altered, lest it | |
1917 | attempt to keep data in them across the string instruction. | |
1918 | ||
1919 | If @var{x} is @code{(mem:BLK (const_int 0))}, it means that all memory | |
1920 | locations must be presumed clobbered. | |
1921 | ||
1922 | Note that the machine description classifies certain hard registers as | |
1923 | ``call-clobbered''. All function call instructions are assumed by | |
1924 | default to clobber these registers, so there is no need to use | |
1925 | @code{clobber} expressions to indicate this fact. Also, each function | |
1926 | call is assumed to have the potential to alter any memory location, | |
1927 | unless the function is declared @code{const}. | |
1928 | ||
1929 | If the last group of expressions in a @code{parallel} are each a | |
1930 | @code{clobber} expression whose arguments are @code{reg} or | |
1931 | @code{match_scratch} (@pxref{RTL Template}) expressions, the combiner | |
1932 | phase can add the appropriate @code{clobber} expressions to an insn it | |
1933 | has constructed when doing so will cause a pattern to be matched. | |
1934 | ||
1935 | This feature can be used, for example, on a machine that whose multiply | |
1936 | and add instructions don't use an MQ register but which has an | |
1937 | add-accumulate instruction that does clobber the MQ register. Similarly, | |
1938 | a combined instruction might require a temporary register while the | |
1939 | constituent instructions might not. | |
1940 | ||
1941 | When a @code{clobber} expression for a register appears inside a | |
1942 | @code{parallel} with other side effects, the register allocator | |
1943 | guarantees that the register is unoccupied both before and after that | |
1944 | insn. However, the reload phase may allocate a register used for one of | |
1945 | the inputs unless the @samp{&} constraint is specified for the selected | |
1946 | alternative (@pxref{Modifiers}). You can clobber either a specific hard | |
1947 | register, a pseudo register, or a @code{scratch} expression; in the | |
1948 | latter two cases, GNU CC will allocate a hard register that is available | |
1949 | there for use as a temporary. | |
1950 | ||
1951 | For instructions that require a temporary register, you should use | |
1952 | @code{scratch} instead of a pseudo-register because this will allow the | |
1953 | combiner phase to add the @code{clobber} when required. You do this by | |
1954 | coding (@code{clobber} (@code{match_scratch} @dots{})). If you do | |
1955 | clobber a pseudo register, use one which appears nowhere else---generate | |
1956 | a new one each time. Otherwise, you may confuse CSE. | |
1957 | ||
1958 | There is one other known use for clobbering a pseudo register in a | |
1959 | @code{parallel}: when one of the input operands of the insn is also | |
1960 | clobbered by the insn. In this case, using the same pseudo register in | |
1961 | the clobber and elsewhere in the insn produces the expected results. | |
1962 | ||
1963 | @findex use | |
1964 | @item (use @var{x}) | |
1965 | Represents the use of the value of @var{x}. It indicates that the | |
1966 | value in @var{x} at this point in the program is needed, even though | |
1967 | it may not be apparent why this is so. Therefore, the compiler will | |
1968 | not attempt to delete previous instructions whose only effect is to | |
1969 | store a value in @var{x}. @var{x} must be a @code{reg} expression. | |
1970 | ||
b60a8416 R |
1971 | During the reload phase, an insn that has a @code{use} as pattern |
1972 | can carry a reg_equal note. These @code{use} insns will be deleted | |
1973 | before the reload phase exits. | |
1974 | ||
89045fd1 JL |
1975 | During the delayed branch scheduling phase, @var{x} may be an insn. |
1976 | This indicates that @var{x} previously was located at this place in the | |
1977 | code and its data dependencies need to be taken into account. These | |
1978 | @code{use} insns will be deleted before the delayed branch scheduling | |
1979 | phase exits. | |
1980 | ||
1981 | @findex parallel | |
1982 | @item (parallel [@var{x0} @var{x1} @dots{}]) | |
1983 | Represents several side effects performed in parallel. The square | |
1984 | brackets stand for a vector; the operand of @code{parallel} is a | |
1985 | vector of expressions. @var{x0}, @var{x1} and so on are individual | |
1986 | side effect expressions---expressions of code @code{set}, @code{call}, | |
1987 | @code{return}, @code{clobber} or @code{use}.@refill | |
1988 | ||
1989 | ``In parallel'' means that first all the values used in the individual | |
1990 | side-effects are computed, and second all the actual side-effects are | |
1991 | performed. For example, | |
1992 | ||
1993 | @example | |
1994 | (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1))) | |
1995 | (set (mem:SI (reg:SI 1)) (reg:SI 1))]) | |
1996 | @end example | |
1997 | ||
1998 | @noindent | |
1999 | says unambiguously that the values of hard register 1 and the memory | |
2000 | location addressed by it are interchanged. In both places where | |
2001 | @code{(reg:SI 1)} appears as a memory address it refers to the value | |
2002 | in register 1 @emph{before} the execution of the insn. | |
2003 | ||
2004 | It follows that it is @emph{incorrect} to use @code{parallel} and | |
2005 | expect the result of one @code{set} to be available for the next one. | |
2006 | For example, people sometimes attempt to represent a jump-if-zero | |
2007 | instruction this way: | |
2008 | ||
2009 | @example | |
2010 | (parallel [(set (cc0) (reg:SI 34)) | |
2011 | (set (pc) (if_then_else | |
2012 | (eq (cc0) (const_int 0)) | |
2013 | (label_ref @dots{}) | |
2014 | (pc)))]) | |
2015 | @end example | |
2016 | ||
2017 | @noindent | |
2018 | But this is incorrect, because it says that the jump condition depends | |
2019 | on the condition code value @emph{before} this instruction, not on the | |
2020 | new value that is set by this instruction. | |
2021 | ||
2022 | @cindex peephole optimization, RTL representation | |
2023 | Peephole optimization, which takes place together with final assembly | |
2024 | code output, can produce insns whose patterns consist of a @code{parallel} | |
2025 | whose elements are the operands needed to output the resulting | |
2026 | assembler code---often @code{reg}, @code{mem} or constant expressions. | |
2027 | This would not be well-formed RTL at any other stage in compilation, | |
2028 | but it is ok then because no further optimization remains to be done. | |
2029 | However, the definition of the macro @code{NOTICE_UPDATE_CC}, if | |
2030 | any, must deal with such insns if you define any peephole optimizations. | |
2031 | ||
2032 | @findex sequence | |
2033 | @item (sequence [@var{insns} @dots{}]) | |
2034 | Represents a sequence of insns. Each of the @var{insns} that appears | |
2035 | in the vector is suitable for appearing in the chain of insns, so it | |
2036 | must be an @code{insn}, @code{jump_insn}, @code{call_insn}, | |
2037 | @code{code_label}, @code{barrier} or @code{note}. | |
2038 | ||
2039 | A @code{sequence} RTX is never placed in an actual insn during RTL | |
2040 | generation. It represents the sequence of insns that result from a | |
2041 | @code{define_expand} @emph{before} those insns are passed to | |
2042 | @code{emit_insn} to insert them in the chain of insns. When actually | |
2043 | inserted, the individual sub-insns are separated out and the | |
2044 | @code{sequence} is forgotten. | |
2045 | ||
2046 | After delay-slot scheduling is completed, an insn and all the insns that | |
2047 | reside in its delay slots are grouped together into a @code{sequence}. | |
2048 | The insn requiring the delay slot is the first insn in the vector; | |
2049 | subsequent insns are to be placed in the delay slot. | |
2050 | ||
2051 | @code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to | |
2052 | indicate that a branch insn should be used that will conditionally annul | |
2053 | the effect of the insns in the delay slots. In such a case, | |
2054 | @code{INSN_FROM_TARGET_P} indicates that the insn is from the target of | |
2055 | the branch and should be executed only if the branch is taken; otherwise | |
2056 | the insn should be executed only if the branch is not taken. | |
2057 | @xref{Delay Slots}. | |
2058 | @end table | |
2059 | ||
2060 | These expression codes appear in place of a side effect, as the body of | |
2061 | an insn, though strictly speaking they do not always describe side | |
2062 | effects as such: | |
2063 | ||
2064 | @table @code | |
2065 | @findex asm_input | |
2066 | @item (asm_input @var{s}) | |
2067 | Represents literal assembler code as described by the string @var{s}. | |
2068 | ||
2069 | @findex unspec | |
2070 | @findex unspec_volatile | |
2071 | @item (unspec [@var{operands} @dots{}] @var{index}) | |
2072 | @itemx (unspec_volatile [@var{operands} @dots{}] @var{index}) | |
2073 | Represents a machine-specific operation on @var{operands}. @var{index} | |
2074 | selects between multiple machine-specific operations. | |
2075 | @code{unspec_volatile} is used for volatile operations and operations | |
2076 | that may trap; @code{unspec} is used for other operations. | |
2077 | ||
2078 | These codes may appear inside a @code{pattern} of an | |
2079 | insn, inside a @code{parallel}, or inside an expression. | |
2080 | ||
2081 | @findex addr_vec | |
2082 | @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}]) | |
2083 | Represents a table of jump addresses. The vector elements @var{lr0}, | |
2084 | etc., are @code{label_ref} expressions. The mode @var{m} specifies | |
2085 | how much space is given to each address; normally @var{m} would be | |
2086 | @code{Pmode}. | |
2087 | ||
2088 | @findex addr_diff_vec | |
33f7f353 | 2089 | @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags}) |
89045fd1 JL |
2090 | Represents a table of jump addresses expressed as offsets from |
2091 | @var{base}. The vector elements @var{lr0}, etc., are @code{label_ref} | |
2092 | expressions and so is @var{base}. The mode @var{m} specifies how much | |
33f7f353 JR |
2093 | space is given to each address-difference. @var{min} and @var{max} |
2094 | are set up by branch shortening and hold a label with a minimum and a | |
2095 | maximum address, respectively. @var{flags} indicates the relative | |
2096 | position of @var{base}, @var{min} and @var{max} to the cointaining insn | |
2097 | and of @var{min} and @var{max} to @var{base}. See rtl.def for details.@refill | |
89045fd1 JL |
2098 | @end table |
2099 | ||
4404ce28 | 2100 | @node Incdec |
89045fd1 JL |
2101 | @section Embedded Side-Effects on Addresses |
2102 | @cindex RTL preincrement | |
2103 | @cindex RTL postincrement | |
2104 | @cindex RTL predecrement | |
2105 | @cindex RTL postdecrement | |
2106 | ||
b18cfc28 | 2107 | Six special side-effect expression codes appear as memory addresses. |
89045fd1 JL |
2108 | |
2109 | @table @code | |
2110 | @findex pre_dec | |
2111 | @item (pre_dec:@var{m} @var{x}) | |
2112 | Represents the side effect of decrementing @var{x} by a standard | |
2113 | amount and represents also the value that @var{x} has after being | |
2114 | decremented. @var{x} must be a @code{reg} or @code{mem}, but most | |
2115 | machines allow only a @code{reg}. @var{m} must be the machine mode | |
2116 | for pointers on the machine in use. The amount @var{x} is decremented | |
2117 | by is the length in bytes of the machine mode of the containing memory | |
2118 | reference of which this expression serves as the address. Here is an | |
2119 | example of its use:@refill | |
2120 | ||
2121 | @example | |
2122 | (mem:DF (pre_dec:SI (reg:SI 39))) | |
2123 | @end example | |
2124 | ||
2125 | @noindent | |
2126 | This says to decrement pseudo register 39 by the length of a @code{DFmode} | |
2127 | value and use the result to address a @code{DFmode} value. | |
2128 | ||
2129 | @findex pre_inc | |
2130 | @item (pre_inc:@var{m} @var{x}) | |
2131 | Similar, but specifies incrementing @var{x} instead of decrementing it. | |
2132 | ||
2133 | @findex post_dec | |
2134 | @item (post_dec:@var{m} @var{x}) | |
2135 | Represents the same side effect as @code{pre_dec} but a different | |
2136 | value. The value represented here is the value @var{x} has @i{before} | |
2137 | being decremented. | |
2138 | ||
2139 | @findex post_inc | |
2140 | @item (post_inc:@var{m} @var{x}) | |
2141 | Similar, but specifies incrementing @var{x} instead of decrementing it. | |
b18cfc28 MH |
2142 | |
2143 | @findex post_modify | |
2144 | @item (post_modify:@var{m} @var{x} @var{y}) | |
2145 | ||
2146 | Represents the side effect of setting @var{x} to @var{y} and | |
2147 | represents @var{x} before @var{x} is modified. @var{x} must be a | |
2148 | @code{reg} or @code{mem}, but most machines allow only a @code{reg}. | |
2149 | @var{m} must be the machine mode for pointers on the machine in use. | |
2150 | The amount @var{x} is decremented by is the length in bytes of the | |
2151 | machine mode of the containing memory reference of which this expression | |
2152 | serves as the address. Note that this is not currently implemented. | |
2153 | ||
2154 | The expression @var{y} must be one of three forms: | |
2155 | @table @code | |
2156 | @code{(plus:@var{m} @var{x} @var{z})}, | |
2157 | @code{(minus:@var{m} @var{x} @var{z})}, or | |
2158 | @code{(plus:@var{m} @var{x} @var{i})}, | |
2159 | @end table | |
2160 | where @var{z} is an index register and @var{i} is a constant. | |
2161 | ||
2162 | Here is an example of its use:@refill | |
2163 | ||
2164 | @example | |
2165 | (mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42) (reg:SI 48)))) | |
2166 | @end example | |
2167 | ||
2168 | This says to modify pseudo register 42 by adding the contents of pseudo | |
2169 | register 48 to it, after the use of what ever 42 points to. | |
2170 | ||
2171 | @findex post_modify | |
2172 | @item (pre_modify:@var{m} @var{x} @var{expr}) | |
2173 | Similar except side effects happen before the use. | |
89045fd1 JL |
2174 | @end table |
2175 | ||
2176 | These embedded side effect expressions must be used with care. Instruction | |
2177 | patterns may not use them. Until the @samp{flow} pass of the compiler, | |
2178 | they may occur only to represent pushes onto the stack. The @samp{flow} | |
2179 | pass finds cases where registers are incremented or decremented in one | |
2180 | instruction and used as an address shortly before or after; these cases are | |
2181 | then transformed to use pre- or post-increment or -decrement. | |
2182 | ||
2183 | If a register used as the operand of these expressions is used in | |
2184 | another address in an insn, the original value of the register is used. | |
2185 | Uses of the register outside of an address are not permitted within the | |
2186 | same insn as a use in an embedded side effect expression because such | |
2187 | insns behave differently on different machines and hence must be treated | |
2188 | as ambiguous and disallowed. | |
2189 | ||
2190 | An instruction that can be represented with an embedded side effect | |
2191 | could also be represented using @code{parallel} containing an additional | |
2192 | @code{set} to describe how the address register is altered. This is not | |
2193 | done because machines that allow these operations at all typically | |
2194 | allow them wherever a memory address is called for. Describing them as | |
2195 | additional parallel stores would require doubling the number of entries | |
2196 | in the machine description. | |
2197 | ||
4404ce28 | 2198 | @node Assembler |
89045fd1 JL |
2199 | @section Assembler Instructions as Expressions |
2200 | @cindex assembler instructions in RTL | |
2201 | ||
2202 | @cindex @code{asm_operands}, usage | |
2203 | The RTX code @code{asm_operands} represents a value produced by a | |
2204 | user-specified assembler instruction. It is used to represent | |
2205 | an @code{asm} statement with arguments. An @code{asm} statement with | |
2206 | a single output operand, like this: | |
2207 | ||
2208 | @smallexample | |
2209 | asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z)); | |
2210 | @end smallexample | |
2211 | ||
2212 | @noindent | |
2213 | is represented using a single @code{asm_operands} RTX which represents | |
2214 | the value that is stored in @code{outputvar}: | |
2215 | ||
2216 | @smallexample | |
2217 | (set @var{rtx-for-outputvar} | |
2218 | (asm_operands "foo %1,%2,%0" "a" 0 | |
2219 | [@var{rtx-for-addition-result} @var{rtx-for-*z}] | |
2220 | [(asm_input:@var{m1} "g") | |
2221 | (asm_input:@var{m2} "di")])) | |
2222 | @end smallexample | |
2223 | ||
2224 | @noindent | |
2225 | Here the operands of the @code{asm_operands} RTX are the assembler | |
2226 | template string, the output-operand's constraint, the index-number of the | |
2227 | output operand among the output operands specified, a vector of input | |
2228 | operand RTX's, and a vector of input-operand modes and constraints. The | |
2229 | mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of | |
2230 | @code{*z}. | |
2231 | ||
2232 | When an @code{asm} statement has multiple output values, its insn has | |
2233 | several such @code{set} RTX's inside of a @code{parallel}. Each @code{set} | |
2234 | contains a @code{asm_operands}; all of these share the same assembler | |
2235 | template and vectors, but each contains the constraint for the respective | |
2236 | output operand. They are also distinguished by the output-operand index | |
2237 | number, which is 0, 1, @dots{} for successive output operands. | |
2238 | ||
4404ce28 | 2239 | @node Insns |
89045fd1 JL |
2240 | @section Insns |
2241 | @cindex insns | |
2242 | ||
2243 | The RTL representation of the code for a function is a doubly-linked | |
2244 | chain of objects called @dfn{insns}. Insns are expressions with | |
2245 | special codes that are used for no other purpose. Some insns are | |
2246 | actual instructions; others represent dispatch tables for @code{switch} | |
2247 | statements; others represent labels to jump to or various sorts of | |
2248 | declarative information. | |
2249 | ||
2250 | In addition to its own specific data, each insn must have a unique | |
2251 | id-number that distinguishes it from all other insns in the current | |
2252 | function (after delayed branch scheduling, copies of an insn with the | |
2253 | same id-number may be present in multiple places in a function, but | |
2254 | these copies will always be identical and will only appear inside a | |
2255 | @code{sequence}), and chain pointers to the preceding and following | |
2256 | insns. These three fields occupy the same position in every insn, | |
2257 | independent of the expression code of the insn. They could be accessed | |
2258 | with @code{XEXP} and @code{XINT}, but instead three special macros are | |
2259 | always used: | |
2260 | ||
2261 | @table @code | |
2262 | @findex INSN_UID | |
2263 | @item INSN_UID (@var{i}) | |
2264 | Accesses the unique id of insn @var{i}. | |
2265 | ||
2266 | @findex PREV_INSN | |
2267 | @item PREV_INSN (@var{i}) | |
2268 | Accesses the chain pointer to the insn preceding @var{i}. | |
2269 | If @var{i} is the first insn, this is a null pointer. | |
2270 | ||
2271 | @findex NEXT_INSN | |
2272 | @item NEXT_INSN (@var{i}) | |
2273 | Accesses the chain pointer to the insn following @var{i}. | |
2274 | If @var{i} is the last insn, this is a null pointer. | |
2275 | @end table | |
2276 | ||
2277 | @findex get_insns | |
2278 | @findex get_last_insn | |
2279 | The first insn in the chain is obtained by calling @code{get_insns}; the | |
2280 | last insn is the result of calling @code{get_last_insn}. Within the | |
2281 | chain delimited by these insns, the @code{NEXT_INSN} and | |
2282 | @code{PREV_INSN} pointers must always correspond: if @var{insn} is not | |
2283 | the first insn, | |
2284 | ||
2285 | @example | |
2286 | NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn} | |
2287 | @end example | |
2288 | ||
2289 | @noindent | |
2290 | is always true and if @var{insn} is not the last insn, | |
2291 | ||
2292 | @example | |
2293 | PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn} | |
2294 | @end example | |
2295 | ||
2296 | @noindent | |
2297 | is always true. | |
2298 | ||
2299 | After delay slot scheduling, some of the insns in the chain might be | |
2300 | @code{sequence} expressions, which contain a vector of insns. The value | |
2301 | of @code{NEXT_INSN} in all but the last of these insns is the next insn | |
2302 | in the vector; the value of @code{NEXT_INSN} of the last insn in the vector | |
2303 | is the same as the value of @code{NEXT_INSN} for the @code{sequence} in | |
2304 | which it is contained. Similar rules apply for @code{PREV_INSN}. | |
2305 | ||
2306 | This means that the above invariants are not necessarily true for insns | |
2307 | inside @code{sequence} expressions. Specifically, if @var{insn} is the | |
2308 | first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))} | |
2309 | is the insn containing the @code{sequence} expression, as is the value | |
2310 | of @code{PREV_INSN (NEXT_INSN (@var{insn}))} is @var{insn} is the last | |
2311 | insn in the @code{sequence} expression. You can use these expressions | |
2312 | to find the containing @code{sequence} expression.@refill | |
2313 | ||
2314 | Every insn has one of the following six expression codes: | |
2315 | ||
2316 | @table @code | |
2317 | @findex insn | |
2318 | @item insn | |
2319 | The expression code @code{insn} is used for instructions that do not jump | |
2320 | and do not do function calls. @code{sequence} expressions are always | |
2321 | contained in insns with code @code{insn} even if one of those insns | |
2322 | should jump or do function calls. | |
2323 | ||
2324 | Insns with code @code{insn} have four additional fields beyond the three | |
2325 | mandatory ones listed above. These four are described in a table below. | |
2326 | ||
2327 | @findex jump_insn | |
2328 | @item jump_insn | |
2329 | The expression code @code{jump_insn} is used for instructions that may | |
2330 | jump (or, more generally, may contain @code{label_ref} expressions). If | |
2331 | there is an instruction to return from the current function, it is | |
2332 | recorded as a @code{jump_insn}. | |
2333 | ||
2334 | @findex JUMP_LABEL | |
2335 | @code{jump_insn} insns have the same extra fields as @code{insn} insns, | |
2336 | accessed in the same way and in addition contain a field | |
2337 | @code{JUMP_LABEL} which is defined once jump optimization has completed. | |
2338 | ||
2339 | For simple conditional and unconditional jumps, this field contains the | |
2340 | @code{code_label} to which this insn will (possibly conditionally) | |
2341 | branch. In a more complex jump, @code{JUMP_LABEL} records one of the | |
2342 | labels that the insn refers to; the only way to find the others | |
2343 | is to scan the entire body of the insn. | |
2344 | ||
2345 | Return insns count as jumps, but since they do not refer to any labels, | |
2346 | they have zero in the @code{JUMP_LABEL} field. | |
2347 | ||
2348 | @findex call_insn | |
2349 | @item call_insn | |
2350 | The expression code @code{call_insn} is used for instructions that may do | |
2351 | function calls. It is important to distinguish these instructions because | |
2352 | they imply that certain registers and memory locations may be altered | |
2353 | unpredictably. | |
2354 | ||
2355 | @findex CALL_INSN_FUNCTION_USAGE | |
2356 | @code{call_insn} insns have the same extra fields as @code{insn} insns, | |
2357 | accessed in the same way and in addition contain a field | |
2358 | @code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of | |
2359 | @code{expr_list} expressions) containing @code{use} and @code{clobber} | |
2360 | expressions that denote hard registers used or clobbered by the called | |
2361 | function. A register specified in a @code{clobber} in this list is | |
2362 | modified @emph{after} the execution of the @code{call_insn}, while a | |
2363 | register in a @code{clobber} in the body of the @code{call_insn} is | |
2364 | clobbered before the insn completes execution. @code{clobber} | |
2365 | expressions in this list augment registers specified in | |
2366 | @code{CALL_USED_REGISTERS} (@pxref{Register Basics}). | |
2367 | ||
2368 | @findex code_label | |
2369 | @findex CODE_LABEL_NUMBER | |
2370 | @item code_label | |
2371 | A @code{code_label} insn represents a label that a jump insn can jump | |
2372 | to. It contains two special fields of data in addition to the three | |
2373 | standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label | |
2374 | number}, a number that identifies this label uniquely among all the | |
2375 | labels in the compilation (not just in the current function). | |
2376 | Ultimately, the label is represented in the assembler output as an | |
2377 | assembler label, usually of the form @samp{L@var{n}} where @var{n} is | |
2378 | the label number. | |
2379 | ||
2380 | When a @code{code_label} appears in an RTL expression, it normally | |
2381 | appears within a @code{label_ref} which represents the address of | |
2382 | the label, as a number. | |
2383 | ||
2384 | @findex LABEL_NUSES | |
2385 | The field @code{LABEL_NUSES} is only defined once the jump optimization | |
2386 | phase is completed and contains the number of times this label is | |
2387 | referenced in the current function. | |
2388 | ||
8cd0faaf CM |
2389 | @findex LABEL_ALTERNATE_NAME |
2390 | The field @code{LABEL_ALTERNATE_NAME} is used to associate a name with | |
2391 | a @code{code_label}. If this field is defined, the alternate name will | |
2392 | be emitted instead of an internally generated label name. | |
2393 | ||
89045fd1 JL |
2394 | @findex barrier |
2395 | @item barrier | |
2396 | Barriers are placed in the instruction stream when control cannot flow | |
2397 | past them. They are placed after unconditional jump instructions to | |
2398 | indicate that the jumps are unconditional and after calls to | |
2399 | @code{volatile} functions, which do not return (e.g., @code{exit}). | |
2400 | They contain no information beyond the three standard fields. | |
2401 | ||
2402 | @findex note | |
2403 | @findex NOTE_LINE_NUMBER | |
2404 | @findex NOTE_SOURCE_FILE | |
2405 | @item note | |
2406 | @code{note} insns are used to represent additional debugging and | |
2407 | declarative information. They contain two nonstandard fields, an | |
2408 | integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a | |
2409 | string accessed with @code{NOTE_SOURCE_FILE}. | |
2410 | ||
2411 | If @code{NOTE_LINE_NUMBER} is positive, the note represents the | |
2412 | position of a source line and @code{NOTE_SOURCE_FILE} is the source file name | |
2413 | that the line came from. These notes control generation of line | |
2414 | number data in the assembler output. | |
2415 | ||
2416 | Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a | |
2417 | code with one of the following values (and @code{NOTE_SOURCE_FILE} | |
2418 | must contain a null pointer): | |
2419 | ||
2420 | @table @code | |
2421 | @findex NOTE_INSN_DELETED | |
2422 | @item NOTE_INSN_DELETED | |
2423 | Such a note is completely ignorable. Some passes of the compiler | |
2424 | delete insns by altering them into notes of this kind. | |
2425 | ||
2426 | @findex NOTE_INSN_BLOCK_BEG | |
2427 | @findex NOTE_INSN_BLOCK_END | |
2428 | @item NOTE_INSN_BLOCK_BEG | |
2429 | @itemx NOTE_INSN_BLOCK_END | |
2430 | These types of notes indicate the position of the beginning and end | |
2431 | of a level of scoping of variable names. They control the output | |
2432 | of debugging information. | |
2433 | ||
2434 | @findex NOTE_INSN_EH_REGION_BEG | |
2435 | @findex NOTE_INSN_EH_REGION_END | |
2436 | @item NOTE_INSN_EH_REGION_BEG | |
2437 | @itemx NOTE_INSN_EH_REGION_END | |
2438 | These types of notes indicate the position of the beginning and end of a | |
2439 | level of scoping for exception handling. @code{NOTE_BLOCK_NUMBER} | |
2440 | identifies which @code{CODE_LABEL} is associated with the given region. | |
2441 | ||
2442 | @findex NOTE_INSN_LOOP_BEG | |
2443 | @findex NOTE_INSN_LOOP_END | |
2444 | @item NOTE_INSN_LOOP_BEG | |
2445 | @itemx NOTE_INSN_LOOP_END | |
2446 | These types of notes indicate the position of the beginning and end | |
2447 | of a @code{while} or @code{for} loop. They enable the loop optimizer | |
2448 | to find loops quickly. | |
2449 | ||
2450 | @findex NOTE_INSN_LOOP_CONT | |
2451 | @item NOTE_INSN_LOOP_CONT | |
2452 | Appears at the place in a loop that @code{continue} statements jump to. | |
2453 | ||
2454 | @findex NOTE_INSN_LOOP_VTOP | |
2455 | @item NOTE_INSN_LOOP_VTOP | |
2456 | This note indicates the place in a loop where the exit test begins for | |
2457 | those loops in which the exit test has been duplicated. This position | |
2458 | becomes another virtual start of the loop when considering loop | |
2459 | invariants. | |
2460 | ||
2461 | @findex NOTE_INSN_FUNCTION_END | |
2462 | @item NOTE_INSN_FUNCTION_END | |
2463 | Appears near the end of the function body, just before the label that | |
2464 | @code{return} statements jump to (on machine where a single instruction | |
2465 | does not suffice for returning). This note may be deleted by jump | |
2466 | optimization. | |
2467 | ||
2468 | @findex NOTE_INSN_SETJMP | |
2469 | @item NOTE_INSN_SETJMP | |
2470 | Appears following each call to @code{setjmp} or a related function. | |
2471 | @end table | |
2472 | ||
2473 | These codes are printed symbolically when they appear in debugging dumps. | |
2474 | @end table | |
2475 | ||
9953e375 | 2476 | @cindex @code{TImode}, in @code{insn} |
89045fd1 JL |
2477 | @cindex @code{HImode}, in @code{insn} |
2478 | @cindex @code{QImode}, in @code{insn} | |
2479 | The machine mode of an insn is normally @code{VOIDmode}, but some | |
7609e720 | 2480 | phases use the mode for various purposes. |
9953e375 RH |
2481 | |
2482 | The common subexpression elimination pass sets the mode of an insn to | |
2483 | @code{QImode} when it is the first insn in a block that has already | |
2484 | been processed. | |
2485 | ||
2486 | The second Haifa scheduling pass, for targets that can multiple issue, | |
2487 | sets the mode of an insn to @code{TImode} when it is believed that the | |
2488 | instruction begins an issue group. That is, when the instruction | |
2489 | cannot issue simultaneously with the previous. This may be relied on | |
2490 | by later passes, in particular machine-dependant reorg. | |
89045fd1 JL |
2491 | |
2492 | Here is a table of the extra fields of @code{insn}, @code{jump_insn} | |
2493 | and @code{call_insn} insns: | |
2494 | ||
2495 | @table @code | |
2496 | @findex PATTERN | |
2497 | @item PATTERN (@var{i}) | |
2498 | An expression for the side effect performed by this insn. This must be | |
2499 | one of the following codes: @code{set}, @code{call}, @code{use}, | |
2500 | @code{clobber}, @code{return}, @code{asm_input}, @code{asm_output}, | |
2501 | @code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec}, | |
2502 | @code{unspec_volatile}, @code{parallel}, or @code{sequence}. If it is a @code{parallel}, | |
2503 | each element of the @code{parallel} must be one these codes, except that | |
2504 | @code{parallel} expressions cannot be nested and @code{addr_vec} and | |
2505 | @code{addr_diff_vec} are not permitted inside a @code{parallel} expression. | |
2506 | ||
2507 | @findex INSN_CODE | |
2508 | @item INSN_CODE (@var{i}) | |
2509 | An integer that says which pattern in the machine description matches | |
2510 | this insn, or -1 if the matching has not yet been attempted. | |
2511 | ||
2512 | Such matching is never attempted and this field remains -1 on an insn | |
2513 | whose pattern consists of a single @code{use}, @code{clobber}, | |
2514 | @code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression. | |
2515 | ||
2516 | @findex asm_noperands | |
2517 | Matching is also never attempted on insns that result from an @code{asm} | |
2518 | statement. These contain at least one @code{asm_operands} expression. | |
2519 | The function @code{asm_noperands} returns a non-negative value for | |
2520 | such insns. | |
2521 | ||
2522 | In the debugging output, this field is printed as a number followed by | |
2523 | a symbolic representation that locates the pattern in the @file{md} | |
2524 | file as some small positive or negative offset from a named pattern. | |
2525 | ||
2526 | @findex LOG_LINKS | |
2527 | @item LOG_LINKS (@var{i}) | |
2528 | A list (chain of @code{insn_list} expressions) giving information about | |
2529 | dependencies between instructions within a basic block. Neither a jump | |
2530 | nor a label may come between the related insns. | |
2531 | ||
2532 | @findex REG_NOTES | |
2533 | @item REG_NOTES (@var{i}) | |
2534 | A list (chain of @code{expr_list} and @code{insn_list} expressions) | |
2535 | giving miscellaneous information about the insn. It is often | |
2536 | information pertaining to the registers used in this insn. | |
2537 | @end table | |
2538 | ||
2539 | The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list} | |
2540 | expressions. Each of these has two operands: the first is an insn, | |
2541 | and the second is another @code{insn_list} expression (the next one in | |
2542 | the chain). The last @code{insn_list} in the chain has a null pointer | |
2543 | as second operand. The significant thing about the chain is which | |
2544 | insns appear in it (as first operands of @code{insn_list} | |
2545 | expressions). Their order is not significant. | |
2546 | ||
2547 | This list is originally set up by the flow analysis pass; it is a null | |
2548 | pointer until then. Flow only adds links for those data dependencies | |
2549 | which can be used for instruction combination. For each insn, the flow | |
2550 | analysis pass adds a link to insns which store into registers values | |
2551 | that are used for the first time in this insn. The instruction | |
2552 | scheduling pass adds extra links so that every dependence will be | |
2553 | represented. Links represent data dependencies, antidependencies and | |
2554 | output dependencies; the machine mode of the link distinguishes these | |
2555 | three types: antidependencies have mode @code{REG_DEP_ANTI}, output | |
2556 | dependencies have mode @code{REG_DEP_OUTPUT}, and data dependencies have | |
2557 | mode @code{VOIDmode}. | |
2558 | ||
2559 | The @code{REG_NOTES} field of an insn is a chain similar to the | |
2560 | @code{LOG_LINKS} field but it includes @code{expr_list} expressions in | |
2561 | addition to @code{insn_list} expressions. There are several kinds of | |
2562 | register notes, which are distinguished by the machine mode, which in a | |
2563 | register note is really understood as being an @code{enum reg_note}. | |
2564 | The first operand @var{op} of the note is data whose meaning depends on | |
2565 | the kind of note. | |
2566 | ||
2567 | @findex REG_NOTE_KIND | |
2568 | @findex PUT_REG_NOTE_KIND | |
2569 | The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of | |
2570 | register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND | |
2571 | (@var{x}, @var{newkind})} sets the register note type of @var{x} to be | |
2572 | @var{newkind}. | |
2573 | ||
2574 | Register notes are of three classes: They may say something about an | |
2575 | input to an insn, they may say something about an output of an insn, or | |
2576 | they may create a linkage between two insns. There are also a set | |
2577 | of values that are only used in @code{LOG_LINKS}. | |
2578 | ||
2579 | These register notes annotate inputs to an insn: | |
2580 | ||
2581 | @table @code | |
2582 | @findex REG_DEAD | |
2583 | @item REG_DEAD | |
2584 | The value in @var{op} dies in this insn; that is to say, altering the | |
2585 | value immediately after this insn would not affect the future behavior | |
2586 | of the program. | |
2587 | ||
2588 | This does not necessarily mean that the register @var{op} has no useful | |
2589 | value after this insn since it may also be an output of the insn. In | |
2590 | such a case, however, a @code{REG_DEAD} note would be redundant and is | |
2591 | usually not present until after the reload pass, but no code relies on | |
2592 | this fact. | |
2593 | ||
2594 | @findex REG_INC | |
2595 | @item REG_INC | |
2596 | The register @var{op} is incremented (or decremented; at this level | |
2597 | there is no distinction) by an embedded side effect inside this insn. | |
2598 | This means it appears in a @code{post_inc}, @code{pre_inc}, | |
2599 | @code{post_dec} or @code{pre_dec} expression. | |
2600 | ||
2601 | @findex REG_NONNEG | |
2602 | @item REG_NONNEG | |
2603 | The register @var{op} is known to have a nonnegative value when this | |
2604 | insn is reached. This is used so that decrement and branch until zero | |
2605 | instructions, such as the m68k dbra, can be matched. | |
2606 | ||
2607 | The @code{REG_NONNEG} note is added to insns only if the machine | |
2608 | description has a @samp{decrement_and_branch_until_zero} pattern. | |
2609 | ||
2610 | @findex REG_NO_CONFLICT | |
2611 | @item REG_NO_CONFLICT | |
2612 | This insn does not cause a conflict between @var{op} and the item | |
2613 | being set by this insn even though it might appear that it does. | |
2614 | In other words, if the destination register and @var{op} could | |
2615 | otherwise be assigned the same register, this insn does not | |
2616 | prevent that assignment. | |
2617 | ||
2618 | Insns with this note are usually part of a block that begins with a | |
2619 | @code{clobber} insn specifying a multi-word pseudo register (which will | |
2620 | be the output of the block), a group of insns that each set one word of | |
2621 | the value and have the @code{REG_NO_CONFLICT} note attached, and a final | |
2622 | insn that copies the output to itself with an attached @code{REG_EQUAL} | |
2623 | note giving the expression being computed. This block is encapsulated | |
2624 | with @code{REG_LIBCALL} and @code{REG_RETVAL} notes on the first and | |
2625 | last insns, respectively. | |
2626 | ||
2627 | @findex REG_LABEL | |
2628 | @item REG_LABEL | |
2629 | This insn uses @var{op}, a @code{code_label}, but is not a | |
2630 | @code{jump_insn}. The presence of this note allows jump optimization to | |
2631 | be aware that @var{op} is, in fact, being used. | |
2632 | @end table | |
2633 | ||
2634 | The following notes describe attributes of outputs of an insn: | |
2635 | ||
2636 | @table @code | |
2637 | @findex REG_EQUIV | |
2638 | @findex REG_EQUAL | |
2639 | @item REG_EQUIV | |
2640 | @itemx REG_EQUAL | |
2641 | This note is only valid on an insn that sets only one register and | |
2642 | indicates that that register will be equal to @var{op} at run time; the | |
2643 | scope of this equivalence differs between the two types of notes. The | |
2644 | value which the insn explicitly copies into the register may look | |
2645 | different from @var{op}, but they will be equal at run time. If the | |
2646 | output of the single @code{set} is a @code{strict_low_part} expression, | |
2647 | the note refers to the register that is contained in @code{SUBREG_REG} | |
2648 | of the @code{subreg} expression. | |
2649 | ||
2650 | For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout | |
2651 | the entire function, and could validly be replaced in all its | |
2652 | occurrences by @var{op}. (``Validly'' here refers to the data flow of | |
2653 | the program; simple replacement may make some insns invalid.) For | |
2654 | example, when a constant is loaded into a register that is never | |
2655 | assigned any other value, this kind of note is used. | |
2656 | ||
2657 | When a parameter is copied into a pseudo-register at entry to a function, | |
2658 | a note of this kind records that the register is equivalent to the stack | |
2659 | slot where the parameter was passed. Although in this case the register | |
2660 | may be set by other insns, it is still valid to replace the register | |
2661 | by the stack slot throughout the function. | |
2662 | ||
2663 | A @code{REG_EQUIV} note is also used on an instruction which copies a | |
2664 | register parameter into a pseudo-register at entry to a function, if | |
2665 | there is a stack slot where that parameter could be stored. Although | |
2666 | other insns may set the pseudo-register, it is valid for the compiler to | |
2667 | replace the pseudo-register by stack slot throughout the function, | |
2668 | provided the compiler ensures that the stack slot is properly | |
2669 | initialized by making the replacement in the initial copy instruction as | |
2670 | well. This is used on machines for which the calling convention | |
2671 | allocates stack space for register parameters. See | |
2672 | @code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}. | |
2673 | ||
2674 | In the case of @code{REG_EQUAL}, the register that is set by this insn | |
2675 | will be equal to @var{op} at run time at the end of this insn but not | |
2676 | necessarily elsewhere in the function. In this case, @var{op} | |
2677 | is typically an arithmetic expression. For example, when a sequence of | |
2678 | insns such as a library call is used to perform an arithmetic operation, | |
2679 | this kind of note is attached to the insn that produces or copies the | |
2680 | final value. | |
2681 | ||
2682 | These two notes are used in different ways by the compiler passes. | |
2683 | @code{REG_EQUAL} is used by passes prior to register allocation (such as | |
2684 | common subexpression elimination and loop optimization) to tell them how | |
2685 | to think of that value. @code{REG_EQUIV} notes are used by register | |
2686 | allocation to indicate that there is an available substitute expression | |
2687 | (either a constant or a @code{mem} expression for the location of a | |
2688 | parameter on the stack) that may be used in place of a register if | |
2689 | insufficient registers are available. | |
2690 | ||
2691 | Except for stack homes for parameters, which are indicated by a | |
2692 | @code{REG_EQUIV} note and are not useful to the early optimization | |
2693 | passes and pseudo registers that are equivalent to a memory location | |
2694 | throughout there entire life, which is not detected until later in | |
2695 | the compilation, all equivalences are initially indicated by an attached | |
2696 | @code{REG_EQUAL} note. In the early stages of register allocation, a | |
2697 | @code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if | |
2698 | @var{op} is a constant and the insn represents the only set of its | |
2699 | destination register. | |
2700 | ||
2701 | Thus, compiler passes prior to register allocation need only check for | |
2702 | @code{REG_EQUAL} notes and passes subsequent to register allocation | |
2703 | need only check for @code{REG_EQUIV} notes. | |
2704 | ||
2705 | @findex REG_UNUSED | |
2706 | @item REG_UNUSED | |
2707 | The register @var{op} being set by this insn will not be used in a | |
2708 | subsequent insn. This differs from a @code{REG_DEAD} note, which | |
2709 | indicates that the value in an input will not be used subsequently. | |
2710 | These two notes are independent; both may be present for the same | |
2711 | register. | |
2712 | ||
2713 | @findex REG_WAS_0 | |
2714 | @item REG_WAS_0 | |
2715 | The single output of this insn contained zero before this insn. | |
2716 | @var{op} is the insn that set it to zero. You can rely on this note if | |
2717 | it is present and @var{op} has not been deleted or turned into a @code{note}; | |
2718 | its absence implies nothing. | |
2719 | @end table | |
2720 | ||
2721 | These notes describe linkages between insns. They occur in pairs: one | |
2722 | insn has one of a pair of notes that points to a second insn, which has | |
2723 | the inverse note pointing back to the first insn. | |
2724 | ||
2725 | @table @code | |
2726 | @findex REG_RETVAL | |
2727 | @item REG_RETVAL | |
2728 | This insn copies the value of a multi-insn sequence (for example, a | |
2729 | library call), and @var{op} is the first insn of the sequence (for a | |
2730 | library call, the first insn that was generated to set up the arguments | |
2731 | for the library call). | |
2732 | ||
2733 | Loop optimization uses this note to treat such a sequence as a single | |
2734 | operation for code motion purposes and flow analysis uses this note to | |
2735 | delete such sequences whose results are dead. | |
2736 | ||
2737 | A @code{REG_EQUAL} note will also usually be attached to this insn to | |
2738 | provide the expression being computed by the sequence. | |
2739 | ||
80599fd9 NC |
2740 | These notes will be deleted after reload, since they are no longer |
2741 | accurate or useful. | |
2742 | ||
89045fd1 JL |
2743 | @findex REG_LIBCALL |
2744 | @item REG_LIBCALL | |
2745 | This is the inverse of @code{REG_RETVAL}: it is placed on the first | |
2746 | insn of a multi-insn sequence, and it points to the last one. | |
2747 | ||
80599fd9 NC |
2748 | These notes are deleted after reload, since they are no longer useful or |
2749 | accurate. | |
2750 | ||
89045fd1 JL |
2751 | @findex REG_CC_SETTER |
2752 | @findex REG_CC_USER | |
2753 | @item REG_CC_SETTER | |
2754 | @itemx REG_CC_USER | |
2755 | On machines that use @code{cc0}, the insns which set and use @code{cc0} | |
2756 | set and use @code{cc0} are adjacent. However, when branch delay slot | |
2757 | filling is done, this may no longer be true. In this case a | |
2758 | @code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to | |
2759 | point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will | |
2760 | be placed on the insn using @code{cc0} to point to the insn setting | |
2761 | @code{cc0}.@refill | |
2762 | @end table | |
2763 | ||
2764 | These values are only used in the @code{LOG_LINKS} field, and indicate | |
2765 | the type of dependency that each link represents. Links which indicate | |
2766 | a data dependence (a read after write dependence) do not use any code, | |
2767 | they simply have mode @code{VOIDmode}, and are printed without any | |
2768 | descriptive text. | |
2769 | ||
2770 | @table @code | |
2771 | @findex REG_DEP_ANTI | |
2772 | @item REG_DEP_ANTI | |
2773 | This indicates an anti dependence (a write after read dependence). | |
2774 | ||
2775 | @findex REG_DEP_OUTPUT | |
2776 | @item REG_DEP_OUTPUT | |
2777 | This indicates an output dependence (a write after write dependence). | |
2778 | @end table | |
2779 | ||
2780 | These notes describe information gathered from gcov profile data. They | |
2781 | are stored in the @code{REG_NOTES} field of an insn as an | |
2782 | @code{expr_list}. | |
2783 | ||
2784 | @table @code | |
2785 | @findex REG_EXEC_COUNT | |
2786 | @item REG_EXEC_COUNT | |
2787 | This is used to indicate the number of times a basic block was executed | |
2788 | according to the profile data. The note is attached to the first insn in | |
2789 | the basic block. | |
2790 | ||
2791 | @findex REG_BR_PROB | |
2792 | @item REG_BR_PROB | |
2793 | This is used to specify the ratio of branches to non-branches of a | |
2794 | branch insn according to the profile data. The value is stored as a | |
2795 | value between 0 and REG_BR_PROB_BASE; larger values indicate a higher | |
2796 | probability that the branch will be taken. | |
6714c1ae JL |
2797 | |
2798 | @findex REG_BR_PRED | |
2799 | @item REG_BR_PRED | |
2800 | These notes are found in JUMP insns after delayed branch scheduling | |
2801 | has taken place. They indicate both the direction and the likelyhood | |
2802 | of the JUMP. The format is a bitmask of ATTR_FLAG_* values. | |
07ebc930 RH |
2803 | |
2804 | @findex REG_FRAME_RELATED_EXPR | |
2805 | @item REG_FRAME_RELATED_EXPR | |
2806 | This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression | |
2807 | is used in place of the actual insn pattern. This is done in cases where | |
2808 | the pattern is either complex or misleading. | |
89045fd1 JL |
2809 | @end table |
2810 | ||
2811 | For convenience, the machine mode in an @code{insn_list} or | |
2812 | @code{expr_list} is printed using these symbolic codes in debugging dumps. | |
2813 | ||
2814 | @findex insn_list | |
2815 | @findex expr_list | |
2816 | The only difference between the expression codes @code{insn_list} and | |
2817 | @code{expr_list} is that the first operand of an @code{insn_list} is | |
2818 | assumed to be an insn and is printed in debugging dumps as the insn's | |
2819 | unique id; the first operand of an @code{expr_list} is printed in the | |
2820 | ordinary way as an expression. | |
2821 | ||
4404ce28 | 2822 | @node Calls |
89045fd1 JL |
2823 | @section RTL Representation of Function-Call Insns |
2824 | @cindex calling functions in RTL | |
2825 | @cindex RTL function-call insns | |
2826 | @cindex function-call insns | |
2827 | ||
2828 | Insns that call subroutines have the RTL expression code @code{call_insn}. | |
2829 | These insns must satisfy special rules, and their bodies must use a special | |
2830 | RTL expression code, @code{call}. | |
2831 | ||
2832 | @cindex @code{call} usage | |
2833 | A @code{call} expression has two operands, as follows: | |
2834 | ||
2835 | @example | |
2836 | (call (mem:@var{fm} @var{addr}) @var{nbytes}) | |
2837 | @end example | |
2838 | ||
2839 | @noindent | |
2840 | Here @var{nbytes} is an operand that represents the number of bytes of | |
2841 | argument data being passed to the subroutine, @var{fm} is a machine mode | |
2842 | (which must equal as the definition of the @code{FUNCTION_MODE} macro in | |
2843 | the machine description) and @var{addr} represents the address of the | |
2844 | subroutine. | |
2845 | ||
2846 | For a subroutine that returns no value, the @code{call} expression as | |
2847 | shown above is the entire body of the insn, except that the insn might | |
2848 | also contain @code{use} or @code{clobber} expressions. | |
2849 | ||
2850 | @cindex @code{BLKmode}, and function return values | |
2851 | For a subroutine that returns a value whose mode is not @code{BLKmode}, | |
2852 | the value is returned in a hard register. If this register's number is | |
2853 | @var{r}, then the body of the call insn looks like this: | |
2854 | ||
2855 | @example | |
2856 | (set (reg:@var{m} @var{r}) | |
2857 | (call (mem:@var{fm} @var{addr}) @var{nbytes})) | |
2858 | @end example | |
2859 | ||
2860 | @noindent | |
2861 | This RTL expression makes it clear (to the optimizer passes) that the | |
2862 | appropriate register receives a useful value in this insn. | |
2863 | ||
2864 | When a subroutine returns a @code{BLKmode} value, it is handled by | |
2865 | passing to the subroutine the address of a place to store the value. | |
2866 | So the call insn itself does not ``return'' any value, and it has the | |
2867 | same RTL form as a call that returns nothing. | |
2868 | ||
2869 | On some machines, the call instruction itself clobbers some register, | |
2870 | for example to contain the return address. @code{call_insn} insns | |
2871 | on these machines should have a body which is a @code{parallel} | |
2872 | that contains both the @code{call} expression and @code{clobber} | |
2873 | expressions that indicate which registers are destroyed. Similarly, | |
2874 | if the call instruction requires some register other than the stack | |
2875 | pointer that is not explicitly mentioned it its RTL, a @code{use} | |
2876 | subexpression should mention that register. | |
2877 | ||
2878 | Functions that are called are assumed to modify all registers listed in | |
2879 | the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register | |
2880 | Basics}) and, with the exception of @code{const} functions and library | |
2881 | calls, to modify all of memory. | |
2882 | ||
2883 | Insns containing just @code{use} expressions directly precede the | |
2884 | @code{call_insn} insn to indicate which registers contain inputs to the | |
2885 | function. Similarly, if registers other than those in | |
2886 | @code{CALL_USED_REGISTERS} are clobbered by the called function, insns | |
2887 | containing a single @code{clobber} follow immediately after the call to | |
2888 | indicate which registers. | |
2889 | ||
2890 | @node Sharing | |
2891 | @section Structure Sharing Assumptions | |
2892 | @cindex sharing of RTL components | |
2893 | @cindex RTL structure sharing assumptions | |
2894 | ||
2895 | The compiler assumes that certain kinds of RTL expressions are unique; | |
2896 | there do not exist two distinct objects representing the same value. | |
2897 | In other cases, it makes an opposite assumption: that no RTL expression | |
2898 | object of a certain kind appears in more than one place in the | |
2899 | containing structure. | |
2900 | ||
2901 | These assumptions refer to a single function; except for the RTL | |
2902 | objects that describe global variables and external functions, | |
2903 | and a few standard objects such as small integer constants, | |
2904 | no RTL objects are common to two functions. | |
2905 | ||
2906 | @itemize @bullet | |
2907 | @cindex @code{reg}, RTL sharing | |
2908 | @item | |
2909 | Each pseudo-register has only a single @code{reg} object to represent it, | |
2910 | and therefore only a single machine mode. | |
2911 | ||
2912 | @cindex symbolic label | |
2913 | @cindex @code{symbol_ref}, RTL sharing | |
2914 | @item | |
2915 | For any symbolic label, there is only one @code{symbol_ref} object | |
2916 | referring to it. | |
2917 | ||
2918 | @cindex @code{const_int}, RTL sharing | |
2919 | @item | |
2920 | There is only one @code{const_int} expression with value 0, only | |
2921 | one with value 1, and only one with value @minus{}1. | |
2922 | Some other integer values are also stored uniquely. | |
2923 | ||
2924 | @cindex @code{pc}, RTL sharing | |
2925 | @item | |
2926 | There is only one @code{pc} expression. | |
2927 | ||
2928 | @cindex @code{cc0}, RTL sharing | |
2929 | @item | |
2930 | There is only one @code{cc0} expression. | |
2931 | ||
2932 | @cindex @code{const_double}, RTL sharing | |
2933 | @item | |
2934 | There is only one @code{const_double} expression with value 0 for | |
2935 | each floating point mode. Likewise for values 1 and 2. | |
2936 | ||
2937 | @cindex @code{label_ref}, RTL sharing | |
2938 | @cindex @code{scratch}, RTL sharing | |
2939 | @item | |
2940 | No @code{label_ref} or @code{scratch} appears in more than one place in | |
2941 | the RTL structure; in other words, it is safe to do a tree-walk of all | |
2942 | the insns in the function and assume that each time a @code{label_ref} | |
2943 | or @code{scratch} is seen it is distinct from all others that are seen. | |
2944 | ||
2945 | @cindex @code{mem}, RTL sharing | |
2946 | @item | |
2947 | Only one @code{mem} object is normally created for each static | |
2948 | variable or stack slot, so these objects are frequently shared in all | |
2949 | the places they appear. However, separate but equal objects for these | |
2950 | variables are occasionally made. | |
2951 | ||
2952 | @cindex @code{asm_operands}, RTL sharing | |
2953 | @item | |
2954 | When a single @code{asm} statement has multiple output operands, a | |
2955 | distinct @code{asm_operands} expression is made for each output operand. | |
2956 | However, these all share the vector which contains the sequence of input | |
2957 | operands. This sharing is used later on to test whether two | |
2958 | @code{asm_operands} expressions come from the same statement, so all | |
2959 | optimizations must carefully preserve the sharing if they copy the | |
2960 | vector at all. | |
2961 | ||
2962 | @item | |
2963 | No RTL object appears in more than one place in the RTL structure | |
2964 | except as described above. Many passes of the compiler rely on this | |
2965 | by assuming that they can modify RTL objects in place without unwanted | |
2966 | side-effects on other insns. | |
2967 | ||
2968 | @findex unshare_all_rtl | |
2969 | @item | |
2970 | During initial RTL generation, shared structure is freely introduced. | |
2971 | After all the RTL for a function has been generated, all shared | |
2972 | structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c}, | |
2973 | after which the above rules are guaranteed to be followed. | |
2974 | ||
2975 | @findex copy_rtx_if_shared | |
2976 | @item | |
2977 | During the combiner pass, shared structure within an insn can exist | |
2978 | temporarily. However, the shared structure is copied before the | |
2979 | combiner is finished with the insn. This is done by calling | |
2980 | @code{copy_rtx_if_shared}, which is a subroutine of | |
2981 | @code{unshare_all_rtl}. | |
2982 | @end itemize | |
2983 | ||
2984 | @node Reading RTL | |
2985 | @section Reading RTL | |
2986 | ||
2987 | To read an RTL object from a file, call @code{read_rtx}. It takes one | |
2988 | argument, a stdio stream, and returns a single RTL object. | |
2989 | ||
2990 | Reading RTL from a file is very slow. This is not currently a | |
2991 | problem since reading RTL occurs only as part of building the | |
2992 | compiler. | |
2993 | ||
2994 | People frequently have the idea of using RTL stored as text in a file as | |
2995 | an interface between a language front end and the bulk of GNU CC. This | |
2996 | idea is not feasible. | |
2997 | ||
2998 | GNU CC was designed to use RTL internally only. Correct RTL for a given | |
2999 | program is very dependent on the particular target machine. And the RTL | |
3000 | does not contain all the information about the program. | |
3001 | ||
3002 | The proper way to interface GNU CC to a new language front end is with | |
3003 | the ``tree'' data structure. There is no manual for this data | |
3004 | structure, but it is described in the files @file{tree.h} and | |
3005 | @file{tree.def}. |