/*
 * seh.h
 *
 * [Generated from seh, 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 __seh_h
#define __seh_h

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

/*----- Overview ----------------------------------------------------------*
 *
 * Functions provided:
 *
 *  seh_try
 *  seh_unTry
 *  seh_throw
 *  seh_throwErrors
 *  seh_setListBase
 *  seh_init
 */

/* --- seh_try --- *
 *
 * On entry:	R0 == pointer to catch definition block
 *
 * On exit:	R13 dropped by a (small) amount
 *
 * Use:		Inserts an exception handler at the current position.
 *		Exceptions are matched against those described in the catch
 *		block.  If there is a handler for the exception, the
 *		corresponding handler is called, and expected to resume
 *		normally.  Otherwise the tidy-up routine is called and we
 *		unwind the stack further to find an appropriate handler.
 *
 *		The catch block has the following format:
 *
 *		word	B to tidy-up routine
 *		word	1st exception mask
 *		word	1st B to catch routine
 *		word	2nd exception mask
 *		word	2nd B to catch routine
 *		...
 *		word	0
 *
 *		An exception mask contains two halfwords.  Bits 16-31 are the
 *		class to match, or -1 for all classes.  Bits 0-15 are the
 *		subtype to match, or -1 for all subtypes.  You can do really
 *		odd things if you set bits 16-31 to -1 and leave 0-15
 *		matching specific subtypes -- do this at your own risk.
 */

extern routine seh_try;

/* --- seh_unTry --- *
 *
 * On entry:	--
 *
 * On exit:	R13 moved to position before corresponding seh_try
 *
 * Use:		Removes the try block marker in the stack at the current
 *		position.  Note that the stack will be unwound to where it
 *		was when seh_try was called.
 */

extern routine seh_unTry;

/* --- seh_throw --- *
 *
 * On entry:	R0 == exception to match
 *		R1-R3 == useful bits of information
 *
 * On exit:	Doesn't return, unless you've done something /really/ odd
 *
 * Use:		Throws an exception.  The stack is unwound until we find
 *		a handler which can cope.  If there is no handler, we abort
 *		the program.
 */

extern routine seh_throw;

/* --- seh_throwErrors --- *
 *
 * On entry:	--
 *
 * On exit:	--
 *
 * Use:		Sets up an except-style error handler to throw errors
 *		as SEH exceptions.
 */

extern routine seh_throwErrors;

/* --- seh_setListBase --- *
 *
 * On entry:	R0 == pointer to try block list base, or 0 to use global
 *
 * On exit:	--
 *
 * Use:		Sets the try block list base.  This should only be used by
 *		coroutine providers, like coRoutine and thread.
 */

extern routine seh_setListBase;

/* --- seh_init --- *
 *
 * On entry:	--
 *
 * On exit:	--
 *
 * Use:		Initialises SEH's facilities.
 */

extern routine seh_init;

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

#endif
