tv.h 21 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
 */

Michael Beck's avatar
Michael Beck committed
6
/**
Michael Beck's avatar
Michael Beck committed
7
8
9
10
11
 * @file
 * @brief    Representation of and static computations on target machine
 *           values.
 * @date     2003
 * @author   Mathias Heil
Matthias Braun's avatar
Matthias Braun committed
12
13
14
15
16
17
18
19
20
21
22
23
24
 * @brief    target machine values.
 */
#ifndef FIRM_TV_TV_H
#define FIRM_TV_TV_H

#include <stddef.h>
#include "firm_types.h"

#include "begin.h"

/** @defgroup ir_tarval  Target Machine Values
 *
 * Tarvals only represent values of mode_sort:
Michael Beck's avatar
Michael Beck committed
25
26
27
28
29
 *    - int_number,
 *    - float_number,
 *    - boolean,
 *    - reference,
 *    - character
30
31
 *
 *   In case of references the module accepts an entity to represent the
Matthias Braun's avatar
Matthias Braun committed
32
 *   value. Furthermore, computations and conversions of these values can
33
34
 *   be performed.
 *
Michael Beck's avatar
Michael Beck committed
35
 * @sa
36
37
 *    Techreport 1999-14
 *    irmode.h for the modes definitions
Matthias Braun's avatar
Matthias Braun committed
38
39
 *
 * @{
Michael Beck's avatar
Michael Beck committed
40
 */
41

42
43
/**
 * Constructor function for new tarvals.
44
 *
45
46
47
 * @param str   The string representing the target value
 * @param len   The length of the string
 * @param mode  The mode requested for the result tarval
48
 *
49
50
51
52
 * This function creates a new tarval representing the value represented
 * by a CString, aka char array. If a tarval representing this value already
 * exists, this tarval is returned instead of a new one. So tarvals are
 * directly comparable since their representation is unique.
53
 *
54
 * This function accepts the following strings:
55
 *
56
 * if mode is int_number:
57
58
 *  - [+-]?0[xX][0-9a-fA-F]+ (hexadecimal representation)
 *  - [+-]?0[0-7]*           (octal representation)
59
 *  - [+-]?0[bB][01]+        (binary representation)
60
 *  - [+-]?[1-9][0-9]*       (decimal representation)
61
 *
Christoph Mallon's avatar
Christoph Mallon committed
62
 * if mode is float_number:
63
 *  - [+-]?(decimal int) (. (decimal int))? ([eE][+-]?(decimal int))?
64
65
66
 *
 * if mode is boolean: true, True, TRUE ... False... 0, 1,
 *
67
 * if mode is reference: "null" and the same as for int_number
68
69
70
71
72
 *
 * Leading and/or trailing spaces are ignored
 *
 * @return
 *   A tarval of proper type representing the requested value is returned.
73
74
75
76
 *   Tarvals are unique, so for any value/mode pair at most one tarval will
 *   exist, which will be returned upon further requests with an identical
 *   value/mode pair.
 *
77
78
79
 * @note
 *   If the string is not representable in the given mode an assertion is
 *   thrown in assert build.
80
 *
81
 * @sa
82
 *   irmode.h for predefined modes
83
84
85
 *   new_tarval_from_long()
 *   new_tarval_from_double()
 */
Matthias Braun's avatar
Matthias Braun committed
86
87
FIRM_API ir_tarval *new_tarval_from_str(const char *str, size_t len,
                                        ir_mode *mode);
Christian Schäfer's avatar
Christian Schäfer committed
88

89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
/**
 * Construct a new tarval from a given string.
 *
 * @param str   The string representing the target value
 * @param len   The length of the string
 * @param sign  is -1 or 1 depending on the numbers sign
 * @param base  number system base.
 *              binary(2), octal(8), decimal(10) and hexadecimal(16) numbers
 *              are supported.
 * @param mode  The mode requested for the result tarval
 *
 * @return
 *   A tarval with the given mode. If overflow settings are set to
 *   TV_OVERFLOW_BAD then a tarval_bad is returned if the number can't be
 *   represented in the given mode.
104
 *   Returns bad if the number couldn't successfully be parsed.
105
 */
Matthias Braun's avatar
Matthias Braun committed
106
107
108
FIRM_API ir_tarval *new_integer_tarval_from_str(const char *str, size_t len,
                                                char sign, unsigned char base,
                                                ir_mode *mode);
109

110
111
/**
 * Constructor function for new tarvals
112
 *
113
114
 * @param l     The long representing the value
 * @param mode  The mode requested for the result tarval
115
 *
116
117
118
119
 * This function creates a new tarval representing the value represented
 * by a long integer. If a tarval representing this value already exists,
 * this tarval is returned instead of a new one. So tarvals are directly
 * comparable since their representation is unique.
120
 *
121
122
 * @return
 *   A tarval of proper type representing the requested value is returned.
123
124
125
126
 *   Tarvals are unique, so for any value/mode pair at most one tarval will
 *   exist, which will be returned upon further requests with an identical
 *   value/mode pair.
 *
127
128
129
 * @note
 *   If the long is not representable in the given mode an assertion is
 *   thrown in assert build.
130
 *
131
 * @sa
132
 *   irmode.h for predefined modes
133
134
 *   new_tarval_from_str()
 *   new_tarval_from_double()
135
 *
136
 */
Matthias Braun's avatar
Matthias Braun committed
137
FIRM_API ir_tarval *new_tarval_from_long(long l, ir_mode *mode);
138

Matthias Braun's avatar
Matthias Braun committed
139
140
141
142
143
144
145
146
147
148
149
150
151
/**
 * Construct a new tarval from a sequence of bytes.
 *
 * @param buf          pointer to a buffer holding at least
 *                     get_ir_mode_size_bytes(mode) bytes.
 * @param mode         mode for the resulting tarval
 * @param big_endian   construct value in big_endian order if true, else little
 *                     endian.
 * @return A newly created (or cached) tarval representing the value.
 */
FIRM_API ir_tarval *new_tarval_from_bytes(unsigned char const *buf,
                                          ir_mode *mode, int big_endian);

152
153
/**
 * Returns value as long if possible.
154
 */
Matthias Braun's avatar
Matthias Braun committed
155
FIRM_API long get_tarval_long(ir_tarval *tv);
156

157
/**
Götz Lindenmaier's avatar
Götz Lindenmaier committed
158
 * This validates if get_tarval_long() will return a satisfying
159
160
 * result. I.e. if tv is an int_number and between min, max
 * of long int (signed!)
161
162
 *
 * @param tv    the tarval
163
 */
Matthias Braun's avatar
Matthias Braun committed
164
FIRM_API int tarval_is_long(ir_tarval *tv);
165

166
167
/**
 * Constructor function for new tarvals.
168
 *
169
 * @param d     The (long) double representing the value
170
 * @param mode  The mode requested for the result tarval
171
 *
172
 * This function creates a new tarval representing the value represented
173
 * by a (long) double. If a tarval representing this value already exists,
174
175
176
 * this tarval is returned instead of a new one. So tarvals are directly
 * comparable since their representation is unique.
 * Only modes of sort float_number can be constructed this way.
177
 *
178
179
 * @return
 *   A tarval of proper type representing the requested value is returned.
180
181
182
183
 *   Tarvals are unique, so for any value/mode pair at most one tarval will
 *   exist, which will be returned upon further requests with an identical
 *   value/mode pair.
 *
184
 * @note
185
 *   If the (long) double is not representable in the given mode an assertion
186
 *   is thrown. This will happen for any mode not of sort float_number.
187
 *
188
 * @sa
189
 *   irmode.h for predefined values
190
191
192
 *   new_tarval_from_str()
 *   new_tarval_from_long()
 */
193
194
195
196
197
198
FIRM_API ir_tarval *new_tarval_from_double(double d, ir_mode *mode);

/**
 * same as new_tarval_from_double(), but with a long double argument
 */
FIRM_API ir_tarval *new_tarval_from_long_double(long double d, ir_mode *mode);
199
200
201
202
203
204
205

/**
 * This returns a double with the value represented value, or
 * gibberish, depending on the size of double and the size of the
 * stored value.
 * This will overflow silently, so use only if you know what
 * you are doing! (better check with tarval_is_long...)
206
207
 *
 * @param tv    the tarval
208
 */
209
210
211
212
213
214
FIRM_API double get_tarval_double(ir_tarval *tv);

/**
 * same as get_tarval_double but returns a long double value
 */
FIRM_API long double get_tarval_long_double(ir_tarval *tv);
215
216
217
218
219

/**
 * This validates if tarval_to_double() will return a satisfying
 * result. I.e. if tv is an float_number and between min, max
 * of double
220
221
 *
 * @param tv    the tarval
222
 */
Matthias Braun's avatar
Matthias Braun committed
223
FIRM_API int tarval_is_double(ir_tarval *tv);
224

225
226
227
228
229
/**
 * Returns the mode of the tarval.
 *
 * @param tv    the tarval
 */
Matthias Braun's avatar
Matthias Braun committed
230
FIRM_API ir_mode *get_tarval_mode(const ir_tarval *tv);
231

Michael Beck's avatar
Michael Beck committed
232
233
/**
 * Returns 1 if tv is negative
234
 *
235
 * @param tv    the tarval
236
 */
Matthias Braun's avatar
Matthias Braun committed
237
FIRM_API int tarval_is_negative(ir_tarval *tv);
238

Michael Beck's avatar
Michael Beck committed
239
240
241
/**
 * Returns 1 if tv is null
 *
242
 * @param tv    the tarval
Michael Beck's avatar
Michael Beck committed
243
 */
Matthias Braun's avatar
Matthias Braun committed
244
FIRM_API int tarval_is_null(ir_tarval *tv);
Michael Beck's avatar
Michael Beck committed
245

Michael Beck's avatar
Michael Beck committed
246
247
248
/**
 * Returns 1 if tv is the "one"
 *
249
 * @param tv    the tarval
Michael Beck's avatar
Michael Beck committed
250
 */
Matthias Braun's avatar
Matthias Braun committed
251
FIRM_API int tarval_is_one(ir_tarval *tv);
Michael Beck's avatar
Michael Beck committed
252

Michael Beck's avatar
Michael Beck committed
253
254
255
/**
 * Returns 1 if tv is the "minus one"
 *
256
 * @param tv    the tarval
Michael Beck's avatar
Michael Beck committed
257
 */
Matthias Braun's avatar
Matthias Braun committed
258
FIRM_API int tarval_is_minus_one(ir_tarval *tv);
Michael Beck's avatar
Michael Beck committed
259

260
/**
261
262
 * returns non-zero if all bits in the tarval are set
 */
Matthias Braun's avatar
Matthias Braun committed
263
FIRM_API int tarval_is_all_one(ir_tarval *tv);
264

265
/**
yb9976's avatar
yb9976 committed
266
 * Returns non-zero if the tarval is a constant (i.e. NOT
267
268
 * a reserved tarval like bad, undef, reachable etc.)
 */
Matthias Braun's avatar
Matthias Braun committed
269
FIRM_API int tarval_is_constant(ir_tarval *tv);
270

271
/** The 'bad' tarval. */
Matthias Braun's avatar
Matthias Braun committed
272
FIRM_API ir_tarval *tarval_bad;
273
/** Returns the 'bad' tarval. */
Matthias Braun's avatar
Matthias Braun committed
274
FIRM_API ir_tarval *get_tarval_bad(void);
275

276
/** The 'undefined' tarval. */
Matthias Braun's avatar
Matthias Braun committed
277
FIRM_API ir_tarval *tarval_undefined;
278
/** Returns the 'undefined' tarval. */
Matthias Braun's avatar
Matthias Braun committed
279
FIRM_API ir_tarval *get_tarval_undefined(void);
280
281

/** The mode_b tarval 'false'. */
Matthias Braun's avatar
Matthias Braun committed
282
FIRM_API ir_tarval *tarval_b_false;
283
/** Returns the mode_b tarval 'false'. */
Matthias Braun's avatar
Matthias Braun committed
284
FIRM_API ir_tarval *get_tarval_b_false(void);
285
286

/** The mode_b tarval 'true'. */
Matthias Braun's avatar
Matthias Braun committed
287
FIRM_API ir_tarval *tarval_b_true;
288
/** Returns the mode_b tarval 'true'. */
Matthias Braun's avatar
Matthias Braun committed
289
FIRM_API ir_tarval *get_tarval_b_true(void);
290

291
/** The mode_X tarval 'unreachable'. */
Matthias Braun's avatar
Matthias Braun committed
292
FIRM_API ir_tarval *tarval_unreachable;
293
/** Returns the mode_X tarval 'unreachable'. */
Matthias Braun's avatar
Matthias Braun committed
294
FIRM_API ir_tarval *get_tarval_unreachable(void);
295
296

/** The mode_X tarval 'reachable'. */
Matthias Braun's avatar
Matthias Braun committed
297
FIRM_API ir_tarval *tarval_reachable;
298
/** Returns the mode_X tarval 'reachable'. */
Matthias Braun's avatar
Matthias Braun committed
299
FIRM_API ir_tarval *get_tarval_reachable(void);
300

301
302
303
304
305
306
307
308
309
310
/** The 'top' tarval. This is just another name for the 'undefined' tarval. */
#define tarval_top          tarval_undefined
/** Returns the 'top' tarval. */
#define get_tarval_top()    get_tarval_undefined()

/** The 'bottom' tarval. This is just another name for the 'bad' tarval. */
#define tarval_bottom       tarval_bad
/** Returns the 'bottom' tarval. */
#define get_tarval_bottom() get_tarval_bad()

311
/** Returns the maximum value of a given mode. */
Matthias Braun's avatar
Matthias Braun committed
312
FIRM_API ir_tarval *get_tarval_max(ir_mode *mode);
313
314

/** Returns the minimum value of a given mode. */
Matthias Braun's avatar
Matthias Braun committed
315
FIRM_API ir_tarval *get_tarval_min(ir_mode *mode);
316

317
318
/** Returns the 0 value (additive neutral) of a given mode.
    For reference modes, the NULL value is returned (old tarval_P_void) */
Matthias Braun's avatar
Matthias Braun committed
319
FIRM_API ir_tarval *get_tarval_null(ir_mode *mode);
320
321

/** Returns the 1 value (multiplicative neutral) of a given mode. */
Matthias Braun's avatar
Matthias Braun committed
322
FIRM_API ir_tarval *get_tarval_one(ir_mode *mode);
323

324
325
/** Returns the -1 value (multiplicative neutral) of a given mode.
 *  Returns tarval bad for unsigned modes */
Matthias Braun's avatar
Matthias Braun committed
326
FIRM_API ir_tarval *get_tarval_minus_one(ir_mode *mode);
327

Matthias Braun's avatar
Matthias Braun committed
328
329
/** returns the value where all bits are 1 of a given mode.
 * returns tarval_bad for float modes */
Matthias Braun's avatar
Matthias Braun committed
330
FIRM_API ir_tarval *get_tarval_all_one(ir_mode *mode);
Matthias Braun's avatar
Matthias Braun committed
331

332
/** Returns quite nan for float_number modes. */
Matthias Braun's avatar
Matthias Braun committed
333
FIRM_API ir_tarval *get_tarval_nan(ir_mode *mode);
334

335
/** Returns +inf for float_number modes. */
Matthias Braun's avatar
Matthias Braun committed
336
FIRM_API ir_tarval *get_tarval_plus_inf(ir_mode *mode);
337

338
/** Returns -inf for float_number modes. */
Matthias Braun's avatar
Matthias Braun committed
339
FIRM_API ir_tarval *get_tarval_minus_inf(ir_mode *mode);
340

341
/** Modes for handling integer overflows. */
342
typedef enum tarval_int_overflow_mode_t {
343
344
345
	TV_OVERFLOW_BAD,      /**< tarval module will return tarval_bad if a overflow occurs */
	TV_OVERFLOW_WRAP,     /**< tarval module will overflow will be ignored, wrap around occurs */
	TV_OVERFLOW_SATURATE  /**< tarval module will saturate the overflow */
346
347
348
349
} tarval_int_overflow_mode_t;

/**
 * Sets the overflow mode for integer operations.
350
 *
yb9976's avatar
yb9976 committed
351
 * @param ov_mode  one of the overflow modes
352
 */
Michael Beck's avatar
Michael Beck committed
353
FIRM_API void tarval_set_integer_overflow_mode(tarval_int_overflow_mode_t ov_mode);
354
355

/**
356
 * Returns the overflow mode for integer operations.
357
 */
Michael Beck's avatar
Michael Beck committed
358
FIRM_API tarval_int_overflow_mode_t tarval_get_integer_overflow_mode(void);
359

360
361
/**
 * Compares two tarvals
362
 *
363
364
365
366
 * Compare a with b and return their relation.
 * This is either ir_rel_unordered, ir_rel_less, ir_rel_greater, ir_rel_equal
 * or ir_rel_false if a or b are symbolic pointers which can not be compared at
 * all.
367
 *
368
369
 * @param a   the first tarval to be compared
 * @param b   the second tarval to be compared
370
 */
371
FIRM_API ir_relation tarval_cmp(ir_tarval *a, ir_tarval *b);
372

373
374
/**
 * Converts a tarval to another mode.
375
 *
Michael Beck's avatar
Michael Beck committed
376
 * Convert tarval 'src' to mode 'mode', this will succeed if and only if mode
377
378
 * 'mode' is wider than the mode of src, as defined in the firm documentation
 * and as returned by the function mode_is_smaller defined in irmode.h.
379
 *
380
381
 * @param src    The tarval to convert
 * @param mode   Tho mode to convert to
382
 *
383
384
 * @return
 *   If a tarval of mode 'mode' with the result of the conversion of the 'src'
385
386
387
 *   tarvals value already exists, it will be returned, else a new tarval is
 *   constructed and returned
 *
388
 * @note
389
 *    Illegal convertions will trigger a panic
390
 *
391
 * @sa
392
393
 *    FIRM documentation for conversion rules
 *    mode_is_smaller defined in irmode.h
394
 */
Matthias Braun's avatar
Matthias Braun committed
395
FIRM_API ir_tarval *tarval_convert_to(ir_tarval *src, ir_mode *mode);
396

397
398
399
/*
 * These function implement basic computations representable as opcodes
 * in FIRM nodes.
400
401
402
403
404
405
 *
 * PARAMETERS
 *    tarval_neg:
 *    traval_abs:
 *      a - the tarval to operate on
 *
Michael Beck's avatar
Michael Beck committed
406
 *    all others:
407
408
409
410
 *      a - the first operand tarval
 *      b - the second operand tarval
 *
 * RESULT
Michael Beck's avatar
Michael Beck committed
411
 *    If necessary a new tarval is constructed for the resulting value,
412
413
414
415
 *   or the one already carrying the computation result is retrieved and
 *   returned as result.
 *
 * NOTES
416
 *   The order the arguments are given in is important, imagine postfix
417
 *   notation.
418
419
420
421
 *   Illegal operations will trigger an assertion.
 *   The sort member of the struct mode defines which operations are valid
 */

422
423
424
425
426
427
428
/**
 * Bitwise Negation of a tarval.
 *
 * @param a  the first tarval
 *
 * @return ~a or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
429
FIRM_API ir_tarval *tarval_not(ir_tarval *a);
430

431
432
433
434
435
436
437
/**
 * Arithmetic Negation of a tarval.
 *
 * @param a  the first tarval
 *
 * @return -a or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
438
FIRM_API ir_tarval *tarval_neg(ir_tarval *a);
439

440
441
442
443
444
445
446
447
/**
 * Addition of two tarvals.
 *
 * @param a  the first tarval
 * @param b  the second tarval
 *
 * @return a + b or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
448
FIRM_API ir_tarval *tarval_add(ir_tarval *a, ir_tarval *b);
449

450
451
452
453
454
455
456
457
458
/**
 * Subtraction from a tarval.
 *
 * @param a         the first tarval
 * @param b         the second tarval
 * @param dst_mode  the mode of the result, needed for mode_P - mode_P, else NULL
 *
 * @return a - b or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
459
FIRM_API ir_tarval *tarval_sub(ir_tarval *a, ir_tarval *b, ir_mode *dst_mode);
460

461
462
463
464
465
466
467
468
/**
 * Multiplication of tarvals.
 *
 * @param a  the first tarval
 * @param b  the second tarval
 *
 * @return a * b or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
469
FIRM_API ir_tarval *tarval_mul(ir_tarval *a, ir_tarval *b);
470

471
472
473
474
475
476
477
478
/**
 * Integer division of two tarvals.
 *
 * @param a  the first tarval
 * @param b  the second tarval
 *
 * @return a / b or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
479
FIRM_API ir_tarval *tarval_div(ir_tarval *a, ir_tarval *b);
480

481
482
483
484
485
486
487
488
/**
 * Remainder of integer division.
 *
 * @param a  the first tarval
 * @param b  the second tarval
 *
 * @return a % b or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
489
FIRM_API ir_tarval *tarval_mod(ir_tarval *a, ir_tarval *b);
490

491
492
493
494
495
496
497
498
499
/**
 * Integer division AND remainder.
 *
 * @param a        the first tarval
 * @param b        the second tarval
 * @param mod_res  after return, contains the remainder result, a % b or tarval_bad
 *
 * @return a / b or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
500
FIRM_API ir_tarval *tarval_divmod(ir_tarval *a, ir_tarval *b, ir_tarval **mod_res);
Michael Beck's avatar
Michael Beck committed
501

502
503
504
505
506
507
508
/**
 * Absolute value of a tarval.
 *
 * @param a  the first tarval
 *
 * @return |a| or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
509
FIRM_API ir_tarval *tarval_abs(ir_tarval *a);
510

511
512
513
514
515
516
517
518
/**
 * Bitwise and of two integer tarvals.
 *
 * @param a  the first tarval
 * @param b  the second tarval
 *
 * @return a & b or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
519
FIRM_API ir_tarval *tarval_and(ir_tarval *a, ir_tarval *b);
520

521
522
523
524
525
526
527
528
/**
 * Bitwise and not of two integer tarvals.
 *
 * @param a  the first tarval
 * @param b  the second tarval
 *
 * @return a & ~b or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
529
FIRM_API ir_tarval *tarval_andnot(ir_tarval *a, ir_tarval *b);
530

531
532
533
534
535
536
537
538
/**
 * Bitwise or of two integer tarvals.
 *
 * @param a  the first tarval
 * @param b  the second tarval
 *
 * @return a | b or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
539
FIRM_API ir_tarval *tarval_or(ir_tarval *a, ir_tarval *b);
540

541
542
543
544
545
546
547
548
/**
 * Bitwise exclusive or of two integer tarvals.
 *
 * @param a  the first tarval
 * @param b  the second tarval
 *
 * @return a ^ b or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
549
FIRM_API ir_tarval *tarval_eor(ir_tarval *a, ir_tarval *b);
550

551
552
553
554
555
556
557
558
/**
 * Logical Left shift.
 *
 * @param a  the first tarval
 * @param b  the second tarval
 *
 * @return a << b or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
559
FIRM_API ir_tarval *tarval_shl(ir_tarval *a, ir_tarval *b);
560

561
562
563
564
565
566
/**
 * logical left shift (variant with unsigned argument).
 * @see tarval_shl()
 */
FIRM_API ir_tarval *tarval_shl_unsigned(ir_tarval *a, unsigned b);

567
568
569
570
571
572
573
574
/**
 * Unsigned (logical) right shift.
 *
 * @param a  the first tarval
 * @param b  the second tarval
 *
 * @return a >>u b or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
575
FIRM_API ir_tarval *tarval_shr(ir_tarval *a, ir_tarval *b);
576

577
578
579
580
581
582
/**
 * unsigned (logical) right shift (variant with unsigned argument).
 * @see tarval_shr()
 */
FIRM_API ir_tarval *tarval_shr_unsigned(ir_tarval *a, unsigned b);

583
584
585
586
587
588
589
590
/**
 * Signed (arithmetic) right shift.
 *
 * @param a  the first tarval
 * @param b  the second tarval
 *
 * @return a >>s b or tarval_bad
 */
Matthias Braun's avatar
Matthias Braun committed
591
FIRM_API ir_tarval *tarval_shrs(ir_tarval *a, ir_tarval *b);
592

593
594
595
596
597
598
/**
 * signed (arithmetic) right shift (variant with unsigned argument).
 * @see tarval_shrs()
 */
FIRM_API ir_tarval *tarval_shrs_unsigned(ir_tarval *a, unsigned b);

599
600
/**
 * Returns Bit representation of a tarval value, as string of '0' and '1'
601
 *
602
 * @param tv   The tarval
603
 *
604
605
 * This function returns a printable bit representation of any value
 * stored as tarval. This representation is a null terminated C string.
606
 *
607
608
 * @return
 *   As usual in C a pointer to a char is returned. The length of the
609
610
611
 *   returned string if fixed, just read as many chars as the mode defines
 *   as size.
 *
612
613
614
 * @note
 *   The string is allocated using malloc() and is free()ed on the next call
 *   of this function.
Michael Beck's avatar
Michael Beck committed
615
 *   The string consists of the ASCII characters '0' and '1' and is
616
 *   null terminated
617
 *
618
 * @sa
619
620
 *    irmode.h for the definition of the ir_mode struct
 *    the size member of aforementioned struct
621
 */
Matthias Braun's avatar
Matthias Braun committed
622
FIRM_API char *get_tarval_bitpattern(ir_tarval *tv);
623

624
625
626
627
628
629
630
631
/**
 * Returns the bitpattern of the bytes_ofs byte.
 *
 * This function succeeds even if the mode of the tarval uses lesser bits
 * than requested, in that case the bitpattern is filled with zero bits.
 *
 * To query a 32bit value the following code can be used:
 *
632
 * val0 = tarval_sub_bits(tv, 0);  <- lowest bits
633
634
 * val1 = tarval_sub_bits(tv, 1);
 * val2 = tarval_sub_bits(tv, 2);
635
 * val3 = tarval_sub_bits(tv, 3);  <- highest bits
636
 *
637
638
 * Because this is the bit representation of the target machine, only the
 * following operations are legal on the result:
639
 *
Michael Beck's avatar
Michael Beck committed
640
 * - concatenation (endian dependence MUST be handled by the CALLER)
641
 * - bitwise logical operations to select/mask bits
642
 *
643
 * @param tv        the tarval
644
 * @param byte_ofs  the byte offset from lower to higher
645
646
 *
 * @note
647
648
 *   The result of this function is undefined if the mode is neither integer
 *   nor float.
649
 */
Matthias Braun's avatar
Matthias Braun committed
650
FIRM_API unsigned char get_tarval_sub_bits(ir_tarval *tv, unsigned byte_ofs);
651

652
653
654
/**
 * Returns non-zero if a given (integer) tarval has only one single bit
 * set.
655
656
 *
 * @param tv    the tarval
657
 */
Matthias Braun's avatar
Matthias Braun committed
658
FIRM_API int tarval_is_single_bit(ir_tarval *tv);
659

660
/**
661
 * Returns the number of set bits in a given (integer) tarval.
662
663
664
665
666
 *
 * @param tv    the tarval
 *
 * @return number of set bits or -1 on error
 */
Matthias Braun's avatar
Matthias Braun committed
667
FIRM_API int get_tarval_popcount(ir_tarval *tv);
668
669

/**
670
 * Returns the number of the lowest set bit in a given (integer) tarval.
671
672
673
674
675
 *
 * @param tv    the tarval
 *
 * @return number of lowest set bit or -1 on error
 */
Matthias Braun's avatar
Matthias Braun committed
676
FIRM_API int get_tarval_lowest_bit(ir_tarval *tv);
677

678
679
680
681
682
683
684
685
686
/**
 * Return the number of the highest set bit in a given (integer) tarval.
 *
 * @param tv    the tarval
 *
 * @return number of highest set bit or -1 on error
 */
FIRM_API int get_tarval_highest_bit(ir_tarval *tv);

687
/**
688
689
690
691
692
 * Output a tarval to a string buffer.
 *
 * @param buf     the output buffer
 * @param buflen  the length of the buffer
 * @param tv      the tarval
693
 * @param hex     print value in hexadecimal if true, else decimal
694
 */
695
696
FIRM_API int tarval_snprintf(char *buf, size_t buflen, ir_tarval *tv,
                             int hex);
697

698
/**
699
700
701
 * Output a tarval to stdio.
 *
 * @param tv    the tarval
702
 */
Matthias Braun's avatar
Matthias Braun committed
703
FIRM_API int tarval_printf(ir_tarval *tv);
704

Michael Beck's avatar
Michael Beck committed
705
/**
706
707
 * Returns non-zero if the mantissa of a floating point tarval is zero
 * (i.e. 1.0Exxx)
708
709
 *
 * @param tv    the tarval
Michael Beck's avatar
Michael Beck committed
710
 */
711
FIRM_API int tarval_zero_mantissa(ir_tarval *tv);
Michael Beck's avatar
Michael Beck committed
712
713
714
715

/**
 * Returns the exponent of a floating point IEEE-754
 * tarval.
716
717
 *
 * @param tv    the tarval
Michael Beck's avatar
Michael Beck committed
718
 */
719
FIRM_API int tarval_get_exponent(ir_tarval *tv);
Michael Beck's avatar
Michael Beck committed
720

721
722
723
724
725
/**
 * Check if the tarval can be converted to the given mode without
 * precision loss.
 *
 * @param tv    the tarval
726
 * @param mode  the mode to convert to
727
 */
Matthias Braun's avatar
Matthias Braun committed
728
FIRM_API int tarval_ieee754_can_conv_lossless(ir_tarval *tv, ir_mode *mode);
729

730
/**
731
 * Returns non-zero if the result of the last IEEE-754 operation was exact.
732
 */
Michael Beck's avatar
Michael Beck committed
733
FIRM_API unsigned tarval_ieee754_get_exact(void);
734

735
736
/**
 * Check if its the a floating point NaN.
737
738
 *
 * @param tv    the tarval
739
 */
Matthias Braun's avatar
Matthias Braun committed
740
FIRM_API int tarval_is_NaN(ir_tarval *tv);
741
742
743

/**
 * Check if its the a floating point +inf.
744
745
 *
 * @param tv    the tarval
746
 */
Matthias Braun's avatar
Matthias Braun committed
747
FIRM_API int tarval_is_plus_inf(ir_tarval *tv);
748
749
750

/**
 * Check if its the a floating point -inf.
751
752
 *
 * @param tv    the tarval
753
 */
Matthias Braun's avatar
Matthias Braun committed
754
FIRM_API int tarval_is_minus_inf(ir_tarval *tv);
755
756
757

/**
 * Check if the tarval represents a finite value, ie neither NaN nor inf.
758
759
 *
 * @param tv    the tarval
760
 */
Matthias Braun's avatar
Matthias Braun committed
761
FIRM_API int tarval_is_finite(ir_tarval *tv);
762

Michael Beck's avatar
Michael Beck committed
763
764
765
766
767
768
769
770
/**
 *   Checks whether a pointer points to a tarval.
 *
 *   @param thing     an arbitrary pointer
 *
 *   @return
 *       true if the thing is a tarval, else false
 */
Michael Beck's avatar
Michael Beck committed
771
FIRM_API int is_tarval(const void *thing);
772

Matthias Braun's avatar
Matthias Braun committed
773
774
/** @} */

775
#include "end.h"
Michael Beck's avatar
Michael Beck committed
776

777
#endif