These routines allow decimal floating point control, influencing decimal floating point arithmetic. The decimal floating point arithmetic unit (either decNumber or POWER6 processor) indicates exceptions conditions (overflow, underflow, divide by zero, invalid operation, inexact) by setting relevant status bits in the status field. The IEEE 754r (draft) standard requires following five exceptions, invalid operation, overflow, underflow, divide by zero, and inexact. For details about when these exception conditions arise refer to General Decimal Arithmetic Specification.
The following guidelines shall be observed with DFPAL.
- Never use operating system or decNumber exception, trap and rounding mode definitions, i.e. do not use decNumber defines such as
DEC_Overflow, DEC_Underflow, and operating system defines such as FP_OVERFLOW, FP_UNDERFLOW etc. (defined in fpxcp.h).
- Only use definitions and facility provides by the DFPAL. All DFPAL definitions are prefixed with
"DFPAL_". For example, DFPAL_FP_OVERFLOW and DFPAL_FP_UNDERFLOW. DFPAL definition values are dynamic, changed at runtime depending on whether DFPAL is operating in hardware or software.
- Never check output of any of the routines for boolean value. Perform bitwise and operation to determine particular status bit(s).
- POWER6 processor Floating Point Status and Control Register (FPSCR) holds status and control information. The FPSCR exception and trap bits are shared between binary floating point and the decimal floating point (rounding mode control in not shared between binary floating point and decimal floating point, however). This may result into cross-contamination, i.e. overflow caused by the binary floating point arithmetic operation will show up in the decimal floating status and vice versa. This can be avoided by carefully clearing and checking status before and after particular arithmetic operation or set of operations.
- Applications shall not call any decNumber functions directly.
- Unless it is a condition raised as a result of arithmetic operation or altered via following API, DFPAL never sets or clears status or control flags. The IEEE 754r (draft) standard requires that it is application’s responsibility to manage exceptions status flags.
- DFPAL floating point control routines are similar to AIX floating point control routines (
fp_clr_flag(), fp_set_flag(), fp_read_flag(), fp_swap_flag() and so on). This will allow easy code migration to compiler native decimal floating point usage.
Exception status flag management
The following routines allow accessing and altering decimal floating point exception status value. DFPAL provides the following exception status flags. An application must use following defines to access the exception flags. For details about when the exceptions are raised refer to General Decimal Arithmetic Specification.
- DFPAL_FP_INVALID
- DFPAL_FP_OVERFLOW
- DFPAL_FP_UNDERFLOW
- DFPAL_FP_DIV_BY_ZERO
- DFPAL_FP_INEXACT
- DFPAL_FP_ALL
void dfpalClearStatusFlag(dfpalflag_t mask)
Clear exception status flags specified by the mask parameter. A bit value of 1 in mask will clear that particular exception status flag. The exception status flags can be bitwise or’ed together indicating multiple status flag to be cleared. The exception status flag remains unchanged if the corresponding bit value is 0 in the mask.
void dfpalClearAllStatusFlag()
Clear all exception status flags. This function is equivalent to, but relatively faster than dfpalClearStatusFlag() function with DFPAL_FP_ALL argument.
void dfpalSetStatusFlag(dfpalflag_t mask)
Set exception status flags specified by the mask parameter. Bit value of 1 in the mask will set that flag, value of 0 will clear the flag.
dfpalflag_t dfpalReadStatusFlag(void)
Read current exception status flags. Return value of the function can be used in bitwise and operation to check presence of particular exception status.
dfpalflag_t dfpalSwapStatusFlag(dfpalflag_t mask)
This is combination of the dfpalSetStatusFlag() and the dfpalReadStatusFlag(). Read and return current exception status flags, set exception status flags specified by the mask parameter.
Exception trap management
The following routines allow accessing and altering decimal floating point trap control. DFPAL provides the following trap control flags. An application must use following defines to access the trap control flags. SIGFPE is raised when trap is enabled for that particular exception.
- DFPAL_TRP_INVALID
- DFPAL_TRP_OVERFLOW
- DFPAL_TRP_UNDERFLOW
- DFPAL_TRP_DIV_BY_ZERO
- DFPAL_TRP_INEXACT
- DFPAL_TRP_ALL
void dfpalEnableTrap(dfpaltrap_t mask)
Enable floating point trap for exception(s) specified by the mask parameter. Bit value of 1 will turn on trap for that particular exception. The traps can be bitwise or’ed together to indicate multiple traps to be enabled.
void dfpalEnableAllTrap(void)
Enable all five floating point exception traps.
void dfpalDisableTrap(dfpaltrap_t mask)
Disable floating point trap for exception(s) specified by the mask parameter. Bit value of 1 will turn off trap for that particular exception. The traps can be bitwise or’ed together to indicate multiple traps to be disabled.
void dfpalDisableAllTrap(void)
Disable all five floating point exception traps.
uint8_t dfpalAnyTrapEnabled(void)
Returns boolean value 1 if any trap is enabled, 0 otherwise.
uint8_t dfpalTrapEnabled(dfpaltrap_t mask)
Returns boolean value 1 if any of the trap(s) specified by the mask parameter is enabled, 0 otherwise.
Rounding mode control
The following routines allow controlling and accessing decimal floating point rounding mode. DFPAL provides the following rounding mode definitions. An application must use following defines to access the exception flags. For details about how rounding mode influence decimal floating point arithmetic refer to General Decimal Arithmetic.
- DFPAL_ROUND_TO_NEAREST_WITH_TIES_TO_EVEN
- DFPAL_ROUND_TOWARD_ZERO
- DFPAL_ROUND_TOWARD_POSITIVE_INFINITY
- DFPAL_ROUND_TOWARD_NEGATIVE_INFINITY
- DFPAL_ROUND_TO_NEAREST_WITH_TIES_AWAY_FROM_ZERO
- DFPAL_ROUND_TO_NEAREST_WITH_TIES_TOWARD_ZERO
- DFPAL_ROUND_AWAY_FROM_ZERO
dfpalrnd_t dfpalReadRoundingMode(void)
Return current rounding mode.
dfpalrnd_t dfpalSwapRoundingMode(dfpalrnd_t rndmode)
Return current rounding mode and set rounding mode specified by the rndmode parameter.
void dfpalSetRoundingMode(dfpalrnd_t rndmode)
Set rounding mode specified by the rndmode parameter.
uint8_t dfpalSetExponentClamp(uint8_t) [deprecated]
Set exponent clamp for decNumber context. Do not use this function.
[previous | contents | next]
DFPAL is authored by Punit Shah (punit@us.ibm.com).
Please send any corrections, comments or questions to dfpal-l@austin.ibm.com.
| This page was updated on 21 Dec 2007. |