The Swi module manages software interrupt service routines, which are
patterned after hardware interrupt service routines.
DSP/BIOS manages four distinct levels of execution threads: hardware
interrupt service routines, software interrupt routines, tasks, and
background idle functions. A software interrupt is an object that
encapsulates a function to be executed and a priority.
Software interrupts are prioritized, preempt tasks, and are preempted
by hardware interrupt service routines.
Each software interrupt has a priority level. A software interrupt
preempts any lower-priority software interrupt currently executing.
A target program uses an API call to post a Swi object. This causes the
Swi module to schedule execution of the software interrupt's function.
When a Swi is posted by an API call, the Swi object's function is not
executed immediately. Instead, the function is scheduled for execution.
DSP/BIOS uses the Swi's priority to determine whether to preempt the
thread currently running. Note that if a Swi is posted several times
before it begins running, (because Hwis and higher priority interrupts
are running,) when the Swi does eventually run, it will run only one time.
A Swi preempts any currently running Swi with a lower priority. If two
Swis with the same priority level have been posted, the Swi that was
posted first runs first. Hwis in turn preempt any currently running Swi,
allowing the target to respond quickly to hardware peripherals.
Swi threads are executed using the ISR (or "Hwi") stack. Thus
they share the ISR stack with Hwi threads.
In the following example, the newly created task is not switched to
until after the Swi_restore() call since Task scheduling is disabled
while Swi scheduling is disabled:
Sets of hook functions can be specified for the Swi module. Each set
contains these hook functions:
The create and delete functions are called whenever a Swi is created
or deleted. They are called with interrupts enabled (unless called
at boot time or from main()).
The ready, begin and end functions are all called with interrupts
enabled. The ready function is called when a Swi is posted and made
ready to run. The begin function is called right before the function
associated with the given Swi is run. The end function is called
right after this function returns.
typedef Swi.FuncPtr |
|
Swi function type definition
typedef Void (*Swi_FuncPtr)(UArg,UArg);
metaonly struct Swi.BasicView |
|
XDCscript usage |
meta-domain |
var obj = new Swi.BasicView;
obj.label = String ...
obj.state = String ...
obj.priority = UInt ...
obj.fxn = String[] ...
obj.arg0 = UArg ...
obj.arg1 = UArg ...
obj.initTrigger = UInt ...
obj.curTrigger = UInt ...
struct Swi.HookSet |
|
Swi hook set type definition
XDCscript usage |
meta-domain |
var obj = new Swi.HookSet;
obj.registerFxn = Void(*)(Int) ...
typedef struct Swi_HookSet {
Void (*registerFxn)(Int);
} Swi_HookSet;
metaonly struct Swi.ModuleView |
|
XDCscript usage |
meta-domain |
var obj = new Swi.ModuleView;
obj.schedulerState = String ...
obj.readyQMask = String ...
obj.currentSwi = Ptr ...
obj.currentFxn = String[] ...
config Swi.A_badPriority // module-wide |
|
Asserted when a Swi priority is not in the range of 0 and numPriorities-1
XDCscript usage |
meta-domain |
msg: "A_badPriority: An invalid Swi priority was used."
};
config Swi.A_swiDisabled // module-wide |
|
Asserted when Swi_create is called when ti.sysbios.BIOS.swiEnabled is false
XDCscript usage |
meta-domain |
msg: "A_swiDisabled: Cannot create a Swi when Swi is disabled."
};
config Swi.LD_end // module-wide |
|
Logged just after returning from a Swi's function
XDCscript usage |
meta-domain |
msg: "LD_end: swi: 0x%x"
};
config Swi.LM_begin // module-wide |
|
Logged just prior to invoking a Swi's function
XDCscript usage |
meta-domain |
msg: "LM_begin: swi: 0x%x, func: 0x%x, preThread: %d"
};
config Swi.LM_post // module-wide |
|
Logged when Swi_post() is called
XDCscript usage |
meta-domain |
msg: "LM_post: swi: 0x%x, func: 0x%x, pri: %d"
};
config Swi.hooks // module-wide |
|
const array to hold all HookSet objects
XDCscript usage |
meta-domain |
config Swi.numPriorities // module-wide |
|
Number of Swi priorities supported. Default is 16
XDCscript usage |
meta-domain |
Swi.numPriorities = UInt 16;
extern const UInt Swi_numPriorities;
DETAILS
The maximum number of priorities supported is
target specific and depends on the number of
bits in a UInt data type. For 6x and Arm devices
the maximum number of priorities is therefore 32.
For 28x and 55x devices, the maximum number of
priorities is 16.
metaonly config Swi.common$ // module-wide |
|
Common module configuration parameters
XDCscript usage |
meta-domain |
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.
Swi.disable( ) // module-wide |
|
Disable Swi Scheduling
RETURNS
opaque key for use with Swi_restore()
DETAILS
disable and
restore control Swi scheduling.
disable disables all other Swi functions from running until
restore is called. Hardware interrupts can still run.
disable and
restore allow you to ensure that
statements that must be performed together during critical
processing are not preempted by other Swis or Tasks.
The value of the key returned is opaque to applications and is meant
to be passed to Swi_restore().
In the following example, the critical section cannot be preempted
by any Swis.
key = Swi_disable();
`critical section`
Swi_restore(key);
CONSTRAINTS
Swi_disable also disables the Task scheduler.
Swi_restore will re-enable and invoke the Task
scheduler if the Task scheduler was not disabled prior
to invoking Swi_disable().
Swi.getTrigger( ) // module-wide |
|
Return the trigger value of the currently executing Swi
RETURNS
trigger value
DETAILS
Swi_getTrigger returns the value that Swi's trigger had when the Swi
started running. DSP/BIOS saves the trigger value internally so that
Swi_getTrigger can access it at any point within a Swi object's function.
DSP/BIOS then automatically resets the trigger to its initial value.
Swi_getTrigger should only be called within a function run by a Swi
object.
When called from within the context of a Swi, the value returned by
Swi_getTrigger is zero if the Swi was posted by a call to Swi_andn,
or Swi_dec. Therefore, Swi_getTrigger provides relevant information
only if the Swi was posted by a call to Swi_inc, Swi_or, Swi_orHook,
or Swi_post.
Swi.restore( ) // module-wide |
|
Restore Swi Scheduling state
Void Swi_restore( UInt key );
ARGUMENTS
key
key to restore previous Swi scheduler state
DETAILS
Swi_restore restores the Swi scheduler to the locked/unlocked state
it was in when Swi_disable was called. If the scheduler becomes
unlocked and Swis of sufficient priority have been made ready to
run by any of the posting APIs, then they are run at this time.
Swi_disable and Swi_restore control software interrupt processing.
Swi_disable disables all other Swi functions from running until
Swi_restore is called. Hardware interrupts can still run.
Swi_disable and Swi_restore allow you to ensure that statements that
must be performed together during critical processing are not
pre-empted by other Swis.
In the following example, the critical section can not be preempted
by any Swis:
key = Swi_disable();
`critical section`
Swi_restore(key);
CONSTRAINTS
Swi_restore will also re-enable and invoke the Task
scheduler if the Task scheduler was not disabled prior to
invoking Swi_disable().
The
post discussion regarding global interrupts applies
to this API.
Swi.self( ) // module-wide |
|
Return address of currently executing Swi object
RETURNS
handle of currently running Swi
DETAILS
Swi_self returns the handle of the currently executing Swi.
metaonly Swi.addHookSet( ) // module-wide |
|
addHookSet is used in a config file to add a hook set (defined
by struct HookSet)
XDCscript usage |
meta-domain |
ARGUMENTS
hookSet
structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those
elements will not exist.
module-wide built-ins |
|
// Get this module's unique id
Bool Swi_Module_startupDone( );
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool Swi_Module_hasMask( );
// Test whether this module has a diagnostics mask
Bits16 Swi_Module_getMask( );
// Returns the diagnostics mask for this module
Void Swi_Module_setMask( Bits16 mask );
// Set the diagnostics mask for this module
per-instance object types |
|
typedef struct Swi_Object Swi_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct Swi_Struct Swi_Struct;
// Opaque client structure large enough to hold an instance object
// Convert this instance structure pointer into an instance handle
// Convert this instance handle into an instance structure pointer
per-instance config parameters |
|
XDCscript usage |
meta-domain |
var params = new Swi.Params;
// Instance config-params object
params.arg0 = UArg 0;
// Swi function argument 0. Default is 0
params.arg1 = UArg 0;
// Swi function argument 1. Default is 0
params.priority = UInt ~0;
// Swi priority (0 to {@link #numPriorities} - 1)
params.trigger = UInt 0;
// Initial Swi trigger value. Default is 0
typedef struct Swi_Params {
// Instance config-params structure
// Common per-instance configs
UArg arg0;
// Swi function argument 0. Default is 0
UArg arg1;
// Swi function argument 1. Default is 0
UInt priority;
// Swi priority (0 to {@link #numPriorities} - 1)
UInt trigger;
// Initial Swi trigger value. Default is 0
} Swi_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Swi.arg0 // per-instance |
|
Swi function argument 0. Default is 0
XDCscript usage |
meta-domain |
var params = new Swi.Params;
...
params.arg0 = UArg 0;
config Swi.arg1 // per-instance |
|
Swi function argument 1. Default is 0
XDCscript usage |
meta-domain |
var params = new Swi.Params;
...
params.arg1 = UArg 0;
config Swi.priority // per-instance |
|
Swi priority (0 to numPriorities - 1)
XDCscript usage |
meta-domain |
var params = new Swi.Params;
...
params.priority = UInt ~0;
DETAILS
Default value of ~0 yields a Swi priority of
(numPriorities - 1).
config Swi.trigger // per-instance |
|
Initial Swi trigger value. Default is 0
XDCscript usage |
meta-domain |
var params = new Swi.Params;
...
params.trigger = UInt 0;
per-instance creation |
|
XDCscript usage |
meta-domain |
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Swi.create( Void(*)(UArg,UArg) fxn, params );
// Create an instance-object
// Allocate and initialize a new instance object and return its handle
// Initialize a new instance object inside the provided structure
ARGUMENTS
fxn
Swi Function
params
per-instance config params, or NULL to select default values (target-domain only)
eb
active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Swi_create creates a new Swi object.
per-instance deletion |
|
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
Swi.andn( ) // per-instance |
|
Clear bits in Swi's trigger; post if trigger becomes 0
ARGUMENTS
handle
handle of a previously-created Swi instance object
mask
inverse value to be ANDed
DETAILS
Swi_andn is used to conditionally post a software interrupt.
Swi_andn clears the bits specified by a mask from Swi's internal
trigger. If the Swi's trigger becomes 0, Swi_andn posts the Swi.
The bitwise logical operation performed is:
trigger = trigger AND (NOT MASK)
For example, if multiple conditions that all be met before a
Swi can run, you should use a different bit in the trigger for
each condition. When a condition is met, clear the bit for that
condition.
Swi_andn results in a context switch if the Swi's trigger becomes
zero and the Swi has higher priority than the currently executing
thread.
You specify a Swi's initial trigger value in the configuration.
The trigger value is automatically reset when the Swi executes.
CONSTRAINTS
The
post discussion regarding global interrupts applies
to this API.
Swi.dec( ) // per-instance |
|
Decrement Swi's trigger value; post if trigger becomes 0
ARGUMENTS
handle
handle of a previously-created Swi instance object
DETAILS
Swi_dec is used to conditionally post a software interrupt. Swi_dec
decrements the value in Swi's trigger by 1. If Swi's trigger value
becomes 0, Swi_dec posts the Swi. You can increment a trigger value
by using Swi_inc, which always posts the Swi.
For example, you would use Swi_dec if you wanted to post a Swi after
a number of occurrences of an event.
You specify a Swi's initial trigger value in the configuration. The
trigger value is automatically reset when the Swi executes.
Swi_dec results in a context switch if the Swi's trigger becomes
zero and the Swi has higher priority than the currently executing
thread.
CONSTRAINTS
The
post discussion regarding global interrupts applies
to this API.
Swi.getHookContext( ) // per-instance |
|
Get hook instance's context pointer for a swi
Ptr Swi_getHookContext(
Swi_Handle handle,
Int id );
ARGUMENTS
handle
handle of a previously-created Swi instance object
RETURNS
hook instance's context pointer for swi
Swi.getPri( ) // per-instance |
|
Return a Swi's priority
ARGUMENTS
handle
handle of a previously-created Swi instance object
RETURNS
Priority of swi
DETAILS
Swi_getPri returns the priority of the Swi passed in as the
argument.
Swi.inc( ) // per-instance |
|
Increment Swi's trigger value and post the Swi
ARGUMENTS
handle
handle of a previously-created Swi instance object
DETAILS
Swi_inc increments the value in Swi's trigger by 1 and posts the Swi
regardless of the resulting trigger value. You can decrement a
trigger value using Swi_dec, which only posts the Swi if the
trigger value is 0.
If a Swi is posted several times before it has a chance to begin
executing (ie: when Hwis or higher priority Swis are running) the Swi
only runs one time. If this situation occurs, you can use Swi_inc to
post the Swi. Within the Swi's function, you could then use
Swi_getTrigger to find out how many times this Swi has been posted
since the last time it was executed.
You specify a Swi's initial trigger value at Swi creation time.
The trigger value is automatically reset when the Swi executes.
To get the trigger value, use Swi_getTrigger.
Swi_inc results in a context switch if the Swi is higher priority
than the currently executing thread.
CONSTRAINTS
The
post discussion regarding global interrupts applies
to this API.
Swi.or( ) // per-instance |
|
Or mask with value contained in Swi's trigger and post the
Swi
ARGUMENTS
handle
handle of a previously-created Swi instance object
mask
value to be ORed
DETAILS
Swi_or is used to post a software interrupt. Swi_or sets the bits
specified by a mask in Swi's trigger. Swi_or posts the Swi
regardless of the resulting trigger value. The bitwise logical
operation performed on the trigger value is:
trigger = trigger OR mask
You specify a Swi's initial trigger value in the configuration.
The trigger value is automatically reset when the Swi executes.
To get the trigger value, use Swi_getTrigger.
For example, you might use Swi_or to post a Swi if any of three
events should cause a Swi to be executed, but you want the Swi's
function to be able to tell which event occurred. Each event
would correspond to a different bit in the trigger.
Swi_or results in a context switch if the Swi is higher priority
than the currently executing thread.
CONSTRAINTS
The
post discussion regarding global interrupts applies
to this API.
Swi.post( ) // per-instance |
|
Unconditionally post a software interrupt
ARGUMENTS
handle
handle of a previously-created Swi instance object
DETAILS
Swi_post is used to post a software interrupt regardless of the
trigger value. No change is made to the Swi object's trigger value.
Swi_post results in a context switch if the Swi is higher priority
than the currently executing thread.
CONSTRAINTS
Swis are ALWAYS run with interrupts enabled.
If a Swi is made ready to run as a consequence of this
API, interrupts will be globally enabled while the Swi function
executes, regardless of the prior globally enabled/disabled state of interrupts.
Upon return from this API, the global interrupt enabled/disabled state
is restored to its previous value.
Swi.setHookContext( ) // per-instance |
|
Set hook instance's context for a swi
Void Swi_setHookContext(
Swi_Handle handle,
Int id,
Ptr hookContext );
ARGUMENTS
handle
handle of a previously-created Swi instance object
id
hook instance's ID
hookContext
value to write to context
per-instance built-ins |
|
Int Swi_Object_count( );
// The number of statically-created instance objects
// The handle of the i-th statically-created instance object (array == NULL)
// The handle of the first dynamically-created instance object, or NULL
// The handle of the next dynamically-created instance object, or NULL
// The heap used to allocate dynamically-created instance objects
// The label associated with this instance object
// The name of this instance object