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

fp_controlSoftware IEEE floating-point control. 

fpcrHardware 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 can incur any of the following five 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 are capable of causing invalid operation, division by zero, and overflow traps; this default cannot be overridden.  To generate floating-point code capable of causing overflow, underflow, or inexact result traps, you must specify −ieee_with_inexact, −ieee_with_no_inexact, or an appropriate floating-point trapping mode option  when compiling the C language source (see cc(1) for details), or use the appropriate instruction operators when writing assembly language code. 

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 types of trap 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. 

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:

The fp_control also contains five 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.  machine/fpu.h defines the following constants to allow manipulation of these 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 set.  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 parents 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 have been generated as resumption safe and software completion must have been specified in the trapping mode. 

The concept of resumption-safe code warrants further explanation.  Because AXP 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).  There may have been several intervening instructions, which 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 −resumption_safe flag on the command line. 

In order 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 in order 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:

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 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 a copy of the trigger instruction. 

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:  ieee_functions(3), exec(2), setjmp(3), sigreturn(2), longjmp(3), write_rnd(3). 

Files: signal(4), excpt(4), c_excpt(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.