excep_api.h

MIPS YAMON, a famous monitor inc. source, make file and PDF manuals.

 *  ------------
 *
 *  'cpu_int',      IN,    CPU interrupt (C0_STATUS_IM_HW[0..5] |
 *					  C0_STATUS_IM_SW[0..1])
 *			   or EXCEP_DEFAULT_HANDLER for a default handler.
 *  'handler',      IN,    Function pointer for user defined handler
 *  'data',         IN,    Data pointer, may be NULL
 *  'ref',	    OUT,   Handle used for deregistration of handler.
 *
 *  Return values :
 *  ---------------
 *
 *  'OK'(=0)
 *  'ERROR_EXCEP_ILLEGAL_INTERRUPT': CPU interrupt source is unknown
 *  'ERROR_EXCEP_ILLEGAL_HANDLER':   Handler reference is NULL
 *  'ERROR_EXCEP_NO_SPACE':          Too many handlers have been registered
 *
 ************************************************************************/
INT32 
EXCEP_register_cpu_isr(
    UINT32      cpu_int,	     /* CPU interrupt, 0..7		*/
    t_EXCEP_isr handler,	     /* ISR to be registered		*/
    void        *data,   	     /* Data reference to be registered */
    t_EXCEP_ref *ref );	             /* OUT : Handle for deregistration */


/************************************************************************
 *
 *                          EXCEP_deregister_cpu_isr
 *  Description :
 *  -------------
 *
 *  Deregisters interrupt handler
 *  
 *  Parameters :
 *  ------------
 *
 *  'ref',	 IN,   Handle obtained when calling EXCEP_register_cpu_isr
 *  It is OK to call this function even if we are in interrupt context.
 *
 *  Return values :
 *  ---------------
 *
 *  'OK'(=0)
 *  'ERROR_EXCEP_ILLEGAL_HANDLER':  ref is unknown
 *
 ************************************************************************/
INT32 
EXCEP_deregister_cpu_isr(
    t_EXCEP_ref ref );	             /* In : Handle for deregistration */


/************************************************************************
 *
 *                          EXCEP_register_ic_isr
 *  Description :
 *  -------------
 *
 *  Registers an interrupt handler for the specified source in the
 *  interrupt controller. 
 *
 *  A special ID is defined :
 *      EXCEP_DEFAULT_HANDLER used for a default handler.
 *	
 *  The default handler is called if no other handler is registered
 *  for an interrupt.
 *
 *  Deregistration of the default handler may be done by calling
 *  this function with 'handler' set to NULL.
 *  Also, a new default handler may be registered even if a 
 *  previously registered handler has not been deregistered.
 *  Handlers for specific interrupts must be deregistered using 
 *  EXCEP_deregister_ic_isr.

 *  Parameters :
 *  ------------
 *
 *  'ic_int_line', IN,    Interrupt source line in Int. Controller
 *			  or EXCEP_DEFAULT_HANDLER for a default handler.
 *  'handler',     IN,    Function pointer for user defined handler
 *  'data',        IN,    Data pointer; may be NULL
 *  'ref',	   OUT,   Handle used for deregistration of handler.
 *
 *  Return values :
 *  ---------------
 *
 *  'OK'(=0)
 *  'ERROR_EXCEP_ILLEGAL_INTERRUPT': Int. source line is unknown
 *  'ERROR_EXCEP_ILLEGAL_HANDLER':   Handler reference is NULL
 *  'ERROR_EXCEP_NO_SPACE':          Too many handlers have been registered
 *
 ************************************************************************/
INT32 
EXCEP_register_ic_isr(
    UINT32      ic_int_line,	    /* Exception identification		*/
    t_EXCEP_isr handler,	    /* ISR to be registered		*/
    void        *data,		    /* Data reference to be registered  */
    t_EXCEP_ref *ref );		    /* OUT : Handle for deregistration  */


/************************************************************************
 *
 *                          EXCEP_deregister_ic_isr
 *  Description :
 *  -------------
 *
 *  Deregisters interrupt handler for source in interrupt controller
 *  It is OK to call this function even if we are in interrupt context.
 *  
 *  Parameters :
 *  ------------
 *
 *  'ref',	 IN,   Handle obtained when calling EXCEP_register_ic_isr
 *
 *  Return values :
 *  ---------------
 *
 *  'OK'(=0)
 *  'ERROR_EXCEP_ILLEGAL_HANDLER':  ref is unknown
 *
 ************************************************************************/
INT32 
EXCEP_deregister_ic_isr(
    t_EXCEP_ref ref );	             /* In : Handle for deregistration */


/************************************************************************
 *
 *                          EXCEP_store_handlers
 *  Description :
 *  -------------
 *
 *  The current setup of registered exception handlers is copied to
 *  a table so that it may later be restored using EXCEP_set_handlers().
 *
 ************************************************************************/
void 
EXCEP_store_handlers(
    UINT32 set ); /* table where setup is copied */
#define EXCEP_HANDLERS_SHELL	0
#define EXCEP_HANDLERS_GDB	1


/************************************************************************
 *
 *                          EXCEP_set_handlers
 *  Description :
 *  -------------
 *
 *  The setup of registered exception handlers is restored to the
 *  state stored previously using EXCEP_store_handlers().
 *
 ************************************************************************/
void 
EXCEP_set_handlers(
    UINT32 set ); /* table where setup is copied */


/************************************************************************
 *
 *                          EXCEP_install_exc_in_ram
 *  Description :
 *  -------------
 *  Install jump instructions to exc handler at exception vector locations.
 *
 *  Return values :
 *  ---------------
 *  None
 *
 ************************************************************************/
void
EXCEP_install_exc_in_ram( void );


/************************************************************************
 *
 *                          EXCEP_save_context
 *  Description :
 *  -------------
 *  Saves current context, as done by an exception
 *  Will return 0 when context is saved.
 *  Will return 1 second time, when context is restored.
 *
 *  Parameters :
 *  ------------
 *  'context',	 IN,   Pointer to context structure to save to
 *
 *  Return values :
 *  ---------------
 *  None
 *
 ************************************************************************/
UINT32
EXCEP_save_context(
    t_gdb_regs *context );


/************************************************************************
 *
 *                          EXCEP_get_context_ptr
 *  Description :
 *  -------------
 *  Retrieves pointer to current exception context.
 *
 *  Return values :
 *  ---------------
 *  Pointer to register structure saved at exception entry.
 *  If a valid pointer cannot be returned, the routine does not return!
 ************************************************************************/
t_gdb_regs *
EXCEP_get_context_ptr( void );


/************************************************************************
 *
 *                          EXCEP_exc_handler_ret
 *  Description :
 *  -------------
 *
 *  Restore context and return from exception
 *
 *  Return values :
 *  ---------------
 *
 *  None
 *
 ************************************************************************/
void 
EXCEP_exc_handler_ret( 
    t_gdb_regs *context );


/************************************************************************
 *
 *                          EXCEP_exc_handler_ret_ss
 *  Description :
 *  -------------
 *
 * Same functionality as EXCEP_exc_handler_ret()
 * except that for CPUs implementing MIPS32/MIPS64
 * Release 2, we first make sure to use shadowset 0.
 *
 *  Return values :
 *  ---------------
 *
 *  None
 *
 ************************************************************************/
void 
EXCEP_exc_handler_ret_ss( 
    t_gdb_regs *context );


/************************************************************************
 *
 *                          EXCEP_print_context
 *  Description :
 *  -------------
 *
 *  Print context
 *
 *  Note : Printout is done by printf() through the IO module, so if
 *         this routine is entered before serial drivers are installed,
 *         no printout will take place - and no harm is done.
 *
 *  Return values :
 *  ---------------
 *
 *  None
 *
 ************************************************************************/
void
EXCEP_print_context( 
    t_gdb_regs *context,	/* Context to print			*/
    char       *msg,		/* Special msg to be printed (or NULL)	*/
    bool       user,		/* In user context			*/
    bool       display );	/* TRUE -> Print EPC in ASCII display	*/


/************************************************************************
 *
 *                          EXCEP_run_default_esr_handler
 *  Description :
 *  -------------
 *  Runs default exception handler.
 *  Called by North Bridge Interrupt handlers (init_core.c)
 *  to print out context and possibly continue (go.c).
 *
 *  Return values :
 *  ---------------
 *  None - may not return
 *
 ************************************************************************/
void
EXCEP_run_default_esr_handler( void );


#else /* #ifndef _ASSEMBLER_ */

EXTERN(EXCEP_install_exc_in_ram)
EXTERN(EXCEP_exc_handler_ret)

#endif /* #ifndef _ASSEMBLER_ */


#endif /* #ifndef EXCEP_API_H */