2 * Copyright (C) 1995-2007 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
30 #include "firm_config.h"
32 #ifdef HAVE_LONG_DOUBLE
33 /* XXX Set this via autoconf */
34 #define HAVE_EXPLICIT_ONE
35 typedef long double LLDBL;
41 FC_add, /**< addition */
42 FC_sub, /**< subtraction */
43 FC_mul, /**< multiplication */
44 FC_div, /**< divide */
45 FC_neg, /**< negate */
46 FC_int, /**< truncate to integer */
47 FC_rnd /**< round to integer */
57 /** IEEE-754 Rounding modes. */
59 FC_TONEAREST, /**< if unsure, to the nearest even */
60 FC_TOPOSITIVE, /**< to +oo */
61 FC_TONEGATIVE, /**< to -oo */
62 FC_TOZERO /**< to 0 */
65 #define FC_DEFAULT_PRECISION 64
68 /** internal buffer access
69 * All functions that accept NULL as return buffer put their result into an
71 * @return fc_get_buffer() returns the pointer to the buffer, fc_get_buffer_length()
72 * returns the size of this buffer
74 const void *fc_get_buffer(void);
75 int fc_get_buffer_length(void);
78 char *fc_val_from_str(const char *str, unsigned int len, char exp_size, char mant_size, char *result);
80 /** get the representation of a floating point value
81 * This function tries to builds a representation having the same value as the
82 * float number passed.
83 * If the wished precision is less than the precision of LLDBL the value built
84 * will be rounded. Therefore only an approximation of the passed float can be
85 * expected in this case.
87 * @param l The floating point number to build a representation for
88 * @param exp_size The number of bits of the new exponent
89 * @param mant_size The number of bits of the new mantissa
90 * @param result A buffer to hold the value built. If this is NULL, the internal
91 * accumulator buffer is used. Note that the buffer must be big
92 * enough to hold the value. Use fc_get_buffer_length() to find out
94 * @return The result pointer passed to the function. If this was NULL this returns
95 * a pointer to the internal accumulator buffer
97 char *fc_val_from_float(LLDBL l, char exp_size, char mant_size, char *result);
99 /** retrieve the float value of an internal value
100 * This function casts the internal value to LLDBL and returns a LLDBL with
102 * This implies that values of higher precision than LLDBL are subject to
103 * rounding, so the returned value might not the same than the actually
106 * @param val The representation of a float value
107 * @return a float value approximating the represented value
109 LLDBL fc_val_to_float(const void *val);
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.
116 * @param val The value to be casted
117 * @param exp_size The number of bits of the new exponent
118 * @param mant_size The number of bits of the new mantissa
119 * @param result A buffer to hold the value built. If this is NULL, the internal
120 * accumulator buffer is used. Note that the buffer must be big
121 * enough to hold the value. Use fc_get_buffer_length() to find out
123 * @return The result pointer passed to the function. If this was NULL this returns
124 * a pointer to the internal accumulator buffer
126 char *fc_cast(const void *val, char exp_size, char mant_size, char *result);
129 /** build a special float value
130 * This function builds a representation for a special float value, as indicated by the
133 * @param exponent_size The number of bits of exponent of the float type the value
135 * @param mantissa_size The number of bits of mantissa of the float type the value
137 * @param result A buffer to hold the value built. If this is NULL, the internal
138 * accumulator buffer is used. Note that the buffer must be big
139 * enough to hold the value. Use fc_get_buffer_length() to find out
141 * @return The result pointer passed to the function. If this was NULL this returns
142 * a pointer to the internal accumulator buffer
144 char *fc_get_min(unsigned int exponent_size, unsigned int mantissa_size, char* result);
145 char *fc_get_max(unsigned int exponent_size, unsigned int mantissa_size, char* result);
146 char *fc_get_snan(unsigned int exponent_size, unsigned int mantissa_size, char* result);
147 char *fc_get_qnan(unsigned int exponent_size, unsigned int mantissa_size, char* result);
148 char *fc_get_plusinf(unsigned int exponent_size, unsigned int mantissa_size, char* result);
149 char *fc_get_minusinf(unsigned int exponent_size, unsigned int mantissa_size, char* result);
152 int fc_is_zero(const void *a);
153 int fc_is_negative(const void *a);
154 int fc_is_inf(const void *a);
155 int fc_is_nan(const void *a);
156 int fc_is_subnormal(const void *a);
158 char *fc_add(const void *a, const void *b, void *result);
159 char *fc_sub(const void *a, const void *b, void *result);
160 char *fc_mul(const void *a, const void *b, void *result);
161 char *fc_div(const void *a, const void *b, void *result);
162 char *fc_neg(const void *a, void *result);
163 char *fc_int(const void *a, void *result);
164 char *fc_rnd(const void *a, void *result);
166 char *fc_print(const void *a, char *buf, int buflen, unsigned base);
168 /** Compare two values
169 * This function compares two values
171 * @param a Value No. 1
172 * @param b Value No. 2
173 * @result The returned value will be one of
177 * 2 if either value is NaN
179 int fc_comp(const void *a, const void *b);
181 /** Set new rounding mode
182 * This function sets the rounding mode to one of the following, returning
183 * the previously set rounding mode.
184 * FC_TONEAREST (default):
185 * Any unrepresentable value is rounded to the nearest representable
186 * value. If it lies in the middle the value with the least significant
187 * bit of zero is chosen (the even one).
188 * Values too big to represent will round to +/-infinity.
190 * Any unrepresentable value is rounded towards negative infinity.
191 * Positive values too big to represent will round to the biggest
192 * representable value, negative values too small to represent will
193 * round to -infinity.
195 * Any unrepresentable value is rounded towards positive infinity
196 * Negative values too small to represent will round to the biggest
197 * representable value, positive values too big to represent will
198 * round to +infinity.
200 * Any unrepresentable value is rounded towards zero, effectively
201 * chopping off any bits beyond the mantissa size.
202 * Values too big to represent will round to the biggest/smallest
203 * representable value.
205 * These modes correspond to the modes required by the IEEE-754 standard.
207 * @param mode The new rounding mode. Any value other than the four
208 * defined values will have no effect.
209 * @return The previous rounding mode.
211 * @see fc_get_rounding_mode()
212 * @see IEEE754, IEEE854 Floating Point Standard
214 fc_rounding_mode_t fc_set_rounding_mode(fc_rounding_mode_t mode);
216 /** Get the rounding mode
217 * This function retrieves the currently used rounding mode
219 * @return The current rounding mode
220 * @see fc_set_rounding_mode()
222 fc_rounding_mode_t fc_get_rounding_mode(void);
224 /** Get bit representation of a value
225 * This function allows to read a value in encoded form, byte wise.
226 * The value will be packed corresponding to the way used by the IEEE
227 * encoding formats, i.e.
229 * exp_size bits exponent + bias
230 * mant_size bits mantissa, without leading 1
232 * As in IEEE, an exponent of 0 indicates a denormalized number, which
233 * implies a most significant bit of zero instead of one; an exponent
234 * of all ones (2**exp_size - 1) encodes infinity if the mantissa is
235 * all zeros, else Not A Number.
237 * @param val A pointer to the value. If NULL is passed a copy of the
238 * most recent value passed to this function is used, saving the
239 * packing step. This behavior may be changed in the future.
240 * @param num_bit The maximum number of bits to return. Any bit beyond
241 * num_bit will be returned as zero.
242 * @param byte_ofs The byte index to read, 0 is the least significant
244 * @return 8 bits of encoded data
246 unsigned char fc_sub_bits(const void *val, unsigned num_bit, unsigned byte_ofs);
248 void init_fltcalc(int precision);
249 void finish_fltcalc(void);
251 #endif /* FIRM_TV_FLTCALC_H */