Fix setoutfile/irgname debugger commands.
[libfirm] / ir / tv / fltcalc.h
1 /*
2  * Copyright (C) 1995-2011 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  * @file
22  * @brief    tarval floating point calculations
23  * @date     2003
24  * @author   Mathias Heil
25  * @version  $Id$
26  */
27 #ifndef FIRM_TV_FLTCALC_H
28 #define FIRM_TV_FLTCALC_H
29
30 #include <stdlib.h>
31 #include "firm_types.h"
32 #include "irtypes.h"
33
34 enum {
35         FC_DEC,
36         FC_HEX,
37         FC_BIN,
38         FC_PACKED
39 };
40
41 /** IEEE-754 Rounding modes. */
42 typedef enum {
43         FC_TONEAREST,   /**< if unsure, to the nearest even */
44         FC_TOPOSITIVE,  /**< to +oo */
45         FC_TONEGATIVE,  /**< to -oo */
46         FC_TOZERO       /**< to 0 */
47 } fc_rounding_mode_t;
48
49 #define FC_DEFAULT_PRECISION 64
50
51 /**
52  * possible float states
53  */
54 typedef enum {
55         FC_NORMAL,       /**< normal representation, implicit 1 */
56         FC_ZERO,         /**< +/-0 */
57         FC_SUBNORMAL,    /**< denormals, implicit 0 */
58         FC_INF,          /**< +/-oo */
59         FC_NAN,          /**< Not A Number */
60 } value_class_t;
61
62 struct fp_value;
63 typedef struct fp_value fp_value;
64
65 /*@{*/
66 /** internal buffer access
67  * All functions that accept NULL as return buffer put their result into an
68  * internal buffer.
69  * @return fc_get_buffer() returns the pointer to the buffer, fc_get_buffer_length()
70  * returns the size of this buffer
71  */
72 const void *fc_get_buffer(void);
73 int fc_get_buffer_length(void);
74 /*}@*/
75
76 void *fc_val_from_str(const char *str, size_t len, const float_descriptor_t *desc, void *result);
77
78 /** get the representation of a floating point value
79  * This function tries to builds a representation having the same value as the
80  * float number passed.
81  * If the wished precision is less than the precision of long double the value
82  * built will be rounded. Therefore only an approximation of the passed float
83  * can be expected in this case.
84  *
85  * @param l       The floating point number to build a representation for
86  * @param desc    The floating point descriptor
87  * @param result  A buffer to hold the value built. If this is NULL, the internal
88  *                accumulator buffer is used. Note that the buffer must be big
89  *                enough to hold the value. Use fc_get_buffer_length() to find out
90  *                the size needed
91  *
92  * @return  The result pointer passed to the function. If this was NULL this returns
93  *          a pointer to the internal accumulator buffer
94  */
95 fp_value *fc_val_from_ieee754(long double l, const float_descriptor_t *desc,
96                               fp_value *result);
97
98 /** retrieve the float value of an internal value
99  * This function casts the internal value to long double and returns a
100  * long double with that value.
101  * This implies that values of higher precision than long double are subject to
102  * rounding, so the returned value might not the same than the actually
103  * represented value.
104  *
105  * @param val  The representation of a float value
106  *
107  * @return a float value approximating the represented value
108  */
109 long double fc_val_to_ieee754(const fp_value *val);
110
111 /** cast a value to another precision
112  * This function changes the precision of a float representation.
113  * If the new precision is less than the original precision the returned
114  * value might not be the same as the original value.
115  *
116  * @param val     The value to be casted
117  * @param desc    The floating point descriptor
118  * @param result  A buffer to hold the value built. If this is NULL, the internal
119  *                accumulator buffer is used. Note that the buffer must be big
120  *                enough to hold the value. Use fc_get_buffer_length() to find out
121  *                the size needed
122  * @return  The result pointer passed to the function. If this was NULL this returns
123  *          a pointer to the internal accumulator buffer
124  */
125 fp_value *fc_cast(const fp_value *val, const float_descriptor_t *desc, fp_value *result);
126
127 /*@{*/
128 /** build a special float value
129  * This function builds a representation for a special float value, as indicated by the
130  * function's suffix.
131  *
132  * @param desc    The floating point descriptor
133  * @param result  A buffer to hold the value built. If this is NULL, the internal
134  *                accumulator buffer is used. Note that the buffer must be big
135  *                enough to hold the value. Use fc_get_buffer_length() to find out
136  *                the size needed
137  * @return  The result pointer passed to the function. If this was NULL this returns
138  *          a pointer to the internal accumulator buffer
139  */
140 fp_value *fc_get_min(const float_descriptor_t *desc, fp_value *result);
141 fp_value *fc_get_max(const float_descriptor_t *desc, fp_value *result);
142 fp_value *fc_get_snan(const float_descriptor_t *desc, fp_value *result);
143 fp_value *fc_get_qnan(const float_descriptor_t *desc, fp_value *result);
144 fp_value *fc_get_plusinf(const float_descriptor_t *desc, fp_value *result);
145 fp_value *fc_get_minusinf(const float_descriptor_t *desc, fp_value *result);
146 /*@}*/
147
148 int fc_is_zero(const fp_value *a);
149 int fc_is_negative(const fp_value *a);
150 int fc_is_inf(const fp_value *a);
151 int fc_is_nan(const fp_value *a);
152 int fc_is_subnormal(const fp_value *a);
153
154 fp_value *fc_add(const fp_value *a, const fp_value *b, fp_value *result);
155 fp_value *fc_sub(const fp_value *a, const fp_value *b, fp_value *result);
156 fp_value *fc_mul(const fp_value *a, const fp_value *b, fp_value *result);
157 fp_value *fc_div(const fp_value *a, const fp_value *b, fp_value *result);
158 fp_value *fc_neg(const fp_value *a, fp_value *result);
159 fp_value *fc_int(const fp_value *a, fp_value *result);
160 fp_value *fc_rnd(const fp_value *a, fp_value *result);
161
162 char *fc_print(const fp_value *a, char *buf, int buflen, unsigned base);
163
164 /** Compare two values
165  * This function compares two values
166  *
167  * @param a Value No. 1
168  * @param b Value No. 2
169  * @result The returned value will be one of
170  *          -1  if a < b
171  *           0  if a == b
172  *           1  if a > b
173  *           2  if either value is NaN
174  */
175 int fc_comp(const fp_value *a, const fp_value *b);
176
177 /**
178  * Converts an floating point value into an integer value.
179  */
180 int fc_flt2int(const fp_value *a, void *result, ir_mode *dst_mode);
181
182 /**
183  * Returns non-zero if the mantissa is zero, i.e. 1.0Exxx
184  */
185 int fc_zero_mantissa(const fp_value *value);
186
187 /**
188  * Returns the exponent of a value.
189  */
190 int fc_get_exponent(const fp_value *value);
191
192 /**
193  * Return non-zero if a given value can be converted lossless into another precision.
194  */
195 int fc_can_lossless_conv_to(const fp_value *value, const float_descriptor_t *desc);
196
197 /** Set new rounding mode
198  * This function sets the rounding mode to one of the following, returning
199  * the previously set rounding mode.
200  * FC_TONEAREST (default):
201  *    Any unrepresentable value is rounded to the nearest representable
202  *    value. If it lies in the middle the value with the least significant
203  *    bit of zero is chosen (the even one).
204  *    Values too big to represent will round to +/-infinity.
205  * FC_TONEGATIVE
206  *    Any unrepresentable value is rounded towards negative infinity.
207  *    Positive values too big to represent will round to the biggest
208  *    representable value, negative values too small to represent will
209  *    round to -infinity.
210  * FC_TOPOSITIVE
211  *    Any unrepresentable value is rounded towards positive infinity
212  *    Negative values too small to represent will round to the biggest
213  *    representable value, positive values too big to represent will
214  *    round to +infinity.
215  * FC_TOZERO
216  *    Any unrepresentable value is rounded towards zero, effectively
217  *    chopping off any bits beyond the mantissa size.
218  *    Values too big to represent will round to the biggest/smallest
219  *    representable value.
220  *
221  * These modes correspond to the modes required by the IEEE-754 standard.
222  *
223  * @param mode The new rounding mode. Any value other than the four
224  *        defined values will have no effect.
225  * @return The previous rounding mode.
226  *
227  * @see fc_get_rounding_mode()
228  * @see IEEE754, IEEE854 Floating Point Standard
229  */
230 fc_rounding_mode_t fc_set_rounding_mode(fc_rounding_mode_t mode);
231
232 /** Get the rounding mode
233  * This function retrieves the currently used rounding mode
234  *
235  * @return The current rounding mode
236  * @see fc_set_rounding_mode()
237  */
238 fc_rounding_mode_t fc_get_rounding_mode(void);
239
240 /** Get bit representation of a value
241  * This function allows to read a value in encoded form, byte wise.
242  * The value will be packed corresponding to the way used by the IEEE
243  * encoding formats, i.e.
244  *        One bit   sign
245  *   exp_size bits  exponent + bias
246  *  mant_size bits  mantissa, without leading 1
247  *
248  * As in IEEE, an exponent of 0 indicates a denormalized number, which
249  * implies a most significant bit of zero instead of one; an exponent
250  * of all ones (2**exp_size - 1) encodes infinity if the mantissa is
251  * all zeros, else Not A Number.
252  *
253  * @param val A pointer to the value. If NULL is passed a copy of the
254  *        most recent value passed to this function is used, saving the
255  *        packing step. This behavior may be changed in the future.
256  * @param num_bit The maximum number of bits to return. Any bit beyond
257  *        num_bit will be returned as zero.
258  * @param byte_ofs The byte index to read, 0 is the least significant
259  *        byte.
260  * @return 8 bits of encoded data
261  */
262 unsigned char fc_sub_bits(const fp_value *val, unsigned num_bit, unsigned byte_ofs);
263
264 /**
265  * Returns non-zero if the result of the last operation was exact.
266  */
267 int fc_is_exact(void);
268
269 void init_fltcalc(int precision);
270 void finish_fltcalc(void);
271
272 #endif /* FIRM_TV_FLTCALC_H */