output documentation to file on request
[libfirm] / scripts / ir_spec.py
index 9296d84..489cd40 100755 (executable)
@@ -38,10 +38,10 @@ class Alloc(Op):
                ("count", "number of objects to allocate" ),
        ]
        outs  = [
-               ("M",         "memory result",                         "pn_Generic_M"),
-               ("X_regular", "control flow when no exception occurs", "pn_Generic_X_regular"),
-               ("X_except",  "control flow when exception occured",   "pn_Generic_X_except"),
-               ("res",       "pointer to newly allocated memory",     "pn_Generic_other"),
+               ("M",         "memory result"),
+               ("res",       "pointer to newly allocated memory"),
+               ("X_regular", "control flow when no exception occurs"),
+               ("X_except",  "control flow when exception occured"),
        ]
        attrs = [
                dict(
@@ -56,7 +56,9 @@ class Alloc(Op):
                )
        ]
        flags       = [ "fragile", "uses_memory" ]
-       pinned      = "yes"
+       pinned      = "exception"
+       throws_init = "false"
+       pinned_init = "op_pin_state_pinned"
        attr_struct = "alloc_attr"
 
 class Anchor(Op):
@@ -98,7 +100,7 @@ class ASM(Op):
                ),
                dict(
                        name    = "n_output_constraints",
-                       type    = "int",
+                       type    = "size_t",
                        noprop  = True,
                        comment = "number of output constraints",
                ),
@@ -109,7 +111,7 @@ class ASM(Op):
                ),
                dict(
                        name    = "n_clobbers",
-                       type    = "int",
+                       type    = "size_t",
                        noprop  = True,
                        comment = "number of clobbered registers/memory",
                ),
@@ -146,12 +148,10 @@ class Bad(Op):
        they are set to Bad, and the actual removal is left to the control flow
        optimisation phase. Block, Phi, Tuple with only Bad inputs however are
        replaced by Bad right away."""
-       mode          = "mode_T"
-       flags         = [ "cfopcode", "start_block", "dump_noblock" ]
+       flags         = [ "start_block", "dump_noblock" ]
        pinned        = "yes"
        knownBlock    = True
        block         = "get_irg_start_block(irg)"
-       singleton     = True
        attr_struct   = "bad_attr"
        init = '''
        res->attr.bad.irg.irg = irg;
@@ -164,7 +164,7 @@ class Deleted(Op):
        flags            = [ ]
        pinned           = "yes"
        noconstructor    = True
-       customSerializer = True
+       customSerializer = True # this has no serializer
 
 class Block(Op):
        """A basic block"""
@@ -175,6 +175,14 @@ class Block(Op):
        arity            = "variable"
        flags            = [ "labeled" ]
        attr_struct      = "block_attr"
+       attrs            = [
+               dict(
+                       name    = "entity",
+                       type    = "ir_entity*",
+                       comment = "entity representing this block",
+                       init    = "NULL",
+               ),
+       ]
        customSerializer = True
 
        init = '''
@@ -203,16 +211,16 @@ class Bound(Op):
                ("upper",  "upper bound (exclusive)"),
        ]
        outs  = [
-               ("M",         "memory result",                         "pn_Generic_M"),
-               ("X_regular", "control flow when no exception occurs", "pn_Generic_X_regular"),
-               ("X_except",  "control flow when exception occured",   "pn_Generic_X_except"),
-               ("res",       "the checked index",                     "pn_Generic_other"),
+               ("M",         "memory result"),
+               ("res",       "the checked index"),
+               ("X_regular", "control flow when no exception occurs"),
+               ("X_except",  "control flow when exception occured"),
        ]
        flags  = [ "fragile", "highlevel" ]
        pinned = "exception"
        pinned_init = "op_pin_state_pinned"
+       throws_init = "false"
        attr_struct = "bound_attr"
-       attrs_name  = "bound"
 
 class Builtin(Op):
        """performs a backend-specific builtin."""
@@ -221,8 +229,8 @@ class Builtin(Op):
        ]
        arity    = "variable"
        outs     = [
-               ("M",        "memory result", "pn_Generic_M"),
-               ("1_result", "first result",  "pn_Generic_other"),
+               ("M", "memory result"),
+               # results follow here
        ]
        flags    = [ "uses_memory" ]
        attrs    = [
@@ -255,11 +263,10 @@ class Call(Op):
        ]
        arity    = "variable"
        outs     = [
-               ("M",                "memory result",                         "pn_Generic_M"),
-               ("X_regular",        "control flow when no exception occurs", "pn_Generic_X_regular"),
-               ("X_except",         "control flow when exception occured",   "pn_Generic_X_except"),
-               ("T_result",         "tuple containing all results",          "pn_Generic_other"),
-               ("P_value_res_base", "pointer to memory register containing copied results passed by value"),
+               ("M",                "memory result"),
+               ("T_result",         "tuple containing all results"),
+               ("X_regular",        "control flow when no exception occurs"),
+               ("X_except",         "control flow when exception occured"),
        ]
        flags    = [ "fragile", "uses_memory" ]
        attrs    = [
@@ -268,16 +275,11 @@ class Call(Op):
                        name    = "type",
                        comment = "type of the call (usually type of the called procedure)",
                ),
-               dict(
-                       type = "unsigned",
-                       name = "tail_call",
-                       # the tail call attribute can only be set by analysis
-                       init = "0",
-               )
        ]
        attr_struct = "call_attr"
        pinned      = "memory"
        pinned_init = "op_pin_state_pinned"
+       throws_init = "false"
        init = '''
        assert((get_unknown_type() == type) || is_Method_type(type));
        '''
@@ -302,41 +304,21 @@ class Cast(Unop):
        init     = "assert(is_atomic_type(type));"
 
 class Cmp(Binop):
-       """Returns the relation of 2 operands"""
-       outs  = [
-               ("False", "always false",                            "0"),
-               ("Eq",    "equal",                                   "1"),
-               ("Lt",    "less",                                    "2"),
-               ("Le",    "less or equal",                           "pn_Cmp_Eq|pn_Cmp_Lt"),
-               ("Gt",    "greater",                                 "4"),
-               ("Ge",    "greater or equal",                        "pn_Cmp_Eq|pn_Cmp_Gt"),
-               ("Lg",    "less or greater ('not equal' for integer numbers)", "pn_Cmp_Lt|pn_Cmp_Gt"),
-               ("Leg",   "less, equal or greater ('not unordered')", "pn_Cmp_Lt|pn_Cmp_Eq|pn_Cmp_Gt"),
-               ("Uo",    "unordered",                               "8"),
-               ("Ue",    "unordered or equal",                      "pn_Cmp_Uo|pn_Cmp_Eq"),
-               ("Ul",    "unordered or less",                       "pn_Cmp_Uo|pn_Cmp_Lt"),
-               ("Ule",   "unordered, less or equal",                "pn_Cmp_Uo|pn_Cmp_Lt|pn_Cmp_Eq"),
-               ("Ug",    "unordered or greater",                    "pn_Cmp_Uo|pn_Cmp_Gt"),
-               ("Uge",   "onordered, greater or equal",             "pn_Cmp_Uo|pn_Cmp_Gt|pn_Cmp_Eq"),
-               ("Ne",    "unordered, less or greater ('not equal' for floatingpoint numbers)", "pn_Cmp_Uo|pn_Cmp_Lt|pn_Cmp_Gt"),
-               ("True",  "always true",                             "15"),
-       ]
+       """Compares its two operands and checks whether a specified
+          relation (like less or equal) is fulfilled."""
        flags = []
+       mode  = "mode_b"
+       attrs = [
+               dict(
+                       type    = "ir_relation",
+                       name    = "relation",
+                       comment = "Comparison relation"
+               )
+       ]
+       attr_struct = "cmp_attr"
 
 class Cond(Op):
-       """Conditionally change control flow. There are two versions of this node:
-
-       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.
-
-       Switch Cond:
-       Input:  A value of mode_Iu
-       Output: A tuple of n control flows. If the Cond's input is i, control flow
-       will proceed along output i. If the input is >= n control flow proceeds
-       along output def_proj.
-       """
+       """Conditionally change control flow."""
        ins      = [
                ("selector",  "condition parameter"),
        ]
@@ -347,21 +329,42 @@ class Cond(Op):
        flags    = [ "cfopcode", "forking" ]
        pinned   = "yes"
        attrs    = [
-               dict(
-                       name    = "default_proj",
-                       type    = "long",
-                       init    = "0",
-                       comment = "Proj-number of default case for switch-Cond",
-               ),
                dict(
                        name    = "jmp_pred",
                        type    = "cond_jmp_predicate",
                        init    = "COND_JMP_PRED_NONE",
                        comment = "can indicate the most likely jump",
-               )
+               ),
        ]
        attr_struct = "cond_attr"
 
+class Switch(Op):
+       """Change control flow. The destination is choosen based on an integer input value which is looked up in a table.
+
+       Backends can implement this efficiently using a jump table."""
+       ins    = [
+               ("selector", "input selector"),
+       ]
+       outs   = [
+               ("default", "control flow if no other case matches"),
+       ]
+       flags  = [ "cfopcode", "forking" ]
+       pinned = "yes"
+       attrs  = [
+               dict(
+                       name    = "n_outs",
+                       type    = "unsigned",
+                       comment = "number of outputs (including pn_Switch_default)",
+               ),
+               dict(
+                       name    = "table",
+                       type    = "ir_switch_table*",
+                       comment = "table describing mapping from input values to Proj numbers",
+               ),
+       ]
+       attr_struct = "switch_attr"
+       attrs_name  = "switcha"
+
 class Confirm(Op):
        """Specifies constraints for a value. This allows explicit representation
        of path-sensitive properties. (Example: This value is always >= 0 on 1
@@ -381,13 +384,12 @@ class Confirm(Op):
        pinned   = "yes"
        attrs    = [
                dict(
-                       name    = "cmp",
-                       type    = "pn_Cmp",
-                       comment = "compare operation",
+                       name    = "relation",
+                       type    = "ir_relation",
+                       comment = "relation of value to bound",
                ),
        ]
        attr_struct = "confirm_attr"
-       attrs_name  = "confirm"
 
 class Const(Op):
        """Returns a constant value."""
@@ -418,7 +420,6 @@ class Conv(Unop):
                )
        ]
        attr_struct = "conv_attr"
-       attrs_name  = "conv"
 
 class CopyB(Op):
        """Copies a block of memory"""
@@ -428,9 +429,9 @@ class CopyB(Op):
                ("src",  "source address"),
        ]
        outs  = [
-               ("M",         "memory result",                         "pn_Generic_M"),
-               ("X_regular", "control flow when no exception occurs", "pn_Generic_X_regular"),
-               ("X_except",  "control flow when exception occured",   "pn_Generic_X_except"),
+               ("M",         "memory result"),
+               ("X_regular", "control flow when no exception occurs"),
+               ("X_except",  "control flow when exception occured"),
        ]
        flags = [ "fragile", "uses_memory" ]
        attrs = [
@@ -441,9 +442,9 @@ class CopyB(Op):
                )
        ]
        attr_struct = "copyb_attr"
-       attrs_name  = "copyb"
        pinned      = "memory"
        pinned_init = "op_pin_state_pinned"
+       throws_init = "false"
 
 class Div(Op):
        """returns the quotient of its 2 operands"""
@@ -453,13 +454,12 @@ class Div(Op):
                ("right", "second operand"),
        ]
        outs  = [
-               ("M",         "memory result",                         "pn_Generic_M"),
-               ("X_regular", "control flow when no exception occurs", "pn_Generic_X_regular"),
-               ("X_except",  "control flow when exception occured",   "pn_Generic_X_except"),
-               ("res",       "result of computation",                 "pn_Generic_other"),
+               ("M",         "memory result"),
+               ("res",       "result of computation"),
+               ("X_regular", "control flow when no exception occurs"),
+               ("X_except",  "control flow when exception occured"),
        ]
        flags = [ "fragile", "uses_memory" ]
-       attrs_name = "divmod"
        attrs = [
                dict(
                        type    = "ir_mode*",
@@ -472,8 +472,9 @@ class Div(Op):
                        init = "0",
                )
        ]
-       attr_struct = "divmod_attr"
+       attr_struct = "div_attr"
        pinned      = "exception"
+       throws_init = "false"
        op_index    = 1
        arity_override = "oparity_binary"
 
@@ -497,7 +498,6 @@ class End(Op):
        knownBlock       = True
        block            = "get_irg_end_block(irg)"
        singleton        = True
-       customSerializer = True
 
 class Eor(Binop):
        """returns the result of a bitwise exclusive or operation of its operands"""
@@ -508,7 +508,7 @@ class Free(Op):
        ins    = [
                ("mem",   "memory dependency" ),
                ("ptr",   "pointer to the object to free"),
-               ("size",  "number of objects to allocate" ),
+               ("count", "number of objects to allocate" ),
        ]
        mode   = "mode_M"
        flags  = [ "uses_memory" ]
@@ -544,19 +544,19 @@ class IJmp(Op):
        ins      = [
           ("target", "target address of the jump"),
        ]
-       flags    = [ "cfopcode", "forking", "keep" ]
+       flags    = [ "cfopcode", "forking", "keep", "unknown_jump" ]
 
 class InstOf(Op):
-       """Tests wether an object is an instance of a class-type"""
+       """Tests whether an object is an instance of a class-type"""
        ins   = [
           ("store", "memory dependency"),
           ("obj",   "pointer to object being queried")
        ]
        outs  = [
-               ("M",         "memory result",                         "pn_Generic_M"),
-               ("X_regular", "control flow when no exception occurs", "pn_Generic_X_regular"),
-               ("X_except",  "control flow when exception occured",   "pn_Generic_X_except"),
-               ("res",       "checked object pointer",                "pn_Generic_other"),
+               ("M",         "memory result"),
+               ("res",       "checked object pointer"),
+               ("X_regular", "control flow when no exception occurs"),
+               ("X_except",  "control flow when exception occured"),
        ]
        flags = [ "highlevel" ]
        attrs = [
@@ -584,10 +584,10 @@ class Load(Op):
                ("ptr",  "address to load from"),
        ]
        outs  = [
-               ("M",         "memory result",                         "pn_Generic_M"),
-               ("X_regular", "control flow when no exception occurs", "pn_Generic_X_regular"),
-               ("X_except",  "control flow when exception occured",   "pn_Generic_X_except"),
-               ("res",       "result of load operation",              "pn_Generic_other"),
+               ("M",         "memory result"),
+               ("res",       "result of load operation"),
+               ("X_regular", "control flow when no exception occurs"),
+               ("X_except",  "control flow when exception occured"),
        ]
        flags    = [ "fragile", "uses_memory" ]
        pinned   = "exception"
@@ -595,9 +595,22 @@ class Load(Op):
                dict(
                        type      = "ir_mode*",
                        name      = "mode",
-                       java_name = "load_mode",
                        comment   = "mode of the value to be loaded",
                ),
+               dict(
+                       type      = "ir_volatility",
+                       name      = "volatility",
+                       comment   = "volatile loads are a visible side-effect and may not be optimized",
+                       init      = "flags & cons_volatile ? volatility_is_volatile : volatility_non_volatile",
+                       to_flags  = "%s == volatility_is_volatile ? cons_volatile : 0"
+               ),
+               dict(
+                       type      = "ir_align",
+                       name      = "unaligned",
+                       comment   = "pointers to unaligned loads don't need to respect the load-mode/type alignments",
+                       init      = "flags & cons_unaligned ? align_non_aligned : align_is_aligned",
+                       to_flags  = "%s == align_non_aligned ? cons_unaligned : 0"
+               ),
        ]
        attr_struct = "load_attr"
        constructor_args = [
@@ -608,10 +621,7 @@ class Load(Op):
                ),
        ]
        pinned_init = "flags & cons_floats ? op_pin_state_floats : op_pin_state_pinned"
-       init = '''
-       res->attr.load.volatility = flags & cons_volatile ? volatility_is_volatile : volatility_non_volatile;
-       res->attr.load.aligned = flags & cons_unaligned ? align_non_aligned : align_is_aligned;
-       '''
+       throws_init = "(flags & cons_throws_exception) != 0"
 
 class Minus(Unop):
        """returns the difference between its operands"""
@@ -621,6 +631,7 @@ class Mod(Op):
        """returns the remainder of its operands from an implied division.
 
        Examples:
+
        * mod(5,3)   produces 2
        * mod(5,-3)  produces 2
        * mod(-5,3)  produces -2
@@ -632,13 +643,12 @@ class Mod(Op):
                ("right", "second operand"),
        ]
        outs  = [
-               ("M",         "memory result",                         "pn_Generic_M"),
-               ("X_regular", "control flow when no exception occurs", "pn_Generic_X_regular"),
-               ("X_except",  "control flow when exception occured",   "pn_Generic_X_except"),
-               ("res",       "result of computation",                 "pn_Generic_other"),
+               ("M",         "memory result"),
+               ("res",       "result of computation"),
+               ("X_regular", "control flow when no exception occurs"),
+               ("X_except",  "control flow when exception occured"),
        ]
        flags = [ "fragile", "uses_memory" ]
-       attrs_name = "divmod"
        attrs = [
                dict(
                        type    = "ir_mode*",
@@ -646,8 +656,9 @@ class Mod(Op):
                        comment = "mode of the result",
                ),
        ]
-       attr_struct = "divmod_attr"
+       attr_struct = "mod_attr"
        pinned      = "exception"
+       throws_init = "false"
        op_index    = 1
        arity_override = "oparity_binary"
 
@@ -705,6 +716,7 @@ class Phi(Op):
           As we can't distinguish these easily we keep all of them alive. */
        if (is_Phi(res) && mode == mode_M)
                add_End_keepalive(get_irg_end(irg), res);'''
+       customSerializer = True
 
 class Pin(Op):
        """Pin the value of the node node in the current block. No users of the Pin
@@ -728,7 +740,6 @@ class Proj(Op):
        knownGraph       = True
        block            = "get_nodes_block(irn_pred)"
        graph            = "get_irn_irg(irn_pred)"
-       customSerializer = True
        attrs      = [
                dict(
                        type    = "long",
@@ -747,8 +758,8 @@ class Raise(Op):
                ("exo_ptr", "pointer to exception object to be thrown"),
        ]
        outs  = [
-               ("M", "memory result",                     "pn_Generic_M"),
-               ("X", "control flow to exception handler", "pn_Generic_X_regular"),
+               ("M", "memory result"),
+               ("X", "control flow to exception handler"),
        ]
        flags  = [ "highlevel", "cfopcode" ]
        pinned = "yes"
@@ -771,7 +782,10 @@ class Rotl(Binop):
 
 class Sel(Op):
        """Computes the address of a entity of a compound type given the base
-       address of an instance of the compound type."""
+       address of an instance of the compound type.
+
+       Optimisations assume that a Sel node can only produce a NULL pointer if the
+       ptr input was NULL."""
        ins    = [
                ("mem", "memory dependency"),
                ("ptr", "pointer to object to select from"),
@@ -811,7 +825,6 @@ class Start(Op):
                ("X_initial_exec", "control flow"),
                ("M",              "initial memory"),
                ("P_frame_base",   "frame base pointer"),
-               ("P_tls",          "pointer to thread local storage segment"),
                ("T_args",         "function arguments")
        ]
        mode             = "mode_T"
@@ -819,7 +832,6 @@ class Start(Op):
        flags            = [ "cfopcode" ]
        singleton        = True
        knownBlock       = True
-       customSerializer = True
        block            = "get_irg_start_block(irg)"
 
 class Store(Op):
@@ -830,14 +842,31 @@ class Store(Op):
           ("value", "value to store"),
        ]
        outs  = [
-               ("M",         "memory result",                         "pn_Generic_M"),
-               ("X_regular", "control flow when no exception occurs", "pn_Generic_X_regular"),
-               ("X_except",  "control flow when exception occured",   "pn_Generic_X_except"),
+               ("M",         "memory result"),
+               ("X_regular", "control flow when no exception occurs"),
+               ("X_except",  "control flow when exception occured"),
        ]
        flags    = [ "fragile", "uses_memory" ]
        pinned   = "exception"
        attr_struct = "store_attr"
        pinned_init = "flags & cons_floats ? op_pin_state_floats : op_pin_state_pinned"
+       throws_init = "(flags & cons_throws_exception) != 0"
+       attrs = [
+               dict(
+                       type      = "ir_volatility",
+                       name      = "volatility",
+                       comment   = "volatile stores are a visible side-effect and may not be optimized",
+                       init      = "flags & cons_volatile ? volatility_is_volatile : volatility_non_volatile",
+                       to_flags  = "%s == volatility_is_volatile ? cons_volatile : 0"
+               ),
+               dict(
+                       type      = "ir_align",
+                       name      = "unaligned",
+                       comment   = "pointers to unaligned stores don't need to respect the load-mode/type alignments",
+                       init      = "flags & cons_unaligned ? align_non_aligned : align_is_aligned",
+                       to_flags  = "%s == align_non_aligned ? cons_unaligned : 0"
+               ),
+       ]
        constructor_args = [
                dict(
                        type    = "ir_cons_flags",
@@ -845,10 +874,6 @@ class Store(Op):
                        comment = "specifies alignment, volatility and pin state",
                ),
        ]
-       init = '''
-       res->attr.store.volatility = flags & cons_volatile ? volatility_is_volatile : volatility_non_volatile;
-       res->attr.store.aligned = flags & cons_unaligned ? align_non_aligned : align_is_aligned;
-       '''
 
 class Sub(Binop):
        """returns the difference of its operands"""
@@ -857,21 +882,19 @@ class Sub(Binop):
 class SymConst(Op):
        """A symbolic constant.
 
-        - 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."""
+        - *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."""
        mode       = "mode_P"
        flags      = [ "constlike", "start_block" ]
        knownBlock = True
@@ -909,7 +932,7 @@ class Tuple(Op):
        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 node, so that a node can be changed into a Tuple by
-       just changing it's opcode and giving it a new in array."""
+       just changing its opcode and giving it a new in array."""
        arity  = "variable"
        mode   = "mode_T"
        pinned = "no"
@@ -921,7 +944,7 @@ class Unknown(Op):
        knownBlock = True
        pinned     = "yes"
        block      = "get_irg_start_block(irg)"
-       flags      = [ "cfopcode", "start_block", "constlike", "dump_noblock" ]
+       flags      = [ "start_block", "constlike", "dump_noblock" ]
 
 # Prepare node list