CrashLib Copyright (C) 2002 By Gregory Dietsche.
Version: 1.0b

Description:

How To Use:

Quick Start:

1. Enable exit support. This means removing #define NO_EXIT_SUPPORT from your project.
2. Add crash.h and crash.a to your project.
3. #include "crash.h" after tigcclib.h
4. Choose, or write your own HUD function to use when recovering from a crash.
5. Immediately after variable declarations in your _main function, place this code: AntiCrashProtection(myHUDFunc); where MyHUDFunc is the previously chosen function. An example would be AntiCrashProtection(Crash_Debug_HUD);
6. Write your program :)
7. Before releasing your program, remove crashlib (a well written and debugged program should not need it).

What is a HUD function?

A HUD is an acronym for Heads Up Display. Normally, a HUD's are associated with games, but in this case, it is slightly different. A HUD from the point of view of CrashLib is a simple function that does not return a value which can display information in the event of a crash. All HUD functions should be declared returning void, and the parameter list should either be CRASH_RECOVERY_STATE* state, or void.

The HUD is not limited to just a graphical display. It could be a function that outputs information to the link port, or to a file for debugging. Be creative!

HUD's are run in user mode with an interrupt mask of 0.

Example HUD function prototypes:

void MyHUD(void);
void MyHUD(CRASH_RECOVERY_STATE *state);

What CrashLib Does:
CrashLib recovers all errors listed in Table 1. It also makes a backup of auto-interrupts 1,2,3,4,5,6 exception vectors, and restores them when the calling program terminates (either normally, or through a crash).

• Entry Points:
  
  
  • #define AntiCrashProtection(HUD)
    • This is the main function of CrashLib. It takes a pointer to a function which will be called in case of an assembly language error.
    • The function pointed to by HUD will normally be prototyped in the following manner: void MyHUDFunc(CRASH_RECOVERY_STATE state);
      
      
  • void InstallExceptionVectors(const short vlist[], const long vnew[], short num);
    • This is a simple function which can install any number of vectors in the exception vector table.
    • vlist is an array of words which contain the address of the vector to be altered.
    • vnew is an array of long words which point to the replacement function or datum of the exception vector.
    • num is the number of entries in each array. Note that each array should have a dimension of at least num elements.
      
      
  • Void BackupExceptionVectors(const short vlist[], long vsaved[], short num);
    • This function makes a backup of selected vectors in the exception vector table.
    • vlist contains the addresses of the vectors to save.
    • vsaved will be filled by this function corresponding with the vectors specified in vlist.
    • num is the number of entries in each array. Note that each array should have a dimension of at least num elements.
      
      
  • Void Crash_File_HUD(CRASH_RECOVERY_STATE *state);
    • This is a built-in function which can be used as a parameter for AntiCrashProtection.
    • All Registers, the USP (user stack pointer), SR (status register) and the type of error encountered are placed in the variable CrashLib with a txt extension in the var-link menu.
    • A Small dialog is displayed informing the user where to find crash data.
      
      
  • Void Crash_Debug_HUD(CRASH_RECOVERY_STATE *state);
    • This is a built-in function which can be used as a parameter for AntiCrashProtection.
    • This function displays detailed information about a crash.
    • All Registers, the USP (user stack pointer), SR (status register) and the type of error encountered are displayed on the LCD.
      
      
  • void Crash_Simple_HUD(void);
    • This is a built-in function which can be used as a parameter for AntiCrashProtection.
    • This function displays a dialog informing the user that a fatal crash has been encountered.
      
      
  • #define Crash_No_HUD
    • This is a null pointer used when no hud will be used by the calling program.
      
      
  • #Define VECT_ADDR(n)
    • a simple macro which return's a pointer to a pointer to a function or datum of vector number n
      
      
  • #define VECT_ADDR_sh(s)
    • A macro used internally to convert VECT_ADDR pointers to the type of short
      
      
  • #define NUM_VECT_REDIR
    • The Number of Exception Handlers installed by CrashLib
      
      
  • #define NUM_VECT_SAVED
    • The total number of vectors that CrashLib saves and restores.
      
      
  • Void atexit_RemoveAntiCrashProtection(void);
    • This is an internal function used by CrashLib.
    • Under normal circumstances, it is not necessary to call this function directly.
    • The AntiCrashProtection macro uses this function to implement crash recovery support.
      
      
• Global Variables
  • extern const char * const gCrashLibText[NUM_VECT_REDIR];
    • Pointers to the error strings used by CrashLib.
    • The crashtype member of the CRASH_RECOVERY_STATE data structure can be used to access the appropriate string.
      
      
  • extern const char * const CrashLibVersion;
    • A global pointer which contains a time/date stamp, and version information regarding CrashLib.
      
      
  • Extern const char * const CrashLibBuildDate;
    • A string constant which returns the date CrashLib was last built on.
      
      
  • Extern const char * const CrashLibBuildTime;
    • A string constant which returns the timeCrashLib was last built.
      
      
• Extern long __gOldVectors[NUM_VECT_SAVED];
  • An internal array used to save the old exception vectors.
  • Under normal circumstances, it is not necessary to access this variable directly.
    
    
• Extern const long __gRedirect[NUM_VECT_REDIR];
  • An internal array which points to the exception vector replacements.
  • Under normal circumstances, it is not necessary to access this variable directly.
    
    
• Extern short __gVectors[NUM_VECT_SAVED];
  • An internal array which contains the addresses of the vectors which are altered by CrashLib.
  • Under normal circumstances, it is not necessary to access this variable directly.
    
    
• Extern void *__gCrashHandler;
  • An internal pointer used by CrashLib to determine what function to call when handling a crash.
  • Under normal circumstances, it is not necessary to access this variable directly.
  • In certain situations, however, it may be beneficial to modify this pointer to change the HUD displayed if an error is encountered.

Data Structures

typedef struct
{
	unsigned long  a7;							/* Registers a0-a7/d0-d7 */
	unsigned long  d0;
	unsigned long  d1;
	unsigned long  d2;
	unsigned long  d3;
	unsigned long  d4;
	unsigned long  d5;
	unsigned long  d6;
	unsigned long  d7;
	unsigned long  a0;
	unsigned long  a1;
	unsigned long  a2;
	unsigned long  a3;
	unsigned long  a4;
	unsigned long  a5;
	unsigned long  a6;
	const unsigned char frametype;		/*see the 'frame' union of this data structure*/
	unsigned char  crashtype;			/* A Number That Corresponds With gCrashLibText */
	
	union {
		
		struct {
			unsigned short sr;			/* STATUS REGISTER */
			unsigned long  pc;			/* PROGRAM COUNTER */
			}type_else;					/* Error Frame Types 1,2,4 */
		
		struct {
			unsigned short flags;		/* only bits 0-4 are used */
			unsigned long  address;		/* ACCESS ADDRESS */
			unsigned short ir;			/* INSTRUCTION REGISTER */
			unsigned short SR;			/* STATUS REGISTER */
			unsigned long  PC;			/* PROGRAM COUNTER */
			}type_zero;					/* Error Frame Type 0 */
			
		}frame;
		
	}CRASH_RECOVERY_STATE;
	

LEGAL INFORMATION

The author makes no representations or warranties about the suitability of the software, either express or implied. The author shall not be liable for any damages suffered as a result of using or distributing this software. Any program that makes uses of routines from this library should explicitly state that fact in the readme.

This library is shareware. I am asking that you, the developer, sign the guest book located at my website as payment instead. The goal of this is to have an easy electronic form of the 'postcard'. Thank you in advance :)

Other Information
This library was compiled using TIGCC version 0.94 SP3.
The most current version of CrashLib and its full source code can be found at: http://calc.gregd.org/download.php?what=crashlib

Library History

04/04/2002 - Initial Beta Release
04/07/2002 - Beta 3 Released
04/08/2002 - Beta 4 Released
04/12/2002 - Beta 5 Released
04/12/2002 - Beta 6 (Release Candidate) Released
04/13/2002 - Beta 7 Small Bug fixes to Beta 6
06/14/2002 - Version 1.0 (its been rotting on my hd for a few months :)
07/17/2002 - Version 1.0a removes handling of Bus Errors -- They can't happen on the current 68k calcs...
01/18/2003 - Version 1.0b some minor code changes to work with the TIGCC version 0.94 series