Detailed Description

Software Interrupt Manager.

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 Swi_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. Swi_andn and Swi_dec post the Swi if the trigger value transitions to 0. Swi_or and Swi_inc also modify the trigger value. (Swi_or sets bits, and Swi_andn clears bits.)

The Swi_disable and Swi_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, Swi_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 Swi_post, Swi_inc, Swi_andn, Swi_or, or Swi_restore) 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.

To use the Swi module or to set any of the Swi module configuration variables, the following must be added to the app.syscfg file:

const Swi = scripting.addModule("/ti/sysbios/knl/Swi");

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 Swi_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 Swi_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.

To add a Swi hook or set of Swi hooks, the following syntax is used in the app.syscfg file:

const Swi = scripting.addModule("/ti/sysbios/knl/Swi");
Swi.swiHooks[0].registerFxn = "myRegisterFxn";
Swi.swiHooks[0].createFxn   = "myCreateFxn";
Swi.swiHooks[0].readyFxn    = "myrReadyFxn";
Swi.swiHooks[0].beginFxn    = "myBeginFxn";
Swi.swiHooks[0].endFxn      = "myEndFxn";
Swi.swiHooks[0].deleteFxn   = "myDeleteFxn";

Leaving a subset of the hook functions undefined is ok.

Register Function

The Register function is provided to allow a hook set to store its hookset ID. This id can be passed to Swi_setHookContext and Swi_getHookContext to set or get hookset-specific context. The Register function must be specified if the hook implementation needs to use Swi_setHookContext or Swi_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
Swi_create	N	N	Y	Y	N
Swi_disable	Y	Y	Y	Y	N
Swi_getTrigger	Y	Y	N	N	N
Swi_Params_init	Y	Y	Y	Y	Y
Swi_restore	Y	Y	Y	Y	N
Swi_self	Y	Y	N	N	N
Swi_andn	Y	Y	Y	Y	N
Swi_construct	N	N	Y	Y	N
Swi_dec	Y	Y	Y	Y	N
Swi_delete	N	N	Y	Y	N
Swi_destruct	N	N	Y	Y	N
Swi_getAttrs	Y	Y	Y	Y	N
Swi_getFunc	Y	Y	Y	Y	N
Swi_getHookContext	Y	Y	Y	Y	N
Swi_getPri	Y	Y	Y	Y	N
Swi_inc	Y	Y	Y	Y	N
Swi_or	Y	Y	Y	Y	N
Swi_post	Y	Y	Y	Y	N
Swi_setAttrs	Y*	Y*	Y	Y	N
Swi_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. after Swi_init() has been called). 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. before Swi_init() has been called).

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/sysbios/knl/Queue.h>
#include <ti/sysbios/runtime/Error.h>

Include dependency graph for Swi.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	Swi_HookSet
	Swi hook set type definition. More...

struct	Swi_Hook

struct	Swi_Params

Macros
#define	Swi_A_swiDisabled "cannot create a SWI when Swi is disabled"
	Assertion raised if Swi_create is called and runtime Swi creation is disabled. More...

#define	Swi_A_badPriority "invalid priority"
	Assertion raised if a Swi's priority is out of range. More...

Typedefs
typedef struct Swi_Struct	Swi_Struct

typedef struct Swi_Struct	Swi_Object

typedef Swi_Struct *	Swi_Handle

typedef Swi_Struct *	Swi_Instance

typedef struct Swi_HookSet	Swi_HookSet
	Swi hook set type definition. More...

typedef struct Swi_Params	Swi_Params

typedef void(*	Swi_FuncPtr) (uintptr_t arg1, uintptr_t arg2)
	Swi function type definition. More...

Functions
Swi_Handle	Swi_create (Swi_FuncPtr swiFxn, const Swi_Params prms, Error_Block eb)
	Create a software interrupt. More...

Swi_Handle	Swi_construct (Swi_Struct obj, Swi_FuncPtr swiFxn, const Swi_Params prms, Error_Block *eb)
	Construct a software interrupt. More...

void	Swi_delete (Swi_Handle *swi)
	Delete a software interrupt. More...

void	Swi_destruct (Swi_Struct *obj)
	Destruct a software interrupt. More...

void	Swi_Params_init (Swi_Params *prms)
	Initialize the Swi_Params structure with default values. More...

Swi_Handle	Swi_Object_first (void)
	return handle of the first Swi on Swi list More...

Swi_Handle	Swi_Object_next (Swi_Handle swi)
	return handle of the next Swi on Swi list More...

unsigned int	Swi_disable (void)
	Disable Swi Scheduling. More...

void	Swi_restore (unsigned int key)
	Restore Swi Scheduling state. More...

Swi_Handle	Swi_self (void)
	Return address of currently executing Swi object. More...

unsigned int	Swi_getTrigger (void)
	Return the trigger value of the currently executing Swi. More...

void	Swi_andn (Swi_Handle swi, unsigned int mask)
	Clear bits in Swi's trigger; post if trigger becomes 0. More...

void	Swi_dec (Swi_Handle swi)
	Decrement Swi's trigger value; post if trigger becomes 0. More...

void *	Swi_getHookContext (Swi_Handle swi, int id)
	Get hook instance's context pointer for a Swi. More...

void	Swi_setHookContext (Swi_Handle swi, int id, void *hookContext)
	Set hook instance's context for a swi. More...

char *	Swi_getName (Swi_Handle swi)
	Return a Swi's name. More...

unsigned int	Swi_getPri (Swi_Handle swi)
	Return a Swi's priority. More...

Swi_FuncPtr	Swi_getFunc (Swi_Handle swi, uintptr_t arg0, uintptr_t arg1)
	Get Swi function and arguments. More...

void	Swi_getAttrs (Swi_Handle swi, Swi_FuncPtr swiFxn, Swi_Params params)
	Retrieve attributes of an existing Swi object. More...

void	Swi_setAttrs (Swi_Handle swi, Swi_FuncPtr swiFxn, Swi_Params *params)
	Set the attributes of an existing Swi object. More...

void	Swi_setPri (Swi_Handle swi, unsigned int priority)
	Set a Swi's priority. More...

void	Swi_inc (Swi_Handle swi)
	Increment Swi's trigger value and post the Swi. More...

void	Swi_or (Swi_Handle swi, unsigned int mask)
	Or mask with value contained in Swi's trigger and post the Swi. More...

void	Swi_post (Swi_Handle swi)
	Unconditionally post a software interrupt. More...

Variables
const unsigned int	Swi_numPriorities
	Number of Swi priorities supported. More...

const Swi_Hook	Swi_hooks
	const array to hold all HookSet objects. More...

Macro Definition Documentation

§ Swi_A_swiDisabled

#define Swi_A_swiDisabled "cannot create a SWI when Swi is disabled"

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

§ Swi_A_badPriority

#define Swi_A_badPriority "invalid priority"

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

Swi priorities must be in the range of 0 and Swi_numPriorities-1.

Typedef Documentation

§ Swi_Struct

typedef struct Swi_Struct Swi_Struct

§ Swi_Object

typedef struct Swi_Struct Swi_Object

§ Swi_Handle

typedef Swi_Struct* Swi_Handle

§ Swi_Instance

typedef Swi_Struct* Swi_Instance

§ Swi_HookSet

typedef struct Swi_HookSet Swi_HookSet

Swi hook set type definition.

This structure defines the set of hook functions that can be specified for the Swi module.

See Hook Functions for details.

§ Swi_Params

typedef struct Swi_Params Swi_Params

§ Swi_FuncPtr

typedef void(* Swi_FuncPtr) (uintptr_t arg1, uintptr_t arg2)

Swi function type definition.

All Swi functions are passed two uninterpreted arguments of type uintptr_t and have no return value.

Function Documentation

§ Swi_create()

Swi_Handle Swi_create	(	Swi_FuncPtr	swiFxn,
		const Swi_Params *	prms,
		Error_Block *	eb
	)

Create a software interrupt.

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();
}

Parameters

swiFxn	Swi Function
prms	optional create parameters (NULL for defaults)
eb	error block

Return values

Swi	handle (NULL on failure)

§ Swi_construct()

Swi_Handle Swi_construct	(	Swi_Struct *	obj,
		Swi_FuncPtr	swiFxn,
		const Swi_Params *	prms,
		Error_Block *	eb
	)

Construct a software interrupt.

Swi_construct is equivalent to Swi_create except that the Swi_Struct is pre-allocated. See Swi_create() for a description of this API.

Parameters

obj	pointer to a Swi object
swiFxn	Swi Function
prms	optional create parameters (NULL for defaults)
eb	error block

Return values

Swi	handle (NULL on failure)

§ Swi_delete()

void Swi_delete ( Swi_Handle * swi )

Delete a software interrupt.

Swi_delete deletes a Swi object. Note that Swi_delete takes a pointer to a Swi_Handle which enables Swi_delete to set the Swi_handle to NULL.

Parameters

swi	pointer to Swi handle

§ Swi_destruct()

void Swi_destruct ( Swi_Struct * obj )

Destruct a software interrupt.

Swi_destruct destructs a Swi object.

Parameters

obj	pointer to Swi object

§ Swi_Params_init()

void Swi_Params_init ( Swi_Params * prms )

Initialize the Swi_Params structure with default values.

Swi_Params_init initializes the Swi_Params structure with default values. Swi_Params_init should always be called before setting individual parameter fields. This allows new fields to be added in the future with compatible defaults – existing source code does not need to change when new fields are added.

Parameters

prms	pointer to uninitialized params structure

§ Swi_Object_first()

Swi_Handle Swi_Object_first ( void )

return handle of the first Swi on Swi list

Return the handle of the first Swi on the create/construct list. NULL if no Swis have been created or constructed.

Return values

Swi handle

§ Swi_Object_next()

Swi_Handle Swi_Object_next ( Swi_Handle swi )

return handle of the next Swi on Swi list

Return the handle of the next Swi on the create/construct list. NULL if no more Swis are on the list.

Parameters

swi	Swi handle

Return values

Swi handle

§ Swi_disable()

unsigned int Swi_disable ( void )

Disable Swi Scheduling.

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.

Return values

opaque key for use with Swi_restore()

§ Swi_restore()

void Swi_restore ( unsigned int key )

Restore Swi Scheduling state.

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.

Precondition: Swi_restore will also re-enable and invoke the Task scheduler if the Task scheduler was not disabled prior to invoking Swi_disable().

The Swi_post discussion regarding global interrupts applies to this API.

Parameters

key	key to restore previous Swi scheduler state

§ Swi_self()

Swi_Handle Swi_self ( void )

Return address of currently executing Swi object.

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());

Return values

handle of currently running Swi

§ Swi_getTrigger()

unsigned int Swi_getTrigger ( void )

Return the trigger value of the currently executing Swi.

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();

Return values

trigger value

§ Swi_andn()

void Swi_andn	(	Swi_Handle	swi,
		unsigned int	mask
	)

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

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.

Precondition: The Swi_post discussion regarding global interrupts applies to this API.

Parameters

swi	Swi handle
mask	inverse value to be ANDed

§ Swi_dec()

void Swi_dec ( Swi_Handle swi )

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

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.

Precondition: The Swi_post discussion regarding global interrupts applies to this API.

Parameters

swi	Swi handle

§ Swi_getHookContext()

void* Swi_getHookContext	(	Swi_Handle	swi,
		int	id
	)

Get hook instance's context pointer for a Swi.

For example, this C code gets the HookContext, prints it, and sets a new value for the HookContext.

void * 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, (void *)0xc0de1);

See Hook Functions for more details.

Parameters

swi	Swi handle
id	hook id

Return values

hook	instance's context pointer for Swi

§ Swi_setHookContext()

void Swi_setHookContext	(	Swi_Handle	swi,
		int	id,
		void *	hookContext
	)

Set hook instance's context for a swi.

For example, this C code gets the HookContext, prints it, and sets a new value for the HookContext.

void * 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, (void *)0xc0de1);

See Hook Functions for more details.

Parameters

swi	Swi handle
id	hook instance's ID
hookContext	value to write to context

§ Swi_getName()

char* Swi_getName ( Swi_Handle swi )

Return a Swi's name.

Swi_getName returns the name of the Swi passed in as the argument.

Parameters

swi	Swi handle

Return values

name	of the Swi

§ Swi_getPri()

unsigned int Swi_getPri ( Swi_Handle swi )

Return a Swi's priority.

Swi_getPri returns the priority of the Swi passed in as the argument.

Parameters

swi	Swi handle

Return values

Priority of Swi

§ Swi_getFunc()

Swi_FuncPtr Swi_getFunc	(	Swi_Handle	swi,
		uintptr_t *	arg0,
		uintptr_t *	arg1
	)

Get Swi function and arguments.

If either arg0 or arg1 is NULL, then the corresponding argument is not returned.

See also: Swi_getAttrs

Parameters

swi	Swi handle
arg0	pointer for returning Swi's first function argument
arg1	pointer for returning Swi's second function argument

Return values

Swi function

§ Swi_getAttrs()

void Swi_getAttrs	(	Swi_Handle	swi,
		Swi_FuncPtr *	swiFxn,
		Swi_Params *	params
	)

Retrieve attributes of an existing Swi object.

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. If 'params' is NULL, no attempt is made to retrieve the Swi_Params.

See also: Swi_setAttrs

Parameters

swi	Swi handle
swiFxn	pointer to a Swi_FuncPtr
params	pointer for returning Swi's Params

§ Swi_setAttrs()

void Swi_setAttrs	(	Swi_Handle	swi,
		Swi_FuncPtr	swiFxn,
		Swi_Params *	params
	)

Set the attributes of an existing Swi object.

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'.

Warning: Swi_setAttrs() must not be used on a Swi that is preempted or is ready to run.

See also: Swi_getAttrs

Parameters

swi	Swi handle
swiFxn	address of the Swi function
params	pointer to optional Swi_Params structure

§ Swi_setPri()

void Swi_setPri	(	Swi_Handle	swi,
		unsigned int	priority
	)

Set a Swi's priority.

Swi_setPri sets the priority of the Swi passed in as the argument.

Precondition: The priority must be in the range of 0 and numPriorities-1.; Swi_setPri() must not be used on a Swi that is preempted or is ready to run.

See also: Swi_getPri

Parameters

swi	Swi handle
priority	priority of Swi

§ Swi_inc()

void Swi_inc ( Swi_Handle swi )

Increment Swi's trigger value and post the Swi.

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.

Precondition: The Swi_post discussion regarding global interrupts applies to this API.

Parameters

swi	Swi handle

§ Swi_or()

void Swi_or	(	Swi_Handle	swi,
		unsigned int	mask
	)

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

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.

Precondition: The Swi_post discussion regarding global interrupts applies to this API.

Parameters

swi	Swi handle
mask	value to be ORed

§ Swi_post()

void Swi_post ( Swi_Handle swi )

Unconditionally post a software interrupt.

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.

Precondition: 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.

Parameters

swi	Swi handle

Variable Documentation

§ Swi_numPriorities

const unsigned int Swi_numPriorities

Number of Swi priorities supported.

The maximum number of priorities supported is target-specific and depends on the number of bits in a unsigned int data type. For 6x and ARM devices the maximum number of priorities is therefore 32. For the C28x, the maximum number of priorities is 16.

§ Swi_hooks

const Swi_Hook Swi_hooks

const array to hold all HookSet objects.

Detailed Description

Calling Context

Data Structures

Macros

Typedefs

Functions

Variables

Macro Definition Documentation

§ Swi_A_swiDisabled

§ Swi_A_badPriority

Typedef Documentation

§ Swi_Struct

§ Swi_Object

§ Swi_Handle

§ Swi_Instance

§ Swi_HookSet

§ Swi_Params

§ Swi_FuncPtr

Function Documentation

§ Swi_create()

§ Swi_construct()

§ Swi_delete()

§ Swi_destruct()

§ Swi_Params_init()

§ Swi_Object_first()

§ Swi_Object_next()

§ Swi_disable()

Side Effects of Disabling the Swi Scheduler

§ Swi_restore()

§ Swi_self()

§ Swi_getTrigger()

§ Swi_andn()

§ Swi_dec()

§ Swi_getHookContext()

§ Swi_setHookContext()

§ Swi_getName()

§ Swi_getPri()

§ Swi_getFunc()

§ Swi_getAttrs()

§ Swi_setAttrs()

§ Swi_setPri()

§ Swi_inc()

§ Swi_or()

§ Swi_post()

Variable Documentation

§ Swi_numPriorities

§ Swi_hooks