ircons.h 131 KB
Newer Older
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1
2
3
4
5
6
7
8
9
10
11
12
/*
 * Project:     libFIRM
 * File name:   ir/ir/ircons.h
 * Purpose:     Various irnode constructors.  Automatic construction
 *              of SSA representation.
 * Author:      Martin Trapp, Christian Schaefer
 * Modified by: Goetz Lindenmaier, Boris Boesler
 * Created:
 * CVS-ID:      $Id$
 * Copyright:   (c) 1998-2003 Universität Karlsruhe
 * Licence:     This file protected by GPL -  GNU GENERAL PUBLIC LICENSE.
 */
Christian Schäfer's avatar
Christian Schäfer committed
13

Sebastian Felis's avatar
Sebastian Felis committed
14
/**
Michael Beck's avatar
Michael Beck committed
15
16
17
18
19
20
21
22
23
24
 @todo
 Ideas for imrovement:
 -# Handle construction of exceptions more comfortable:
    Add new constructors that pass the exception region (or better the
    Phi for the memories, the ex. region can be found from there) as parameter,
    constructor then adds all Proj nodes and returns the pointer
    to the Proj node that selects the result of the arithmetic operation.
 -# Maybe hide the exception region in a global variable, especially if
    it is always unambiguous.
*/
Christian Schäfer's avatar
Christian Schäfer committed
25

Sebastian Felis's avatar
Sebastian Felis committed
26
/**
Michael Beck's avatar
Michael Beck committed
27
28
 *  @file ircons.h
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
29
30
 *  documentation no more supported since 2001
 *
Michael Beck's avatar
Michael Beck committed
31
 *  ir node construction.
Boris Boesler's avatar
Boris Boesler committed
32
 *
Michael Beck's avatar
Michael Beck committed
33
 *  @author Martin Trapp, Christian Schaefer, Goetz Lindenmaier
Boris Boesler's avatar
Boris Boesler committed
34
 *
Boris Boesler's avatar
Boris Boesler committed
35
 *    This file documents all datatypes and constructors needed to
Götz Lindenmaier's avatar
Götz Lindenmaier committed
36
 *    build a FIRM representation of a procedure.  The constructors are
Boris Boesler's avatar
Boris Boesler committed
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 *    also implemented in this file.
 *
 *    The documentation also gives a short manual how to use the library.
 *
 *    For extensive documentation of FIRM see UKA Techreport 1999-14.
 *
 *    =========
 *
 *    The struct ir_graph
 *    -------------------
 *
 *      This struct contains all information about a procedure.
 *      It's allocated directly to memory.
 *
 *      The fields of ir_graph:
 *
 *      *ent             The entity describing this procedure.
 *
 *      The beginning and end of a graph:
 *
 *      *start_block     This ir_node is the block that contains the unique
 *                       start node of the procedure.  With it it contains
 *                       the Proj's on starts results.
 *                       Further all Const nodes are placed in the start block.
 *      *start           This ir_node is the unique start node of the procedure.
 *
 *      *end_block       This ir_node is the block that contains the unique
 *                       end node of the procedure.  This block contains no
 *                       further nodes.
 *      *end             This ir_node is the unique end node of the procedure.
 *
 *      The following nodes are Projs from the start node, held in ir_graph for
 *      simple access:
 *
 *      *frame           The ir_node producing the pointer to the stack frame of
 *                       the procedure as output.  This is the Proj node on the
 *                       third output of the start node.  This output of the start
Götz Lindenmaier's avatar
Götz Lindenmaier committed
74
 *                      node is tagged as pns_frame_base.  In FIRM most lokal
Boris Boesler's avatar
Boris Boesler committed
75
76
77
78
79
 *                       variables are modeled as data flow edges.  Static
 *                       allocated arrays can not be represented as dataflow
 *                       edges. Therefore FIRM has to represent them in the stack
 *                       frame.
 *
80
81
82
83
 *      *globals         This models a pointer to a space in the memory where
 *               _all_ global things are held.  Select from this pointer
 *               with a Sel node the pointer to a global variable /
 *               procedure / compiler known function... .
Boris Boesler's avatar
Boris Boesler committed
84
 *
85
86
87
 *      *args        The ir_node that produces the arguments of the method as
 *               it's result.  This is a Proj node on the fourth output of
 *               the start node.  This output is tagged as pns_args.
Boris Boesler's avatar
Boris Boesler committed
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 *
 *      *bad             The bad node is an auxiliary node. It is needed only once,
 *                       so there is this globally reachable node.
 *
 *      Datastructures that are private to a graph:
 *
 *      *obst            An obstack that contains all nodes.
 *
 *      *current_block   A pointer to the current block.  Any node created with
 *                       one of the node constructors (new_<opcode>) are assigned
 *                       to this block.  It can be set with switch_block(block).
 *                       Only needed for ir construction.
 *
 *      params/n_loc     An int giving the number of local variables in this
102
103
 *               procedure.  This is neede for ir construction. Name will
 *               be changed.
Boris Boesler's avatar
Boris Boesler committed
104
105
 *
 *      *value_table     This hash table (pset) is used for global value numbering
106
 *               for optimizing use in iropt.c.
Boris Boesler's avatar
Boris Boesler committed
107
108
 *
 *      *Phi_in_stack;   a stack needed for automatic Phi construction, needed only
109
 *               during ir construction.
Boris Boesler's avatar
Boris Boesler committed
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 *
 *      visited          A int used as flag to traverse the ir_graph.
 *
 *      block_visited    A int used as a flag to traverse block nodes in the graph.
 *
 *    Three kinds of nodes
 *    --------------------
 *
 *      There are three kinds of nodes known to the ir:  entities,
 *      types, and ir_nodes
 *
 *      + ir_nodes are the actual nodes of the FIRM intermediate representation.
 *        They represent operations on the data of the program and control flow
 *        operations.
 *
 *      + entity ==> implemented in entity.h
 *        Refers to a single entity of the compiled program, e.g. a field of a
 *        class or a method.  If a method or variable can not be assigned to
 *        a method or class or the like, it is a global object.
 *
 *      + types ==> implemented in type.h
 *        With types type information is represented.  There are several type
Götz Lindenmaier's avatar
Götz Lindenmaier committed
132
 *       nodes.
Boris Boesler's avatar
Boris Boesler committed
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 *
 *    Implementation of the FIRM operations: ir_node
 *    ----------------------------------------------
 *
 *      Ir_nodes represent operations on the data of the program and control flow
 *      operations.  Examples of ir_nodes:  Add, Jmp, Cmp
 *
 *      FIRM is a dataflow graph.  A dataflow graph is a directed graph,
 *      so that every node has incoming and outgoing edges.  A node is
 *      executable if every input at it's incoming edges is available.
 *      Execution of the dataflow graph is started at the Start node which
 *      has no incoming edges and ends when the End node executes, even if
 *      there are still executable or not executed nodes.  (Is this true,
 *      or must all executable nodes be executed?)  (There are exceptions
 *      to the dataflow paradigma that all inputs have to be available
 *      before a node can execute: Phi, Block.  See UKA Techreport
 *      1999-14.)
 *
 *      The implementation of FIRM differs from the view as a dataflow
 *      graph.  To allow fast traversion of the graph edges are
 *      implemented as C-pointers.  Inputs to nodes are not ambiguous, the
 *      results can be used by several other nodes.  Each input can be
 *      implemented as a single pointer to a predecessor node, outputs
 *      need to be lists of pointers to successors.  Therefore a node
 *      contains pointers to it's predecessor so that the implementation is a
 *      dataflow graph with reversed edges.  It has to be traversed bottom
 *      up.
 *
 *      All nodes of the ir have the same basic structure.  They are
 *      distinguished by a field containing the opcode.
 *
 *      The fields of an ir_node:
 *
 *      kind             A firm_kind tag containing k_ir_node.  This is useful for
 *                       dynamically checking the type of a node.
 *
 *      *op              This ir_op gives the opcode as a tag and a string
 *                       and the number of attributes of an ir_node.  There is
 *                       one statically allocated struct ir_op for each opcode.
 *
 *      *mode            The ir_mode of the operation represented by this firm
Götz Lindenmaier's avatar
Götz Lindenmaier committed
174
 *                      node.  The mode of the operation is the mode of it's
Boris Boesler's avatar
Boris Boesler committed
175
 *                       result.  A Firm mode is a datatype as known to the target,
176
 *               not a type of the source language.
Boris Boesler's avatar
Boris Boesler committed
177
178
179
180
181
182
183
184
185
186
 *
 *      visit            A flag for traversing the ir.
 *
 *      **in             An array with pointers to the node's predecessors.
 *
 *      *link            A pointer to an ir_node.  With this pointer all Phi nodes
 *                       are attached to a Block, i.e., a Block points to it's
 *                       first Phi node, this node points to the second Phi node
 *                       in the Block and so fourth.  Used in mature_block
 *                       to find all Phi nodes to be matured.  It's also used to
187
 *               annotate a node with a better, optimized version of it.
Boris Boesler's avatar
Boris Boesler committed
188
189
190
 *
 *      attr             An attr struct containing the attributes of the nodes. The
 *                       attributes depend on the opcode of the node.  The number
191
 *               of these attributes is given in op.
Boris Boesler's avatar
Boris Boesler committed
192
193
194
195
196
197
198
199
200
 *
 *    The struct ir_op
 *    ----------------
 *                       Not yet documented. See irop.h.
 *
 *    The struct ir_mode
 *    ------------------
 *                       Not yet documented. See irmode.h.
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
201
 *    GLOBAL VARIABLES -- now also fields of ir_graph.
Boris Boesler's avatar
Boris Boesler committed
202
203
204
 *    ================
 *
 *    current_ir_graph   Points to the current ir_graph.  All constructors for
Götz Lindenmaier's avatar
Götz Lindenmaier committed
205
 *                      nodes add nodes to this graph.
Boris Boesler's avatar
Boris Boesler committed
206
207
208
209
210
211
212
213
214
215
 *
 *    ir_visited         An int used as flag to traverse the ir_graph.
 *
 *    block_visited      An int used as a flag to traverse block nodes in the
 *                       graph.
 *
 *                       Others not yet documented.
 *
 *
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
216
 *    CONSTRUCTOR FOR IR_GRAPH --> see irgraph.h
Boris Boesler's avatar
Boris Boesler committed
217
218
219
 *    ========================
 *
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
220
 *    PROCEDURE TO CONSTRUCT AN IR GRAPH --> see also Firm tutorial
Boris Boesler's avatar
Boris Boesler committed
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
 *    ==================================
 *
 *    This library supplies several interfaces to construct a FIRM graph for
 *    a program:
 *    * A "comfortable" interface generating SSA automatically.  Automatically
 *      computed predecessors of nodes need not be specified in the constructors.
 *      (new_<Node> constructurs and a set of additional routines.)
 *    * A less comfortable interface where all predecessors except the block
 *      an operation belongs to need to be specified.  SSA must be constructed
 *      by hand.  (new_<Node> constructors and switch_block()).  This interface
 *      is called "block oriented".  It automatically calles the local optimizations
 *      for each new node.
 *    * An even less comfortable interface where the block needs to be specified
 *      explicitly.  This is called the "raw" interface. (new_r_<Node>
 *      constructors).  These nodes are not optimized.
 *
 *    To use the functionality of the comfortable interface correctly the Front
 *    End needs to follow certain protocols.  This is explained in the following.
 *    To build a correct IR with the other interfaces study the semantics of
Götz Lindenmaier's avatar
Götz Lindenmaier committed
240
 *    the firm node (See tech-reprot UKA 1999-14).  For the construction of
Boris Boesler's avatar
Boris Boesler committed
241
242
243
244
245
 *    types and entities see the documentation in those modules.
 *
 *    First the Frontend needs to decide which variables and values used in
 *    a procedure can be represented by dataflow edges.  These are variables
 *    that need not be saved to memory as they cause no side effects visible
Götz Lindenmaier's avatar
Götz Lindenmaier committed
246
 *    out of the procedure.  Often these are all compiler generated
Boris Boesler's avatar
Boris Boesler committed
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 *    variables and simple local variables of the procedure as integers,
 *    reals and pointers.  The frontend has to count and number these variables.
 *
 *    First an ir_graph needs to be constructed with new_ir_graph.  The
 *    constructor gets the number of local variables.  The graph is hold in the
 *    global variable irg.
 *
 *    Now the construction of the procedure can start.  Several basic blocks can
 *    be constructed in parallel, but the code within each block needs to
 *    be constructed (almost) in program order.
 *
 *    A global variable holds the current basic block.  All (non block) nodes
 *    generated are added to this block.  The current block can be set with
 *    switch_block(block).  If several blocks are constructed in parallel block
 *    switches need to be performed constantly.
 *
 *    To generate a Block node (with the comfortable interface) it's predecessor
 *    control flow nodes need not be known.  In case of cyclic control flow these
 *    can not be known when the block is constructed.  With add_in_edge(block,
 *    cfnode) predecessors can be added to the block.  If all predecessors are
 *    added to the block mature_block(b) needs to be called.  Calling mature_block
 *    early improves the efficiency of the Phi node construction algorithm.
 *    But if several  blocks are constructed at once, mature_block must only
 *    be called after performing all set_values and set_stores in the block!
 *    (See documentation of new_immBlock constructor.)
 *
 *    The constructors of arithmetic nodes require that their predecessors
 *    are mentioned.  Sometimes these are available in the Frontend as the
 *    predecessors have just been generated by the frontend.  If they are local
 *    values the predecessors can be obtained from the library with a call to
 *    get_value(local_val_nr).  (local_val_nr needs to be administered by
 *    the Frontend.)  A call to get_value triggers the generation of Phi nodes.
 *    If an arithmetic operation produces a local value this value needs to be
 *    passed to the library by set_value(node, local_val_nr).
 *    In straight line code these two operations just remember and return the
 *    pointer to nodes producing the value.  If the value passes block boundaries
 *    Phi nodes can be inserted.
 *    Similar routines exist to manage the Memory operands: set_store and
 *    get_store.
 *
 *    Several nodes produce more than one result.  An example is the Div node.
 *    Such nodes return tuples of values.  From these individual values can be
 *    extracted by proj nodes.
 *
 *    The following example illustrates the construction of a simple basic block
 *    with two predecessors stored in variables cf_pred1 and cf_pred2, containing
 *    the code
 *      a = a div a;
 *    and finally jumping to an other block.  The variable a got the local_val_nr
 *    42 by the frontend.
 *
 *    ir_node *this_block, *cf_pred1, *cf_pred2, *a_val, *mem, *div, *res, *cf_op;
 *
 *    this_block = new_immBlock();
 *    add_in_edge(this_block, cf_pred1);
 *    add_in_edge(this_block, cf_pred2);
 *    mature_block(this_block);
Matthias Heil's avatar
Matthias Heil committed
304
 *    a_val = get_value(42, mode_Iu);
Boris Boesler's avatar
Boris Boesler committed
305
306
307
 *    mem = get_store();
 *    div = new_Div(mem, a_val, a_val);
 *    mem = new_Proj(div, mode_M, 0);   * for the numbers for Proj see docu *
Matthias Heil's avatar
Matthias Heil committed
308
 *    res = new_Proj(div, mode_Iu, 2);
Boris Boesler's avatar
Boris Boesler committed
309
 *    set_store(mem);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
310
 *    set_value(res, 42);
Boris Boesler's avatar
Boris Boesler committed
311
312
313
314
315
316
 *    cf_op = new_Jmp();
 *
 *    For further information look at the documentation of the nodes and
 *    constructors and at the paragraph COPING WITH DATA OBJECTS at the
 *    end of this documentation.
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
317
  *    The comfortable interface contains the following routines further explained
Boris Boesler's avatar
Boris Boesler committed
318
319
 *    below:
 *
320
321
322
323
324
325
326
327
 *    ir_node *new_immBlock (void);
 *    ir_node *new_Start    (void);
 *    ir_node *new_End      (void);
 *    ir_node *new_Jmp      (void);
 *    ir_node *new_Cond     (ir_node *c);
 *    ir_node *new_Return   (ir_node *store, int arity, ir_node **in);
 *    ir_node *new_Raise    (ir_node *store, ir_node *obj);
 *    ir_node *new_Const    (ir_mode *mode, tarval *con);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
328
 *    ir_node *new_SymConst (type_or_id_p value, symconst_kind kind);
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
 *    ir_node *new_simpleSel (ir_node *store, ir_node *objptr, entity *ent);
 *    ir_node *new_Sel    (ir_node *store, ir_node *objptr, int arity,
 *                         ir_node **in, entity *ent);
 *    ir_node *new_InstOf (ir_node *store, ir_node obj, type *ent);
 *    ir_node *new_Call   (ir_node *store, ir_node *callee, int arity,
 *                 ir_node **in, type_method *type);
 *    ir_node *new_Add    (ir_node *op1, ir_node *op2, ir_mode *mode);
 *    ir_node *new_Sub    (ir_node *op1, ir_node *op2, ir_mode *mode);
 *    ir_node *new_Minus  (ir_node *op,  ir_mode *mode);
 *    ir_node *new_Mul    (ir_node *op1, ir_node *op2, ir_mode *mode);
 *    ir_node *new_Quot   (ir_node *memop, ir_node *op1, ir_node *op2);
 *    ir_node *new_DivMod (ir_node *memop, ir_node *op1, ir_node *op2);
 *    ir_node *new_Div    (ir_node *memop, ir_node *op1, ir_node *op2);
 *    ir_node *new_Mod    (ir_node *memop, ir_node *op1, ir_node *op2);
 *    ir_node *new_Abs    (ir_node *op,                ir_mode *mode);
 *    ir_node *new_And    (ir_node *op1, ir_node *op2, ir_mode *mode);
 *    ir_node *new_Or     (ir_node *op1, ir_node *op2, ir_mode *mode);
 *    ir_node *new_Eor    (ir_node *op1, ir_node *op2, ir_mode *mode);
 *    ir_node *new_Not    (ir_node *op,                ir_mode *mode);
 *    ir_node *new_Shl    (ir_node *op,  ir_node *k,   ir_mode *mode);
 *    ir_node *new_Shr    (ir_node *op,  ir_node *k,   ir_mode *mode);
 *    ir_node *new_Shrs   (ir_node *op,  ir_node *k,   ir_mode *mode);
 *    ir_node *new_Rot    (ir_node *op,  ir_node *k,   ir_mode *mode);
 *    ir_node *new_Cmp    (ir_node *op1, ir_node *op2);
 *    ir_node *new_Conv   (ir_node *op, ir_mode *mode);
 *    ir_node *new_Cast   (ir_node *op, type *to_tp);
 *    ir_node *new_Load   (ir_node *store, ir_node *addr);
 *    ir_node *new_Store  (ir_node *store, ir_node *addr, ir_node *val);
 *    ir_node *new_Alloc  (ir_node *store, ir_node *size, type *alloc_type,
 *                         where_alloc where);
 *    ir_node *new_Free   (ir_node *store, ir_node *ptr, ir_node *size,
 *               type *free_type);
 *    ir_node *new_Proj   (ir_node *arg, ir_mode *mode, long proj);
=======
363
364
365
366
 *    ir_node *new_simpleSel(ir_node *store, ir_node *objptr, entity *ent);
 *    ir_node *new_Sel      (ir_node *store, ir_node *objptr, int arity,
 *                           ir_node **in, entity *ent);
 *    ir_node *new_Call     (ir_node *store, ir_node *callee, int arity,
367
 *                       ir_node **in, type_method *type);
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
 *    ir_node *new_Add      (ir_node *op1, ir_node *op2, ir_mode *mode);
 *    ir_node *new_Sub      (ir_node *op1, ir_node *op2, ir_mode *mode);
 *    ir_node *new_Minus    (ir_node *op,  ir_mode *mode);
 *    ir_node *new_Mul      (ir_node *op1, ir_node *op2, ir_mode *mode);
 *    ir_node *new_Quot     (ir_node *memop, ir_node *op1, ir_node *op2);
 *    ir_node *new_DivMod   (ir_node *memop, ir_node *op1, ir_node *op2);
 *    ir_node *new_Div      (ir_node *memop, ir_node *op1, ir_node *op2);
 *    ir_node *new_Mod      (ir_node *memop, ir_node *op1, ir_node *op2);
 *    ir_node *new_Abs      (ir_node *op,                ir_mode *mode);
 *    ir_node *new_And      (ir_node *op1, ir_node *op2, ir_mode *mode);
 *    ir_node *new_Or       (ir_node *op1, ir_node *op2, ir_mode *mode);
 *    ir_node *new_Eor      (ir_node *op1, ir_node *op2, ir_mode *mode);
 *    ir_node *new_Not      (ir_node *op,                ir_mode *mode);
 *    ir_node *new_Shl      (ir_node *op,  ir_node *k,   ir_mode *mode);
 *    ir_node *new_Shr      (ir_node *op,  ir_node *k,   ir_mode *mode);
 *    ir_node *new_Shrs     (ir_node *op,  ir_node *k,   ir_mode *mode);
 *    ir_node *new_Rot      (ir_node *op,  ir_node *k,   ir_mode *mode);
 *    ir_node *new_Cmp      (ir_node *op1, ir_node *op2);
 *    ir_node *new_Conv     (ir_node *op, ir_mode *mode);
 *    ir_node *new_Cast     (ir_node *op, type *to_tp);
 *    ir_node *new_Load     (ir_node *store, ir_node *addr);
 *    ir_node *new_Store    (ir_node *store, ir_node *addr, ir_node *val);
 *    ir_node *new_Alloc    (ir_node *store, ir_node *size, type *alloc_type,
 *                           where_alloc where);
 *    ir_node *new_Free     (ir_node *store, ir_node *ptr, ir_node *size,
393
 *                       type *free_type);
394
395
 *    ir_node *new_Proj     (ir_node *arg, ir_mode *mode, long proj);
 *    ir_node *new_FuncCall (ir_node *store, ir_node *callee, int arity,
396
 *                       ir_node **in, type_method *type);
Boris Boesler's avatar
Boris Boesler committed
397
398
 *
 *    void add_in_edge (ir_node *block, ir_node *jmp);
399
 *    void mature_block (ir_node *block);
Boris Boesler's avatar
Boris Boesler committed
400
401
402
403
404
 *    void switch_block (ir_node *target);
 *    ir_node *get_value (int pos, ir_mode *mode);
 *    void set_value (int pos, ir_node *value);
 *    ir_node *get_store (void);
 *    void set_store (ir_node *store);
405
 *    keep_alive (ir_node ka)
Boris Boesler's avatar
Boris Boesler committed
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
 *
 *    IR_NODES AND CONSTRUCTORS FOR IR_NODES
 *    =======================================
 *
 *    All ir_nodes are defined by a common data structure.  They are distinguished
 *    by their opcode and differ in the number of their attributes.
 *
 *    The constructor for the block node sets current_block to itself.
 *    Const nodes are always added to the start block.
 *    All other constructors add the created node to the current_block.
 *    swich_block(block) allows to set the current block to block.
 *
 *    Watch for my inconsistent use of input and predecessor (dataflow view)
 *    and `the node points to' (implementation view).
 *
 *    The following description of the nodes lists four properties them if these
 *    are of interest:
 *     - the parameters to the constructor
 *     - the inputs of the Firm node
 *     - the outputs of the Firm node
 *     - attributes to the node
 *
 *    ------------
 *
 *    ir_node *new_immBlock (void)
 *    ----------------------------
 *
 *    Creates a new block.  Sets current_block to itself.  When a new block is
 *    created it cannot be known how many predecessors this block will have in the
 *    control flow graph. Therefore the list of inputs can not be fixed at
 *    creation.  Predecessors can be added with add_in_edge (block, control flow
 *    operation).  With every added predecessor the number of inputs to Phi nodes
 *    also changes.
 *
 *    The block can be completed by mature_block(block) if all predecessors are
 *    known.  If several blocks are built at once, mature_block can only be called
 *    after set_value has been called for all values that are life at the end
 *    of the block.  This is necessary so that Phi nodes created by mature_block
 *    get the right predecessors in case of cyclic dependencies.  If all set_values
 *    of this block are called after maturing it and before calling get_value
 *    in some block that is control flow dependent on this block, the construction
 *    is correct.
 *
 *    Example for faulty ir construction:  (draw the graph on a paper and you'll
 *                                          get it ;-)
 *
 *      block_before_loop = new_block();
 *      set_value(x);
 *      mature_block(block_before_loop);
 *      before2header = new_Jmp;
 *
 *      loop_header = new_block ();
 *      header2body - new_Jmp();
 *
 *      loop_body = new_block ();
 *      body2header = new_Jmp();
 *
 *      add_in_edge(loop_header, before2header);
 *      add_in_edge(loop_header, body2header);
 *      add_in_edge(loop_body, header2body);
 *
 *      mature_block(loop_header);
 *      mature_block(loop_body);
 *
470
471
472
 *      get_value(loop_body, x);   //  gets the Phi in loop_header
 *      set_value(loop_header, x); //  sets the value the above get_value should
 *                                 //  have returned!!!
Boris Boesler's avatar
Boris Boesler committed
473
474
475
 *
 *    Mature_block also fixes the number of inputs to the Phi nodes.  Mature_block
 *    should be called as early as possible, as afterwards the generation of Phi
Götz Lindenmaier's avatar
Götz Lindenmaier committed
476
 *   nodes is more efficient.
Boris Boesler's avatar
Boris Boesler committed
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
 *
 *    Inputs:
 *      There is an input for each control flow predecessor of the block.
 *      The input points to an instruction producing an output of type X.
 *      Possible predecessors:  Start, Jmp, Cond, Raise or Return or any node
 *      possibly causing an exception.  (Often the real predecessors are Projs.)
 *    Output:
 *      Mode BB (R), all nodes belonging to this block should consume this output.
 *      As they are strict (except Block and Phi node) it is a necessary condition
 *      that the block node executed before any other node in this block executes.
 *    Attributes:
 *      block.matured  Indicates whether the block is mature.
 *      block.**graph_arr
 *                      This attribute contains all local values valid in this
 *                      block. This is needed to build the Phi nodes and removed
 *                      if the graph is complete.  This field is used by the
493
494
 *              internal construction algorithm and should not be accessed
 *              from outside.
Boris Boesler's avatar
Boris Boesler committed
495
496
497
498
499
500
 *
 *
 *    ir_node *new_Block (int arity, ir_node **in)
 *    --------------------------------------------
 *
 *    Creates a new Block with the given list of predecessors.  This block
501
502
503
504
505
506
 *    is mature.  As other constructors calls optimization and vrfy for the
 *    block.  If one of the predecessors is Unknown (as it has to be filled in
 *    later) optimizations are skipped.  This is necessary to
 *    construct Blocks in loops.  Leaving Unknown in the Block after finishing
 *    the construction may have strange effects, especially for interprocedural
 *    representation and analyses.
Boris Boesler's avatar
Boris Boesler committed
507
508
509
510
511
512
513
514
515
516
517
518
519
 *
 *
 *    CONTROL FLOW OPERATIONS
 *    -----------------------
 *
 *    In each block there must be exactly one of the control flow
 *    operations Start, End, Jmp, Cond, Return or Raise.  The output of a
 *    control flow operation points to the block to be executed next.
 *
 *    ir_node *new_Start (void)
 *    -------------------------
 *
 *    Creates a start node.  Not actually needed public.  There is only one such
Götz Lindenmaier's avatar
Götz Lindenmaier committed
520
 *   node in each procedure which is automatically created by new_ir_graph.
Boris Boesler's avatar
Boris Boesler committed
521
522
523
524
525
526
527
528
529
530
531
 *
 *    Inputs:
 *      No inputs except the block it belogns to.
 *    Output:
 *      A tuple of 4 (5, 6) distinct values. These are labeled by the following
 *      projection numbers (pns_number):
 *      * pns_initial_exec
 *                       mode X, points to the first block to be executed.
 *      * pns_global_store
 *                       mode M, the global store
 *      * pns_frame_base mode P, a pointer to the base of the procedures
532
 *                       stack frame.
Boris Boesler's avatar
Boris Boesler committed
533
534
535
536
537
538
539
540
541
 *      * pns_globals    mode P, a pointer to the part of the memory containing
 *                               _all_ global things.
 *      * pns_args       mode T, a tuple containing all arguments of the procedure.
 *
 *
 *    ir_node *new_End (void)
 *    -----------------------
 *
 *    Creates an end node.  Not actually needed public.  There is only one such
Götz Lindenmaier's avatar
Götz Lindenmaier committed
542
 *   node in each procedure which is automatically created by new_ir_graph.
Boris Boesler's avatar
Boris Boesler committed
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
 *
 *    Inputs:
 *      No inputs except the block it belongs to.
 *    Output:
 *      No output.
 *
 *    ir_node *new_Jmp (void)
 *    -----------------------
 *
 *    Creates a Jmp node.
 *
 *    Inputs:
 *      The block the node belongs to
 *    Output:
 *      Control flow to the next block.
 *
 *    ir_node *new_Cond (ir_node *c)
 *    ------------------------------
 *
 *    Creates a Cond node.  There are two versions of this node.
 *
 *    The Boolean Cond:
 *    Input:
 *      A value of mode b.
 *    Output:
 *      A tuple of two control flows.  The first is taken if the input is
 *      false, the second if it is true.
 *
 *    The Switch Cond:
 *    Input:
 *      A value of mode I_u. (i)
 *    Output:
 *      A tuple of n control flows.  If the Cond's input is i, control
 *      flow will procede along output i. If the input is >= n control
 *      flow proceeds along output n.
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
579
 *    ir_node *new_Return (ir_node *store, int arity, ir_node **in)
Boris Boesler's avatar
Boris Boesler committed
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
 *    -------------------------------------------------------------
 *
 *    The return node has as inputs the results of the procedure.  It
 *    passes the control flow to the end_block.
 *
 *    Inputs:
 *      The memory state.
 *      All results.
 *    Output
 *      Control flow to the end block.
 *
 *    ir_node *new_Raise (ir_node *store, ir_node *obj)
 *    -------------------------------------------------
 *
 *    Raises an exception.  Unconditional change of control flow.  Writes
 *    an explicit Except variable to memory to pass it to the exception
 *    handler.  See TechReport 1999-14, chapter Exceptions.
 *
 *    Inputs:
 *      The memory state.
 *      A pointer to the Except variable.
 *    Output:
 *      A tuple of control flow and the changed memory state.  The control flow
 *      points to the exception handler if it is definied in this procedure,
 *      else it points to the end_block.
 *
 *
 *    ---------
 *
 *    ir_node *new_Const (ir_mode *mode, tarval *con)
 *    -----------------------------------------------
 *
 *    Creates a constant in the constant table and adds a Const node
 *    returning this value to the start block.
 *
 *    Parameters:
 *      *mode            The mode of the constant.
 *      *con             Points to an entry in the constant table.
 *                       This pointer is added to the attributes of
 *                       the node (self->attr.con)
 *    Inputs:
 *      No inputs except the block it belogns to.
 *    Output:
 *      The constant value.
 *    Attribute:
 *      attr.con   A tarval* pointer to the proper entry in the constant
 *                 table.
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
628
 *    ir_node *new_SymConst (type *tp, symconst_addr_ent kind)
Boris Boesler's avatar
Boris Boesler committed
629
630
631
 *    ------------------------------------------------------------
 *
 *    There are three kinds of symbolic constants:
Götz Lindenmaier's avatar
Götz Lindenmaier committed
632
633
634
 *     symconst_type_tag  The symbolic constant represents a type tag.
 *     symconst_size      The symbolic constant represents the size of a class.
 *     symconst_addr_name Information for the linker, e.g. the name of a global
Boris Boesler's avatar
Boris Boesler committed
635
 *                variable.
636
637
638
639
 *    To represent a pointer to an entity that is represented by an entity
 *    datastructure don't use
 *      new_SymConst((type_or_id*)get_entity_ld_ident(ent), linkage_ptr_info);.
 *    Use a real const instead:
Michael Beck's avatar
fixed:    
Michael Beck committed
640
 *      new_Const(mode_P_mach, tarval_p_from_entity(ent));
641
642
 *    This makes the Constant independent of name changes of the entity due to
 *    mangling.
Boris Boesler's avatar
Boris Boesler committed
643
644
645
646
647
648
649
650
651
652
653
654
655
 *
 *    Parameters
 *      kind        The kind of the symbolic constant: type_tag, size or link_info.
 *      *type_or_id Points to the type the tag stands for or to the type
 *                  whose size is represented by the constant or to an ident
 *                  representing the linkage info.
 *
 *    Inputs:
 *      No inputs except the block it belogns to.
 *    Output:
 *      An unsigned integer (I_u) or a pointer (P).
 *
 *    Attributes:
Götz Lindenmaier's avatar
Götz Lindenmaier committed
656
657
658
659
660
 *      attr.i.num       The symconst_addr_ent, i.e. one of
 *                        -symconst_type_tag
 *                        -symconst_size
 *                - symconst_addr_name
 *        If the attr.i.num is symconst_type_tag or symconst_size, the node contains an attribute
Matthias Heil's avatar
Matthias Heil committed
661
 *      attr.i.*type,    a pointer to a type_class.  The mode of the node is mode_Is.
Boris Boesler's avatar
Boris Boesler committed
662
663
 *        if it is linkage_ptr_info it contains
 *      attr.i.*ptrinfo,  an ident holding information for the linker.  The mode
Michael Beck's avatar
fixed:    
Michael Beck committed
664
 *        of the node is mode_P_mach.
Boris Boesler's avatar
Boris Boesler committed
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
 *
 *    ---------------
 *
 *    ir_node *new_simpleSel (ir_node *store, ir_node *frame, entity *sel)
 *    --------------------------------------------------------------------
 *
 *
 *    Selects an entity from a compound type. This entity can be a field or
 *    a method.
 *
 *    Parameters:
 *      *store     The memory in which the object the entity should be selected
 *                 from is allocated.
 *      *frame     The pointer to the object.
 *      *sel       The entity to select.
 *
 *    Inputs:
 *      The memory containing the object.
 *      A pointer to the object.
 *      An unsigned integer.
 *    Output:
 *      A pointer to the selected entity.
 *    Attributes:
 *      attr.sel   Pointer to the entity
 *
 *
 *    ir_node *new_Sel (ir_node *store, ir_node *frame, int arity, ir_node **in,
 *    --------------------------------------------------------------------------
 *                      entity *sel)
 *                      ------------
 *
 *    Selects a field from an array type.  The entity has as owner the array, as
 *    type the arrays element type.  The indexes to access an array element are
 *    given also.
 *
 *    Parameters:
 *      *store     The memory in which the object the entity should be selected from
 *                 is allocated.
 *      *frame     The pointer to the object.
 *      *arity     number of array indexes.
 *      *in        array with index inputs to the node.
 *      *sel       The entity to select.
 *
 *    Inputs:
 *      The memory containing the object.
 *      A pointer to the object.
 *      As much unsigned integer as there are array expressions.
 *    Output:
 *      A pointer to the selected entity.
 *    Attributes:
 *      attr.sel   Pointer to the entity
 *
 *    The constructors new_Sel and new_simpleSel generate the same ir nodes.
 *    simpleSel just sets the arity of the index inputs to zero.
 *
 *
 *    ARITHMETIC OPERATIONS
 *    ---------------------
 *
 *    ir_node *new_Call (ir_node *store, ir_node *callee, int arity, ir_node **in,
 *    ----------------------------------------------------------------------------
 *                       type_method *type)
 *                       ------------------
 *
 *    Creates a procedure call.
 *
 *    Parameters
 *      *store           The actual store.
 *      *callee          A pointer to the called procedure.
 *      arity            The number of procedure parameters.
 *      **in             An array with the pointers to the parameters.
 *                       The constructor copies this array.
 *      *type            Type information of the procedure called.
 *
 *    Inputs:
 *      The store, the callee and the parameters.
 *    Output:
 *      A tuple containing the eventually changed store and the procedure
 *      results.
 *    Attributes:
 *      attr.call        Contains the type information for the procedure.
 *
747
748
749
750
 *    ir_node *new_FuncCall (ir_node *callee, int arity, ir_node **in, type_method *type)
 *    -----------------------------------------------------------------------------------
 *
 *    Creates a procedure call to a function WITHOUT memory side effects.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
751
 *   nodes of this kind are floating in contrast to Call nodes.
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
 *    Further, a procedure call with FuncCall cannot raise an exception!
 *
 *    Parameters
 *      *callee          A pointer to the called procedure.
 *      arity            The number of procedure parameters.
 *      **in             An array with the pointers to the parameters.
 *                       The constructor copies this array.
 *      *type            Type information of the procedure called.
 *
 *    Inputs:
 *      The callee and the parameters.
 *    Output:
 *      A tuple containing the procedure results.
 *    Attributes:
 *      attr.call        Contains the type information for the procedure.
 *
Boris Boesler's avatar
Boris Boesler committed
768
769
770
771
772
773
774
775
776
777
778
779
780
 *    ir_node *new_Add (ir_node *op1, ir_node *op2, ir_mode *mode)
 *    ------------------------------------------------------------
 *
 *    Trivial.
 *
 *    ir_node *new_Sub (ir_node *op1, ir_node *op2, ir_mode *mode)
 *    ------------------------------------------------------------
 *
 *    Trivial.
 *
 *    ir_node *new_Minus (ir_node *op, ir_mode *mode)
 *    -----------------------------------------------
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
781
 *    Unary Minus operations on floating point values.
Boris Boesler's avatar
Boris Boesler committed
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
 *
 *    ir_node *new_Mul (ir_node *op1, ir_node *op2, ir_mode *mode)
 *    ------------------------------------------------------------
 *
 *    Trivial.
 *
 *    ir_node *new_Quot (ir_node *memop, ir_node *op1, ir_node *op2)
 *    --------------------------------------------------------------
 *
 *    Quot performs exact division of floating point numbers.  It's mode
 *    is Tuple, the mode of the result must be annotated to the Proj
 *    that extracts the result of the arithmetic operations.
 *
 *    Inputs:
 *      The store needed to model exceptions and the two operands.
 *    Output:
 *      A tuple contaning a memory and a execution for modeling exceptions
 *      and the result of the arithmetic operation.
 *
 *    ir_node *new_DivMod (ir_node *memop, ir_node *op1, ir_node *op2)
 *    ----------------------------------------------------------------
 *
 *    Performs Div and Mod on interger values.
 *
 *    Output:
 *      A tuple contaning a memory and a execution for modeling exceptions
 *      and the two result of the arithmetic operations.
 *
 *    ir_node *new_Div (ir_node *memop, ir_node *op1, ir_node *op2)
 *    -------------------------------------------------------------
 *
 *    Trivial.
 *
 *    ir_node *new_Mod (ir_node *memop, ir_node *op1, ir_node *op2)
 *    -------------------------------------------------------------
 *
 *    Trivial.
 *
 *    ir_node *new_Abs (ir_node *op, ir_mode *mode)
 *    ---------------------------------------------
 *
 *    Trivial.
 *
 *    ir_node *new_And (ir_node *op1, ir_node *op2, ir_mode *mode)
 *    ------------------------------------------------------------
 *
 *    Trivial.
 *
 *    ir_node *new_Or (ir_node *op1, ir_node *op2, ir_mode *mode)
 *    -----------------------------------------------------------
 *
 *    Trivial.
 *
 *    ir_node *new_Eor (ir_node *op1, ir_node *op2, ir_mode *mode)
 *    ------------------------------------------------------------
 *
 *    Trivial.
 *
 *    ir_node *new_Not (ir_node *op, ir_mode *mode)
 *    ---------------------------------------------
 *
 *    This node constructs a constant where all bits are set to one
 *    and a Eor of this constant and the operator.  This simulates a
 *    Not operation.
 *
 *    ir_node *new_Shl (ir_node *op, ir_node *k, ir_mode *mode)
 *    ---------------------------------------------------------
 *
 *    Trivial.
 *
 *    ir_node *new_Shr (ir_node *op, ir_node *k, ir_mode *mode)
 *    ---------------------------------------------------------
 *
 *    Logic shift right, i.e., zero extended.
 *
 *
 *    ir_node *new_Shrs (ir_node *op, ir_node *k, ir_mode *mode)
 *    ----------------------------------------------------------
 *
 *    Arithmetic shift right, i.e., sign extended.
 *
 *    ir_node *new_Rot (ir_node *op, ir_node *k, ir_mode *mode)
 *    ---------------------------------------------------------
 *
 *    Rotates the operand to the (right??) by k bits.
 *
 *    ir_node *new_Conv (ir_node *op, ir_mode *mode)
 *    ---------------------------------------------
 *
 *    Mode conversion.  For allowed conversions see UKA Tech Report
 *    1999-14.
 *
 *    ir_node *new_Cmp (ir_node *op1, ir_node *op2)
 *    ---------------------------------------------
 *
 *    Input:
 *      The two values to be compared.
 *    Output:
 *      A 16-tuple containing the results of the 16 different comparisons.
 *      The following is a list giving the comparisons and a projection
 *      number (pnc_number) to use in Proj nodes to extract the proper result.
 *        False     false
 *        Eq        equal
885
886
887
888
889
890
891
892
893
894
895
896
897
898
 *        Lt    less
 *        Le    less or equal
 *        Gt    greater
 *        Ge    greater of equal
 *        Lg    less or greater
 *        Leg   less, equal or greater = ordered
 *        Uo    unordered
 *        Ue    unordered or equal
 *        Ul    unordered or less
 *        Ule   unordered, less or equal
 *        Ug    unordered or greater
 *        Uge   unordered, greater or equal
 *        Ne    unordered, less or greater = not equal
 *        True  true
Boris Boesler's avatar
Boris Boesler committed
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
 *
 *
 *
 *    ------------
 *
 *    In general, Phi nodes are automaitcally inserted.  In some cases, if
 *    all predecessors of a block are known, an explicit Phi node constructor
 *    is needed.  E.g., to construct a FIRM graph for a statement as
 *      a = (b==c) ? 2 : 5;
 *
 *    ir_node *new_Phi (int arity, ir_node **in, ir_mode *mode)
 *    ---------------------------------------------------------
 *
 *    Creates a Phi node. The in's order has to correspond to the order
 *    of in's of current_block.  This is not checked by the library!
914
915
916
917
918
 *    If one of the predecessors is Unknown (as it has to be filled in
 *    later) optimizations are skipped.  This is necessary to
 *    construct Phi nodes in loops.  Leaving Unknown in the Phi after finishing
 *    the construction may have strange effects, especially for interprocedural
 *    representation and analyses.
Boris Boesler's avatar
Boris Boesler committed
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
 *
 *    Parameter
 *      arity            number of predecessors
 *      **in             array with predecessors
 *      *mode            The mode of it's inputs and output.
 *    Inputs:
 *      A Phi node has as many inputs as the block it belongs to.
 *      Each input points to a definition of the same value on a
 *      different path in the control flow.
 *    Output
 *      The definition valid in this block.
 *
 *
 *    OPERATIONS TO MANAGE MEMORY EXPLICITLY
 *    --------------------------------------
 *
 *    ir_node *new_Load (ir_node *store, ir_node *addr)
 *    ----------------------------------------------------------------
 *
 *    The Load operation reads a value from memory.
 *
 *    Parameters:
 *    *store        The current memory.
 *    *addr         A pointer to the variable to be read in this memory.
 *
 *    Inputs:
 *      The memory and a pointer to a variable in this memory.
 *    Output:
 *      A tuple of the memory, a control flow to be taken in case of
 *      an exception and the loaded value.
 *
 *    ir_node *new_Store (ir_node *store, ir_node *addr, ir_node *val)
 *    ----------------------------------------------------------------
 *
 *    The Store operation writes a value to a variable in memory.
 *
 *    Inputs:
 *      The memory, a pointer to a variable in this memory and the value
 *      to write to this variable.
 *    Output:
 *      A tuple of the changed memory and a control flow to be taken in
 *      case of an exception.
 *
 *    ir_node *new_Alloc (ir_node *store, ir_node *size, type *alloc_type,
 *    --------------------------------------------------------------------
 *                        where_alloc where)
 *                        ------------------
 *
 *    The Alloc node allocates a new variable.  It can be specified whether the
 *    variable should be allocated to the stack or to the heap.
 *
 *    Parameters:
 *      *store       The memory which shall contain the new variable.
 *      **    *size        The number of bytes to allocate. Old. **
 *      *size        We decided that the size easily can be derived from the type.
 *                   This field is for allocating arrays, i.e., it gives the multiple
975
 *           of the size of alloc_type to allocate memory for.
Boris Boesler's avatar
Boris Boesler committed
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
 *      *alloc_type  The type of the allocated variable.
 *      where        Where to allocate the variable, either heap_alloc or stack_alloc.
 *
 *    Inputs:
 *      A memory and an unsigned integer.
 *    Output:
 *      A tuple of the changed memory, a control flow to be taken in
 *      case of an exception and the pointer to the new variable.
 *    Attributes:
 *      a.where          Indicates where the variable is allocated.
 *      a.*type          A pointer to the class the allocated data object
 *                       belongs to.
 *
 *    ir_node *new_Free (ir_node *store, ir_node *ptr, type *free_type)
 *    ------------------------------------------------------------------
 *
 *    The Free node frees memory of the given variable.
 *
 *    Parameters:
 *      *store       The memory which shall contain the new variable.
 *      *ptr         The pointer to the object to free.
 *      *size        The number of objects of type free_type to free in a sequence.
 *      *free_type   The type of the freed variable.
 *
 *    Inputs: