The IHwi interface specifies APIs for globally enabling, disabling, and
restoring interrupts.
Additionally, management of individual, device-specific hardware
interrupts is provided.
The user can statically or dynamically assign routines that run when
specific hardware interrupts occur.
Dynamic assignment of Hwi routines to interrupts at run-time is done
using the Hwi_create function.
Interrupt routines can be written completely in C, completely in
assembly, or in a mix of C and assembly. In order to support interrupt
routines
written completely in C, an interrupt dispatcher is provided that performs
the requisite prolog and epilog for an interrupt routine.
Some routines are assigned to interrupts by the other SYS/BIOS
modules. For example, the Clock module configures its own timer interrupt
handler. See the Clock Module for more details.
Below is an example of configuring an interrupt at runtime.
Usually this code would be placed in main().
Sets of hook functions can be specified for the Hwi module
using the configuration tool. Each set contains these hook
functions:
The create and delete functions are called whenever a Hwi is created
or deleted. They are called with interrupts enabled (unless called
at boot time or from main()).
The beginFxn and endFxn function hooks are called with interrupts
globally disabled, therefore any hook processing function will contribute
to the overall system interrupt response latency. In order to minimize
this impact, carefully consider the processing time spent in an Hwi
beginFxn or endFxn function hook.
Hook functions can only be configured statically.
enum IHwi.MaskingOption |
|
Shorthand interrupt masking options
enum MaskingOption {
MaskingOption_NONE,
MaskingOption_ALL,
MaskingOption_SELF,
MaskingOption_BITMASK,
MaskingOption_LOWER
};
VALUES
MaskingOption_NONE
No interrupts are disabled
MaskingOption_ALL
All interrupts are disabled
MaskingOption_SELF
Only this interrupt is disabled
MaskingOption_BITMASK
User supplies interrupt enable masks
MaskingOption_LOWER
All current and lower priority
interrupts are disabled.
Only a few targets/devices truly
support this masking option. For those
that don't, this setting is treated
the same as MaskingOption_SELF.
typedef IHwi.FuncPtr |
|
Hwi create function type definition
typedef Void (*FuncPtr)(UArg);
typedef IHwi.Irp |
|
Interrupt Return Pointer
DETAILS
This is the address of the interrupted instruction.
struct IHwi.HookSet |
|
Hwi hook set type definition
struct HookSet {
Void (*registerFxn)(Int);
};
DETAILS
The functions that make up a hookSet have certain restrictions. They
cannot call any Hwi instance functions other than Hwi_getHookContext()
and Hwi_setHookContext(). For all practical purposes, they should treat
the Hwi_Handle passed to these functions as an opaque handle.
config IHwi.dispatcherAutoNestingSupport // module-wide |
|
Include interrupt nesting logic in interrupt dispatcher?
config Bool dispatcherAutoNestingSupport = true;
DETAILS
Default is true.
This option provides the user with the ability to optimize
interrupt dispatcher performance when support for interrupt
nesting is not required.
Setting this parameter to false will disable the logic in
the interrupt dispatcher that manipulates interrupt mask
registers and enables and disables interrupts before and
after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts
enabled during the execution of your Hwi functions.
config IHwi.dispatcherIrpTrackingSupport // module-wide |
|
Controls whether the
dispatcher retains the interrupted thread's return address
config Bool dispatcherIrpTrackingSupport = true;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in
the interrupt dispatcher that keeps track of the interrupt's
return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return
address using the
getIrp API.
config IHwi.dispatcherSwiSupport // module-wide |
|
Include Swi scheduling logic in interrupt dispatcher?
config Bool dispatcherSwiSupport;
DETAILS
Default is inherited from
BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize
interrupt dispatcher performance when it is known that Swis
will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in
the interrupt dispatcher that invokes the Swi scheduler
prior to returning from an interrupt.
config IHwi.dispatcherTaskSupport // module-wide |
|
Include Task scheduling logic in interrupt dispatcher?
config Bool dispatcherTaskSupport;
DETAILS
Default is inherited from
BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize
interrupt dispatcher performance when it is known that no
Task scheduling APIs (ie
Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in
the interrupt dispatcher that invokes the Task scheduler
prior to returning from an interrupt.
metaonly config IHwi.common$ // module-wide |
|
Common module configuration parameters
DETAILS
All modules have this configuration parameter. Its name
contains the '$' character to ensure it does not conflict with
configuration parameters declared by the module. This allows
new configuration parameters to be added in the future without
any chance of breaking existing modules.
IHwi.clearInterrupt() // module-wide |
|
Clear a specific interrupt
Void clearInterrupt(UInt intNum);
ARGUMENTS
intNum
interrupt number to clear
DETAILS
Clears a specific interrupt's pending status.
The implementation is family-specific.
IHwi.disable() // module-wide |
|
Globally disable interrupts
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an
opaque key indicating whether interrupts were globally enabled or
disabled on entry to Hwi_disable().
The actual value of the key is target/device specific and is meant
to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs
to run without interruption. When critical processing is complete, call
Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is
postponed until interrupts are reenabled. However, if the same type
of interrupt occurs several times while interrupts are disabled,
the interrupt's function is executed only once when interrupts are
reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if
an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts
are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as
Semaphore_pend(),
Semaphore_post(),
Task_sleep(), or
Task_yield()
is invoked which results in a context switch while
interrupts are disabled, an embedded call to
Hwi_enable occurs
on the way to the new thread context which unconditionally re-enables
interrupts. Interrupts will remain enabled until a subsequent
Hwi_disable
invocation.
Swis always run with interrupts enabled.
See
Swi_post() for a discussion Swis and
interrupts.
IHwi.disableInterrupt() // module-wide |
|
Disable a specific interrupt
UInt disableInterrupt(UInt intNum);
ARGUMENTS
intNum
interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
IHwi.enable() // module-wide |
|
Globally enable interrupts
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an
opaque key indicating whether interrupts were globally enabled or
disabled on entry to Hwi_enable().
The actual value of the key is target/device specific and is meant
to be passed to Hwi_restore().
This function is
called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
Hardware interrupts are enabled unless a call to Hwi_disable disables
them.
Servicing of interrupts that occur while interrupts are disabled is
postponed until interrupts are reenabled. However, if the same type
of interrupt occurs several times while interrupts are disabled,
the interrupt's function is executed only once when interrupts are
reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if
an enabled interrupt occurred while interrupts are disabled.
Any call to Hwi_enable enables interrupts, even if Hwi_disable has
been called several times.
Hwi_enable must not be called from main().
IHwi.enableInterrupt() // module-wide |
|
Enable a specific interrupt
UInt enableInterrupt(UInt intNum);
ARGUMENTS
intNum
interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
IHwi.restore() // module-wide |
|
Globally restore interrupts
ARGUMENTS
key
enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined
by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore
reenables interrupts and another Hwi occurred while interrupts were
disabled.
Hwi_restore may be called from main(). However, since Hwi_enable
cannot be called from main(), interrupts are always disabled in
main(), and a call to Hwi_restore has no effect.
IHwi.restoreInterrupt() // module-wide |
|
Restore a specific interrupt's enabled/disabled state
Void restoreInterrupt(UInt intNum, UInt key);
ARGUMENTS
intNum
interrupt number to restore
key
key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number.
restoreInterrupt is generally used to restore an interrupt to its state
before
disableInterrupt or
enableInterrupt was
invoked
IHwi.startup() // module-wide |
|
Initially enable interrupts
DETAILS
Called within BIOS_start
metaonly IHwi.addHookSet() // module-wide |
|
addHookSet is used in a config file to add a hook set (defined
by struct HookSet)
ARGUMENTS
hook
structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those
elements will not exist.
config IHwi.arg // instance |
|
ISR function argument. Default is 0
config IHwi.enableInt // instance |
|
Enable this interrupt when object is created? Default is true
config Bool enableInt = true;
config IHwi.eventId // instance |
|
Interrupt event ID (Interrupt Selection Number)
DETAILS
Default is -1.
Not all targets/devices support this instance parameter.
On those that don't, this parameter is ignored.
config IHwi.maskSetting // instance |
|
maskSetting. Default is Hwi_MaskingOption_SELF
config IHwi.priority // instance |
|
Interrupt priority
config Int priority = -1;
DETAILS
Default is -1.
Not all targets/devices support this instance parameter.
On those that don't, this parameter is ignored.
Instance Creation |
|
// Create an instance-object
ARGUMENTS
intNum
interrupt number
hwiFxn
pointer to ISR function
DETAILS
A Hwi dispatcher table entry is created and filled with the
function specified by the fxn parameter and the attributes
specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a
default set of values. Otherwise, the following properties
are specified by a structure of type Hwi_Params.
- The arg element is a generic argument that is passed to the plugged
function as its only parameter. The default value is 0.
- The enableInt element determines whether the interrupt should be
enabled in the IER by create.
- The maskSetting element defines the dispatcherAutoNestingSupport
behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
IHwi.getFunc() // instance |
|
Get Hwi function and arg
ARGUMENTS
arg
pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
IHwi.getHookContext() // instance |
|
Get hook instance's context for a Hwi
Ptr getHookContext(Int id);
RETURNS
hook instance's context for hwi
IHwi.getIrp() // instance |
|
Get address of interrupted instruction
RETURNS
most current IRP of a Hwi
IHwi.setFunc() // instance |
|
Overwrite Hwi function and arg
ARGUMENTS
fxn
pointer to ISR function
arg
argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally
provided in
create.
IHwi.setHookContext() // instance |
|
Set hook instance's context for a Hwi
Void setHookContext(Int id, Ptr hookContext);
ARGUMENTS
id
hook instance's ID
hookContext
value to write to context