ieee(3)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
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( );
LIBRARY
Standard C Library (libc.so, libc.a)
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 standard,
C language programmers should use the -ieee option 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 option to the cc command
with the -ieee_with_inexact option. 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
option might cause a significant drop in performance on such implemen‐
tations. 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 deliv‐
ery 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 options 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 oper‐
ands 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 options which, when set, indicate one or more
occurrences of individual floating-point exception conditions. These
options remain set until a user program explicitly clears them by call‐
ing ieee_set_fp_control(). To allow manipulation of these options, 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 options
──────────────────────────────────────────────────
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 options 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 options.
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.
Because HP Alpha systems incorporate pipelining and multi-instruction
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
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 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 option 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
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 options in fp_control Whether the user
program has been created as resumption safe code Whether the user pro‐
gram has specified a handler for SIGFPE, has decided to ignore the sig‐
nal (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 con‐
tinue at trig‐
ger 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 con‐
tinue at trig‐
ger 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 con‐
tinue at trig‐
ger 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 program 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 deter‐
mine 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
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 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).
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, 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
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
SEE ALSO
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.
ieee(3)