fixade(3)

NAME
     fixade - handles and reports on misaligned data bus errors

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.

     For performance reasons, the MIPS architecture is very restrictive
     about the alignment of data which can be used with its standard
     instruction set.  The compilers can usually guarantee this alignment;
     however, some situations arise 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 (by using of the
     -align options; see the f77(1) man page for details).  If the bus
     error caused by a load or store from a misaligned address is not
     caught, it causes an unexpected program failure.

     Routines in the fixade group provide a bus error handler to catch
     these errors, correct them, and allow the program to continue
     execution.  These routines 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 produces 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 needed.  A report of misaligned
     references consists of two portions:

     * a summary of the types of misaligned instructions, their counts and
       relative frequency. For example:

          half aligned load-word occurred fifteen times, and accounted
          for 2% of all misaligned references

     * a listing based either on the instruction addresses at which the
       faults occurred, or the data addresses producing the faults.

     This listing is either a detailed listing (default), or a summary
     listing.  The summary report lists the address associated with the
     fault (either instruction or data) and its absolute and relative
     frequency, as a percentage.  The detailed report lists all
     instruction/data address pairs producing a fault.  This listing is
     sorted by the address on which the listing is based (for example, by
     instruction address or data address).  By default, the listing is
     detailed.  If  a summary is needed, the summary_listing routine must
     be called immediately after the initialization routine.

     Also by default, the listing is based on instruction addresses.  To
     sort the listing on data addresses, the list_by_addr routine must be
     invoked during initialization.

     Prior to program exit, the print_unaligned_summary routine may be
     called to print the listing of bus error events, in either summary or
     detailed format, as described previously.  This listing goes to the
     standard output.

     A sample line of this listing in summary format follows:

               0x0042445c    1536    33%    67%

     0x0042445c is the address associated with 1536 faults (33% of the
     total).  The final percentage is cumulative.  A printed heading
     indicates if the address is the address of the data causing the fault
     or the instruction at which it occurred.

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

     To find and repair instances of misaligned data, 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, are necessary to map the addresses to routine (or common
     block) names.

NOTES
     Similar functionality is available from the IRIX kernel by using 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 affected by its use.  In addition, programs
     using fixade.o may fail to work under future releases of the operating
     system or on future processors.

     When making a detailed report, the trap handler's tables may overflow.
     If this occurs, the following message is printed at the end of the
     listing:

          number events not listed due to insufficient table size

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

SEE ALSO
     f77(1)
     sysmips(2)