| 1 | /*␊ |
| 2 | * Copyright (c) 2002 Apple Computer, Inc. All rights reserved.␊ |
| 3 | *␊ |
| 4 | * @APPLE_LICENSE_HEADER_START@␊ |
| 5 | * ␊ |
| 6 | * The contents of this file constitute Original Code as defined in and␊ |
| 7 | * are subject to the Apple Public Source License Version 1.1 (the␊ |
| 8 | * "License"). You may not use this file except in compliance with the␊ |
| 9 | * License. Please obtain a copy of the License at␊ |
| 10 | * http://www.apple.com/publicsource and read it before using this file.␊ |
| 11 | * ␊ |
| 12 | * This Original Code and all software distributed under the License are␊ |
| 13 | * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER␊ |
| 14 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,␊ |
| 15 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,␊ |
| 16 | * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the␊ |
| 17 | * License for the specific language governing rights and limitations␊ |
| 18 | * under the License.␊ |
| 19 | * ␊ |
| 20 | * @APPLE_LICENSE_HEADER_END@␊ |
| 21 | */␊ |
| 22 | ␊ |
| 23 | /*******************************************************************************␊ |
| 24 | * *␊ |
| 25 | * File: fenv.h␉ *␊ |
| 26 | * *␊ |
| 27 | * Contains: typedefs and prototypes for C99 floating point environment. *␊ |
| 28 | * *␊ |
| 29 | *******************************************************************************/␊ |
| 30 | ␊ |
| 31 | #ifndef __FENV__␊ |
| 32 | #define __FENV__␊ |
| 33 | ␊ |
| 34 | #if defined( __ppc__ ) || defined( __ppc64__ )␊ |
| 35 | #error Wrong arch. This is Intel only.␊ |
| 36 | #endif␊ |
| 37 | ␊ |
| 38 | #if defined(__GNUC__) && (__GNUC__ >= 4) ␊ |
| 39 | #pragma GCC fenv␊ |
| 40 | #endif␊ |
| 41 | ␊ |
| 42 | #ifdef __cplusplus␊ |
| 43 | extern "C" {␊ |
| 44 | #endif␊ |
| 45 | ␊ |
| 46 | /*␊ |
| 47 | A collection of functions designed to provide access to the floating␊ |
| 48 | point environment for numerical programming. It is compliant with␊ |
| 49 | the floating-point requirements in C99.␊ |
| 50 | ␊ |
| 51 | Earlier versions of fenv.h were merely "modeled after" C9X. Many of the functions ␊ |
| 52 | that formerly returned ints now return void to be standard compliant.␊ |
| 53 | ␊ |
| 54 | Note: There are actually two physical floating point environments on x86. There␊ |
| 55 | is the one described by the x87 floating point control and status words, which applies ␊ |
| 56 | primarily to calculations done with long double on MacOS X for Intel. There is the ␊ |
| 57 | MXCSR which applies primarily to calculations done with scalar float, scalar double ␊ |
| 58 | and SSE/SSE2/SSE3. The high level interface, which uses FE_ macros as int arguments ␊ |
| 59 | to configure the fexcep_t, returns and works with values that represents the logical ␊ |
| 60 | OR of these two sets of flags or masks. That is, if a flag or mask is set in either ␊ |
| 61 | environment, it will be set in fexcept_t when the state is read. Likewise, setting ␊ |
| 62 | the mask using a fexcep_t will set that mask on both environments. For this reason, ␊ |
| 63 | changing the value of the MXCSR state or floating point control/status word state on ␊ |
| 64 | your own will make the results of the functions declared in this header undefined. ␊ |
| 65 | See below for details about how and when. Exception: you may change the FZ, DAZ, DE ␊ |
| 66 | and DM bits in the MXCSR independent of this interface and retain defined behavior, ␊ |
| 67 | so long as you do not change the other bits. It is suggested that developers who wish ␊ |
| 68 | this level of control access the bits in the fenv_t directly. They are direct copies ␊ |
| 69 | of the hardware special purpose registers of similar name. Please consult appropriate ␊ |
| 70 | Intel documentation for the processor about the meaning of various bits in each register. ␊ |
| 71 | ␊ |
| 72 | The file <fenv.h> declares many functions in support of numerical␊ |
| 73 | programming. Programs that test flags or run under␊ |
| 74 | non-default modes must do so under the effect of an enabling␊ |
| 75 | "fenv_access" pragma.␊ |
| 76 | */␊ |
| 77 | ␊ |
| 78 | /********************************************************************************␊ |
| 79 | * *␊ |
| 80 | * fenv_t is a type for representing the entire floating-point *␊ |
| 81 | * environment in a single object. *␊ |
| 82 | * *␊ |
| 83 | * fexcept_t is a type for representing the floating-point *␊ |
| 84 | * exception flag state collectively. *␊ |
| 85 | * *␊ |
| 86 | ********************************************************************************/␊ |
| 87 | typedef struct {␊ |
| 88 | unsigned short __control; /* A direct copy of the floaing point control word */␊ |
| 89 | unsigned short __status; /* A direct copy of the floaing point status word */␊ |
| 90 | unsigned int __mxcsr; /* A direct copy of the MXCSR */␊ |
| 91 | char __reserved[8]; /* Reserved for future expansion. */ ␊ |
| 92 | } fenv_t;␊ |
| 93 | ␊ |
| 94 | typedef unsigned short fexcept_t;␊ |
| 95 | ␊ |
| 96 | /* Definitions of floating-point exception macros */␊ |
| 97 | #define FE_INEXACT 0x0020␊ |
| 98 | #define FE_UNDERFLOW 0x0010␊ |
| 99 | #define FE_OVERFLOW 0x0008␊ |
| 100 | #define FE_DIVBYZERO 0x0004␊ |
| 101 | #define FE_INVALID 0x0001␊ |
| 102 | #define FE_ALL_EXCEPT 0x003D␊ |
| 103 | ␊ |
| 104 | /* Definitions of rounding direction macros */␊ |
| 105 | #define FE_TONEAREST 0x0000␊ |
| 106 | #define FE_DOWNWARD 0x0400␊ |
| 107 | #define FE_UPWARD 0x0800␊ |
| 108 | #define FE_TOWARDZERO 0x0C00␊ |
| 109 | ␊ |
| 110 | /* default environment object */␊ |
| 111 | extern const fenv_t _FE_DFL_ENV;␊ |
| 112 | #define FE_DFL_ENV &_FE_DFL_ENV /* pointer to default environment */␊ |
| 113 | ␊ |
| 114 | /*******************************************************************************␊ |
| 115 | * A environment object that sets to defualt settings and in addition sets the *␊ |
| 116 | * FZ and DAZ bits in the MXCSR, which causes flush-to-zero behavior of *␊ |
| 117 | * denormals. When using this environment, denormals encountered by XMM based *␊ |
| 118 | * calculation (which normally should be all single and double precision scalar *␊ |
| 119 | * floating point calculations, and all SSE/SSE2/SSE3 computation) will be *␊ |
| 120 | * treated as zero. Calculation results that are denormals will also be *␊ |
| 121 | * truncated to zero. This calculation mode is not IEEE-754 compliant, but may *␊ |
| 122 | * prevent lengthy stalls that occur in code that encounters denormals. It is *␊ |
| 123 | * suggested that you do not use this mode unless you have established that *␊ |
| 124 | * denormals are causing trouble for your code. Please use wisely. *␊ |
| 125 | * *␊ |
| 126 | * CAUTION: The math library currently is not architected to do the right *␊ |
| 127 | * thing in the face of DAZ + FZ mode. For example, ceil( +denormal) returns *␊ |
| 128 | * +denormal rather than 1.0 in some versions of MacOS X. In some circumstances *␊ |
| 129 | * this may lead to unexpected application behavior. Use at your own risk. *␊ |
| 130 | * *␊ |
| 131 | * It is not possible to disable denorm stalls on calculation using the x87 FPU.*␊ |
| 132 | *******************************************************************************/␊ |
| 133 | extern const fenv_t _FE_DFL_DISABLE_SSE_DENORMS_ENV;␊ |
| 134 | #define FE_DFL_DISABLE_SSE_DENORMS_ENV &_FE_DFL_DISABLE_SSE_DENORMS_ENV␊ |
| 135 | ␊ |
| 136 | /*******************************************************************************␊ |
| 137 | * The following functions provide high level access to the exception flags.* ␊ |
| 138 | * The "int" input argument can be constructed by bitwise ORs of the *␊ |
| 139 | * exception macros: for example: FE_OVERFLOW | FE_INEXACT. *␊ |
| 140 | *******************************************************************************/␊ |
| 141 | ␊ |
| 142 | /*******************************************************************************␊ |
| 143 | * The function "feclearexcept" clears the supported floating point *␊ |
| 144 | * exceptions represented by its argument. *␊ |
| 145 | *******************************************************************************/␊ |
| 146 | ␊ |
| 147 | extern int feclearexcept(int /*excepts*/);␊ |
| 148 | ␊ |
| 149 | ␊ |
| 150 | /*******************************************************************************␊ |
| 151 | * The function "fegetexceptflag" stores a implementation-defined *␊ |
| 152 | * representation of the states of the floating-point status flags indicated *␊ |
| 153 | * by its integer argument excepts in the object pointed to by the argument, * ␊ |
| 154 | * flagp. *␊ |
| 155 | *******************************************************************************/␊ |
| 156 | ␊ |
| 157 | extern int fegetexceptflag(fexcept_t * /*flagp*/, int /*excepts*/);␊ |
| 158 | ␊ |
| 159 | ␊ |
| 160 | /*******************************************************************************␊ |
| 161 | * The function "feraiseexcept" raises the supported floating-point *␊ |
| 162 | * exceptions represented by its argument. The order in which these *␊ |
| 163 | * floating-point exceptions are raised is unspecified. *␊ |
| 164 | *******************************************************************************/␊ |
| 165 | ␊ |
| 166 | extern int feraiseexcept(int /*excepts*/);␊ |
| 167 | ␊ |
| 168 | ␊ |
| 169 | /*******************************************************************************␊ |
| 170 | * The function "fesetexceptflag" sets or clears the floating point status *␊ |
| 171 | * flags indicated by the argument excepts to the states stored in the *␊ |
| 172 | * object pointed to by flagp. The value of the *flagp shall have been set *␊ |
| 173 | * by a previous call to fegetexceptflag whose second argument represented *␊ |
| 174 | * at least those floating-point exceptions represented by the argument *␊ |
| 175 | * excepts. This function does not raise floating-point exceptions; it just *␊ |
| 176 | * sets the state of the flags. *␊ |
| 177 | *******************************************************************************/␊ |
| 178 | ␊ |
| 179 | extern int fesetexceptflag(const fexcept_t * /*flagp*/, int /*excepts*/);␊ |
| 180 | ␊ |
| 181 | ␊ |
| 182 | /*******************************************************************************␊ |
| 183 | * The function "fetestexcept" determines which of the specified subset of *␊ |
| 184 | * the floating-point exception flags are currently set. The excepts *␊ |
| 185 | * argument specifies the floating-point status flags to be queried. This *␊ |
| 186 | * function returns the value of the bitwise OR of the floating-point *␊ |
| 187 | * exception macros corresponding to the currently set floating-point *␊ |
| 188 | * exceptions included in excepts. *␊ |
| 189 | * *␊ |
| 190 | * On MacOS X for Intel, the result is the value of union of the *␊ |
| 191 | * corresponding result from the x87 and SSE floating point states. *␊ |
| 192 | *******************************************************************************/␊ |
| 193 | ␊ |
| 194 | extern int fetestexcept(int /*excepts*/);␊ |
| 195 | ␊ |
| 196 | ␊ |
| 197 | /*******************************************************************************␊ |
| 198 | * The following functions provide control of rounding direction modes. *␊ |
| 199 | *******************************************************************************/␊ |
| 200 | ␊ |
| 201 | /*******************************************************************************␊ |
| 202 | * The function "fegetround" returns the value of the rounding direction *␊ |
| 203 | * macro which represents the current rounding direction, or a negative *␊ |
| 204 | * if there is no such rounding direction macro or the current rounding *␊ |
| 205 | * direction is not determinable. *␊ |
| 206 | *******************************************************************************/␊ |
| 207 | ␊ |
| 208 | extern int fegetround(void);␊ |
| 209 | ␊ |
| 210 | ␊ |
| 211 | /*******************************************************************************␊ |
| 212 | * The function "fesetround" establishes the rounding direction represented *␊ |
| 213 | * by its argument "round". If the argument is not equal to the value of a *␊ |
| 214 | * rounding direction macro, the rounding direction is not changed. It *␊ |
| 215 | * returns zero if and only if the argument is equal to a rounding *␊ |
| 216 | * direction macro. *␊ |
| 217 | *******************************************************************************/␊ |
| 218 | ␊ |
| 219 | extern int fesetround(int /*round*/);␊ |
| 220 | ␊ |
| 221 | ␊ |
| 222 | /*******************************************************************************␊ |
| 223 | * The following functions manage the floating-point environment, exception *␊ |
| 224 | * flags and dynamic modes, as one entity. *␊ |
| 225 | *******************************************************************************/␊ |
| 226 | ␊ |
| 227 | /*******************************************************************************␊ |
| 228 | * The fegetenv function stores the current floating-point enviornment in *␊ |
| 229 | * the object pointed to by envp. *␊ |
| 230 | *******************************************************************************/␊ |
| 231 | extern int fegetenv(fenv_t * /*envp*/);␊ |
| 232 | ␊ |
| 233 | /*******************************************************************************␊ |
| 234 | * The feholdexcept function saves the current floating-point environment in *␊ |
| 235 | * the object pointed to by envp, clears the floating-point status flags, *␊ |
| 236 | * and then installs a non-stop (continue on floating-point exceptions) *␊ |
| 237 | * mode, if available, for all floating-point exceptions. The feholdexcept *␊ |
| 238 | * function returns zero if and only if non-stop floating-point exceptions *␊ |
| 239 | * handling was successfully installed. *␊ |
| 240 | *******************************************************************************/␊ |
| 241 | extern int feholdexcept(fenv_t * /*envp*/);␊ |
| 242 | ␊ |
| 243 | /*******************************************************************************␊ |
| 244 | * The fesetnv function establishes the floating-point environment *␊ |
| 245 | * represented by the object pointed to by envp. The argument envp shall *␊ |
| 246 | * point to an object set by a call to fegetenv or feholdexcept, or equal to *␊ |
| 247 | * a floating-point environment macro -- we define only *FE_DFL_ENV and *␊ |
| 248 | * FE_DISABLE_SSE_DENORMS_ENV -- to be C99 standard compliant and portable *␊ |
| 249 | * to other architectures. Note that fesetnv merely installs the state of *␊ |
| 250 | * the floating-point status flags represented through its argument, and *␊ |
| 251 | * does not raise these floating-point exceptions. *␊ |
| 252 | * *␊ |
| 253 | * On MacOS X for Intel you may test and set the bits in *envp yourself, *␊ |
| 254 | * provided that you conditionalize the code appropriately to preserve *␊ |
| 255 | * portability and you follow the various strictures and suggestions *␊ |
| 256 | * provided by Intel in appropriate processor documentation. Please be aware *␊ |
| 257 | * that because there are two hardware locations for setting and reading *␊ |
| 258 | * floating point environment, this function (and others like it) are not *␊ |
| 259 | * atomic -- that is, for a brief period of time during the function call *␊ |
| 260 | * your new environment will have been applied to one but not both of the *␊ |
| 261 | * floating point engines (x87 and SSE). In addition, the behavior of some *␊ |
| 262 | * higher level interfaces (fegetround) is undefined if the x87 and SSE *␊ |
| 263 | * floating point units rounding modes are configured differently. Please *␊ |
| 264 | * use common sense. *␊ |
| 265 | *******************************************************************************/␊ |
| 266 | extern int fesetenv(const fenv_t * /*envp*/);␊ |
| 267 | ␊ |
| 268 | /*******************************************************************************␊ |
| 269 | * The feupdateenv function saves the currently raised floating-point *␊ |
| 270 | * exceptions in its automatic storage, installs the floating-point *␊ |
| 271 | * environment represented by the object pointed to by envp, and then raises *␊ |
| 272 | * the saved floating-point exceptions. The argument envp shall point to an *␊ |
| 273 | * object set by a call to feholdexcept or fegetenv or equal a *␊ |
| 274 | * floating-point environment macro. *␊ |
| 275 | * *␊ |
| 276 | * Please see the description of feholdexcept for additional ways to create *␊ |
| 277 | * a fenv_t object, which are valid only for MacOS X for Intel. *␊ |
| 278 | *******************************************************************************/␊ |
| 279 | extern int feupdateenv(const fenv_t * /*envp*/);␊ |
| 280 | ␊ |
| 281 | ␊ |
| 282 | #ifdef __cplusplus␊ |
| 283 | }␊ |
| 284 | #endif␊ |
| 285 | ␊ |
| 286 | #endif /* __FENV__ */␊ |
| 287 | ␊ |
| 288 | |
