Fixed documentation od tarval_classify and add new enum to make things more clear

[libfirm] / ir / tv / tv.h

diff --git a/ir/tv/tv.h b/ir/tv/tv.h
index a8c2531..9778967 100644 (file)
--- a/ir/tv/tv.h
+++ b/ir/tv/tv.h
@@ -1,46 +1,22 @@
+/*
+ * Project:     libFIRM
+ * File name:   ir/tv/tv.h
+ * Purpose:     Representation of and static computations on target machine
+ *              values.
+ * Author:      Mathias Heil
+ * Modified by:
+ * Created:
+ * CVS-ID:      $Id$
+ * Copyright:   (c) 2003 Universität Karlsruhe
+ * Licence:     This file protected by GPL -  GNU GENERAL PUBLIC LICENSE.
+ */
+
 /**
  * @file tv.h
  *
  * Declarations for Target Values.
  */
 
-/* $Id$ */
-
-/*
-Discussion of new interface, proposals by Prof. Waite:
-(email of 13.6.2001)
-> 1. You say that you plan to replace the tv module.  That replacement is
->    absolutely essential for an ANSI C translator:  Section 6.1.3.2 of the
->    standard says that the representation of an integer_constant depends
->    upon its value as well as any suffixes that are attached to it.  The
->    possible Firm modes for such a constant are i, I, l, and L.  The
->    current tv module provides only one integer conversion routine, and
->    that requires conversion by the client.  Since the type of the value
->    argument is long, this may preclude the representation of an unsigned
->    long constant.
->
->    There is a similar problem with floating constants.  Floating
->    constants can be suffixed in C, and the mode depends upon the suffix.
->    It can indicate that the constant is of type long double, which your
->    current tv module is incapable of representing.
->
->    Your tv module interface accepts two kinds of information: modes and
->    values.  Values obtained from the program text might be uninterpreted
->    strings, strings interpreted as integers, and strings interpreted as
->    reals.  Values provided by the compiler are usually integers.  Modes are
->    always Firm modes.  It seems to me that the tv module should provide
->    tarval* constructors for three of the four kinds of values.  Each of these
->    constructors should have an ir_mode parameter and one or more parameters
->    appropriate for the kind of value.  As is currently the case, one
->    constructor should be provided for both compiler-generated integers and
->    source strings interpreted as integers.  (This avoids problems of
->    different conversion radices -- the client does the conversion.)  For
->    symmetry, the constructor for source strings interpreted as reals should
->    accept a long double parameter and require the client to do the
->    conversion.
-
-*/
-
 #ifndef _TV_H_
 #define _TV_H_
 
@@ -56,7 +32,6 @@ Discussion of new interface, proposals by Prof. Waite:
  *   Internal representation for machine values.
  *
  * AUTHORS
- *    Christian von Roques
  *    Matthias Heil
  *
  * DESCRIPTION
@@ -246,8 +221,10 @@ int tarval_is_double(tarval *tv);
 tarval *new_tarval_from_entity (entity *ent, ir_mode *mode);
 
 /**
- * Returns the associated entity of a tarval.
+ * Returns the associated entity of a tarval.  Asserts if tarval does not
+ * contain an entity.
  */
+#define get_tarval_entity tarval_to_entity
 entity *tarval_to_entity(tarval *tv);
 
 /**
@@ -299,6 +276,13 @@ int tarval_is_negative(tarval *a);
  */
 int tarval_is_null(tarval *a);
 
+/**
+ * Returns 1 if tv is the "one"
+ *
+ * @param a    the tarval
+ */
+int tarval_is_one(tarval *a);
+
 /** The 'bad' tarval. */
 extern tarval *tarval_bad;
 /** Returns the 'bad tarval. */
@@ -420,7 +404,10 @@ tarval *tarval_convert_to(tarval *src, ir_mode *m);
  *   The sort member of the struct mode defines which operations are valid
  */
 
-/** Negation of a tarval. */
+/** bitwise Negation of a tarval. */
+tarval *tarval_not(tarval *a);
+
+/** arithmetic Negation of a tarval. */
 tarval *tarval_neg(tarval *a);
 
 /** Addition of two tarvals. */
@@ -487,7 +474,7 @@ typedef enum {
 
 /**
  * This structure contains helper information to format the output
- * of a tarval of an mode.
+ * of a tarval of a mode.
  */
 typedef struct tarval_mode_info {
     tv_output_mode mode_output;                /**< if != TVO_NATIVE select a special mode */
@@ -573,19 +560,25 @@ char *tarval_bitpattern(tarval *tv);
 unsigned char tarval_sub_bits(tarval *tv, unsigned byte_ofs);
 
 /**
- * Identifying some tarvals ???
- *
+ * Return values of tarval classify
+ */
+typedef enum _tarval_classification_t {
+  TV_CLASSIFY_NULL    =  0,    /**< the tarval represents the additive neutral element */
+  TV_CLASSIFY_ONE     = +1,    /**< the tarval represents the multiplicative neutral element */
+  TV_CLASSIFY_ALL_ONE = -1,    /**< the tarval represents the bitwise-and neutral element */
+  TV_CLASSIFY_OTHER   =  2,    /*<< all other tarvals */
+} tarval_classification_t;
+
+/**
+ * Identifying tarvals values for algebraic simplifications.
+ * @param tv
  * @return
- *   - 0 for additive neutral,
- *   - +1 for multiplicative neutral,
- *   - -1 for bitwise-and neutral
- *   - 2 else
- *
- * @deprecated
- *   This function is deprecated and its use strongly discouraged.
- *   Implemented for completeness.
+ *   - TV_CLASSIFY_NULL    for additive neutral,
+ *   - TV_CLASSIFY_ONE     for multiplicative neutral,
+ *   - TV_CLASSIFY_ALL_ONE for bitwise-and neutral
+ *   - TV_CLASSIFY_OTHER   else
  */
-long tarval_classify(tarval *tv);
+tarval_classification_t tarval_classify(tarval *tv);
 
 /**
  * Initialization of the tarval module.