/************************************************************************ * * yamon_api.h * * YAMON interface definitions * * ###################################################################### * * mips_start_of_legal_notice * * Copyright (c) 2003 MIPS Technologies, Inc. All rights reserved. * * * Unpublished rights (if any) reserved under the copyright laws of the * United States of America and other countries. * * This code is proprietary to MIPS Technologies, Inc. ("MIPS * Technologies"). Any copying, reproducing, modifying or use of this code * (in whole or in part) that is not expressly permitted in writing by MIPS * Technologies or an authorized third party is strictly prohibited. At a * minimum, this code is protected under unfair competition and copyright * laws. Violations thereof may result in criminal penalties and fines. * * MIPS Technologies reserves the right to change this code to improve * function, design or otherwise. MIPS Technologies does not assume any * liability arising out of the application or use of this code, or of any * error or omission in such code. Any warranties, whether express, * statutory, implied or otherwise, including but not limited to the implied * warranties of merchantability or fitness for a particular purpose, are * excluded. Except as expressly provided in any written license agreement * from MIPS Technologies or an authorized third party, the furnishing of * this code does not give recipient any license to any intellectual * property rights, including any patent rights, that cover this code. * * This code shall not be exported or transferred for the purpose of * reexporting in violation of any U.S. or non-U.S. regulation, treaty, * Executive Order, law, statute, amendment or supplement thereto. * * This code constitutes one or more of the following: commercial computer * software, commercial computer software documentation or other commercial * items. If the user of this code, or any related documentation of any * kind, including related technical data or manuals, is an agency, * department, or other entity of the United States government * ("Government"), the use, duplication, reproduction, release, * modification, disclosure, or transfer of this code, or any related * documentation of any kind, is restricted in accordance with Federal * Acquisition Regulation 12.212 for civilian agencies and Defense Federal * Acquisition Regulation Supplement 227.7202 for military agencies. The use * of this code by the Government is further restricted in accordance with * the terms of the license agreement(s) and/or applicable contract terms * and conditions covering this code from MIPS Technologies or an authorized * third party. * * * mips_end_of_legal_notice * * ************************************************************************/ #ifndef YAMON_API_H #define YAMON_API_H /************************************************************************ * Include files ************************************************************************/ /************************************************************************ * Definitions *************************************************************************/ /* Basic types */ typedef unsigned int t_yamon_uint32; typedef unsigned short t_yamon_uint16; typedef unsigned char t_yamon_uint8; typedef signed int t_yamon_int32; typedef signed short t_yamon_int16; typedef signed char t_yamon_int8; typedef unsigned char t_yamon_bool; #define YAMON_FALSE 0 #define YAMON_TRUE (!YAMON_FALSE) /* YAMON Environment variable */ typedef struct { char *name; char *val; } t_yamon_env_var; /* Format of application function */ typedef t_yamon_uint32 (*t_yamon_appl_main)( t_yamon_uint32 argc, /* Number of tokens in argv array */ char **argv, /* Array of tokens (first is "go") */ t_yamon_env_var *env, /* Array of env. variables */ t_yamon_uint32 memsize ); /* Size of memory (byte count) */ /* ID of YAMON configuration object */ typedef t_yamon_uint32 t_yamon_syscon_id; /* Number used by the exception registration functions in order to register * a default ISR/ESR. */ #define YAMON_DEFAULT_HANDLER 0xfffffff0 /* Number used by the exception registration functions in order to register * an EJTAG debug exception ESR. */ #define YAMON_DEFAULT_EJTAG_ESR 0xfffffff1 /* Registered Interrupt Service Routine (ISR) */ typedef void (*t_yamon_isr)(void *data); /* Registered Exception Service Routine (ESR) */ typedef void (*t_yamon_esr)(void); /* Entry point called by ESRs wishing to pass control back to YAMON */ typedef void (*t_yamon_retfunc)(void); /* Handle used for deregistration of ISR/ESR */ typedef void *t_yamon_ref; /* YAMONE Vector table address */ #define YAMON_FUNCTION_BASE 0x9fc00500 /* YAMON Vector table offsets */ #define YAMON_FUNC_PRINT_COUNT_OFS 0x04 #define YAMON_FUNC_EXIT_OFS 0x20 #define YAMON_FUNC_FLUSH_CACHE_OFS 0x2C #define YAMON_FUNC_PRINT_OFS 0x34 #define YAMON_FUNC_REGISTER_CPU_ISR_OFS 0x38 #define YAMON_FUNC_DEREGISTER_CPU_ISR_OFS 0x3c #define YAMON_FUNC_REGISTER_IC_ISR_OFS 0x40 #define YAMON_FUNC_DEREGISTER_IC_ISR_OFS 0x44 #define YAMON_FUNC_REGISTER_ESR_OFS 0x48 #define YAMON_FUNC_DEREGISTER_ESR_OFS 0x4c #define YAMON_FUNC_GETCHAR_OFS 0x50 #define YAMON_FUNC_SYSCON_READ_OFS 0x54 /* Macro for accessing YAMON function */ #define YAMON_FUNC(ofs)\ (*(t_yamon_uint32 *)(YAMON_FUNCTION_BASE + (ofs))) /************************************************************************ * Public variables ************************************************************************/ /************************************************************************ * Public functions ************************************************************************/ /************************************************************************ * * t_yamon_exit * Description : * ------------- * * Exit application and return to YAMON. * * Parameters : * ------------ * * 'rc' (OUT) : Return code * * Return values : * --------------- * * None (never returns) * ************************************************************************/ typedef void (*t_yamon_exit)( t_yamon_uint32 rc ); /* Return code */ #define YAMON_FUNC_EXIT( rc )\ ((t_yamon_exit)( YAMON_FUNC(YAMON_FUNC_EXIT_OFS) ))\ ( rc ) /************************************************************************ * * t_yamon_print * Description : * ------------- * * Print null-terminated string to tty0. * * Parameters : * ------------ * * 'port' (OUT) : Ignored, always prints to tty0. Not included in macro. * 's' (OUT) : String to print. * * Return values : * --------------- * * None * ************************************************************************/ typedef void (*t_yamon_print)( t_yamon_uint32 port, /* Output port (not used, always tty0) */ const char *s ); /* String to output */ #define YAMON_FUNC_PRINT( s )\ ((t_yamon_print)( YAMON_FUNC(YAMON_FUNC_PRINT_OFS) ))\ ( 0, s ) /************************************************************************ * * t_yamon_print_count * Description : * ------------- * * Print specified number of characters to tty0. * * Parameters : * ------------ * * 'port' (OUT) : Ignored, always prints to tty0. Not included in macro. * 's' (OUT) : Array of characters to print. * 'count' (OUT) : Number of characters to print. * * Return values : * --------------- * * None * ************************************************************************/ typedef void (*t_yamon_print_count)( t_yamon_uint32 port, /* Output port (not used, always tty0 */ char *s, /* String to output */ t_yamon_uint32 count ); /* Number of characters to output */ #define YAMON_FUNC_PRINT_COUNT( s, count )\ ((t_yamon_print_count)( YAMON_FUNC(YAMON_FUNC_PRINT_COUNT_OFS) ))\ ( 0, s, count ) /************************************************************************ * * t_yamon_getchar * Description : * ------------- * * Get character from tty0 if character is available. Function * returns immediately if no character is available. * * Parameters : * ------------ * * 'port' (OUT) : Ignored, always uses tty0. Not included in macro. * 'ch' (OUT) : Character read (if available). * * Return values : * --------------- * * YAMON_TRUE if character was available, else YAMON_FALSE. * ************************************************************************/ typedef t_yamon_bool (*t_yamon_getchar)( t_yamon_uint32 port, /* Output port (not used, always tty0 */ char *ch ); /* Character to output */ #define YAMON_FUNC_GETCHAR( ch )\ ((t_yamon_getchar)( YAMON_FUNC(YAMON_FUNC_GETCHAR_OFS) ))\ ( 0, ch ) /************************************************************************ * * t_yamon_syscon_read * Description : * ------------- * * Read the value of system configuration object given by 'id'. * * See syscon_api.h in YAMON source distribution for further details * on object IDs and error codes. * * Parameters : * ------------ * * 'id' (IN) : Object id. * 'param' (INOUT) : Buffer for object value. * 'size' (IN) : Size of buffer (must match size of object). * * Return values : * --------------- * * 0 : Returned parameter is valid. * Other values indicate error. * ************************************************************************/ typedef t_yamon_int32 (*t_yamon_syscon_read)( t_yamon_syscon_id id, /* Object ID */ void *param, /* Buffer for object value */ t_yamon_uint32 size); /* Buffer size (bytes) */ #define YAMON_FUNC_SYSCON_READ( id, param, size )\ ((t_yamon_syscon_read)( YAMON_FUNC(YAMON_FUNC_SYSCON_READ_OFS) ))\ ( id, param, size ) /************************************************************************ * * t_yamon_flush_cache * Description : * ------------- * * Flush I-or D-cache * * Function performs "writeback and invalidate" operations on D-cache * lines and "invalidate" operations on I-cache lines. * * Parameters : * ------------ * * 'type' (IN) : Cache to be flushed. * * Return values : * --------------- * * None * ************************************************************************/ typedef void (*t_yamon_flush_cache)( #define YAMON_FLUSH_ICACHE 0 #define YAMON_FLUSH_DCACHE 1 t_yamon_uint32 type ); /* I- or D-cache indication */ #define YAMON_FUNC_FLUSH_CACHE( type )\ ((t_yamon_flush_cache)( YAMON_FUNC(YAMON_FUNC_FLUSH_CACHE_OFS) ))\ ( type ) /************************************************************************ * * t_yamon_register_esr * Description : * ------------- * * Registers an exception handler, also known as an "Exception Service * Routine" (ESR) for the specified exception. * * Two special exception IDs are defined : * YAMON_DEFAULT_HANDLER used for a default ESR. * YAMON_DEFAULT_EJTAG_ESR used for EJTAG exceptions. * * The default ESR is called if no other ESR is registered * for an exception. If no default ESR is registered, a static * (i.e. not registered) "super default" function is invoked. * This function prints out the registers and halts. * * Deregistration of an ESR may be be done by calling this function * with 'esr' set to NULL. * An ESR can also be deregistered using the 'yamon_deregister_esr' * function. * * An ESR may be registered even if a previously registered * ESR has not been deregistered. In this case the previously * registered ESR is lost. * * The ESR will get called with registers in the state they were * when the exception occurred. This includes all CP0 registers and * CPU registers $0..$31, except for k0,k1 ($26,$27). * * In case an ESR does not want to handle the exception, it may * call the return function passed in the 'retfunc' parameter. * * Case 1 : 'retfunc' called by ESR registered for the * INTERRUPT exception. * * We assume an application has registered this ESR and wants * YAMON to process the (remaining) interrupts. * * Case 2 : 'retfunc' called by an ESR registered for a specific * exception (not INTERRUPT). * * Default handling will be done. * * Case 3 : 'retfunc' is called by the ESR registered as default ESR. * * The exception will be handled as though no ESR is registered * (i.e. the "super default" function is called). * * Parameters : * ------------ * * 'exception' (IN) : Exception code * or YAMON_DEFAULT_HANDLER for a default ESR * or YAMON_DEFAULT_EJTAG_ESR for ejtag exceptions. * 'esr' (IN) : Function pointer for ESR. * 'ref' (OUT) : Handle used for deregistration of ESR. * 'retfunc' (OUT) : Pointer to function pointer for the return * function described above. * * Return values : * --------------- * * 0 : Registration went well. * Other values indicate error. * ************************************************************************/ typedef t_yamon_int32 (*t_yamon_register_esr)( t_yamon_uint32 exception, /* Exception identification */ t_yamon_esr esr, /* ESR to be registered */ t_yamon_ref *ref, /* Handle for deregistration */ t_yamon_retfunc *retfunc ); /* Return function */ #define YAMON_FUNC_REGISTER_ESR( exc, esr, ref, retfunc )\ ((t_yamon_register_esr)( YAMON_FUNC(YAMON_FUNC_REGISTER_ESR_OFS) ))\ ( exc, esr, ref, retfunc ) /************************************************************************ * * t_yamon_deregister_esr * Description : * ------------- * * Deregisters ESR.. * * Parameters : * ------------ * * 'ref' (IN) : Handle obtained when calling 'yamon_register_esr'. * * Return values : * --------------- * * 0 : Deregistration went well. * Other values indicate error. * ************************************************************************/ typedef t_yamon_int32 (*t_yamon_deregister_esr)( t_yamon_ref ref ); /* Handle for deregistration */ #define YAMON_FUNC_DEREGISTER_ESR( ref )\ ((t_yamon_deregister_esr)( YAMON_FUNC(YAMON_FUNC_DEREGISTER_ESR_OFS) ))\ ( ref ) /************************************************************************ * * t_yamon_register_cpu_isr * Description : * ------------- * * Registers an Interrupt Service Routine (ISR) for the specified * CPU interrupt. * The highest service priority is attached to HW-INT5, which is * connected to the CPU-built-in CP0-timer. SW_INT0 gets the lowest * service priority. During registration, the interrupt mask field * in the CPU CP0-status register is updated to enable interrupts * from the specified interrupt source. * * A special ID is defined : * YAMON_DEFAULT_HANDLER used for a default ISR. * * The default ISR is called if no other ISR is registered * for a CPU interrupt. * * Deregistration of the default ISR may be done by calling * this function with 'isr' set to NULL. * Also, a new default ISR may be registered even if a * previously registered ISR has not been deregistered. * ISRs for specific CPU interrupts must be deregistered using * 'yamon_deregister_cpu_isr'. * * Parameters : * ------------ * * 'cpu_int' (IN) : CPU interrupt (0..7) * or YAMON_DEFAULT_HANDLER for a default ISR. * 'isr' (IN) : Function pointer for ISR. * 'data' (IN) : Data pointer (may be NULL). Will be passed to * ISR when called. * 'ref' (OUT) : Handle used for deregistration of ISR. * * Return values : * --------------- * * 0 : Registration went well. * Other values indicate error. * ************************************************************************/ typedef t_yamon_int32 (*t_yamon_register_cpu_isr)( t_yamon_uint32 cpu_int, /* CPU interrupt (0..7) */ t_yamon_isr isr, /* ISR to be registered */ void *data, /* Data reference to be registered */ t_yamon_ref *ref ); /* Handle for deregistration */ #define YAMON_FUNC_REGISTER_CPU_ISR( cpu_int, isr, data, ref )\ ((t_yamon_register_cpu_isr)( YAMON_FUNC(YAMON_FUNC_REGISTER_CPU_ISR_OFS) ))\ ( cpu_int, isr, data, ref ) /************************************************************************ * * t_yamon_deregister_cpu_isr * Description : * ------------- * * Deregisters ISR for CPU interrupt. * * Parameters : * ------------ * * 'ref' (IN) : Handle obtained when calling 'yamon_register_cpu_isr'. * * Return values : * --------------- * * 0 : Deregistration went well. * Other values indicate error * ************************************************************************/ typedef t_yamon_int32 (*t_yamon_deregister_cpu_isr)( t_yamon_ref ref ); /* Handle for deregistration */ #define YAMON_FUNC_DEREGISTER_CPU_ISR( ref )\ ((t_yamon_deregister_cpu_isr)( YAMON_FUNC(YAMON_FUNC_DEREGISTER_CPU_ISR_OFS) ))\ ( ref ) /************************************************************************ * * t_yamon_register_ic_isr * Description : * ------------- * * Registers an Interrupt Service Routine (ISR) for the specified * source in the interrupt controller. * * A special ID is defined : * YAMON_DEFAULT_HANDLER used for a default ISR. * * The default ISR is called if no other ISR is registered * for an interrupt. * * Deregistration of the default ISR may be done by calling * this function with 'isr' set to NULL. * Also, a new default ISR may be registered even if a * previously registered ISR has not been deregistered. * ISRs for specific interrupts must be deregistered using * 'yamon_deregister_ic_isr'. * * Parameters : * ------------ * * 'ic_line' (IN) : Interrupt source line in Int. Controller * or YAMON_DEFAULT_HANDLER for a default ISR. * 'isr', (IN) : Function pointer for user defined ISR. * 'data' (IN) : Data pointer (may be NULL). Will be passed to * ISR when called. * 'ref', (OUT) : Handle used for deregistration of ISR. * * Return values : * --------------- * * 0 : Registration went well. * Other values indicate error. * ************************************************************************/ typedef t_yamon_int32 (*t_yamon_register_ic_isr)( t_yamon_uint32 ic_line, /* Interrupt controller line */ t_yamon_isr isr, /* ISR to be registered */ void *data, /* Data reference to be registered */ t_yamon_ref *ref ); /* Handle for deregistration */ #define YAMON_FUNC_REGISTER_IC_ISR( ic_line, isr, data, ref )\ ((t_yamon_register_ic_isr)( YAMON_FUNC(YAMON_FUNC_REGISTER_IC_ISR_OFS) ))\ ( ic_line, isr, data, ref ) /************************************************************************ * * t_yamon_deregister_ic_isr * Description : * ------------- * * Deregisters ISR for source in interrupt controller. * * Parameters : * ------------ * * 'ref' (IN) : Handle obtained when calling 'yamon_register_ic_isr'. * * Return values : * --------------- * * 0 : Deregistration went well. * Other values indicate error * ************************************************************************/ typedef t_yamon_int32 (*t_yamon_deregister_ic_isr)( t_yamon_ref ref ); /* Handle for deregistration */ #define YAMON_FUNC_DEREGISTER_IC_ISR( ref )\ ((t_yamon_deregister_ic_isr)( YAMON_FUNC(YAMON_FUNC_DEREGISTER_IC_ISR_OFS) ))\ ( ref ) #endif /* #ifndef YAMON_API_H */