2 * Copyright (C) 1995-2011 University of Karlsruhe. All right reserved.
4 * This file is part of libFirm.
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.
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.
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
22 * @brief tarval floating point calculations
24 * @author Mathias Heil
27 #ifndef FIRM_TV_FLTCALC_H
28 #define FIRM_TV_FLTCALC_H
31 #include "firm_types.h"
40 /** IEEE-754 Rounding modes. */
42 FC_TONEAREST, /**< if unsure, to the nearest even */
43 FC_TOPOSITIVE, /**< to +oo */
44 FC_TONEGATIVE, /**< to -oo */
45 FC_TOZERO /**< to 0 */
48 #define FC_DEFAULT_PRECISION 64
51 * possible float states
54 NORMAL, /**< normal representation, implicit 1 */
56 SUBNORMAL, /**< denormals, implicit 0 */
58 NAN, /**< Not A Number */
62 * A descriptor for an IEEE float value.
64 typedef struct ieee_descriptor_t {
65 unsigned char exponent_size; /**< size of exponent in bits */
66 unsigned char mantissa_size; /**< size of mantissa in bits */
67 unsigned char explicit_one; /**< set if the leading one is explicit */
68 unsigned char clss; /**< state of this float */
72 typedef struct fp_value fp_value;
75 /** internal buffer access
76 * All functions that accept NULL as return buffer put their result into an
78 * @return fc_get_buffer() returns the pointer to the buffer, fc_get_buffer_length()
79 * returns the size of this buffer
81 const void *fc_get_buffer(void);
82 int fc_get_buffer_length(void);
85 void *fc_val_from_str(const char *str, size_t len, const ieee_descriptor_t *desc, void *result);
87 /** get the representation of a floating point value
88 * This function tries to builds a representation having the same value as the
89 * float number passed.
90 * If the wished precision is less than the precision of long double the value
91 * built will be rounded. Therefore only an approximation of the passed float
92 * can be expected in this case.
94 * @param l The floating point number to build a representation for
95 * @param desc The floating point descriptor
96 * @param result A buffer to hold the value built. If this is NULL, the internal
97 * accumulator buffer is used. Note that the buffer must be big
98 * enough to hold the value. Use fc_get_buffer_length() to find out
101 * @return The result pointer passed to the function. If this was NULL this returns
102 * a pointer to the internal accumulator buffer
104 fp_value *fc_val_from_ieee754(long double l, const ieee_descriptor_t *desc,
107 /** retrieve the float value of an internal value
108 * This function casts the internal value to long double and returns a
109 * long double with that value.
110 * This implies that values of higher precision than long double are subject to
111 * rounding, so the returned value might not the same than the actually
114 * @param val The representation of a float value
116 * @return a float value approximating the represented value
118 long double fc_val_to_ieee754(const fp_value *val);
120 /** cast a value to another precision
121 * This function changes the precision of a float representation.
122 * If the new precision is less than the original precision the returned
123 * value might not be the same as the original value.
125 * @param val The value to be casted
126 * @param desc The floating point descriptor
127 * @param result A buffer to hold the value built. If this is NULL, the internal
128 * accumulator buffer is used. Note that the buffer must be big
129 * enough to hold the value. Use fc_get_buffer_length() to find out
131 * @return The result pointer passed to the function. If this was NULL this returns
132 * a pointer to the internal accumulator buffer
134 fp_value *fc_cast(const fp_value *val, const ieee_descriptor_t *desc, fp_value *result);
137 /** build a special float value
138 * This function builds a representation for a special float value, as indicated by the
141 * @param desc The floating point descriptor
142 * @param result A buffer to hold the value built. If this is NULL, the internal
143 * accumulator buffer is used. Note that the buffer must be big
144 * enough to hold the value. Use fc_get_buffer_length() to find out
146 * @return The result pointer passed to the function. If this was NULL this returns
147 * a pointer to the internal accumulator buffer
149 fp_value *fc_get_min(const ieee_descriptor_t *desc, fp_value *result);
150 fp_value *fc_get_max(const ieee_descriptor_t *desc, fp_value *result);
151 fp_value *fc_get_snan(const ieee_descriptor_t *desc, fp_value *result);
152 fp_value *fc_get_qnan(const ieee_descriptor_t *desc, fp_value *result);
153 fp_value *fc_get_plusinf(const ieee_descriptor_t *desc, fp_value *result);
154 fp_value *fc_get_minusinf(const ieee_descriptor_t *desc, fp_value *result);
157 int fc_is_zero(const fp_value *a);
158 int fc_is_negative(const fp_value *a);
159 int fc_is_inf(const fp_value *a);
160 int fc_is_nan(const fp_value *a);
161 int fc_is_subnormal(const fp_value *a);
163 fp_value *fc_add(const fp_value *a, const fp_value *b, fp_value *result);
164 fp_value *fc_sub(const fp_value *a, const fp_value *b, fp_value *result);
165 fp_value *fc_mul(const fp_value *a, const fp_value *b, fp_value *result);
166 fp_value *fc_div(const fp_value *a, const fp_value *b, fp_value *result);
167 fp_value *fc_neg(const fp_value *a, fp_value *result);
168 fp_value *fc_int(const fp_value *a, fp_value *result);
169 fp_value *fc_rnd(const fp_value *a, fp_value *result);
171 char *fc_print(const fp_value *a, char *buf, int buflen, unsigned base);
173 /** Compare two values
174 * This function compares two values
176 * @param a Value No. 1
177 * @param b Value No. 2
178 * @result The returned value will be one of
182 * 2 if either value is NaN
184 int fc_comp(const fp_value *a, const fp_value *b);
187 * Converts an floating point value into an integer value.
189 int fc_flt2int(const fp_value *a, void *result, ir_mode *dst_mode);
192 * Returns non-zero if the mantissa is zero, i.e. 1.0Exxx
194 int fc_zero_mantissa(const fp_value *value);
197 * Returns the exponent of a value.
199 int fc_get_exponent(const fp_value *value);
202 * Return non-zero if a given value can be converted lossless into another precision.
204 int fc_can_lossless_conv_to(const fp_value *value, const ieee_descriptor_t *desc);
206 /** Set new rounding mode
207 * This function sets the rounding mode to one of the following, returning
208 * the previously set rounding mode.
209 * FC_TONEAREST (default):
210 * Any unrepresentable value is rounded to the nearest representable
211 * value. If it lies in the middle the value with the least significant
212 * bit of zero is chosen (the even one).
213 * Values too big to represent will round to +/-infinity.
215 * Any unrepresentable value is rounded towards negative infinity.
216 * Positive values too big to represent will round to the biggest
217 * representable value, negative values too small to represent will
218 * round to -infinity.
220 * Any unrepresentable value is rounded towards positive infinity
221 * Negative values too small to represent will round to the biggest
222 * representable value, positive values too big to represent will
223 * round to +infinity.
225 * Any unrepresentable value is rounded towards zero, effectively
226 * chopping off any bits beyond the mantissa size.
227 * Values too big to represent will round to the biggest/smallest
228 * representable value.
230 * These modes correspond to the modes required by the IEEE-754 standard.
232 * @param mode The new rounding mode. Any value other than the four
233 * defined values will have no effect.
234 * @return The previous rounding mode.
236 * @see fc_get_rounding_mode()
237 * @see IEEE754, IEEE854 Floating Point Standard
239 fc_rounding_mode_t fc_set_rounding_mode(fc_rounding_mode_t mode);
241 /** Get the rounding mode
242 * This function retrieves the currently used rounding mode
244 * @return The current rounding mode
245 * @see fc_set_rounding_mode()
247 fc_rounding_mode_t fc_get_rounding_mode(void);
249 /** Get bit representation of a value
250 * This function allows to read a value in encoded form, byte wise.
251 * The value will be packed corresponding to the way used by the IEEE
252 * encoding formats, i.e.
254 * exp_size bits exponent + bias
255 * mant_size bits mantissa, without leading 1
257 * As in IEEE, an exponent of 0 indicates a denormalized number, which
258 * implies a most significant bit of zero instead of one; an exponent
259 * of all ones (2**exp_size - 1) encodes infinity if the mantissa is
260 * all zeros, else Not A Number.
262 * @param val A pointer to the value. If NULL is passed a copy of the
263 * most recent value passed to this function is used, saving the
264 * packing step. This behavior may be changed in the future.
265 * @param num_bit The maximum number of bits to return. Any bit beyond
266 * num_bit will be returned as zero.
267 * @param byte_ofs The byte index to read, 0 is the least significant
269 * @return 8 bits of encoded data
271 unsigned char fc_sub_bits(const fp_value *val, unsigned num_bit, unsigned byte_ofs);
274 * Set the immediate precision for IEEE-754 results. Set this to
275 * 0 to get the same precision as the operands.
276 * For x87 compatibility, set this to 80.
278 * @return the old setting
280 unsigned fc_set_immediate_precision(unsigned bits);
283 * Returns non-zero if the result of the last operation was exact.
285 int fc_is_exact(void);
287 void init_fltcalc(int precision);
288 void finish_fltcalc(void);
290 #endif /* FIRM_TV_FLTCALC_H */