/*
 * except.h
 *
 * [Generated from except, 25 September 1996]
 */

#if !defined(__CC_NORCROFT) || !defined(__arm)
  #error You must use the Norcroft ARM Compiler for Sapphire programs
#endif

#pragma include_only_once
#pragma force_top_level

#ifndef __except_h
#define __except_h

#ifndef __sapphire_h
  #include "sapphire.h"
#endif

/*----- Overview ----------------------------------------------------------*
 *
 * Functions provided:
 *
 *  except_init
 *  except_fatal
 *  except_atExit
 *  except_returnPt
 */

/* --- except_init --- *
 *
 * On entry:	--
 *
 * On exit:	--
 *
 * Use:		Initialises the exception handler.
 */

extern routine except_init;

/* --- except_fatal --- *
 *
 * On entry:	R0 == pointer to an error block
 *
 * On exit:	Doesn't
 *
 * Use:		Reports an error to our /caller's/ error handler.  We quit
 *		and die at this point.  Don't use unless you have absolutely
 *		no choice in the matter.
 */

extern routine except_fatal;

/* --- except_atExit --- *
 *
 * On entry:	R0 == pointer to routine to call on exit
 *		R1 == R12 value to call with
 *
 * On exit:	--
 *
 * Use:		Registers a routine to get called when the application quits.
 *		Later-registered routines are called earlier than earlier-
 *		registered routines, so everything closes down in a nice
 *		manner.
 */

extern routine except_atExit;

/* --- except_returnPt --- *
 *
 * On entry:	R0 == pointer to exception handler routine
 *		R1 == R12 value to enter routine with
 *		R2 == R13 value to enter routine with
 *
 * On exit:	--
 *
 * Use:		Sets up a routine to be called whenever there's an error.
 *		The idea is that it should ask the user whether to quit,
 *		and if not, resume to some known (safe?) state.
 *
 * 		The routine is called with R0 == pointer to error block, and
 *		R12 and R13 being the values set up here(*).  It should
 *		return with R0 == pointer to a routine to resume at, and R1
 *		being the value to pass to the resume routine in R12.  If
 *		you decide to quit, just call OS_Exit -- this should tidy
 *		everything up.
 *
 *		Note that the error is held in the scratchpad buffer, so
 *		you can't use the first 256 bytes of that until you've
 *		finished with the error message.
 *
 *		(*) Actually, R13 is 4 bytes lower because it's assumed that
 *		it points to a full descending stack that we can use.  This
 *		shouldn't make any difference as long as you're using R13
 *		as a full descending stack pointer.
 */

extern routine except_returnPt;

/*----- That's all, folks -------------------------------------------------*/

#endif