ircons.h 37.6 KB
Newer Older
Christian Würdig's avatar
Christian Würdig committed
1
2
/*
 * This file is part of libFirm.
3
 * Copyright (C) 2012 University of Karlsruhe.
Christian Würdig's avatar
Christian Würdig committed
4
5
 */

Matthias Braun's avatar
Matthias Braun committed
6
7
8
9
10
11
/**
 * @file
 * @brief   Various irnode constructors. Automatic construction of SSA
 *          representation.
 * @author  Martin Trapp, Christian Schaefer, Goetz Lindenmaier, Boris Boesler,
 *          Michael Beck
Götz Lindenmaier's avatar
Götz Lindenmaier committed
12
 */
Christian Schäfer's avatar
Christian Schäfer committed
13

Sebastian Felis's avatar
Sebastian Felis committed
14
/**
Matthias Braun's avatar
Matthias Braun committed
15
 *  @file
Michael Beck's avatar
Michael Beck committed
16
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
17
18
 *  documentation no more supported since 2001
 *
19
 *  IR node construction.
Boris Boesler's avatar
Boris Boesler committed
20
 *
Boris Boesler's avatar
Boris Boesler committed
21
 *    This file documents all datatypes and constructors needed to
Götz Lindenmaier's avatar
Götz Lindenmaier committed
22
 *    build a FIRM representation of a procedure.  The constructors are
Boris Boesler's avatar
Boris Boesler committed
23
24
25
26
27
28
29
30
31
32
 *    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
 *    --------------------
 *
33
 *      There are three kinds of nodes known to the IR:  entities,
Boris Boesler's avatar
Boris Boesler committed
34
35
36
37
38
39
40
41
42
43
44
45
46
 *      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
47
 *       nodes.
Boris Boesler's avatar
Boris Boesler committed
48
49
50
51
52
53
54
55
56
 *
 *    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
57
 *      executable if every input at its incoming edges is available.
Boris Boesler's avatar
Boris Boesler committed
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 *      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
72
 *      contains pointers to its predecessors so that the implementation is a
Boris Boesler's avatar
Boris Boesler committed
73
74
75
 *      dataflow graph with reversed edges.  It has to be traversed bottom
 *      up.
 *
76
 *      All nodes of the IR have the same basic structure.  They are
Boris Boesler's avatar
Boris Boesler committed
77
78
79
80
81
82
83
84
85
86
87
88
 *      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
89
90
91
 *                       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
92
 *
93
 *      visit            A flag for traversing the IR.
Boris Boesler's avatar
Boris Boesler committed
94
95
96
97
 *
 *      **in             An array with pointers to the node's predecessors.
 *
 *      *link            A pointer to an ir_node.  With this pointer all Phi nodes
98
 *                       are attached to a Block, i.e. a Block points to its
Boris Boesler's avatar
Boris Boesler committed
99
 *                       first Phi node, this node points to the second Phi node
100
 *                       in the Block and so forth.  Used in mature_immBlock
Boris Boesler's avatar
Boris Boesler committed
101
 *                       to find all Phi nodes to be matured.  It's also used to
102
 *                       annotate a node with a better, optimized version of it.
Boris Boesler's avatar
Boris Boesler committed
103
104
105
 *
 *      attr             An attr struct containing the attributes of the nodes. The
 *                       attributes depend on the opcode of the node.  The number
106
 *                       of these attributes is given in op.
Boris Boesler's avatar
Boris Boesler committed
107
108
109
110
111
112
113
114
115
 *
 *    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
116
 *    GLOBAL VARIABLES -- now also fields of ir_graph.
Boris Boesler's avatar
Boris Boesler committed
117
118
119
 *    ================
 *
 *    current_ir_graph   Points to the current ir_graph.  All constructors for
120
 *                       nodes add nodes to this graph.
Boris Boesler's avatar
Boris Boesler committed
121
122
123
124
125
126
127
128
129
130
 *
 *    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
131
 *    CONSTRUCTOR FOR IR_GRAPH --> see irgraph.h
Boris Boesler's avatar
Boris Boesler committed
132
133
134
 *    ========================
 *
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
135
 *    PROCEDURE TO CONSTRUCT AN IR GRAPH --> see also Firm tutorial
Boris Boesler's avatar
Boris Boesler committed
136
137
138
139
 *    ==================================
 *
 *    This library supplies several interfaces to construct a FIRM graph for
 *    a program:
Michael Beck's avatar
Michael Beck committed
140
 *    - A "comfortable" interface generating SSA automatically.  Automatically
Boris Boesler's avatar
Boris Boesler committed
141
142
 *      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
143
 *    - A less comfortable interface where all predecessors except the block
Boris Boesler's avatar
Boris Boesler committed
144
 *      an operation belongs to need to be specified.  SSA must be constructed
145
 *      by hand.  (new_<Node> constructors and set_cur_block()).  This interface
Boris Boesler's avatar
Boris Boesler committed
146
147
 *      is called "block oriented".  It automatically calles the local optimizations
 *      for each new node.
Michael Beck's avatar
Michael Beck committed
148
 *    - An even less comfortable interface where the block needs to be specified
Boris Boesler's avatar
Boris Boesler committed
149
150
151
152
153
154
 *      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
155
 *    the firm node (See tech-reprot UKA 1999-14).  For the construction of
Boris Boesler's avatar
Boris Boesler committed
156
157
158
159
160
 *    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
161
 *    out of the procedure.  Often these are all compiler generated
Boris Boesler's avatar
Boris Boesler committed
162
163
164
165
 *    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
166
 *    constructor gets the number of local variables.  The graph is held in the
Boris Boesler's avatar
Boris Boesler committed
167
168
169
170
171
172
173
174
 *    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
175
 *    set_cur_block(block).  If several blocks are constructed in parallel block
Boris Boesler's avatar
Boris Boesler committed
176
177
 *    switches need to be performed constantly.
 *
Christoph Mallon's avatar
Christoph Mallon committed
178
 *    To generate a Block node (with the comfortable interface), its predecessor
Boris Boesler's avatar
Boris Boesler committed
179
 *    control flow nodes need not be known.  In case of cyclic control flow these
180
 *    can not be known when the block is constructed.  With add_immBlock_pred(block,
Boris Boesler's avatar
Boris Boesler committed
181
 *    cfnode) predecessors can be added to the block.  If all predecessors are
182
 *    added to the block mature_immBlock(b) needs to be called.  Calling mature_immBlock
Boris Boesler's avatar
Boris Boesler committed
183
 *    early improves the efficiency of the Phi node construction algorithm.
184
 *    But if several  blocks are constructed at once, mature_immBlock must only
Boris Boesler's avatar
Boris Boesler committed
185
186
187
188
189
190
 *    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
191
 *    values, the predecessors can be obtained from the library with a call to
Boris Boesler's avatar
Boris Boesler committed
192
193
 *    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.
194
 *    If an arithmetic operation produces a local value, this value needs to be
Boris Boesler's avatar
Boris Boesler committed
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 *    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();
216
217
218
 *    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
219
 *    a_val = get_value(42, mode_Iu);
Boris Boesler's avatar
Boris Boesler committed
220
 *    mem = get_store();
221
222
223
 *    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
224
 *    set_store(mem);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
225
 *    set_value(res, 42);
Boris Boesler's avatar
Boris Boesler committed
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 *    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.
 *
 *    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
 *
 *    ------------
 *
 *    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
267
 *    The following two functions can be used to add a newly computed value
Boris Boesler's avatar
Boris Boesler committed
268
269
270
271
272
273
274
275
276
277
 *    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
278
 *    Requires current_block to be set correctly.
Boris Boesler's avatar
Boris Boesler committed
279
280
281
282
283
284
285
286
287
288
289
 *
 *    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
290
 *    turned on right after its creation.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
291
 *    Requires current_block to be set correctly.
Boris Boesler's avatar
Boris Boesler committed
292
293
294
 *
 *    There are two special routines for the global store:
 */
Matthias Braun's avatar
Matthias Braun committed
295
296
#ifndef FIRM_IR_IRCONS_H
#define FIRM_IR_IRCONS_H
Christian Schäfer's avatar
Christian Schäfer committed
297

Matthias Braun's avatar
Matthias Braun committed
298
#include "firm_types.h"
299
#include "begin.h"
300
#include "irnode.h"
Christian Schäfer's avatar
Christian Schäfer committed
301

Matthias Braun's avatar
Matthias Braun committed
302
303
304
/** @addtogroup Const
 * @{
 */
Christian Schäfer's avatar
Christian Schäfer committed
305

306
307
/**
 * Constructor for a Const node.
yb9976's avatar
yb9976 committed
308
309
310
 *
 * Adds the node to the start block.
 *
311
 * The constant represents a target value.
yb9976's avatar
yb9976 committed
312
313
314
315
316
317
 *
 * @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
318
FIRM_API ir_node *new_rd_Const_long(dbg_info *db, ir_graph *irg,
319
                                    ir_mode *mode, long value);
yb9976's avatar
yb9976 committed
320

Matthias Braun's avatar
Matthias Braun committed
321
322
323
324
/** Constructor for a Const node.
 *
 * Adds the node to the start block.
 *
325
 * The constant represents a target value.
Matthias Braun's avatar
Matthias Braun committed
326
327
328
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
 *
 * @param *irg   The IR graph the node  belongs to.
 * @param *mode  The mode of the operands and the results.
 * @param value  A value from which the tarval is made.
 */
FIRM_API ir_node *new_r_Const_long(ir_graph *irg, ir_mode *mode, long value);

/**
 * @see new_rd_Const_long()
 *
 * @param *db    A pointer for debug information.
 * @param *mode  The mode of the operands and results.
 * @param value  A value from which the tarval is made.
 */
FIRM_API ir_node *new_d_Const_long(dbg_info *db, ir_mode *mode, long value);

/**
 * Make a const from a long.
 * This is just convenience for the usual
 * <code>
 * new_Const(mode, tarval_from_long(mode, ...))
 * </code>
 * pain.
 * @param mode The mode for the const.
 * @param value The value of the constant.
 * @return A new const node.
 */
FIRM_API ir_node *new_Const_long(ir_mode *mode, long value);

/** @} */

/** addtogroup SymConst
 * @{
 */

361
/** Constructor for a SymConst node.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
362
363
 *
 *  This is the constructor for a symbolic constant.
364
365
366
367
368
369
370
371
372
373
374
375
376
377
 *    There are several kinds of symbolic constants:
 *    - 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
378
379
 *
 *    Inputs to the node:
Götz Lindenmaier's avatar
Götz Lindenmaier committed
380
 *      No inputs except the block it belongs to.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
381
382
383
 *    Outputs of the node.
 *      An unsigned integer (I_u) or a pointer (P).
 *
Götz Lindenmaier's avatar
Götz Lindenmaier committed
384
385
386
 *    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
387
 * @param *db     A pointer for debug information.
388
389
 * @param *irg    The IR graph the node  belongs to.
 * @param mode    The mode for the SymConst.
Matthias Braun's avatar
Matthias Braun committed
390
 * @param value   A type, ident, entity or enum constant depending on the
391
392
 *                SymConst kind.
 * @param kind    The kind of the symbolic constant, see the list above
393
 */
Michael Beck's avatar
Michael Beck committed
394
FIRM_API ir_node *new_rd_SymConst(dbg_info *db, ir_graph *irg, ir_mode *mode,
395
396
                                  union symconst_symbol value,
                                  symconst_kind kind);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
397
398
399

/** Constructor for a SymConst addr_ent node.
 *
400
 * Same as new_rd_SymConst, except that the constructor is tailored for
Götz Lindenmaier's avatar
Götz Lindenmaier committed
401
 * symconst_addr_ent.
Matthias Braun's avatar
Matthias Braun committed
402
403
 * Adds the SymConst to the start block of irg.
 */
Michael Beck's avatar
Michael Beck committed
404
FIRM_API ir_node *new_rd_SymConst_addr_ent(dbg_info *db, ir_graph *irg,
405
                                           ir_mode *mode, ir_entity *symbol);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
406

407
408
/** Constructor for a SymConst ofs_ent node.
 *
409
 * Same as new_rd_SymConst, except that the constructor is tailored for
410
 * symconst_ofs_ent.
411
412
 * Adds the SymConst to the start block of irg.
 */
Michael Beck's avatar
Michael Beck committed
413
FIRM_API ir_node *new_rd_SymConst_ofs_ent(dbg_info *db, ir_graph *irg,
414
                                          ir_mode *mode, ir_entity *symbol);
415

Götz Lindenmaier's avatar
Götz Lindenmaier committed
416
417
/** Constructor for a SymConst size node.
 *
418
 * Same as new_rd_SymConst, except that the constructor is tailored for
419
 * symconst_type_size.
Matthias Braun's avatar
Matthias Braun committed
420
421
 * Adds the SymConst to the start block of irg.
 */
Michael Beck's avatar
Michael Beck committed
422
FIRM_API ir_node *new_rd_SymConst_size(dbg_info *db, ir_graph *irg,
423
                                       ir_mode *mode, ir_type *symbol);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
424

425
426
/** Constructor for a SymConst size node.
 *
427
 * Same as new_rd_SymConst, except that the constructor is tailored for
428
 * symconst_type_align.
429
430
 * Adds the SymConst to the start block of irg.
 */
Michael Beck's avatar
Michael Beck committed
431
FIRM_API ir_node *new_rd_SymConst_align(dbg_info *db, ir_graph *irg,
432
                                        ir_mode *mode, ir_type *symbol);
433

434
/** Constructor for a SymConst node.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
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
 *  This is the constructor for a symbolic constant.
 *    There are several kinds of symbolic constants:
 *    - 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.
 *
 *    Inputs to the node:
 *      No inputs except the block it belongs to.
 *    Outputs of the node.
 *      An unsigned integer (I_u) or a pointer (P).
 *
 *    Mention union in declaration so that the firmjni generator recognizes that
 *    it can not cast the argument to an int.
 *
 * @param *irg    The IR graph the node  belongs to.
 * @param mode    The mode for the SymConst.
 * @param value   A type, ident, entity or enum constant depending on the
 *                SymConst kind.
 * @param kind    The kind of the symbolic constant, see the list above
Götz Lindenmaier's avatar
Götz Lindenmaier committed
465
 */
466
467
468
FIRM_API ir_node *new_r_SymConst(ir_graph *irg, ir_mode *mode,
                                 union symconst_symbol value,
                                 symconst_kind kind);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
469

Matthias Braun's avatar
Matthias Braun committed
470
/** Constructor for an SymConst node
Götz Lindenmaier's avatar
Götz Lindenmaier committed
471
 *
Matthias Braun's avatar
Matthias Braun committed
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
 *  This is the constructor for a symbolic constant.
 *    There are several kinds of symbolic constants:
 *    - 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
487
 *
Matthias Braun's avatar
Matthias Braun committed
488
489
490
491
 *    Inputs to the node:
 *      No inputs except the block it belongs to.
 *    Outputs of the node.
 *      An unsigned integer (I_u) or a pointer (P).
Götz Lindenmaier's avatar
Götz Lindenmaier committed
492
 *
Matthias Braun's avatar
Matthias Braun committed
493
494
 *    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
495
 *
Matthias Braun's avatar
Matthias Braun committed
496
497
498
499
500
 * @param *db     A pointer for debug information.
 * @param mode    The mode for the SymConst.
 * @param value   A type, ident, entity or enum constant depending on the
 *                SymConst kind.
 * @param kind    The kind of the symbolic constant, see the list above
Götz Lindenmaier's avatar
Götz Lindenmaier committed
501
 */
Matthias Braun's avatar
Matthias Braun committed
502
503
504
FIRM_API ir_node *new_d_SymConst(dbg_info *db, ir_mode *mode,
                                 union symconst_symbol value,
                                 symconst_kind kind);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
505

506
/** Constructor for a SymConst node.
507
 *
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
 *  This is the constructor for a symbolic constant.
 *    There are several kinds of symbolic constants:
 *    - 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.
523
 *
524
525
526
527
 *    Inputs to the node:
 *      No inputs except the block it belongs to.
 *    Outputs of the node.
 *      An unsigned integer (I_u) or a pointer (P).
Beyhan's avatar
Beyhan committed
528
 *
529
530
 *    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
531
 *
532
533
534
535
 * @param mode    The mode for the SymConst.
 * @param value   A type, ident, entity or enum constant depending on the
 *                SymConst kind.
 * @param kind    The kind of the symbolic constant, see the list above
Götz Lindenmaier's avatar
Götz Lindenmaier committed
536
 */
Matthias Braun's avatar
Matthias Braun committed
537
538
539
540
541
542
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
FIRM_API ir_node *new_SymConst(ir_mode *mode, union symconst_symbol value,
                               symconst_kind kind);

/** @} */

/** @addtogroup Sel
 * @{
 */

/** Constructor for a simpleSel node.
 *
 *  This is a shortcut for the new_rd_Sel() constructor.  To be used for
 *  Sel nodes that do not select from an array, i.e., have no index
 *  inputs.  It adds the two parameters 0, NULL.
 *
 * @param   *db        A pointer for debug information.
 * @param   *block     The IR block the node belongs to.
 * @param   *store     The memory in which the object the entity should be
 *                     selected from is allocated.
 * @param   *objptr    The object from that the Sel operation selects a
 *                     single attribute out.
 * @param   *ent       The entity to select.
 */
FIRM_API ir_node *new_rd_simpleSel(dbg_info *db, ir_node *block, ir_node *store,
                                   ir_node *objptr, ir_entity *ent);

/** Constructor for a simpleSel node.
 *
 *  This is a shortcut for the new_d_Sel() constructor.  To be used for
 *  Sel nodes that do not select from an array, i.e., have no index
 *  inputs.  It adds the two parameters 0, NULL.
 *
 * @param *block     The IR block the node belongs to.
 * @param *store     The memory in which the object the entity should be selected
 *                   from is allocated.
 * @param *objptr    The object from that the Sel operation selects a
 *                   single attribute out.
 * @param *ent       The entity to select.
 * @ingroup Sel
 */
FIRM_API ir_node *new_r_simpleSel(ir_node *block, ir_node *store,
                                  ir_node *objptr, ir_entity *ent);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
579

580
/** Constructor for a simpleSel node.
581
 *
582
583
584
 *  This is a shortcut for the new_d_Sel() constructor.  To be used for
 *  Sel nodes that do not select from an array, i.e., have no index
 *  inputs.  It adds the two parameters 0, NULL.
585
 *
586
587
588
589
590
591
 * @param   *db        A pointer for debug information.
 * @param   *store     The memory in which the object the entity should be
 *                     selected from is allocated.
 * @param   *objptr    The object from that the Sel operation selects a
 *                     single attribute out.
 * @param   *ent       The entity to select.
592
 */
593
594
FIRM_API ir_node *new_d_simpleSel(dbg_info *db, ir_node *store, ir_node *objptr,
                                  ir_entity *ent);
Matthias Braun's avatar
Matthias Braun committed
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
628
629
630
631
632
633
634
635
636
637
638
639
640
641

/** Constructor for a simpelSel node.
 *
 *  This is a shortcut for the new_Sel() constructor.  To be used for
 *  Sel nodes that do not select from an array, i.e., have no index
 *  inputs.  It adds the two parameters 0, NULL.
 *
 * @param   *store     The memory in which the object the entity should be selected from is allocated.
 * @param   *objptr    The object from that the Sel operation selects a single attribute out.
 * @param   *ent       The entity to select.
 */
FIRM_API ir_node *new_simpleSel(ir_node *store, ir_node *objptr,
                                ir_entity *ent);

/** @} */

/** @addtogroup Div
 * @{
 */

/** Constructor for a remainderless Div node.
 *
 * @param   *db    A pointer for debug information.
 * @param   *block The IR block the node belongs to.
 * @param   *memop The store needed to model exceptions
 * @param   *op1   The first operand.
 * @param   *op2   The second operand.
 * @param   *mode  The mode of the result.
 * @param   state  The pinned state.
 */
FIRM_API ir_node *new_rd_DivRL(dbg_info *db, ir_node *block, ir_node *memop,
                               ir_node *op1, ir_node *op2, ir_mode *mode,
                               op_pin_state state);

/** Constructor for a remainderless Div node.
 *
 * @param *block The IR block the node belongs to.
 * @param *memop The store needed to model exceptions
 * @param *op1   The first operand.
 * @param *op2   The second operand.
 * @param *mode  The mode of the result.
 * @param state  The pinned state.
 */
FIRM_API ir_node *new_r_DivRL(ir_node *block, ir_node *memop,
                              ir_node *op1, ir_node *op2, ir_mode *mode,
                              op_pin_state state);

642
/** Constructor for a remainderless Div node.
643
644
645
 *
 * Adds the node to the block in current_ir_block.
 *
646
647
 * @param   *db    A pointer for debug information.
 * @param   *memop The store needed to model exceptions
648
649
 * @param   *op1   The first operand.
 * @param   *op2   The second operand.
650
651
 * @param   *mode  The mode of the result.
 * @param   state  The pinned state.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
652
 */
653
654
655
FIRM_API ir_node *new_d_DivRL(dbg_info *db, ir_node *memop,
                              ir_node *op1, ir_node *op2, ir_mode *mode,
                              op_pin_state state);
Matthias Braun's avatar
Matthias Braun committed
656
657

/** Constructor for a remainderless Div node.
Beyhan's avatar
Beyhan committed
658
659
 *
 * Adds the node to the block in current_ir_block.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
660
 *
Matthias Braun's avatar
Matthias Braun committed
661
662
663
664
665
666
667
668
669
670
671
672
673
 * @param   *memop The store needed to model exceptions
 * @param   *op1   The first operand.
 * @param   *op2   The second operand.
 * @param   *mode  The mode of the result.
 * @param   state  The pinned state.
 */
FIRM_API ir_node *new_DivRL(ir_node *memop, ir_node *op1, ir_node *op2,
                            ir_mode *mode, op_pin_state state);

/** @} */

/** @addtogroup ASM
 * @{
Götz Lindenmaier's avatar
Götz Lindenmaier committed
674
675
 */

676
/** Constructor for an ASM pseudo node.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
677
 *
678
 * @param *db         A pointer for debug information.
Matthias Braun's avatar
Matthias Braun committed
679
 * @param *block      The block the node belong to.
680
 * @param *mem        memory dependency
681
682
683
684
685
686
687
688
 * @param arity       The number of data inputs to the node.
 * @param *in         The array of length arity of data inputs.
 * @param *inputs     The array of length arity of input constraints.
 * @param n_outs      The number of data outputs to the node.
 * @param *outputs    The array of length n_outs of output constraints.
 * @param n_clobber   The number of clobbered registers.
 * @param *clobber    The array of length n_clobber of clobbered registers.
 * @param *asm_text   The assembler text.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
689
 */
690
FIRM_API ir_node *new_rd_ASM(dbg_info *db, ir_node *block, ir_node *mem,
Matthias Braun's avatar
Matthias Braun committed
691
                            int arity, ir_node *in[], ir_asm_constraint *inputs,
692
693
694
                            size_t n_outs, ir_asm_constraint *outputs,
                            size_t n_clobber, ident *clobber[],
                            ident *asm_text);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
695

Matthias Braun's avatar
Matthias Braun committed
696
/** Constructor for an ASM pseudo node.
Michael Beck's avatar
Michael Beck committed
697
 *
Matthias Braun's avatar
Matthias Braun committed
698
 * @param *block      The block the node belong to.
699
 * @param *mem        memory dependency
Matthias Braun's avatar
Matthias Braun committed
700
701
702
703
704
705
706
707
 * @param arity       The number of data inputs to the node.
 * @param *in         The array of length arity of data inputs.
 * @param *inputs     The array of length arity of input constraints.
 * @param n_outs      The number of data outputs to the node.
 * @param *outputs    The array of length n_outs of output constraints.
 * @param n_clobber   The number of clobbered registers.
 * @param *clobber    The array of length n_clobber of clobbered registers.
 * @param *asm_text   The assembler text.
708
 */
709
FIRM_API ir_node *new_r_ASM(ir_node *block, ir_node *mem,
Matthias Braun's avatar
Matthias Braun committed
710
711
712
713
                            int arity, ir_node *in[], ir_asm_constraint *inputs,
                            size_t n_outs, ir_asm_constraint *outputs,
                            size_t n_clobber, ident *clobber[],
                            ident *asm_text);
714

Matthias Braun's avatar
Matthias Braun committed
715
/** Constructor for an ASM pseudo node.
716
 *
Matthias Braun's avatar
Matthias Braun committed
717
 * @param *db         A pointer for debug information.
718
 * @param *mem        memory dependency
Matthias Braun's avatar
Matthias Braun committed
719
720
721
722
723
724
725
726
727
 * @param arity       The number of data inputs to the node.
 * @param *in         The array of length arity of data inputs.
 * @param *inputs     The array of length arity of input constraints.
 * @param n_outs      The number of data outputs to the node.
 * @param *outputs    The array of length n_outs of output constraints.
 * @param n_clobber   The number of clobbered registers.
 * @param *clobber    The array of length n_clobber of clobbered registers.
 * @param *asm_text   The assembler text.
 * @ingroup ASM
728
 */
729
730
FIRM_API ir_node *new_d_ASM(dbg_info *db, ir_node *mem, int arity,
                            ir_node *in[], ir_asm_constraint *inputs,
Matthias Braun's avatar
Matthias Braun committed
731
732
733
                            size_t n_outs, ir_asm_constraint *outputs,
                            size_t n_clobber, ident *clobber[],
                            ident *asm_text);
734

Michael Beck's avatar
Michael Beck committed
735
736
/** Constructor for an ASM pseudo node.
 *
737
 * @param *mem        memory dependency
Michael Beck's avatar
Michael Beck committed
738
 * @param arity       The number of data inputs to the node.
Michael Beck's avatar
Michael Beck committed
739
740
741
742
 * @param *in         The array of length arity of data inputs.
 * @param *inputs     The array of length arity of input constraints.
 * @param n_outs      The number of data outputs to the node.
 * @param *outputs    The array of length n_outs of output constraints.
Michael Beck's avatar
Michael Beck committed
743
744
 * @param n_clobber   The number of clobbered registers.
 * @param *clobber    The array of length n_clobber of clobbered registers.
Michael Beck's avatar
Michael Beck committed
745
 * @param *asm_text   The assembler text.
Matthias Braun's avatar
Matthias Braun committed
746
 * @ingroup ASM
Michael Beck's avatar
Michael Beck committed
747
 */
748
749
750
FIRM_API ir_node *new_ASM(ir_node *mem, int arity, ir_node *in[],
                          ir_asm_constraint *inputs, size_t n_outs,
                          ir_asm_constraint *outputs,
751
                          size_t n_clobber, ident *clobber[], ident *asm_text);
Michael Beck's avatar
Michael Beck committed
752

Matthias Braun's avatar
Matthias Braun committed
753
754
/** @} */

Matthias Braun's avatar
Matthias Braun committed
755
756
757
/**
 * @ingroup ir_graph
 * @defgroup ir_cons Construction Support
Matthias Braun's avatar
Matthias Braun committed
758
759
 * @{
 */
Götz Lindenmaier's avatar
Götz Lindenmaier committed
760

761
762
/**
 * Global variable holding the graph which is currently constructed.
763
764
765
 */
FIRM_API ir_graph *current_ir_graph;

766
767
768
/**
 * Returns graph which is currently constructed
 */
769
FIRM_API ir_graph *get_current_ir_graph(void);
770
771
772
773

/**
 * Sets graph which is currently constructed
 */
774
775
FIRM_API void set_current_ir_graph(ir_graph *graph);

Michael Beck's avatar
Michael Beck committed
776
/** Create an immature Block.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
777
 *
Michael Beck's avatar
Michael Beck committed
778
 * An immature Block has an unknown number of predecessors.  Predecessors
Götz Lindenmaier's avatar
Götz Lindenmaier committed
779
780
781
 * can be added with add_immBlock_pred().  Once all predecessors are
 * added the block must be matured.
 *
782
 * Adds the block to the graph in current_ir_graph.
783
 * This constructor can only be used if the graph is in state_building.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
784
 */
Michael Beck's avatar
Michael Beck committed
785
FIRM_API ir_node *new_d_immBlock(dbg_info *db);
786
787
788
789
790
791
792
793
794
/** Create an immature Block.
 *
 * An immature Block has an unknown number of predecessors.  Predecessors
 * can be added with add_immBlock_pred().  Once all predecessors are
 * added the block must be matured.
 *
 * Adds the block to the graph in current_ir_graph.
 * This constructor can only be used if the graph is in state_building.
 */
Michael Beck's avatar
Michael Beck committed
795
FIRM_API ir_node *new_immBlock(void);
796
797
798
799
800
801
802
803
/** Create an immature Block.
 *
 * An immature Block has an unknown number of predecessors.  Predecessors
 * can be added with add_immBlock_pred().  Once all predecessors are
 * added the block must be matured.
 *
 * This constructor can only be used if the graph is in state_building.
 */
804
FIRM_API ir_node *new_r_immBlock(ir_graph *irg);
805
806
807
808
809
810
811
812
/** Create an immature Block.
 *
 * An immature Block has an unknown number of predecessors.  Predecessors
 * can be added with add_immBlock_pred().  Once all predecessors are
 * added the block must be matured.
 *
 * This constructor can only be used if the graph is in state_building.
 */
813
FIRM_API ir_node *new_rd_immBlock(dbg_info *db, ir_graph *irg);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
814

Michael Beck's avatar
Michael Beck committed
815
/** Add a control flow edge to an immature block. */
Michael Beck's avatar
Michael Beck committed
816
FIRM_API void add_immBlock_pred(ir_node *immblock, ir_node *jmp);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
817

Michael Beck's avatar
Michael Beck committed
818
/** Finalize a Block node, when all control flows are known. */
Michael Beck's avatar
Michael Beck committed
819
FIRM_API void mature_immBlock(ir_node *block);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
820

821
822
823
/**
 * Sets the current block in which the following constructors place the
 * nodes they construct.
Matthias Braun's avatar
Matthias Braun committed
824
 *
825
 * @param target  The new current block.
Matthias Braun's avatar
Matthias Braun committed
826
827
 */
FIRM_API void set_cur_block(ir_node *target);
828
829
830
831
/**
 * Sets current block of a given graph.
 * @see set_cur_block()
 */
Matthias Braun's avatar
Matthias Braun committed
832
833
834
835
FIRM_API void set_r_cur_block(ir_graph *irg, ir_node *target);

/** Returns the current block of the current graph. */
FIRM_API ir_node *get_cur_block(void);
836
/** Returns current block of a given graph */
Matthias Braun's avatar
Matthias Braun committed
837
838
FIRM_API ir_node *get_r_cur_block(ir_graph *irg);

839
/** Returns the current value of a local variable.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
840
841
 *
 * Use this function to obtain the last definition of the local variable
842
 * associated with pos.  pos must be less than the value passed as n_loc
Götz Lindenmaier's avatar
Götz Lindenmaier committed
843
844
845
846
847
 * to new_ir_graph.  This call automatically inserts Phi nodes.
 *
 * @param  pos   The position/id of the local variable.
 * @param *mode  The mode of the value to get.
 */
Michael Beck's avatar
Michael Beck committed
848
FIRM_API ir_node *get_value(int pos, ir_mode *mode);
849
850
/** Returns the current value of a local variable in given graph
 * @see get_value() */
851
FIRM_API ir_node *get_r_value(ir_graph *irg, int pos, ir_mode *mode);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
852

853
854
855
856
857
858
859
860
861
/**
 * Try to guess the mode of a local variable.
 * This is done by recursively going up the control flow graph until
 * we find a definition for the variable. The mode of the first found
 * definition is returned. NULL in case no definition is found.
 *
 * @param  pos   The position/id of the local variable.
 */
FIRM_API ir_mode *ir_guess_mode(int pos);
862
863
864
/**
 * Try to guess the mode of a local variable in a given graph.
 */
865
FIRM_API ir_mode *ir_r_guess_mode(ir_graph *irg, int pos);
866

867
/** Memorize a new definition of a variable.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
868
869
 *
 * Use this function to remember a new definition of the value
870
 * associated with pos.  pos must be less than the value passed as n_loc
Götz Lindenmaier's avatar
Götz Lindenmaier committed
871
872
873
874
875
 * to new_ir_graph.  This call is needed to automatically inserts Phi
 * nodes.
 *
 * @param  pos   The position/id of the local variable.
 * @param *value The new value written to the local variable.
876
 */
Michael Beck's avatar
Michael Beck committed
877
FIRM_API void set_value(int pos, ir_node *value);
878
/** Sets current value of a variable in a given graph */
879
FIRM_API void set_r_value(ir_graph *irg, int pos, ir_node *value);
880

881
/** Returns the current memory state.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
882
883
884
885
886
 *
 * Use this function to obtain the last definition of the memory
 * state.  This call automatically inserts Phi nodes for the memory
 * state value.
 */
Michael Beck's avatar
Michael Beck committed
887
FIRM_API ir_node *get_store(void);
888
889
/** Returns current memory state for a given graph
 * @see get_store() */
890
FIRM_API ir_node *get_r_store(ir_graph *irg);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
891

892
/** Memorize a new definition of the memory state.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
893
894
895
896
897
 *
 * Use this function to remember a new definition of the memory state.
 * This call is needed to automatically inserts Phi nodes.
 *
 * @param *store The new memory state.
898
 */
Michael Beck's avatar
Michael Beck committed
899
FIRM_API void set_store(ir_node *store);
900
901
/** Sets current memory state for a given graph
 * @see set_store() */
902
FIRM_API void set_r_store(ir_graph *irg, ir_node *store);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
903

Götz Lindenmaier's avatar
Götz Lindenmaier committed
904
905
906
907
/** keep this node alive even if End is not control-reachable from it
 *
 * @param ka The node to keep alive.
 */
Michael Beck's avatar
Michael Beck committed
908
FIRM_API void keep_alive(ir_node *ka);
909

Michael Beck's avatar
Michael Beck committed
910
/** Puts the graph into state "phase_high" */
911
FIRM_API void irg_finalize_cons(ir_graph *irg);
912
913
914
915
916

/** Puts the program and all graphs into state phase_high.
 *
 * This also remarks, the construction of types is finished,
 * e.g., that no more subtypes will be added.  */
Michael Beck's avatar
Michael Beck committed
917
FIRM_API void irp_finalize_cons(void);
Christian Schäfer's avatar
Christian Schäfer committed
918

919
920
921
922
/**
 * Register a new callback for the case that the value of an uninitialized
 * variable is requested.
 */
923
924
925
FIRM_API void ir_set_uninitialized_local_variable_func(
		uninitialized_local_variable_func_t *func);

Matthias Braun's avatar
Matthias Braun committed
926
927
/** @} */

928
#include "end.h"
929

Matthias Braun's avatar
Matthias Braun committed
930
#endif