fixade(3)

NAME
     fixade - misaligned data bus error handler and report generator

SYNOPSIS
     subroutine handle_unaligned_traps

     subroutine list_by_addr

     subroutine summary_listing

     subroutine print_unaligned_summary

DESCRIPTION
     Fixade is a bus error handler which fields, corrects, and reports bus
     errors arising due to misaligned data in Irix programs.  The MIPS
     architecture, for performance reasons, is very restrictive on the
     alignment of data which can be used with its standard instruction set.
     Usually, the compilers can guarantee this alignment, however, some
     situations exist in which this guarantee cannot be made.  These
     misalignments may be necessary to satisfy Fortran equivalence statements,
     due to mismatched formal/actual parameter types, or due to user-
     instructed suppression of common block padding (via use of the -align
     switches, see f77(1)).  Unless the bus error arising due to a load or
     store from a misaligned address is caught, it will cause unexpected
     program failure.

     Routines in the fixade package provide a bus error handler to catch these
     errors, correct them, and allow the program to continue execution.  They
     also provide a reporting facility so that the causes of these errors can
     be located and remedied.

     None of the routines of fixade have arguments.  The routine
     handle_unaligned_traps must be called to initialize the handler.  If a
     misaligned reference is encountered prior to calling this initialization
     routine, the reference will produce a core dump. No other routines of the
     trap handler may be called prior to calling this initialization routine.

     No other routines of the trap handler need to be called unless a report
     of misaligned references is desired.  A report of misaligned references
     consists of two portions:  a summary of the types of misaligned
     instructions, their counts and relative frequency. (e.g., 'half aligned
     load-word occurred fifteen times, and accounted for 2% of all misaligned
     references'); and a listing based either on the instruction addresses at
     which the faults occurred, or the data addresses producing the faults.

     This listing is either an exhaustive listing (default), or a summary
     listing.  The summary listing will list the address (either instruction
     or data, as opted) associated with the fault, and its absolute and
     relative frequency, as a percentage.  The exhaustive listing will list
     all instruction/data address pairs producing a fault.  This listing will
     be sorted by the address on which the listing is based (i.e., by
     instruction address or data address).  By default, the listing is
     exhaustive.  If only a summary of misalignment errors is desired, the
     routine summary_listing must be called immediately after the
     initialization routine.

     Also by default, the listing is based on instruction addresses. If it is
     desired to base the listing on data addresses, the routine list_by_addr
     must be invoked during initialization.

     Prior to program exit, the routine print_unaligned_summary may be called
     to print the listing of bus error events, in either summary or exhaustive
     format, as described previously.  This listing will go to the standard
     output.  A sample line of this listing in summary format might be

          0x0042445c    1536    33%    67%

     where 0x0042445c is the address associated with 1536 faults (33% of the
     total).  The final percentage is cumulative.  Whether the address is of
     the data causing the fault or the instruction at which it occurred is
     indicated in a printed heading.

     New options have been added to f77(1) to generate (much slower) code
     which tolerates misalignments (see f77(1)).  As discussed previously, use
     of these options will suppress the padding of common usually done by the
     fortran compiler to align elements.  They will also generate code which
     uses pessimistic code sequences to avoid bus errors due to misalignment.
     No bus errors due to misaligned data will occur in modules compiled with
     these new options.

     Users desiring to find and repair instances of misaligned data may use
     either instruction addresses to decide which modules need to be specially
     compiled (see f77(1)), or data addresses to find misalignments.  In
     either case, a symbol table listing produced by nm(1), using the -Bgn
     options, will be necessary to map the addresses to routine (or common
     block) names.

NOTES
     Similar functionality is available from the Irix kernel by way of the
     sysmips(2) call.  This, too, handles the unaligned data traps and
     emulates the memory reference in software but does not generate any
     reports at program termination.

     The use of fixade.o is intended for diagnostic purposes only. Program
     efficiency may be severely impacted by its use.  In addition, programs
     using fixade.o may fail to work under future releases of the operating
     system or on future processors.

FILES
     /usr/lib/fixade.o
     /usr/lib32/mips3/fixade.o
     /usr/lib32/mips4/fixade.o
     /usr/lib64/mips3/fixade.o
     /usr/lib64/mips4/fixade.o
AUTHOR
     Larry Weber
     Greg Boyd

SEE ALSO
     f77(1), sysmips(2)

DIAGNOSTICS
     When making an exhaustive listing, the trap handler's tables may
     overflow.  If this occurs, the message

          number events not listed due to insufficient table size.

     will be printed at the end of the listing.