ieee(3) Library Functions Manual ieee(3)
NAME
ieee, ieee_set_fp_control, ieee_get_fp_control, ieee_set_state_at_signal, 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 Binary 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 invalid 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 stan-
dard, C language programmers should use the -ieee flag to the cc command. Assembly language programmers should use the su suffix on float-
ing-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 different method is required to enable it. Assembly language program-
mers can access the inexact result feature by using the sui suffix on floating-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 implemen-
tations the inexact result feature is implemented by trapping to a software emulator. Using sui floating-point instructions or the
-ieee_with_inexact flag might cause a significant drop in performance on such implementations. 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 associ-
ated flags in the software IEEE floating-point control register (fp_control) that control trap delivery. And, in a similar way, a user
program can request 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:
------------------------------------------------------
Constant Meaning
------------------------------------------------------
IEEE_TRAP_ENABLE_INV Invalid operation
IEEE_TRAP_ENABLE_DZE Divide by 0
IEEE_TRAP_ENABLE_OVF Overflow
IEEE_TRAP_ENABLE_UNF Underflow
IEEE_TRAP_ENABLE_INE Inexact
IEEE_TRAP_ENABLE_DNO denormal operand
IEEE_TRAP_ENABLE_MASK mask of all the trap enables
IEEE_MAP_DMZ map denormal inputs to zero
IEEE_MAP_UMZ map underflow results to zero
------------------------------------------------------
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 occur-
rences 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 following constants are defined in machine/fpu.h:
------------------------------------------------
Constant Meaning
------------------------------------------------
IEEE_STATUS_INV Invalid operation
IEEE_STATUS_DZE Divide by 0
IEEE_STATUS_OVF Overflow
IEEE_STATUS_UNF Underflow
IEEE_STATUS_INE Inexact
IEEE_STATUS_DNO denormal operand
IEEE_STATUS_MASK mask of all the status flags
------------------------------------------------
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 current 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
sigreturn(2), the sc_fp_control includes the current set of trap flags.
The IEEE standard specifies default result values (including denormalized numbers, NaNs, and infinities) for operations that cause traps
that are not user-enabled. An operating system trap handler must "complete" 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. Because Compaq 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 actu-
ally 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 instructions 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 creating 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 handler 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 determined, the operating system can then decide what to do when an
exception 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:
------------------------------------------------------------------------
SIGFPE Trap enable Shadow Actions
------------------------------------------------------------------------
SIG_IGN clear invalid Continue at trap PC + 4.
SIG_DFL clear invalid Cause core dump.
SIG_IGN|SIG_DFL clear safe Supply default IEEE result
value and continue at trigger
PC + 4.
SIG_IGN set invalid Continue at trap PC + 4.
SIG_DFL set invalid Cause core dump.
SIG_IGN set safe Supply default IEEE result
value and continue at trigger
PC + 4.
SIG_DFL set safe Cause core dump.
user handler clear invalid Deliver SIGFPE to user pro-
gram.
user handler clear safe Supply default IEEE result
value and continue at trigger
PC + 4.
user handler set invalid Deliver SIGFPE to user pro-
gram, trap PC == trigger PC,
and set ieee_invalid_shadow.
user handler set safe Deliver SIGFPE to user pro-
gram and trap PC != trigger
PC.
------------------------------------------------------------------------
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 determine which traps were enabled at the time of the exception.
On precise floating faults (in which the system trap handler has indicated 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
reported 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 exception 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 register 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). Another way to continue from a precise fault is to modify the input
registers 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, sigcontext
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 exception, 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 enables 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 returns, the original floating-point context is restored.
A user program can retrieve the current exception state reporting behavior 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 behavior.
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), sigreturn(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)