module ti.sysbios.knl.Swi
index URL

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 
Swi_andn// Clear bits in Swi's trigger; post if trigger becomes 0(Swi_Handle handle, UInt mask);
Void
Swi_construct// Initialize a new instance object inside the provided structure(Swi_Struct *structP, Swi_FuncPtr swiFxn, const Swi_Params *params, Error_Block *eb);
Swi_Handle
Swi_create// Allocate and initialize a new instance object and return its handle(Swi_FuncPtr swiFxn, const Swi_Params *params, Error_Block *eb);
Void 
Swi_dec// Decrement Swi's trigger value; post if trigger becomes 0(Swi_Handle handle);
Void
Swi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Swi_Handle *handleP);
Void
Swi_destruct// Finalize the instance object inside the provided structure(Swi_Struct *structP);
UInt 
Swi_disable// Disable Swi Scheduling();
Void 
Swi_getAttrs// Retrieve attributes of an existing Swi object(Swi_Handle handle, Swi_FuncPtr *swiFxn, Swi_Params *params);
Swi_FuncPtr 
Swi_getFunc// Get Swi function and arguments(Swi_Handle handle, UArg *arg0, UArg *arg1);
Ptr 
Swi_getHookContext// Get hook instance's context pointer for a Swi(Swi_Handle handle, Int id);
UInt 
Swi_getPri// Return a Swi's priority(Swi_Handle handle);
UInt 
Swi_getTrigger// Return the trigger value of the currently executing Swi();
Void 
Swi_inc// Increment Swi's trigger value and post the Swi(Swi_Handle handle);
Void 
Swi_or// Or mask with value contained in Swi's trigger and post the Swi(Swi_Handle handle, UInt mask);
Void
Swi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Swi_Params *params);
Void 
Swi_post// Unconditionally post a software interrupt(Swi_Handle handle);
Void 
Swi_restore// Restore Swi Scheduling state(UInt key);
Swi_Handle 
Swi_self// Return address of currently executing Swi object();
Void 
Swi_setAttrs// Set the attributes of an existing Swi object(Swi_Handle handle, Swi_FuncPtr swiFxn, Swi_Params *params);
Void 
Swi_setHookContext// Set hook instance's context for a swi(Swi_Handle handle, Int id, Ptr hookContext);
Functions common to all target instances
Swi_handle// Convert this instance structure pointer into an instance handle, Swi_Handle_label// The label associated with this instance object, Swi_Handle_name// The name of this instance object, Swi_Object_count// The number of statically-created instance objects, Swi_Object_first// The handle of the first dynamically-created instance object, or NULL, Swi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Swi_Object_heap// The heap used to allocate dynamically-created instance objects, Swi_Object_next// The handle of the next dynamically-created instance object, or NULL, Swi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
Swi_Module_getMask// Returns the diagnostics mask for this module, Swi_Module_hasMask// Test whether this module has a diagnostics mask, Swi_Module_heap// The heap from which this module allocates memory, Swi_Module_id// Get this module's unique id, Swi_Module_setMask// Set the diagnostics mask for this module, Swi_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void 
(*Swi_FuncPtr// Swi function type definition)(UArg,UArg);
typedef Swi_Object *
Swi_Handle// Client reference to an instance object;
typedef struct
Swi_HookSet// Swi hook set type definition ...
typedef struct
Swi_Object// Opaque internal representation of an instance object Swi_Object;
typedef struct
Swi_Params// Instance config-params structure ...
typedef struct
Swi_Struct// Opaque client structure large enough to hold an instance object Swi_Struct;
Constants
extern const Assert_Id 
Swi_A_badPriority// Assertion raised if a Swi's priority is out of range;
extern const Assert_Id 
Swi_A_swiDisabled// Assertion raised if Swi_create is called and runtime Swi creation is disabled;
extern const Log_Event 
Swi_LD_end// The event logged just after returning from a Swi's function;
extern const Log_Event 
Swi_LM_begin// The event logged just prior to invoking a Swi's function;
extern const Log_Event 
Swi_LM_post// The event logged when Swi_post() is called;
extern const UInt 
Swi_numPriorities// Number of Swi priorities supported;
 
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
index URL

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
index URL

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
index URL

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
index URL

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
see ti.sysbios.BIOS.swiEnabled
 
config Swi_LD_end  // module-wide
index URL

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
index URL

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
index URL

The event logged when Swi_post() is called

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

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
index URL

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
index URL

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
index URL

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
index URL

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
index URL

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
index URL

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
index URL

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
index URL

Swi function argument 0

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

Swi function argument 1

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

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
index URL

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
index URL

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
index URL

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
index URL

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
index URL

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
index URL

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_setAttrs()
 
Swi_getFunc()  // instance
index URL

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_getAttrs()
 
Swi_getHookContext()  // instance
index URL

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
index URL

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
index URL

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
index URL

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
index URL

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
index URL

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_getAttrs()
 
Swi_setHookContext()  // instance
index URL

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
index URL

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
    var obj = new Swi.HookSet// Swi hook set type definition;
        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
    Swi.A_badPriority// Assertion raised if a Swi's priority is out of range = Assert.Desc {
        msg: "A_badPriority: An invalid Swi priority was used."
    };
    Swi.A_swiDisabled// Assertion raised if Swi_create is called and runtime Swi creation is disabled = Assert.Desc {
        msg: "A_swiDisabled: Cannot create a Swi when Swi is disabled."
    };
    Swi.LD_end// The event logged just after returning from a Swi's function = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_end: swi: 0x%x"
    };
    Swi.LM_begin// The event logged just prior to invoking a Swi's function = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: swi: 0x%x, func: 0x%x, preThread: %d"
    };
    Swi.LM_post// The event logged when Swi_post() is called = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_post: swi: 0x%x, func: 0x%x, pri: %d"
    };
    Swi.numPriorities// Number of Swi priorities supported = UInt 16;
 
    Swi.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
    Swi.addHookSet// Add hook functions to be called by the Swi scheduler(Swi.HookSet hookSet) returns Void
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
index URL

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
Swi_HookSet
 
config Swi.A_badPriority  // module-wide
index URL

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
Swi_A_badPriority
 
config Swi.A_swiDisabled  // module-wide
index URL

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
see ti.sysbios.BIOS.swiEnabled
C SYNOPSIS
Swi_A_swiDisabled
 
config Swi.LD_end  // module-wide
index URL

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
Swi_LD_end
 
config Swi.LM_begin  // module-wide
index URL

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
Swi_LM_begin
 
config Swi.LM_post  // module-wide
index URL

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
Swi_LM_post
 
config Swi.numPriorities  // module-wide
index URL

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
Swi_numPriorities
 
metaonly config Swi.common$  // module-wide
index URL

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
index URL

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
index URL

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
index URL

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
FuncPtr
C SYNOPSIS
Swi_Params.arg0
 
config Swi.Params.arg1  // instance
index URL

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
FuncPtr
C SYNOPSIS
Swi_Params.arg1
 
config Swi.Params.priority  // instance
index URL

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
Swi_Params.priority
 
config Swi.Params.trigger  // instance
index URL

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
Swi_Params.trigger
Static Instance Creation
index URL

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 Tue, 08 Nov 2016 16:10:57 GMT