module ti.sysbios.knl.Swi

Software Interrupt Manager

The Swi module manages software interrupt service routines, which are patterned after hardware interrupt service routines. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/knl/Swi.xdc
#include <ti/sysbios/knl/Swi.h>
Functions
Void 
Void
Void 
Void
Void
UInt 
Ptr 
UInt 
UInt 
Void 
Void 
Void
Void 
Void 
Void 
Functions common to all target instances
Functions common to all target modules
Typedefs
typedef Void 
typedef Swi_Object *
typedef struct
typedef struct
typedef struct
typedef struct
Constants
extern const Assert_Id 
extern const Assert_Id 
extern const Log_Event 
extern const Log_Event 
extern const Log_Event 
extern const UInt 
 
DETAILS
The Swi module manages software interrupt service routines, which are patterned after hardware interrupt service routines.
SYS/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. SYS/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.
Software interrupts can be posted for execution with a call to post or a number of other Swi functions. Each Swi object has a "trigger" which is used either to determine whether to post the Swi or as a value that can be evaluated within the Swi's function. andn and dec post the Swi if the trigger value transitions to 0. or and inc also modify the trigger value. (or sets bits, and andn clears bits.)
The disable and restore operations allow you to post several Swis and enable them all for execution at the same time. The Swi priorities then determine which Swi runs first.
All Swis run to completion; you cannot suspend a Swi while it waits for something (for example, a device) to be ready. So, you can use the trigger to tell the Swi when all the devices and other conditions it relies on are ready. Within a Swi processing function, a call to Swi_getTrigger returns the value of the trigger when the Swi started running. Note that the trigger is automatically reset to its original value when a Swi runs; however, getTrigger will return the saved trigger value from when the Swi started execution.
All Swis run with interrupts globally enabled (ie GIE = 1). Therefore, any Swi module API that results in a Swi being made ready to run (ie post, inc, andn, or, restore, or enable) will subsequently also cause interrupts to be enabled while the Swi function executes. Upon return from the Swi function, global interrupts are restored to their previous enabled/disabled state.
A Swi preempts any currently running Swi with a lower priority. When multiple Swis of the same priority level have been posted, their respective Swi functions are executed in the order the Swis were posted. 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.
disable also disables the Task scheduler. Therefore, Task pre-emption and blocking is disabled while the Swi scheduler is disabled. restore will re-enable and invoke the Task scheduler if the Task scheduler was not disabled prior to invoking disable. The currently ready highest priority task will be immediately switched to or continue to run when the lowest order restore invocation re-enables the Swi scheduler.
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:
  key = Swi_disable();
  // create a task of higher priority than the current task thread
  myTaskParams.priority = Task_getPri(Task_self()) + 1;
  myTask = Task_create(myTaskFunc, &myTaskParams, NULL);
  Swi_restore(key);
HOOK FUNCTIONS
Sets of hook functions can be specified for the Swi module. Each set contains these hook functions:
  • Register: A function called before all statically-created Swis are initialized at runtime.
  • Create: A function that is called when a Swi is created. This includes Swis that are created statically and those created dynamically using create.
  • Ready: A function that is called when any Swi becomes ready to run.
  • Begin: A function that is called just prior to running a Swi.
  • End: A function that is called just after a Swi finishes.
  • Delete: A function that is called when a Swi is deleted at run-time with delete.
Hook functions can only be configured statically.
If you define more than one set of hook functions, all the functions of a particular type will be run when a Swi triggers that type of hook.
Register Function
The Register function is provided to allow a hook set to store its hookset ID. This id can be passed to setHookContext and getHookContext to set or get hookset-specific context. The Register function must be specified if the hook implementation needs to use setHookContext or getHookContext. The registerFxn hook function is called during system initialization before interrupts have been enabled.
  Void myRegisterFxn(Int id);
Create and Delete 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()).
  Void myCreateFxn(Swi_Handle swi, Error_Block *eb);
  Void myDeleteFxn(Swi_Handle swi);
Ready, Begin, and End Functions
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.
  Void myReady(Swi_Handle swi);
  Void myBegin(Swi_Handle swi);
  Void myEnd(Swi_Handle swi);

Calling Context

Function Hwi Swi Task Main Startup
create N N Y Y N
disable Y Y Y Y N
getTrigger Y Y N N N
Params_init Y Y Y Y Y
restore Y Y Y Y N
self Y Y N N N
andn Y Y Y Y N
construct N N Y Y N
dec Y Y Y Y N
delete N N Y Y N
destruct N N Y Y N
getHookContext Y Y Y Y N
getPri Y Y Y Y N
getFunc Y Y Y Y N
inc Y Y Y Y N
or Y Y Y Y N
post Y Y Y Y N
setHookContext Y Y Y Y N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Swi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Swi_Module_startupDone() returns FALSE).
 
typedef Swi_FuncPtr

Swi function type definition

C synopsis target-domain
typedef Void (*Swi_FuncPtr)(UArg,UArg);
 
DETAILS
All Swi functions are passed two uninterpreted arguments of type UArg and have no return value.
 
struct Swi_HookSet

Swi hook set type definition

C synopsis target-domain
typedef struct Swi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(Swi_Handle,Error_Block*);
    Void (*readyFxn)(Swi_Handle);
    Void (*beginFxn)(Swi_Handle);
    Void (*endFxn)(Swi_Handle);
    Void (*deleteFxn)(Swi_Handle);
} Swi_HookSet;
 
DETAILS
This structure defines the set of hook functions that can be specified for the Swi module.
See Hook Functions for details.
 
config Swi_A_badPriority  // module-wide

Assertion raised if a Swi's priority is out of range

C synopsis target-domain
extern const Assert_Id Swi_A_badPriority;
 
DETAILS
Swi priorities must be in the range of 0 and numPriorities-1.
 
config Swi_A_swiDisabled  // module-wide

Assertion raised if Swi_create is called and runtime Swi creation is disabled

C synopsis target-domain
extern const Assert_Id Swi_A_swiDisabled;
 
DETAILS
 
config Swi_LD_end  // module-wide

The event logged just after returning from a Swi's function

C synopsis target-domain
extern const Log_Event Swi_LD_end;
 
 
config Swi_LM_begin  // module-wide

The event logged just prior to invoking a Swi's function

C synopsis target-domain
extern const Log_Event Swi_LM_begin;
 
 
config Swi_LM_post  // module-wide

The event logged when Swi_post() is called

C synopsis target-domain
extern const Log_Event Swi_LM_post;
 
 
config Swi_numPriorities  // module-wide

Number of Swi priorities supported

C synopsis target-domain
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, 55x, and MSP430 devices, the maximum number of priorities is 16.
 
Swi_disable()  // module-wide

Disable Swi Scheduling

C synopsis target-domain
UInt Swi_disable();
 
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

C synopsis target-domain
UInt Swi_getTrigger();
 
RETURNS
trigger value
DETAILS
Swi_getTrigger returns the value that Swi's trigger had when the Swi started running. SYS/BIOS saves the trigger value internally, so that Swi_getTrigger can access it at any point within a Swi object's function, and 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.
This API is called within a Swi object's function to use the trigger value that caused the function to run. For example, if you use Swi_or or Swi_inc to post a Swi, different trigger values can require different processing.
  swicount = Swi_getTrigger();
 
Swi_restore()  // module-wide

Restore Swi Scheduling state

C synopsis target-domain
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 cannot 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

C synopsis target-domain
Swi_Handle Swi_self();
 
RETURNS
handle of currently running Swi
DETAILS
Swi_self returns the handle of the currently executing Swi.
For example, you can call Swi_self as follows if you want a Swi to repost itself:
  Swi_post(Swi_self());
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId Swi_Module_id();
// Get this module's unique id
 
Bool Swi_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle Swi_Module_heap();
// 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
Instance Object Types

C synopsis target-domain
typedef struct Swi_Object Swi_Object;
// Opaque internal representation of an instance object
 
typedef Swi_Object *Swi_Handle;
// Client reference to an instance object
 
typedef struct Swi_Struct Swi_Struct;
// Opaque client structure large enough to hold an instance object
 
Swi_Handle Swi_handle(Swi_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
Swi_Struct *Swi_struct(Swi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters

C synopsis target-domain
typedef struct Swi_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    UArg arg0;
    // Swi function argument 0
    UArg arg1;
    // Swi function argument 1
    UInt priority;
    // Swi priority
    UInt trigger;
    // Initial Swi trigger value
} Swi_Params;
 
Void Swi_Params_init(Swi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config Swi_arg0  // instance

Swi function argument 0

C synopsis target-domain
struct Swi_Params {
      ...
    UArg arg0;
 
DETAILS
The default value of this optional parameter is 0.
SEE
 
config Swi_arg1  // instance

Swi function argument 1

C synopsis target-domain
struct Swi_Params {
      ...
    UArg arg1;
 
DETAILS
The default value of this optional parameter is 0.
SEE
 
config Swi_priority  // instance

Swi priority

C synopsis target-domain
struct Swi_Params {
      ...
    UInt priority;
 
DETAILS
Each software interrupt has a priority level, 0 to (numPriorities - 1). A software interrupt preempts any lower-priority software interrupt currently executing. When multiple Swis of the same priority level have been posted, their respective Swi functions are executed in the order the Swis were posted.
The default value of this optional parameter is ~0, which yields a Swi with the highest priority: (numPriorities - 1).
 
config Swi_trigger  // instance

Initial Swi trigger value

C synopsis target-domain
struct Swi_Params {
      ...
    UInt trigger;
 
DETAILS
The default value of this optional parameter is 0.
Each Swi object has a "trigger" used either to determine whether to post the Swi or as a value that can be evaluated within the Swi's function.
The andn and dec functions post the Swi if the trigger value transitions to 0. The or and inc functions also modify the trigger value. (or sets bits, and andn clears bits.)
Instance Creation

C synopsis target-domain
Swi_Handle Swi_create(Swi_FuncPtr fxn, const Swi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void Swi_construct(Swi_Struct *structP, Swi_FuncPtr fxn, const Swi_Params *params, Error_Block *eb);
// 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.
The following C code sets Swi parameters and creates two Swi objects:
  Void main()
  {       
      Swi_Params swiParams;
  
      Swi_Params_init(&swiParams);
      swiParams.arg0 = 1;
      swiParams.arg1 = 0;
      swiParams.priority = 2;
      swiParams.trigger = 0;
  
      swi0 = Swi_create(swi0Fxn, &swiParams, NULL);
  
      swiParams.arg0 = 2;
      swiParams.arg1 = 0;
      swiParams.priority = 1;
      swiParams.trigger = 3;
  
      swi1 = Swi_create(swi1Fxn, &swiParams, NULL);

      BIOS_start();
  }
The following XDCscript statements set Swi parameters and create two Swi objects:
  var Swi = xdc.useModule('ti.sysbios.knl.Swi');
  
  var swiParams = new Swi.Params();
  swiParams.arg0 = 1;
  swiParams.arg1 = 0;
  swiParams.priority = 2;
  swiParams.trigger = 0;
  Program.global.swi0 = Swi.create('&swi0Fxn', swiParams);
  
  swiParams.arg0 = 2;
  swiParams.priority = 1;
  swiParams.trigger = 3;
  Program.global.swi1 = Swi.create('&swi1Fxn', swiParams);
Instance Deletion

C synopsis target-domain
Void Swi_delete(Swi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void Swi_destruct(Swi_Struct *structP);
// Finalize the instance object inside the provided structure
 
Swi_andn()  // instance

Clear bits in Swi's trigger; post if trigger becomes 0

C synopsis target-domain
Void Swi_andn(Swi_Handle handle, UInt mask);
 
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)
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.
For example, if two events must happen before a Swi is to be triggered, the initial trigger value of the Swi can be 3 (binary 0011). One call to Swi_andn can have a mask value of 2 (binary 0010), and another call to Swi_andn can have a mask value of 1 (binary 0001). After both calls have been made, the trigger value will be 0.
  Swi_andn(swi0, 2);  // clear bit 1
  Swi_andn(swi0, 1);  // clear bit 0
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 at Swi creation time. The trigger value is automatically reset when the Swi executes.
CONSTRAINTS
The post discussion regarding global interrupts applies to this API.
 
Swi_dec()  // instance

Decrement Swi's trigger value; post if trigger becomes 0

C synopsis target-domain
Void Swi_dec(Swi_Handle handle);
 
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.
  // swi0's trigger is configured to start at 3
  Swi_dec(swi0);      // trigger = 2
  Swi_dec(swi0);      // trigger = 1
  Swi_dec(swi0);      // trigger = 0
You specify a Swi's initial trigger value at Swi creation time. 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_getFunc()  // instance

Get Swi function and arguments

C synopsis target-domain
Swi_FuncPtr Swi_getFunc(Swi_Handle handle, UArg *arg0, UArg *arg1);
 
ARGUMENTS
handle — handle of a previously-created Swi instance object
arg0 — pointer for returning Swi's first function argument
arg1 — pointer for returning Swi's second function argument
RETURNS
Swi function
DETAILS
If either arg0 or arg1 is NULL, then the corresponding argument is not returned.
 
Swi_getHookContext()  // instance

Get hook instance's context pointer for a Swi

C synopsis target-domain
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
DETAILS
For example, this C code gets the HookContext, prints it, and sets a new value for the HookContext.
  Ptr pEnv;
  Swi_Handle mySwi;
  Int myHookSetId1;
 
  pEnv = Swi_getHookContext(swi, myHookSetId1);
 
  System_printf("myEnd1: pEnv = 0x%lx, time = %ld\n", 
                (ULong)pEnv, (ULong)Timestamp_get32());
 
  Swi_setHookContext(swi, myHookSetId1, (Ptr)0xc0de1);
See Hook Functions for more details.
 
Swi_getPri()  // instance

Return a Swi's priority

C synopsis target-domain
UInt Swi_getPri(Swi_Handle handle);
 
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()  // instance

Increment Swi's trigger value and post the Swi

C synopsis target-domain
Void Swi_inc(Swi_Handle handle);
 
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 (i.e. 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()  // instance

Or mask with value contained in Swi's trigger and post the Swi

C synopsis target-domain
Void Swi_or(Swi_Handle handle, UInt mask);
 
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 at Swi creation time. 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()  // instance

Unconditionally post a software interrupt

C synopsis target-domain
Void Swi_post(Swi_Handle handle);
 
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()  // instance

Set hook instance's context for a swi

C synopsis target-domain
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
DETAILS
For example, this C code gets the HookContext, prints it, and sets a new value for the HookContext.
  Ptr pEnv;
  Swi_Handle mySwi;
  Int myHookSetId1;
 
  pEnv = Swi_getHookContext(swi, myHookSetId1);
 
  System_printf("myEnd1: pEnv = 0x%lx, time = %ld\n", 
                (ULong)pEnv, (ULong)Timestamp_get32());
 
  Swi_setHookContext(swi, myHookSetId1, (Ptr)0xc0de1);
See Hook Functions for more details.
Instance Built-Ins

C synopsis target-domain
Int Swi_Object_count();
// The number of statically-created instance objects
 
Swi_Handle Swi_Object_get(Swi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
Swi_Handle Swi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
Swi_Handle Swi_Object_next(Swi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle Swi_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *Swi_Handle_label(Swi_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String Swi_Handle_name(Swi_Handle handle);
// The name of this instance object
 
XDCscript usage meta-domain sourced in ti/sysbios/knl/Swi.xdc
var Swi = xdc.useModule('ti.sysbios.knl.Swi');
module-wide constants & types
        obj.registerFxn = Void(*)(Int)  ...
        obj.createFxn = Void(*)(Swi.Handle,Error.Block*)  ...
        obj.readyFxn = Void(*)(Swi.Handle)  ...
        obj.beginFxn = Void(*)(Swi.Handle)  ...
        obj.endFxn = Void(*)(Swi.Handle)  ...
        obj.deleteFxn = Void(*)(Swi.Handle)  ...
module-wide config parameters
        msg: "A_badPriority: An invalid Swi priority was used."
    };
        msg: "A_swiDisabled: Cannot create a Swi when Swi is disabled."
    };
        mask: Diags.USER2,
        msg: "LD_end: swi: 0x%x"
    };
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: swi: 0x%x, func: 0x%x, preThread: %d"
    };
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_post: swi: 0x%x, func: 0x%x, pri: %d"
    };
 
module-wide functions
per-instance config parameters
    var params = new Swi.Params// Instance config-params object;
        params.arg0// Swi function argument 0 = UArg 0;
        params.arg1// Swi function argument 1 = UArg 0;
        params.priority// Swi priority = UInt ~0;
        params.trigger// Initial Swi trigger value = UInt 0;
per-instance creation
    var inst = Swi.create// Create an instance-object(Void(*)(UArg,UArg) fxn, params);
 
 
struct Swi.HookSet

Swi hook set type definition

XDCscript usage meta-domain
var obj = new Swi.HookSet;
 
    obj.registerFxn = Void(*)(Int)  ...
    obj.createFxn = Void(*)(Swi.Handle,Error.Block*)  ...
    obj.readyFxn = Void(*)(Swi.Handle)  ...
    obj.beginFxn = Void(*)(Swi.Handle)  ...
    obj.endFxn = Void(*)(Swi.Handle)  ...
    obj.deleteFxn = Void(*)(Swi.Handle)  ...
 
DETAILS
This structure defines the set of hook functions that can be specified for the Swi module.
See Hook Functions for details.
C SYNOPSIS
 
config Swi.A_badPriority  // module-wide

Assertion raised if a Swi's priority is out of range

XDCscript usage meta-domain
Swi.A_badPriority = Assert.Desc {
    msg: "A_badPriority: An invalid Swi priority was used."
};
 
DETAILS
Swi priorities must be in the range of 0 and numPriorities-1.
C SYNOPSIS
 
config Swi.A_swiDisabled  // module-wide

Assertion raised if Swi_create is called and runtime Swi creation is disabled

XDCscript usage meta-domain
Swi.A_swiDisabled = Assert.Desc {
    msg: "A_swiDisabled: Cannot create a Swi when Swi is disabled."
};
 
DETAILS
C SYNOPSIS
 
config Swi.LD_end  // module-wide

The event logged just after returning from a Swi's function

XDCscript usage meta-domain
Swi.LD_end = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_end: swi: 0x%x"
};
 
C SYNOPSIS
 
config Swi.LM_begin  // module-wide

The event logged just prior to invoking a Swi's function

XDCscript usage meta-domain
Swi.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: swi: 0x%x, func: 0x%x, preThread: %d"
};
 
C SYNOPSIS
 
config Swi.LM_post  // module-wide

The event logged when Swi_post() is called

XDCscript usage meta-domain
Swi.LM_post = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_post: swi: 0x%x, func: 0x%x, pri: %d"
};
 
C SYNOPSIS
 
config Swi.numPriorities  // module-wide

Number of Swi priorities supported

XDCscript usage meta-domain
Swi.numPriorities = UInt 16;
 
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, 55x, and MSP430 devices, the maximum number of priorities is 16.
C SYNOPSIS
 
metaonly config Swi.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
Swi.common$ = Types.Common$ undefined;
 
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.
 
metaonly Swi.addHookSet()  // module-wide

Add hook functions to be called by the Swi scheduler

XDCscript usage meta-domain
Swi.addHookSet(Swi.HookSet hookSet) returns Void
 
ARGUMENTS
hookSet — structure of type HookSet
DETAILS
This function is used in a config file to add a set of functions that are called before or after significant points within the Swi scheduler.
Configures a set of hook functions for the Swi module. Each set contains these hook functions:
  • Register: A function called before all statically-created Swis are initialized at runtime.
  • Create: A function that is called when a Swi is created. This includes Swis that are created statically and those created dynamically using create.
  • Ready: A function that is called when any Swi becomes ready to run.
  • Begin: A function that is called just prior to running a Swi.
  • End: A function that is called just after a Swi finishes.
  • Delete: A function that is called when a Swi is deleted at run-time with delete.
See Hook Functions for more details.
HookSet structure elements may be omitted, in which case those elements will not exist.
For example, the following configuration code defines a HookSet:
  // Hook Set 1 
  Swi.addHookSet({
     registerFxn: '&myRegister1',
     createFxn:   '&myCreate1',
     readyFxn:    '&myReady1',
     beginFxn:    '&myBegin1',
     endFxn:      '&myEnd1',
     deleteFxn:   '&myDelete1'
  });
Instance Config Parameters

XDCscript usage meta-domain
var params = new Swi.Params;
// Instance config-params object
    params.arg0 = UArg 0;
    // Swi function argument 0
    params.arg1 = UArg 0;
    // Swi function argument 1
    params.priority = UInt ~0;
    // Swi priority
    params.trigger = UInt 0;
    // Initial Swi trigger value
 
config Swi.arg0  // instance

Swi function argument 0

XDCscript usage meta-domain
var params = new Swi.Params;
  ...
params.arg0 = UArg 0;
 
DETAILS
The default value of this optional parameter is 0.
SEE
C SYNOPSIS
 
config Swi.arg1  // instance

Swi function argument 1

XDCscript usage meta-domain
var params = new Swi.Params;
  ...
params.arg1 = UArg 0;
 
DETAILS
The default value of this optional parameter is 0.
SEE
C SYNOPSIS
 
config Swi.priority  // instance

Swi priority

XDCscript usage meta-domain
var params = new Swi.Params;
  ...
params.priority = UInt ~0;
 
DETAILS
Each software interrupt has a priority level, 0 to (numPriorities - 1). A software interrupt preempts any lower-priority software interrupt currently executing. When multiple Swis of the same priority level have been posted, their respective Swi functions are executed in the order the Swis were posted.
The default value of this optional parameter is ~0, which yields a Swi with the highest priority: (numPriorities - 1).
C SYNOPSIS
 
config Swi.trigger  // instance

Initial Swi trigger value

XDCscript usage meta-domain
var params = new Swi.Params;
  ...
params.trigger = UInt 0;
 
DETAILS
The default value of this optional parameter is 0.
Each Swi object has a "trigger" used either to determine whether to post the Swi or as a value that can be evaluated within the Swi's function.
The andn and dec functions post the Swi if the trigger value transitions to 0. The or and inc functions also modify the trigger value. (or sets bits, and andn clears bits.)
C SYNOPSIS
Instance Creation

XDCscript usage meta-domain
var params = new Swi.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = Swi.create(Void(*)(UArg,UArg) fxn, params);
// Create an instance-object
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.
The following C code sets Swi parameters and creates two Swi objects:
  Void main()
  {       
      Swi_Params swiParams;
  
      Swi_Params_init(&swiParams);
      swiParams.arg0 = 1;
      swiParams.arg1 = 0;
      swiParams.priority = 2;
      swiParams.trigger = 0;
  
      swi0 = Swi_create(swi0Fxn, &swiParams, NULL);
  
      swiParams.arg0 = 2;
      swiParams.arg1 = 0;
      swiParams.priority = 1;
      swiParams.trigger = 3;
  
      swi1 = Swi_create(swi1Fxn, &swiParams, NULL);

      BIOS_start();
  }
The following XDCscript statements set Swi parameters and create two Swi objects:
  var Swi = xdc.useModule('ti.sysbios.knl.Swi');
  
  var swiParams = new Swi.Params();
  swiParams.arg0 = 1;
  swiParams.arg1 = 0;
  swiParams.priority = 2;
  swiParams.trigger = 0;
  Program.global.swi0 = Swi.create('&swi0Fxn', swiParams);
  
  swiParams.arg0 = 2;
  swiParams.priority = 1;
  swiParams.trigger = 3;
  Program.global.swi1 = Swi.create('&swi1Fxn', swiParams);
generated on Thu, 01 Mar 2012 16:58:11 GMT