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