*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> ieee (3)              



NAME    [Toc]    [Back]

       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

SYNOPSIS    [Toc]    [Back]

       #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    [Toc]    [Back]

       Standard C Library (libc.so, libc.a)

PARAMETERS    [Toc]    [Back]

       Software   IEEE  floating-point  control.   Hardware  IEEE
       floating-point control register.

DESCRIPTION    [Toc]    [Back]

       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 different method is  required  to  enable  it.
       Assembly  language  programmers  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  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 emulator. Using sui
       floating-point  instructions  or  the   -ieee_with_inexact
       option  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   associated
       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

       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 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 calling
       ieee_set_fp_control().  To  allow  manipulation  of  these
       options,   the   following   constants   are   defined  in

       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

       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

       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 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 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 option 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 options 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
       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
       SIG_IGN           set           safe      Supply  default
                                                 IEEE     result
                                                 value  and continue
 at  trigger
 PC + 4.
       SIG_DFL           set           safe      Cause      core
       user handler      clear         invalid   Deliver  SIGFPE
                                                 to   user  program.

       user handler      clear         safe      Supply  default
                                                 IEEE     result
                                                 value and  continue
  at trigger
 PC + 4.
       user handler      set           invalid   Deliver  SIGFPE
                                                 to   user  program,
  trap  PC
                                                 ==  trigger PC,
                                                 and         set
       user handler      set           safe      Deliver  SIGFPE   to
                                                 user   program   and
                                                 trap PC  !=  trigger

       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

       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 floatingpoint
  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  thirdparty
  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    [Toc]    [Back]

       /usr/include/excpt.h -- include file
       /usr/include/signal.h -- include file
       /usr/include/machine/fpu.h -- include file

SEE ALSO    [Toc]    [Back]

       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.

[ Back ]
 Similar pages
Name OS Title
frexp IRIX manipulate parts of floating-point numbers (libc routines)
catch IRIX Evaluate script and trap exceptional returns
snmp_traprcv Tru64 A program that listens for SNMP trap messages and prints any it receives
__exc_last_chance Tru64 support routines for unhandled exceptions
exc_set_last_chance_handler Tru64 support routines for unhandled exceptions
set_unhandled_exception Tru64 support routines for unhandled exceptions
exc_add_gp_range Tru64 routines to support mapping program counters to the data structures defined at run time
exc_add_pc_range Tru64 routines to support mapping program counters to the data structures defined at run time
exc_remote_lookup_function_entry Tru64 routines to support mapping program counters to the data structures defined at run time
exc_lookup_function_table Tru64 routines to support mapping program counters to the data structures defined at run time
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service