1 /*
2 * Copyright (c) 2015, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32 /*
33 * ======== IHwi.xdc ========
34 *
35 */
36
37 import xdc.runtime.Error;
38
39
40 /*!
41 * ======== Hwi ========
42 * Hardware Interrupt Support Module.
43 *
44 * The IHwi interface specifies APIs for globally enabling, disabling, and
45 * restoring interrupts.
46 *
47 * Additionally, management of individual, device-specific hardware
48 * interrupts is provided.
49 *
50 * The user can statically or dynamically assign routines that run when
51 * specific hardware interrupts occur.
52 *
53 * Dynamic assignment of Hwi routines to interrupts at run-time is done
54 * using the Hwi_create function.
55 *
56 * Interrupt routines can be written completely in C, completely in
57 * assembly, or in a mix of C and assembly. In order to support interrupt
58 * routines
59 * written completely in C, an interrupt dispatcher is provided that performs
60 * the requisite prolog and epilog for an interrupt routine.
61 *
62 * Some routines are assigned to interrupts by the other SYS/BIOS
63 * modules. For example, the Clock module configures its own timer interrupt
64 * handler. See the Clock Module for more details.
65 *
66 * @a(Runtime Hwi Creation) 67 *
68 * Below is an example of configuring an interrupt at runtime.
69 * Usually this code would be placed in main().
70 *
71 * @p(code) 72 * #include <xdc/runtime/Error.h>
73 * #include <ti/sysbios/hal/Hwi.h>
74 *
75 * Hwi_Handle myHwi;
76 *
77 * Int main(Int argc, char* argv[])
78 * {
79 * Hwi_Params hwiParams;
80 * Error_Block eb;
81 *
82 * Hwi_Params_init(&hwiParams);
83 * Error_init(&eb);
84 *
85 * // set the argument you want passed to your ISR function
86 * hwiParams.arg = 1;
87 *
88 * // set the event id of the peripheral assigned to this interrupt
89 * hwiParams.eventId = 10;
90 *
91 * // don't allow this interrupt to nest itself
92 * hwiParams.maskSetting = Hwi_MaskingOption_SELF;
93 *
94 * //
95 * // Configure interrupt 5 to invoke "myIsr".
96 * // Automatically enables interrupt 5 by default
97 * // set params.enableInt = FALSE if you want to control
98 * // when the interrupt is enabled using Hwi_enableInterrupt()
99 * //
100 *
101 * myHwi = Hwi_create(5, myIsr, &hwiParams, &eb);
102 *
103 * if (Error_check(&eb)) {
104 * // handle the error
105 * }
106 * }
107 *
108 * Void myIsr(UArg arg)
109 * {
110 * // here when interrupt #5 goes off
111 * }
112 * @p 113 *
114 * @a(Hook Functions) 115 *
116 * Sets of hook functions can be specified for the Hwi module
117 * using the configuration tool. Each set contains these hook
118 * functions:
119 * @p(blist) 120 * -Register: A function called before any statically-created Hwis
121 * are initialized at runtime. The register hook is called at boot time
122 * before main() and before interrupts are enabled.
123 * -Create: A function that is called when a Hwi is created.
124 * This includes hwis that are created statically and those
125 * created dynamically using {@link #create Hwi_create}.
126 * -Begin: A function that is called just prior to running a Hwi.
127 * -End: A function that is called just after a Hwi finishes.
128 * -Delete: A function that is called when a Hwi is deleted at
129 * run-time with {@link #delete Hwi_delete}.
130 * @p 131 *
132 * Register Function
133 *
134 * The Register function is provided to allow a hook set to store its
135 * hookset ID. This id can be passed to
136 * {@link #setHookContext Hwi_setHookContext} and
137 * {@link #getHookContext Hwi_getHookContext} to set or get
138 * hookset-specific context. The
139 * Register function must be specified if the hook implementation
140 * needs to use {@link #setHookContext Hwi_setHookContext} or
141 * {@link #getHookContext Hwi_getHookContext}.
142 * The registerFxn hook function is called during system initialization
143 * before interrupts have been enabled.
144 *
145 * @p(code) 146 * Void myRegisterFxn(Int id);
147 * @p 148 *
149 * Create and Delete Functions
150 *
151 * The create and delete functions are called whenever a Hwi is created
152 * or deleted. They are called with interrupts enabled (unless called
153 * at boot time or from main()).
154 *
155 * @p(code) 156 * Void myCreateFxn(Hwi_Handle hwi, Error_Block *eb);
157 * @p 158 *
159 * @p(code) 160 * Void myDeleteFxn(Hwi_Handle hwi);
161 * @p 162 *
163 * Begin and End Functions
164 *
165 * The beginFxn and endFxn function hooks are called with interrupts
166 * globally disabled, therefore any hook processing function will contribute
167 * to the overall system interrupt response latency. In order to minimize
168 * this impact, carefully consider the processing time spent in an Hwi
169 * beginFxn or endFxn function hook.
170 *
171 * @p(code) 172 * Void myBeginFxn(Hwi_Handle hwi);
173 * @p 174 *
175 * @p(code) 176 * Void myEndFxn(Hwi_Handle hwi);
177 * @p 178 *
179 * Hook functions can only be configured statically.
180 */
181
182 @DirectCall
183 @InstanceFinalize
184 @InstanceInitError
185
186 interface IHwi {
187
188 // -------- Module Types --------
189
190 /*! Hwi create function type definition. */
191 typedef Void (*FuncPtr)(UArg);
192
193 /*!
194 * Interrupt Return Pointer.
195 *
196 * This is the address of the interrupted instruction.
197 */
198 typedef UArg Irp;
199
200 /*!
201 * Hwi hook set type definition.
202 *
203 * The functions that make up a hookSet have certain restrictions. They
204 * cannot call any Hwi instance functions other than Hwi_getHookContext()
205 * and Hwi_setHookContext(). For all practical purposes, they should treat
206 * the Hwi_Handle passed to these functions as an opaque handle.
207 */
208 struct HookSet {
209 Void (*registerFxn)(Int);
210 Void (*createFxn)(Handle, Error.Block *);
211 Void (*beginFxn)(Handle);
212 Void (*endFxn)(Handle);
213 Void (*deleteFxn)(Handle);
214 };
215
216 /*!
217 * ======== MaskingOption ========
218 * Shorthand interrupt masking options
219 *
220 * @value(MaskingOption_NONE) No interrupts are disabled
221 *
222 * @value(MaskingOption_ALL) All interrupts are disabled
223 *
224 * @value(MaskingOption_SELF) Only this interrupt is disabled
225 *
226 * @value(MaskingOption_BITMASK) User supplies interrupt enable masks
227 *
228 * @value(MaskingOption_LOWER) All current and lower priority
229 * interrupts are disabled.
230 *
231 * Only a few targets/devices truly
232 * support this masking option. For those
233 * that don't, this setting is treated
234 * the same as MaskingOption_SELF.
235 */
236 enum MaskingOption {
237 MaskingOption_NONE,
238 MaskingOption_ALL,
239 MaskingOption_SELF,
240 MaskingOption_BITMASK,
241 MaskingOption_LOWER
242 };
243
244 /*!
245 * ======== StackInfo ========
246 * Structure contains Hwi stack usage info
247 *
248 * Used by getStackInfo() and viewGetStackInfo() functions
249 */
250 struct StackInfo {
251 SizeT hwiStackPeak;
252 SizeT hwiStackSize;
253 Ptr hwiStackBase;
254 };
255
256 // -------- Module Parameters --------
257
258 /*!
259 * Include interrupt nesting logic in interrupt dispatcher?
260 *
261 * Default is true.
262 *
263 * This option provides the user with the ability to optimize
264 * interrupt dispatcher performance when support for interrupt
265 * nesting is not required.
266 *
267 * Setting this parameter to false will disable the logic in
268 * the interrupt dispatcher that manipulates interrupt mask
269 * registers and enables and disables interrupts before and
270 * after invoking the user's Hwi function.
271 *
272 * Set this parameter to false if you don't need interrupts
273 * enabled during the execution of your Hwi functions.
274 */
275 config Bool dispatcherAutoNestingSupport = true;
276
277 /*!
278 * Include Swi scheduling logic in interrupt dispatcher?
279 *
280 * Default is inherited from {@link ti.sysbios.BIOS#swiEnabled
281 * BIOS.swiEnabled}, which is true by default.
282 *
283 * This option provides the user with the ability to optimize
284 * interrupt dispatcher performance when it is known that Swis
285 * will not be posted from any of their Hwi threads.
286 *
287 * Setting this parameter to false will disable the logic in
288 * the interrupt dispatcher that invokes the Swi scheduler
289 * prior to returning from an interrupt.
290 */
291 config Bool dispatcherSwiSupport;
292
293 /*!
294 * Include Task scheduling logic in interrupt dispatcher?
295 *
296 * Default is inherited from {@link ti.sysbios.BIOS#taskEnabled
297 * BIOS.taskEnabled}, which is true by default.
298 *
299 * This option provides the user with the ability to optimize
300 * interrupt dispatcher performance when it is known that no
301 * Task scheduling APIs (ie {@link ti.sysbios.knl.Semaphore#post
302 * Semaphore_post()}) will be executed from any of their Hwi threads.
303 *
304 * Setting this parameter to false will disable the logic in
305 * the interrupt dispatcher that invokes the Task scheduler
306 * prior to returning from an interrupt.
307 */
308 config Bool dispatcherTaskSupport;
309
310 /*!
311 * Controls whether the
312 * dispatcher retains the interrupted thread's return address.
313 *
314 * This option is enabled by default.
315 *
316 * Setting this parameter to false will disable the logic in
317 * the interrupt dispatcher that keeps track of the interrupt's
318 * return address and provide a small savings in interrupt latency.
319 *
320 * The application can get an interrupt's most recent return
321 * address using the {@link #getIrp} API.
322 */
323 config Bool dispatcherIrpTrackingSupport = true;
324
325 // -------- Module Functions --------
326
327 /*!
328 * ======== addHookSet ========
329 * addHookSet is used in a config file to add a hook set (defined
330 * by struct HookSet).
331 *
332 * HookSet structure elements may be omitted, in which case those
333 * elements will not exist.
334 *
335 * @param(hook) structure of type HookSet
336 */
337 metaonly Void addHookSet(HookSet hook);
338
339 /*!
340 * ======== viewGetStackInfo ========
341 * @_nodoc 342 * Returns the Hwi stack usage info. Used at ROV time.
343 *
344 * @b(returns) Hwi stack base, size, peak
345 */
346 metaonly StackInfo viewGetStackInfo();
347
348 /*!
349 * ======== getStackInfo ========
350 * Get Hwi stack usage Info.
351 *
352 * getStackInfo returns the Hwi stack usage info to its calling
353 * function by filling stack base address, stack size and stack
354 * peak fields in the {@link #StackInfo} structure.
355 *
356 * getStackInfo accepts two arguments, a pointer to a structure
357 * of type {@link #StackInfo} and a boolean. If the boolean is set
358 * to true, the function computes the stack depth and fills the
359 * stack peak field in the StackInfo structure. If a stack overflow
360 * is detected, the stack depth is not computed. If the boolean is
361 * set to false, the function only checks for a stack overflow.
362 *
363 * The isr stack is always checked for an overflow and a boolean
364 * is returned to indicate whether an overflow occured.
365 *
366 * Below is an example of calling getStackInfo() API:
367 *
368 * @p(code) 369 * #include <ti/sysbios/BIOS.h>
370 * #include <ti/sysbios/hal/Hwi.h>
371 * #include <ti/sysbios/knl/Swi.h>
372 * #include <ti/sysbios/knl/Task.h>
373 *
374 * Swi_Handle swi0;
375 * volatile Bool swiStackOverflow = FALSE;
376 *
377 * Void swi0Fxn(UArg arg1, UArg arg2)
378 * {
379 * Hwi_StackInfo stkInfo;
380 *
381 * // Request stack depth
382 * swiStackOverflow = Hwi_getStackInfo(&stkInfo, TRUE);
383 *
384 * // Alternately, we can omit the request for stack depth and
385 * // request only the stack base and stack size (the check for
386 * // stack overflow is always performed):
387 * //
388 * // swiStackOverflow = Hwi_getStackInfo(&stkInfo, FALSE);
389 *
390 * if (swiStackOverflow) {
391 * // isr Stack Overflow detected
392 * }
393 * }
394 *
395 * Void idleTask()
396 * {
397 * Swi_post(swi0);
398 * }
399 *
400 * Int main(Int argc, char* argv[])
401 * {
402 * swi0 = Swi_create(swi0Fxn, NULL, NULL);
403 *
404 * BIOS_start();
405 * return (0);
406 * }
407 * @p 408 *
409 * @param(stkInfo) pointer to structure of type {@link #StackInfo}
410 * @param(computeStackDepth) decides whether to compute stack depth
411 *
412 * @b(returns) boolean to indicate a stack overflow
413 */
414 Bool getStackInfo(StackInfo *stkInfo, Bool computeStackDepth);
415
416 /*!
417 * ======== getCoreStackInfo ========
418 * Get Hwi stack usage Info for the specified coreId.
419 *
420 * getCoreStackInfo returns the Hwi stack usage info for the specified
421 * coreId to its calling function by filling stack base address,
422 * stack size and stack peak fields in the {@link #StackInfo} structure.
423 *
424 * This function should be used only in applications built with
425 * {@link ti.sysbios.BIOS#smpEnabled} set to true.
426 *
427 * getCoreStackInfo accepts three arguments, a pointer to a structure
428 * of type {@link #StackInfo}, a boolean and a coreId. If the boolean
429 * is set to true, the function computes the stack depth and fills the
430 * stack peak field in the StackInfo structure. If a stack overflow
431 * is detected, the stack depth is not computed. If the boolean is
432 * set to false, the function only checks for a stack overflow.
433 *
434 * The isr stack is always checked for an overflow and a boolean
435 * is returned to indicate whether an overflow occured.
436 *
437 * Below is an example of calling getCoreStackInfo() API:
438 *
439 * @p(code) 440 * #include <ti/sysbios/BIOS.h>
441 * #include <ti/sysbios/hal/Hwi.h>
442 * #include <ti/sysbios/hal/Core.h>
443 * #include <ti/sysbios/knl/Task.h>
444 *
445 * ...
446 *
447 * Void idleTask()
448 * {
449 * UInt idx;
450 * Hwi_StackInfo stkInfo;
451 * Bool stackOverflow = FALSE;
452 *
453 * // Request stack depth for each core's Hwi stack and check for
454 * // overflow
455 * for (idx = 0; idx < Core_numCores; idx++) {
456 * stackOverflow = Hwi_getCoreStackInfo(&stkInfo, TRUE, idx);
457 *
458 * // Alternately, we can omit the request for stack depth and
459 * // request only the stack base and stack size (the check for
460 * // stack overflow is always performed):
461 * //
462 * // stackOverflow = Hwi_getCoreStackInfo(&stkInfo, FALSE, idx);
463 *
464 * if (stackOverflow) {
465 * // isr Stack Overflow detected
466 * }
467 * }
468 * }
469 *
470 * Int main(Int argc, char* argv[])
471 * {
472 * ...
473 * BIOS_start();
474 * return (0);
475 * }
476 * @p 477 *
478 * @param(stkInfo) pointer to structure of type {@link #StackInfo}
479 * @param(computeStackDepth) decides whether to compute stack depth
480 * @param(coreId) core whose stack info needs to be retrieved
481 *
482 * @b(returns) boolean to indicate a stack overflow
483 */
484 Bool getCoreStackInfo(StackInfo *stkInfo, Bool computeStackDepth,
485 UInt coreId);
486
487 /*!
488 * ======== startup ========
489 * Initially enable interrupts
490 *
491 * Called within BIOS_start
492 */
493 Void startup();
494
495 /*!
496 * ======== disable ========
497 */
498 UInt disable();
499
500 /*!
501 * ======== enable ========
502 * Globally enable interrupts.
503 *
504 * Hwi_enable globally enables hardware interrupts and returns an
505 * opaque key indicating whether interrupts were globally enabled or
506 * disabled on entry to Hwi_enable().
507 * The actual value of the key is target/device specific and is meant
508 * to be passed to Hwi_restore().
509 *
510 *
511 * This function is
512 * called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
513 *
514 * Hardware interrupts are enabled unless a call to Hwi_disable disables
515 * them.
516 *
517 * Servicing of interrupts that occur while interrupts are disabled is
518 * postponed until interrupts are reenabled. However, if the same type
519 * of interrupt occurs several times while interrupts are disabled,
520 * the interrupt's function is executed only once when interrupts are
521 * reenabled.
522 *
523 * A context switch can occur when calling Hwi_enable or Hwi_restore if
524 * an enabled interrupt occurred while interrupts are disabled.
525 *
526 * Any call to Hwi_enable enables interrupts, even if Hwi_disable has
527 * been called several times.
528 *
529 * Hwi_enable must not be called from main().
530 *
531 * @b(returns) opaque key for use by Hwi_restore()
532 */
533 UInt enable();
534
535 /*!
536 * ======== restore ========
537 * Globally restore interrupts.
538 *
539 * Hwi_restore globally restores interrupts to the state determined
540 * by the key argument provided by a previous invocation of Hwi_disable.
541 *
542 * A context switch may occur when calling Hwi_restore if Hwi_restore
543 * reenables interrupts and another Hwi occurred while interrupts were
544 * disabled.
545 *
546 * Hwi_restore may be called from main(). However, since Hwi_enable
547 * cannot be called from main(), interrupts are always disabled in
548 * main(), and a call to Hwi_restore has no effect.
549 *
550 * @param(key) enable/disable state to restore
551 */
552 Void restore(UInt key);
553
554 /*!
555 * @_nodoc 556 * ======== switchFromBootStack ========
557 * Indicate that we are leaving the boot stack and
558 * are about to switch to a task stack.
559 * Used by Task_startup()
560 */
561 Void switchFromBootStack();
562
563 /*!
564 * ======== post ========
565 * Generate an interrupt for test purposes.
566 *
567 * @param(intNum) ID of interrupt to generate
568 */
569 Void post(UInt intNum);
570
571 /*!
572 * @_nodoc 573 * ======== getTaskSP ========
574 * retrieve interrupted task's SP
575 *
576 * Used for benchmarking the SYS/BIOS Hwi dispatcher's task
577 * stack utilization.
578 *
579 * @b(returns) interrupted task's SP
580 */
581 Char *getTaskSP();
582
583 /*
584 * @_nodoc
585 * The following two target-unique Hwi APIs must be called
586 * directly in order to work properly. Thus they are not
587 * published here in order to bypass the multi-layered indirect function
588 * calls (__E, __F) that would arise if they appeared in this spec file.
589 *
590 * These APIs must be implemented by the target Hwi modules and must be
591 * given these EXACT names.
592 *
593 * The two functions, switchToIsrStack() and switchToTaskStack() must
594 * work in tandem to insure that only the first order (ie non nested)
595 * invocation of these APIs result in the switch to the ISR stack and
596 * the switch back to the task stack. The opaque char * token returned
597 * by switchToIsrStack() and passed to switchToTaskStack() is provided
598 * purely for implementation efficiency and thus can have implementation
599 * dependent definitions.
600 */
601
602 /*
603 * @_nodoc
604 * ======== switchAndRunFunc ========
605 * If not on ISR stack already, switch to it, then call
606 * the function whose address is passed as an argument
607 * and then switch back to Task stack.
608 *
609 * Used by the Swi scheduler.
610 *
611 * This function must be implemented by all Hwi modules
612 * name) because it can't be _E and _F'd due to its
613 * inherent stack switching behavior.
614 *
615 * @a(param) Function pointer
616 */
617 /* Char *ti_bios_family_xxx_Hwi_switchAndRunFunc(); */
618
619 /*
620 * @_nodoc
621 * ======== switchToIsrStack ========
622 * If not on ISR stack already, switch to it.
623 * Used by the Swi scheduler and interrupt dispatcher.
624 *
625 * This function must be implemented by all Hwi modules
626 * name) because it can't be _E and _F'd due to its
627 * inherent stack switching behavior.
628 *
629 * @b(returns) token to use with
630 * switchToTaskStack()
631 */
632 /* Char *ti_bios_family_xxx_Hwi_switchToIsrStack(); */
633
634 /*
635 * @_nodoc
636 * ======== switchToTaskStack ========
637 * If at bottom of ISR stack, switch to Task stack.
638 * Used by the Swi scheduler and interrupt dispatcher.
639 *
640 * This function must be implemented by all Hwi modules
641 * and be given this exact name (without a target-specific
642 * name) because it can't be _E and _F'd due to its
643 * inherent stack switching behavior.
644 *
645 * @param(key) token returned by
646 * switchToIsrStack()
647 */
648 /* Void ti_bios_family_xxx_Hwi_switchToTaskStack(Char *key); */
649
650 /*!
651 * ======== disableInterrupt ========
652 * Disable a specific interrupt.
653 *
654 * Disable a specific interrupt identified by an interrupt number.
655 *
656 * @param(intNum) interrupt number to disable
657 * @b(returns) key to restore previous enable/disable state
658 */
659 UInt disableInterrupt(UInt intNum);
660
661 /*!
662 * ======== enableInterrupt ========
663 * Enable a specific interrupt.
664 *
665 * Enables a specific interrupt identified by an interrupt number.
666 *
667 * @param(intNum) interrupt number to enable
668 * @b(returns) key to restore previous enable/disable state
669 */
670 UInt enableInterrupt(UInt intNum);
671
672 /*!
673 * ======== restoreInterrupt ========
674 * Restore a specific interrupt's enabled/disabled state.
675 *
676 * Restores a specific interrupt identified by an interrupt number.
677 * restoreInterrupt is generally used to restore an interrupt to its state
678 * before {@link #disableInterrupt} or {@link #enableInterrupt} was
679 * invoked
680 *
681 * @param(intNum) interrupt number to restore
682 * @param(key) key returned from enableInt or disableInt
683 */
684 Void restoreInterrupt(UInt intNum, UInt key);
685
686 /*!
687 * ======== clearInterrupt ========
688 * Clear a specific interrupt.
689 *
690 * Clears a specific interrupt's pending status.
691 * The implementation is family-specific.
692 *
693 * @param(intNum) interrupt number to clear
694 */
695 Void clearInterrupt(UInt intNum);
696
697 instance:
698
699 /*!
700 * Create a dispatched interrupt.
701 *
702 * A Hwi dispatcher table entry is created and filled with the
703 * function specified by the fxn parameter and the attributes
704 * specified by the params parameter.
705 *
706 * If params is NULL, the Hwi's dispatcher properties are assigned a
707 * default set of values. Otherwise, the following properties
708 * are specified by a structure of type Hwi_Params.
709 *
710 * @p(blist) 711 * - The arg element is a generic argument that is passed to the plugged
712 * function as its only parameter. The default value is 0.
713 * - The enableInt element determines whether the interrupt should be
714 * enabled in the IER by create.
715 * - The maskSetting element defines the dispatcherAutoNestingSupport
716 * behavior of the interrupt.
717 * @p 718 *
719 * Hwi_create returns a pointer to the created Hwi object.
720 *
721 * @param(intNum) interrupt number
722 * @param(hwiFxn) pointer to ISR function
723 *
724 */
725 create(Int intNum, FuncPtr hwiFxn);
726
727 /*! maskSetting. Default is {@link #MaskingOption Hwi_MaskingOption_SELF} */
728 config MaskingOption maskSetting = MaskingOption_SELF;
729
730 /*! ISR function argument. Default is 0. */
731 config UArg arg = 0;
732
733 /*! Enable this interrupt when object is created? Default is true. */
734 config Bool enableInt = true;
735
736 /*!
737 * Interrupt event ID (Interrupt Selection Number)
738 *
739 * Default is -1.
740 * Not all targets/devices support this instance parameter.
741 * On those that don't, this parameter is ignored.
742 */
743 config Int eventId = -1;
744
745 /*!
746 * Interrupt priority.
747 *
748 * The default value of -1 is used as a flag to indicate
749 * the lowest (logical) device-specific priority value.
750 *
751 * Not all targets/devices support this instance parameter.
752 * On those that don't, this parameter is ignored.
753 */
754 config Int priority = -1;
755
756 /*!
757 * ======== getFunc ========
758 * Get Hwi function and arg
759 *
760 * @param(arg) pointer for returning hwi's ISR function argument
761 * @b(returns) hwi's ISR function
762 */
763 FuncPtr getFunc(UArg *arg);
764
765 /*!
766 * ======== setFunc ========
767 * Overwrite Hwi function and arg
768 *
769 * Replaces a Hwi object's hwiFxn function originally
770 * provided in {@link #create}.
771 *
772 * @param(fxn) pointer to ISR function
773 * @param(arg) argument to ISR function
774 */
775 Void setFunc(FuncPtr fxn, UArg arg);
776
777 /*!
778 * ======== getHookContext ========
779 * Get hook instance's context for a Hwi.
780 *
781 * @b(returns) hook instance's context for hwi
782 */
783 Ptr getHookContext(Int id);
784
785 /*!
786 * ======== setHookContext ========
787 * Set hook instance's context for a Hwi.
788 *
789 * @param(id) hook instance's ID
790 * @param(hookContext) value to write to context
791 */
792 Void setHookContext(Int id, Ptr hookContext);
793
794 /*!
795 * ======== getIrp ========
796 * Get address of interrupted instruction.
797 *
798 * @b(returns) most current IRP of a Hwi
799 */
800 Irp getIrp();
801 }