nsz Git - libfirm/blob - ir/tv/tv.h

   1 /*
   2  * Copyright (C) 1995-2007 University of Karlsruhe.  All right reserved.
   3  *
   4  * This file is part of libFirm.
   5  *
   6  * This file may be distributed and/or modified under the terms of the
   7  * GNU General Public License version 2 as published by the Free Software
   8  * Foundation and appearing in the file LICENSE.GPL included in the
   9  * packaging of this file.
  10  *
  11  * Licensees holding valid libFirm Professional Edition licenses may use
  12  * this file in accordance with the libFirm Commercial License.
  13  * Agreement provided with the Software.
  14  *
  15  * This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
  16  * WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  17  * PURPOSE.
  18  */
  19
  20 /*
  21  * Project:     libFIRM
  22  * File name:   ir/tv/tv.h
  23  * Purpose:     Representation of and static computations on target machine
  24  *              values.
  25  * Author:      Mathias Heil
  26  * Modified by:
  27  * Created:
  28  * CVS-ID:      $Id$
  29  * Copyright:   (c) 2003 Universität Karlsruhe
  30  */
  31
  32 /**
  33  * @file tv.h
  34  *
  35  * Declarations for Target Values.
  36  */
  37 #ifndef _TV_H_
  38 #define _TV_H_
  39
  40 #include "irmode.h"
  41 #include "irnode.h"
  42
  43 /****h* libfirm/tv
  44  *
  45  * NAME
  46  *    tv -- TargetValue, short tarval.
  47  *   Internal representation for machine values.
  48  *
  49  * AUTHORS
  50  *    Matthias Heil
  51  *
  52  * DESCRIPTION
  53  *    Tarvals represent target machine values.  They are typed by modes.
  54  *   Tarvals only represent values of mode_sort:
  55  *     int_number,
  56  *     float_number,
  57  *     boolean,
  58  *     reference,
  59  *     character
  60  *
  61  *   In case of references the module accepts an entity to represent the
  62  *   value.
  63  *    Furthermore, computations and conversions of these values can
  64  *   be performed.
  65  *
  66  * USES
  67  *    This module is closely related to the irmode module, as the modes
  68  *   defined there are thoroughly used throughout the whole module.
  69  *    Also, the comparison functions rely on the definition of comparison
  70  *   values in the irnode module.
  71  *
  72  * HISTORY
  73  *    The original tv module originated in the fiasco compiler written ...
  74  *    This is the new version, described in the tech report 1999-14 by ...
  75  *
  76  * SEE ALSO
  77  *    Techreport 1999-14
  78  *    irmode.h for the modes definitions
  79  *    irnode.h for the pn_Cmp table
  80  *
  81  *    tarval_init1 and tarval_init2 for initialization of the
  82  *   module
  83  *
  84  ******/
  85
  86 #ifndef _TARVAL_TYPEDEF_
  87 #define _TARVAL_TYPEDEF_
  88   typedef struct tarval tarval;
  89 #endif
  90
  91 /* ************************ Constructors for tarvals ************************ */
  92
  93 /**
  94  * Constructor function for new tarvals.
  95  *
  96  * @param str   The string representing the target value
  97  * @param len   The length of the string
  98  * @param mode  The mode requested for the result tarval
  99  *
 100  * This function creates a new tarval representing the value represented
 101  * by a CString, aka char array. If a tarval representing this value already
 102  * exists, this tarval is returned instead of a new one. So tarvals are
 103  * directly comparable since their representation is unique.
 104  *
 105  * This function accepts the following strings:
 106  *
 107  * if mode is int_number:
 108  *  - 0(x|X)[0-9a-fA-F]+ (hexadecimal representation)
 109  *  - 0[0-7]*            (octal representation)
 110  *  - (+|-)?[1-9][0-9]*  (decimal representation)
 111  *
 112  * if mode if float_number:
 113  *  - (+|-)?(decimal int) (. (decimal int))? ((e|E)(+|-)?(decimal int))?
 114  *
 115  * if mode is boolean: true, True, TRUE ... False... 0, 1,
 116  *
 117  * if mode is reference: hexadecimal of decimal number as int
 118  *
 119  * if mode is character: hex or dec
 120  *
 121  * Leading and/or trailing spaces are ignored
 122  *
 123  * @return
 124  *   A tarval of proper type representing the requested value is returned.
 125  *   Tarvals are unique, so for any value/mode pair at most one tarval will
 126  *   exist, which will be returned upon further requests with an identical
 127  *   value/mode pair.
 128  *
 129  * @note
 130  *   If the string is not representable in the given mode an assertion is
 131  *   thrown in assert build.
 132  *
 133  * @sa
 134  *   irmode.h for predefined modes
 135  *   new_tarval_from_long()
 136  *   new_tarval_from_double()
 137  */
 138 tarval *new_tarval_from_str(const char *str, size_t len, ir_mode *mode);
 139
 140 /**
 141  * Constructor function for new tarvals
 142  *
 143  * @param l     The long representing the value
 144  * @param mode  The mode requested for the result tarval
 145  *
 146  * This function creates a new tarval representing the value represented
 147  * by a long integer. If a tarval representing this value already exists,
 148  * this tarval is returned instead of a new one. So tarvals are directly
 149  * comparable since their representation is unique.
 150  *
 151  * @return
 152  *   A tarval of proper type representing the requested value is returned.
 153  *   Tarvals are unique, so for any value/mode pair at most one tarval will
 154  *   exist, which will be returned upon further requests with an identical
 155  *   value/mode pair.
 156  *
 157  * @note
 158  *   If the long is not representable in the given mode an assertion is
 159  *   thrown in assert build.
 160  *
 161  * @sa
 162  *   irmode.h for predefined modes
 163  *   new_tarval_from_str()
 164  *   new_tarval_from_double()
 165  *
 166  */
 167 tarval *new_tarval_from_long(long l, ir_mode *mode);
 168
 169 /** Return value as long if possible.
 170  *
 171  * This returns a long int with the value represented value, or
 172  * gibberish, depending on the size of long int and the size of the
 173  * stored value. It works for e.g. 1 as mode_Ls, but might not work for
 174  * get_mode_max(mode_Ls).
 175  * This will overflow silently, so use only if you know what
 176  * you are doing! (better check with tarval_is_long()...)
 177  * Works only for int modes, even not for character modes!
 178  */
 179 long get_tarval_long(tarval *tv);
 180
 181 /**
 182  * This validates if get_tarval_long() will return a satisfying
 183  * result. I.e. if tv is an int_number and between min, max
 184  * of long int (signed!)
 185  */
 186 int tarval_is_long(tarval *tv);
 187
 188 /**
 189  * Constructor function for new tarvals.
 190  *
 191  * @param d     The (long) double representing the value
 192  * @param mode  The mode requested for the result tarval
 193  *
 194  * This function creates a new tarval representing the value represented
 195  * by a (long) double. If a tarval representing this value already exists,
 196  * this tarval is returned instead of a new one. So tarvals are directly
 197  * comparable since their representation is unique.
 198  * Only modes of sort float_number can be constructed this way.
 199  *
 200  * @return
 201  *   A tarval of proper type representing the requested value is returned.
 202  *   Tarvals are unique, so for any value/mode pair at most one tarval will
 203  *   exist, which will be returned upon further requests with an identical
 204  *   value/mode pair.
 205  *
 206  * @note
 207  *   If the (long) double is not representable in the given mode an assertion
 208  *   is thrown. This will happen for any mode not of sort float_number.
 209  *
 210  * @sa
 211  *   irmode.h for predefined values
 212  *   new_tarval_from_str()
 213  *   new_tarval_from_long()
 214  */
 215 tarval *new_tarval_from_double(long double d, ir_mode *mode);
 216
 217 /**
 218  * This returns a double with the value represented value, or
 219  * gibberish, depending on the size of double and the size of the
 220  * stored value.
 221  * This will overflow silently, so use only if you know what
 222  * you are doing! (better check with tarval_is_long...)
 223  */
 224 long double get_tarval_double(tarval *tv);
 225
 226 /**
 227  * This validates if tarval_to_double() will return a satisfying
 228  * result. I.e. if tv is an float_number and between min, max
 229  * of double
 230  */
 231 int tarval_is_double(tarval *tv);
 232
 233
 234 /** ********** Access routines for tarval fields ********** **/
 235
 236 /*
 237  * NAME
 238  *   get_tarval_mode
 239  *   get_tarval_ ...
 240  *
 241  * SYNOPSIS
 242  *   ir_mode *get_tarval_mode(tarval *tv)
 243  *   ...
 244  *
 245  * DESCRIPTION
 246  *    These are access function for tarval struct members. It is encouraged
 247  *   to use them instead of direct access to the struct fields.
 248  *
 249  * PARAMETERS
 250  *   tv - The tarval to access fields of
 251  *
 252  * RESULT
 253  *   get_tv_mode: The mode of the tarval
 254  *
 255  * SEE ALSO
 256  *   the struct tarval
 257  */
 258
 259 /** Returns the mode of the tarval. */
 260 ir_mode *get_tarval_mode (const tarval *tv);
 261
 262 /** Returns the contents of the 'link' field of the tarval */
 263 /* void *get_tarval_link (tarval*); */
 264
 265 /* Testing properties of the represented values */
 266
 267 /**
 268  * Returns 1 if tv is negative
 269  *
 270  * @param a the tarval
 271  */
 272 int tarval_is_negative(tarval *a);
 273
 274 /**
 275  * Returns 1 if tv is null
 276  *
 277  * @param a the tarval
 278  */
 279 int tarval_is_null(tarval *a);
 280
 281 /**
 282  * Returns 1 if tv is the "one"
 283  *
 284  * @param a the tarval
 285  */
 286 int tarval_is_one(tarval *a);
 287
 288 /** The 'bad' tarval. */
 289 extern tarval *tarval_bad;
 290 /** Returns the 'bad tarval. */
 291 tarval *get_tarval_bad(void);
 292
 293 /** The 'undefined' tarval. */
 294 extern tarval *tarval_undefined;
 295 /** Returns the 'undefined' tarval. */
 296 tarval *get_tarval_undefined(void);
 297
 298 /** The mode_b tarval 'false'. */
 299 extern tarval *tarval_b_false;
 300
 301 /** Returns the mode_b tarval 'false'. */
 302 tarval *get_tarval_b_false(void);
 303
 304 /** The mode_b tarval 'true'. */
 305 extern tarval *tarval_b_true;
 306 /** Returns the mode_b tarval 'true'. */
 307 tarval *get_tarval_b_true(void);
 308
 309 /* These functions calculate and return a tarval representing the requested
 310  * value.
 311  * The functions get_mode_{Max,Min,...} return tarvals retrieved from these
 312  * functions, but these are stored on initialization of the irmode module and
 313  * therefore the irmode functions should be preferred to the functions below. */
 314
 315 /** Returns the maximum value of a given mode. */
 316 tarval *get_tarval_max(ir_mode *mode);
 317
 318 /** Returns the minimum value of a given mode. */
 319 tarval *get_tarval_min(ir_mode *mode);
 320
 321 /** Returns the 0 value (additive neutral) of a given mode.
 322     For reference modes, the NULL value is returned (old tarval_P_void) */
 323 tarval *get_tarval_null(ir_mode *mode);
 324
 325 /** Returns the 1 value (multiplicative neutral) of a given mode. */
 326 tarval *get_tarval_one(ir_mode *mode);
 327
 328 /** Returns the -1 value (multiplicative neutral) of a given mode.
 329  *  Returns tarval bad for unsigned modes */
 330 tarval *get_tarval_minus_one(ir_mode *mode);
 331
 332 /** Return quite nan for float_number modes. */
 333 tarval *get_tarval_nan(ir_mode *mode);
 334
 335 /** Return +inf for float_number modes. */
 336 tarval *get_tarval_plus_inf(ir_mode *mode);
 337
 338 /** Return -inf for float_number modes. */
 339 tarval *get_tarval_minus_inf(ir_mode *mode);
 340
 341 /* ******************** Arithmetic operations on tarvals ******************** */
 342
 343 typedef enum _tarval_int_overflow_mode_t {
 344   TV_OVERFLOW_BAD,      /**< tarval module will return tarval_bad if a overflow occurs */
 345   TV_OVERFLOW_WRAP,     /**< tarval module will overflow will be ignored, wrap around occurs */
 346   TV_OVERFLOW_SATURATE  /**< tarval module will saturate the overflow */
 347 } tarval_int_overflow_mode_t;
 348
 349 /**
 350  * Sets the overflow mode for integer operations.
 351  */
 352 void tarval_set_integer_overflow_mode(tarval_int_overflow_mode_t ov_mode);
 353
 354 /**
 355  * Get the overflow mode for integer operations.
 356  */
 357 tarval_int_overflow_mode_t tarval_get_integer_overflow_mode(void);
 358
 359 /**
 360  * Compares two tarvals
 361  *
 362  * Compare a with b and return a pn_Cmp describing the relation
 363  * between a and b.  This is either pn_Cmp_Uo, pn_Cmp_Lt, pn_Cmp_Eq, pn_Cmp_Gt,
 364  * or pn_Cmp_False if a or b are symbolic pointers which can not be compared at all.
 365  *
 366  * @param a   A tarval to be compared
 367  * @param b   A tarval to be compared
 368  *
 369  * @return
 370  *   The pn_Cmp best describing the relation between a and b is returned.
 371  *   This means the mode with the least bits set is returned, e.g. if the
 372  *   tarvals are equal the pn_Cmp 'pn_Cmp_Eq' is returned, not 'pn_Cmp_Ge' which
 373  *   indicates 'greater or equal'
 374  *
 375  * @sa
 376  *    irnode.h for the definition of pn_Cmp
 377  */
 378 pn_Cmp tarval_cmp(tarval *a, tarval *b);
 379
 380 /**
 381  * Converts a tarval to another mode.
 382  *
 383  * Convert tarval 'src' to mode 'mode', this will succeed if and only if mode
 384  * 'mode' is wider than the mode of src, as defined in the firm documentation
 385  * and as returned by the function mode_is_smaller defined in irmode.h.
 386  *
 387  * @param src    The tarval to convert
 388  * @param mode   Tho mode to convert to
 389  *
 390  * @return
 391  *   If a tarval of mode 'mode' with the result of the conversion of the 'src'
 392  *   tarvals value already exists, it will be returned, else a new tarval is
 393  *   constructed and returned
 394  *
 395  * @note
 396  *    Illegal conversations will trigger an assertion
 397  *
 398  * @sa
 399  *    FIRM documentation for conversion rules
 400  *    mode_is_smaller defined in irmode.h
 401  */
 402 tarval *tarval_convert_to(tarval *src, ir_mode *mode);
 403
 404 /*
 405  * These function implement basic computations representable as opcodes
 406  * in FIRM nodes.
 407  *
 408  * PARAMETERS
 409  *    tarval_neg:
 410  *    traval_abs:
 411  *      a - the tarval to operate on
 412  *
 413  *    all others:
 414  *      a - the first operand tarval
 415  *      b - the second operand tarval
 416  *
 417  * RESULT
 418  *    If necessary a new tarval is constructed for the resulting value,
 419  *   or the one already carrying the computation result is retrieved and
 420  *   returned as result.
 421  *
 422  * NOTES
 423  *   The order the arguments are given in is important, imagine postfix
 424  *   notation.
 425  *   Illegal operations will trigger an assertion.
 426  *   The sort member of the struct mode defines which operations are valid
 427  */
 428
 429 /** bitwise Negation of a tarval. */
 430 tarval *tarval_not(tarval *a);
 431
 432 /** arithmetic Negation of a tarval. */
 433 tarval *tarval_neg(tarval *a);
 434
 435 /** Addition of two tarvals. */
 436 tarval *tarval_add(tarval *a, tarval *b);
 437
 438 /** Subtraction from a tarval. */
 439 tarval *tarval_sub(tarval *a, tarval *b);
 440
 441 /** Multiplication of tarvals. */
 442 tarval *tarval_mul(tarval *a, tarval *b);
 443
 444 /** 'Exact' division. */
 445 tarval *tarval_quo(tarval *a, tarval *b);
 446
 447 /** Integer division. */
 448 tarval *tarval_div(tarval *a, tarval *b);
 449
 450 /** Remainder of integer division. */
 451 tarval *tarval_mod(tarval *a, tarval *b);
 452
 453 /** Absolute value. */
 454 tarval *tarval_abs(tarval *a);
 455
 456 /** Bitwise and. */
 457 tarval *tarval_and(tarval *a, tarval *b);
 458
 459 /** Bitwise or. */
 460 tarval *tarval_or(tarval *a, tarval *b);
 461
 462 /** Bitwise exclusive or. */
 463 tarval *tarval_eor(tarval *a, tarval *b);
 464
 465 /** Left shift. */
 466 tarval *tarval_shl(tarval *a, tarval *b);
 467
 468 /** Unsigned (logical) right shift. */
 469 tarval *tarval_shr(tarval *a, tarval *b);
 470
 471 /** Signed (arithmetic) right shift. */
 472 tarval *tarval_shrs(tarval *a, tarval *b);
 473
 474 /** Rotation. */
 475 tarval *tarval_rot(tarval *a, tarval *b);
 476
 477 /** Carry flag of the last operation */
 478 int tarval_carry(void);
 479
 480 /* *********** Output of tarvals *********** */
 481
 482 /**
 483  * The output mode for tarval values.
 484  *
 485  * Some modes allow more that one representation, for instance integers
 486  * can be represented hex or decimal. Of course it would be enough to have
 487  * one and let every backend convert it into the 'right' one.
 488  * However, we can do this in the tarval much simpler...
 489  */
 490 typedef enum {
 491   TVO_NATIVE,       /**< the default output mode, depends on the mode */
 492   TVO_HEX,          /**< use hex representation, always possible */
 493   TVO_DECIMAL,      /**< use decimal representation */
 494   TVO_OCTAL,        /**< use octal representation */
 495   TVO_BINARY,       /**< use binary representation */
 496   TVO_FLOAT,        /**< use floating point representation (i.e 1.342e-2)*/
 497   TVO_HEXFLOAT      /**< use hexadecimal floating point representation (i.e 0x1.ea32p-12)*/
 498 } tv_output_mode;
 499
 500 /**
 501  * This structure contains helper information to format the output
 502  * of a tarval of a mode.
 503  */
 504 typedef struct tarval_mode_info {
 505   tv_output_mode mode_output;  /**< if != TVO_NATIVE select a special mode */
 506   const char *mode_prefix;     /**< if set, this prefix will be printed
 507                                     before a value of this mode */
 508   const char *mode_suffix;     /**< if set, this suffix will be printed
 509                                     after a value of this mode */
 510 } tarval_mode_info;
 511
 512 /**
 513  * Specify the output options of one mode.
 514  *
 515  * This functions stores the mode info, so DO NOT DESTROY it.
 516  *
 517  * @param mode      a ir_mode that should be associated
 518  * @param modeinfo  the output format info
 519  *
 520  * @return zero on success.
 521  */
 522 int  set_tarval_mode_output_option(ir_mode *mode, const tarval_mode_info *modeinfo);
 523
 524 /**
 525  * Returns the output options of one mode.
 526  *
 527  * This functions returns the mode info of a given mode.
 528  *
 529  * @param mode      a ir_mode that should be associated
 530  *
 531  * @return the output option
 532  */
 533 const tarval_mode_info *get_tarval_mode_output_option(ir_mode *mode);
 534
 535 /**
 536  * Returns Bit representation of a tarval value, as string of '0' and '1'
 537  *
 538  * @param tv   The tarval
 539  *
 540  * This function returns a printable bit representation of any value
 541  * stored as tarval. This representation is a null terminated C string.
 542  *
 543  * @return
 544  *   As usual in C a pointer to a char is returned. The length of the
 545  *   returned string if fixed, just read as many chars as the mode defines
 546  *   as size.
 547  *
 548  * @note
 549  *   The string is allocated using malloc() and is free()ed on the next call
 550  *   of this function.
 551  *   The string consists of the ASCII characters '0' and '1' and is
 552  *   null terminated
 553  *
 554  * @sa
 555  *    irmode.h for the definition of the ir_mode struct
 556  *    the size member of aforementioned struct
 557  */
 558 char *get_tarval_bitpattern(tarval *tv);
 559
 560 /**
 561  * Returns the bitpattern of the bytes_ofs byte.
 562  *
 563  * This function succeeds even if the mode of the tarval uses lesser bits
 564  * than requested, in that case the bitpattern is filled with zero bits.
 565  *
 566  * To query a 32bit value the following code can be used:
 567  *
 568  * val0 = tarval_sub_bits(tv, 0);
 569  * val1 = tarval_sub_bits(tv, 1);
 570  * val2 = tarval_sub_bits(tv, 2);
 571  * val3 = tarval_sub_bits(tv, 3);
 572  *
 573  * Because this is the bit representation of the target machine, only the following
 574  * operations are legal on the result:
 575  *
 576  * - concatenation (endian dependence MUST be handled by the CALLER)
 577  * - bitwise logical operations to select/mask bits
 578  *
 579  * @param tv        the tarval
 580  * @param byte_ofs  the byte offset
 581  *
 582  * @note
 583  *   The result of this function is undefined if the mode is neither integer nor float.
 584  */
 585 unsigned char get_tarval_sub_bits(tarval *tv, unsigned byte_ofs);
 586
 587 /**
 588  * Return values of tarval classify
 589  */
 590 typedef enum _tarval_classification_t {
 591   TV_CLASSIFY_NULL    =  0, /**< the tarval represents the additive neutral element */
 592   TV_CLASSIFY_ONE     = +1, /**< the tarval represents the multiplicative neutral element */
 593   TV_CLASSIFY_ALL_ONE = -1, /**< the tarval represents the bitwise-and neutral element */
 594   TV_CLASSIFY_OTHER   =  2  /**< all other tarvals */
 595 } tarval_classification_t;
 596
 597 /**
 598  * Identifying tarvals values for algebraic simplifications.
 599  *
 600  * @param tv        the tarval
 601  *
 602  * @return
 603  *   - TV_CLASSIFY_NULL    for additive neutral or the NULL tarval for reference modes,
 604  *   - TV_CLASSIFY_ONE     for multiplicative neutral,
 605  *   - TV_CLASSIFY_ALL_ONE for bitwise-and neutral
 606  *   - TV_CLASSIFY_OTHER   else
 607  */
 608 tarval_classification_t classify_tarval(tarval *tv);
 609
 610 /**
 611  * Returns non-zero if a given (integer) tarval has only one single bit
 612  * set.
 613  */
 614 int is_single_bit_tarval(tarval *tv);
 615
 616 /**
 617  * Output of tarvals to a buffer.
 618  */
 619 int tarval_snprintf(char *buf, size_t buflen, tarval *tv);
 620
 621 /**
 622  * Output of tarvals to stdio.
 623  */
 624 int tarval_printf(tarval *tv);
 625
 626 #endif  /* _TV_H_ */