RTEMS: bsps/mips/rbtx4938/console/yamon_api.h Source File

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
yamon_api.h
1/************************************************************************
2 *
3 * yamon_api.h
4 *
5 * YAMON interface definitions
6 *
7 * ######################################################################
8 *
9 * mips_start_of_legal_notice
10 *
11 * Copyright (c) 2003 MIPS Technologies, Inc. All rights reserved.
12 *
13 *
14 * Unpublished rights (if any) reserved under the copyright laws of the
15 * United States of America and other countries.
16 *
17 * This code is proprietary to MIPS Technologies, Inc. ("MIPS
18 * Technologies"). Any copying, reproducing, modifying or use of this code
19 * (in whole or in part) that is not expressly permitted in writing by MIPS
20 * Technologies or an authorized third party is strictly prohibited. At a
21 * minimum, this code is protected under unfair competition and copyright
22 * laws. Violations thereof may result in criminal penalties and fines.
23 *
24 * MIPS Technologies reserves the right to change this code to improve
25 * function, design or otherwise. MIPS Technologies does not assume any
26 * liability arising out of the application or use of this code, or of any
27 * error or omission in such code. Any warranties, whether express,
28 * statutory, implied or otherwise, including but not limited to the implied
29 * warranties of merchantability or fitness for a particular purpose, are
30 * excluded. Except as expressly provided in any written license agreement
31 * from MIPS Technologies or an authorized third party, the furnishing of
32 * this code does not give recipient any license to any intellectual
33 * property rights, including any patent rights, that cover this code.
34 *
35 * This code shall not be exported or transferred for the purpose of
36 * reexporting in violation of any U.S. or non-U.S. regulation, treaty,
37 * Executive Order, law, statute, amendment or supplement thereto.
38 *
39 * This code constitutes one or more of the following: commercial computer
40 * software, commercial computer software documentation or other commercial
41 * items. If the user of this code, or any related documentation of any
42 * kind, including related technical data or manuals, is an agency,
43 * department, or other entity of the United States government
44 * ("Government"), the use, duplication, reproduction, release,
45 * modification, disclosure, or transfer of this code, or any related
46 * documentation of any kind, is restricted in accordance with Federal
47 * Acquisition Regulation 12.212 for civilian agencies and Defense Federal
48 * Acquisition Regulation Supplement 227.7202 for military agencies. The use
49 * of this code by the Government is further restricted in accordance with
50 * the terms of the license agreement(s) and/or applicable contract terms
51 * and conditions covering this code from MIPS Technologies or an authorized
52 * third party.
53 *
54 *
55 * mips_end_of_legal_notice
56 *
57 *
58 ************************************************************************/
59
60#ifndef YAMON_API_H
61#define YAMON_API_H
62
63/************************************************************************
64 * Include files
65 ************************************************************************/
66
67
68/************************************************************************
69 * Definitions
70*************************************************************************/
71
72/* Basic types */
73
74typedef unsigned int t_yamon_uint32;
75typedef unsigned short t_yamon_uint16;
76typedef unsigned char t_yamon_uint8;
77typedef signed int t_yamon_int32;
78typedef signed short t_yamon_int16;
79typedef signed char t_yamon_int8;
80
81typedef unsigned char t_yamon_bool;
82
83#define YAMON_FALSE 0
84#define YAMON_TRUE (!YAMON_FALSE)
85
86/* YAMON Environment variable */
87typedef struct
88{
89 char *name;
90 char *val;
91}
92 t_yamon_env_var;
93
94/* Format of application function */
95typedef t_yamon_uint32
96(*t_yamon_appl_main)(
97 t_yamon_uint32 argc, /* Number of tokens in argv array */
98 char **argv, /* Array of tokens (first is "go") */
99 t_yamon_env_var *env, /* Array of env. variables */
100 t_yamon_uint32 memsize ); /* Size of memory (byte count) */
101
102
103/* ID of YAMON configuration object */
104typedef t_yamon_uint32 t_yamon_syscon_id;
105
106
107/* Number used by the exception registration functions in order to register
108 * a default ISR/ESR.
109 */
110#define YAMON_DEFAULT_HANDLER 0xfffffff0
111
112/* Number used by the exception registration functions in order to register
113 * an EJTAG debug exception ESR.
114 */
115#define YAMON_DEFAULT_EJTAG_ESR 0xfffffff1
116
117/* Registered Interrupt Service Routine (ISR) */
118typedef void (*t_yamon_isr)(void *data);
119
120/* Registered Exception Service Routine (ESR) */
121typedef void (*t_yamon_esr)(void);
122
123/* Entry point called by ESRs wishing to pass control back to YAMON */
124typedef void (*t_yamon_retfunc)(void);
125
126/* Handle used for deregistration of ISR/ESR */
127typedef void *t_yamon_ref;
128
129
130/* YAMONE Vector table address */
131#define YAMON_FUNCTION_BASE 0x9fc00500
132
133/* YAMON Vector table offsets */
134#define YAMON_FUNC_PRINT_COUNT_OFS 0x04
135#define YAMON_FUNC_EXIT_OFS 0x20
136#define YAMON_FUNC_FLUSH_CACHE_OFS 0x2C
137#define YAMON_FUNC_PRINT_OFS 0x34
138#define YAMON_FUNC_REGISTER_CPU_ISR_OFS 0x38
139#define YAMON_FUNC_DEREGISTER_CPU_ISR_OFS 0x3c
140#define YAMON_FUNC_REGISTER_IC_ISR_OFS 0x40
141#define YAMON_FUNC_DEREGISTER_IC_ISR_OFS 0x44
142#define YAMON_FUNC_REGISTER_ESR_OFS 0x48
143#define YAMON_FUNC_DEREGISTER_ESR_OFS 0x4c
144#define YAMON_FUNC_GETCHAR_OFS 0x50
145#define YAMON_FUNC_SYSCON_READ_OFS 0x54
146
147/* Macro for accessing YAMON function */
148#define YAMON_FUNC(ofs)\
149 (*(t_yamon_uint32 *)(YAMON_FUNCTION_BASE + (ofs)))
150
151
152/************************************************************************
153 * Public variables
154 ************************************************************************/
155
156/************************************************************************
157 * Public functions
158 ************************************************************************/
159
160
161/************************************************************************
162 *
163 * t_yamon_exit
164 * Description :
165 * -------------
166 *
167 * Exit application and return to YAMON.
168 *
169 * Parameters :
170 * ------------
171 *
172 * 'rc' (OUT) : Return code
173 *
174 * Return values :
175 * ---------------
176 *
177 * None (never returns)
178 *
179 ************************************************************************/
180typedef void
181(*t_yamon_exit)(
182 t_yamon_uint32 rc ); /* Return code */
183
184#define YAMON_FUNC_EXIT( rc )\
185 ((t_yamon_exit)( YAMON_FUNC(YAMON_FUNC_EXIT_OFS) ))\
186 ( rc )
187
188
189/************************************************************************
190 *
191 * t_yamon_print
192 * Description :
193 * -------------
194 *
195 * Print null-terminated string to tty0.
196 *
197 * Parameters :
198 * ------------
199 *
200 * 'port' (OUT) : Ignored, always prints to tty0. Not included in macro.
201 * 's' (OUT) : String to print.
202 *
203 * Return values :
204 * ---------------
205 *
206 * None
207 *
208 ************************************************************************/
209typedef void
210(*t_yamon_print)(
211 t_yamon_uint32 port, /* Output port (not used, always tty0) */
212 const char *s ); /* String to output */
213
214#define YAMON_FUNC_PRINT( s )\
215 ((t_yamon_print)( YAMON_FUNC(YAMON_FUNC_PRINT_OFS) ))\
216 ( 0, s )
217
218
219/************************************************************************
220 *
221 * t_yamon_print_count
222 * Description :
223 * -------------
224 *
225 * Print specified number of characters to tty0.
226 *
227 * Parameters :
228 * ------------
229 *
230 * 'port' (OUT) : Ignored, always prints to tty0. Not included in macro.
231 * 's' (OUT) : Array of characters to print.
232 * 'count' (OUT) : Number of characters to print.
233 *
234 * Return values :
235 * ---------------
236 *
237 * None
238 *
239 ************************************************************************/
240typedef void
241(*t_yamon_print_count)(
242 t_yamon_uint32 port, /* Output port (not used, always tty0 */
243 char *s, /* String to output */
244 t_yamon_uint32 count ); /* Number of characters to output */
245
246#define YAMON_FUNC_PRINT_COUNT( s, count )\
247 ((t_yamon_print_count)( YAMON_FUNC(YAMON_FUNC_PRINT_COUNT_OFS) ))\
248 ( 0, s, count )
249
250
251/************************************************************************
252 *
253 * t_yamon_getchar
254 * Description :
255 * -------------
256 *
257 * Get character from tty0 if character is available. Function
258 * returns immediately if no character is available.
259 *
260 * Parameters :
261 * ------------
262 *
263 * 'port' (OUT) : Ignored, always uses tty0. Not included in macro.
264 * 'ch' (OUT) : Character read (if available).
265 *
266 * Return values :
267 * ---------------
268 *
269 * YAMON_TRUE if character was available, else YAMON_FALSE.
270 *
271 ************************************************************************/
272typedef t_yamon_bool
273(*t_yamon_getchar)(
274 t_yamon_uint32 port, /* Output port (not used, always tty0 */
275 char *ch ); /* Character to output */
276
277#define YAMON_FUNC_GETCHAR( ch )\
278 ((t_yamon_getchar)( YAMON_FUNC(YAMON_FUNC_GETCHAR_OFS) ))\
279 ( 0, ch )
280
281
282/************************************************************************
283 *
284 * t_yamon_syscon_read
285 * Description :
286 * -------------
287 *
288 * Read the value of system configuration object given by 'id'.
289 *
290 * See syscon_api.h in YAMON source distribution for further details
291 * on object IDs and error codes.
292 *
293 * Parameters :
294 * ------------
295 *
296 * 'id' (IN) : Object id.
297 * 'param' (INOUT) : Buffer for object value.
298 * 'size' (IN) : Size of buffer (must match size of object).
299 *
300 * Return values :
301 * ---------------
302 *
303 * 0 : Returned parameter is valid.
304 * Other values indicate error.
305 *
306 ************************************************************************/
307typedef t_yamon_int32
308(*t_yamon_syscon_read)(
309 t_yamon_syscon_id id, /* Object ID */
310 void *param, /* Buffer for object value */
311 t_yamon_uint32 size); /* Buffer size (bytes) */
312
313#define YAMON_FUNC_SYSCON_READ( id, param, size )\
314 ((t_yamon_syscon_read)( YAMON_FUNC(YAMON_FUNC_SYSCON_READ_OFS) ))\
315 ( id, param, size )
316
317
318/************************************************************************
319 *
320 * t_yamon_flush_cache
321 * Description :
322 * -------------
323 *
324 * Flush I-or D-cache
325 *
326 * Function performs "writeback and invalidate" operations on D-cache
327 * lines and "invalidate" operations on I-cache lines.
328 *
329 * Parameters :
330 * ------------
331 *
332 * 'type' (IN) : Cache to be flushed.
333 *
334 * Return values :
335 * ---------------
336 *
337 * None
338 *
339 ************************************************************************/
340typedef void
341(*t_yamon_flush_cache)(
342#define YAMON_FLUSH_ICACHE 0
343#define YAMON_FLUSH_DCACHE 1
344 t_yamon_uint32 type ); /* I- or D-cache indication */
345
346#define YAMON_FUNC_FLUSH_CACHE( type )\
347 ((t_yamon_flush_cache)( YAMON_FUNC(YAMON_FUNC_FLUSH_CACHE_OFS) ))\
348 ( type )
349
350
351/************************************************************************
352 *
353 * t_yamon_register_esr
354 * Description :
355 * -------------
356 *
357 * Registers an exception handler, also known as an "Exception Service
358 * Routine" (ESR) for the specified exception.
359 *
360 * Two special exception IDs are defined :
361 * YAMON_DEFAULT_HANDLER used for a default ESR.
362 * YAMON_DEFAULT_EJTAG_ESR used for EJTAG exceptions.
363 *
364 * The default ESR is called if no other ESR is registered
365 * for an exception. If no default ESR is registered, a static
366 * (i.e. not registered) "super default" function is invoked.
367 * This function prints out the registers and halts.
368 *
369 * Deregistration of an ESR may be be done by calling this function
370 * with 'esr' set to NULL.
371 * An ESR can also be deregistered using the 'yamon_deregister_esr'
372 * function.
373 *
374 * An ESR may be registered even if a previously registered
375 * ESR has not been deregistered. In this case the previously
376 * registered ESR is lost.
377 *
378 * The ESR will get called with registers in the state they were
379 * when the exception occurred. This includes all CP0 registers and
380 * CPU registers $0..$31, except for k0,k1 ($26,$27).
381 *
382 * In case an ESR does not want to handle the exception, it may
383 * call the return function passed in the 'retfunc' parameter.
384 *
385 * Case 1 : 'retfunc' called by ESR registered for the
386 * INTERRUPT exception.
387 *
388 * We assume an application has registered this ESR and wants
389 * YAMON to process the (remaining) interrupts.
390 *
391 * Case 2 : 'retfunc' called by an ESR registered for a specific
392 * exception (not INTERRUPT).
393 *
394 * Default handling will be done.
395 *
396 * Case 3 : 'retfunc' is called by the ESR registered as default ESR.
397 *
398 * The exception will be handled as though no ESR is registered
399 * (i.e. the "super default" function is called).
400 *
401 * Parameters :
402 * ------------
403 *
404 * 'exception' (IN) : Exception code
405 * or YAMON_DEFAULT_HANDLER for a default ESR
406 * or YAMON_DEFAULT_EJTAG_ESR for ejtag exceptions.
407 * 'esr' (IN) : Function pointer for ESR.
408 * 'ref' (OUT) : Handle used for deregistration of ESR.
409 * 'retfunc' (OUT) : Pointer to function pointer for the return
410 * function described above.
411 *
412 * Return values :
413 * ---------------
414 *
415 * 0 : Registration went well.
416 * Other values indicate error.
417 *
418 ************************************************************************/
419typedef t_yamon_int32
420(*t_yamon_register_esr)(
421 t_yamon_uint32 exception, /* Exception identification */
422 t_yamon_esr esr, /* ESR to be registered */
423 t_yamon_ref *ref, /* Handle for deregistration */
424 t_yamon_retfunc *retfunc ); /* Return function */
425
426#define YAMON_FUNC_REGISTER_ESR( exc, esr, ref, retfunc )\
427 ((t_yamon_register_esr)( YAMON_FUNC(YAMON_FUNC_REGISTER_ESR_OFS) ))\
428 ( exc, esr, ref, retfunc )
429
430
431/************************************************************************
432 *
433 * t_yamon_deregister_esr
434 * Description :
435 * -------------
436 *
437 * Deregisters ESR..
438 *
439 * Parameters :
440 * ------------
441 *
442 * 'ref' (IN) : Handle obtained when calling 'yamon_register_esr'.
443 *
444 * Return values :
445 * ---------------
446 *
447 * 0 : Deregistration went well.
448 * Other values indicate error.
449 *
450 ************************************************************************/
451typedef t_yamon_int32
452(*t_yamon_deregister_esr)(
453 t_yamon_ref ref ); /* Handle for deregistration */
454
455#define YAMON_FUNC_DEREGISTER_ESR( ref )\
456 ((t_yamon_deregister_esr)( YAMON_FUNC(YAMON_FUNC_DEREGISTER_ESR_OFS) ))\
457 ( ref )
458
459
460/************************************************************************
461 *
462 * t_yamon_register_cpu_isr
463 * Description :
464 * -------------
465 *
466 * Registers an Interrupt Service Routine (ISR) for the specified
467 * CPU interrupt.
468 * The highest service priority is attached to HW-INT5, which is
469 * connected to the CPU-built-in CP0-timer. SW_INT0 gets the lowest
470 * service priority. During registration, the interrupt mask field
471 * in the CPU CP0-status register is updated to enable interrupts
472 * from the specified interrupt source.
473 *
474 * A special ID is defined :
475 * YAMON_DEFAULT_HANDLER used for a default ISR.
476 *
477 * The default ISR is called if no other ISR is registered
478 * for a CPU interrupt.
479 *
480 * Deregistration of the default ISR may be done by calling
481 * this function with 'isr' set to NULL.
482 * Also, a new default ISR may be registered even if a
483 * previously registered ISR has not been deregistered.
484 * ISRs for specific CPU interrupts must be deregistered using
485 * 'yamon_deregister_cpu_isr'.
486 *
487 * Parameters :
488 * ------------
489 *
490 * 'cpu_int' (IN) : CPU interrupt (0..7)
491 * or YAMON_DEFAULT_HANDLER for a default ISR.
492 * 'isr' (IN) : Function pointer for ISR.
493 * 'data' (IN) : Data pointer (may be NULL). Will be passed to
494 * ISR when called.
495 * 'ref' (OUT) : Handle used for deregistration of ISR.
496 *
497 * Return values :
498 * ---------------
499 *
500 * 0 : Registration went well.
501 * Other values indicate error.
502 *
503 ************************************************************************/
504typedef t_yamon_int32
505(*t_yamon_register_cpu_isr)(
506 t_yamon_uint32 cpu_int, /* CPU interrupt (0..7) */
507 t_yamon_isr isr, /* ISR to be registered */
508 void *data, /* Data reference to be registered */
509 t_yamon_ref *ref ); /* Handle for deregistration */
510
511#define YAMON_FUNC_REGISTER_CPU_ISR( cpu_int, isr, data, ref )\
512 ((t_yamon_register_cpu_isr)( YAMON_FUNC(YAMON_FUNC_REGISTER_CPU_ISR_OFS) ))\
513 ( cpu_int, isr, data, ref )
514
515
516/************************************************************************
517 *
518 * t_yamon_deregister_cpu_isr
519 * Description :
520 * -------------
521 *
522 * Deregisters ISR for CPU interrupt.
523 *
524 * Parameters :
525 * ------------
526 *
527 * 'ref' (IN) : Handle obtained when calling 'yamon_register_cpu_isr'.
528 *
529 * Return values :
530 * ---------------
531 *
532 * 0 : Deregistration went well.
533 * Other values indicate error
534 *
535 ************************************************************************/
536typedef t_yamon_int32
537(*t_yamon_deregister_cpu_isr)(
538 t_yamon_ref ref ); /* Handle for deregistration */
539
540#define YAMON_FUNC_DEREGISTER_CPU_ISR( ref )\
541 ((t_yamon_deregister_cpu_isr)( YAMON_FUNC(YAMON_FUNC_DEREGISTER_CPU_ISR_OFS) ))\
542 ( ref )
543
544
545/************************************************************************
546 *
547 * t_yamon_register_ic_isr
548 * Description :
549 * -------------
550 *
551 * Registers an Interrupt Service Routine (ISR) for the specified
552 * source in the interrupt controller.
553 *
554 * A special ID is defined :
555 * YAMON_DEFAULT_HANDLER used for a default ISR.
556 *
557 * The default ISR is called if no other ISR is registered
558 * for an interrupt.
559 *
560 * Deregistration of the default ISR may be done by calling
561 * this function with 'isr' set to NULL.
562 * Also, a new default ISR may be registered even if a
563 * previously registered ISR has not been deregistered.
564 * ISRs for specific interrupts must be deregistered using
565 * 'yamon_deregister_ic_isr'.
566 *
567 * Parameters :
568 * ------------
569 *
570 * 'ic_line' (IN) : Interrupt source line in Int. Controller
571 * or YAMON_DEFAULT_HANDLER for a default ISR.
572 * 'isr', (IN) : Function pointer for user defined ISR.
573 * 'data' (IN) : Data pointer (may be NULL). Will be passed to
574 * ISR when called.
575 * 'ref', (OUT) : Handle used for deregistration of ISR.
576 *
577 * Return values :
578 * ---------------
579 *
580 * 0 : Registration went well.
581 * Other values indicate error.
582 *
583 ************************************************************************/
584typedef t_yamon_int32
585(*t_yamon_register_ic_isr)(
586 t_yamon_uint32 ic_line, /* Interrupt controller line */
587 t_yamon_isr isr, /* ISR to be registered */
588 void *data, /* Data reference to be registered */
589 t_yamon_ref *ref ); /* Handle for deregistration */
590
591#define YAMON_FUNC_REGISTER_IC_ISR( ic_line, isr, data, ref )\
592 ((t_yamon_register_ic_isr)( YAMON_FUNC(YAMON_FUNC_REGISTER_IC_ISR_OFS) ))\
593 ( ic_line, isr, data, ref )
594
595
596/************************************************************************
597 *
598 * t_yamon_deregister_ic_isr
599 * Description :
600 * -------------
601 *
602 * Deregisters ISR for source in interrupt controller.
603 *
604 * Parameters :
605 * ------------
606 *
607 * 'ref' (IN) : Handle obtained when calling 'yamon_register_ic_isr'.
608 *
609 * Return values :
610 * ---------------
611 *
612 * 0 : Deregistration went well.
613 * Other values indicate error
614 *
615 ************************************************************************/
616typedef t_yamon_int32
617(*t_yamon_deregister_ic_isr)(
618 t_yamon_ref ref ); /* Handle for deregistration */
619
620#define YAMON_FUNC_DEREGISTER_IC_ISR( ref )\
621 ((t_yamon_deregister_ic_isr)( YAMON_FUNC(YAMON_FUNC_DEREGISTER_IC_ISR_OFS) ))\
622 ( ref )
623
624
625#endif /* #ifndef YAMON_API_H */
626
627
628
629
630
631
env
Definition: main_edit.c:207
t_yamon_env_var
Definition: yamon_api.h:88