*** UNIX MANUAL PAGE BROWSER ***

ieee(3) Library Functions Manual ieee(3) NAME ieee, ieee_set_fp_control, ieee_get_fp_control, ieee_set_state_at_sig- nal, ieee_get_state_at_signal, ieee_ignore_state_at_signal - libc ieee trap enable support routines. LIBRARY Standard C Library (libc.so, libc.a) SYNOPSIS #include <machine/fpu.h> void ieee_set_fp_control( unsigned long fp_control); unsigned long ieee_get_fp_control(); void ieee_set_state_at_signal( unsigned long fp_control, unsigned long fpcr); int ieee_get_state_at_signal( unsigned long *fp_control, unsigned long *fpcr); void ieee_ignore_state_at_signal(); PARAMETERS Software IEEE floating-point control. Hardware IEEE floating-point control register. DESCRIPTION These routines support the implementation of the IEEE Standard for Bi- nary Floating-Point Arithmetic. IEEE-format floating-point operations are subject to the following traps: Invalid operation Division by zero Overflow Underflow Inexact result (Note that floating-point-to-integer conversion operations may generate an integer overflow trap, which the operating system traps and delivers as an invalid operation.) By default, floating-point operations generate imprecise traps for in- valid operation, division by zero, and overflow errors. To cause floating-point errors to be handled with precise exception faults, or with the signal handling specified in the IEEE floating-point standard, C language programmers should use the -ieee flag to the cc command. Assembly language programmers should use the su suffix on floating- point instruction opcodes and follow the software completion rules of the Alpha architecture. These methods allow you to access all features of the IEEE standard except the inexact result feature. The inexact result feature can sometimes degrade performance, so a dif- ferent method is required to enable it. Assembly language programmers can access the inexact result feature by using the sui suffix on float- ing-point instruction opcodes. C language programmers can access the inexact result feature by replacing the -ieee flag to the cc command with the -ieee_with_inexact flag. On some Alpha implementations the inexact result feature is implemented by trapping to a software emula- tor. Using sui floating-point instructions or the -ieee_with_inexact flag might cause a significant drop in performance on such implementa- tions. Because of this, you should use the inexact result feature only in those few program statements where inexact signaling is needed. When your code is compiled with ieee or ieee_with_inexact, the delivery of all floating-point traps to a user program is disabled by default. A user program can request the delivery of any of the five standard IEEE traps by calling ieee_set_fp_control to set the associated flags in the software IEEE floating-point control register (fp_control) that control trap delivery. And, in a similar way, a user program can re- quest delivery of an invalid operation trap whenever a denormalized operand is used. When the IEEE gradual underflow capability (that is, denormalized operands and results) is not desired, it can be disabled by specifying one or both of the options to map denormalized input operands to zero or to flush underflowing results to zero. The following constants are defined in machine/fpu.h and can be used to construct an appropriate set mask in the fp_control argument to an ieee_set_fp_control call: tab(@); lfHB lfHB ll. _ Constant@Meaning _ IEEE_TRAP_ENABLE_INV@T{ Invalid operation T} IEEE_TRAP_ENABLE_DZE@T{ Divide by 0 T} IEEE_TRAP_ENABLE_OVF@T{ Overflow T} IEEE_TRAP_ENABLE_UNF@T{ Underflow T} IEEE_TRAP_ENABLE_INE@T{ Inexact T} IEEE_TRAP_ENABLE_DNO@T{ denormal operand T} IEEE_TRAP_ENABLE_MASK@T{ mask of all the trap enables T} IEEE_MAP_DMZ@T{ map denormal inputs to zero T} IEEE_MAP_UMZ@T{ map underflow results to zero T} _ The fp_control, which can be read by means of ieee_get_fp_control, also contains status flags which, when set, indicate one or more occurrences of individual floating-point exception conditions. These flags remain set until a user program explicitly clears them by calling ieee_set_fp_control. To allow manipulation of these flags, the follow- ing constants are defined in machine/fpu.h: tab(@); lfHB lfHB ll. _ Constant@Meaning _ IEEE_STATUS_INV@T{ Invalid operation T} IEEE_STATUS_DZE@T{ Divide by 0 T} IEEE_STATUS_OVF@T{ Overflow T} IEEE_STATUS_UNF@T{ Underflow T} IEEE_STATUS_INE@T{ Inexact T} IEEE_STATUS_DNO@T{ denormal operand T} IEEE_STATUS_MASK@T{ mask of all the status flags T} _ At thread creation (and process creation as a result of an exec(2) call), the delivery of all-floating point traps is disabled and all floating-point exception status flags in the fp_control are clear. If the thread creating the new process has set the inherit bit in its fp_control (by specifying the constant IEEE_INHERIT in the fp_control mask to an ieee_set_fp_control call), the newly-created process will inherit its creator's fpcr and fp_control settings. At a fork(2) call, the child process always inherits its parent's fp_control and fpcr settings, regardless of the setting of the inherit bit. Users should be careful to remember that setting the bits in the fp_control, like setting signal handlers, will affect other code within their thread. A user program calls ieee_get_fp_control to obtain a copy of the cur- rent fp_control. Additionally, the jmp_buf argument for setjmp(3), which uses struct sigcontext from signal(4) as an overlay, provides an sc_fp_control field. When a user program issues a longjmp(3) or sigre- turn(2), the sc_fp_control includes the current set of trap flags. The IEEE standard specifies default result values (including denormal- ized numbers, NaNs, and infinities) for operations that cause traps that are not user-enabled. An operating system trap handler must "com- plete" these operations by supplying the default IEEE result. For the operating system to properly fix the results of these operations, the code must be generated as resumption safe and software completion must be specified in the trapping mode. The concept of resumption-safe code warrants further explanation. Be- cause DIGITAL Alpha systems incorporate pipelining and multi-instruc- tion issue techniques, when an arithmetic exception occurs, the program counter may not contain the address of the instruction that actually caused the trap (referred to as the trigger PC). It may instead contain the address of the instruction that was executing at the time the trap was executed (referred to as the trap PC). Several intervening in- structions may have been present and could have changed the machine state from what it was at the time of the exception. The instructions between the trigger PC and the trap PC are called the trap shadow. The Alpha Architecture Reference Manual specifies conventions for cre- ating the trap shadow so that the operating system trap handler can provide an IEEE result value for an operation and continue execution. The architecture provides a way for software to mark instructions which abide by the conventions and a user may request this of the compiler driver (cc(1)) by specifying the -ieee flag on the command line. To determine which exception occurred, the operating system trap han- dler must back up instructions and look for the trigger PC. Once it finds the trigger PC, the software may need to re-execute or emulate the trigger instruction to determine which trap it actually caused. Once the validity of the trap shadow and the trigger exception is de- termined, the operating system can then decide what to do when an ex- ception occurs, depending on three factors: Whether the user program has set any of the trap-enable flags in fp_control Whether the user program has been created as resumption safe code Whether the user program has specified a handler for SIGFPE, has decided to ignore the signal (SIG_IGN), or has accepted the signal's default treatment (SIG_DFL) The following table describes the system's actions based on these three factors: tab(@); lfHB lfHB lfHB lfHB llll. _ SIGFPE@Trap enable@Shadow@Actions _ SIG_IGN@clear@invalid@T{ Continue at trap PC + 4. T} SIG_DFL@clear@invalid@T{ Cause core dump. T} SIG_IGN|SIG_DFL@clear@safe@T{ Supply default IEEE result value and con- tinue at trigger PC + 4. T} SIG_IGN@set@invalid@T{ Continue at trap PC + 4. T} SIG_DFL@set@invalid@T{ Cause core dump. T} SIG_IGN@set@safe@T{ Supply default IEEE result value and continue at trigger PC + 4. T} SIG_DFL@set@safe@T{ Cause core dump. T} user handler@clear@invalid@T{ Deliver SIGFPE to user program. T} user handler@clear@safe@T{ Supply default IEEE result value and con- tinue at trigger PC + 4. T} user handler@set@invalid@T{ Deliver SIGFPE to user program, trap PC == trigger PC, and set ieee_invalid_shadow. T} user handler@set@safe@T{ Deliver SIGFPE to user program and trap PC != trigger PC. T} _ See signal(4) for additional information on default actions for SIGFPE. A SIGFPE handler can also obtain additional information about floating- point exceptions from the sigcontext. The sigcontext contains a copy of the current fp_control in sc_fp_control, allowing a handler to de- termine which traps were enabled at the time of the exception. On precise floating faults (in which the system trap handler has indi- cated a valid trap shadow and executed successfully), indicated by codes FPE_xxxxx_FAULT, relevant sigcontext fields contain the following information: sc_traparg_a0 contains the exception summary register re- ported by hardware. sc_traparg_a1 contains the exception register write mask reported by hardware. sc_fp_trap_pc contains the trap PC. sc_pc contains the trigger PC. sc_fp_trigger_sum contains the excep- tion summary register reported by hardware with the SWC bit masked off. sc_fp_trigger_inst is a copy of the trigger instruction. On precise arithmetic faults with valid trap shadows, the result regis- ter of the faulting instruction is loaded with the IEEE floating-point result that would have been generated if the exception had not been signaled. One way to continue from such a fault is to increment sc_pc by 4 and continue with this result (or some modification of it). An- other way to continue from a precise fault is to modify the input reg- isters to the floating operation, leave the sc_pc field unchanged, and then reexecute the faulting instruction with the modified input. On imprecise arithmetic traps (for instance, when an invalid trap shadow has been detected), indicated by codes FPE_xxxxx_TRAP, sigcon- text provides the same information, with the following differences: sc_pc contains the trap PC. sc_fp_trigger_inst is undefined. By default, the exception state at the time of a floating-point excep- tion, as represented by the fp_control and fpcr, is the state provided to a signal handler. The ieee_set_state_at_signal routine allows a user program to specify the values to be placed in the fp_control and the fpcr at the call to a signal handler. This enables the program to easily modify the trap en- ables or rounding modes so that a critical region (for instance, in third-party code executed from a signal handler) is immune from certain exception state. The original settings of the fp_control and the fpcr are saved in the sigcontext prior to the signal. When the handler re- turns, the original floating-point context is restored. A user program can retrieve the current exception state reporting be- havior by calling ieee_get_state_at_signal. The ieee_ignore_state_at_signal routine specifies that floating-point state is not modified when calling a signal handler. A user program calls this routine to restore the default exception state reporting be- havior. FILES usr/include/excpt.h - include file usr/include/signal.h - include file usr/include/machine/fpu.h - include file RELATED INFORMATION Commands: cc(1). Functions: exec(2), ieee_functions(3), longjmp(3), setjmp(3), sigre- turn(2), write_rnd(3). Files: c_excpt(4), excpt(4), signal(4). IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985). Alpha Architecture Reference Manual. Assembly Language Programmer's Guide. Programmer's Guide. delim off ieee(3)