ircons.h 166 KB
Newer Older
Christian Würdig's avatar
Christian Würdig committed
1
/*
Michael Beck's avatar
Michael Beck committed
2
 * Copyright (C) 1995-2010 University of Karlsruhe.  All right reserved.
Christian Würdig's avatar
Christian Würdig committed
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 *
 * This file is part of libFirm.
 *
 * This file may be distributed and/or modified under the terms of the
 * GNU General Public License version 2 as published by the Free Software
 * Foundation and appearing in the file LICENSE.GPL included in the
 * packaging of this file.
 *
 * Licensees holding valid libFirm Professional Edition licenses may use
 * this file in accordance with the libFirm Commercial License.
 * Agreement provided with the Software.
 *
 * This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
 * WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE.
 */

Matthias Braun's avatar
Matthias Braun committed
20
21
22
23
24
25
26
/**
 * @file
 * @brief   Various irnode constructors. Automatic construction of SSA
 *          representation.
 * @author  Martin Trapp, Christian Schaefer, Goetz Lindenmaier, Boris Boesler,
 *          Michael Beck
 * @version $Id$
Götz Lindenmaier's avatar
Götz Lindenmaier committed
27
 */
Christian Schäfer's avatar
Christian Schäfer committed
28

Sebastian Felis's avatar
Sebastian Felis committed
29
/**
Matthias Braun's avatar
Matthias Braun committed
30
 *  @file
Michael Beck's avatar
Michael Beck committed
31
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
32
33
 *  documentation no more supported since 2001
 *
34
 *  IR node construction.
Boris Boesler's avatar
Boris Boesler committed
35
 *
Boris Boesler's avatar
Boris Boesler committed
36
 *    This file documents all datatypes and constructors needed to
Götz Lindenmaier's avatar
Götz Lindenmaier committed
37
 *    build a FIRM representation of a procedure.  The constructors are
Boris Boesler's avatar
Boris Boesler committed
38
39
40
41
42
43
44
45
46
47
 *    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.
 *
 *
 *    Three kinds of nodes
 *    --------------------
 *
48
 *      There are three kinds of nodes known to the IR:  entities,
Boris Boesler's avatar
Boris Boesler committed
49
50
51
52
53
54
55
56
57
58
59
60
61
 *      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
62
 *       nodes.
Boris Boesler's avatar
Boris Boesler committed
63
64
65
66
67
68
69
70
71
 *
 *    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
72
 *      executable if every input at its incoming edges is available.
Boris Boesler's avatar
Boris Boesler committed
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 *      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
87
 *      contains pointers to its predecessors so that the implementation is a
Boris Boesler's avatar
Boris Boesler committed
88
89
90
 *      dataflow graph with reversed edges.  It has to be traversed bottom
 *      up.
 *
91
 *      All nodes of the IR have the same basic structure.  They are
Boris Boesler's avatar
Boris Boesler committed
92
93
94
95
96
97
98
99
100
101
102
103
 *      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
104
105
106
 *                       node.  The mode of the operation is the mode of its
 *                       result.  A Firm mode is a datatype as known to the
 *                       target, not a type of the source language.
Boris Boesler's avatar
Boris Boesler committed
107
 *
108
 *      visit            A flag for traversing the IR.
Boris Boesler's avatar
Boris Boesler committed
109
110
111
112
 *
 *      **in             An array with pointers to the node's predecessors.
 *
 *      *link            A pointer to an ir_node.  With this pointer all Phi nodes
113
 *                       are attached to a Block, i.e. a Block points to its
Boris Boesler's avatar
Boris Boesler committed
114
 *                       first Phi node, this node points to the second Phi node
115
 *                       in the Block and so forth.  Used in mature_immBlock
Boris Boesler's avatar
Boris Boesler committed
116
 *                       to find all Phi nodes to be matured.  It's also used to
117
 *                       annotate a node with a better, optimized version of it.
Boris Boesler's avatar
Boris Boesler committed
118
119
120
 *
 *      attr             An attr struct containing the attributes of the nodes. The
 *                       attributes depend on the opcode of the node.  The number
121
 *                       of these attributes is given in op.
Boris Boesler's avatar
Boris Boesler committed
122
123
124
125
126
127
128
129
130
 *
 *    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
131
 *    GLOBAL VARIABLES -- now also fields of ir_graph.
Boris Boesler's avatar
Boris Boesler committed
132
133
134
 *    ================
 *
 *    current_ir_graph   Points to the current ir_graph.  All constructors for
135
 *                       nodes add nodes to this graph.
Boris Boesler's avatar
Boris Boesler committed
136
137
138
139
140
141
142
143
144
145
 *
 *    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
146
 *    CONSTRUCTOR FOR IR_GRAPH --> see irgraph.h
Boris Boesler's avatar
Boris Boesler committed
147
148
149
 *    ========================
 *
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
150
 *    PROCEDURE TO CONSTRUCT AN IR GRAPH --> see also Firm tutorial
Boris Boesler's avatar
Boris Boesler committed
151
152
153
154
 *    ==================================
 *
 *    This library supplies several interfaces to construct a FIRM graph for
 *    a program:
Michael Beck's avatar
Michael Beck committed
155
 *    - A "comfortable" interface generating SSA automatically.  Automatically
Boris Boesler's avatar
Boris Boesler committed
156
157
 *      computed predecessors of nodes need not be specified in the constructors.
 *      (new_<Node> constructurs and a set of additional routines.)
Michael Beck's avatar
Michael Beck committed
158
 *    - A less comfortable interface where all predecessors except the block
Boris Boesler's avatar
Boris Boesler committed
159
 *      an operation belongs to need to be specified.  SSA must be constructed
160
 *      by hand.  (new_<Node> constructors and set_cur_block()).  This interface
Boris Boesler's avatar
Boris Boesler committed
161
162
 *      is called "block oriented".  It automatically calles the local optimizations
 *      for each new node.
Michael Beck's avatar
Michael Beck committed
163
 *    - An even less comfortable interface where the block needs to be specified
Boris Boesler's avatar
Boris Boesler committed
164
165
166
167
168
169
 *      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
170
 *    the firm node (See tech-reprot UKA 1999-14).  For the construction of
Boris Boesler's avatar
Boris Boesler committed
171
172
173
174
175
 *    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
176
 *    out of the procedure.  Often these are all compiler generated
Boris Boesler's avatar
Boris Boesler committed
177
178
179
180
 *    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
181
 *    constructor gets the number of local variables.  The graph is held in the
Boris Boesler's avatar
Boris Boesler committed
182
183
184
185
186
187
188
189
 *    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
190
 *    set_cur_block(block).  If several blocks are constructed in parallel block
Boris Boesler's avatar
Boris Boesler committed
191
192
 *    switches need to be performed constantly.
 *
Christoph Mallon's avatar
Christoph Mallon committed
193
 *    To generate a Block node (with the comfortable interface), its predecessor
Boris Boesler's avatar
Boris Boesler committed
194
 *    control flow nodes need not be known.  In case of cyclic control flow these
195
 *    can not be known when the block is constructed.  With add_immBlock_pred(block,
Boris Boesler's avatar
Boris Boesler committed
196
 *    cfnode) predecessors can be added to the block.  If all predecessors are
197
 *    added to the block mature_immBlock(b) needs to be called.  Calling mature_immBlock
Boris Boesler's avatar
Boris Boesler committed
198
 *    early improves the efficiency of the Phi node construction algorithm.
199
 *    But if several  blocks are constructed at once, mature_immBlock must only
Boris Boesler's avatar
Boris Boesler committed
200
201
202
203
204
205
 *    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
206
 *    values, the predecessors can be obtained from the library with a call to
Boris Boesler's avatar
Boris Boesler committed
207
208
 *    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.
209
 *    If an arithmetic operation produces a local value, this value needs to be
Boris Boesler's avatar
Boris Boesler committed
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 *    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();
231
232
233
 *    add_immBlock_pred(this_block, cf_pred1);
 *    add_immBlock_pred(this_block, cf_pred2);
 *    mature_immBlock(this_block);
Matthias Heil's avatar
Matthias Heil committed
234
 *    a_val = get_value(42, mode_Iu);
Boris Boesler's avatar
Boris Boesler committed
235
 *    mem = get_store();
236
237
238
 *    div = new_Div(mem, a_val, a_val, mode_Iu);
 *    mem = new_Proj(div, mode_M, pn_Div_M);   * for the numbers for Proj see docu *
 *    res = new_Proj(div, mode_Iu, pn_Div_res);
Boris Boesler's avatar
Boris Boesler committed
239
 *    set_store(mem);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
240
 *    set_value(res, 42);
Boris Boesler's avatar
Boris Boesler committed
241
242
243
244
245
246
 *    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.
 *
247
 *    The comfortable interface contains the following routines further explained
Boris Boesler's avatar
Boris Boesler committed
248
249
 *    below:
 *
250
251
252
253
 *    ir_node *new_immBlock (void);
 *    ir_node *new_Start    (void);
 *    ir_node *new_End      (void);
 *    ir_node *new_Jmp      (void);
254
 *    ir_node *new_IJmp     (ir_node *tgt);
255
256
 *    ir_node *new_Cond     (ir_node *c);
 *    ir_node *new_Return   (ir_node *store, int arity, ir_node **in);
257
 *    ir_node *new_Const    (tarval *con);
258
 *    ir_node *new_SymConst (ir_mode *mode, symconst_symbol value, symconst_kind kind);
Michael Beck's avatar
Michael Beck committed
259
 *    ir_node *new_simpleSel (ir_node *store, ir_node *objptr, ir_entity *ent);
260
 *    ir_node *new_Sel    (ir_node *store, ir_node *objptr, int arity,
Michael Beck's avatar
Michael Beck committed
261
 *                         ir_node **in, ir_entity *ent);
262
 *    ir_node *new_Call   (ir_node *store, ir_node *callee, int arity,
263
264
265
 *                         ir_node **in, type_method *type);
 *    ir_node *new_Builtin(ir_node *store, ir_builtin_kind kind, int arity,
 *                         ir_node **in, type_method *type);
266
267
268
269
 *    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);
Michael Beck's avatar
Michael Beck committed
270
 *    ir_node *new_Mulh   (ir_node *op1, ir_node *op2, ir_mode *mode);
271
272
273
274
 *    ir_node *new_Quot   (ir_node *memop, ir_node *op1, ir_node *op2, ir_mode *mode, op_pin_state state);
 *    ir_node *new_DivMod (ir_node *memop, ir_node *op1, ir_node *op2, ir_mode *mode, op_pin_state state);
 *    ir_node *new_Div    (ir_node *memop, ir_node *op1, ir_node *op2, ir_mode *mode, op_pin_state state);
 *    ir_node *new_Mod    (ir_node *memop, ir_node *op1, ir_node *op2, ir_mode *mode, op_pin_state state;
275
276
277
278
279
280
281
 *    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);
282
 *    ir_node *new_Rotl   (ir_node *op,  ir_node *k,   ir_mode *mode);
283
284
 *    ir_node *new_Cmp    (ir_node *op1, ir_node *op2);
 *    ir_node *new_Conv   (ir_node *op, ir_mode *mode);
Michael Beck's avatar
Michael Beck committed
285
 *    ir_node *new_Cast   (ir_node *op, ir_type *to_tp);
286
287
 *    ir_node *new_Carry  (ir_node *op1, ir_node *op2, ir_mode *mode);
 *    ir_node *new_Borrow (ir_node *op1, ir_node *op2, ir_mode *mode);
288
289
 *    ir_node *new_Load   (ir_node *store, ir_node *addr, ir_mode *mode, ir_cons_flags flags);
 *    ir_node *new_Store  (ir_node *store, ir_node *addr, ir_node *val, ir_cons_flags flags);
290
 *    ir_node *new_Alloc  (ir_node *store, ir_node *count, ir_type *alloc_type,
291
292
 *                         where_alloc where);
 *    ir_node *new_Free   (ir_node *store, ir_node *ptr, ir_node *size,
Michael Beck's avatar
Michael Beck committed
293
 *               ir_type *free_type, where_alloc where);
294
 *    ir_node *new_Proj   (ir_node *arg, ir_mode *mode, long proj);
295
 *    ir_node *new_NoMem  (void);
296
 *    ir_node *new_Mux    (ir_node *sel, ir_node *ir_false, ir_node *ir_true, ir_mode *mode);
Michael Beck's avatar
Michael Beck committed
297
 *    ir_node *new_CopyB  (ir_node *store, ir_node *dst, ir_node *src, ir_type *data_type);
298
299
 *    ir_node *new_InstOf (ir_node *store, ir_node obj, ir_type *ent);
 *    ir_node *new_Raise  (ir_node *store, ir_node *obj);
Michael Beck's avatar
Michael Beck committed
300
 *    ir_node *new_Bound  (ir_node *store, ir_node *idx, ir_node *lower, ir_node *upper);
Michael Beck's avatar
Michael Beck committed
301
 *    ir_node *new_Pin    (ir_node *node);
Boris Boesler's avatar
Boris Boesler committed
302
 *
303
304
305
 *    void add_immBlock_pred (ir_node *block, ir_node *jmp);
 *    void mature_immBlock (ir_node *block);
 *    void set_cur_block (ir_node *target);
Boris Boesler's avatar
Boris Boesler committed
306
307
308
309
 *    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);
310
 *    keep_alive (ir_node ka)
Boris Boesler's avatar
Boris Boesler committed
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
 *
 *    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.
 *
 *    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)
 *    ----------------------------
 *
337
338
339
340
341
342
 *    Creates a new block. 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_immBlock_pred (block, control flow operation).
 *    With every added predecessor the number of inputs to Phi nodes also
 *    changes.
Boris Boesler's avatar
Boris Boesler committed
343
 *
344
345
 *    The block can be completed by mature_immBlock(block) if all predecessors are
 *    known.  If several blocks are built at once, mature_immBlock can only be called
Boris Boesler's avatar
Boris Boesler committed
346
 *    after set_value has been called for all values that are life at the end
Michael Beck's avatar
Michael Beck committed
347
348
 *    of the block.  This is necessary so that Phi nodes created mature_immBlock
 *    get the right predecessors in case of cyclic dependencies.  If all set_values
Boris Boesler's avatar
Boris Boesler committed
349
350
351
352
 *    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.
 *
353
 *    Example for faulty IR construction:  (draw the graph on a paper and you'll
Boris Boesler's avatar
Boris Boesler committed
354
355
 *                                          get it ;-)
 *
356
357
 *      block_before_loop = new_immBlock();
 *      set_cur_block(block_before_loop);
Boris Boesler's avatar
Boris Boesler committed
358
 *      set_value(x);
359
 *      mature_immBlock(block_before_loop);
Boris Boesler's avatar
Boris Boesler committed
360
361
 *      before2header = new_Jmp;
 *
362
363
 *      loop_header = new_immBlock ();
 *      set_cur_block(loop_header);
Boris Boesler's avatar
Boris Boesler committed
364
365
 *      header2body - new_Jmp();
 *
366
367
 *      loop_body = new_immBlock ();
 *      set_cur_block(loop_body);
Boris Boesler's avatar
Boris Boesler committed
368
369
 *      body2header = new_Jmp();
 *
370
371
372
 *      add_immBlock_pred(loop_header, before2header);
 *      add_immBlock_pred(loop_header, body2header);
 *      add_immBlock_pred(loop_body, header2body);
Boris Boesler's avatar
Boris Boesler committed
373
 *
374
375
 *      mature_immBlock(loop_header);
 *      mature_immBlock(loop_body);
Boris Boesler's avatar
Boris Boesler committed
376
 *
377
378
379
 *      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
380
 *
381
 *    Mature_immBlock also fixes the number of inputs to the Phi nodes.  Mature_immBlock
Boris Boesler's avatar
Boris Boesler committed
382
 *    should be called as early as possible, as afterwards the generation of Phi
Michael Beck's avatar
Michael Beck committed
383
 *    nodes is more efficient.
Boris Boesler's avatar
Boris Boesler committed
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
 *
 *    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
400
401
 *              internal construction algorithm and should not be accessed
 *              from outside.
Boris Boesler's avatar
Boris Boesler committed
402
403
404
405
406
407
 *
 *
 *    ir_node *new_Block (int arity, ir_node **in)
 *    --------------------------------------------
 *
 *    Creates a new Block with the given list of predecessors.  This block
408
 *    is mature.  As other constructors calls optimization and verify for the
409
410
 *    block.  If one of the predecessors is Unknown (as it has to be filled in
 *    later) optimizations are skipped.  This is necessary to
411
 *    construct Blocks in loops.
Boris Boesler's avatar
Boris Boesler committed
412
413
414
415
416
417
 *
 *
 *    CONTROL FLOW OPERATIONS
 *    -----------------------
 *
 *    In each block there must be exactly one of the control flow
418
 *    operations Start, End, Jmp, Cond, Return or Raise.  The output of a
Boris Boesler's avatar
Boris Boesler committed
419
420
421
422
423
424
 *    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
425
 *   node in each procedure which is automatically created by new_ir_graph.
Boris Boesler's avatar
Boris Boesler committed
426
427
 *
 *    Inputs:
Michael Beck's avatar
Michael Beck committed
428
 *      No inputs except the block it belongs to.
Boris Boesler's avatar
Boris Boesler committed
429
430
 *    Output:
 *      A tuple of 4 (5, 6) distinct values. These are labeled by the following
431
432
433
434
435
436
 *      projection numbers (pn_Start):
 *      * pn_Start_X_initial_exec    mode X, points to the first block to be exe *                                   cuted.
 *      * pn_Start_M                 mode M, the global store
 *      * pn_Start_P_frame_base      mode P, a pointer to the base of the proce  *                                   dures stack frame.
 *      * pn_Start_P_globals         mode P, a pointer to the part of the memory *                                   containing_all_ global things.
 *      * pn_Start_T_args            mode T, a tuple containing all arguments of *                                   the procedure.
Boris Boesler's avatar
Boris Boesler committed
437
438
439
440
441
442
 *
 *
 *    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
443
 *   node in each procedure which is automatically created by new_ir_graph.
Boris Boesler's avatar
Boris Boesler committed
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
 *
 *    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.
 *
460
461
462
463
464
465
466
467
468
469
470
 *    ir_node *new_IJmp (ir_node *tgt)
 *    -----------------------
 *
 *    Creates an IJmp node.
 *
 *    Inputs:
 *      The node that represents the target jump address
 *    Output:
 *      Control flow to an unknown target, must be pinned by
 *      the End node.
 *
Boris Boesler's avatar
Boris Boesler committed
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
 *    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
Michael Beck's avatar
Michael Beck committed
488
 *      flow will proceed along output i. If the input is >= n control
Boris Boesler's avatar
Boris Boesler committed
489
490
 *      flow proceeds along output n.
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
491
 *    ir_node *new_Return (ir_node *store, int arity, ir_node **in)
Boris Boesler's avatar
Boris Boesler committed
492
493
 *    -------------------------------------------------------------
 *
Michael Beck's avatar
Michael Beck committed
494
 *    The Return node has as inputs the results of the procedure.  It
Boris Boesler's avatar
Boris Boesler committed
495
496
497
498
499
500
501
502
503
 *    passes the control flow to the end_block.
 *
 *    Inputs:
 *      The memory state.
 *      All results.
 *    Output
 *      Control flow to the end block.
 *
 *
504
 *    ir_node *new_Const (tarval *con)
Boris Boesler's avatar
Boris Boesler committed
505
506
507
 *    -----------------------------------------------
 *
 *    Creates a constant in the constant table and adds a Const node
508
509
 *    returning this value to the start block. The mode is derived
 *    from the tarval.
Boris Boesler's avatar
Boris Boesler committed
510
511
512
513
514
515
516
517
518
519
520
521
522
 *
 *    Parameters:
 *      *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.
 *
523
 *    ir_node *new_SymConst (ir_mode *mode, union symconst_symbol value, symconst_addr_ent kind)
524
 *    -----------------------------------------------------------------------------------------
Boris Boesler's avatar
Boris Boesler committed
525
 *
526
 *    There are several symbolic constants:
527
528
529
 *     symconst_type_tag   The symbolic constant represents a type tag.
 *     symconst_type_size  The symbolic constant represents the size of a type.
 *     symconst_type_align The symbolic constant represents the alignment of a type.
530
 *     symconst_addr_ent   The symbolic constant represents the address of an entity.
531
532
533
534
 *     symconst_ofs_ent    The symbolic constant represents the offset of an
 *                         entity in its owner type.
 *     symconst_enum_const The symbolic constant is a enumeration constant of an
 *                         enumeration type.
535
 *
Boris Boesler's avatar
Boris Boesler committed
536
 *    Parameters
537
538
539
540
 *      mode        P for SymConsts representing addresses, Iu otherwise.
 *      value       The type, ident, entity or enum constant, depending on the
 *                  kind
 *      kind        The kind of the symbolic constant, see the list above.
Boris Boesler's avatar
Boris Boesler committed
541
542
 *
 *    Inputs:
543
 *      No inputs except the block it belongs to.
Boris Boesler's avatar
Boris Boesler committed
544
 *    Output:
545
 *      A symbolic constant.
Boris Boesler's avatar
Boris Boesler committed
546
547
 *
 *    Attributes:
Götz Lindenmaier's avatar
Götz Lindenmaier committed
548
549
 *      attr.i.num       The symconst_addr_ent, i.e. one of
 *                        -symconst_type_tag
550
551
 *                        -symconst_type_size
 *                        -symconst_type_align
552
 *                        -symconst_addr_ent
553
554
555
556
 *
 *    If the attr.i.num is symconst_type_tag, symconst_type_size or symconst_type_align,
 *    the node contains an attribute:
 *
557
 *      attr.i.*type,    a pointer to a type_class.
Boris Boesler's avatar
Boris Boesler committed
558
 *        if it is linkage_ptr_info it contains
559
 *      attr.i.*ptrinfo,  an ident holding information for the linker.
Boris Boesler's avatar
Boris Boesler committed
560
561
562
 *
 *    ---------------
 *
Michael Beck's avatar
Michael Beck committed
563
564
 *    ir_node *new_simpleSel (ir_node *store, ir_node *frame, ir_entity *sel)
 *    -----------------------------------------------------------------------
Boris Boesler's avatar
Boris Boesler committed
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
 *
 *
 *    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,
 *    --------------------------------------------------------------------------
Michael Beck's avatar
Michael Beck committed
588
589
 *                      ir_entity *sel)
 *                      ---------------
Boris Boesler's avatar
Boris Boesler committed
590
591
 *
 *    Selects a field from an array type.  The entity has as owner the array, as
Michael Beck's avatar
Michael Beck committed
592
 *    type the arrays element type.  The indices to access an array element are
Boris Boesler's avatar
Boris Boesler committed
593
594
595
596
597
598
 *    given also.
 *
 *    Parameters:
 *      *store     The memory in which the object the entity should be selected from
 *                 is allocated.
 *      *frame     The pointer to the object.
Michael Beck's avatar
Michael Beck committed
599
 *      *arity     number of array indices.
Boris Boesler's avatar
Boris Boesler committed
600
601
602
603
604
605
606
607
608
609
610
611
 *      *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
 *
612
 *    The constructors new_Sel and new_simpleSel generate the same IR nodes.
Boris Boesler's avatar
Boris Boesler committed
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
 *    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:
640
 *      attr.call        Contains the attributes for the procedure.
Boris Boesler's avatar
Boris Boesler committed
641
 *
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
 *    ir_node *new_Builtin(ir_node *store, ir_builtin_kind kind, int arity, ir_node **in,
 *    -----------------------------------------------------------------------------------
 *                       type_method *type)
 *                       ------------------
 *
 *    Creates a builtin call.
 *
 *    Parameters
 *      *store           The actual store.
 *      kind             Describes the called builtin.
 *      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 kind and the parameters.
 *    Output:
 *      A tuple containing the eventually changed store and the procedure
 *      results.
 *    Attributes:
 *      attr.builtin     Contains the attributes for the called builtin.
664
 *
Boris Boesler's avatar
Boris Boesler committed
665
666
667
668
669
670
671
672
673
674
675
676
677
 *    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)
 *    -----------------------------------------------
 *
Michael Beck's avatar
Michael Beck committed
678
 *    Unary Minus operations on integer and floating point values.
Boris Boesler's avatar
Boris Boesler committed
679
680
681
682
683
684
 *
 *    ir_node *new_Mul (ir_node *op1, ir_node *op2, ir_mode *mode)
 *    ------------------------------------------------------------
 *
 *    Trivial.
 *
Michael Beck's avatar
Michael Beck committed
685
686
687
688
689
 *    ir_node *new_Mulh (ir_node *op1, ir_node *op2, ir_mode *mode)
 *    ------------------------------------------------------------
 *
 *    Returns the high order bits of a n*n=2n multiplication.
 *
690
691
 *    ir_node *new_Quot (ir_node *memop, ir_node *op1, ir_node *op2, ir_mode *mode, op_pin_state state)
 *    -------------------------------------------------------------------------------------------------
Boris Boesler's avatar
Boris Boesler committed
692
693
 *
 *    Quot performs exact division of floating point numbers.  It's mode
694
 *    is Tuple, the mode of the result must match the Proj mode
Boris Boesler's avatar
Boris Boesler committed
695
696
697
698
699
 *    that extracts the result of the arithmetic operations.
 *
 *    Inputs:
 *      The store needed to model exceptions and the two operands.
 *    Output:
700
 *      A tuple containing a memory and a execution for modeling exceptions
Boris Boesler's avatar
Boris Boesler committed
701
702
 *      and the result of the arithmetic operation.
 *
703
704
 *    ir_node *new_DivMod (ir_node *memop, ir_node *op1, ir_node *op2, ir_mode *mode, op_pin_state state)
 *    ---------------------------------------------------------------------------------------------------
Boris Boesler's avatar
Boris Boesler committed
705
 *
706
 *    Performs Div and Mod on integer values.
Boris Boesler's avatar
Boris Boesler committed
707
708
 *
 *    Output:
709
 *      A tuple containing a memory and a execution for modeling exceptions
Boris Boesler's avatar
Boris Boesler committed
710
711
 *      and the two result of the arithmetic operations.
 *
712
713
 *    ir_node *new_Div (ir_node *memop, ir_node *op1, ir_node *op2, ir_mode *mode, op_pin_state state)
 *    ------------------------------------------------------------------------------------------------
Boris Boesler's avatar
Boris Boesler committed
714
715
716
 *
 *    Trivial.
 *
717
718
 *    ir_node *new_Mod (ir_node *memop, ir_node *op1, ir_node *op2, ir_mode *mode, op_pin_state state)
 *    ------------------------------------------------------------------------------------------------
Boris Boesler's avatar
Boris Boesler committed
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
747
748
749
750
751
752
753
754
755
756
757
758
759
 *
 *    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.
 *
760
 *    ir_node *new_Rotl (ir_node *op, ir_node *k, ir_mode *mode)
Boris Boesler's avatar
Boris Boesler committed
761
762
 *    ---------------------------------------------------------
 *
763
 *    Rotates the operand to the left by k bits.
Boris Boesler's avatar
Boris Boesler committed
764
 *
765
766
767
768
769
770
771
772
773
774
775
776
 *    ir_node *new_Carry (ir_node *op1, ir_node *op2, ir_mode *mode)
 *    ------------------------------------------------------------
 *
 *    Calculates the Carry value for integer addition. Used only
 *    in lowering code.
 *
 *    ir_node *new_Borrow (ir_node *op1, ir_node *op2, ir_mode *mode)
 *    ------------------------------------------------------------
 *
 *    Calculates the Borrow value for integer substraction. Used only
 *    in lowering code.
 *
Boris Boesler's avatar
Boris Boesler committed
777
778
779
780
781
782
783
784
785
786
787
788
789
790
 *    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
Michael Beck's avatar
Michael Beck committed
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
 *      number (pn_Cmp) to use in Proj nodes to extract the proper result.
 *        pn_Cmp_False false
 *        pn_Cmp_Eq    equal
 *        pn_Cmp_Lt    less
 *        pn_Cmp_Le    less or equal
 *        pn_Cmp_Gt    greater
 *        pn_Cmp_Ge    greater of equal
 *        pn_Cmp_Lg    less or greater
 *        pn_Cmp_Leg   less, equal or greater = ordered
 *        pn_Cmp_Uo    unordered
 *        pn_Cmp_Ue    unordered or equal
 *        pn_Cmp_Ul    unordered or less
 *        pn_Cmp_Ule   unordered, less or equal
 *        pn_Cmp_Ug    unordered or greater
 *        pn_Cmp_Uge   unordered, greater or equal
 *        pn_Cmp_Ne    unordered, less or greater = not equal
 *        pn_Cmp_True  true
Boris Boesler's avatar
Boris Boesler committed
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
 *
 *
 *
 *    ------------
 *
 *    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!
823
824
 *    If one of the predecessors is Unknown (as it has to be filled in
 *    later) optimizations are skipped.  This is necessary to
825
 *    construct Phi nodes in loops.
Boris Boesler's avatar
Boris Boesler committed
826
827
828
829
830
831
832
833
834
835
836
837
 *
 *    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.
 *
838
 *    ir_node *new_Mux (ir_node *sel, ir_node *ir_false, ir_node *ir_true, ir_mode *mode)
839
 *    -----------------------------------------------------------------------------------
840
841
842
843
844
 *
 *    Creates a Mux node. This node implements the following semantic:
 *    If the sel node (which must be of mode_b) evaluates to true, its value is
 *    ir_true, else ir_false;
 *
Boris Boesler's avatar
Boris Boesler committed
845
 *
846
 *
Boris Boesler's avatar
Boris Boesler committed
847
848
849
 *    OPERATIONS TO MANAGE MEMORY EXPLICITLY
 *    --------------------------------------
 *
850
851
 *    ir_node *new_Load (ir_node *store, ir_node *addr, ir_mode *mode, ir_cons_flags flags)
 *    -------------------------------------------------------------------------------------
Boris Boesler's avatar
Boris Boesler committed
852
853
854
855
856
857
 *
 *    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.
858
 *    *mode         The mode of the value to be loaded.
859
 *     flags        Additional flags for alignment, volatility and pin state.
Boris Boesler's avatar
Boris Boesler committed
860
861
862
863
864
865
866
 *
 *    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.
 *
867
868
 *    ir_node *new_Store (ir_node *store, ir_node *addr, ir_node *val, ir_cons_flags flags)
 *    -------------------------------------------------------------------------------------
Boris Boesler's avatar
Boris Boesler committed
869
870
871
872
873
874
875
876
877
878
 *
 *    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.
 *
879
 *    ir_node *new_Alloc (ir_node *store, ir_node *count, ir_type *alloc_type,
Michael Beck's avatar
Michael Beck committed
880
 *    -----------------------------------------------------------------------
Boris Boesler's avatar
Boris Boesler committed
881
882
883
884
885
886
887
888
 *                        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.
889
890
891
892
893
 *      *count       This field is for allocating arrays, it specifies how
 *                   many array elements are to be allocated.
 *      *alloc_type  The type of the allocated variable. In case of allocating
 *                   arrays this has to be the array type, not the type of the
 *                   array elements.
Boris Boesler's avatar
Boris Boesler committed
894
895
896
897
898
899
900
901
902
903
904
905
 *      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.
 *
Michael Beck's avatar
Michael Beck committed
906
907
 *    ir_node *new_Free (ir_node *store, ir_node *ptr, ir_node *size, ir_type *free_type,
 *    -----------------------------------------------------------------------------------
908
909
 *                        where_alloc where)
 *                        ------------------
Boris Boesler's avatar
Boris Boesler committed
910
911
912
913
914
915
916
917
 *
 *    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.
918
 *      where        Where the variable was allocated, either heap_alloc or stack_alloc.
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
 *
 *    Inputs:
 *      A memory, a pointer and an unsigned integer.
 *    Output:
 *      The changed memory.
 *    Attributes:
 *      f.*type          A pointer to the type information of the freed data object.
 *
 *    Not Implemented!
 *
 *    ir_node *new_Sync (int arity, ir_node **in)
 *    -------------------------------------------
 *
 *    The Sync operation unifies several partial memory blocks.  These blocks
 *    have to be pairwise disjunct or the values in common locations have to
 *    be identical.  This operation allows to specify all operations that eventually
 *    need several partial memory blocks as input with a single entrance by
 *    unifying the memories with a preceding Sync operation.
 *
 *    Parameters
Michael Beck's avatar
Michael Beck committed
939
 *      arity    The number of memories to synchronize.
Boris Boesler's avatar
Boris Boesler committed
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
 *      **in     An array of pointers to nodes that produce an output of
 *               type memory.
 *    Inputs
 *      Several memories.
 *    Output
 *      The unified memory.
 *
 *
 *    SPECIAL OPERATIONS
 *    ------------------
 *
 *    ir_node *new_Bad (void)
 *    -----------------------
 *
 *    Returns the unique Bad node current_ir_graph->bad.
 *    This node is used to express results of dead code elimination.
 *
957
958
959
960
961
962
963
 *    ir_node *new_NoMem (void)
 *    -----------------------------------------------------------------------------------
 *
 *    Returns the unique NoMem node current_ir_graph->no_mem.
 *    This node is used as input for operations that need a Memory, but do not
 *    change it like Div by const != 0, analyzed calls etc.
 *
Boris Boesler's avatar
Boris Boesler committed
964
965
966
 *    ir_node *new_Proj (ir_node *arg, ir_mode *mode, long proj)
 *    ----------------------------------------------------------
 *
967
 *    Selects one entry of a tuple.  This is a hidden edge with attributes.
Boris Boesler's avatar
Boris Boesler committed
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
 *
 *    Parameters
 *      *arg      A node producing a tuple.
 *      *mode     The mode of the value to project.
 *      proj      The position of the value in the tuple.
 *    Input:
 *      The tuple.
 *    Output:
 *      The value.
 *
 *    ir_node *new_Tuple (int arity, ir_node **in)
 *    --------------------------------------------
 *
 *    Builds a Tuple from single values.  This is needed to implement
 *    optimizations that remove a node that produced a tuple.  The node can be
 *    replaced by the Tuple operation so that the following Proj nodes have not to
 *    be changed.  (They are hard to find due to the implementation with pointers
 *    in only one direction.)  The Tuple node is smaller than any other
986
 *    node, so that a node can be changed into a Tuple by just changing it's
Boris Boesler's avatar
Boris Boesler committed
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
 *    opcode and giving it a new in array.
 *
 *    Parameters
 *      arity    The number of tuple elements.
 *      **in     An array containing pointers to the nodes producing the
 *               tuple elements.
 *
 *    ir_node *new_Id (ir_node *val, ir_mode *mode)
 *    ---------------------------------------------
 *
 *    The single output of the Id operation is it's input.  Also needed
 *    for optimizations.
 *
 *
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
 *    HIGH LEVEL OPERATIONS
 *    ---------------------
 *
 *    ir_node *new_CopyB (ir_node *store, ir_node *dst, ir_node *src, ir_type *data_type)
 *    -----------------------------------------------------------------------------------
 *
 *    Describes a high level block copy of a compound type from address src to
 *    address dst. Must be lowered to a Call to a runtime memory copy function.
 *
 *
 *    HIGH LEVEL OPERATIONS: Exception Support
 *    ----------------------------------------
 *    See TechReport 1999-14, chapter Exceptions.
 *
 *    ir_node *new_InstOf(ir_node *store, ir_node *ptr, ir_type *type);
 *    -----------------------------------------------------------------------------------
 *
 *    Describes a high level type check. Must be lowered to a Call to a runtime check
 *    function.
 *
 *    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.  Must be lowered to a Call to a runtime check
 *    function.
 *
 *    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_Bound  (ir_node *store, ir_node *idx, ir_node *lower, ir_node *upper);
 *    -----------------------------------------------------------------------------------
 *
 *    Describes a high level bounds check. Must be lowered to a Call to a runtime check
 *    function.
 *
Michael Beck's avatar
Michael Beck committed
1043
1044
1045
1046
1047
1048
1049
 *    ir_node *new_Pin  (ir_node *node);
 *    -----------------------------------------------------------------------------------
 *
 *    Pin the value of the node node in the current block  No users of the Pin node can
 *    float above the Block of the Pin. The node cannot float behind this block. Often
 *    used to Pin the NoMem node.
 *
1050
 *
Boris Boesler's avatar
Boris Boesler committed
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
 *    COPING WITH DATA OBJECTS
 *    ========================
 *
 *    Two kinds of data objects have to be distinguished for generating
 *    FIRM.  First there are local variables other than arrays that are
 *    known to be alias free.  Second there are all other data objects.
 *    For the first a common SSA representation is built, the second
 *    are modeled by saving them to memory.  The memory is treated as
 *    a single local variable, the alias problem is hidden in the
 *    content of this variable.
 *
 *    All values known in a Block are listed in the block's attribute,
 *    block.**graph_arr which is used to automatically insert Phi nodes.
Michael Beck's avatar
Michael Beck committed
1064
 *    The following two functions can be used to add a newly computed value
Boris Boesler's avatar
Boris Boesler committed
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
 *    to the array, or to get the producer of a value, i.e., the current
 *    live value.
 *
 *    inline void set_value (int pos, ir_node *value)
 *    -----------------------------------------------
 *
 *    Has to be called for every assignment to a local variable.  It
 *    adds the value to the array of used values at position pos.  Pos
 *    has to be a unique identifier for an entry in the procedure's
 *    definition table.  It can be used to access the value again.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1075
 *    Requires current_block to be set correctly.
Boris Boesler's avatar
Boris Boesler committed
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
 *
 *    ir_node *get_value (int pos, ir_mode *mode)
 *    -------------------------------------------
 *
 *    Returns the node defining the value referred to by pos. If the
 *    value is not defined in this block a Phi node is generated and
 *    all definitions reaching this Phi node are collected.  It can
 *    happen that the algorithm allocates an unnecessary Phi node,
 *    e.g. if there is only one definition of this value, but this
 *    definition reaches the currend block on several different
 *    paths.  This Phi node will be eliminated if optimizations are
 *    turned on right after it's creation.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1088
 *    Requires current_block to be set correctly.
Boris Boesler's avatar
Boris Boesler committed
1089
1090
1091
 *
 *    There are two special routines for the global store:
 *
Michael Beck's avatar
Michael Beck committed
1092
1093
 *    void set_store (ir_node *store)
 *    -------------------------------
Boris Boesler's avatar
Boris Boesler committed
1094
1095
1096
 *
 *    Adds the store to the array of known values at a reserved
 *    position.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1097
 *    Requires current_block to be set correctly.
Boris Boesler's avatar
Boris Boesler committed
1098
 *
Michael Beck's avatar
Michael Beck committed
1099
1100
 *    ir_node *get_store (void)
 *    -------------------------
Boris Boesler's avatar
Boris Boesler committed
1101
1102
 *
 *    Returns the node defining the actual store.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1103
 *    Requires current_block to be set correctly.
1104
1105
1106
1107
1108
1109
1110
 *
 *
 *    inline void keep_alive (ir_node *ka)
 *    ------------------------------------
 *
 *    Keep this node alive because it is (might be) not in the control
 *    flow from Start to End.  Adds the node to the list in the end
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1111
 *   node.
1112
 *
Boris Boesler's avatar
Boris Boesler committed
1113
 */
Matthias Braun's avatar
Matthias Braun committed
1114
1115
#ifndef FIRM_IR_IRCONS_H
#define FIRM_IR_IRCONS_H
Christian Schäfer's avatar
Christian Schäfer committed
1116

Matthias Braun's avatar
Matthias Braun committed
1117
#include "firm_types.h"
1118
#include "begin.h"
1119
#include "irnode.h"
Christian Schäfer's avatar
Christian Schäfer committed
1120

1121
1122
1123
1124
1125
1126
1127
1128
1129
/**
 * constrained flags for memory operations.
 */
typedef enum ir_cons_flags {
	cons_none      = 0,        /**< No constrains. */
	cons_volatile  = 1U << 0,  /**< Memory operation is volatile. */
	cons_unaligned = 1U << 1,  /**< Memory operation is unaligned. */
	cons_floats    = 1U << 2   /**< Memory operation can float. */
} ir_cons_flags;
1130

Michael Beck's avatar
Michael Beck committed
1131
/*-------------------------------------------------------------------------*/
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1132
/* The raw interface                                                       */
Michael Beck's avatar
Michael Beck committed
1133
/*-------------------------------------------------------------------------*/
Christian Schäfer's avatar
Christian Schäfer committed
1134

Götz Lindenmaier's avatar
Götz Lindenmaier committed
1135
1136
/** Constructor for a Block node.
 *
1137
 * Constructs a mature block with the given predecessors.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1138
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1139
 * @param *db    A Pointer for  debug information.
1140
 * @param irg    The IR graph the block belongs to.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1141
 * @param arity  The number of control predecessors.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1142
1143
 * @param in[]   An array of control predecessors.  The length of
 *               the array must be 'arity'.  The constructor copies this array.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1144
 */
Michael Beck's avatar
Michael Beck committed
1145
FIRM_API ir_node *new_rd_Block(dbg_info *db, ir_graph *irg, int arity, ir_node *in[]);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1146

Götz Lindenmaier's avatar
Götz Lindenmaier committed
1147
/** Constructor for a Start node.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1148
1149
 *
 * @param *db    A pointer for debug information.
1150
1151
 * @param *irg   The IR graph the node belongs to.
 * @param *block The IR block the node belongs to.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1152
 */
1153
FIRM_API ir_node *new_rd_Start(dbg_info *db, ir_node *block);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1154

Götz Lindenmaier's avatar
Götz Lindenmaier committed
1155
/** Constructor for a End node.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1156
1157
 *
 * @param *db    A pointer for  debug information.
1158
1159
 * @param *irg   The IR graph the node  belongs to.
 * @param *block The IR block the node belongs to.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1160
 */
1161
FIRM_API ir_node *new_rd_End(dbg_info *db, ir_node *block);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1162

Götz Lindenmaier's avatar
Götz Lindenmaier committed
1163
1164
/** Constructor for a Jmp node.
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1165
 * Jmp represents control flow to a single control successor.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1166
1167
 *
 * @param *db     A pointer for debug information.
1168
 * @param *block  The IR block the node belongs to.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1169
 */
Michael Beck's avatar
Michael Beck committed
1170
FIRM_API ir_node *new_rd_Jmp(dbg_info *db, ir_node *block);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1171

1172
1173
1174
1175
1176
1177
/** Constructor for an IJmp node.
 *
 * IJmp represents control flow to a single control successor not
 * statically known i.e. an indirect Jmp.
 *
 * @param *db     A pointer for debug information.
1178
1179
 * @param *block  The IR block the node belongs to.
 * @param *tgt    The IR node representing the target address.
1180
 */
Michael Beck's avatar
Michael Beck committed
1181
FIRM_API ir_node *new_rd_IJmp(dbg_info *db, ir_node *block, ir_node *tgt);
1182

Götz Lindenmaier's avatar
Götz Lindenmaier committed
1183
1184
1185
1186
1187
1188
1189
1190
/** Constructor for a Cond node.
 *
 * If c is mode_b represents a conditional branch (if/else). If c is
 * mode_Is/mode_Iu (?) represents a switch.  (Allocates dense Cond
 * node, default Proj is 0.)
 *
 * This is not consistent:  Input to Cond is Is, Proj has as proj number
 * longs.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1191
1192
 *
 * @param *db    A pointer for debug information.
1193
 * @param *block The IR block the node belongs to.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1194
 * @param *c     The conditions parameter. Can be of mode b or I_u.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1195
 */
Michael Beck's avatar
Michael Beck committed
1196
FIRM_API ir_node *new_rd_Cond(dbg_info *db, ir_node *block, ir_node *c);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1197

Götz Lindenmaier's avatar
Götz Lindenmaier committed
1198
1199
/** Constructor for a Return node.
 *
Christoph Mallon's avatar
Christoph Mallon committed
1200
 * Returns the memory and zero or more return values.  Only node that
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1201
 * can end regular control flow.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1202
1203
 *
 * @param *db    A pointer for debug information.
1204
 * @param *block The IR block the node belongs to.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1205
 * @param *store The state of memory.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1206
1207
 * @param arity  Number of return values.
 * @param *in    Array of length arity with return values.  The constructor copies this array.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1208
 */
Michael Beck's avatar
Michael Beck committed
1209
FIRM_API ir_node *new_rd_Return(dbg_info *db, ir_node *block,
1210
                                ir_node *store, int arity, ir_node *in[]);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1211

Beyhan's avatar
Beyhan committed
1212
/** Constructor for a Const_type node.
1213
1214
 *
 * Adds the node to the start block.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1215
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1216
1217
 * The constant represents a target value.  This constructor sets high
 * level type information for the constant value.
1218
 * Derives mode from passed tarval.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1219
1220
 *
 * @param *db    A pointer for debug information.
1221
 * @param *irg   The IR graph the node  belongs to.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1222
 * @param *con   Points to an entry in the constant table.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1223
1224
 * @param *tp    The type of the constant.
 */
Michael Beck's avatar
Michael Beck committed
1225
FIRM_API ir_node *new_rd_Const_type(dbg_info *db, ir_graph *irg,
1226
                                    tarval *con, ir_type *tp);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1227

Götz Lindenmaier's avatar
Götz Lindenmaier committed
1228
/** Constructor for a Const node.
1229
1230
 *
 * Adds the node to the start block.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1231
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1232
1233
1234
 * Constructor for a Const node. The constant represents a target
 * value.  Sets the type information to type_unknown.  (No more
 * supported: If tv is entity derives a somehow useful type.)
1235
 * Derives mode from passed tarval.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1236
1237
 *
 * @param *db    A pointer for debug information.
1238
 * @param *irg   The IR graph the node  belongs to.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1239
 * @param *con   Points to an entry in the constant table.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1240
 */
Michael Beck's avatar
Michael Beck committed
1241
FIRM_API ir_node *new_rd_Const(dbg_info *db, ir_graph *irg, tarval *con);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1242

1243
1244
/**
 * Constructor for a Const node.
yb9976's avatar
yb9976 committed
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
 *
 * Adds the node to the start block.
 *
 * Constructor for a Const node. The constant represents a target
 * value.  Sets the type information to type_unknown.  (No more
 * supported: If tv is entity derives a somehow useful type.)
 *
 * @param *db    A pointer for debug information.
 * @param *irg   The IR graph the node  belongs to.
 * @param *mode  The mode of the operands and results.
 * @param value  A value from which the tarval is made.
 */
Michael Beck's avatar
Michael Beck committed
1257
FIRM_API ir_node *new_rd_Const_long(dbg_info *db, ir_graph *irg,
1258
                                    ir_mode *mode, long value);
yb9976's avatar
yb9976 committed
1259

Beyhan's avatar
Beyhan committed
1260
/** Constructor for a SymConst_type node.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1261
1262
 *
 *  This is the constructor for a symbolic constant.
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
 *    There are several kinds of symbolic constants:
 *    - symconst_type_tag   The symbolic constant represents a type tag.  The
 *                          type the tag stands for is given explicitly.
 *    - symconst_type_size  The symbolic constant represents the size of a type.
 *                          The type of which the constant represents the size
 *                          is given explicitly.
 *    - symconst_type_align The symbolic constant represents the alignment of a
 *                          type.  The type of which the constant represents the
 *                          size is given explicitly.
 *    - symconst_addr_ent   The symbolic constant represents the address of an
 *                          entity (variable or method).  The variable is given
 *                          explicitly by a firm entity.
 *    - symconst_ofs_ent    The symbolic constant represents the offset of an
 *                          entity in its owner type.
 *    - symconst_enum_const The symbolic constant is a enumeration constant of
 *                          an enumeration type.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1279
1280
 *
 *    Inputs to the node:
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1281
 *      No inputs except the block it belongs to.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1282
1283
1284
 *    Outputs of the node.
 *      An unsigned integer (I_u) or a pointer (P).
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1285
1286
1287
 *    Mention union in declaration so that the firmjni generator recognizes that
 *    it can not cast the argument to an int.
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1288
 * @param *db     A pointer for debug information.
1289
1290
 * @param *irg    The IR graph the node  belongs to.
 * @param mode    The mode for the SymConst.
1291
 * @param val     A type, ident, entity or enum constant depending on the
1292
1293
 *                SymConst kind.
 * @param kind    The kind of the symbolic constant, see the list above
Beyhan's avatar
Beyhan committed
1294
 * @param tp      The source type of the constant.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1295
 */
Michael Beck's avatar
Michael Beck committed
1296
FIRM_API ir_node *new_rd_SymConst_type(dbg_info *db, ir_graph *irg,
1297
1298
                                       ir_mode *mode, union symconst_symbol val,
                                       symconst_kind kind, ir_type *tp);
Beyhan's avatar
Beyhan committed
1299
1300
1301

/** Constructor for a SymConst node.
 *
1302
1303
 *  Same as new_rd_SymConst_type, except that it sets the type to type_unknown.
 */
Michael Beck's avatar
Michael Beck committed
1304
FIRM_API ir_node *new_rd_SymConst(dbg_info *db, ir_graph *irg, ir_mode *mode,
1305
1306
                                  union symconst_symbol value,
                                  symconst_kind kind);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1307
1308
1309
1310
1311

/** Constructor for a SymConst addr_ent node.
 *
 * Same as new_rd_SymConst_type, except that the constructor is tailored for
 * symconst_addr_ent.
Michael Beck's avatar
Michael Beck committed
1312
 * Adds the SymConst to the start block of irg. */
Michael Beck's avatar
Michael Beck committed
1313
FIRM_API ir_node *new_rd_SymConst_addr_ent(dbg_info *db, ir_graph *irg,
1314
1315
                                           ir_mode *mode, ir_entity *symbol,
                                           ir_type *tp);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
1316

1317
1318
1319
1320
/** Constructor for a SymConst ofs_ent node.
 *
 * Same as new_rd_SymConst_type, except that the constructor is tailored for
 * symconst_ofs_ent.
1321
1322
 * Adds the SymConst to the start block of irg.
 */
Michael Beck's avatar
Michael Beck committed
1323
FIRM_API ir_node *new_rd_SymConst_ofs_ent(dbg_info *db, ir_graph *irg,
1324
1325
                                          ir_mode *mode, ir_entity *symbol,
                                          ir_type *tp);
1326

Götz Lindenmaier's avatar
Götz Lindenmaier committed