diff options
Diffstat (limited to 'bsps/mips/rbtx4938/console/yamon_api.h')
| -rw-r--r-- | bsps/mips/rbtx4938/console/yamon_api.h | 631 |
1 files changed, 631 insertions, 0 deletions
diff --git a/bsps/mips/rbtx4938/console/yamon_api.h b/bsps/mips/rbtx4938/console/yamon_api.h new file mode 100644 index 0000000000..529cf16a3f --- /dev/null +++ b/bsps/mips/rbtx4938/console/yamon_api.h @@ -0,0 +1,631 @@ +/************************************************************************ + * + * 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 */ + + + + + + |