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 
Void 
Ptr 
UInt 
UInt 
Void 
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.
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
getAttrs Y Y Y Y N
getFunc Y Y Y Y N
getHookContext Y Y Y Y N
getPri Y Y Y Y N
inc Y Y Y Y N
or Y Y Y Y N
post Y Y Y Y N
setAttrs 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
Swi_disable() and Swi_restore() control Swi scheduling. Swi_disable() disables all 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 preempted by other Swis or Tasks.
The value of the key returned by Swi_disable() 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. Nor can it be pre-empted by other Tasks.
  key = Swi_disable();
      `critical section`
  Swi_restore(key);
SIDE EFFECTS OF DISABLING THE SWI SCHEDULER
Swi_disable(), in addition to disabling Swis from pre-empting the code which follows its invocation, has the side effect of also disabling the Task scheduler. Consequently, Task pre-emption and blocking is also disabled while the Swi scheduler is disabled. When Swi_restore() is subsequently called, it will re-enable and invoke the Task scheduler if the Task scheduler was not already disabled prior to invoking Swi_disable().
The following code snippet:
  key = Swi_disable();
  ...
  Swi_post(swi);        <-- 'swi' will not run
  ...
  Swi_restore(key);     <-- 'swi' runs now
Should be thought of as equivalent to this:
  tasKey = Task_disable();
  swiKey = Swi_disable();
  ...
  Swi_post(swi);        <-- 'swi' will not run
  ...
  Swi_restore(swiKey);  <-- 'swi' runs now
  Task_restore(taskKey);
In the following example, even though the Semaphore_post() call unblocks a task of higher priority, the local task is not pre-empted until after the Swi_restore() call is made:
  key = Swi_disable();
  ...
  Swi_post(swi);        <-- 'swi' will not run
  Semaphore_post(sem);  <-- readys a task of higher priority than current task
  ...
  Swi_restore(key);     <-- 'swi' runs now, then current task is pre-empted.
A common mistake that users make is to invoke a blocking API such as Semaphore_pend() after calling Swi_disable(). This results in unrecoverable damage to the Task scheduler's internal state and will lead to unpredictable and usually catastrophic behavior:
  key = Swi_disable();
  ...
  Semaphore_pend(sem, BIOS_WAIT_FOREVER);  <-- !!! DO NOT DO THIS !!!
  ...
  Swi_restore(key);   <-- !!! System failure guaranteed to follow !!!
A more subtle variant of the above problem occurs when an API such as GateMutex_enter() is invoked directly or indirectly while the Swi scheduler is disabled. If the GateMutex has already been entered by another thread, the current thread should block until the other thread calls GateMutex_leave(). But because the Task scheduler is disabled, the local thread returns immediately from GateMutex_enter(), just as though it successfully entered the GateMutex! This usually leads to catastrophic results.
 
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, 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. Nor can it be pre-empted by other Tasks.
  key = Swi_disable();
      `critical section`
  Swi_restore(key);
Read the discussion of the side effects of disabling the Swi scheduler here.
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_Params.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_Params.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_Params.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_Params.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.)
Runtime Instance Creation

C synopsis target-domain
Swi_Handle Swi_create(Swi_FuncPtr swiFxn, 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 swiFxn, const Swi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
swiFxn — 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_getAttrs()  // instance

Retrieve attributes of an existing Swi object

C synopsis target-domain
Void Swi_getAttrs(Swi_Handle handle, Swi_FuncPtr *swiFxn, Swi_Params *params);
 
ARGUMENTS
handle — handle of a previously-created Swi instance object
swiFxn — pointer to a Swi_FuncPtr
params — pointer for returning Swi's Params
DETAILS
The 'handle' argument specifies the address of the Swi object whose attributes are to be retrieved.
The 'swiFxn' argument is the address of a function pointer where the the Swi function address is to be written to. If NULL is passed for 'swiFxn', no attempt is made to return the Swi function.
The 'params' argument is a pointer to a Swi_Params structure that will contain the retrieved Swi attributes.
RELATED
 
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.
RELATED
 
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_setAttrs()  // instance

Set the attributes of an existing Swi object

C synopsis target-domain
Void Swi_setAttrs(Swi_Handle handle, Swi_FuncPtr swiFxn, Swi_Params *params);
 
ARGUMENTS
handle — handle of a previously-created Swi instance object
swiFxn — address of the Swi function
params — pointer for returning Swi's Params
DETAILS
The 'handle' argument specifies the address of the Swi object whose attributes are to be set.
The 'swiFxn' argument is the address of the function to be invoked when the Swi runs. If 'swiFxn' is NULL, no change is made to the Swi function.
The 'params' argument, which can be either NULL or a pointer to a Swi_Params structure that contains attributes for the Swi object, facilitates setting the attributes of the Swi object.
If 'params' is NULL, the Swi object is assigned a default set of attributes. Otherwise, the Swi object's attributes are set according the values passed within 'params'.
CONSTRAINTS
Swi_setAttrs() must not be used on a Swi that is preempted or is ready to run.
RELATED
 
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
 
Configuration settings 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) swiFxn, params);
 
 
struct Swi.HookSet

Swi hook set type definition

Configuration settings
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

Configuration settings
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

Configuration settings
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

Configuration settings
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

Configuration settings
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

Configuration settings
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

Configuration settings
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

Configuration settings
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

Configuration settings
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

Configuration settings
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.Params.arg0  // instance

Swi function argument 0

Configuration settings
var params = new Swi.Params;
  ...
params.arg0 = UArg 0;
 
DETAILS
The default value of this optional parameter is 0.
SEE
C SYNOPSIS
 
config Swi.Params.arg1  // instance

Swi function argument 1

Configuration settings
var params = new Swi.Params;
  ...
params.arg1 = UArg 0;
 
DETAILS
The default value of this optional parameter is 0.
SEE
C SYNOPSIS
 
config Swi.Params.priority  // instance

Swi priority

Configuration settings
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.Params.trigger  // instance

Initial Swi trigger value

Configuration settings
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
Static Instance Creation

Configuration settings
var params = new Swi.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = Swi.create(Void(*)(UArg,UArg) swiFxn, params);
// Create an instance-object
ARGUMENTS
swiFxn — 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 Fri, 10 Jun 2016 23:29:41 GMT