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