]>
Commit | Line | Data |
---|---|---|
7adcbafe | 1 | @c Copyright (C) 2004-2022 Free Software Foundation, Inc. |
e6c99067 DN |
2 | @c This is part of the GCC manual. |
3 | @c For copying conditions, see the file gcc.texi. | |
4 | ||
5 | @c --------------------------------------------------------------------- | |
6 | @c GENERIC | |
7 | @c --------------------------------------------------------------------- | |
8 | ||
9 | @node GENERIC | |
10 | @chapter GENERIC | |
11 | @cindex GENERIC | |
12 | ||
13 | The purpose of GENERIC is simply to provide a | |
14 | language-independent way of representing an entire function in | |
15 | trees. To this end, it was necessary to add a few new tree codes | |
57fc74a4 | 16 | to the back end, but almost everything was already there. If you |
e6c99067 DN |
17 | can express it with the codes in @code{gcc/tree.def}, it's |
18 | GENERIC@. | |
19 | ||
20 | Early on, there was a great deal of debate about how to think | |
21 | about statements in a tree IL@. In GENERIC, a statement is | |
22 | defined as any expression whose value, if any, is ignored. A | |
23 | statement will always have @code{TREE_SIDE_EFFECTS} set (or it | |
24 | will be discarded), but a non-statement expression may also have | |
25 | side effects. A @code{CALL_EXPR}, for instance. | |
26 | ||
27 | It would be possible for some local optimizations to work on the | |
28 | GENERIC form of a function; indeed, the adapted tree inliner | |
29 | works fine on GENERIC, but the current compiler performs inlining | |
30 | after lowering to GIMPLE (a restricted form described in the next | |
31 | section). Indeed, currently the frontends perform this lowering | |
32 | before handing off to @code{tree_rest_of_compilation}, but this | |
33 | seems inelegant. | |
34 | ||
929769f4 | 35 | @menu |
1cb5e50f | 36 | * Deficiencies:: Topics not yet covered in this document. |
929769f4 JQ |
37 | * Tree overview:: All about @code{tree}s. |
38 | * Types:: Fundamental and aggregate types. | |
39 | * Declarations:: Type declarations and variables. | |
40 | * Attributes:: Declaration and type attributes. | |
41 | * Expressions: Expression trees. Operating on data. | |
42 | * Statements:: Control flow and related trees. | |
43 | * Functions:: Function bodies, linkage, and other aspects. | |
44 | * Language-dependent trees:: Topics and trees specific to language front ends. | |
45 | * C and C++ Trees:: Trees specific to C and C++. | |
929769f4 JQ |
46 | @end menu |
47 | ||
48 | @c --------------------------------------------------------------------- | |
49 | @c Deficiencies | |
50 | @c --------------------------------------------------------------------- | |
51 | ||
52 | @node Deficiencies | |
53 | @section Deficiencies | |
54 | ||
a3e3f116 | 55 | @c The spelling of "incomplet" and "incorrekt" below is intentional. |
929769f4 JQ |
56 | There are many places in which this document is incomplet and incorrekt. |
57 | It is, as of yet, only @emph{preliminary} documentation. | |
58 | ||
59 | @c --------------------------------------------------------------------- | |
60 | @c Overview | |
61 | @c --------------------------------------------------------------------- | |
62 | ||
63 | @node Tree overview | |
64 | @section Overview | |
65 | @cindex tree | |
66 | @findex TREE_CODE | |
67 | ||
68 | The central data structure used by the internal representation is the | |
69 | @code{tree}. These nodes, while all of the C type @code{tree}, are of | |
70 | many varieties. A @code{tree} is a pointer type, but the object to | |
71 | which it points may be of a variety of types. From this point forward, | |
72 | we will refer to trees in ordinary type, rather than in @code{this | |
73 | font}, except when talking about the actual C type @code{tree}. | |
74 | ||
75 | You can tell what kind of node a particular tree is by using the | |
76 | @code{TREE_CODE} macro. Many, many macros take trees as input and | |
77 | return trees as output. However, most macros require a certain kind of | |
78 | tree node as input. In other words, there is a type-system for trees, | |
79 | but it is not reflected in the C type-system. | |
80 | ||
81 | For safety, it is useful to configure GCC with @option{--enable-checking}. | |
82 | Although this results in a significant performance penalty (since all | |
83 | tree types are checked at run-time), and is therefore inappropriate in a | |
84 | release version, it is extremely helpful during the development process. | |
85 | ||
86 | Many macros behave as predicates. Many, although not all, of these | |
87 | predicates end in @samp{_P}. Do not rely on the result type of these | |
88 | macros being of any particular type. You may, however, rely on the fact | |
89 | that the type can be compared to @code{0}, so that statements like | |
90 | @smallexample | |
91 | if (TEST_P (t) && !TEST_P (y)) | |
92 | x = 1; | |
93 | @end smallexample | |
94 | @noindent | |
95 | and | |
96 | @smallexample | |
97 | int i = (TEST_P (t) != 0); | |
98 | @end smallexample | |
99 | @noindent | |
100 | are legal. Macros that return @code{int} values now may be changed to | |
101 | return @code{tree} values, or other pointers in the future. Even those | |
102 | that continue to return @code{int} may return multiple nonzero codes | |
103 | where previously they returned only zero and one. Therefore, you should | |
104 | not write code like | |
105 | @smallexample | |
106 | if (TEST_P (t) == 1) | |
107 | @end smallexample | |
108 | @noindent | |
109 | as this code is not guaranteed to work correctly in the future. | |
110 | ||
111 | You should not take the address of values returned by the macros or | |
112 | functions described here. In particular, no guarantee is given that the | |
113 | values are lvalues. | |
114 | ||
115 | In general, the names of macros are all in uppercase, while the names of | |
116 | functions are entirely in lowercase. There are rare exceptions to this | |
117 | rule. You should assume that any macro or function whose name is made | |
118 | up entirely of uppercase letters may evaluate its arguments more than | |
119 | once. You may assume that a macro or function whose name is made up | |
120 | entirely of lowercase letters will evaluate its arguments only once. | |
121 | ||
122 | The @code{error_mark_node} is a special tree. Its tree code is | |
123 | @code{ERROR_MARK}, but since there is only ever one node with that code, | |
124 | the usual practice is to compare the tree against | |
125 | @code{error_mark_node}. (This test is just a test for pointer | |
126 | equality.) If an error has occurred during front-end processing the | |
127 | flag @code{errorcount} will be set. If the front end has encountered | |
128 | code it cannot handle, it will issue a message to the user and set | |
129 | @code{sorrycount}. When these flags are set, any macro or function | |
130 | which normally returns a tree of a particular kind may instead return | |
131 | the @code{error_mark_node}. Thus, if you intend to do any processing of | |
132 | erroneous code, you must be prepared to deal with the | |
133 | @code{error_mark_node}. | |
134 | ||
135 | Occasionally, a particular tree slot (like an operand to an expression, | |
136 | or a particular field in a declaration) will be referred to as | |
137 | ``reserved for the back end''. These slots are used to store RTL when | |
138 | the tree is converted to RTL for use by the GCC back end. However, if | |
139 | that process is not taking place (e.g., if the front end is being hooked | |
140 | up to an intelligent editor), then those slots may be used by the | |
141 | back end presently in use. | |
142 | ||
143 | If you encounter situations that do not match this documentation, such | |
144 | as tree nodes of types not mentioned here, or macros documented to | |
145 | return entities of a particular kind that instead return entities of | |
146 | some different kind, you have found a bug, either in the front end or in | |
147 | the documentation. Please report these bugs as you would any other | |
148 | bug. | |
149 | ||
150 | @menu | |
151 | * Macros and Functions::Macros and functions that can be used with all trees. | |
152 | * Identifiers:: The names of things. | |
153 | * Containers:: Lists and vectors. | |
154 | @end menu | |
155 | ||
156 | @c --------------------------------------------------------------------- | |
157 | @c Trees | |
158 | @c --------------------------------------------------------------------- | |
159 | ||
160 | @node Macros and Functions | |
161 | @subsection Trees | |
162 | @cindex tree | |
163 | @findex TREE_CHAIN | |
164 | @findex TREE_TYPE | |
165 | ||
166 | All GENERIC trees have two fields in common. First, @code{TREE_CHAIN} | |
167 | is a pointer that can be used as a singly-linked list to other trees. | |
168 | The other is @code{TREE_TYPE}. Many trees store the type of an | |
169 | expression or declaration in this field. | |
170 | ||
171 | These are some other functions for handling trees: | |
172 | ||
173 | @ftable @code | |
174 | ||
175 | @item tree_size | |
176 | Return the number of bytes a tree takes. | |
177 | ||
178 | @item build0 | |
179 | @itemx build1 | |
180 | @itemx build2 | |
181 | @itemx build3 | |
182 | @itemx build4 | |
183 | @itemx build5 | |
184 | @itemx build6 | |
185 | ||
186 | These functions build a tree and supply values to put in each | |
187 | parameter. The basic signature is @samp{@w{code, type, [operands]}}. | |
188 | @code{code} is the @code{TREE_CODE}, and @code{type} is a tree | |
189 | representing the @code{TREE_TYPE}. These are followed by the | |
190 | operands, each of which is also a tree. | |
191 | ||
192 | @end ftable | |
193 | ||
194 | ||
195 | @c --------------------------------------------------------------------- | |
196 | @c Identifiers | |
197 | @c --------------------------------------------------------------------- | |
198 | ||
199 | @node Identifiers | |
200 | @subsection Identifiers | |
201 | @cindex identifier | |
202 | @cindex name | |
203 | @tindex IDENTIFIER_NODE | |
204 | ||
205 | An @code{IDENTIFIER_NODE} represents a slightly more general concept | |
57fc74a4 | 206 | than the standard C or C++ concept of identifier. In particular, an |
929769f4 JQ |
207 | @code{IDENTIFIER_NODE} may contain a @samp{$}, or other extraordinary |
208 | characters. | |
209 | ||
210 | There are never two distinct @code{IDENTIFIER_NODE}s representing the | |
211 | same identifier. Therefore, you may use pointer equality to compare | |
212 | @code{IDENTIFIER_NODE}s, rather than using a routine like | |
213 | @code{strcmp}. Use @code{get_identifier} to obtain the unique | |
214 | @code{IDENTIFIER_NODE} for a supplied string. | |
215 | ||
216 | You can use the following macros to access identifiers: | |
217 | @ftable @code | |
218 | @item IDENTIFIER_POINTER | |
219 | The string represented by the identifier, represented as a | |
220 | @code{char*}. This string is always @code{NUL}-terminated, and contains | |
221 | no embedded @code{NUL} characters. | |
222 | ||
223 | @item IDENTIFIER_LENGTH | |
224 | The length of the string returned by @code{IDENTIFIER_POINTER}, not | |
225 | including the trailing @code{NUL}. This value of | |
226 | @code{IDENTIFIER_LENGTH (x)} is always the same as @code{strlen | |
227 | (IDENTIFIER_POINTER (x))}. | |
228 | ||
229 | @item IDENTIFIER_OPNAME_P | |
230 | This predicate holds if the identifier represents the name of an | |
231 | overloaded operator. In this case, you should not depend on the | |
232 | contents of either the @code{IDENTIFIER_POINTER} or the | |
233 | @code{IDENTIFIER_LENGTH}. | |
234 | ||
235 | @item IDENTIFIER_TYPENAME_P | |
236 | This predicate holds if the identifier represents the name of a | |
237 | user-defined conversion operator. In this case, the @code{TREE_TYPE} of | |
238 | the @code{IDENTIFIER_NODE} holds the type to which the conversion | |
239 | operator converts. | |
240 | ||
241 | @end ftable | |
242 | ||
243 | @c --------------------------------------------------------------------- | |
244 | @c Containers | |
245 | @c --------------------------------------------------------------------- | |
246 | ||
247 | @node Containers | |
248 | @subsection Containers | |
249 | @cindex container | |
250 | @cindex list | |
251 | @cindex vector | |
252 | @tindex TREE_LIST | |
253 | @tindex TREE_VEC | |
254 | @findex TREE_PURPOSE | |
255 | @findex TREE_VALUE | |
256 | @findex TREE_VEC_LENGTH | |
257 | @findex TREE_VEC_ELT | |
258 | ||
259 | Two common container data structures can be represented directly with | |
260 | tree nodes. A @code{TREE_LIST} is a singly linked list containing two | |
261 | trees per node. These are the @code{TREE_PURPOSE} and @code{TREE_VALUE} | |
262 | of each node. (Often, the @code{TREE_PURPOSE} contains some kind of | |
263 | tag, or additional information, while the @code{TREE_VALUE} contains the | |
264 | majority of the payload. In other cases, the @code{TREE_PURPOSE} is | |
265 | simply @code{NULL_TREE}, while in still others both the | |
266 | @code{TREE_PURPOSE} and @code{TREE_VALUE} are of equal stature.) Given | |
267 | one @code{TREE_LIST} node, the next node is found by following the | |
268 | @code{TREE_CHAIN}. If the @code{TREE_CHAIN} is @code{NULL_TREE}, then | |
269 | you have reached the end of the list. | |
270 | ||
271 | A @code{TREE_VEC} is a simple vector. The @code{TREE_VEC_LENGTH} is an | |
272 | integer (not a tree) giving the number of nodes in the vector. The | |
273 | nodes themselves are accessed using the @code{TREE_VEC_ELT} macro, which | |
274 | takes two arguments. The first is the @code{TREE_VEC} in question; the | |
275 | second is an integer indicating which element in the vector is desired. | |
276 | The elements are indexed from zero. | |
277 | ||
278 | @c --------------------------------------------------------------------- | |
279 | @c Types | |
280 | @c --------------------------------------------------------------------- | |
281 | ||
282 | @node Types | |
283 | @section Types | |
284 | @cindex type | |
285 | @cindex pointer | |
286 | @cindex reference | |
287 | @cindex fundamental type | |
288 | @cindex array | |
289 | @tindex VOID_TYPE | |
290 | @tindex INTEGER_TYPE | |
291 | @tindex TYPE_MIN_VALUE | |
292 | @tindex TYPE_MAX_VALUE | |
293 | @tindex REAL_TYPE | |
294 | @tindex FIXED_POINT_TYPE | |
295 | @tindex COMPLEX_TYPE | |
296 | @tindex ENUMERAL_TYPE | |
297 | @tindex BOOLEAN_TYPE | |
298 | @tindex POINTER_TYPE | |
299 | @tindex REFERENCE_TYPE | |
300 | @tindex FUNCTION_TYPE | |
301 | @tindex METHOD_TYPE | |
302 | @tindex ARRAY_TYPE | |
303 | @tindex RECORD_TYPE | |
304 | @tindex UNION_TYPE | |
6b91b3e9 | 305 | @tindex OPAQUE_TYPE |
929769f4 JQ |
306 | @tindex UNKNOWN_TYPE |
307 | @tindex OFFSET_TYPE | |
308 | @findex TYPE_UNQUALIFIED | |
309 | @findex TYPE_QUAL_CONST | |
310 | @findex TYPE_QUAL_VOLATILE | |
311 | @findex TYPE_QUAL_RESTRICT | |
312 | @findex TYPE_MAIN_VARIANT | |
313 | @cindex qualified type | |
314 | @findex TYPE_SIZE | |
315 | @findex TYPE_ALIGN | |
316 | @findex TYPE_PRECISION | |
317 | @findex TYPE_ARG_TYPES | |
318 | @findex TYPE_METHOD_BASETYPE | |
319 | @findex TYPE_OFFSET_BASETYPE | |
320 | @findex TREE_TYPE | |
321 | @findex TYPE_CONTEXT | |
322 | @findex TYPE_NAME | |
323 | @findex TYPENAME_TYPE_FULLNAME | |
324 | @findex TYPE_FIELDS | |
325 | @findex TYPE_CANONICAL | |
326 | @findex TYPE_STRUCTURAL_EQUALITY_P | |
327 | @findex SET_TYPE_STRUCTURAL_EQUALITY | |
328 | ||
329 | All types have corresponding tree nodes. However, you should not assume | |
330 | that there is exactly one tree node corresponding to each type. There | |
331 | are often multiple nodes corresponding to the same type. | |
332 | ||
333 | For the most part, different kinds of types have different tree codes. | |
334 | (For example, pointer types use a @code{POINTER_TYPE} code while arrays | |
335 | use an @code{ARRAY_TYPE} code.) However, pointers to member functions | |
336 | use the @code{RECORD_TYPE} code. Therefore, when writing a | |
337 | @code{switch} statement that depends on the code associated with a | |
338 | particular type, you should take care to handle pointers to member | |
339 | functions under the @code{RECORD_TYPE} case label. | |
340 | ||
341 | The following functions and macros deal with cv-qualification of types: | |
342 | @ftable @code | |
343 | @item TYPE_MAIN_VARIANT | |
344 | This macro returns the unqualified version of a type. It may be applied | |
345 | to an unqualified type, but it is not always the identity function in | |
346 | that case. | |
347 | @end ftable | |
348 | ||
349 | A few other macros and functions are usable with all types: | |
350 | @ftable @code | |
351 | @item TYPE_SIZE | |
352 | The number of bits required to represent the type, represented as an | |
353 | @code{INTEGER_CST}. For an incomplete type, @code{TYPE_SIZE} will be | |
354 | @code{NULL_TREE}. | |
355 | ||
356 | @item TYPE_ALIGN | |
357 | The alignment of the type, in bits, represented as an @code{int}. | |
358 | ||
359 | @item TYPE_NAME | |
360 | This macro returns a declaration (in the form of a @code{TYPE_DECL}) for | |
361 | the type. (Note this macro does @emph{not} return an | |
362 | @code{IDENTIFIER_NODE}, as you might expect, given its name!) You can | |
363 | look at the @code{DECL_NAME} of the @code{TYPE_DECL} to obtain the | |
364 | actual name of the type. The @code{TYPE_NAME} will be @code{NULL_TREE} | |
365 | for a type that is not a built-in type, the result of a typedef, or a | |
366 | named class type. | |
367 | ||
368 | @item TYPE_CANONICAL | |
369 | This macro returns the ``canonical'' type for the given type | |
370 | node. Canonical types are used to improve performance in the C++ and | |
371 | Objective-C++ front ends by allowing efficient comparison between two | |
372 | type nodes in @code{same_type_p}: if the @code{TYPE_CANONICAL} values | |
373 | of the types are equal, the types are equivalent; otherwise, the types | |
374 | are not equivalent. The notion of equivalence for canonical types is | |
375 | the same as the notion of type equivalence in the language itself. For | |
376 | instance, | |
377 | ||
378 | When @code{TYPE_CANONICAL} is @code{NULL_TREE}, there is no canonical | |
379 | type for the given type node. In this case, comparison between this | |
380 | type and any other type requires the compiler to perform a deep, | |
381 | ``structural'' comparison to see if the two type nodes have the same | |
382 | form and properties. | |
383 | ||
384 | The canonical type for a node is always the most fundamental type in | |
385 | the equivalence class of types. For instance, @code{int} is its own | |
386 | canonical type. A typedef @code{I} of @code{int} will have @code{int} | |
387 | as its canonical type. Similarly, @code{I*}@ and a typedef @code{IP}@ | |
388 | (defined to @code{I*}) will has @code{int*} as their canonical | |
389 | type. When building a new type node, be sure to set | |
390 | @code{TYPE_CANONICAL} to the appropriate canonical type. If the new | |
391 | type is a compound type (built from other types), and any of those | |
392 | other types require structural equality, use | |
393 | @code{SET_TYPE_STRUCTURAL_EQUALITY} to ensure that the new type also | |
394 | requires structural equality. Finally, if for some reason you cannot | |
395 | guarantee that @code{TYPE_CANONICAL} will point to the canonical type, | |
396 | use @code{SET_TYPE_STRUCTURAL_EQUALITY} to make sure that the new | |
397 | type--and any type constructed based on it--requires structural | |
398 | equality. If you suspect that the canonical type system is | |
399 | miscomparing types, pass @code{--param verify-canonical-types=1} to | |
400 | the compiler or configure with @code{--enable-checking} to force the | |
401 | compiler to verify its canonical-type comparisons against the | |
402 | structural comparisons; the compiler will then print any warnings if | |
403 | the canonical types miscompare. | |
404 | ||
405 | @item TYPE_STRUCTURAL_EQUALITY_P | |
406 | This predicate holds when the node requires structural equality | |
407 | checks, e.g., when @code{TYPE_CANONICAL} is @code{NULL_TREE}. | |
408 | ||
409 | @item SET_TYPE_STRUCTURAL_EQUALITY | |
410 | This macro states that the type node it is given requires structural | |
411 | equality checks, e.g., it sets @code{TYPE_CANONICAL} to | |
412 | @code{NULL_TREE}. | |
413 | ||
414 | @item same_type_p | |
415 | This predicate takes two types as input, and holds if they are the same | |
416 | type. For example, if one type is a @code{typedef} for the other, or | |
417 | both are @code{typedef}s for the same type. This predicate also holds if | |
418 | the two trees given as input are simply copies of one another; i.e., | |
419 | there is no difference between them at the source level, but, for | |
420 | whatever reason, a duplicate has been made in the representation. You | |
421 | should never use @code{==} (pointer equality) to compare types; always | |
422 | use @code{same_type_p} instead. | |
423 | @end ftable | |
424 | ||
425 | Detailed below are the various kinds of types, and the macros that can | |
426 | be used to access them. Although other kinds of types are used | |
427 | elsewhere in G++, the types described here are the only ones that you | |
428 | will encounter while examining the intermediate representation. | |
429 | ||
430 | @table @code | |
431 | @item VOID_TYPE | |
432 | Used to represent the @code{void} type. | |
433 | ||
434 | @item INTEGER_TYPE | |
435 | Used to represent the various integral types, including @code{char}, | |
436 | @code{short}, @code{int}, @code{long}, and @code{long long}. This code | |
437 | is not used for enumeration types, nor for the @code{bool} type. | |
438 | The @code{TYPE_PRECISION} is the number of bits used in | |
439 | the representation, represented as an @code{unsigned int}. (Note that | |
440 | in the general case this is not the same value as @code{TYPE_SIZE}; | |
441 | suppose that there were a 24-bit integer type, but that alignment | |
442 | requirements for the ABI required 32-bit alignment. Then, | |
443 | @code{TYPE_SIZE} would be an @code{INTEGER_CST} for 32, while | |
444 | @code{TYPE_PRECISION} would be 24.) The integer type is unsigned if | |
445 | @code{TYPE_UNSIGNED} holds; otherwise, it is signed. | |
446 | ||
447 | The @code{TYPE_MIN_VALUE} is an @code{INTEGER_CST} for the smallest | |
448 | integer that may be represented by this type. Similarly, the | |
449 | @code{TYPE_MAX_VALUE} is an @code{INTEGER_CST} for the largest integer | |
450 | that may be represented by this type. | |
451 | ||
452 | @item REAL_TYPE | |
453 | Used to represent the @code{float}, @code{double}, and @code{long | |
454 | double} types. The number of bits in the floating-point representation | |
455 | is given by @code{TYPE_PRECISION}, as in the @code{INTEGER_TYPE} case. | |
456 | ||
457 | @item FIXED_POINT_TYPE | |
458 | Used to represent the @code{short _Fract}, @code{_Fract}, @code{long | |
459 | _Fract}, @code{long long _Fract}, @code{short _Accum}, @code{_Accum}, | |
460 | @code{long _Accum}, and @code{long long _Accum} types. The number of bits | |
461 | in the fixed-point representation is given by @code{TYPE_PRECISION}, | |
462 | as in the @code{INTEGER_TYPE} case. There may be padding bits, fractional | |
463 | bits and integral bits. The number of fractional bits is given by | |
464 | @code{TYPE_FBIT}, and the number of integral bits is given by @code{TYPE_IBIT}. | |
465 | The fixed-point type is unsigned if @code{TYPE_UNSIGNED} holds; otherwise, | |
466 | it is signed. | |
467 | The fixed-point type is saturating if @code{TYPE_SATURATING} holds; otherwise, | |
468 | it is not saturating. | |
469 | ||
470 | @item COMPLEX_TYPE | |
471 | Used to represent GCC built-in @code{__complex__} data types. The | |
472 | @code{TREE_TYPE} is the type of the real and imaginary parts. | |
473 | ||
474 | @item ENUMERAL_TYPE | |
475 | Used to represent an enumeration type. The @code{TYPE_PRECISION} gives | |
476 | (as an @code{int}), the number of bits used to represent the type. If | |
477 | there are no negative enumeration constants, @code{TYPE_UNSIGNED} will | |
478 | hold. The minimum and maximum enumeration constants may be obtained | |
479 | with @code{TYPE_MIN_VALUE} and @code{TYPE_MAX_VALUE}, respectively; each | |
480 | of these macros returns an @code{INTEGER_CST}. | |
481 | ||
482 | The actual enumeration constants themselves may be obtained by looking | |
483 | at the @code{TYPE_VALUES}. This macro will return a @code{TREE_LIST}, | |
484 | containing the constants. The @code{TREE_PURPOSE} of each node will be | |
485 | an @code{IDENTIFIER_NODE} giving the name of the constant; the | |
486 | @code{TREE_VALUE} will be an @code{INTEGER_CST} giving the value | |
487 | assigned to that constant. These constants will appear in the order in | |
488 | which they were declared. The @code{TREE_TYPE} of each of these | |
489 | constants will be the type of enumeration type itself. | |
490 | ||
6b91b3e9 AS |
491 | @item OPAQUE_TYPE |
492 | Used for things that have a @code{MODE_OPAQUE} mode class in the | |
493 | backend. Opaque types have a size and precision, and can be held in | |
494 | memory or registers. They are used when we do not want the compiler to | |
495 | make assumptions about the availability of other operations as would | |
496 | happen with integer types. | |
497 | ||
929769f4 JQ |
498 | @item BOOLEAN_TYPE |
499 | Used to represent the @code{bool} type. | |
500 | ||
501 | @item POINTER_TYPE | |
502 | Used to represent pointer types, and pointer to data member types. The | |
503 | @code{TREE_TYPE} gives the type to which this type points. | |
504 | ||
505 | @item REFERENCE_TYPE | |
506 | Used to represent reference types. The @code{TREE_TYPE} gives the type | |
507 | to which this type refers. | |
508 | ||
509 | @item FUNCTION_TYPE | |
510 | Used to represent the type of non-member functions and of static member | |
511 | functions. The @code{TREE_TYPE} gives the return type of the function. | |
512 | The @code{TYPE_ARG_TYPES} are a @code{TREE_LIST} of the argument types. | |
513 | The @code{TREE_VALUE} of each node in this list is the type of the | |
514 | corresponding argument; the @code{TREE_PURPOSE} is an expression for the | |
515 | default argument value, if any. If the last node in the list is | |
516 | @code{void_list_node} (a @code{TREE_LIST} node whose @code{TREE_VALUE} | |
517 | is the @code{void_type_node}), then functions of this type do not take | |
518 | variable arguments. Otherwise, they do take a variable number of | |
519 | arguments. | |
520 | ||
521 | Note that in C (but not in C++) a function declared like @code{void f()} | |
522 | is an unprototyped function taking a variable number of arguments; the | |
523 | @code{TYPE_ARG_TYPES} of such a function will be @code{NULL}. | |
524 | ||
525 | @item METHOD_TYPE | |
526 | Used to represent the type of a non-static member function. Like a | |
527 | @code{FUNCTION_TYPE}, the return type is given by the @code{TREE_TYPE}. | |
528 | The type of @code{*this}, i.e., the class of which functions of this | |
529 | type are a member, is given by the @code{TYPE_METHOD_BASETYPE}. The | |
530 | @code{TYPE_ARG_TYPES} is the parameter list, as for a | |
531 | @code{FUNCTION_TYPE}, and includes the @code{this} argument. | |
532 | ||
533 | @item ARRAY_TYPE | |
534 | Used to represent array types. The @code{TREE_TYPE} gives the type of | |
535 | the elements in the array. If the array-bound is present in the type, | |
536 | the @code{TYPE_DOMAIN} is an @code{INTEGER_TYPE} whose | |
537 | @code{TYPE_MIN_VALUE} and @code{TYPE_MAX_VALUE} will be the lower and | |
538 | upper bounds of the array, respectively. The @code{TYPE_MIN_VALUE} will | |
539 | always be an @code{INTEGER_CST} for zero, while the | |
540 | @code{TYPE_MAX_VALUE} will be one less than the number of elements in | |
541 | the array, i.e., the highest value which may be used to index an element | |
542 | in the array. | |
543 | ||
544 | @item RECORD_TYPE | |
545 | Used to represent @code{struct} and @code{class} types, as well as | |
546 | pointers to member functions and similar constructs in other languages. | |
547 | @code{TYPE_FIELDS} contains the items contained in this type, each of | |
548 | which can be a @code{FIELD_DECL}, @code{VAR_DECL}, @code{CONST_DECL}, or | |
549 | @code{TYPE_DECL}. You may not make any assumptions about the ordering | |
550 | of the fields in the type or whether one or more of them overlap. | |
551 | ||
552 | @item UNION_TYPE | |
553 | Used to represent @code{union} types. Similar to @code{RECORD_TYPE} | |
554 | except that all @code{FIELD_DECL} nodes in @code{TYPE_FIELD} start at | |
555 | bit position zero. | |
556 | ||
557 | @item QUAL_UNION_TYPE | |
558 | Used to represent part of a variant record in Ada. Similar to | |
559 | @code{UNION_TYPE} except that each @code{FIELD_DECL} has a | |
560 | @code{DECL_QUALIFIER} field, which contains a boolean expression that | |
561 | indicates whether the field is present in the object. The type will only | |
562 | have one field, so each field's @code{DECL_QUALIFIER} is only evaluated | |
563 | if none of the expressions in the previous fields in @code{TYPE_FIELDS} | |
564 | are nonzero. Normally these expressions will reference a field in the | |
565 | outer object using a @code{PLACEHOLDER_EXPR}. | |
566 | ||
567 | @item LANG_TYPE | |
568 | This node is used to represent a language-specific type. The front | |
569 | end must handle it. | |
570 | ||
571 | @item OFFSET_TYPE | |
572 | This node is used to represent a pointer-to-data member. For a data | |
573 | member @code{X::m} the @code{TYPE_OFFSET_BASETYPE} is @code{X} and the | |
574 | @code{TREE_TYPE} is the type of @code{m}. | |
575 | ||
576 | @end table | |
577 | ||
578 | There are variables whose values represent some of the basic types. | |
579 | These include: | |
580 | @table @code | |
581 | @item void_type_node | |
582 | A node for @code{void}. | |
583 | ||
584 | @item integer_type_node | |
585 | A node for @code{int}. | |
586 | ||
587 | @item unsigned_type_node. | |
588 | A node for @code{unsigned int}. | |
589 | ||
590 | @item char_type_node. | |
591 | A node for @code{char}. | |
592 | @end table | |
593 | @noindent | |
594 | It may sometimes be useful to compare one of these variables with a type | |
595 | in hand, using @code{same_type_p}. | |
596 | ||
597 | @c --------------------------------------------------------------------- | |
598 | @c Declarations | |
599 | @c --------------------------------------------------------------------- | |
600 | ||
601 | @node Declarations | |
602 | @section Declarations | |
603 | @cindex declaration | |
604 | @cindex variable | |
605 | @cindex type declaration | |
606 | @tindex LABEL_DECL | |
607 | @tindex CONST_DECL | |
608 | @tindex TYPE_DECL | |
609 | @tindex VAR_DECL | |
610 | @tindex PARM_DECL | |
38be945b | 611 | @tindex DEBUG_EXPR_DECL |
929769f4 JQ |
612 | @tindex FIELD_DECL |
613 | @tindex NAMESPACE_DECL | |
614 | @tindex RESULT_DECL | |
615 | @tindex TEMPLATE_DECL | |
616 | @tindex THUNK_DECL | |
617 | @findex THUNK_DELTA | |
618 | @findex DECL_INITIAL | |
619 | @findex DECL_SIZE | |
620 | @findex DECL_ALIGN | |
621 | @findex DECL_EXTERNAL | |
622 | ||
623 | This section covers the various kinds of declarations that appear in the | |
624 | internal representation, except for declarations of functions | |
625 | (represented by @code{FUNCTION_DECL} nodes), which are described in | |
626 | @ref{Functions}. | |
627 | ||
628 | @menu | |
629 | * Working with declarations:: Macros and functions that work on | |
630 | declarations. | |
ff2ce160 | 631 | * Internal structure:: How declaration nodes are represented. |
929769f4 JQ |
632 | @end menu |
633 | ||
634 | @node Working with declarations | |
635 | @subsection Working with declarations | |
636 | ||
637 | Some macros can be used with any kind of declaration. These include: | |
638 | @ftable @code | |
639 | @item DECL_NAME | |
640 | This macro returns an @code{IDENTIFIER_NODE} giving the name of the | |
641 | entity. | |
642 | ||
643 | @item TREE_TYPE | |
644 | This macro returns the type of the entity declared. | |
645 | ||
646 | @item EXPR_FILENAME | |
647 | This macro returns the name of the file in which the entity was | |
648 | declared, as a @code{char*}. For an entity declared implicitly by the | |
649 | compiler (like @code{__builtin_memcpy}), this will be the string | |
650 | @code{"<internal>"}. | |
651 | ||
652 | @item EXPR_LINENO | |
653 | This macro returns the line number at which the entity was declared, as | |
654 | an @code{int}. | |
655 | ||
656 | @item DECL_ARTIFICIAL | |
657 | This predicate holds if the declaration was implicitly generated by the | |
658 | compiler. For example, this predicate will hold of an implicitly | |
659 | declared member function, or of the @code{TYPE_DECL} implicitly | |
660 | generated for a class type. Recall that in C++ code like: | |
661 | @smallexample | |
662 | struct S @{@}; | |
663 | @end smallexample | |
664 | @noindent | |
665 | is roughly equivalent to C code like: | |
666 | @smallexample | |
667 | struct S @{@}; | |
668 | typedef struct S S; | |
669 | @end smallexample | |
670 | The implicitly generated @code{typedef} declaration is represented by a | |
671 | @code{TYPE_DECL} for which @code{DECL_ARTIFICIAL} holds. | |
672 | ||
673 | @end ftable | |
674 | ||
675 | The various kinds of declarations include: | |
676 | @table @code | |
677 | @item LABEL_DECL | |
678 | These nodes are used to represent labels in function bodies. For more | |
679 | information, see @ref{Functions}. These nodes only appear in block | |
680 | scopes. | |
681 | ||
682 | @item CONST_DECL | |
683 | These nodes are used to represent enumeration constants. The value of | |
684 | the constant is given by @code{DECL_INITIAL} which will be an | |
685 | @code{INTEGER_CST} with the same type as the @code{TREE_TYPE} of the | |
686 | @code{CONST_DECL}, i.e., an @code{ENUMERAL_TYPE}. | |
687 | ||
688 | @item RESULT_DECL | |
689 | These nodes represent the value returned by a function. When a value is | |
690 | assigned to a @code{RESULT_DECL}, that indicates that the value should | |
691 | be returned, via bitwise copy, by the function. You can use | |
692 | @code{DECL_SIZE} and @code{DECL_ALIGN} on a @code{RESULT_DECL}, just as | |
693 | with a @code{VAR_DECL}. | |
694 | ||
695 | @item TYPE_DECL | |
696 | These nodes represent @code{typedef} declarations. The @code{TREE_TYPE} | |
697 | is the type declared to have the name given by @code{DECL_NAME}. In | |
698 | some cases, there is no associated name. | |
699 | ||
700 | @item VAR_DECL | |
701 | These nodes represent variables with namespace or block scope, as well | |
702 | as static data members. The @code{DECL_SIZE} and @code{DECL_ALIGN} are | |
703 | analogous to @code{TYPE_SIZE} and @code{TYPE_ALIGN}. For a declaration, | |
704 | you should always use the @code{DECL_SIZE} and @code{DECL_ALIGN} rather | |
705 | than the @code{TYPE_SIZE} and @code{TYPE_ALIGN} given by the | |
706 | @code{TREE_TYPE}, since special attributes may have been applied to the | |
707 | variable to give it a particular size and alignment. You may use the | |
708 | predicates @code{DECL_THIS_STATIC} or @code{DECL_THIS_EXTERN} to test | |
709 | whether the storage class specifiers @code{static} or @code{extern} were | |
710 | used to declare a variable. | |
711 | ||
712 | If this variable is initialized (but does not require a constructor), | |
713 | the @code{DECL_INITIAL} will be an expression for the initializer. The | |
714 | initializer should be evaluated, and a bitwise copy into the variable | |
715 | performed. If the @code{DECL_INITIAL} is the @code{error_mark_node}, | |
716 | there is an initializer, but it is given by an explicit statement later | |
717 | in the code; no bitwise copy is required. | |
718 | ||
719 | GCC provides an extension that allows either automatic variables, or | |
720 | global variables, to be placed in particular registers. This extension | |
721 | is being used for a particular @code{VAR_DECL} if @code{DECL_REGISTER} | |
722 | holds for the @code{VAR_DECL}, and if @code{DECL_ASSEMBLER_NAME} is not | |
723 | equal to @code{DECL_NAME}. In that case, @code{DECL_ASSEMBLER_NAME} is | |
724 | the name of the register into which the variable will be placed. | |
725 | ||
726 | @item PARM_DECL | |
727 | Used to represent a parameter to a function. Treat these nodes | |
728 | similarly to @code{VAR_DECL} nodes. These nodes only appear in the | |
729 | @code{DECL_ARGUMENTS} for a @code{FUNCTION_DECL}. | |
730 | ||
731 | The @code{DECL_ARG_TYPE} for a @code{PARM_DECL} is the type that will | |
732 | actually be used when a value is passed to this function. It may be a | |
733 | wider type than the @code{TREE_TYPE} of the parameter; for example, the | |
734 | ordinary type might be @code{short} while the @code{DECL_ARG_TYPE} is | |
735 | @code{int}. | |
736 | ||
38be945b AO |
737 | @item DEBUG_EXPR_DECL |
738 | Used to represent an anonymous debug-information temporary created to | |
739 | hold an expression as it is optimized away, so that its value can be | |
740 | referenced in debug bind statements. | |
741 | ||
929769f4 JQ |
742 | @item FIELD_DECL |
743 | These nodes represent non-static data members. The @code{DECL_SIZE} and | |
ff2ce160 MS |
744 | @code{DECL_ALIGN} behave as for @code{VAR_DECL} nodes. |
745 | The position of the field within the parent record is specified by a | |
929769f4 JQ |
746 | combination of three attributes. @code{DECL_FIELD_OFFSET} is the position, |
747 | counting in bytes, of the @code{DECL_OFFSET_ALIGN}-bit sized word containing | |
ff2ce160 | 748 | the bit of the field closest to the beginning of the structure. |
929769f4 JQ |
749 | @code{DECL_FIELD_BIT_OFFSET} is the bit offset of the first bit of the field |
750 | within this word; this may be nonzero even for fields that are not bit-fields, | |
751 | since @code{DECL_OFFSET_ALIGN} may be greater than the natural alignment | |
752 | of the field's type. | |
753 | ||
754 | If @code{DECL_C_BIT_FIELD} holds, this field is a bit-field. In a bit-field, | |
755 | @code{DECL_BIT_FIELD_TYPE} also contains the type that was originally | |
756 | specified for it, while DECL_TYPE may be a modified type with lesser precision, | |
757 | according to the size of the bit field. | |
758 | ||
759 | @item NAMESPACE_DECL | |
7a50adb7 | 760 | Namespaces provide a name hierarchy for other declarations. They |
929769f4 JQ |
761 | appear in the @code{DECL_CONTEXT} of other @code{_DECL} nodes. |
762 | ||
763 | @end table | |
764 | ||
765 | @node Internal structure | |
766 | @subsection Internal structure | |
767 | ||
768 | @code{DECL} nodes are represented internally as a hierarchy of | |
769 | structures. | |
770 | ||
771 | @menu | |
772 | * Current structure hierarchy:: The current DECL node structure | |
773 | hierarchy. | |
774 | * Adding new DECL node types:: How to add a new DECL node to a | |
775 | frontend. | |
776 | @end menu | |
777 | ||
778 | @node Current structure hierarchy | |
779 | @subsubsection Current structure hierarchy | |
780 | ||
781 | @table @code | |
782 | ||
783 | @item struct tree_decl_minimal | |
784 | This is the minimal structure to inherit from in order for common | |
785 | @code{DECL} macros to work. The fields it contains are a unique ID, | |
786 | source location, context, and name. | |
787 | ||
788 | @item struct tree_decl_common | |
789 | This structure inherits from @code{struct tree_decl_minimal}. It | |
790 | contains fields that most @code{DECL} nodes need, such as a field to | |
791 | store alignment, machine mode, size, and attributes. | |
792 | ||
793 | @item struct tree_field_decl | |
794 | This structure inherits from @code{struct tree_decl_common}. It is | |
795 | used to represent @code{FIELD_DECL}. | |
796 | ||
797 | @item struct tree_label_decl | |
798 | This structure inherits from @code{struct tree_decl_common}. It is | |
799 | used to represent @code{LABEL_DECL}. | |
800 | ||
801 | @item struct tree_translation_unit_decl | |
802 | This structure inherits from @code{struct tree_decl_common}. It is | |
803 | used to represent @code{TRANSLATION_UNIT_DECL}. | |
804 | ||
805 | @item struct tree_decl_with_rtl | |
806 | This structure inherits from @code{struct tree_decl_common}. It | |
807 | contains a field to store the low-level RTL associated with a | |
808 | @code{DECL} node. | |
809 | ||
810 | @item struct tree_result_decl | |
811 | This structure inherits from @code{struct tree_decl_with_rtl}. It is | |
812 | used to represent @code{RESULT_DECL}. | |
813 | ||
814 | @item struct tree_const_decl | |
815 | This structure inherits from @code{struct tree_decl_with_rtl}. It is | |
816 | used to represent @code{CONST_DECL}. | |
817 | ||
818 | @item struct tree_parm_decl | |
819 | This structure inherits from @code{struct tree_decl_with_rtl}. It is | |
ff2ce160 | 820 | used to represent @code{PARM_DECL}. |
929769f4 JQ |
821 | |
822 | @item struct tree_decl_with_vis | |
823 | This structure inherits from @code{struct tree_decl_with_rtl}. It | |
824 | contains fields necessary to store visibility information, as well as | |
825 | a section name and assembler name. | |
826 | ||
827 | @item struct tree_var_decl | |
828 | This structure inherits from @code{struct tree_decl_with_vis}. It is | |
ff2ce160 | 829 | used to represent @code{VAR_DECL}. |
929769f4 JQ |
830 | |
831 | @item struct tree_function_decl | |
832 | This structure inherits from @code{struct tree_decl_with_vis}. It is | |
ff2ce160 | 833 | used to represent @code{FUNCTION_DECL}. |
929769f4 JQ |
834 | |
835 | @end table | |
836 | @node Adding new DECL node types | |
837 | @subsubsection Adding new DECL node types | |
838 | ||
839 | Adding a new @code{DECL} tree consists of the following steps | |
840 | ||
841 | @table @asis | |
842 | ||
843 | @item Add a new tree code for the @code{DECL} node | |
844 | For language specific @code{DECL} nodes, there is a @file{.def} file | |
845 | in each frontend directory where the tree code should be added. | |
846 | For @code{DECL} nodes that are part of the middle-end, the code should | |
847 | be added to @file{tree.def}. | |
848 | ||
849 | @item Create a new structure type for the @code{DECL} node | |
850 | These structures should inherit from one of the existing structures in | |
851 | the language hierarchy by using that structure as the first member. | |
852 | ||
853 | @smallexample | |
854 | struct tree_foo_decl | |
855 | @{ | |
856 | struct tree_decl_with_vis common; | |
857 | @} | |
858 | @end smallexample | |
859 | ||
860 | Would create a structure name @code{tree_foo_decl} that inherits from | |
861 | @code{struct tree_decl_with_vis}. | |
862 | ||
863 | For language specific @code{DECL} nodes, this new structure type | |
864 | should go in the appropriate @file{.h} file. | |
865 | For @code{DECL} nodes that are part of the middle-end, the structure | |
866 | type should go in @file{tree.h}. | |
867 | ||
868 | @item Add a member to the tree structure enumerator for the node | |
869 | For garbage collection and dynamic checking purposes, each @code{DECL} | |
870 | node structure type is required to have a unique enumerator value | |
871 | specified with it. | |
872 | For language specific @code{DECL} nodes, this new enumerator value | |
873 | should go in the appropriate @file{.def} file. | |
874 | For @code{DECL} nodes that are part of the middle-end, the enumerator | |
875 | values are specified in @file{treestruct.def}. | |
876 | ||
877 | @item Update @code{union tree_node} | |
878 | In order to make your new structure type usable, it must be added to | |
879 | @code{union tree_node}. | |
880 | For language specific @code{DECL} nodes, a new entry should be added | |
881 | to the appropriate @file{.h} file of the form | |
882 | @smallexample | |
883 | struct tree_foo_decl GTY ((tag ("TS_VAR_DECL"))) foo_decl; | |
884 | @end smallexample | |
885 | For @code{DECL} nodes that are part of the middle-end, the additional | |
886 | member goes directly into @code{union tree_node} in @file{tree.h}. | |
887 | ||
888 | @item Update dynamic checking info | |
889 | In order to be able to check whether accessing a named portion of | |
890 | @code{union tree_node} is legal, and whether a certain @code{DECL} node | |
891 | contains one of the enumerated @code{DECL} node structures in the | |
892 | hierarchy, a simple lookup table is used. | |
893 | This lookup table needs to be kept up to date with the tree structure | |
894 | hierarchy, or else checking and containment macros will fail | |
895 | inappropriately. | |
896 | ||
0ac15b17 | 897 | For language specific @code{DECL} nodes, there is an @code{init_ts} |
929769f4 JQ |
898 | function in an appropriate @file{.c} file, which initializes the lookup |
899 | table. | |
900 | Code setting up the table for new @code{DECL} nodes should be added | |
901 | there. | |
902 | For each @code{DECL} tree code and enumerator value representing a | |
903 | member of the inheritance hierarchy, the table should contain 1 if | |
904 | that tree code inherits (directly or indirectly) from that member. | |
905 | Thus, a @code{FOO_DECL} node derived from @code{struct decl_with_rtl}, | |
906 | and enumerator value @code{TS_FOO_DECL}, would be set up as follows | |
907 | @smallexample | |
908 | tree_contains_struct[FOO_DECL][TS_FOO_DECL] = 1; | |
909 | tree_contains_struct[FOO_DECL][TS_DECL_WRTL] = 1; | |
910 | tree_contains_struct[FOO_DECL][TS_DECL_COMMON] = 1; | |
911 | tree_contains_struct[FOO_DECL][TS_DECL_MINIMAL] = 1; | |
912 | @end smallexample | |
913 | ||
914 | For @code{DECL} nodes that are part of the middle-end, the setup code | |
915 | goes into @file{tree.c}. | |
916 | ||
917 | @item Add macros to access any new fields and flags | |
918 | ||
919 | Each added field or flag should have a macro that is used to access | |
920 | it, that performs appropriate checking to ensure only the right type of | |
921 | @code{DECL} nodes access the field. | |
922 | ||
923 | These macros generally take the following form | |
924 | @smallexample | |
925 | #define FOO_DECL_FIELDNAME(NODE) FOO_DECL_CHECK(NODE)->foo_decl.fieldname | |
926 | @end smallexample | |
927 | However, if the structure is simply a base class for further | |
928 | structures, something like the following should be used | |
929 | @smallexample | |
930 | #define BASE_STRUCT_CHECK(T) CONTAINS_STRUCT_CHECK(T, TS_BASE_STRUCT) | |
931 | #define BASE_STRUCT_FIELDNAME(NODE) \ | |
932 | (BASE_STRUCT_CHECK(NODE)->base_struct.fieldname | |
933 | @end smallexample | |
934 | ||
1a79fb8a TS |
935 | Reading them from the generated @file{all-tree.def} file (which in |
936 | turn includes all the @file{tree.def} files), @file{gencheck.c} is | |
937 | used during GCC's build to generate the @code{*_CHECK} macros for all | |
938 | tree codes. | |
939 | ||
929769f4 JQ |
940 | @end table |
941 | ||
942 | ||
943 | @c --------------------------------------------------------------------- | |
944 | @c Attributes | |
945 | @c --------------------------------------------------------------------- | |
946 | @node Attributes | |
947 | @section Attributes in trees | |
948 | @cindex attributes | |
949 | ||
950 | Attributes, as specified using the @code{__attribute__} keyword, are | |
951 | represented internally as a @code{TREE_LIST}. The @code{TREE_PURPOSE} | |
952 | is the name of the attribute, as an @code{IDENTIFIER_NODE}. The | |
953 | @code{TREE_VALUE} is a @code{TREE_LIST} of the arguments of the | |
954 | attribute, if any, or @code{NULL_TREE} if there are no arguments; the | |
955 | arguments are stored as the @code{TREE_VALUE} of successive entries in | |
956 | the list, and may be identifiers or expressions. The @code{TREE_CHAIN} | |
957 | of the attribute is the next attribute in a list of attributes applying | |
958 | to the same declaration or type, or @code{NULL_TREE} if there are no | |
959 | further attributes in the list. | |
960 | ||
961 | Attributes may be attached to declarations and to types; these | |
962 | attributes may be accessed with the following macros. All attributes | |
963 | are stored in this way, and many also cause other changes to the | |
964 | declaration or type or to other internal compiler data structures. | |
965 | ||
966 | @deftypefn {Tree Macro} tree DECL_ATTRIBUTES (tree @var{decl}) | |
967 | This macro returns the attributes on the declaration @var{decl}. | |
968 | @end deftypefn | |
969 | ||
970 | @deftypefn {Tree Macro} tree TYPE_ATTRIBUTES (tree @var{type}) | |
971 | This macro returns the attributes on the type @var{type}. | |
972 | @end deftypefn | |
973 | ||
974 | ||
975 | @c --------------------------------------------------------------------- | |
976 | @c Expressions | |
977 | @c --------------------------------------------------------------------- | |
978 | ||
979 | @node Expression trees | |
980 | @section Expressions | |
981 | @cindex expression | |
982 | @findex TREE_TYPE | |
983 | @findex TREE_OPERAND | |
984 | ||
985 | The internal representation for expressions is for the most part quite | |
986 | straightforward. However, there are a few facts that one must bear in | |
987 | mind. In particular, the expression ``tree'' is actually a directed | |
988 | acyclic graph. (For example there may be many references to the integer | |
989 | constant zero throughout the source program; many of these will be | |
990 | represented by the same expression node.) You should not rely on | |
991 | certain kinds of node being shared, nor should you rely on certain kinds of | |
992 | nodes being unshared. | |
993 | ||
994 | The following macros can be used with all expression nodes: | |
995 | ||
996 | @ftable @code | |
997 | @item TREE_TYPE | |
998 | Returns the type of the expression. This value may not be precisely the | |
999 | same type that would be given the expression in the original program. | |
1000 | @end ftable | |
1001 | ||
1002 | In what follows, some nodes that one might expect to always have type | |
1003 | @code{bool} are documented to have either integral or boolean type. At | |
1004 | some point in the future, the C front end may also make use of this same | |
1005 | intermediate representation, and at this point these nodes will | |
1006 | certainly have integral type. The previous sentence is not meant to | |
1007 | imply that the C++ front end does not or will not give these nodes | |
1008 | integral type. | |
1009 | ||
1010 | Below, we list the various kinds of expression nodes. Except where | |
1011 | noted otherwise, the operands to an expression are accessed using the | |
1012 | @code{TREE_OPERAND} macro. For example, to access the first operand to | |
1013 | a binary plus expression @code{expr}, use: | |
1014 | ||
1015 | @smallexample | |
1016 | TREE_OPERAND (expr, 0) | |
1017 | @end smallexample | |
1018 | @noindent | |
1019 | ||
1020 | As this example indicates, the operands are zero-indexed. | |
1021 | ||
1022 | ||
1023 | @menu | |
1024 | * Constants: Constant expressions. | |
1025 | * Storage References:: | |
1026 | * Unary and Binary Expressions:: | |
1027 | * Vectors:: | |
1028 | @end menu | |
1029 | ||
1030 | @node Constant expressions | |
1031 | @subsection Constant expressions | |
1032 | @tindex INTEGER_CST | |
929769f4 JQ |
1033 | @findex tree_int_cst_lt |
1034 | @findex tree_int_cst_equal | |
807e902e KZ |
1035 | @tindex tree_fits_uhwi_p |
1036 | @tindex tree_fits_shwi_p | |
1037 | @tindex tree_to_uhwi | |
1038 | @tindex tree_to_shwi | |
1039 | @tindex TREE_INT_CST_NUNITS | |
1040 | @tindex TREE_INT_CST_ELT | |
1041 | @tindex TREE_INT_CST_LOW | |
929769f4 JQ |
1042 | @tindex REAL_CST |
1043 | @tindex FIXED_CST | |
1044 | @tindex COMPLEX_CST | |
1045 | @tindex VECTOR_CST | |
1046 | @tindex STRING_CST | |
36fd6408 | 1047 | @tindex POLY_INT_CST |
929769f4 JQ |
1048 | @findex TREE_STRING_LENGTH |
1049 | @findex TREE_STRING_POINTER | |
1050 | ||
1051 | The table below begins with constants, moves on to unary expressions, | |
1052 | then proceeds to binary expressions, and concludes with various other | |
1053 | kinds of expressions: | |
1054 | ||
1055 | @table @code | |
1056 | @item INTEGER_CST | |
1057 | These nodes represent integer constants. Note that the type of these | |
1058 | constants is obtained with @code{TREE_TYPE}; they are not always of type | |
1059 | @code{int}. In particular, @code{char} constants are represented with | |
1060 | @code{INTEGER_CST} nodes. The value of the integer constant @code{e} is | |
807e902e KZ |
1061 | represented in an array of HOST_WIDE_INT. There are enough elements |
1062 | in the array to represent the value without taking extra elements for | |
1063 | redundant 0s or -1. The number of elements used to represent @code{e} | |
1064 | is available via @code{TREE_INT_CST_NUNITS}. Element @code{i} can be | |
1065 | extracted by using @code{TREE_INT_CST_ELT (e, i)}. | |
1066 | @code{TREE_INT_CST_LOW} is a shorthand for @code{TREE_INT_CST_ELT (e, 0)}. | |
1067 | ||
1068 | The functions @code{tree_fits_shwi_p} and @code{tree_fits_uhwi_p} | |
1069 | can be used to tell if the value is small enough to fit in a | |
1070 | signed HOST_WIDE_INT or an unsigned HOST_WIDE_INT respectively. | |
1071 | The value can then be extracted using @code{tree_to_shwi} and | |
1072 | @code{tree_to_uhwi}. | |
929769f4 JQ |
1073 | |
1074 | @item REAL_CST | |
1075 | ||
1076 | FIXME: Talk about how to obtain representations of this constant, do | |
1077 | comparisons, and so forth. | |
1078 | ||
1079 | @item FIXED_CST | |
1080 | ||
1081 | These nodes represent fixed-point constants. The type of these constants | |
1082 | is obtained with @code{TREE_TYPE}. @code{TREE_FIXED_CST_PTR} points to | |
1083 | a @code{struct fixed_value}; @code{TREE_FIXED_CST} returns the structure | |
1084 | itself. @code{struct fixed_value} contains @code{data} with the size of two | |
1085 | @code{HOST_BITS_PER_WIDE_INT} and @code{mode} as the associated fixed-point | |
1086 | machine mode for @code{data}. | |
1087 | ||
1088 | @item COMPLEX_CST | |
1089 | These nodes are used to represent complex number constants, that is a | |
1090 | @code{__complex__} whose parts are constant nodes. The | |
1091 | @code{TREE_REALPART} and @code{TREE_IMAGPART} return the real and the | |
1092 | imaginary parts respectively. | |
1093 | ||
1094 | @item VECTOR_CST | |
734914b6 RS |
1095 | These nodes are used to represent vector constants. Each vector |
1096 | constant @var{v} is treated as a specific instance of an arbitrary-length | |
1097 | sequence that itself contains @samp{VECTOR_CST_NPATTERNS (@var{v})} | |
1098 | interleaved patterns. Each pattern has the form: | |
1099 | ||
1100 | @smallexample | |
1101 | @{ @var{base0}, @var{base1}, @var{base1} + @var{step}, @var{base1} + @var{step} * 2, @dots{} @} | |
1102 | @end smallexample | |
1103 | ||
1104 | The first three elements in each pattern are enough to determine the | |
1105 | values of the other elements. However, if all @var{step}s are zero, | |
1106 | only the first two elements are needed. If in addition each @var{base1} | |
1107 | is equal to the corresponding @var{base0}, only the first element in | |
1108 | each pattern is needed. The number of encoded elements per pattern | |
1109 | is given by @samp{VECTOR_CST_NELTS_PER_PATTERN (@var{v})}. | |
1110 | ||
1111 | For example, the constant: | |
1112 | ||
1113 | @smallexample | |
1114 | @{ 0, 1, 2, 6, 3, 8, 4, 10, 5, 12, 6, 14, 7, 16, 8, 18 @} | |
1115 | @end smallexample | |
1116 | ||
1117 | is interpreted as an interleaving of the sequences: | |
1118 | ||
1119 | @smallexample | |
1120 | @{ 0, 2, 3, 4, 5, 6, 7, 8 @} | |
1121 | @{ 1, 6, 8, 10, 12, 14, 16, 18 @} | |
1122 | @end smallexample | |
1123 | ||
1124 | where the sequences are represented by the following patterns: | |
1125 | ||
1126 | @smallexample | |
1127 | @var{base0} == 0, @var{base1} == 2, @var{step} == 1 | |
1128 | @var{base0} == 1, @var{base1} == 6, @var{step} == 2 | |
1129 | @end smallexample | |
1130 | ||
1131 | In this case: | |
1132 | ||
1133 | @smallexample | |
1134 | VECTOR_CST_NPATTERNS (@var{v}) == 2 | |
1135 | VECTOR_CST_NELTS_PER_PATTERN (@var{v}) == 3 | |
1136 | @end smallexample | |
1137 | ||
1138 | The vector is therefore encoded using the first 6 elements | |
1139 | (@samp{@{ 0, 1, 2, 6, 3, 8 @}}), with the remaining 10 elements | |
1140 | being implicit extensions of them. | |
1141 | ||
1142 | Sometimes this scheme can create two possible encodings of the same | |
1143 | vector. For example @{ 0, 1 @} could be seen as two patterns with | |
1144 | one element each or one pattern with two elements (@var{base0} and | |
1145 | @var{base1}). The canonical encoding is always the one with the | |
1146 | fewest patterns or (if both encodings have the same number of | |
1147 | petterns) the one with the fewest encoded elements. | |
1148 | ||
1149 | @samp{vector_cst_encoding_nelts (@var{v})} gives the total number of | |
1150 | encoded elements in @var{v}, which is 6 in the example above. | |
1151 | @code{VECTOR_CST_ENCODED_ELTS (@var{v})} gives a pointer to the elements | |
1152 | encoded in @var{v} and @code{VECTOR_CST_ENCODED_ELT (@var{v}, @var{i})} | |
1153 | accesses the value of encoded element @var{i}. | |
1154 | ||
1155 | @samp{VECTOR_CST_DUPLICATE_P (@var{v})} is true if @var{v} simply contains | |
1156 | repeated instances of @samp{VECTOR_CST_NPATTERNS (@var{v})} values. This is | |
1157 | a shorthand for testing @samp{VECTOR_CST_NELTS_PER_PATTERN (@var{v}) == 1}. | |
1158 | ||
1159 | @samp{VECTOR_CST_STEPPED_P (@var{v})} is true if at least one | |
1160 | pattern in @var{v} has a nonzero step. This is a shorthand for | |
1161 | testing @samp{VECTOR_CST_NELTS_PER_PATTERN (@var{v}) == 3}. | |
1162 | ||
1163 | The utility function @code{vector_cst_elt} gives the value of an | |
1164 | arbitrary index as a @code{tree}. @code{vector_cst_int_elt} gives | |
1165 | the same value as a @code{wide_int}. | |
929769f4 JQ |
1166 | |
1167 | @item STRING_CST | |
1168 | These nodes represent string-constants. The @code{TREE_STRING_LENGTH} | |
1169 | returns the length of the string, as an @code{int}. The | |
1170 | @code{TREE_STRING_POINTER} is a @code{char*} containing the string | |
1171 | itself. The string may not be @code{NUL}-terminated, and it may contain | |
1172 | embedded @code{NUL} characters. Therefore, the | |
1173 | @code{TREE_STRING_LENGTH} includes the trailing @code{NUL} if it is | |
1174 | present. | |
1175 | ||
1176 | For wide string constants, the @code{TREE_STRING_LENGTH} is the number | |
1177 | of bytes in the string, and the @code{TREE_STRING_POINTER} | |
1178 | points to an array of the bytes of the string, as represented on the | |
1179 | target system (that is, as integers in the target endianness). Wide and | |
1180 | non-wide string constants are distinguished only by the @code{TREE_TYPE} | |
1181 | of the @code{STRING_CST}. | |
1182 | ||
1183 | FIXME: The formats of string constants are not well-defined when the | |
1184 | target system bytes are not the same width as host system bytes. | |
1185 | ||
36fd6408 RS |
1186 | @item POLY_INT_CST |
1187 | These nodes represent invariants that depend on some target-specific | |
1188 | runtime parameters. They consist of @code{NUM_POLY_INT_COEFFS} | |
1189 | coefficients, with the first coefficient being the constant term and | |
1190 | the others being multipliers that are applied to the runtime parameters. | |
1191 | ||
1192 | @code{POLY_INT_CST_ELT (@var{x}, @var{i})} references coefficient number | |
1193 | @var{i} of @code{POLY_INT_CST} node @var{x}. Each coefficient is an | |
1194 | @code{INTEGER_CST}. | |
1195 | ||
929769f4 JQ |
1196 | @end table |
1197 | ||
1198 | @node Storage References | |
1199 | @subsection References to storage | |
1200 | @tindex ADDR_EXPR | |
1201 | @tindex INDIRECT_REF | |
70f34814 | 1202 | @tindex MEM_REF |
929769f4 JQ |
1203 | @tindex ARRAY_REF |
1204 | @tindex ARRAY_RANGE_REF | |
1205 | @tindex TARGET_MEM_REF | |
1206 | @tindex COMPONENT_REF | |
1207 | ||
1208 | @table @code | |
1209 | @item ARRAY_REF | |
1210 | These nodes represent array accesses. The first operand is the array; | |
1211 | the second is the index. To calculate the address of the memory | |
1212 | accessed, you must scale the index by the size of the type of the array | |
1213 | elements. The type of these expressions must be the type of a component of | |
1214 | the array. The third and fourth operands are used after gimplification | |
1215 | to represent the lower bound and component size but should not be used | |
1216 | directly; call @code{array_ref_low_bound} and @code{array_ref_element_size} | |
1217 | instead. | |
1218 | ||
1219 | @item ARRAY_RANGE_REF | |
1220 | These nodes represent access to a range (or ``slice'') of an array. The | |
1221 | operands are the same as that for @code{ARRAY_REF} and have the same | |
1222 | meanings. The type of these expressions must be an array whose component | |
1223 | type is the same as that of the first operand. The range of that array | |
1224 | type determines the amount of data these expressions access. | |
1225 | ||
d0d428c4 RB |
1226 | @item COMPONENT_REF |
1227 | These nodes represent non-static data member accesses. The first | |
1228 | operand is the object (rather than a pointer to it); the second operand | |
1229 | is the @code{FIELD_DECL} for the data member. The third operand represents | |
1230 | the byte offset of the field, but should not be used directly; call | |
1231 | @code{component_ref_field_offset} instead. | |
929769f4 JQ |
1232 | |
1233 | @item ADDR_EXPR | |
1234 | These nodes are used to represent the address of an object. (These | |
1235 | expressions will always have pointer or reference type.) The operand may | |
1236 | be another expression, or it may be a declaration. | |
1237 | ||
1238 | As an extension, GCC allows users to take the address of a label. In | |
1239 | this case, the operand of the @code{ADDR_EXPR} will be a | |
1240 | @code{LABEL_DECL}. The type of such an expression is @code{void*}. | |
1241 | ||
1242 | If the object addressed is not an lvalue, a temporary is created, and | |
1243 | the address of the temporary is used. | |
1244 | ||
1245 | @item INDIRECT_REF | |
1246 | These nodes are used to represent the object pointed to by a pointer. | |
1247 | The operand is the pointer being dereferenced; it will always have | |
1248 | pointer or reference type. | |
1249 | ||
70f34814 RG |
1250 | @item MEM_REF |
1251 | These nodes are used to represent the object pointed to by a pointer | |
1252 | offset by a constant. | |
1253 | The first operand is the pointer being dereferenced; it will always have | |
d0d428c4 RB |
1254 | pointer or reference type. The second operand is a pointer constant |
1255 | serving as constant offset applied to the pointer being dereferenced | |
1256 | with its type specifying the type to be used for type-based alias analysis. | |
1257 | The type of the node specifies the alignment of the access. | |
70f34814 | 1258 | |
d0d428c4 RB |
1259 | @item TARGET_MEM_REF |
1260 | These nodes represent memory accesses whose address directly map to | |
1261 | an addressing mode of the target architecture. The first argument | |
1262 | is @code{TMR_BASE} and is a pointer to the object being accessed. | |
1263 | The second argument is @code{TMR_OFFSET} which is a pointer constant | |
1264 | with dual purpose serving both as constant offset and holder of | |
1265 | the type used for type-based alias analysis. The first two operands | |
1266 | have exactly the same semantics as @code{MEM_REF}. The third | |
1267 | and fourth operand are @code{TMR_INDEX} and @code{TMR_STEP} where | |
1268 | the former is an integer and the latter an integer constant. The | |
1269 | fifth and last operand is @code{TMR_INDEX2} which is an alternate | |
1270 | non-constant offset. Any of the third to last operands may be | |
1271 | @code{NULL} if the corresponding component does not appear in | |
1272 | the address, but @code{TMR_INDEX} and @code{TMR_STEP} shall be | |
1273 | always supplied in pair. The Address of the @code{TARGET_MEM_REF} | |
1274 | is determined in the following way. | |
1275 | ||
1276 | @smallexample | |
1277 | TMR_BASE + TMR_OFFSET + TMR_INDEX * TMR_STEP + TMR_INDEX2 | |
1278 | @end smallexample | |
929769f4 | 1279 | |
d0d428c4 | 1280 | The type of the node specifies the alignment of the access. |
929769f4 JQ |
1281 | |
1282 | @end table | |
1283 | ||
1284 | @node Unary and Binary Expressions | |
1285 | @subsection Unary and Binary Expressions | |
1286 | @tindex NEGATE_EXPR | |
1287 | @tindex ABS_EXPR | |
64f7ea7c | 1288 | @tindex ABSU_EXPR |
929769f4 JQ |
1289 | @tindex BIT_NOT_EXPR |
1290 | @tindex TRUTH_NOT_EXPR | |
1291 | @tindex PREDECREMENT_EXPR | |
1292 | @tindex PREINCREMENT_EXPR | |
1293 | @tindex POSTDECREMENT_EXPR | |
1294 | @tindex POSTINCREMENT_EXPR | |
1295 | @tindex FIX_TRUNC_EXPR | |
1296 | @tindex FLOAT_EXPR | |
1297 | @tindex COMPLEX_EXPR | |
1298 | @tindex CONJ_EXPR | |
1299 | @tindex REALPART_EXPR | |
1300 | @tindex IMAGPART_EXPR | |
1301 | @tindex NON_LVALUE_EXPR | |
1302 | @tindex NOP_EXPR | |
1303 | @tindex CONVERT_EXPR | |
1304 | @tindex FIXED_CONVERT_EXPR | |
1305 | @tindex THROW_EXPR | |
1306 | @tindex LSHIFT_EXPR | |
1307 | @tindex RSHIFT_EXPR | |
1308 | @tindex BIT_IOR_EXPR | |
1309 | @tindex BIT_XOR_EXPR | |
1310 | @tindex BIT_AND_EXPR | |
1311 | @tindex TRUTH_ANDIF_EXPR | |
1312 | @tindex TRUTH_ORIF_EXPR | |
1313 | @tindex TRUTH_AND_EXPR | |
1314 | @tindex TRUTH_OR_EXPR | |
1315 | @tindex TRUTH_XOR_EXPR | |
1316 | @tindex POINTER_PLUS_EXPR | |
1af4ebf5 | 1317 | @tindex POINTER_DIFF_EXPR |
929769f4 JQ |
1318 | @tindex PLUS_EXPR |
1319 | @tindex MINUS_EXPR | |
1320 | @tindex MULT_EXPR | |
99651574 | 1321 | @tindex MULT_HIGHPART_EXPR |
929769f4 JQ |
1322 | @tindex RDIV_EXPR |
1323 | @tindex TRUNC_DIV_EXPR | |
1324 | @tindex FLOOR_DIV_EXPR | |
1325 | @tindex CEIL_DIV_EXPR | |
1326 | @tindex ROUND_DIV_EXPR | |
1327 | @tindex TRUNC_MOD_EXPR | |
1328 | @tindex FLOOR_MOD_EXPR | |
1329 | @tindex CEIL_MOD_EXPR | |
1330 | @tindex ROUND_MOD_EXPR | |
1331 | @tindex EXACT_DIV_EXPR | |
1332 | @tindex LT_EXPR | |
1333 | @tindex LE_EXPR | |
1334 | @tindex GT_EXPR | |
1335 | @tindex GE_EXPR | |
1336 | @tindex EQ_EXPR | |
1337 | @tindex NE_EXPR | |
1338 | @tindex ORDERED_EXPR | |
1339 | @tindex UNORDERED_EXPR | |
1340 | @tindex UNLT_EXPR | |
1341 | @tindex UNLE_EXPR | |
1342 | @tindex UNGT_EXPR | |
1343 | @tindex UNGE_EXPR | |
1344 | @tindex UNEQ_EXPR | |
1345 | @tindex LTGT_EXPR | |
1346 | @tindex MODIFY_EXPR | |
1347 | @tindex INIT_EXPR | |
1348 | @tindex COMPOUND_EXPR | |
1349 | @tindex COND_EXPR | |
1350 | @tindex CALL_EXPR | |
1351 | @tindex STMT_EXPR | |
1352 | @tindex BIND_EXPR | |
1353 | @tindex LOOP_EXPR | |
1354 | @tindex EXIT_EXPR | |
1355 | @tindex CLEANUP_POINT_EXPR | |
1356 | @tindex CONSTRUCTOR | |
1357 | @tindex COMPOUND_LITERAL_EXPR | |
1358 | @tindex SAVE_EXPR | |
1359 | @tindex TARGET_EXPR | |
1360 | @tindex VA_ARG_EXPR | |
8170608b | 1361 | @tindex ANNOTATE_EXPR |
929769f4 JQ |
1362 | |
1363 | @table @code | |
1364 | @item NEGATE_EXPR | |
1365 | These nodes represent unary negation of the single operand, for both | |
1366 | integer and floating-point types. The type of negation can be | |
1367 | determined by looking at the type of the expression. | |
1368 | ||
1369 | The behavior of this operation on signed arithmetic overflow is | |
1370 | controlled by the @code{flag_wrapv} and @code{flag_trapv} variables. | |
1371 | ||
1372 | @item ABS_EXPR | |
1373 | These nodes represent the absolute value of the single operand, for | |
1374 | both integer and floating-point types. This is typically used to | |
1375 | implement the @code{abs}, @code{labs} and @code{llabs} builtins for | |
1376 | integer types, and the @code{fabs}, @code{fabsf} and @code{fabsl} | |
1377 | builtins for floating point types. The type of abs operation can | |
1378 | be determined by looking at the type of the expression. | |
1379 | ||
1380 | This node is not used for complex types. To represent the modulus | |
1381 | or complex abs of a complex value, use the @code{BUILT_IN_CABS}, | |
1382 | @code{BUILT_IN_CABSF} or @code{BUILT_IN_CABSL} builtins, as used | |
1383 | to implement the C99 @code{cabs}, @code{cabsf} and @code{cabsl} | |
1384 | built-in functions. | |
1385 | ||
64f7ea7c KV |
1386 | @item ABSU_EXPR |
1387 | These nodes represent the absolute value of the single operand in | |
8498adc2 GP |
1388 | equivalent unsigned type such that @code{ABSU_EXPR} of @code{TYPE_MIN} |
1389 | is well defined. | |
64f7ea7c | 1390 | |
929769f4 JQ |
1391 | @item BIT_NOT_EXPR |
1392 | These nodes represent bitwise complement, and will always have integral | |
1393 | type. The only operand is the value to be complemented. | |
1394 | ||
1395 | @item TRUTH_NOT_EXPR | |
1396 | These nodes represent logical negation, and will always have integral | |
1397 | (or boolean) type. The operand is the value being negated. The type | |
1398 | of the operand and that of the result are always of @code{BOOLEAN_TYPE} | |
1399 | or @code{INTEGER_TYPE}. | |
1400 | ||
1401 | @item PREDECREMENT_EXPR | |
1402 | @itemx PREINCREMENT_EXPR | |
1403 | @itemx POSTDECREMENT_EXPR | |
1404 | @itemx POSTINCREMENT_EXPR | |
1405 | These nodes represent increment and decrement expressions. The value of | |
1406 | the single operand is computed, and the operand incremented or | |
1407 | decremented. In the case of @code{PREDECREMENT_EXPR} and | |
1408 | @code{PREINCREMENT_EXPR}, the value of the expression is the value | |
1409 | resulting after the increment or decrement; in the case of | |
1410 | @code{POSTDECREMENT_EXPR} and @code{POSTINCREMENT_EXPR} is the value | |
1411 | before the increment or decrement occurs. The type of the operand, like | |
1412 | that of the result, will be either integral, boolean, or floating-point. | |
1413 | ||
1414 | @item FIX_TRUNC_EXPR | |
1415 | These nodes represent conversion of a floating-point value to an | |
1416 | integer. The single operand will have a floating-point type, while | |
1417 | the complete expression will have an integral (or boolean) type. The | |
1418 | operand is rounded towards zero. | |
1419 | ||
1420 | @item FLOAT_EXPR | |
1421 | These nodes represent conversion of an integral (or boolean) value to a | |
1422 | floating-point value. The single operand will have integral type, while | |
1423 | the complete expression will have a floating-point type. | |
1424 | ||
1425 | FIXME: How is the operand supposed to be rounded? Is this dependent on | |
1426 | @option{-mieee}? | |
1427 | ||
1428 | @item COMPLEX_EXPR | |
1429 | These nodes are used to represent complex numbers constructed from two | |
1430 | expressions of the same (integer or real) type. The first operand is the | |
1431 | real part and the second operand is the imaginary part. | |
1432 | ||
1433 | @item CONJ_EXPR | |
1434 | These nodes represent the conjugate of their operand. | |
1435 | ||
1436 | @item REALPART_EXPR | |
1437 | @itemx IMAGPART_EXPR | |
1438 | These nodes represent respectively the real and the imaginary parts | |
1439 | of complex numbers (their sole argument). | |
1440 | ||
1441 | @item NON_LVALUE_EXPR | |
1442 | These nodes indicate that their one and only operand is not an lvalue. | |
1443 | A back end can treat these identically to the single operand. | |
1444 | ||
1445 | @item NOP_EXPR | |
1446 | These nodes are used to represent conversions that do not require any | |
1447 | code-generation. For example, conversion of a @code{char*} to an | |
1448 | @code{int*} does not require any code be generated; such a conversion is | |
1449 | represented by a @code{NOP_EXPR}. The single operand is the expression | |
1450 | to be converted. The conversion from a pointer to a reference is also | |
1451 | represented with a @code{NOP_EXPR}. | |
1452 | ||
1453 | @item CONVERT_EXPR | |
1454 | These nodes are similar to @code{NOP_EXPR}s, but are used in those | |
1455 | situations where code may need to be generated. For example, if an | |
1456 | @code{int*} is converted to an @code{int} code may need to be generated | |
1457 | on some platforms. These nodes are never used for C++-specific | |
1458 | conversions, like conversions between pointers to different classes in | |
1459 | an inheritance hierarchy. Any adjustments that need to be made in such | |
1460 | cases are always indicated explicitly. Similarly, a user-defined | |
1461 | conversion is never represented by a @code{CONVERT_EXPR}; instead, the | |
1462 | function calls are made explicit. | |
1463 | ||
1464 | @item FIXED_CONVERT_EXPR | |
1465 | These nodes are used to represent conversions that involve fixed-point | |
1466 | values. For example, from a fixed-point value to another fixed-point value, | |
1467 | from an integer to a fixed-point value, from a fixed-point value to an | |
1468 | integer, from a floating-point value to a fixed-point value, or from | |
1469 | a fixed-point value to a floating-point value. | |
1470 | ||
1471 | @item LSHIFT_EXPR | |
1472 | @itemx RSHIFT_EXPR | |
1473 | These nodes represent left and right shifts, respectively. The first | |
1474 | operand is the value to shift; it will always be of integral type. The | |
1475 | second operand is an expression for the number of bits by which to | |
1476 | shift. Right shift should be treated as arithmetic, i.e., the | |
1477 | high-order bits should be zero-filled when the expression has unsigned | |
1478 | type and filled with the sign bit when the expression has signed type. | |
1479 | Note that the result is undefined if the second operand is larger | |
0fdce875 MG |
1480 | than or equal to the first operand's type size. Unlike most nodes, these |
1481 | can have a vector as first operand and a scalar as second operand. | |
929769f4 JQ |
1482 | |
1483 | ||
1484 | @item BIT_IOR_EXPR | |
1485 | @itemx BIT_XOR_EXPR | |
1486 | @itemx BIT_AND_EXPR | |
1487 | These nodes represent bitwise inclusive or, bitwise exclusive or, and | |
1488 | bitwise and, respectively. Both operands will always have integral | |
1489 | type. | |
1490 | ||
1491 | @item TRUTH_ANDIF_EXPR | |
1492 | @itemx TRUTH_ORIF_EXPR | |
1493 | These nodes represent logical ``and'' and logical ``or'', respectively. | |
1494 | These operators are not strict; i.e., the second operand is evaluated | |
1495 | only if the value of the expression is not determined by evaluation of | |
1496 | the first operand. The type of the operands and that of the result are | |
1497 | always of @code{BOOLEAN_TYPE} or @code{INTEGER_TYPE}. | |
1498 | ||
1499 | @item TRUTH_AND_EXPR | |
1500 | @itemx TRUTH_OR_EXPR | |
1501 | @itemx TRUTH_XOR_EXPR | |
1502 | These nodes represent logical and, logical or, and logical exclusive or. | |
1503 | They are strict; both arguments are always evaluated. There are no | |
1504 | corresponding operators in C or C++, but the front end will sometimes | |
1505 | generate these expressions anyhow, if it can tell that strictness does | |
1506 | not matter. The type of the operands and that of the result are | |
1507 | always of @code{BOOLEAN_TYPE} or @code{INTEGER_TYPE}. | |
1508 | ||
f457c50c | 1509 | @item POINTER_PLUS_EXPR |
929769f4 JQ |
1510 | This node represents pointer arithmetic. The first operand is always |
1511 | a pointer/reference type. The second operand is always an unsigned | |
1af4ebf5 MG |
1512 | integer type compatible with sizetype. This and POINTER_DIFF_EXPR are |
1513 | the only binary arithmetic operators that can operate on pointer types. | |
1514 | ||
1515 | @item POINTER_DIFF_EXPR | |
1516 | This node represents pointer subtraction. The two operands always | |
1517 | have pointer/reference type. It returns a signed integer of the same | |
1518 | precision as the pointers. The behavior is undefined if the difference | |
1519 | of the two pointers, seen as infinite precision non-negative integers, | |
1520 | does not fit in the result type. The result does not depend on the | |
1521 | pointer type, it is not divided by the size of the pointed-to type. | |
929769f4 | 1522 | |
f457c50c | 1523 | @item PLUS_EXPR |
929769f4 JQ |
1524 | @itemx MINUS_EXPR |
1525 | @itemx MULT_EXPR | |
1526 | These nodes represent various binary arithmetic operations. | |
1527 | Respectively, these operations are addition, subtraction (of the second | |
1528 | operand from the first) and multiplication. Their operands may have | |
1529 | either integral or floating type, but there will never be case in which | |
1530 | one operand is of floating type and the other is of integral type. | |
1531 | ||
1532 | The behavior of these operations on signed arithmetic overflow is | |
1533 | controlled by the @code{flag_wrapv} and @code{flag_trapv} variables. | |
1534 | ||
99651574 RH |
1535 | @item MULT_HIGHPART_EXPR |
1536 | This node represents the ``high-part'' of a widening multiplication. | |
1537 | For an integral type with @var{b} bits of precision, the result is | |
1538 | the most significant @var{b} bits of the full @math{2@var{b}} product. | |
1539 | ||
929769f4 JQ |
1540 | @item RDIV_EXPR |
1541 | This node represents a floating point division operation. | |
1542 | ||
1543 | @item TRUNC_DIV_EXPR | |
1544 | @itemx FLOOR_DIV_EXPR | |
1545 | @itemx CEIL_DIV_EXPR | |
1546 | @itemx ROUND_DIV_EXPR | |
1547 | These nodes represent integer division operations that return an integer | |
1548 | result. @code{TRUNC_DIV_EXPR} rounds towards zero, @code{FLOOR_DIV_EXPR} | |
1549 | rounds towards negative infinity, @code{CEIL_DIV_EXPR} rounds towards | |
1550 | positive infinity and @code{ROUND_DIV_EXPR} rounds to the closest integer. | |
1551 | Integer division in C and C++ is truncating, i.e.@: @code{TRUNC_DIV_EXPR}. | |
1552 | ||
1553 | The behavior of these operations on signed arithmetic overflow, when | |
1554 | dividing the minimum signed integer by minus one, is controlled by the | |
1555 | @code{flag_wrapv} and @code{flag_trapv} variables. | |
1556 | ||
1557 | @item TRUNC_MOD_EXPR | |
1558 | @itemx FLOOR_MOD_EXPR | |
1559 | @itemx CEIL_MOD_EXPR | |
1560 | @itemx ROUND_MOD_EXPR | |
1561 | These nodes represent the integer remainder or modulus operation. | |
1562 | The integer modulus of two operands @code{a} and @code{b} is | |
1563 | defined as @code{a - (a/b)*b} where the division calculated using | |
1564 | the corresponding division operator. Hence for @code{TRUNC_MOD_EXPR} | |
1565 | this definition assumes division using truncation towards zero, i.e.@: | |
1566 | @code{TRUNC_DIV_EXPR}. Integer remainder in C and C++ uses truncating | |
1567 | division, i.e.@: @code{TRUNC_MOD_EXPR}. | |
1568 | ||
1569 | @item EXACT_DIV_EXPR | |
1570 | The @code{EXACT_DIV_EXPR} code is used to represent integer divisions where | |
1571 | the numerator is known to be an exact multiple of the denominator. This | |
1572 | allows the backend to choose between the faster of @code{TRUNC_DIV_EXPR}, | |
1573 | @code{CEIL_DIV_EXPR} and @code{FLOOR_DIV_EXPR} for the current target. | |
1574 | ||
1575 | @item LT_EXPR | |
1576 | @itemx LE_EXPR | |
1577 | @itemx GT_EXPR | |
1578 | @itemx GE_EXPR | |
000a5f8d | 1579 | @itemx LTGT_EXPR |
929769f4 JQ |
1580 | @itemx EQ_EXPR |
1581 | @itemx NE_EXPR | |
000a5f8d EB |
1582 | These nodes represent the less than, less than or equal to, greater than, |
1583 | greater than or equal to, less or greater than, equal, and not equal | |
1584 | comparison operators. The first and second operands will either be both | |
1585 | of integral type, both of floating type or both of vector type, except for | |
1586 | LTGT_EXPR where they will only be both of floating type. The result type | |
1587 | of these expressions will always be of integral, boolean or signed integral | |
1588 | vector type. These operations return the result type's zero value for false, | |
1589 | the result type's one value for true, and a vector whose elements are zero | |
1590 | (false) or minus one (true) for vectors. | |
929769f4 JQ |
1591 | |
1592 | For floating point comparisons, if we honor IEEE NaNs and either operand | |
1593 | is NaN, then @code{NE_EXPR} always returns true and the remaining operators | |
1594 | always return false. On some targets, comparisons against an IEEE NaN, | |
000a5f8d | 1595 | other than equality and inequality, may generate a floating-point exception. |
929769f4 JQ |
1596 | |
1597 | @item ORDERED_EXPR | |
1598 | @itemx UNORDERED_EXPR | |
1599 | These nodes represent non-trapping ordered and unordered comparison | |
1600 | operators. These operations take two floating point operands and | |
1601 | determine whether they are ordered or unordered relative to each other. | |
1602 | If either operand is an IEEE NaN, their comparison is defined to be | |
1603 | unordered, otherwise the comparison is defined to be ordered. The | |
1604 | result type of these expressions will always be of integral or boolean | |
1605 | type. These operations return the result type's zero value for false, | |
1606 | and the result type's one value for true. | |
1607 | ||
1608 | @item UNLT_EXPR | |
1609 | @itemx UNLE_EXPR | |
1610 | @itemx UNGT_EXPR | |
1611 | @itemx UNGE_EXPR | |
1612 | @itemx UNEQ_EXPR | |
929769f4 JQ |
1613 | These nodes represent the unordered comparison operators. |
1614 | These operations take two floating point operands and determine whether | |
1615 | the operands are unordered or are less than, less than or equal to, | |
1616 | greater than, greater than or equal to, or equal respectively. For | |
1617 | example, @code{UNLT_EXPR} returns true if either operand is an IEEE | |
000a5f8d EB |
1618 | NaN or the first operand is less than the second. All these operations |
1619 | are guaranteed not to generate a floating point exception. The result | |
929769f4 JQ |
1620 | type of these expressions will always be of integral or boolean type. |
1621 | These operations return the result type's zero value for false, | |
1622 | and the result type's one value for true. | |
1623 | ||
1624 | @item MODIFY_EXPR | |
1625 | These nodes represent assignment. The left-hand side is the first | |
1626 | operand; the right-hand side is the second operand. The left-hand side | |
1627 | will be a @code{VAR_DECL}, @code{INDIRECT_REF}, @code{COMPONENT_REF}, or | |
1628 | other lvalue. | |
1629 | ||
1630 | These nodes are used to represent not only assignment with @samp{=} but | |
1631 | also compound assignments (like @samp{+=}), by reduction to @samp{=} | |
1632 | assignment. In other words, the representation for @samp{i += 3} looks | |
1633 | just like that for @samp{i = i + 3}. | |
1634 | ||
1635 | @item INIT_EXPR | |
1636 | These nodes are just like @code{MODIFY_EXPR}, but are used only when a | |
1637 | variable is initialized, rather than assigned to subsequently. This | |
1638 | means that we can assume that the target of the initialization is not | |
1639 | used in computing its own value; any reference to the lhs in computing | |
1640 | the rhs is undefined. | |
1641 | ||
1642 | @item COMPOUND_EXPR | |
1643 | These nodes represent comma-expressions. The first operand is an | |
1644 | expression whose value is computed and thrown away prior to the | |
1645 | evaluation of the second operand. The value of the entire expression is | |
1646 | the value of the second operand. | |
1647 | ||
1648 | @item COND_EXPR | |
1649 | These nodes represent @code{?:} expressions. The first operand | |
1650 | is of boolean or integral type. If it evaluates to a nonzero value, | |
1651 | the second operand should be evaluated, and returned as the value of the | |
1652 | expression. Otherwise, the third operand is evaluated, and returned as | |
1653 | the value of the expression. | |
1654 | ||
1655 | The second operand must have the same type as the entire expression, | |
1656 | unless it unconditionally throws an exception or calls a noreturn | |
1657 | function, in which case it should have void type. The same constraints | |
1658 | apply to the third operand. This allows array bounds checks to be | |
1659 | represented conveniently as @code{(i >= 0 && i < 10) ? i : abort()}. | |
1660 | ||
1661 | As a GNU extension, the C language front-ends allow the second | |
1662 | operand of the @code{?:} operator may be omitted in the source. | |
1663 | For example, @code{x ? : 3} is equivalent to @code{x ? x : 3}, | |
df18c24a | 1664 | assuming that @code{x} is an expression without side effects. |
929769f4 JQ |
1665 | In the tree representation, however, the second operand is always |
1666 | present, possibly protected by @code{SAVE_EXPR} if the first | |
df18c24a | 1667 | argument does cause side effects. |
929769f4 JQ |
1668 | |
1669 | @item CALL_EXPR | |
1670 | These nodes are used to represent calls to functions, including | |
1671 | non-static member functions. @code{CALL_EXPR}s are implemented as | |
1672 | expression nodes with a variable number of operands. Rather than using | |
1673 | @code{TREE_OPERAND} to extract them, it is preferable to use the | |
1674 | specialized accessor macros and functions that operate specifically on | |
1675 | @code{CALL_EXPR} nodes. | |
1676 | ||
1677 | @code{CALL_EXPR_FN} returns a pointer to the | |
1678 | function to call; it is always an expression whose type is a | |
1679 | @code{POINTER_TYPE}. | |
1680 | ||
1681 | The number of arguments to the call is returned by @code{call_expr_nargs}, | |
ff2ce160 MS |
1682 | while the arguments themselves can be accessed with the @code{CALL_EXPR_ARG} |
1683 | macro. The arguments are zero-indexed and numbered left-to-right. | |
929769f4 JQ |
1684 | You can iterate over the arguments using @code{FOR_EACH_CALL_EXPR_ARG}, as in: |
1685 | ||
1686 | @smallexample | |
1687 | tree call, arg; | |
1688 | call_expr_arg_iterator iter; | |
1689 | FOR_EACH_CALL_EXPR_ARG (arg, iter, call) | |
1690 | /* arg is bound to successive arguments of call. */ | |
1691 | @dots{}; | |
1692 | @end smallexample | |
1693 | ||
1694 | For non-static | |
1695 | member functions, there will be an operand corresponding to the | |
1696 | @code{this} pointer. There will always be expressions corresponding to | |
1697 | all of the arguments, even if the function is declared with default | |
1698 | arguments and some arguments are not explicitly provided at the call | |
1699 | sites. | |
1700 | ||
1701 | @code{CALL_EXPR}s also have a @code{CALL_EXPR_STATIC_CHAIN} operand that | |
1702 | is used to implement nested functions. This operand is otherwise null. | |
1703 | ||
1704 | @item CLEANUP_POINT_EXPR | |
1705 | These nodes represent full-expressions. The single operand is an | |
1706 | expression to evaluate. Any destructor calls engendered by the creation | |
1707 | of temporaries during the evaluation of that expression should be | |
1708 | performed immediately after the expression is evaluated. | |
1709 | ||
1710 | @item CONSTRUCTOR | |
1448093c TG |
1711 | These nodes represent the brace-enclosed initializers for a structure or an |
1712 | array. They contain a sequence of component values made out of a vector of | |
1713 | constructor_elt, which is a (@code{INDEX}, @code{VALUE}) pair. | |
1714 | ||
1715 | If the @code{TREE_TYPE} of the @code{CONSTRUCTOR} is a @code{RECORD_TYPE}, | |
1716 | @code{UNION_TYPE} or @code{QUAL_UNION_TYPE} then the @code{INDEX} of each | |
1717 | node in the sequence will be a @code{FIELD_DECL} and the @code{VALUE} will | |
1718 | be the expression used to initialize that field. | |
1719 | ||
1720 | If the @code{TREE_TYPE} of the @code{CONSTRUCTOR} is an @code{ARRAY_TYPE}, | |
1721 | then the @code{INDEX} of each node in the sequence will be an | |
1722 | @code{INTEGER_CST} or a @code{RANGE_EXPR} of two @code{INTEGER_CST}s. | |
1723 | A single @code{INTEGER_CST} indicates which element of the array is being | |
1724 | assigned to. A @code{RANGE_EXPR} indicates an inclusive range of elements | |
1725 | to initialize. In both cases the @code{VALUE} is the corresponding | |
929769f4 | 1726 | initializer. It is re-evaluated for each element of a |
1448093c | 1727 | @code{RANGE_EXPR}. If the @code{INDEX} is @code{NULL_TREE}, then |
929769f4 JQ |
1728 | the initializer is for the next available array element. |
1729 | ||
1730 | In the front end, you should not depend on the fields appearing in any | |
1731 | particular order. However, in the middle end, fields must appear in | |
1732 | declaration order. You should not assume that all fields will be | |
1448093c TG |
1733 | represented. Unrepresented fields will be cleared (zeroed), unless the |
1734 | CONSTRUCTOR_NO_CLEARING flag is set, in which case their value becomes | |
1735 | undefined. | |
929769f4 JQ |
1736 | |
1737 | @item COMPOUND_LITERAL_EXPR | |
1738 | @findex COMPOUND_LITERAL_EXPR_DECL_EXPR | |
1739 | @findex COMPOUND_LITERAL_EXPR_DECL | |
1740 | These nodes represent ISO C99 compound literals. The | |
1741 | @code{COMPOUND_LITERAL_EXPR_DECL_EXPR} is a @code{DECL_EXPR} | |
1742 | containing an anonymous @code{VAR_DECL} for | |
1743 | the unnamed object represented by the compound literal; the | |
1744 | @code{DECL_INITIAL} of that @code{VAR_DECL} is a @code{CONSTRUCTOR} | |
1745 | representing the brace-enclosed list of initializers in the compound | |
1746 | literal. That anonymous @code{VAR_DECL} can also be accessed directly | |
1747 | by the @code{COMPOUND_LITERAL_EXPR_DECL} macro. | |
1748 | ||
1749 | @item SAVE_EXPR | |
1750 | ||
1751 | A @code{SAVE_EXPR} represents an expression (possibly involving | |
df18c24a | 1752 | side effects) that is used more than once. The side effects should |
929769f4 JQ |
1753 | occur only the first time the expression is evaluated. Subsequent uses |
1754 | should just reuse the computed value. The first operand to the | |
df18c24a | 1755 | @code{SAVE_EXPR} is the expression to evaluate. The side effects should |
929769f4 JQ |
1756 | be executed where the @code{SAVE_EXPR} is first encountered in a |
1757 | depth-first preorder traversal of the expression tree. | |
1758 | ||
1759 | @item TARGET_EXPR | |
1760 | A @code{TARGET_EXPR} represents a temporary object. The first operand | |
1761 | is a @code{VAR_DECL} for the temporary variable. The second operand is | |
1762 | the initializer for the temporary. The initializer is evaluated and, | |
1763 | if non-void, copied (bitwise) into the temporary. If the initializer | |
1764 | is void, that means that it will perform the initialization itself. | |
1765 | ||
1766 | Often, a @code{TARGET_EXPR} occurs on the right-hand side of an | |
1767 | assignment, or as the second operand to a comma-expression which is | |
1768 | itself the right-hand side of an assignment, etc. In this case, we say | |
1769 | that the @code{TARGET_EXPR} is ``normal''; otherwise, we say it is | |
1770 | ``orphaned''. For a normal @code{TARGET_EXPR} the temporary variable | |
1771 | should be treated as an alias for the left-hand side of the assignment, | |
1772 | rather than as a new temporary variable. | |
1773 | ||
1774 | The third operand to the @code{TARGET_EXPR}, if present, is a | |
1775 | cleanup-expression (i.e., destructor call) for the temporary. If this | |
1776 | expression is orphaned, then this expression must be executed when the | |
1777 | statement containing this expression is complete. These cleanups must | |
1778 | always be executed in the order opposite to that in which they were | |
1779 | encountered. Note that if a temporary is created on one branch of a | |
1780 | conditional operator (i.e., in the second or third operand to a | |
1781 | @code{COND_EXPR}), the cleanup must be run only if that branch is | |
1782 | actually executed. | |
1783 | ||
1784 | @item VA_ARG_EXPR | |
1785 | This node is used to implement support for the C/C++ variable argument-list | |
1786 | mechanism. It represents expressions like @code{va_arg (ap, type)}. | |
1787 | Its @code{TREE_TYPE} yields the tree representation for @code{type} and | |
1788 | its sole argument yields the representation for @code{ap}. | |
1789 | ||
8170608b TB |
1790 | @item ANNOTATE_EXPR |
1791 | This node is used to attach markers to an expression. The first operand | |
1792 | is the annotated expression, the second is an @code{INTEGER_CST} with | |
ac9effed | 1793 | a value from @code{enum annot_expr_kind}, the third is an @code{INTEGER_CST}. |
929769f4 JQ |
1794 | @end table |
1795 | ||
8170608b | 1796 | |
929769f4 JQ |
1797 | @node Vectors |
1798 | @subsection Vectors | |
be4c1d4a | 1799 | @tindex VEC_DUPLICATE_EXPR |
9adab579 | 1800 | @tindex VEC_SERIES_EXPR |
929769f4 JQ |
1801 | @tindex VEC_LSHIFT_EXPR |
1802 | @tindex VEC_RSHIFT_EXPR | |
1803 | @tindex VEC_WIDEN_MULT_HI_EXPR | |
1804 | @tindex VEC_WIDEN_MULT_LO_EXPR | |
9fc9573f JH |
1805 | @tindex VEC_WIDEN_PLUS_HI_EXPR |
1806 | @tindex VEC_WIDEN_PLUS_LO_EXPR | |
1807 | @tindex VEC_WIDEN_MINUS_HI_EXPR | |
1808 | @tindex VEC_WIDEN_MINUS_LO_EXPR | |
929769f4 JQ |
1809 | @tindex VEC_UNPACK_HI_EXPR |
1810 | @tindex VEC_UNPACK_LO_EXPR | |
1811 | @tindex VEC_UNPACK_FLOAT_HI_EXPR | |
1812 | @tindex VEC_UNPACK_FLOAT_LO_EXPR | |
1bda738b JJ |
1813 | @tindex VEC_UNPACK_FIX_TRUNC_HI_EXPR |
1814 | @tindex VEC_UNPACK_FIX_TRUNC_LO_EXPR | |
929769f4 JQ |
1815 | @tindex VEC_PACK_TRUNC_EXPR |
1816 | @tindex VEC_PACK_SAT_EXPR | |
1817 | @tindex VEC_PACK_FIX_TRUNC_EXPR | |
1bda738b | 1818 | @tindex VEC_PACK_FLOAT_EXPR |
be4c1d4a | 1819 | @tindex VEC_COND_EXPR |
79d652a5 | 1820 | @tindex SAD_EXPR |
929769f4 JQ |
1821 | |
1822 | @table @code | |
be4c1d4a RS |
1823 | @item VEC_DUPLICATE_EXPR |
1824 | This node has a single operand and represents a vector in which every | |
1825 | element is equal to that operand. | |
1826 | ||
9adab579 RS |
1827 | @item VEC_SERIES_EXPR |
1828 | This node represents a vector formed from a scalar base and step, | |
1829 | given as the first and second operands respectively. Element @var{i} | |
1830 | of the result is equal to @samp{@var{base} + @var{i}*@var{step}}. | |
1831 | ||
1832 | This node is restricted to integral types, in order to avoid | |
1833 | specifying the rounding behavior for floating-point types. | |
1834 | ||
929769f4 JQ |
1835 | @item VEC_LSHIFT_EXPR |
1836 | @itemx VEC_RSHIFT_EXPR | |
ff2ce160 MS |
1837 | These nodes represent whole vector left and right shifts, respectively. |
1838 | The first operand is the vector to shift; it will always be of vector type. | |
929769f4 JQ |
1839 | The second operand is an expression for the number of bits by which to |
1840 | shift. Note that the result is undefined if the second operand is larger | |
1841 | than or equal to the first operand's type size. | |
1842 | ||
1843 | @item VEC_WIDEN_MULT_HI_EXPR | |
1844 | @itemx VEC_WIDEN_MULT_LO_EXPR | |
1845 | These nodes represent widening vector multiplication of the high and low | |
ff2ce160 MS |
1846 | parts of the two input vectors, respectively. Their operands are vectors |
1847 | that contain the same number of elements (@code{N}) of the same integral type. | |
1848 | The result is a vector that contains half as many elements, of an integral type | |
929769f4 JQ |
1849 | whose size is twice as wide. In the case of @code{VEC_WIDEN_MULT_HI_EXPR} the |
1850 | high @code{N/2} elements of the two vector are multiplied to produce the | |
1851 | vector of @code{N/2} products. In the case of @code{VEC_WIDEN_MULT_LO_EXPR} the | |
1852 | low @code{N/2} elements of the two vector are multiplied to produce the | |
1853 | vector of @code{N/2} products. | |
1854 | ||
9fc9573f JH |
1855 | @item VEC_WIDEN_PLUS_HI_EXPR |
1856 | @itemx VEC_WIDEN_PLUS_LO_EXPR | |
1857 | These nodes represent widening vector addition of the high and low parts of | |
1858 | the two input vectors, respectively. Their operands are vectors that contain | |
1859 | the same number of elements (@code{N}) of the same integral type. The result | |
1860 | is a vector that contains half as many elements, of an integral type whose size | |
1861 | is twice as wide. In the case of @code{VEC_WIDEN_PLUS_HI_EXPR} the high | |
1862 | @code{N/2} elements of the two vectors are added to produce the vector of | |
1863 | @code{N/2} products. In the case of @code{VEC_WIDEN_PLUS_LO_EXPR} the low | |
1864 | @code{N/2} elements of the two vectors are added to produce the vector of | |
1865 | @code{N/2} products. | |
1866 | ||
1867 | @item VEC_WIDEN_MINUS_HI_EXPR | |
1868 | @itemx VEC_WIDEN_MINUS_LO_EXPR | |
1869 | These nodes represent widening vector subtraction of the high and low parts of | |
1870 | the two input vectors, respectively. Their operands are vectors that contain | |
1871 | the same number of elements (@code{N}) of the same integral type. The high/low | |
1872 | elements of the second vector are subtracted from the high/low elements of the | |
1873 | first. The result is a vector that contains half as many elements, of an | |
1874 | integral type whose size is twice as wide. In the case of | |
1875 | @code{VEC_WIDEN_MINUS_HI_EXPR} the high @code{N/2} elements of the second | |
1876 | vector are subtracted from the high @code{N/2} of the first to produce the | |
1877 | vector of @code{N/2} products. In the case of | |
1878 | @code{VEC_WIDEN_MINUS_LO_EXPR} the low @code{N/2} elements of the second | |
1879 | vector are subtracted from the low @code{N/2} of the first to produce the | |
1880 | vector of @code{N/2} products. | |
1881 | ||
929769f4 JQ |
1882 | @item VEC_UNPACK_HI_EXPR |
1883 | @itemx VEC_UNPACK_LO_EXPR | |
1884 | These nodes represent unpacking of the high and low parts of the input vector, | |
ff2ce160 | 1885 | respectively. The single operand is a vector that contains @code{N} elements |
929769f4 JQ |
1886 | of the same integral or floating point type. The result is a vector |
1887 | that contains half as many elements, of an integral or floating point type | |
1888 | whose size is twice as wide. In the case of @code{VEC_UNPACK_HI_EXPR} the | |
1889 | high @code{N/2} elements of the vector are extracted and widened (promoted). | |
1890 | In the case of @code{VEC_UNPACK_LO_EXPR} the low @code{N/2} elements of the | |
1891 | vector are extracted and widened (promoted). | |
1892 | ||
1893 | @item VEC_UNPACK_FLOAT_HI_EXPR | |
1894 | @itemx VEC_UNPACK_FLOAT_LO_EXPR | |
1895 | These nodes represent unpacking of the high and low parts of the input vector, | |
1896 | where the values are converted from fixed point to floating point. The | |
1897 | single operand is a vector that contains @code{N} elements of the same | |
1898 | integral type. The result is a vector that contains half as many elements | |
1899 | of a floating point type whose size is twice as wide. In the case of | |
1bda738b JJ |
1900 | @code{VEC_UNPACK_FLOAT_HI_EXPR} the high @code{N/2} elements of the vector are |
1901 | extracted, converted and widened. In the case of @code{VEC_UNPACK_FLOAT_LO_EXPR} | |
929769f4 JQ |
1902 | the low @code{N/2} elements of the vector are extracted, converted and widened. |
1903 | ||
1bda738b JJ |
1904 | @item VEC_UNPACK_FIX_TRUNC_HI_EXPR |
1905 | @itemx VEC_UNPACK_FIX_TRUNC_LO_EXPR | |
1906 | These nodes represent unpacking of the high and low parts of the input vector, | |
1907 | where the values are truncated from floating point to fixed point. The | |
1908 | single operand is a vector that contains @code{N} elements of the same | |
1909 | floating point type. The result is a vector that contains half as many | |
1910 | elements of an integral type whose size is twice as wide. In the case of | |
1911 | @code{VEC_UNPACK_FIX_TRUNC_HI_EXPR} the high @code{N/2} elements of the | |
1912 | vector are extracted and converted with truncation. In the case of | |
1913 | @code{VEC_UNPACK_FIX_TRUNC_LO_EXPR} the low @code{N/2} elements of the | |
1914 | vector are extracted and converted with truncation. | |
1915 | ||
929769f4 JQ |
1916 | @item VEC_PACK_TRUNC_EXPR |
1917 | This node represents packing of truncated elements of the two input vectors | |
1918 | into the output vector. Input operands are vectors that contain the same | |
1919 | number of elements of the same integral or floating point type. The result | |
1920 | is a vector that contains twice as many elements of an integral or floating | |
1921 | point type whose size is half as wide. The elements of the two vectors are | |
1922 | demoted and merged (concatenated) to form the output vector. | |
1923 | ||
1924 | @item VEC_PACK_SAT_EXPR | |
1925 | This node represents packing of elements of the two input vectors into the | |
1926 | output vector using saturation. Input operands are vectors that contain | |
1927 | the same number of elements of the same integral type. The result is a | |
1928 | vector that contains twice as many elements of an integral type whose size | |
1929 | is half as wide. The elements of the two vectors are demoted and merged | |
1930 | (concatenated) to form the output vector. | |
1931 | ||
1932 | @item VEC_PACK_FIX_TRUNC_EXPR | |
1933 | This node represents packing of elements of the two input vectors into the | |
1934 | output vector, where the values are converted from floating point | |
1935 | to fixed point. Input operands are vectors that contain the same number | |
1936 | of elements of a floating point type. The result is a vector that contains | |
1937 | twice as many elements of an integral type whose size is half as wide. The | |
1938 | elements of the two vectors are merged (concatenated) to form the output | |
1939 | vector. | |
0fdce875 | 1940 | |
1bda738b JJ |
1941 | @item VEC_PACK_FLOAT_EXPR |
1942 | This node represents packing of elements of the two input vectors into the | |
1943 | output vector, where the values are converted from fixed point to floating | |
1944 | point. Input operands are vectors that contain the same number of elements | |
1945 | of an integral type. The result is a vector that contains twice as many | |
1946 | elements of floating point type whose size is half as wide. The elements of | |
1947 | the two vectors are merged (concatenated) to form the output vector. | |
1948 | ||
0fdce875 MG |
1949 | @item VEC_COND_EXPR |
1950 | These nodes represent @code{?:} expressions. The three operands must be | |
1951 | vectors of the same size and number of elements. The second and third | |
1952 | operands must have the same type as the entire expression. The first | |
1953 | operand is of signed integral vector type. If an element of the first | |
1954 | operand evaluates to a zero value, the corresponding element of the | |
1955 | result is taken from the third operand. If it evaluates to a minus one | |
1956 | value, it is taken from the second operand. It should never evaluate to | |
a8dcc458 MG |
1957 | any other value currently, but optimizations should not rely on that |
1958 | property. In contrast with a @code{COND_EXPR}, all operands are always | |
1959 | evaluated. | |
79d652a5 CH |
1960 | |
1961 | @item SAD_EXPR | |
1962 | This node represents the Sum of Absolute Differences operation. The three | |
1963 | operands must be vectors of integral types. The first and second operand | |
1964 | must have the same type. The size of the vector element of the third | |
1965 | operand must be at lease twice of the size of the vector element of the | |
1966 | first and second one. The SAD is calculated between the first and second | |
1967 | operands, added to the third operand, and returned. | |
1968 | ||
929769f4 JQ |
1969 | @end table |
1970 | ||
1971 | ||
1972 | @c --------------------------------------------------------------------- | |
1973 | @c Statements | |
1974 | @c --------------------------------------------------------------------- | |
1975 | ||
1976 | @node Statements | |
1977 | @section Statements | |
1978 | @cindex Statements | |
1979 | ||
1980 | Most statements in GIMPLE are assignment statements, represented by | |
1981 | @code{GIMPLE_ASSIGN}. No other C expressions can appear at statement level; | |
1982 | a reference to a volatile object is converted into a | |
1983 | @code{GIMPLE_ASSIGN}. | |
1984 | ||
1985 | There are also several varieties of complex statements. | |
1986 | ||
1987 | @menu | |
1988 | * Basic Statements:: | |
1989 | * Blocks:: | |
1990 | * Statement Sequences:: | |
1991 | * Empty Statements:: | |
1992 | * Jumps:: | |
1993 | * Cleanups:: | |
1994 | * OpenMP:: | |
41dbbb37 | 1995 | * OpenACC:: |
929769f4 JQ |
1996 | @end menu |
1997 | ||
1998 | @node Basic Statements | |
1999 | @subsection Basic Statements | |
2000 | @cindex Basic Statements | |
2001 | ||
2002 | @table @code | |
2003 | @item ASM_EXPR | |
2004 | ||
2005 | Used to represent an inline assembly statement. For an inline assembly | |
2006 | statement like: | |
2007 | @smallexample | |
2008 | asm ("mov x, y"); | |
2009 | @end smallexample | |
2010 | The @code{ASM_STRING} macro will return a @code{STRING_CST} node for | |
2011 | @code{"mov x, y"}. If the original statement made use of the | |
2012 | extended-assembly syntax, then @code{ASM_OUTPUTS}, | |
2013 | @code{ASM_INPUTS}, and @code{ASM_CLOBBERS} will be the outputs, inputs, | |
2014 | and clobbers for the statement, represented as @code{STRING_CST} nodes. | |
2015 | The extended-assembly syntax looks like: | |
2016 | @smallexample | |
2017 | asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); | |
2018 | @end smallexample | |
2019 | The first string is the @code{ASM_STRING}, containing the instruction | |
2020 | template. The next two strings are the output and inputs, respectively; | |
2021 | this statement has no clobbers. As this example indicates, ``plain'' | |
2022 | assembly statements are merely a special case of extended assembly | |
2023 | statements; they have no cv-qualifiers, outputs, inputs, or clobbers. | |
2024 | All of the strings will be @code{NUL}-terminated, and will contain no | |
2025 | embedded @code{NUL}-characters. | |
2026 | ||
2027 | If the assembly statement is declared @code{volatile}, or if the | |
2028 | statement was not an extended assembly statement, and is therefore | |
2029 | implicitly volatile, then the predicate @code{ASM_VOLATILE_P} will hold | |
2030 | of the @code{ASM_EXPR}. | |
2031 | ||
2032 | @item DECL_EXPR | |
2033 | ||
2034 | Used to represent a local declaration. The @code{DECL_EXPR_DECL} macro | |
2035 | can be used to obtain the entity declared. This declaration may be a | |
2036 | @code{LABEL_DECL}, indicating that the label declared is a local label. | |
2037 | (As an extension, GCC allows the declaration of labels with scope.) In | |
2038 | C, this declaration may be a @code{FUNCTION_DECL}, indicating the | |
2039 | use of the GCC nested function extension. For more information, | |
2040 | @pxref{Functions}. | |
2041 | ||
2042 | @item LABEL_EXPR | |
2043 | ||
2044 | Used to represent a label. The @code{LABEL_DECL} declared by this | |
2045 | statement can be obtained with the @code{LABEL_EXPR_LABEL} macro. The | |
2046 | @code{IDENTIFIER_NODE} giving the name of the label can be obtained from | |
2047 | the @code{LABEL_DECL} with @code{DECL_NAME}. | |
2048 | ||
2049 | @item GOTO_EXPR | |
2050 | ||
2051 | Used to represent a @code{goto} statement. The @code{GOTO_DESTINATION} will | |
2052 | usually be a @code{LABEL_DECL}. However, if the ``computed goto'' extension | |
2053 | has been used, the @code{GOTO_DESTINATION} will be an arbitrary expression | |
2054 | indicating the destination. This expression will always have pointer type. | |
2055 | ||
2056 | @item RETURN_EXPR | |
2057 | ||
2058 | Used to represent a @code{return} statement. Operand 0 represents the | |
2059 | value to return. It should either be the @code{RESULT_DECL} for the | |
2060 | containing function, or a @code{MODIFY_EXPR} or @code{INIT_EXPR} | |
2061 | setting the function's @code{RESULT_DECL}. It will be | |
2062 | @code{NULL_TREE} if the statement was just | |
2063 | @smallexample | |
2064 | return; | |
2065 | @end smallexample | |
2066 | ||
2067 | @item LOOP_EXPR | |
2068 | These nodes represent ``infinite'' loops. The @code{LOOP_EXPR_BODY} | |
2069 | represents the body of the loop. It should be executed forever, unless | |
2070 | an @code{EXIT_EXPR} is encountered. | |
2071 | ||
2072 | @item EXIT_EXPR | |
2073 | These nodes represent conditional exits from the nearest enclosing | |
2074 | @code{LOOP_EXPR}. The single operand is the condition; if it is | |
2075 | nonzero, then the loop should be exited. An @code{EXIT_EXPR} will only | |
2076 | appear within a @code{LOOP_EXPR}. | |
2077 | ||
cba079f3 | 2078 | @item SWITCH_EXPR |
929769f4 | 2079 | |
cba079f3 SL |
2080 | Used to represent a @code{switch} statement. The @code{SWITCH_COND} |
2081 | is the expression on which the switch is occurring. The | |
2082 | @code{SWITCH_BODY} is the body of the switch statement. | |
2083 | @code{SWITCH_ALL_CASES_P} is true if the switch includes a default | |
2084 | label or the case label ranges cover all possible values of the | |
2085 | condition expression. | |
2086 | ||
2087 | Note that @code{TREE_TYPE} for a @code{SWITCH_EXPR} represents the | |
2088 | original type of switch expression as given in the source, before any | |
2089 | compiler conversions, instead of the type of the switch expression | |
2090 | itself (which is not meaningful). | |
929769f4 JQ |
2091 | |
2092 | @item CASE_LABEL_EXPR | |
2093 | ||
2094 | Use to represent a @code{case} label, range of @code{case} labels, or a | |
2095 | @code{default} label. If @code{CASE_LOW} is @code{NULL_TREE}, then this is a | |
2096 | @code{default} label. Otherwise, if @code{CASE_HIGH} is @code{NULL_TREE}, then | |
2097 | this is an ordinary @code{case} label. In this case, @code{CASE_LOW} is | |
2098 | an expression giving the value of the label. Both @code{CASE_LOW} and | |
2099 | @code{CASE_HIGH} are @code{INTEGER_CST} nodes. These values will have | |
2100 | the same type as the condition expression in the switch statement. | |
2101 | ||
2102 | Otherwise, if both @code{CASE_LOW} and @code{CASE_HIGH} are defined, the | |
2103 | statement is a range of case labels. Such statements originate with the | |
2104 | extension that allows users to write things of the form: | |
2105 | @smallexample | |
2106 | case 2 ... 5: | |
2107 | @end smallexample | |
2108 | The first value will be @code{CASE_LOW}, while the second will be | |
2109 | @code{CASE_HIGH}. | |
2110 | ||
96a95ac1 AO |
2111 | @item DEBUG_BEGIN_STMT |
2112 | ||
2113 | Marks the beginning of a source statement, for purposes of debug | |
2114 | information generation. | |
2115 | ||
929769f4 JQ |
2116 | @end table |
2117 | ||
2118 | ||
2119 | @node Blocks | |
2120 | @subsection Blocks | |
2121 | @cindex Blocks | |
2122 | ||
2123 | Block scopes and the variables they declare in GENERIC are | |
2124 | expressed using the @code{BIND_EXPR} code, which in previous | |
2125 | versions of GCC was primarily used for the C statement-expression | |
2126 | extension. | |
2127 | ||
2128 | Variables in a block are collected into @code{BIND_EXPR_VARS} in | |
2129 | declaration order through their @code{TREE_CHAIN} field. Any runtime | |
2130 | initialization is moved out of @code{DECL_INITIAL} and into a | |
2131 | statement in the controlled block. When gimplifying from C or C++, | |
2132 | this initialization replaces the @code{DECL_STMT}. These variables | |
2133 | will never require cleanups. The scope of these variables is just the | |
2134 | body | |
2135 | ||
03c00798 EB |
2136 | Variable-length arrays (VLAs) complicate this process, as their size |
2137 | often refers to variables initialized earlier in the block and their | |
2138 | initialization involves an explicit stack allocation. To handle this, | |
2139 | we add an indirection and replace them with a pointer to stack space | |
2140 | allocated by means of @code{alloca}. In most cases, we also arrange | |
2141 | for this space to be reclaimed when the enclosing @code{BIND_EXPR} is | |
2142 | exited, the exception to this being when there is an explicit call to | |
2143 | @code{alloca} in the source code, in which case the stack is left | |
2144 | depressed on exit of the @code{BIND_EXPR}. | |
929769f4 JQ |
2145 | |
2146 | A C++ program will usually contain more @code{BIND_EXPR}s than | |
2147 | there are syntactic blocks in the source code, since several C++ | |
2148 | constructs have implicit scopes associated with them. On the | |
2149 | other hand, although the C++ front end uses pseudo-scopes to | |
2150 | handle cleanups for objects with destructors, these don't | |
2151 | translate into the GIMPLE form; multiple declarations at the same | |
2152 | level use the same @code{BIND_EXPR}. | |
2153 | ||
2154 | @node Statement Sequences | |
2155 | @subsection Statement Sequences | |
2156 | @cindex Statement Sequences | |
2157 | ||
2158 | Multiple statements at the same nesting level are collected into | |
2159 | a @code{STATEMENT_LIST}. Statement lists are modified and | |
2160 | traversed using the interface in @samp{tree-iterator.h}. | |
2161 | ||
2162 | @node Empty Statements | |
2163 | @subsection Empty Statements | |
2164 | @cindex Empty Statements | |
2165 | ||
2166 | Whenever possible, statements with no effect are discarded. But | |
2167 | if they are nested within another construct which cannot be | |
2168 | discarded for some reason, they are instead replaced with an | |
2169 | empty statement, generated by @code{build_empty_stmt}. | |
2170 | Initially, all empty statements were shared, after the pattern of | |
2171 | the Java front end, but this caused a lot of trouble in practice. | |
2172 | ||
2173 | An empty statement is represented as @code{(void)0}. | |
2174 | ||
2175 | @node Jumps | |
2176 | @subsection Jumps | |
2177 | @cindex Jumps | |
2178 | ||
2179 | Other jumps are expressed by either @code{GOTO_EXPR} or | |
2180 | @code{RETURN_EXPR}. | |
2181 | ||
2182 | The operand of a @code{GOTO_EXPR} must be either a label or a | |
2183 | variable containing the address to jump to. | |
2184 | ||
2185 | The operand of a @code{RETURN_EXPR} is either @code{NULL_TREE}, | |
2186 | @code{RESULT_DECL}, or a @code{MODIFY_EXPR} which sets the return | |
2187 | value. It would be nice to move the @code{MODIFY_EXPR} into a | |
2188 | separate statement, but the special return semantics in | |
2189 | @code{expand_return} make that difficult. It may still happen in | |
2190 | the future, perhaps by moving most of that logic into | |
2191 | @code{expand_assignment}. | |
2192 | ||
2193 | @node Cleanups | |
2194 | @subsection Cleanups | |
2195 | @cindex Cleanups | |
2196 | ||
2197 | Destructors for local C++ objects and similar dynamic cleanups are | |
2198 | represented in GIMPLE by a @code{TRY_FINALLY_EXPR}. | |
2199 | @code{TRY_FINALLY_EXPR} has two operands, both of which are a sequence | |
2200 | of statements to execute. The first sequence is executed. When it | |
2201 | completes the second sequence is executed. | |
2202 | ||
2203 | The first sequence may complete in the following ways: | |
2204 | ||
2205 | @enumerate | |
2206 | ||
2207 | @item Execute the last statement in the sequence and fall off the | |
2208 | end. | |
2209 | ||
2210 | @item Execute a goto statement (@code{GOTO_EXPR}) to an ordinary | |
2211 | label outside the sequence. | |
2212 | ||
2213 | @item Execute a return statement (@code{RETURN_EXPR}). | |
2214 | ||
2215 | @item Throw an exception. This is currently not explicitly represented in | |
2216 | GIMPLE. | |
2217 | ||
2218 | @end enumerate | |
2219 | ||
2220 | The second sequence is not executed if the first sequence completes by | |
2221 | calling @code{setjmp} or @code{exit} or any other function that does | |
2222 | not return. The second sequence is also not executed if the first | |
2223 | sequence completes via a non-local goto or a computed goto (in general | |
2224 | the compiler does not know whether such a goto statement exits the | |
2225 | first sequence or not, so we assume that it doesn't). | |
2226 | ||
2227 | After the second sequence is executed, if it completes normally by | |
2228 | falling off the end, execution continues wherever the first sequence | |
2229 | would have continued, by falling off the end, or doing a goto, etc. | |
2230 | ||
ebebc928 AO |
2231 | If the second sequence is an @code{EH_ELSE_EXPR} selector, then the |
2232 | sequence in its first operand is used when the first sequence completes | |
2233 | normally, and that in its second operand is used for exceptional | |
2234 | cleanups, i.e., when an exception propagates out of the first sequence. | |
2235 | ||
929769f4 JQ |
2236 | @code{TRY_FINALLY_EXPR} complicates the flow graph, since the cleanup |
2237 | needs to appear on every edge out of the controlled block; this | |
2238 | reduces the freedom to move code across these edges. Therefore, the | |
2239 | EH lowering pass which runs before most of the optimization passes | |
2240 | eliminates these expressions by explicitly adding the cleanup to each | |
2241 | edge. Rethrowing the exception is represented using @code{RESX_EXPR}. | |
2242 | ||
2243 | @node OpenMP | |
2244 | @subsection OpenMP | |
2245 | @tindex OMP_PARALLEL | |
2246 | @tindex OMP_FOR | |
2247 | @tindex OMP_SECTIONS | |
2248 | @tindex OMP_SINGLE | |
2249 | @tindex OMP_SECTION | |
2250 | @tindex OMP_MASTER | |
2251 | @tindex OMP_ORDERED | |
2252 | @tindex OMP_CRITICAL | |
2253 | @tindex OMP_RETURN | |
2254 | @tindex OMP_CONTINUE | |
2255 | @tindex OMP_ATOMIC | |
2256 | @tindex OMP_CLAUSE | |
2257 | ||
2258 | All the statements starting with @code{OMP_} represent directives and | |
fab8c69d | 2259 | clauses used by the OpenMP API @w{@uref{https://www.openmp.org}}. |
929769f4 JQ |
2260 | |
2261 | @table @code | |
2262 | @item OMP_PARALLEL | |
2263 | ||
2264 | Represents @code{#pragma omp parallel [clause1 @dots{} clauseN]}. It | |
2265 | has four operands: | |
2266 | ||
2267 | Operand @code{OMP_PARALLEL_BODY} is valid while in GENERIC and | |
2268 | High GIMPLE forms. It contains the body of code to be executed | |
2269 | by all the threads. During GIMPLE lowering, this operand becomes | |
2270 | @code{NULL} and the body is emitted linearly after | |
2271 | @code{OMP_PARALLEL}. | |
2272 | ||
2273 | Operand @code{OMP_PARALLEL_CLAUSES} is the list of clauses | |
2274 | associated with the directive. | |
2275 | ||
2276 | Operand @code{OMP_PARALLEL_FN} is created by | |
2277 | @code{pass_lower_omp}, it contains the @code{FUNCTION_DECL} | |
2278 | for the function that will contain the body of the parallel | |
2279 | region. | |
2280 | ||
2281 | Operand @code{OMP_PARALLEL_DATA_ARG} is also created by | |
2282 | @code{pass_lower_omp}. If there are shared variables to be | |
2283 | communicated to the children threads, this operand will contain | |
2284 | the @code{VAR_DECL} that contains all the shared values and | |
2285 | variables. | |
2286 | ||
2287 | @item OMP_FOR | |
2288 | ||
41dbbb37 TS |
2289 | Represents @code{#pragma omp for [clause1 @dots{} clauseN]}. It has |
2290 | six operands: | |
929769f4 JQ |
2291 | |
2292 | Operand @code{OMP_FOR_BODY} contains the loop body. | |
2293 | ||
2294 | Operand @code{OMP_FOR_CLAUSES} is the list of clauses | |
2295 | associated with the directive. | |
2296 | ||
2297 | Operand @code{OMP_FOR_INIT} is the loop initialization code of | |
2298 | the form @code{VAR = N1}. | |
2299 | ||
2300 | Operand @code{OMP_FOR_COND} is the loop conditional expression | |
2301 | of the form @code{VAR @{<,>,<=,>=@} N2}. | |
2302 | ||
2303 | Operand @code{OMP_FOR_INCR} is the loop index increment of the | |
2304 | form @code{VAR @{+=,-=@} INCR}. | |
2305 | ||
df18c24a | 2306 | Operand @code{OMP_FOR_PRE_BODY} contains side effect code from |
929769f4 | 2307 | operands @code{OMP_FOR_INIT}, @code{OMP_FOR_COND} and |
df18c24a | 2308 | @code{OMP_FOR_INC}. These side effects are part of the |
929769f4 JQ |
2309 | @code{OMP_FOR} block but must be evaluated before the start of |
2310 | loop body. | |
2311 | ||
2312 | The loop index variable @code{VAR} must be a signed integer variable, | |
2313 | which is implicitly private to each thread. Bounds | |
2314 | @code{N1} and @code{N2} and the increment expression | |
2315 | @code{INCR} are required to be loop invariant integer | |
2316 | expressions that are evaluated without any synchronization. The | |
df18c24a | 2317 | evaluation order, frequency of evaluation and side effects are |
929769f4 JQ |
2318 | unspecified by the standard. |
2319 | ||
2320 | @item OMP_SECTIONS | |
2321 | ||
2322 | Represents @code{#pragma omp sections [clause1 @dots{} clauseN]}. | |
2323 | ||
2324 | Operand @code{OMP_SECTIONS_BODY} contains the sections body, | |
2325 | which in turn contains a set of @code{OMP_SECTION} nodes for | |
2326 | each of the concurrent sections delimited by @code{#pragma omp | |
2327 | section}. | |
2328 | ||
2329 | Operand @code{OMP_SECTIONS_CLAUSES} is the list of clauses | |
2330 | associated with the directive. | |
2331 | ||
2332 | @item OMP_SECTION | |
2333 | ||
2334 | Section delimiter for @code{OMP_SECTIONS}. | |
2335 | ||
2336 | @item OMP_SINGLE | |
2337 | ||
2338 | Represents @code{#pragma omp single}. | |
2339 | ||
2340 | Operand @code{OMP_SINGLE_BODY} contains the body of code to be | |
2341 | executed by a single thread. | |
2342 | ||
2343 | Operand @code{OMP_SINGLE_CLAUSES} is the list of clauses | |
2344 | associated with the directive. | |
2345 | ||
2346 | @item OMP_MASTER | |
2347 | ||
2348 | Represents @code{#pragma omp master}. | |
2349 | ||
2350 | Operand @code{OMP_MASTER_BODY} contains the body of code to be | |
2351 | executed by the master thread. | |
2352 | ||
2353 | @item OMP_ORDERED | |
2354 | ||
2355 | Represents @code{#pragma omp ordered}. | |
2356 | ||
2357 | Operand @code{OMP_ORDERED_BODY} contains the body of code to be | |
2358 | executed in the sequential order dictated by the loop index | |
2359 | variable. | |
2360 | ||
2361 | @item OMP_CRITICAL | |
2362 | ||
2363 | Represents @code{#pragma omp critical [name]}. | |
2364 | ||
2365 | Operand @code{OMP_CRITICAL_BODY} is the critical section. | |
2366 | ||
2367 | Operand @code{OMP_CRITICAL_NAME} is an optional identifier to | |
2368 | label the critical section. | |
2369 | ||
2370 | @item OMP_RETURN | |
2371 | ||
2372 | This does not represent any OpenMP directive, it is an artificial | |
2373 | marker to indicate the end of the body of an OpenMP@. It is used | |
2374 | by the flow graph (@code{tree-cfg.c}) and OpenMP region | |
2375 | building code (@code{omp-low.c}). | |
2376 | ||
2377 | @item OMP_CONTINUE | |
2378 | ||
2379 | Similarly, this instruction does not represent an OpenMP | |
41dbbb37 | 2380 | directive, it is used by @code{OMP_FOR} (and similar codes) as well as |
929769f4 | 2381 | @code{OMP_SECTIONS} to mark the place where the code needs to |
41dbbb37 | 2382 | loop to the next iteration, or the next section, respectively. |
929769f4 JQ |
2383 | |
2384 | In some cases, @code{OMP_CONTINUE} is placed right before | |
2385 | @code{OMP_RETURN}. But if there are cleanups that need to | |
2386 | occur right after the looping body, it will be emitted between | |
2387 | @code{OMP_CONTINUE} and @code{OMP_RETURN}. | |
2388 | ||
2389 | @item OMP_ATOMIC | |
2390 | ||
2391 | Represents @code{#pragma omp atomic}. | |
2392 | ||
2393 | Operand 0 is the address at which the atomic operation is to be | |
2394 | performed. | |
2395 | ||
2396 | Operand 1 is the expression to evaluate. The gimplifier tries | |
2397 | three alternative code generation strategies. Whenever possible, | |
2398 | an atomic update built-in is used. If that fails, a | |
2399 | compare-and-swap loop is attempted. If that also fails, a | |
2400 | regular critical section around the expression is used. | |
2401 | ||
2402 | @item OMP_CLAUSE | |
2403 | ||
2404 | Represents clauses associated with one of the @code{OMP_} directives. | |
6545f0b3 | 2405 | Clauses are represented by separate subcodes defined in |
929769f4 JQ |
2406 | @file{tree.h}. Clauses codes can be one of: |
2407 | @code{OMP_CLAUSE_PRIVATE}, @code{OMP_CLAUSE_SHARED}, | |
2408 | @code{OMP_CLAUSE_FIRSTPRIVATE}, | |
2409 | @code{OMP_CLAUSE_LASTPRIVATE}, @code{OMP_CLAUSE_COPYIN}, | |
2410 | @code{OMP_CLAUSE_COPYPRIVATE}, @code{OMP_CLAUSE_IF}, | |
2411 | @code{OMP_CLAUSE_NUM_THREADS}, @code{OMP_CLAUSE_SCHEDULE}, | |
2412 | @code{OMP_CLAUSE_NOWAIT}, @code{OMP_CLAUSE_ORDERED}, | |
20906c66 JJ |
2413 | @code{OMP_CLAUSE_DEFAULT}, @code{OMP_CLAUSE_REDUCTION}, |
2414 | @code{OMP_CLAUSE_COLLAPSE}, @code{OMP_CLAUSE_UNTIED}, | |
2415 | @code{OMP_CLAUSE_FINAL}, and @code{OMP_CLAUSE_MERGEABLE}. Each code | |
929769f4 JQ |
2416 | represents the corresponding OpenMP clause. |
2417 | ||
2418 | Clauses associated with the same directive are chained together | |
2419 | via @code{OMP_CLAUSE_CHAIN}. Those clauses that accept a list | |
2420 | of variables are restricted to exactly one, accessed with | |
2421 | @code{OMP_CLAUSE_VAR}. Therefore, multiple variables under the | |
2422 | same clause @code{C} need to be represented as multiple @code{C} clauses | |
2423 | chained together. This facilitates adding new clauses during | |
2424 | compilation. | |
2425 | ||
2426 | @end table | |
2427 | ||
41dbbb37 TS |
2428 | @node OpenACC |
2429 | @subsection OpenACC | |
2430 | @tindex OACC_CACHE | |
2431 | @tindex OACC_DATA | |
2432 | @tindex OACC_DECLARE | |
2433 | @tindex OACC_ENTER_DATA | |
2434 | @tindex OACC_EXIT_DATA | |
2435 | @tindex OACC_HOST_DATA | |
2436 | @tindex OACC_KERNELS | |
2437 | @tindex OACC_LOOP | |
2438 | @tindex OACC_PARALLEL | |
62aee289 | 2439 | @tindex OACC_SERIAL |
41dbbb37 TS |
2440 | @tindex OACC_UPDATE |
2441 | ||
2442 | All the statements starting with @code{OACC_} represent directives and | |
22140cb0 | 2443 | clauses used by the OpenACC API @w{@uref{https://www.openacc.org}}. |
41dbbb37 TS |
2444 | |
2445 | @table @code | |
2446 | @item OACC_CACHE | |
2447 | ||
2448 | Represents @code{#pragma acc cache (var @dots{})}. | |
2449 | ||
2450 | @item OACC_DATA | |
2451 | ||
2452 | Represents @code{#pragma acc data [clause1 @dots{} clauseN]}. | |
2453 | ||
2454 | @item OACC_DECLARE | |
2455 | ||
2456 | Represents @code{#pragma acc declare [clause1 @dots{} clauseN]}. | |
2457 | ||
2458 | @item OACC_ENTER_DATA | |
2459 | ||
2460 | Represents @code{#pragma acc enter data [clause1 @dots{} clauseN]}. | |
2461 | ||
2462 | @item OACC_EXIT_DATA | |
2463 | ||
2464 | Represents @code{#pragma acc exit data [clause1 @dots{} clauseN]}. | |
2465 | ||
2466 | @item OACC_HOST_DATA | |
2467 | ||
2468 | Represents @code{#pragma acc host_data [clause1 @dots{} clauseN]}. | |
2469 | ||
2470 | @item OACC_KERNELS | |
2471 | ||
2472 | Represents @code{#pragma acc kernels [clause1 @dots{} clauseN]}. | |
2473 | ||
2474 | @item OACC_LOOP | |
2475 | ||
2476 | Represents @code{#pragma acc loop [clause1 @dots{} clauseN]}. | |
2477 | ||
2478 | See the description of the @code{OMP_FOR} code. | |
2479 | ||
2480 | @item OACC_PARALLEL | |
2481 | ||
2482 | Represents @code{#pragma acc parallel [clause1 @dots{} clauseN]}. | |
2483 | ||
62aee289 MR |
2484 | @item OACC_SERIAL |
2485 | ||
2486 | Represents @code{#pragma acc serial [clause1 @dots{} clauseN]}. | |
2487 | ||
41dbbb37 TS |
2488 | @item OACC_UPDATE |
2489 | ||
2490 | Represents @code{#pragma acc update [clause1 @dots{} clauseN]}. | |
2491 | ||
2492 | @end table | |
2493 | ||
929769f4 JQ |
2494 | @c --------------------------------------------------------------------- |
2495 | @c Functions | |
2496 | @c --------------------------------------------------------------------- | |
2497 | ||
2498 | @node Functions | |
2499 | @section Functions | |
2500 | @cindex function | |
2501 | @tindex FUNCTION_DECL | |
2502 | ||
2503 | A function is represented by a @code{FUNCTION_DECL} node. It stores | |
2504 | the basic pieces of the function such as body, parameters, and return | |
2505 | type as well as information on the surrounding context, visibility, | |
2506 | and linkage. | |
2507 | ||
2508 | @menu | |
2509 | * Function Basics:: Function names, body, and parameters. | |
2510 | * Function Properties:: Context, linkage, etc. | |
2511 | @end menu | |
2512 | ||
2513 | @c --------------------------------------------------------------------- | |
2514 | @c Function Basics | |
2515 | @c --------------------------------------------------------------------- | |
2516 | ||
2517 | @node Function Basics | |
2518 | @subsection Function Basics | |
2519 | @findex DECL_NAME | |
2520 | @findex DECL_ASSEMBLER_NAME | |
2521 | @findex TREE_PUBLIC | |
2522 | @findex DECL_ARTIFICIAL | |
2523 | @findex DECL_FUNCTION_SPECIFIC_TARGET | |
2524 | @findex DECL_FUNCTION_SPECIFIC_OPTIMIZATION | |
2525 | ||
2526 | A function has four core parts: the name, the parameters, the result, | |
2527 | and the body. The following macros and functions access these parts | |
2528 | of a @code{FUNCTION_DECL} as well as other basic features: | |
2529 | @ftable @code | |
2530 | @item DECL_NAME | |
2531 | This macro returns the unqualified name of the function, as an | |
2532 | @code{IDENTIFIER_NODE}. For an instantiation of a function template, | |
2533 | the @code{DECL_NAME} is the unqualified name of the template, not | |
2534 | something like @code{f<int>}. The value of @code{DECL_NAME} is | |
2535 | undefined when used on a constructor, destructor, overloaded operator, | |
2536 | or type-conversion operator, or any function that is implicitly | |
2537 | generated by the compiler. See below for macros that can be used to | |
2538 | distinguish these cases. | |
2539 | ||
2540 | @item DECL_ASSEMBLER_NAME | |
2541 | This macro returns the mangled name of the function, also an | |
2542 | @code{IDENTIFIER_NODE}. This name does not contain leading underscores | |
2543 | on systems that prefix all identifiers with underscores. The mangled | |
2544 | name is computed in the same way on all platforms; if special processing | |
2545 | is required to deal with the object file format used on a particular | |
2546 | platform, it is the responsibility of the back end to perform those | |
2547 | modifications. (Of course, the back end should not modify | |
2548 | @code{DECL_ASSEMBLER_NAME} itself.) | |
2549 | ||
2550 | Using @code{DECL_ASSEMBLER_NAME} will cause additional memory to be | |
2551 | allocated (for the mangled name of the entity) so it should be used | |
2552 | only when emitting assembly code. It should not be used within the | |
2553 | optimizers to determine whether or not two declarations are the same, | |
2554 | even though some of the existing optimizers do use it in that way. | |
2555 | These uses will be removed over time. | |
2556 | ||
2557 | @item DECL_ARGUMENTS | |
2558 | This macro returns the @code{PARM_DECL} for the first argument to the | |
2559 | function. Subsequent @code{PARM_DECL} nodes can be obtained by | |
2560 | following the @code{TREE_CHAIN} links. | |
2561 | ||
2562 | @item DECL_RESULT | |
2563 | This macro returns the @code{RESULT_DECL} for the function. | |
2564 | ||
2565 | @item DECL_SAVED_TREE | |
2566 | This macro returns the complete body of the function. | |
2567 | ||
2568 | @item TREE_TYPE | |
2569 | This macro returns the @code{FUNCTION_TYPE} or @code{METHOD_TYPE} for | |
2570 | the function. | |
2571 | ||
2572 | @item DECL_INITIAL | |
2573 | A function that has a definition in the current translation unit will | |
2574 | have a non-@code{NULL} @code{DECL_INITIAL}. However, back ends should not make | |
2575 | use of the particular value given by @code{DECL_INITIAL}. | |
2576 | ||
2577 | It should contain a tree of @code{BLOCK} nodes that mirrors the scopes | |
2578 | that variables are bound in the function. Each block contains a list | |
2579 | of decls declared in a basic block, a pointer to a chain of blocks at | |
2580 | the next lower scope level, then a pointer to the next block at the | |
2581 | same level and a backpointer to the parent @code{BLOCK} or | |
2582 | @code{FUNCTION_DECL}. So given a function as follows: | |
2583 | ||
2584 | @smallexample | |
2585 | void foo() | |
2586 | @{ | |
2587 | int a; | |
2588 | @{ | |
2589 | int b; | |
2590 | @} | |
2591 | int c; | |
2592 | @} | |
2593 | @end smallexample | |
2594 | ||
2595 | you would get the following: | |
2596 | ||
2597 | @smallexample | |
2598 | tree foo = FUNCTION_DECL; | |
2599 | tree decl_a = VAR_DECL; | |
2600 | tree decl_b = VAR_DECL; | |
2601 | tree decl_c = VAR_DECL; | |
2602 | tree block_a = BLOCK; | |
2603 | tree block_b = BLOCK; | |
2604 | tree block_c = BLOCK; | |
2605 | BLOCK_VARS(block_a) = decl_a; | |
2606 | BLOCK_SUBBLOCKS(block_a) = block_b; | |
2607 | BLOCK_CHAIN(block_a) = block_c; | |
2608 | BLOCK_SUPERCONTEXT(block_a) = foo; | |
2609 | BLOCK_VARS(block_b) = decl_b; | |
2610 | BLOCK_SUPERCONTEXT(block_b) = block_a; | |
2611 | BLOCK_VARS(block_c) = decl_c; | |
2612 | BLOCK_SUPERCONTEXT(block_c) = foo; | |
2613 | DECL_INITIAL(foo) = block_a; | |
2614 | @end smallexample | |
2615 | ||
2616 | @end ftable | |
2617 | ||
2618 | @c --------------------------------------------------------------------- | |
2619 | @c Function Properties | |
2620 | @c --------------------------------------------------------------------- | |
2621 | ||
2622 | @node Function Properties | |
2623 | @subsection Function Properties | |
2624 | @cindex function properties | |
2625 | @cindex statements | |
2626 | ||
2627 | To determine the scope of a function, you can use the | |
2628 | @code{DECL_CONTEXT} macro. This macro will return the class | |
2629 | (either a @code{RECORD_TYPE} or a @code{UNION_TYPE}) or namespace (a | |
2630 | @code{NAMESPACE_DECL}) of which the function is a member. For a virtual | |
2631 | function, this macro returns the class in which the function was | |
2632 | actually defined, not the base class in which the virtual declaration | |
2633 | occurred. | |
2634 | ||
2635 | In C, the @code{DECL_CONTEXT} for a function maybe another function. | |
2636 | This representation indicates that the GNU nested function extension | |
2637 | is in use. For details on the semantics of nested functions, see the | |
2638 | GCC Manual. The nested function can refer to local variables in its | |
2639 | containing function. Such references are not explicitly marked in the | |
2640 | tree structure; back ends must look at the @code{DECL_CONTEXT} for the | |
2641 | referenced @code{VAR_DECL}. If the @code{DECL_CONTEXT} for the | |
2642 | referenced @code{VAR_DECL} is not the same as the function currently | |
2643 | being processed, and neither @code{DECL_EXTERNAL} nor | |
2644 | @code{TREE_STATIC} hold, then the reference is to a local variable in | |
2645 | a containing function, and the back end must take appropriate action. | |
2646 | ||
2647 | @ftable @code | |
2648 | @item DECL_EXTERNAL | |
2649 | This predicate holds if the function is undefined. | |
2650 | ||
2651 | @item TREE_PUBLIC | |
2652 | This predicate holds if the function has external linkage. | |
2653 | ||
2654 | @item TREE_STATIC | |
2655 | This predicate holds if the function has been defined. | |
2656 | ||
2657 | @item TREE_THIS_VOLATILE | |
2658 | This predicate holds if the function does not return normally. | |
2659 | ||
2660 | @item TREE_READONLY | |
2661 | This predicate holds if the function can only read its arguments. | |
2662 | ||
2663 | @item DECL_PURE_P | |
7a50adb7 | 2664 | This predicate holds if the function can only read its arguments, but |
929769f4 JQ |
2665 | may also read global memory. |
2666 | ||
2667 | @item DECL_VIRTUAL_P | |
2668 | This predicate holds if the function is virtual. | |
2669 | ||
2670 | @item DECL_ARTIFICIAL | |
2671 | This macro holds if the function was implicitly generated by the | |
2672 | compiler, rather than explicitly declared. In addition to implicitly | |
2673 | generated class member functions, this macro holds for the special | |
2674 | functions created to implement static initialization and destruction, to | |
2675 | compute run-time type information, and so forth. | |
2676 | ||
2677 | @item DECL_FUNCTION_SPECIFIC_TARGET | |
2678 | This macro returns a tree node that holds the target options that are | |
2679 | to be used to compile this particular function or @code{NULL_TREE} if | |
2680 | the function is to be compiled with the target options specified on | |
2681 | the command line. | |
2682 | ||
2683 | @item DECL_FUNCTION_SPECIFIC_OPTIMIZATION | |
2684 | This macro returns a tree node that holds the optimization options | |
2685 | that are to be used to compile this particular function or | |
2686 | @code{NULL_TREE} if the function is to be compiled with the | |
2687 | optimization options specified on the command line. | |
2688 | ||
2689 | @end ftable | |
2690 | ||
929769f4 JQ |
2691 | @c --------------------------------------------------------------------- |
2692 | @c Language-dependent trees | |
2693 | @c --------------------------------------------------------------------- | |
2694 | ||
2695 | @node Language-dependent trees | |
2696 | @section Language-dependent trees | |
2697 | @cindex language-dependent trees | |
2698 | ||
2699 | Front ends may wish to keep some state associated with various GENERIC | |
2700 | trees while parsing. To support this, trees provide a set of flags | |
2701 | that may be used by the front end. They are accessed using | |
2702 | @code{TREE_LANG_FLAG_n} where @samp{n} is currently 0 through 6. | |
2703 | ||
e6c99067 DN |
2704 | If necessary, a front end can use some language-dependent tree |
2705 | codes in its GENERIC representation, so long as it provides a | |
2706 | hook for converting them to GIMPLE and doesn't expect them to | |
2707 | work with any (hypothetical) optimizers that run before the | |
2708 | conversion to GIMPLE@. The intermediate representation used while | |
2709 | parsing C and C++ looks very little like GENERIC, but the C and | |
2710 | C++ gimplifier hooks are perfectly happy to take it as input and | |
2711 | spit out GIMPLE@. | |
2712 | ||
e6c99067 | 2713 | |
e6c99067 | 2714 | |
929769f4 JQ |
2715 | @node C and C++ Trees |
2716 | @section C and C++ Trees | |
e6c99067 | 2717 | |
929769f4 JQ |
2718 | This section documents the internal representation used by GCC to |
2719 | represent C and C++ source programs. When presented with a C or C++ | |
2720 | source program, GCC parses the program, performs semantic analysis | |
2721 | (including the generation of error messages), and then produces the | |
2722 | internal representation described here. This representation contains a | |
2723 | complete representation for the entire translation unit provided as | |
2724 | input to the front end. This representation is then typically processed | |
2725 | by a code-generator in order to produce machine code, but could also be | |
2726 | used in the creation of source browsers, intelligent editors, automatic | |
2727 | documentation generators, interpreters, and any other programs needing | |
2728 | the ability to process C or C++ code. | |
2729 | ||
2730 | This section explains the internal representation. In particular, it | |
2731 | documents the internal representation for C and C++ source | |
2732 | constructs, and the macros, functions, and variables that can be used to | |
2733 | access these constructs. The C++ representation is largely a superset | |
2734 | of the representation used in the C front end. There is only one | |
2735 | construct used in C that does not appear in the C++ front end and that | |
2736 | is the GNU ``nested function'' extension. Many of the macros documented | |
2737 | here do not apply in C because the corresponding language constructs do | |
2738 | not appear in C@. | |
2739 | ||
2740 | The C and C++ front ends generate a mix of GENERIC trees and ones | |
2741 | specific to C and C++. These language-specific trees are higher-level | |
2742 | constructs than the ones in GENERIC to make the parser's job easier. | |
2743 | This section describes those trees that aren't part of GENERIC as well | |
7a50adb7 | 2744 | as aspects of GENERIC trees that are treated in a language-specific |
929769f4 JQ |
2745 | manner. |
2746 | ||
2747 | If you are developing a ``back end'', be it is a code-generator or some | |
2748 | other tool, that uses this representation, you may occasionally find | |
2749 | that you need to ask questions not easily answered by the functions and | |
2750 | macros available here. If that situation occurs, it is quite likely | |
2751 | that GCC already supports the functionality you desire, but that the | |
2752 | interface is simply not documented here. In that case, you should ask | |
2753 | the GCC maintainers (via mail to @email{gcc@@gcc.gnu.org}) about | |
2754 | documenting the functionality you require. Similarly, if you find | |
2755 | yourself writing functions that do not deal directly with your back end, | |
2756 | but instead might be useful to other people using the GCC front end, you | |
2757 | should submit your patches for inclusion in GCC@. | |
e6c99067 DN |
2758 | |
2759 | @menu | |
929769f4 JQ |
2760 | * Types for C++:: Fundamental and aggregate types. |
2761 | * Namespaces:: Namespaces. | |
2762 | * Classes:: Classes. | |
2763 | * Functions for C++:: Overloading and accessors for C++. | |
cba079f3 | 2764 | * Statements for C and C++:: Statements specific to C and C++. |
929769f4 | 2765 | * C++ Expressions:: From @code{typeid} to @code{throw}. |
e6c99067 DN |
2766 | @end menu |
2767 | ||
929769f4 JQ |
2768 | @node Types for C++ |
2769 | @subsection Types for C++ | |
2770 | @tindex UNKNOWN_TYPE | |
2771 | @tindex TYPENAME_TYPE | |
2772 | @tindex TYPEOF_TYPE | |
680fba09 | 2773 | @findex cp_type_quals |
929769f4 JQ |
2774 | @findex TYPE_UNQUALIFIED |
2775 | @findex TYPE_QUAL_CONST | |
2776 | @findex TYPE_QUAL_VOLATILE | |
2777 | @findex TYPE_QUAL_RESTRICT | |
2778 | @findex TYPE_MAIN_VARIANT | |
2779 | @cindex qualified type | |
2780 | @findex TYPE_SIZE | |
2781 | @findex TYPE_ALIGN | |
2782 | @findex TYPE_PRECISION | |
2783 | @findex TYPE_ARG_TYPES | |
2784 | @findex TYPE_METHOD_BASETYPE | |
39067958 | 2785 | @findex TYPE_PTRDATAMEM_P |
929769f4 JQ |
2786 | @findex TYPE_OFFSET_BASETYPE |
2787 | @findex TREE_TYPE | |
2788 | @findex TYPE_CONTEXT | |
2789 | @findex TYPE_NAME | |
2790 | @findex TYPENAME_TYPE_FULLNAME | |
2791 | @findex TYPE_FIELDS | |
2792 | @findex TYPE_PTROBV_P | |
e6c99067 | 2793 | |
929769f4 JQ |
2794 | In C++, an array type is not qualified; rather the type of the array |
2795 | elements is qualified. This situation is reflected in the intermediate | |
2796 | representation. The macros described here will always examine the | |
2797 | qualification of the underlying element type when applied to an array | |
2798 | type. (If the element type is itself an array, then the recursion | |
2799 | continues until a non-array type is found, and the qualification of this | |
2800 | type is examined.) So, for example, @code{CP_TYPE_CONST_P} will hold of | |
2801 | the type @code{const int ()[7]}, denoting an array of seven @code{int}s. | |
e6c99067 | 2802 | |
929769f4 JQ |
2803 | The following functions and macros deal with cv-qualification of types: |
2804 | @ftable @code | |
680fba09 MG |
2805 | @item cp_type_quals |
2806 | This function returns the set of type qualifiers applied to this type. | |
929769f4 JQ |
2807 | This value is @code{TYPE_UNQUALIFIED} if no qualifiers have been |
2808 | applied. The @code{TYPE_QUAL_CONST} bit is set if the type is | |
2809 | @code{const}-qualified. The @code{TYPE_QUAL_VOLATILE} bit is set if the | |
2810 | type is @code{volatile}-qualified. The @code{TYPE_QUAL_RESTRICT} bit is | |
2811 | set if the type is @code{restrict}-qualified. | |
e6c99067 | 2812 | |
929769f4 JQ |
2813 | @item CP_TYPE_CONST_P |
2814 | This macro holds if the type is @code{const}-qualified. | |
e6c99067 | 2815 | |
929769f4 JQ |
2816 | @item CP_TYPE_VOLATILE_P |
2817 | This macro holds if the type is @code{volatile}-qualified. | |
e6c99067 | 2818 | |
929769f4 JQ |
2819 | @item CP_TYPE_RESTRICT_P |
2820 | This macro holds if the type is @code{restrict}-qualified. | |
e6c99067 | 2821 | |
929769f4 JQ |
2822 | @item CP_TYPE_CONST_NON_VOLATILE_P |
2823 | This predicate holds for a type that is @code{const}-qualified, but | |
2824 | @emph{not} @code{volatile}-qualified; other cv-qualifiers are ignored as | |
2825 | well: only the @code{const}-ness is tested. | |
e6c99067 | 2826 | |
929769f4 | 2827 | @end ftable |
e6c99067 | 2828 | |
929769f4 JQ |
2829 | A few other macros and functions are usable with all types: |
2830 | @ftable @code | |
2831 | @item TYPE_SIZE | |
2832 | The number of bits required to represent the type, represented as an | |
2833 | @code{INTEGER_CST}. For an incomplete type, @code{TYPE_SIZE} will be | |
2834 | @code{NULL_TREE}. | |
e6c99067 | 2835 | |
929769f4 JQ |
2836 | @item TYPE_ALIGN |
2837 | The alignment of the type, in bits, represented as an @code{int}. | |
e6c99067 | 2838 | |
929769f4 JQ |
2839 | @item TYPE_NAME |
2840 | This macro returns a declaration (in the form of a @code{TYPE_DECL}) for | |
2841 | the type. (Note this macro does @emph{not} return an | |
2842 | @code{IDENTIFIER_NODE}, as you might expect, given its name!) You can | |
2843 | look at the @code{DECL_NAME} of the @code{TYPE_DECL} to obtain the | |
2844 | actual name of the type. The @code{TYPE_NAME} will be @code{NULL_TREE} | |
2845 | for a type that is not a built-in type, the result of a typedef, or a | |
2846 | named class type. | |
e6c99067 | 2847 | |
929769f4 JQ |
2848 | @item CP_INTEGRAL_TYPE |
2849 | This predicate holds if the type is an integral type. Notice that in | |
2850 | C++, enumerations are @emph{not} integral types. | |
e6c99067 | 2851 | |
929769f4 JQ |
2852 | @item ARITHMETIC_TYPE_P |
2853 | This predicate holds if the type is an integral type (in the C++ sense) | |
2854 | or a floating point type. | |
e6c99067 | 2855 | |
929769f4 JQ |
2856 | @item CLASS_TYPE_P |
2857 | This predicate holds for a class-type. | |
e6c99067 | 2858 | |
929769f4 JQ |
2859 | @item TYPE_BUILT_IN |
2860 | This predicate holds for a built-in type. | |
e6c99067 | 2861 | |
39067958 | 2862 | @item TYPE_PTRDATAMEM_P |
929769f4 | 2863 | This predicate holds if the type is a pointer to data member. |
e6c99067 | 2864 | |
929769f4 JQ |
2865 | @item TYPE_PTR_P |
2866 | This predicate holds if the type is a pointer type, and the pointee is | |
2867 | not a data member. | |
e6c99067 | 2868 | |
929769f4 JQ |
2869 | @item TYPE_PTRFN_P |
2870 | This predicate holds for a pointer to function type. | |
e6c99067 | 2871 | |
929769f4 JQ |
2872 | @item TYPE_PTROB_P |
2873 | This predicate holds for a pointer to object type. Note however that it | |
2874 | does not hold for the generic pointer to object type @code{void *}. You | |
2875 | may use @code{TYPE_PTROBV_P} to test for a pointer to object type as | |
2876 | well as @code{void *}. | |
e6c99067 | 2877 | |
929769f4 | 2878 | @end ftable |
e6c99067 | 2879 | |
929769f4 JQ |
2880 | The table below describes types specific to C and C++ as well as |
2881 | language-dependent info about GENERIC types. | |
e6c99067 | 2882 | |
929769f4 | 2883 | @table @code |
e6c99067 | 2884 | |
929769f4 JQ |
2885 | @item POINTER_TYPE |
2886 | Used to represent pointer types, and pointer to data member types. If | |
ff2ce160 | 2887 | @code{TREE_TYPE} |
39067958 | 2888 | is a pointer to data member type, then @code{TYPE_PTRDATAMEM_P} will hold. |
929769f4 JQ |
2889 | For a pointer to data member type of the form @samp{T X::*}, |
2890 | @code{TYPE_PTRMEM_CLASS_TYPE} will be the type @code{X}, while | |
2891 | @code{TYPE_PTRMEM_POINTED_TO_TYPE} will be the type @code{T}. | |
e6c99067 | 2892 | |
929769f4 JQ |
2893 | @item RECORD_TYPE |
2894 | Used to represent @code{struct} and @code{class} types in C and C++. If | |
2895 | @code{TYPE_PTRMEMFUNC_P} holds, then this type is a pointer-to-member | |
2896 | type. In that case, the @code{TYPE_PTRMEMFUNC_FN_TYPE} is a | |
2897 | @code{POINTER_TYPE} pointing to a @code{METHOD_TYPE}. The | |
2898 | @code{METHOD_TYPE} is the type of a function pointed to by the | |
2899 | pointer-to-member function. If @code{TYPE_PTRMEMFUNC_P} does not hold, | |
0d52f2a8 | 2900 | this type is a class type. For more information, @pxref{Classes}. |
e6c99067 | 2901 | |
929769f4 JQ |
2902 | @item UNKNOWN_TYPE |
2903 | This node is used to represent a type the knowledge of which is | |
2904 | insufficient for a sound processing. | |
e6c99067 | 2905 | |
929769f4 JQ |
2906 | @item TYPENAME_TYPE |
2907 | Used to represent a construct of the form @code{typename T::A}. The | |
2908 | @code{TYPE_CONTEXT} is @code{T}; the @code{TYPE_NAME} is an | |
2909 | @code{IDENTIFIER_NODE} for @code{A}. If the type is specified via a | |
2910 | template-id, then @code{TYPENAME_TYPE_FULLNAME} yields a | |
2911 | @code{TEMPLATE_ID_EXPR}. The @code{TREE_TYPE} is non-@code{NULL} if the | |
2912 | node is implicitly generated in support for the implicit typename | |
2913 | extension; in which case the @code{TREE_TYPE} is a type node for the | |
2914 | base-class. | |
2915 | ||
2916 | @item TYPEOF_TYPE | |
2917 | Used to represent the @code{__typeof__} extension. The | |
2918 | @code{TYPE_FIELDS} is the expression the type of which is being | |
2919 | represented. | |
2920 | ||
2921 | @end table | |
2922 | ||
2923 | ||
2924 | @c --------------------------------------------------------------------- | |
2925 | @c Namespaces | |
2926 | @c --------------------------------------------------------------------- | |
2927 | ||
2928 | @node Namespaces | |
2929 | @subsection Namespaces | |
2930 | @cindex namespace, scope | |
2931 | @tindex NAMESPACE_DECL | |
2932 | ||
2933 | The root of the entire intermediate representation is the variable | |
2934 | @code{global_namespace}. This is the namespace specified with @code{::} | |
2935 | in C++ source code. All other namespaces, types, variables, functions, | |
2936 | and so forth can be found starting with this namespace. | |
2937 | ||
2938 | However, except for the fact that it is distinguished as the root of the | |
2939 | representation, the global namespace is no different from any other | |
2940 | namespace. Thus, in what follows, we describe namespaces generally, | |
2941 | rather than the global namespace in particular. | |
2942 | ||
2943 | A namespace is represented by a @code{NAMESPACE_DECL} node. | |
2944 | ||
2945 | The following macros and functions can be used on a @code{NAMESPACE_DECL}: | |
2946 | ||
2947 | @ftable @code | |
2948 | @item DECL_NAME | |
2949 | This macro is used to obtain the @code{IDENTIFIER_NODE} corresponding to | |
2950 | the unqualified name of the name of the namespace (@pxref{Identifiers}). | |
2951 | The name of the global namespace is @samp{::}, even though in C++ the | |
2952 | global namespace is unnamed. However, you should use comparison with | |
2953 | @code{global_namespace}, rather than @code{DECL_NAME} to determine | |
2954 | whether or not a namespace is the global one. An unnamed namespace | |
2955 | will have a @code{DECL_NAME} equal to @code{anonymous_namespace_name}. | |
2956 | Within a single translation unit, all unnamed namespaces will have the | |
2957 | same name. | |
2958 | ||
2959 | @item DECL_CONTEXT | |
2960 | This macro returns the enclosing namespace. The @code{DECL_CONTEXT} for | |
2961 | the @code{global_namespace} is @code{NULL_TREE}. | |
2962 | ||
2963 | @item DECL_NAMESPACE_ALIAS | |
2964 | If this declaration is for a namespace alias, then | |
2965 | @code{DECL_NAMESPACE_ALIAS} is the namespace for which this one is an | |
2966 | alias. | |
2967 | ||
2968 | Do not attempt to use @code{cp_namespace_decls} for a namespace which is | |
2969 | an alias. Instead, follow @code{DECL_NAMESPACE_ALIAS} links until you | |
2970 | reach an ordinary, non-alias, namespace, and call | |
2971 | @code{cp_namespace_decls} there. | |
2972 | ||
2973 | @item DECL_NAMESPACE_STD_P | |
2974 | This predicate holds if the namespace is the special @code{::std} | |
2975 | namespace. | |
2976 | ||
2977 | @item cp_namespace_decls | |
2978 | This function will return the declarations contained in the namespace, | |
2979 | including types, overloaded functions, other namespaces, and so forth. | |
2980 | If there are no declarations, this function will return | |
2981 | @code{NULL_TREE}. The declarations are connected through their | |
2982 | @code{TREE_CHAIN} fields. | |
2983 | ||
2984 | Although most entries on this list will be declarations, | |
2985 | @code{TREE_LIST} nodes may also appear. In this case, the | |
2986 | @code{TREE_VALUE} will be an @code{OVERLOAD}. The value of the | |
2987 | @code{TREE_PURPOSE} is unspecified; back ends should ignore this value. | |
2988 | As with the other kinds of declarations returned by | |
2989 | @code{cp_namespace_decls}, the @code{TREE_CHAIN} will point to the next | |
2990 | declaration in this list. | |
2991 | ||
2992 | For more information on the kinds of declarations that can occur on this | |
2993 | list, @xref{Declarations}. Some declarations will not appear on this | |
2994 | list. In particular, no @code{FIELD_DECL}, @code{LABEL_DECL}, or | |
2995 | @code{PARM_DECL} nodes will appear here. | |
2996 | ||
2997 | This function cannot be used with namespaces that have | |
2998 | @code{DECL_NAMESPACE_ALIAS} set. | |
2999 | ||
3000 | @end ftable | |
3001 | ||
3002 | @c --------------------------------------------------------------------- | |
3003 | @c Classes | |
3004 | @c --------------------------------------------------------------------- | |
3005 | ||
3006 | @node Classes | |
3007 | @subsection Classes | |
3008 | @cindex class, scope | |
3009 | @tindex RECORD_TYPE | |
3010 | @tindex UNION_TYPE | |
3011 | @findex CLASSTYPE_DECLARED_CLASS | |
3012 | @findex TYPE_BINFO | |
3013 | @findex BINFO_TYPE | |
3014 | @findex TYPE_FIELDS | |
3015 | @findex TYPE_VFIELD | |
929769f4 JQ |
3016 | |
3017 | Besides namespaces, the other high-level scoping construct in C++ is the | |
3018 | class. (Throughout this manual the term @dfn{class} is used to mean the | |
3019 | types referred to in the ANSI/ISO C++ Standard as classes; these include | |
3020 | types defined with the @code{class}, @code{struct}, and @code{union} | |
3021 | keywords.) | |
3022 | ||
3023 | A class type is represented by either a @code{RECORD_TYPE} or a | |
3024 | @code{UNION_TYPE}. A class declared with the @code{union} tag is | |
3025 | represented by a @code{UNION_TYPE}, while classes declared with either | |
3026 | the @code{struct} or the @code{class} tag are represented by | |
3027 | @code{RECORD_TYPE}s. You can use the @code{CLASSTYPE_DECLARED_CLASS} | |
3028 | macro to discern whether or not a particular type is a @code{class} as | |
3029 | opposed to a @code{struct}. This macro will be true only for classes | |
3030 | declared with the @code{class} tag. | |
3031 | ||
570e228b | 3032 | Almost all members are available on the @code{TYPE_FIELDS} |
929769f4 JQ |
3033 | list. Given one member, the next can be found by following the |
3034 | @code{TREE_CHAIN}. You should not depend in any way on the order in | |
3035 | which fields appear on this list. All nodes on this list will be | |
3036 | @samp{DECL} nodes. A @code{FIELD_DECL} is used to represent a non-static | |
3037 | data member, a @code{VAR_DECL} is used to represent a static data | |
3038 | member, and a @code{TYPE_DECL} is used to represent a type. Note that | |
3039 | the @code{CONST_DECL} for an enumeration constant will appear on this | |
3040 | list, if the enumeration type was declared in the class. (Of course, | |
3041 | the @code{TYPE_DECL} for the enumeration type will appear here as well.) | |
3042 | There are no entries for base classes on this list. In particular, | |
3043 | there is no @code{FIELD_DECL} for the ``base-class portion'' of an | |
570e228b JJ |
3044 | object. If a function member is overloaded, each of the overloaded |
3045 | functions appears; no @code{OVERLOAD} nodes appear on the @code{TYPE_FIELDS} | |
3046 | list. Implicitly declared functions (including default constructors, | |
3047 | copy constructors, assignment operators, and destructors) will appear on | |
3048 | this list as well. | |
929769f4 JQ |
3049 | |
3050 | The @code{TYPE_VFIELD} is a compiler-generated field used to point to | |
3051 | virtual function tables. It may or may not appear on the | |
3052 | @code{TYPE_FIELDS} list. However, back ends should handle the | |
3053 | @code{TYPE_VFIELD} just like all the entries on the @code{TYPE_FIELDS} | |
3054 | list. | |
3055 | ||
929769f4 JQ |
3056 | Every class has an associated @dfn{binfo}, which can be obtained with |
3057 | @code{TYPE_BINFO}. Binfos are used to represent base-classes. The | |
3058 | binfo given by @code{TYPE_BINFO} is the degenerate case, whereby every | |
3059 | class is considered to be its own base-class. The base binfos for a | |
3060 | particular binfo are held in a vector, whose length is obtained with | |
3061 | @code{BINFO_N_BASE_BINFOS}. The base binfos themselves are obtained | |
3062 | with @code{BINFO_BASE_BINFO} and @code{BINFO_BASE_ITERATE}. To add a | |
3063 | new binfo, use @code{BINFO_BASE_APPEND}. The vector of base binfos can | |
3064 | be obtained with @code{BINFO_BASE_BINFOS}, but normally you do not need | |
3065 | to use that. The class type associated with a binfo is given by | |
3066 | @code{BINFO_TYPE}. It is not always the case that @code{BINFO_TYPE | |
3067 | (TYPE_BINFO (x))}, because of typedefs and qualified types. Neither is | |
3068 | it the case that @code{TYPE_BINFO (BINFO_TYPE (y))} is the same binfo as | |
3069 | @code{y}. The reason is that if @code{y} is a binfo representing a | |
3070 | base-class @code{B} of a derived class @code{D}, then @code{BINFO_TYPE | |
3071 | (y)} will be @code{B}, and @code{TYPE_BINFO (BINFO_TYPE (y))} will be | |
3072 | @code{B} as its own base-class, rather than as a base-class of @code{D}. | |
3073 | ||
3074 | The access to a base type can be found with @code{BINFO_BASE_ACCESS}. | |
3075 | This will produce @code{access_public_node}, @code{access_private_node} | |
3076 | or @code{access_protected_node}. If bases are always public, | |
3077 | @code{BINFO_BASE_ACCESSES} may be @code{NULL}. | |
3078 | ||
3079 | @code{BINFO_VIRTUAL_P} is used to specify whether the binfo is inherited | |
9925bb88 JM |
3080 | virtually or not. The other flags, @code{BINFO_FLAG_0} to |
3081 | @code{BINFO_FLAG_6}, can be used for language specific use. | |
929769f4 JQ |
3082 | |
3083 | The following macros can be used on a tree node representing a class-type. | |
3084 | ||
3085 | @ftable @code | |
3086 | @item LOCAL_CLASS_P | |
3087 | This predicate holds if the class is local class @emph{i.e.}@: declared | |
3088 | inside a function body. | |
3089 | ||
3090 | @item TYPE_POLYMORPHIC_P | |
3091 | This predicate holds if the class has at least one virtual function | |
3092 | (declared or inherited). | |
3093 | ||
3094 | @item TYPE_HAS_DEFAULT_CONSTRUCTOR | |
3095 | This predicate holds whenever its argument represents a class-type with | |
3096 | default constructor. | |
3097 | ||
3098 | @item CLASSTYPE_HAS_MUTABLE | |
3099 | @itemx TYPE_HAS_MUTABLE_P | |
3100 | These predicates hold for a class-type having a mutable data member. | |
3101 | ||
3102 | @item CLASSTYPE_NON_POD_P | |
3103 | This predicate holds only for class-types that are not PODs. | |
3104 | ||
3105 | @item TYPE_HAS_NEW_OPERATOR | |
3106 | This predicate holds for a class-type that defines | |
3107 | @code{operator new}. | |
3108 | ||
3109 | @item TYPE_HAS_ARRAY_NEW_OPERATOR | |
3110 | This predicate holds for a class-type for which | |
3111 | @code{operator new[]} is defined. | |
3112 | ||
3113 | @item TYPE_OVERLOADS_CALL_EXPR | |
3114 | This predicate holds for class-type for which the function call | |
3115 | @code{operator()} is overloaded. | |
3116 | ||
3117 | @item TYPE_OVERLOADS_ARRAY_REF | |
3118 | This predicate holds for a class-type that overloads | |
3119 | @code{operator[]} | |
3120 | ||
3121 | @item TYPE_OVERLOADS_ARROW | |
3122 | This predicate holds for a class-type for which @code{operator->} is | |
3123 | overloaded. | |
3124 | ||
3125 | @end ftable | |
3126 | ||
3127 | @node Functions for C++ | |
3128 | @subsection Functions for C++ | |
3129 | @cindex function | |
3130 | @tindex FUNCTION_DECL | |
3131 | @tindex OVERLOAD | |
3132 | @findex OVL_CURRENT | |
3133 | @findex OVL_NEXT | |
3134 | ||
3135 | A function is represented by a @code{FUNCTION_DECL} node. A set of | |
3136 | overloaded functions is sometimes represented by an @code{OVERLOAD} node. | |
3137 | ||
3138 | An @code{OVERLOAD} node is not a declaration, so none of the | |
3139 | @samp{DECL_} macros should be used on an @code{OVERLOAD}. An | |
3140 | @code{OVERLOAD} node is similar to a @code{TREE_LIST}. Use | |
3141 | @code{OVL_CURRENT} to get the function associated with an | |
3142 | @code{OVERLOAD} node; use @code{OVL_NEXT} to get the next | |
3143 | @code{OVERLOAD} node in the list of overloaded functions. The macros | |
3144 | @code{OVL_CURRENT} and @code{OVL_NEXT} are actually polymorphic; you can | |
3145 | use them to work with @code{FUNCTION_DECL} nodes as well as with | |
3146 | overloads. In the case of a @code{FUNCTION_DECL}, @code{OVL_CURRENT} | |
3147 | will always return the function itself, and @code{OVL_NEXT} will always | |
3148 | be @code{NULL_TREE}. | |
3149 | ||
3150 | To determine the scope of a function, you can use the | |
3151 | @code{DECL_CONTEXT} macro. This macro will return the class | |
3152 | (either a @code{RECORD_TYPE} or a @code{UNION_TYPE}) or namespace (a | |
3153 | @code{NAMESPACE_DECL}) of which the function is a member. For a virtual | |
3154 | function, this macro returns the class in which the function was | |
3155 | actually defined, not the base class in which the virtual declaration | |
3156 | occurred. | |
3157 | ||
3158 | If a friend function is defined in a class scope, the | |
3159 | @code{DECL_FRIEND_CONTEXT} macro can be used to determine the class in | |
3160 | which it was defined. For example, in | |
3161 | @smallexample | |
3162 | class C @{ friend void f() @{@} @}; | |
3163 | @end smallexample | |
3164 | @noindent | |
3165 | the @code{DECL_CONTEXT} for @code{f} will be the | |
3166 | @code{global_namespace}, but the @code{DECL_FRIEND_CONTEXT} will be the | |
3167 | @code{RECORD_TYPE} for @code{C}. | |
3168 | ||
3169 | ||
3170 | The following macros and functions can be used on a @code{FUNCTION_DECL}: | |
3171 | @ftable @code | |
3172 | @item DECL_MAIN_P | |
3173 | This predicate holds for a function that is the program entry point | |
3174 | @code{::code}. | |
3175 | ||
3176 | @item DECL_LOCAL_FUNCTION_P | |
3177 | This predicate holds if the function was declared at block scope, even | |
3178 | though it has a global scope. | |
3179 | ||
3180 | @item DECL_ANTICIPATED | |
3181 | This predicate holds if the function is a built-in function but its | |
3182 | prototype is not yet explicitly declared. | |
3183 | ||
3184 | @item DECL_EXTERN_C_FUNCTION_P | |
3185 | This predicate holds if the function is declared as an | |
3186 | `@code{extern "C"}' function. | |
3187 | ||
3188 | @item DECL_LINKONCE_P | |
3189 | This macro holds if multiple copies of this function may be emitted in | |
3190 | various translation units. It is the responsibility of the linker to | |
3191 | merge the various copies. Template instantiations are the most common | |
3192 | example of functions for which @code{DECL_LINKONCE_P} holds; G++ | |
3193 | instantiates needed templates in all translation units which require them, | |
3194 | and then relies on the linker to remove duplicate instantiations. | |
3195 | ||
3196 | FIXME: This macro is not yet implemented. | |
3197 | ||
3198 | @item DECL_FUNCTION_MEMBER_P | |
3199 | This macro holds if the function is a member of a class, rather than a | |
3200 | member of a namespace. | |
3201 | ||
3202 | @item DECL_STATIC_FUNCTION_P | |
3203 | This predicate holds if the function a static member function. | |
3204 | ||
3205 | @item DECL_NONSTATIC_MEMBER_FUNCTION_P | |
3206 | This macro holds for a non-static member function. | |
3207 | ||
3208 | @item DECL_CONST_MEMFUNC_P | |
3209 | This predicate holds for a @code{const}-member function. | |
3210 | ||
3211 | @item DECL_VOLATILE_MEMFUNC_P | |
3212 | This predicate holds for a @code{volatile}-member function. | |
3213 | ||
3214 | @item DECL_CONSTRUCTOR_P | |
3215 | This macro holds if the function is a constructor. | |
3216 | ||
3217 | @item DECL_NONCONVERTING_P | |
3218 | This predicate holds if the constructor is a non-converting constructor. | |
3219 | ||
3220 | @item DECL_COMPLETE_CONSTRUCTOR_P | |
3221 | This predicate holds for a function which is a constructor for an object | |
3222 | of a complete type. | |
3223 | ||
3224 | @item DECL_BASE_CONSTRUCTOR_P | |
3225 | This predicate holds for a function which is a constructor for a base | |
3226 | class sub-object. | |
3227 | ||
3228 | @item DECL_COPY_CONSTRUCTOR_P | |
3229 | This predicate holds for a function which is a copy-constructor. | |
3230 | ||
3231 | @item DECL_DESTRUCTOR_P | |
3232 | This macro holds if the function is a destructor. | |
3233 | ||
3234 | @item DECL_COMPLETE_DESTRUCTOR_P | |
3235 | This predicate holds if the function is the destructor for an object a | |
3236 | complete type. | |
3237 | ||
3238 | @item DECL_OVERLOADED_OPERATOR_P | |
3239 | This macro holds if the function is an overloaded operator. | |
3240 | ||
3241 | @item DECL_CONV_FN_P | |
3242 | This macro holds if the function is a type-conversion operator. | |
3243 | ||
3244 | @item DECL_GLOBAL_CTOR_P | |
3245 | This predicate holds if the function is a file-scope initialization | |
3246 | function. | |
3247 | ||
3248 | @item DECL_GLOBAL_DTOR_P | |
3249 | This predicate holds if the function is a file-scope finalization | |
3250 | function. | |
3251 | ||
3252 | @item DECL_THUNK_P | |
3253 | This predicate holds if the function is a thunk. | |
3254 | ||
3255 | These functions represent stub code that adjusts the @code{this} pointer | |
3256 | and then jumps to another function. When the jumped-to function | |
3257 | returns, control is transferred directly to the caller, without | |
3258 | returning to the thunk. The first parameter to the thunk is always the | |
3259 | @code{this} pointer; the thunk should add @code{THUNK_DELTA} to this | |
3260 | value. (The @code{THUNK_DELTA} is an @code{int}, not an | |
3261 | @code{INTEGER_CST}.) | |
3262 | ||
3263 | Then, if @code{THUNK_VCALL_OFFSET} (an @code{INTEGER_CST}) is nonzero | |
3264 | the adjusted @code{this} pointer must be adjusted again. The complete | |
3265 | calculation is given by the following pseudo-code: | |
3266 | ||
3267 | @smallexample | |
3268 | this += THUNK_DELTA | |
3269 | if (THUNK_VCALL_OFFSET) | |
3270 | this += (*((ptrdiff_t **) this))[THUNK_VCALL_OFFSET] | |
3271 | @end smallexample | |
3272 | ||
3273 | Finally, the thunk should jump to the location given | |
3274 | by @code{DECL_INITIAL}; this will always be an expression for the | |
3275 | address of a function. | |
3276 | ||
3277 | @item DECL_NON_THUNK_FUNCTION_P | |
3278 | This predicate holds if the function is @emph{not} a thunk function. | |
3279 | ||
3280 | @item GLOBAL_INIT_PRIORITY | |
3281 | If either @code{DECL_GLOBAL_CTOR_P} or @code{DECL_GLOBAL_DTOR_P} holds, | |
3282 | then this gives the initialization priority for the function. The | |
3283 | linker will arrange that all functions for which | |
3284 | @code{DECL_GLOBAL_CTOR_P} holds are run in increasing order of priority | |
3285 | before @code{main} is called. When the program exits, all functions for | |
3286 | which @code{DECL_GLOBAL_DTOR_P} holds are run in the reverse order. | |
3287 | ||
3288 | @item TYPE_RAISES_EXCEPTIONS | |
3289 | This macro returns the list of exceptions that a (member-)function can | |
3290 | raise. The returned list, if non @code{NULL}, is comprised of nodes | |
3291 | whose @code{TREE_VALUE} represents a type. | |
3292 | ||
3293 | @item TYPE_NOTHROW_P | |
3294 | This predicate holds when the exception-specification of its arguments | |
3295 | is of the form `@code{()}'. | |
3296 | ||
3297 | @item DECL_ARRAY_DELETE_OPERATOR_P | |
3298 | This predicate holds if the function an overloaded | |
3299 | @code{operator delete[]}. | |
3300 | ||
3301 | @end ftable | |
3302 | ||
3303 | @c --------------------------------------------------------------------- | |
3304 | @c Function Bodies | |
3305 | @c --------------------------------------------------------------------- | |
3306 | ||
cba079f3 SL |
3307 | @node Statements for C and C++ |
3308 | @subsection Statements for C and C++ | |
929769f4 JQ |
3309 | @cindex statements |
3310 | @tindex BREAK_STMT | |
3311 | @tindex CLEANUP_STMT | |
3312 | @findex CLEANUP_DECL | |
3313 | @findex CLEANUP_EXPR | |
3314 | @tindex CONTINUE_STMT | |
3315 | @tindex DECL_STMT | |
3316 | @findex DECL_STMT_DECL | |
3317 | @tindex DO_STMT | |
3318 | @findex DO_BODY | |
3319 | @findex DO_COND | |
3320 | @tindex EMPTY_CLASS_EXPR | |
3321 | @tindex EXPR_STMT | |
3322 | @findex EXPR_STMT_EXPR | |
3323 | @tindex FOR_STMT | |
3324 | @findex FOR_INIT_STMT | |
3325 | @findex FOR_COND | |
3326 | @findex FOR_EXPR | |
3327 | @findex FOR_BODY | |
3328 | @tindex HANDLER | |
3329 | @tindex IF_STMT | |
3330 | @findex IF_COND | |
3331 | @findex THEN_CLAUSE | |
3332 | @findex ELSE_CLAUSE | |
3333 | @tindex RETURN_STMT | |
3334 | @findex RETURN_EXPR | |
3335 | @tindex SUBOBJECT | |
3336 | @findex SUBOBJECT_CLEANUP | |
3337 | @tindex SWITCH_STMT | |
3338 | @findex SWITCH_COND | |
3339 | @findex SWITCH_BODY | |
3340 | @tindex TRY_BLOCK | |
3341 | @findex TRY_STMTS | |
3342 | @findex TRY_HANDLERS | |
3343 | @findex HANDLER_PARMS | |
3344 | @findex HANDLER_BODY | |
3345 | @findex USING_STMT | |
3346 | @tindex WHILE_STMT | |
3347 | @findex WHILE_BODY | |
3348 | @findex WHILE_COND | |
3349 | ||
cba079f3 SL |
3350 | A function that has a definition in the current translation unit has |
3351 | a non-@code{NULL} @code{DECL_INITIAL}. However, back ends should not make | |
929769f4 JQ |
3352 | use of the particular value given by @code{DECL_INITIAL}. |
3353 | ||
cba079f3 | 3354 | The @code{DECL_SAVED_TREE} gives the complete body of the |
929769f4 JQ |
3355 | function. |
3356 | ||
929769f4 JQ |
3357 | There are tree nodes corresponding to all of the source-level |
3358 | statement constructs, used within the C and C++ frontends. These are | |
3359 | enumerated here, together with a list of the various macros that can | |
3360 | be used to obtain information about them. There are a few macros that | |
3361 | can be used with all statements: | |
3362 | ||
3363 | @ftable @code | |
3364 | @item STMT_IS_FULL_EXPR_P | |
3365 | In C++, statements normally constitute ``full expressions''; temporaries | |
3366 | created during a statement are destroyed when the statement is complete. | |
3367 | However, G++ sometimes represents expressions by statements; these | |
3368 | statements will not have @code{STMT_IS_FULL_EXPR_P} set. Temporaries | |
3369 | created during such statements should be destroyed when the innermost | |
3370 | enclosing statement with @code{STMT_IS_FULL_EXPR_P} set is exited. | |
3371 | ||
3372 | @end ftable | |
3373 | ||
3374 | Here is the list of the various statement nodes, and the macros used to | |
3375 | access them. This documentation describes the use of these nodes in | |
3376 | non-template functions (including instantiations of template functions). | |
3377 | In template functions, the same nodes are used, but sometimes in | |
3378 | slightly different ways. | |
3379 | ||
3380 | Many of the statements have substatements. For example, a @code{while} | |
cba079f3 | 3381 | loop has a body, which is itself a statement. If the substatement |
929769f4 JQ |
3382 | is @code{NULL_TREE}, it is considered equivalent to a statement |
3383 | consisting of a single @code{;}, i.e., an expression statement in which | |
3384 | the expression has been omitted. A substatement may in fact be a list | |
3385 | of statements, connected via their @code{TREE_CHAIN}s. So, you should | |
3386 | always process the statement tree by looping over substatements, like | |
3387 | this: | |
3388 | @smallexample | |
3389 | void process_stmt (stmt) | |
3390 | tree stmt; | |
3391 | @{ | |
3392 | while (stmt) | |
3393 | @{ | |
3394 | switch (TREE_CODE (stmt)) | |
3395 | @{ | |
3396 | case IF_STMT: | |
3397 | process_stmt (THEN_CLAUSE (stmt)); | |
3398 | /* @r{More processing here.} */ | |
3399 | break; | |
3400 | ||
3401 | @dots{} | |
3402 | @} | |
3403 | ||
3404 | stmt = TREE_CHAIN (stmt); | |
3405 | @} | |
3406 | @} | |
3407 | @end smallexample | |
3408 | In other words, while the @code{then} clause of an @code{if} statement | |
3409 | in C++ can be only one statement (although that one statement may be a | |
cba079f3 | 3410 | compound statement), the intermediate representation sometimes uses |
929769f4 JQ |
3411 | several statements chained together. |
3412 | ||
3413 | @table @code | |
3414 | @item BREAK_STMT | |
3415 | ||
3416 | Used to represent a @code{break} statement. There are no additional | |
3417 | fields. | |
3418 | ||
3419 | @item CLEANUP_STMT | |
3420 | ||
3421 | Used to represent an action that should take place upon exit from the | |
3422 | enclosing scope. Typically, these actions are calls to destructors for | |
3423 | local objects, but back ends cannot rely on this fact. If these nodes | |
3424 | are in fact representing such destructors, @code{CLEANUP_DECL} will be | |
3425 | the @code{VAR_DECL} destroyed. Otherwise, @code{CLEANUP_DECL} will be | |
3426 | @code{NULL_TREE}. In any case, the @code{CLEANUP_EXPR} is the | |
3427 | expression to execute. The cleanups executed on exit from a scope | |
3428 | should be run in the reverse order of the order in which the associated | |
3429 | @code{CLEANUP_STMT}s were encountered. | |
3430 | ||
3431 | @item CONTINUE_STMT | |
3432 | ||
3433 | Used to represent a @code{continue} statement. There are no additional | |
3434 | fields. | |
3435 | ||
3436 | @item CTOR_STMT | |
3437 | ||
3438 | Used to mark the beginning (if @code{CTOR_BEGIN_P} holds) or end (if | |
3439 | @code{CTOR_END_P} holds of the main body of a constructor. See also | |
3440 | @code{SUBOBJECT} for more information on how to use these nodes. | |
3441 | ||
3442 | @item DO_STMT | |
3443 | ||
3444 | Used to represent a @code{do} loop. The body of the loop is given by | |
3445 | @code{DO_BODY} while the termination condition for the loop is given by | |
3446 | @code{DO_COND}. The condition for a @code{do}-statement is always an | |
3447 | expression. | |
3448 | ||
3449 | @item EMPTY_CLASS_EXPR | |
3450 | ||
3451 | Used to represent a temporary object of a class with no data whose | |
3452 | address is never taken. (All such objects are interchangeable.) The | |
3453 | @code{TREE_TYPE} represents the type of the object. | |
3454 | ||
3455 | @item EXPR_STMT | |
3456 | ||
3457 | Used to represent an expression statement. Use @code{EXPR_STMT_EXPR} to | |
3458 | obtain the expression. | |
3459 | ||
3460 | @item FOR_STMT | |
3461 | ||
3462 | Used to represent a @code{for} statement. The @code{FOR_INIT_STMT} is | |
3463 | the initialization statement for the loop. The @code{FOR_COND} is the | |
3464 | termination condition. The @code{FOR_EXPR} is the expression executed | |
3465 | right before the @code{FOR_COND} on each loop iteration; often, this | |
3466 | expression increments a counter. The body of the loop is given by | |
cba079f3 SL |
3467 | @code{FOR_BODY}. @code{FOR_SCOPE} holds the scope of the @code{for} |
3468 | statement (used in the C++ front end only). Note that | |
3469 | @code{FOR_INIT_STMT} and @code{FOR_BODY} return statements, while | |
3470 | @code{FOR_COND} and @code{FOR_EXPR} return expressions. | |
929769f4 JQ |
3471 | |
3472 | @item HANDLER | |
3473 | ||
3474 | Used to represent a C++ @code{catch} block. The @code{HANDLER_TYPE} | |
3475 | is the type of exception that will be caught by this handler; it is | |
3476 | equal (by pointer equality) to @code{NULL} if this handler is for all | |
3477 | types. @code{HANDLER_PARMS} is the @code{DECL_STMT} for the catch | |
3478 | parameter, and @code{HANDLER_BODY} is the code for the block itself. | |
3479 | ||
3480 | @item IF_STMT | |
3481 | ||
3482 | Used to represent an @code{if} statement. The @code{IF_COND} is the | |
3483 | expression. | |
3484 | ||
3485 | If the condition is a @code{TREE_LIST}, then the @code{TREE_PURPOSE} is | |
3486 | a statement (usually a @code{DECL_STMT}). Each time the condition is | |
3487 | evaluated, the statement should be executed. Then, the | |
3488 | @code{TREE_VALUE} should be used as the conditional expression itself. | |
3489 | This representation is used to handle C++ code like this: | |
3490 | ||
929769f4 JQ |
3491 | @smallexample |
3492 | if (int i = 7) @dots{} | |
3493 | @end smallexample | |
3494 | ||
3495 | where there is a new local variable (or variables) declared within the | |
3496 | condition. | |
3497 | ||
3498 | The @code{THEN_CLAUSE} represents the statement given by the @code{then} | |
3499 | condition, while the @code{ELSE_CLAUSE} represents the statement given | |
3500 | by the @code{else} condition. | |
3501 | ||
cba079f3 SL |
3502 | C++ distinguishes between this and @code{COND_EXPR} for handling templates. |
3503 | ||
929769f4 JQ |
3504 | @item SUBOBJECT |
3505 | ||
3506 | In a constructor, these nodes are used to mark the point at which a | |
3507 | subobject of @code{this} is fully constructed. If, after this point, an | |
3508 | exception is thrown before a @code{CTOR_STMT} with @code{CTOR_END_P} set | |
3509 | is encountered, the @code{SUBOBJECT_CLEANUP} must be executed. The | |
3510 | cleanups must be executed in the reverse order in which they appear. | |
3511 | ||
3512 | @item SWITCH_STMT | |
3513 | ||
3514 | Used to represent a @code{switch} statement. The @code{SWITCH_STMT_COND} | |
3515 | is the expression on which the switch is occurring. See the documentation | |
3516 | for an @code{IF_STMT} for more information on the representation used | |
3517 | for the condition. The @code{SWITCH_STMT_BODY} is the body of the switch | |
3518 | statement. The @code{SWITCH_STMT_TYPE} is the original type of switch | |
3519 | expression as given in the source, before any compiler conversions. | |
cba079f3 SL |
3520 | The @code{SWITCH_STMT_SCOPE} is the statement scope (used in the |
3521 | C++ front end only). | |
3522 | ||
3523 | There are also two boolean flags used with @code{SWITCH_STMT}. | |
3524 | @code{SWITCH_STMT_ALL_CASES_P} is true if the switch includes a default label | |
3525 | or the case label ranges cover all possible values of the condition | |
3526 | expression. @code{SWITCH_STMT_NO_BREAK_P} is true if there are no | |
3527 | @code{break} statements in the switch. | |
929769f4 JQ |
3528 | |
3529 | @item TRY_BLOCK | |
3530 | Used to represent a @code{try} block. The body of the try block is | |
3531 | given by @code{TRY_STMTS}. Each of the catch blocks is a @code{HANDLER} | |
3532 | node. The first handler is given by @code{TRY_HANDLERS}. Subsequent | |
3533 | handlers are obtained by following the @code{TREE_CHAIN} link from one | |
3534 | handler to the next. The body of the handler is given by | |
3535 | @code{HANDLER_BODY}. | |
3536 | ||
3537 | If @code{CLEANUP_P} holds of the @code{TRY_BLOCK}, then the | |
3538 | @code{TRY_HANDLERS} will not be a @code{HANDLER} node. Instead, it will | |
3539 | be an expression that should be executed if an exception is thrown in | |
3540 | the try block. It must rethrow the exception after executing that code. | |
3541 | And, if an exception is thrown while the expression is executing, | |
3542 | @code{terminate} must be called. | |
3543 | ||
3544 | @item USING_STMT | |
3545 | Used to represent a @code{using} directive. The namespace is given by | |
3546 | @code{USING_STMT_NAMESPACE}, which will be a NAMESPACE_DECL@. This node | |
3547 | is needed inside template functions, to implement using directives | |
3548 | during instantiation. | |
3549 | ||
3550 | @item WHILE_STMT | |
3551 | ||
3552 | Used to represent a @code{while} loop. The @code{WHILE_COND} is the | |
3553 | termination condition for the loop. See the documentation for an | |
3554 | @code{IF_STMT} for more information on the representation used for the | |
3555 | condition. | |
3556 | ||
3557 | The @code{WHILE_BODY} is the body of the loop. | |
3558 | ||
3559 | @end table | |
3560 | ||
3561 | @node C++ Expressions | |
3562 | @subsection C++ Expressions | |
3563 | ||
3564 | This section describes expressions specific to the C and C++ front | |
3565 | ends. | |
3566 | ||
3567 | @table @code | |
3568 | @item TYPEID_EXPR | |
3569 | ||
3570 | Used to represent a @code{typeid} expression. | |
3571 | ||
3572 | @item NEW_EXPR | |
3573 | @itemx VEC_NEW_EXPR | |
3574 | ||
3575 | Used to represent a call to @code{new} and @code{new[]} respectively. | |
3576 | ||
3577 | @item DELETE_EXPR | |
3578 | @itemx VEC_DELETE_EXPR | |
3579 | ||
3580 | Used to represent a call to @code{delete} and @code{delete[]} respectively. | |
3581 | ||
3582 | @item MEMBER_REF | |
3583 | ||
3584 | Represents a reference to a member of a class. | |
3585 | ||
3586 | @item THROW_EXPR | |
3587 | ||
3588 | Represents an instance of @code{throw} in the program. Operand 0, | |
3589 | which is the expression to throw, may be @code{NULL_TREE}. | |
3590 | ||
3591 | ||
3592 | @item AGGR_INIT_EXPR | |
3593 | An @code{AGGR_INIT_EXPR} represents the initialization as the return | |
3594 | value of a function call, or as the result of a constructor. An | |
3595 | @code{AGGR_INIT_EXPR} will only appear as a full-expression, or as the | |
3596 | second operand of a @code{TARGET_EXPR}. @code{AGGR_INIT_EXPR}s have | |
3597 | a representation similar to that of @code{CALL_EXPR}s. You can use | |
3598 | the @code{AGGR_INIT_EXPR_FN} and @code{AGGR_INIT_EXPR_ARG} macros to access | |
3599 | the function to call and the arguments to pass. | |
3600 | ||
3601 | If @code{AGGR_INIT_VIA_CTOR_P} holds of the @code{AGGR_INIT_EXPR}, then | |
3602 | the initialization is via a constructor call. The address of the | |
3603 | @code{AGGR_INIT_EXPR_SLOT} operand, which is always a @code{VAR_DECL}, | |
3604 | is taken, and this value replaces the first argument in the argument | |
3605 | list. | |
3606 | ||
3607 | In either case, the expression is void. | |
3608 | ||
3609 | ||
3610 | @end table |