interface ti.sysbios.interfaces.IHwi

Interrupt routines can be written completely in assembly, completely in C, or in a mix of assembly and C. In order to support interrupt routines written completely in C, an interrupt dispatcher is provided that performs the requisite prolog and epilog for an interrupt routine.

Some routines are assigned to interrupts by the other BIOS modules. For example, the Clock module configures its own timer interrupt handler. See the Clock Module for more details.

Hook Functions

Sets of hook functions can be specified for the Hwi module using the configuration tool. Each set contains these hook functions:

Register: A function called before any statically created hwis are initialized at runtime. The register hook is called at boot time before main() and before interrupts are enabled.
Create: A function that is called when a hwi is created. This includes hwis that are created statically and those created dynamically using Hwi_create.
Begin: A function that is called just prior to running a hwi.
End: A function that is called just after a hwi finishes.
Delete: A function that is called when a hwi is deleted at run-time with Hwi_delete.

The Register function is provided to allow a hook set to store its hookset ID. This id can be passed to Hwi_setHookContext and Hwi_getHookContext to set or get hookset-specific context. The Register function must be specified if the hook implementation needs to use Hwi_setHookContext or Hwi_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 Hwi is created or deleted. They are called with interrupts enabled (unless called at boot time or from main()).

  Void myCreateFxn(Hwi_Handle hwi, Error_Block *eb);

  Void myDeleteFxn(Hwi_Handle hwi);

Begin and End Functions

The beginFxn and endFxn function hooks are called with interrupts globally disabled, therefore any hook processing function will contribute to the overall system interrupt response latency. In order to minimize this impact, carefully consider the processing time spent in an Hwi beginFxn or endFxn function hook.

  Void myBeginFxn(Hwi_Handle hwi);

  Void myEndFxn(Hwi_Handle hwi);

Hook functions can only be configured statically.

enum IHwi.MaskingOption

index URL

Shorthand interrupt masking options

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

enum MaskingOption {

MaskingOption_NONE,

// No interrupts are disabled

MaskingOption_ALL,

// All interrupts are disabled

MaskingOption_SELF,

// Only this interrupt is disabled

MaskingOption_BITMASK,

// User supplies IER masks

MaskingOption_LOWER

// All current and lower priority interrupts are disabled. Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF

};

typedef IHwi.FuncPtr

index URL

Hwi create function type definition

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

typedef Void (*FuncPtr)(UArg);

typedef IHwi.Irp

index URL

Interrupt Return Pointer. This is the address of the interrupted instruction

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

typedef UArg Irp;

struct IHwi.HookSet

index URL

Hwi hook set type definition

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

struct HookSet {

Void (*registerFxn)(Int);

Void (*createFxn)(IHwi.Handle,Error.Block*);

Void (*beginFxn)(IHwi.Handle);

Void (*endFxn)(IHwi.Handle);

Void (*deleteFxn)(IHwi.Handle);

};

config IHwi.dispatcherAutoNestingSupport // module-wide

index URL

Include interrupt nesting logic in interrupt dispatcher? Default is true

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

config Bool dispatcherAutoNestingSupport = true;

DETAILS

This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.

Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.

Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.

config IHwi.dispatcherIrpTrackingSupport // module-wide

index URL

This dispatcher configuration option controls whether the dispatcher retains the interrupted thread's return address. This option is enabled by default

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

config Bool dispatcherIrpTrackingSupport = true;

DETAILS

Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.

The application can get an interrupt's most recent return address using the getIrp API.

config IHwi.dispatcherSwiSupport // module-wide

index URL

Include Swi scheduling logic in interrupt dispatcher? Default is inherited from BIOS.swiEnabled, which is true by default

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

config Bool dispatcherSwiSupport;

DETAILS

This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swi's will not be posted from any of their Hwi threads.

Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.

config IHwi.dispatcherTaskSupport // module-wide

index URL

Include Task scheduling logic in interrupt dispatcher? Default is inherited from BIOS.taskEnabled, which is true by default

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

config Bool dispatcherTaskSupport;

DETAILS

This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.

Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.

metaonly config IHwi.common$ // module-wide

index URL

Common module configuration parameters

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

metaonly config Types.Common$ common$;

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.

IHwi.clearInterrupt( ) // module-wide

index URL

Clear a specific interrupt

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

Void clearInterrupt( UInt intNum );

ARGUMENTS

intNum — interrupt number to enable

DETAILS

Clears a specific interrupt's pending status. The implementation is family specific.

IHwi.disable( ) // module-wide

index URL

Globally disable interrupts

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

UInt disable( );

RETURNS

opaque key for use by Hwi_restore()

DETAILS

Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().

Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.

Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.

A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.

Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.

CONSTRAINTS

If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.

Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.

IHwi.disableInterrupt( ) // module-wide

index URL

Disable a specific interrupt

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

UInt disableInterrupt( UInt intNum );

ARGUMENTS

intNum — interrupt number to disable

RETURNS

key to restore previous enable/disable state

DETAILS

Disable a specific interrupt identified by an interrupt number.

IHwi.enable( ) // module-wide

index URL

Globally enable interrupts

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

UInt enable( );

RETURNS

opaque key for use by Hwi_restore()

DETAILS

Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().

This function is called as part of BIOS Startup_POST_APP_MAIN phase.

Hardware interrupts are enabled unless a call to Hwi_disable disables them.

A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.

Any call to Hwi_enable enables interrupts, even if Hwi_disable has been called several times.

Hwi_enable must not be called from main().

IHwi.enableInterrupt( ) // module-wide

index URL

Enable a specific interrupt

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

UInt enableInterrupt( UInt intNum );

ARGUMENTS

intNum — interrupt number to enable

RETURNS

key to restore previous enable/disable state

DETAILS

Enables a specific interrupt identified by an interrupt number.

IHwi.restore( ) // module-wide

index URL

Globally restore interrupts

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

Void restore( UInt key );

ARGUMENTS

key — enable/disable state to restore

DETAILS

Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.

A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.

Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.

IHwi.restoreInterrupt( ) // module-wide

index URL

Restore a specific interrupt's enabled/disabled state

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

Void restoreInterrupt( UInt intNum, UInt key );

ARGUMENTS

intNum — interrupt number to restore

key — key returned from enableInt or disableInt

DETAILS

Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked

IHwi.startup( ) // module-wide

index URL

Initially enable interrupts

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

Void startup( );

DETAILS

Called within BIOS_start

metaonly IHwi.addHookSet( ) // module-wide

index URL

addHookSet is used in a config file to add a hook set (defined by struct HookSet)

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

metaonly Void addHookSet( IHwi.HookSet hook );

ARGUMENTS

hook — structure of type HookSet

DETAILS

HookSet structure elements may be omitted, in which case those elements will not exist.

per-instance object types

index URL

C synopsis target-domain

typedef struct IHwi_Object *IHwi_Handle;

// Client reference to an abstract instance object

per-instance config parameters

index URL

XDCscript usage meta-domain

var params = new IHwi.Params;

// Instance config-params object

params.arg = UArg 0;

// ISR function argument. Default is 0

params.enableInt = Bool true;

// Enable this interrupt now? Default is true

params.eventId = Int -1;

// Interrupt event ID (Interrupt Selection Number) Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored

params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;

// maskSetting. Default is {@link #MaskingOption Hwi_MaskingOption_SELF}

params.priority = Int -1;

// Interrupt priority. Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored

C synopsis target-domain

typedef struct IHwi_Params {

// Instance config-params structure

IInstance_Params *instance;

// Common per-instance configs

UArg arg;

// ISR function argument. Default is 0

Bool enableInt;

// Enable this interrupt now? Default is true

Int eventId;

// Interrupt event ID (Interrupt Selection Number) Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored

IHwi_MaskingOption maskSetting;

// maskSetting. Default is {@link #MaskingOption Hwi_MaskingOption_SELF}

Int priority;

// Interrupt priority. Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored

} IHwi_Params;

config IHwi.arg // per-instance

index URL

ISR function argument. Default is 0

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

config UArg arg = 0;

config IHwi.enableInt // per-instance

index URL

Enable this interrupt now? Default is true

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

config Bool enableInt = true;

config IHwi.eventId // per-instance

index URL

Interrupt event ID (Interrupt Selection Number) Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

config Int eventId = -1;

config IHwi.maskSetting // per-instance

index URL

maskSetting. Default is Hwi_MaskingOption_SELF

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

config IHwi.MaskingOption maskSetting = IHwi.MaskingOption_SELF;

config IHwi.priority // per-instance

index URL

Interrupt priority. Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

config Int priority = -1;

per-instance creation

index URL

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

create( Int intNum, IHwi.FuncPtr hwiFxn );

// Create an instance-object

ARGUMENTS

intNum — interrupt number

hwiFxn — pointer to ISR function

DETAILS

A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.

If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the Hwi's dispatcher properties are specified by a structure of type Hwi_Params.

The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.

The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.

The enableInt element determines whether the interrupt should be enabled in the IER by create.

Hwi_create returns a pointer to the created Hwi object.

IHwi.getFunc( ) // per-instance

index URL

Get Hwi function and arg

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

IHwi.FuncPtr getFunc( UArg *arg );

ARGUMENTS

arg — pointer for returning hwi's ISR function argument

RETURNS

hwi's ISR function

IHwi.getHookContext( ) // per-instance

index URL

Get hook instance's context for a hwi

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

Ptr getHookContext( Int id );

RETURNS

hook instance's context for hwi

IHwi.getIrp( ) // per-instance

index URL

Get address of interrupted instruction

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

IHwi.Irp getIrp( );

RETURNS

most current IRP of a hwi

IHwi.setFunc( ) // per-instance

index URL

Overwrite Hwi function and arg

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

Void setFunc( IHwi.FuncPtr fxn, UArg arg );

ARGUMENTS

fxn — pointer to ISR function

arg — argument to ISR function

DETAILS

Replaces a Hwi object's hwiFxn function originally provided in create.

IHwi.setHookContext( ) // per-instance

index URL

Set hook instance's context for a hwi

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc

Void setHookContext( Int id, Ptr hookContext );

ARGUMENTS

id — hook instance's ID

hookContext — value to write to context

generated on Mon, 21 Dec 2009 19:43:38 GMT