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