rbtx4938/console/yamon_api.h

0001 /************************************************************************
0002  *
0003  *  yamon_api.h
0004  *
0005  *  YAMON interface definitions
0006  *
0007  * ######################################################################
0008  *
0009  * mips_start_of_legal_notice
0010  *
0011  * Copyright (c) 2003 MIPS Technologies, Inc. All rights reserved.
0012  *
0013  *
0014  * Unpublished rights (if any) reserved under the copyright laws of the
0015  * United States of America and other countries.
0016  *
0017  * This code is proprietary to MIPS Technologies, Inc. ("MIPS
0018  * Technologies"). Any copying, reproducing, modifying or use of this code
0019  * (in whole or in part) that is not expressly permitted in writing by MIPS
0020  * Technologies or an authorized third party is strictly prohibited. At a
0021  * minimum, this code is protected under unfair competition and copyright
0022  * laws. Violations thereof may result in criminal penalties and fines.
0023  *
0024  * MIPS Technologies reserves the right to change this code to improve
0025  * function, design or otherwise. MIPS Technologies does not assume any
0026  * liability arising out of the application or use of this code, or of any
0027  * error or omission in such code. Any warranties, whether express,
0028  * statutory, implied or otherwise, including but not limited to the implied
0029  * warranties of merchantability or fitness for a particular purpose, are
0030  * excluded. Except as expressly provided in any written license agreement
0031  * from MIPS Technologies or an authorized third party, the furnishing of
0032  * this code does not give recipient any license to any intellectual
0033  * property rights, including any patent rights, that cover this code.
0034  *
0035  * This code shall not be exported or transferred for the purpose of
0036  * reexporting in violation of any U.S. or non-U.S. regulation, treaty,
0037  * Executive Order, law, statute, amendment or supplement thereto.
0038  *
0039  * This code constitutes one or more of the following: commercial computer
0040  * software, commercial computer software documentation or other commercial
0041  * items. If the user of this code, or any related documentation of any
0042  * kind, including related technical data or manuals, is an agency,
0043  * department, or other entity of the United States government
0044  * ("Government"), the use, duplication, reproduction, release,
0045  * modification, disclosure, or transfer of this code, or any related
0046  * documentation of any kind, is restricted in accordance with Federal
0047  * Acquisition Regulation 12.212 for civilian agencies and Defense Federal
0048  * Acquisition Regulation Supplement 227.7202 for military agencies. The use
0049  * of this code by the Government is further restricted in accordance with
0050  * the terms of the license agreement(s) and/or applicable contract terms
0051  * and conditions covering this code from MIPS Technologies or an authorized
0052  * third party.
0053  *
0054  *
0055  * mips_end_of_legal_notice
0056  *
0057  *
0058  ************************************************************************/
0059
0060 #ifndef YAMON_API_H
0061 #define YAMON_API_H
0062
0063 /************************************************************************
0064  *  Include files
0065  ************************************************************************/
0066
0067
0068 /************************************************************************
0069  *  Definitions
0070 *************************************************************************/
0071
0072 /* Basic types */
0073
0074 typedef unsigned int        t_yamon_uint32;
0075 typedef unsigned short      t_yamon_uint16;
0076 typedef unsigned char       t_yamon_uint8;
0077 typedef signed int      t_yamon_int32;
0078 typedef signed short        t_yamon_int16;
0079 typedef signed char     t_yamon_int8;
0080
0081 typedef unsigned char       t_yamon_bool;
0082
0083 #define YAMON_FALSE     0
0084 #define YAMON_TRUE      (!YAMON_FALSE)
0085
0086 /* YAMON Environment variable */
0087 typedef struct
0088 {
0089     char *name;
0090     char *val;
0091 }
0092 t_yamon_env_var;
0093
0094 /* Format of application function */
0095 typedef t_yamon_uint32
0096 (*t_yamon_appl_main)(
0097     t_yamon_uint32  argc,      /* Number of tokens in argv array    */
0098     char        **argv,    /* Array of tokens (first is "go")   */
0099     t_yamon_env_var *env,      /* Array of env. variables       */
0100     t_yamon_uint32  memsize ); /* Size of memory (byte count)       */
0101
0102
0103 /* ID of YAMON configuration object */
0104 typedef t_yamon_uint32 t_yamon_syscon_id;
0105
0106
0107 /*  Number used by the exception registration functions in order to register
0108  *  a default ISR/ESR.
0109  */
0110 #define YAMON_DEFAULT_HANDLER           0xfffffff0
0111
0112 /*  Number used by the exception registration functions in order to register
0113  *  an EJTAG debug exception ESR.
0114  */
0115 #define YAMON_DEFAULT_EJTAG_ESR         0xfffffff1
0116
0117 /* Registered Interrupt Service Routine (ISR) */
0118 typedef void (*t_yamon_isr)(void *data);
0119
0120 /* Registered Exception Service Routine (ESR) */
0121 typedef void (*t_yamon_esr)(void);
0122
0123 /* Entry point called by ESRs wishing to pass control back to YAMON */
0124 typedef void (*t_yamon_retfunc)(void);
0125
0126 /* Handle used for deregistration of ISR/ESR */
0127 typedef void *t_yamon_ref;
0128
0129
0130 /* YAMONE Vector table address */
0131 #define YAMON_FUNCTION_BASE         0x9fc00500
0132
0133 /* YAMON Vector table offsets */
0134 #define YAMON_FUNC_PRINT_COUNT_OFS      0x04
0135 #define YAMON_FUNC_EXIT_OFS         0x20
0136 #define YAMON_FUNC_FLUSH_CACHE_OFS      0x2C
0137 #define YAMON_FUNC_PRINT_OFS            0x34
0138 #define YAMON_FUNC_REGISTER_CPU_ISR_OFS     0x38
0139 #define YAMON_FUNC_DEREGISTER_CPU_ISR_OFS   0x3c
0140 #define YAMON_FUNC_REGISTER_IC_ISR_OFS      0x40
0141 #define YAMON_FUNC_DEREGISTER_IC_ISR_OFS    0x44
0142 #define YAMON_FUNC_REGISTER_ESR_OFS     0x48
0143 #define YAMON_FUNC_DEREGISTER_ESR_OFS       0x4c
0144 #define YAMON_FUNC_GETCHAR_OFS          0x50
0145 #define YAMON_FUNC_SYSCON_READ_OFS      0x54
0146
0147 /* Macro for accessing YAMON function */
0148 #define YAMON_FUNC(ofs)\
0149     (*(t_yamon_uint32 *)(YAMON_FUNCTION_BASE + (ofs)))
0150
0151
0152 /************************************************************************
0153  *  Public variables
0154  ************************************************************************/
0155
0156 /************************************************************************
0157  *  Public functions
0158  ************************************************************************/
0159
0160
0161 /************************************************************************
0162  *
0163  *                          t_yamon_exit
0164  *  Description :
0165  *  -------------
0166  *
0167  *  Exit application and return to YAMON.
0168  *
0169  *  Parameters :
0170  *  ------------
0171  *
0172  *  'rc' (OUT) : Return code
0173  *
0174  *  Return values :
0175  *  ---------------
0176  *
0177  *  None (never returns)
0178  *
0179  ************************************************************************/
0180 typedef void
0181 (*t_yamon_exit)(
0182     t_yamon_uint32 rc );    /* Return code              */
0183
0184 #define YAMON_FUNC_EXIT( rc )\
0185     ((t_yamon_exit)( YAMON_FUNC(YAMON_FUNC_EXIT_OFS) ))\
0186         ( rc )
0187
0188
0189 /************************************************************************
0190  *
0191  *                          t_yamon_print
0192  *  Description :
0193  *  -------------
0194  *
0195  *  Print null-terminated string to tty0.
0196  *
0197  *  Parameters :
0198  *  ------------
0199  *
0200  *  'port' (OUT) : Ignored, always prints to tty0. Not included in macro.
0201  *  's'    (OUT) : String to print.
0202  *
0203  *  Return values :
0204  *  ---------------
0205  *
0206  *  None
0207  *
0208  ************************************************************************/
0209 typedef void
0210 (*t_yamon_print)(
0211     t_yamon_uint32 port, /* Output port (not used, always tty0)     */
0212     const char           *s ); /* String to output              */
0213
0214 #define YAMON_FUNC_PRINT( s )\
0215     ((t_yamon_print)( YAMON_FUNC(YAMON_FUNC_PRINT_OFS) ))\
0216         ( 0, s )
0217
0218
0219 /************************************************************************
0220  *
0221  *                          t_yamon_print_count
0222  *  Description :
0223  *  -------------
0224  *
0225  *  Print specified number of characters to tty0.
0226  *
0227  *  Parameters :
0228  *  ------------
0229  *
0230  *  'port'  (OUT) : Ignored, always prints to tty0. Not included in macro.
0231  *  's'     (OUT) : Array of characters to print.
0232  *  'count' (OUT) : Number of characters to print.
0233  *
0234  *  Return values :
0235  *  ---------------
0236  *
0237  *  None
0238  *
0239  ************************************************************************/
0240 typedef void
0241 (*t_yamon_print_count)(
0242     t_yamon_uint32 port,    /* Output port (not used, always tty0   */
0243     char       *s,      /* String to output         */
0244     t_yamon_uint32 count ); /* Number of characters to output   */
0245
0246 #define YAMON_FUNC_PRINT_COUNT( s, count )\
0247     ((t_yamon_print_count)( YAMON_FUNC(YAMON_FUNC_PRINT_COUNT_OFS) ))\
0248         ( 0, s, count )
0249
0250
0251 /************************************************************************
0252  *
0253  *                          t_yamon_getchar
0254  *  Description :
0255  *  -------------
0256  *
0257  *  Get character from tty0 if character is available. Function
0258  *  returns immediately if no character is available.
0259  *
0260  *  Parameters :
0261  *  ------------
0262  *
0263  *  'port'  (OUT) : Ignored, always uses tty0. Not included in macro.
0264  *  'ch'    (OUT) : Character read (if available).
0265  *
0266  *  Return values :
0267  *  ---------------
0268  *
0269  *  YAMON_TRUE if character was available, else YAMON_FALSE.
0270  *
0271  ************************************************************************/
0272 typedef t_yamon_bool
0273 (*t_yamon_getchar)(
0274     t_yamon_uint32 port,    /* Output port (not used, always tty0   */
0275     char       *ch );   /* Character to output          */
0276
0277 #define YAMON_FUNC_GETCHAR( ch )\
0278     ((t_yamon_getchar)( YAMON_FUNC(YAMON_FUNC_GETCHAR_OFS) ))\
0279         ( 0, ch )
0280
0281
0282 /************************************************************************
0283  *
0284  *                          t_yamon_syscon_read
0285  *  Description :
0286  *  -------------
0287  *
0288  *  Read the value of system configuration object given by 'id'.
0289  *
0290  *  See syscon_api.h in YAMON source distribution for further details
0291  *  on object IDs and error codes.
0292  *
0293  *  Parameters :
0294  *  ------------
0295  *
0296  *  'id'    (IN)    : Object id.
0297  *  'param' (INOUT) : Buffer for object value.
0298  *  'size'  (IN)    : Size of buffer (must match size of object).
0299  *
0300  *  Return values :
0301  *  ---------------
0302  *
0303  *  0 : Returned parameter is valid.
0304  *  Other values indicate error.
0305  *
0306  ************************************************************************/
0307 typedef t_yamon_int32
0308 (*t_yamon_syscon_read)(
0309     t_yamon_syscon_id   id,       /* Object ID          */
0310     void                *param,       /* Buffer for object value    */
0311     t_yamon_uint32      size);        /* Buffer size (bytes)        */
0312
0313 #define YAMON_FUNC_SYSCON_READ( id, param, size )\
0314     ((t_yamon_syscon_read)( YAMON_FUNC(YAMON_FUNC_SYSCON_READ_OFS) ))\
0315         ( id, param, size )
0316
0317
0318 /************************************************************************
0319  *
0320  *                          t_yamon_flush_cache
0321  *  Description :
0322  *  -------------
0323  *
0324  *  Flush I-or D-cache
0325  *
0326  *  Function performs "writeback and invalidate" operations on D-cache
0327  *  lines and "invalidate" operations on I-cache lines.
0328  *
0329  *  Parameters :
0330  *  ------------
0331  *
0332  *  'type' (IN) : Cache to be flushed.
0333  *
0334  *  Return values :
0335  *  ---------------
0336  *
0337  *  None
0338  *
0339  ************************************************************************/
0340 typedef void
0341 (*t_yamon_flush_cache)(
0342 #define YAMON_FLUSH_ICACHE  0
0343 #define YAMON_FLUSH_DCACHE  1
0344     t_yamon_uint32 type );  /* I- or D-cache indication     */
0345
0346 #define YAMON_FUNC_FLUSH_CACHE( type )\
0347     ((t_yamon_flush_cache)( YAMON_FUNC(YAMON_FUNC_FLUSH_CACHE_OFS) ))\
0348         ( type )
0349
0350
0351 /************************************************************************
0352  *
0353  *                          t_yamon_register_esr
0354  *  Description :
0355  *  -------------
0356  *
0357  *  Registers an exception handler, also known as an "Exception Service
0358  *  Routine" (ESR) for the specified exception.
0359  *
0360  *  Two special exception IDs are defined :
0361  *      YAMON_DEFAULT_HANDLER used for a default ESR.
0362  *      YAMON_DEFAULT_EJTAG_ESR used for EJTAG exceptions.
0363  *
0364  *  The default ESR is called if no other ESR is registered
0365  *  for an exception. If no default ESR is registered, a static
0366  *  (i.e. not registered) "super default" function is invoked.
0367  *  This function prints out the registers and halts.
0368  *
0369  *  Deregistration of an ESR may be be done by calling this function
0370  *  with 'esr' set to NULL.
0371  *  An ESR can also be deregistered using the 'yamon_deregister_esr'
0372  *  function.
0373  *
0374  *  An ESR may be registered even if a previously registered
0375  *  ESR has not been deregistered. In this case the previously
0376  *  registered ESR is lost.
0377  *
0378  *  The ESR will get called with registers in the state they were
0379  *  when the exception occurred. This includes all CP0 registers and
0380  *  CPU registers $0..$31, except for k0,k1 ($26,$27).
0381  *
0382  *  In case an ESR does not want to handle the exception, it may
0383  *  call the return function passed in the 'retfunc' parameter.
0384  *
0385  *  Case 1 : 'retfunc' called by ESR registered for the
0386  *           INTERRUPT exception.
0387  *
0388  *  We assume an application has registered this ESR and wants
0389  *  YAMON to process the (remaining) interrupts.
0390  *
0391  *  Case 2 :  'retfunc' called by an ESR registered for a specific
0392  *        exception (not INTERRUPT).
0393  *
0394  *  Default handling will be done.
0395  *
0396  *  Case 3 : 'retfunc' is called by the ESR registered as default ESR.
0397  *
0398  *  The exception will be handled as though no ESR is registered
0399  *  (i.e. the "super default" function is called).
0400  *
0401  *  Parameters :
0402  *  ------------
0403  *
0404  *  'exception' (IN)  : Exception code
0405  *              or YAMON_DEFAULT_HANDLER for a default ESR
0406  *              or YAMON_DEFAULT_EJTAG_ESR for ejtag exceptions.
0407  *  'esr'       (IN)  : Function pointer for ESR.
0408  *  'ref'   (OUT) : Handle used for deregistration of ESR.
0409  *  'retfunc'   (OUT) : Pointer to function pointer for the return
0410  *          function described above.
0411  *
0412  *  Return values :
0413  *  ---------------
0414  *
0415  *  0 : Registration went well.
0416  *  Other values indicate error.
0417  *
0418  ************************************************************************/
0419 typedef t_yamon_int32
0420 (*t_yamon_register_esr)(
0421     t_yamon_uint32  exception,       /* Exception identification    */
0422     t_yamon_esr     esr,         /* ESR to be registered        */
0423     t_yamon_ref     *ref,        /* Handle for deregistration   */
0424     t_yamon_retfunc *retfunc );      /* Return function         */
0425
0426 #define YAMON_FUNC_REGISTER_ESR( exc, esr, ref, retfunc )\
0427     ((t_yamon_register_esr)( YAMON_FUNC(YAMON_FUNC_REGISTER_ESR_OFS) ))\
0428         ( exc, esr, ref, retfunc )
0429
0430
0431 /************************************************************************
0432  *
0433  *                          t_yamon_deregister_esr
0434  *  Description :
0435  *  -------------
0436  *
0437  *  Deregisters ESR..
0438  *
0439  *  Parameters :
0440  *  ------------
0441  *
0442  *  'ref' (IN) : Handle obtained when calling 'yamon_register_esr'.
0443  *
0444  *  Return values :
0445  *  ---------------
0446  *
0447  *  0 : Deregistration went well.
0448  *  Other values indicate error.
0449  *
0450  ************************************************************************/
0451 typedef t_yamon_int32
0452 (*t_yamon_deregister_esr)(
0453     t_yamon_ref ref );             /* Handle for deregistration     */
0454
0455 #define YAMON_FUNC_DEREGISTER_ESR( ref )\
0456     ((t_yamon_deregister_esr)( YAMON_FUNC(YAMON_FUNC_DEREGISTER_ESR_OFS) ))\
0457         ( ref )
0458
0459
0460 /************************************************************************
0461  *
0462  *                          t_yamon_register_cpu_isr
0463  *  Description :
0464  *  -------------
0465  *
0466  *  Registers an Interrupt Service Routine (ISR) for the specified
0467  *  CPU interrupt.
0468  *  The highest service priority is attached to HW-INT5, which is
0469  *  connected to the CPU-built-in CP0-timer. SW_INT0 gets the lowest
0470  *  service priority. During registration, the interrupt mask field
0471  *  in the CPU CP0-status register is updated to enable interrupts
0472  *  from the specified interrupt source.
0473  *
0474  *  A special ID is defined :
0475  *      YAMON_DEFAULT_HANDLER used for a default ISR.
0476  *
0477  *  The default ISR is called if no other ISR is registered
0478  *  for a CPU interrupt.
0479  *
0480  *  Deregistration of the default ISR may be done by calling
0481  *  this function with 'isr' set to NULL.
0482  *  Also, a new default ISR may be registered even if a
0483  *  previously registered ISR has not been deregistered.
0484  *  ISRs for specific CPU interrupts must be deregistered using
0485  *  'yamon_deregister_cpu_isr'.
0486  *
0487  *  Parameters :
0488  *  ------------
0489  *
0490  *  'cpu_int' (IN)  : CPU interrupt (0..7)
0491  *            or YAMON_DEFAULT_HANDLER for a default ISR.
0492  *  'isr'     (IN)  : Function pointer for ISR.
0493  *  'data'    (IN)  : Data pointer (may be NULL). Will be passed to
0494  *            ISR when called.
0495  *  'ref'     (OUT) : Handle used for deregistration of ISR.
0496  *
0497  *  Return values :
0498  *  ---------------
0499  *
0500  *  0 : Registration went well.
0501  *  Other values indicate error.
0502  *
0503  ************************************************************************/
0504 typedef t_yamon_int32
0505 (*t_yamon_register_cpu_isr)(
0506     t_yamon_uint32 cpu_int, /* CPU interrupt (0..7)         */
0507     t_yamon_isr    isr,     /* ISR to be registered         */
0508     void       *data,       /* Data reference to be registered  */
0509     t_yamon_ref    *ref );      /* Handle for deregistration        */
0510
0511 #define YAMON_FUNC_REGISTER_CPU_ISR( cpu_int, isr, data, ref )\
0512     ((t_yamon_register_cpu_isr)( YAMON_FUNC(YAMON_FUNC_REGISTER_CPU_ISR_OFS) ))\
0513         ( cpu_int, isr, data, ref )
0514
0515
0516 /************************************************************************
0517  *
0518  *                          t_yamon_deregister_cpu_isr
0519  *  Description :
0520  *  -------------
0521  *
0522  *  Deregisters ISR for CPU interrupt.
0523  *
0524  *  Parameters :
0525  *  ------------
0526  *
0527  *  'ref' (IN) : Handle obtained when calling 'yamon_register_cpu_isr'.
0528  *
0529  *  Return values :
0530  *  ---------------
0531  *
0532  *  0 : Deregistration went well.
0533  *  Other values indicate error
0534  *
0535  ************************************************************************/
0536 typedef t_yamon_int32
0537 (*t_yamon_deregister_cpu_isr)(
0538     t_yamon_ref ref );               /* Handle for deregistration   */
0539
0540 #define YAMON_FUNC_DEREGISTER_CPU_ISR( ref )\
0541     ((t_yamon_deregister_cpu_isr)( YAMON_FUNC(YAMON_FUNC_DEREGISTER_CPU_ISR_OFS) ))\
0542         ( ref )
0543
0544
0545 /************************************************************************
0546  *
0547  *                          t_yamon_register_ic_isr
0548  *  Description :
0549  *  -------------
0550  *
0551  *  Registers an Interrupt Service Routine (ISR) for the specified
0552  *  source in the interrupt controller.
0553  *
0554  *  A special ID is defined :
0555  *      YAMON_DEFAULT_HANDLER used for a default ISR.
0556  *
0557  *  The default ISR is called if no other ISR is registered
0558  *  for an interrupt.
0559  *
0560  *  Deregistration of the default ISR may be done by calling
0561  *  this function with 'isr' set to NULL.
0562  *  Also, a new default ISR may be registered even if a
0563  *  previously registered ISR has not been deregistered.
0564  *  ISRs for specific interrupts must be deregistered using
0565  *  'yamon_deregister_ic_isr'.
0566  *
0567  *  Parameters :
0568  *  ------------
0569  *
0570  *  'ic_line' (IN)  : Interrupt source line in Int. Controller
0571  *            or YAMON_DEFAULT_HANDLER for a default ISR.
0572  *  'isr',    (IN)  : Function pointer for user defined ISR.
0573  *  'data'    (IN)  : Data pointer (may be NULL). Will be passed to
0574  *            ISR when called.
0575  *  'ref',    (OUT) : Handle used for deregistration of ISR.
0576  *
0577  *  Return values :
0578  *  ---------------
0579  *
0580  *  0 : Registration went well.
0581  *  Other values indicate error.
0582  *
0583  ************************************************************************/
0584 typedef t_yamon_int32
0585 (*t_yamon_register_ic_isr)(
0586     t_yamon_uint32 ic_line,     /* Interrupt controller line    */
0587     t_yamon_isr    isr,         /* ISR to be registered     */
0588     void       *data,       /* Data reference to be registered  */
0589     t_yamon_ref    *ref );      /* Handle for deregistration    */
0590
0591 #define YAMON_FUNC_REGISTER_IC_ISR( ic_line, isr, data, ref )\
0592     ((t_yamon_register_ic_isr)( YAMON_FUNC(YAMON_FUNC_REGISTER_IC_ISR_OFS) ))\
0593         ( ic_line, isr, data, ref )
0594
0595
0596 /************************************************************************
0597  *
0598  *                          t_yamon_deregister_ic_isr
0599  *  Description :
0600  *  -------------
0601  *
0602  *  Deregisters ISR for source in interrupt controller.
0603  *
0604  *  Parameters :
0605  *  ------------
0606  *
0607  *  'ref' (IN) : Handle obtained when calling 'yamon_register_ic_isr'.
0608  *
0609  *  Return values :
0610  *  ---------------
0611  *
0612  *  0 : Deregistration went well.
0613  *  Other values indicate error
0614  *
0615  ************************************************************************/
0616 typedef t_yamon_int32
0617 (*t_yamon_deregister_ic_isr)(
0618     t_yamon_ref ref );               /* Handle for deregistration   */
0619
0620 #define YAMON_FUNC_DEREGISTER_IC_ISR( ref )\
0621     ((t_yamon_deregister_ic_isr)( YAMON_FUNC(YAMON_FUNC_DEREGISTER_IC_ISR_OFS) ))\
0622         ( ref )
0623
0624
0625 #endif /* #ifndef YAMON_API_H */
0626
0627
0628
0629
0630
0631