Detailed Description

Cortex M3/M4 Hardware Interrupt Manager.

The Hardware Interrupt Manager provides APIs for managing hardware interrupts.

The user can dynamically assign routines that run when specific hardware interrupts occur.

Dynamic assignment of Hwi routines to interrupts at run-time is done using the Hwi_create() or Hwi_construct() functions.

Interrupt routines can be written completely in C, completely in assembly, or in a mix of C and assembly.

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 so the interrupt function can safely inter-operate with the BIOS Task and Swi schedulers.

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

Runtime Hwi Creation

Below is an example of configuring an interrupt at runtime. Usually this code would be placed in main().

#include <ti/sysbios/family/arm/m3/Hwi.h>
#include <ti/sysbios/runtime/Error.h>
Hwi_Handle myHwi;
int main(int argc, char* argv[])
{
    Hwi_Params hwiParams;
    // set the argument you want passed to your ISR function
    hwiParams.arg = 1;
    //
    // Configure interrupt 16 to invoke "myIsr".
    // Automatically enables interrupt 16 by default
    // set params.enableInt = false if you want to control
    // when the interrupt is enabled using Hwi_enableInterrupt()
    //
    myHwi = Hwi_create(16, myIsr, &hwiParams, Error_IGNORE);
    if (myHwi == NULL) {
        // handle Hwi_create failure
    }
}
void myIsr(uintptr_t arg)
{
    // here when interrupt #16 goes off
}

Below is an example of configuring the same interrupt without requiring the use of a heap.

#include <ti/sysbios/family/arm/m3/Hwi.h>
#include <ti/sysbios/runtime/Error.h>
Hwi_Struct myHwiStruct;
Hwi_Handle myHwi;
int main(int argc, char* argv[])
{
    Hwi_Params hwiParams;
    // set the argument you want passed to your ISR function
    hwiParams.arg = 1;
    //
    // Configure interrupt 16 to invoke "myIsr".
    // Automatically enables interrupt 16 by default
    // set params.enableInt = false if you want to control
    // when the interrupt is enabled using Hwi_enableInterrupt()
    //
    myHwi = Hwi_construct(&myHwiStruct, 16, myIsr, &hwiParams, Error_IGNORE);
    if (myHwi == NULL) {
        // handle Hwi_create failure
    }
}
void myIsr(uintptr_t arg)
{
    // here when interrupt #16 goes off
}

The Cortex-M devices' Nested Vectored Interrupt Controller (NVIC) supports up to 256 interrupts/exceptions. In practice, most devices support much fewer (ie the SimpleLink CC13XX/CC26XX family of devices have around 50 total interrupts defined).

SYS/BIOS Interrupt IDs or interrupt numbers correspond to an interrupt's position in the interrupt vector table.

ID 0 corresponds to vector 0 which is used by the NVIC to hold the initial (reset) stack pointer value.

ID 1 corresponds to vector 1 which is the reset vector which is usually initialized to point to an application's entry point (ie for the TI compiler tool chain, the entry point is "_c_int00")

IDs 2-13 are, by default, hard wired to the internal exception handler which will save important context information that can be viewed using the ROV tool within either the Code Composer Studio debugger or the IAR Workbench debugger.

ID 14 is the "pendSV" handler which is used exclusively by the shared interrupt dispatcher to orchestrate the execution of "Swis" posted from within interrupts, as well as to manage asynchronous task pre-emption upon returning from interrupts which have readied a task of higher priority than the task that was interrupted.

ID 15 is the SysTick timer interrupt.

ID's 16-255 are mapped to the NVIC's "User" interrupts 0-239 which are tied to platform specific interrupt sources.

Zero Latency Interrupts

The M3/M4 Hwi module supports "zero latency" interrupts. Interrupts configured with priority greater (in actual hardware priority, but lower in number) than the configured Hwi_disablePriority are NOT disabled by Hwi_disable(), and they are not managed by the internal interrupt dispatcher.

Zero Latency interrupts fall into the commonly used category of "Unmanaged Interrupts". However they are somewhat distinct from that definition in that in addition to being unmanaged, they are also almost never disabled by SYS/BIOS code, thus gaining the "Zero Latency" title.

Zero latency interrupts are distinguished from regular dispatched interrupts at create time solely by their interrupt priority being set greater than the configured Hwi_disablePriority.

Note that since zero latency interrupts don't use the dispatcher, the "arg" parameter is not functional. Also note that due to the Cortex-M's native automatic stacking of saved-by-caller C context on the way to an ISR, zero latency interrupt handlers are implemented using regular C functions (ie no 'interrupt' keyword is required).

Warning: Zero latency interrupts are NOT HANDLED by the SYS/BIOS interrupt dispatcher! Instead, they are vectored to directly. As such, and because they are NOT DISABLED BY Hwi_disable(), these interrupt handlers are SEVERELY RESTRICTED in terms of the SYS/BIOS APIs they can invoke and THREAD SAFETY MUST BE CAREFULLY CONSIDERED! See the descriptions of Hwi_disable and the configuration parameter "Hwi.disablePriority" for more details.

Interrupt Masking Options

The NVIC interrupt controller is designed for priority based interrupts.

In this Hwi module, the Hwi_maskSetting instance configuration parameter is ignored. Effectively, only the Hwi_MaskingOption_LOWER is supported.

Interrupt Priorities

In general, the NVIC supports priority values of 0 thru 255.

In practice, the number of priorities and their values are device dependent, and their nesting behaviors depend on the Hwi_priGroup setting.

For most TI MCU devices, 8 priorities are supported. A peculiarity of ARM's NVIC is that, although the priority field is an 8 bit value, the range of supported priority values are left-justified within this 8 bit field. Consequently, the 8 priority values are not 0 thru 7 as one might expect, but rather:

0x00    // highest priority, non dispatched, Zero Latency priority
0x20    // highest dispatched interrupt priority
0x40
0x60
0x80
0xa0
0xc0
0xe0    // lowest dispatched interrupt priority, (default)

Priority 0 is the highest priority and by default is reserved for zero latency interrupts (see Hwi.disablePriority configuration parameter).

See the "Cortex M4 Devices Generic User Guide" for details on the behavior of interrupt priorities and their relationship to the Hwi.priGroup setting.

Interrupt Vector Tables

SimpleLink CC13XX/CC26XX devices:

By default, two vector tables are created for SimpleLink devices:

A 15 entry boot vector table is placed at address 0x00000000 in FLASH.

A vector table of length Hwi_NUM_INTERRUPTS is placed at address 0x20000000 in RAM.

The FLASH boot vector table contains the reset vector and exception handler vectors used until the RAM based vector table is initialized.

The RAM vector table contains those same first 15 vectors plus the SysTick interrupt vector and the remainder of the user interrupt vectors.

During system startup, the NVIC Vector Table Offset Registor is intialized to point to the RAM vector table after it has been initialized.

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.

Register Function

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.

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

const Hwi = scripting.addModule("/family/arm/m3/Hwi");
Hwi.hwiHooks.create(1);
Hwi.hwiHooks[0].registerFxn = "myRegisterFxn";
Hwi.hwiHooks[0].createFxn   = "myCreateFxn";
Hwi.hwiHooks[0].beginFxn    = "myBeginFxn";
Hwi.hwiHooks[0].endFxn      = "myEndFxn";
Hwi.hwiHooks[0].deleteFxn   = "myDeleteFxn";

Leaving a subset of the hook functions undefined is ok.

Calling Context

Function	Hwi	Swi	Task	Main	Startup
Hwi_clearInterrupt	Y	Y	Y	Y	Y
Hwi_create	N	N	Y	Y	N
Hwi_disable	Y	Y	Y	Y	Y
Hwi_disableInterrupt	Y	Y	Y	Y	N
Hwi_enable	Y	Y	Y	N	N
Hwi_enableInterrupt	Y	Y	Y	Y	N
Hwi_Params_init	Y	Y	Y	Y	Y
Hwi_restore	Y	Y	Y	Y	Y
Hwi_restoreInterrupt	Y	Y	Y	Y	Y
Hwi_construct	N	N	Y	Y	N
Hwi_delete	N	N	Y	Y	N
Hwi_destruct	N	N	Y	Y	N
Hwi_getHookContext	Y	Y	Y	Y	N
Hwi_setFunc	Y	Y	Y	Y	N
Hwi_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: During xdc.runtime.Startup.lastFxns. During main(). During BIOS.startupFxns. Startup: API is callable during any of these phases: During xdc.runtime.Startup.firstFxns.

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

Include dependency graph for Hwi.h:

Go to the source code of this file.

Data Structures
struct	Hwi_HookSet
	Hwi hook set type definition. More...

struct	Hwi_Hook

struct	Hwi_StackInfo
	Structure contains Hwi stack usage info. More...

struct	Hwi_NVIC
	Nested Vectored Interrupt Controller. More...

struct	Hwi_ExcContext
	Exception Context - Register contents at the time of an exception. More...

struct	Hwi_Module_State

struct	Hwi_Struct

struct	Hwi_Params

Macros
#define	Hwi_E_badIntNum "intnum: %d is out of range"
	Error raised Error raised if an attempt is made to create a Hwi with an interrupt number greater than Hwi_NUM_INTERRUPTS - 1. More...

#define	Hwi_E_alreadyDefined "Hwi already defined: intr# %d"
	Error raised when a Hwi is already defined. More...

#define	Hwi_E_hwiLimitExceeded "Too many interrupts defined"
	Error raised when the number of interrupts being created exceeds the number supported. More...

#define	Hwi_E_exception "hardware exception id = %d, pc = 0x%08x"
	Error raised when an exception occurs. More...

#define	Hwi_E_noIsr "no ISR, id = %d, pc = 0x%08x"
	Error raised when an uninitialized interrupt occurs. More...

#define	Hwi_E_NMI "NMI: %s"
	Error raised when NMI exception occurs. More...

#define	Hwi_E_hardFault "Hard-fault: %s"
	Error raised when hard fault exception occurs. More...

#define	Hwi_E_memFault "Mem-fault: %s, addresss: 0x%08x"
	Error raised when memory fault exception occurs. More...

#define	Hwi_E_busFault "Bus-fault: %s, address: 0x%08x"
	Error raised when bus fault exception occurs. More...

#define	Hwi_E_usageFault "Usage-fault: %s"
	Error raised when usage fault exception occurs. More...

#define	Hwi_E_svCall "SvCall: svNum = %d"
	Error raised when svCall exception occurs. More...

#define	Hwi_E_debugMon "Debug-monitor: %s"
	Error raised when debugMon exception occurs. More...

#define	Hwi_E_reserved "reserved %s %d"
	Error raised when reserved exceptions occur. More...

#define	Hwi_E_stackOverflow "ISR stack overflow"
	Error raised when the ISR stack has overflowed. More...

Typedefs
typedef struct Hwi_Struct	Hwi_Struct

typedef struct Hwi_Struct	Hwi_Object

typedef Hwi_Struct *	Hwi_Handle

typedef Hwi_Struct *	Hwi_Instance

typedef struct Hwi_HookSet	Hwi_HookSet
	Hwi hook set type definition. More...

typedef struct Hwi_Module_State	Hwi_Module_State

typedef struct Hwi_Params	Hwi_Params

typedef struct Hwi_NVIC	Hwi_NVIC
	Nested Vectored Interrupt Controller. More...

typedef struct Hwi_ExcContext	Hwi_ExcContext
	Exception Context - Register contents at the time of an exception. More...

typedef struct Hwi_StackInfo	Hwi_StackInfo
	Structure contains Hwi stack usage info. More...

typedef void(*	Hwi_FuncPtr) (uintptr_t)
	Hwi create function type definition. More...

typedef void(*	Hwi_VectorFuncPtr) (void)
	Hwi vector function type definition. More...

typedef void(*	Hwi_ExceptionHookFuncPtr) (Hwi_ExcContext *arg1)
	Exception hook function type definition. More...

typedef Hwi_ExceptionHookFuncPtr	Hwi_ExcHookFunc

typedef enum Hwi_MaskingOption	Hwi_MaskingOption
	Shorthand interrupt masking options. More...

typedef void(*	Hwi_ExcHandlerFuncPtr) (unsigned int *arg1, unsigned int arg2)
	Hwi exception handler function type definition. More...

Enumerations
enum	Hwi_MaskingOption { Hwi_MaskingOption_NONE, Hwi_MaskingOption_ALL, Hwi_MaskingOption_SELF, Hwi_MaskingOption_BITMASK, Hwi_MaskingOption_LOWER }
	Interrupt masking options. More...

Functions
unsigned int	Hwi_Disable ()
	Globally disable interrupts. More...

unsigned int	Hwi_Enable ()
	Globally enable interrupts. More...

void	Hwi_Restore (uint32_t key)
	restore global interrupts to the state they were in prior Hwi_disable(). More...

Hwi_Handle	Hwi_create (int intNum, Hwi_FuncPtr hwiFxn, const Hwi_Params prms, Error_Block eb)

Hwi_Handle	Hwi_construct (Hwi_Struct obj, int intNum, Hwi_FuncPtr hwiFxn, const Hwi_Params prms, Error_Block *eb)

void	Hwi_delete (Hwi_Handle *handle)

void	Hwi_destruct (Hwi_Struct *obj)

bool	Hwi_getStackInfo (Hwi_StackInfo *stkInfo, bool computeStackDepth)
	Get Hwi stack usage Info. More...

void	Hwi_post (unsigned int intNum)
	Generate an interrupt for test purposes. More...

unsigned int	Hwi_disableInterrupt (unsigned int intNum)
	Disable a specific interrupt. More...

unsigned int	Hwi_enableInterrupt (unsigned int intNum)
	Enable a specific interrupt. More...

void	Hwi_restoreInterrupt (unsigned int intNum, unsigned int key)
	Restore a specific interrupt's enabled/disabled state. More...

void	Hwi_clearInterrupt (unsigned int intNum)
	Clear a specific interrupt. More...

Hwi_FuncPtr	Hwi_getFunc (Hwi_Handle hwi, uintptr_t *arg)
	Get Hwi function and arg. More...

void	Hwi_setFunc (Hwi_Handle hwi, Hwi_FuncPtr fxn, uintptr_t arg)
	Overwrite Hwi function and arg. More...

void *	Hwi_getHookContext (Hwi_Handle hwi, int id)
	Get hook instance's context for a Hwi. More...

void	Hwi_setHookContext (Hwi_Handle hwi, int id, void *hookContext)
	Set hook instance's context for a Hwi. More...

uintptr_t	Hwi_getIrp (Hwi_Handle hwi)
	Get address of interrupted instruction. More...

void	Hwi_plug (unsigned int intNum, void *fxn)
	Plug a non dispatched interrupt vector with an ISR address. More...

Hwi_Handle	Hwi_getHandle (unsigned int intNum)
	Returns Hwi_handle associated with intNum. More...

void	Hwi_setPriority (unsigned int intNum, unsigned int priority)
	Set an interrupt's relative priority. More...

void	Hwi_excSetBuffers (void excContextBuffer, void excStackBuffer)
	Set the exception context and stack buffer pointers. More...

void	Hwi_reconfig (Hwi_Handle hwi, Hwi_FuncPtr fxn, const Hwi_Params *params)
	Reconfigure a dispatched interrupt. More...

void	Hwi_Params_init (Hwi_Params *prms)

Hwi_Handle	Hwi_Object_first (void)

Hwi_Handle	Hwi_Object_next (Hwi_Object *obj)

Variables
volatile Hwi_NVIC	Hwi_nvic
	Physical Nested Vectored Interrupt Controller Device. short name is "Hwi_nvic" long name is "ti_sysbios_family_arm_m3_Hwi_nvic". More...

const int	Hwi_NUM_INTERRUPTS
	The Cortex M3/M4 NVIC supports up to 256 interrupts/exceptions. More...

const int	Hwi_NUM_PRIORITIES
	The Cortex M3/M4 NVIC supports up to 256 interrupt priorities. More...

const Hwi_ExcHookFunc	Hwi_excHookFunc
	User Exception hook function. More...

const unsigned int	Hwi_disablePriority
	The priority that BASEPRI is set to by Hwi_disable(). More...

const unsigned int	Hwi_priGroup
	The PRIGROUP setting. Default is 0. More...

const unsigned int	Hwi_numSparseInterrupts
	If Hwi.dispatchTableSize is initialized by the user then Hwi.numSparseInterrupts is set to the value of Hwi.dispatchTableSize. More...

Macro Definition Documentation

§ Hwi_E_badIntNum

#define Hwi_E_badIntNum "intnum: %d is out of range"

Error raised Error raised if an attempt is made to create a Hwi with an interrupt number greater than Hwi_NUM_INTERRUPTS - 1.

§ Hwi_E_alreadyDefined

#define Hwi_E_alreadyDefined "Hwi already defined: intr# %d"

Error raised when a Hwi is already defined.

§ Hwi_E_hwiLimitExceeded

#define Hwi_E_hwiLimitExceeded "Too many interrupts defined"

Error raised when the number of interrupts being created exceeds the number supported.

§ Hwi_E_exception

#define Hwi_E_exception "hardware exception id = %d, pc = 0x%08x"

Error raised when an exception occurs.

§ Hwi_E_noIsr

#define Hwi_E_noIsr "no ISR, id = %d, pc = 0x%08x"

Error raised when an uninitialized interrupt occurs.

§ Hwi_E_NMI

#define Hwi_E_NMI "NMI: %s"

Error raised when NMI exception occurs.

§ Hwi_E_hardFault

#define Hwi_E_hardFault "Hard-fault: %s"

Error raised when hard fault exception occurs.

§ Hwi_E_memFault

#define Hwi_E_memFault "Mem-fault: %s, addresss: 0x%08x"

Error raised when memory fault exception occurs.

§ Hwi_E_busFault

#define Hwi_E_busFault "Bus-fault: %s, address: 0x%08x"

Error raised when bus fault exception occurs.

§ Hwi_E_usageFault

#define Hwi_E_usageFault "Usage-fault: %s"

Error raised when usage fault exception occurs.

§ Hwi_E_svCall

#define Hwi_E_svCall "SvCall: svNum = %d"

Error raised when svCall exception occurs.

§ Hwi_E_debugMon

#define Hwi_E_debugMon "Debug-monitor: %s"

Error raised when debugMon exception occurs.

§ Hwi_E_reserved

#define Hwi_E_reserved "reserved %s %d"

Error raised when reserved exceptions occur.

§ Hwi_E_stackOverflow

#define Hwi_E_stackOverflow "ISR stack overflow"

Error raised when the ISR stack has overflowed.

Typedef Documentation

§ Hwi_Struct

typedef struct Hwi_Struct Hwi_Struct

§ Hwi_Object

typedef struct Hwi_Struct Hwi_Object

§ Hwi_Handle

typedef Hwi_Struct* Hwi_Handle

§ Hwi_Instance

typedef Hwi_Struct* Hwi_Instance

§ Hwi_HookSet

typedef struct Hwi_HookSet Hwi_HookSet

Hwi hook set type definition.

The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.

§ Hwi_Module_State

typedef struct Hwi_Module_State Hwi_Module_State

§ Hwi_Params

typedef struct Hwi_Params Hwi_Params

§ Hwi_NVIC

typedef struct Hwi_NVIC Hwi_NVIC

Nested Vectored Interrupt Controller.

§ Hwi_ExcContext

typedef struct Hwi_ExcContext Hwi_ExcContext

Exception Context - Register contents at the time of an exception.

§ Hwi_StackInfo

typedef struct Hwi_StackInfo Hwi_StackInfo

Structure contains Hwi stack usage info.

Used by getStackInfo() and viewGetStackInfo() functions

§ Hwi_FuncPtr

typedef void(* Hwi_FuncPtr) (uintptr_t)

Hwi create function type definition.

§ Hwi_VectorFuncPtr

typedef void(* Hwi_VectorFuncPtr) (void)

Hwi vector function type definition.

§ Hwi_ExceptionHookFuncPtr

typedef void(* Hwi_ExceptionHookFuncPtr) (Hwi_ExcContext *arg1)

Exception hook function type definition.

§ Hwi_ExcHookFunc

typedef Hwi_ExceptionHookFuncPtr Hwi_ExcHookFunc

§ Hwi_MaskingOption

typedef enum Hwi_MaskingOption Hwi_MaskingOption

Shorthand interrupt masking options.

§ Hwi_ExcHandlerFuncPtr

typedef void(* Hwi_ExcHandlerFuncPtr) (unsigned int *arg1, unsigned int arg2)

Hwi exception handler function type definition.

Enumeration Type Documentation

§ Hwi_MaskingOption

enum Hwi_MaskingOption

Interrupt masking options.

Enumerator
Hwi_MaskingOption_NONE	No interrupts are disabled (not support on cortexM devices)
Hwi_MaskingOption_ALL	All interrupts are disabled (not support on cortexM devices)
Hwi_MaskingOption_SELF	Only this interrupt is disabled (not support on cortexM devices)
Hwi_MaskingOption_BITMASK	User supplies interrupt enable masks (not support on cortexM devices)
Hwi_MaskingOption_LOWER	All current and lower priority interrupts are disabled. (default for all cortexM devices)

Function Documentation

§ Hwi_Disable()

unsigned int Hwi_Disable ( )

Globally disable interrupts.

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.

Warning: The cortexM implementation of Hwi_disable() sets the basepri register to the value of Hwi_disablePriority.; If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), 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.

Return values

opaque uint32_t key for use by Hwi_restore()

§ Hwi_Enable()

unsigned int Hwi_Enable ( )

Globally enable interrupts.

Hwi_enable()

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 within BIOS_start() to enable interrupts after "main()" has been executed. Prior to BIOS_start(), interrupts are globally disabled.

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

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.

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

Hwi_enable must not be called from within "main()".

§ Hwi_Restore()

void Hwi_Restore ( uint32_t key )

restore global interrupts to the state they were in prior Hwi_disable().

Hwi_restore(key)

Globally restore interrupts.

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.

The Hwi_disable() / Hwi_restore() pair may be called from within main(). However, since interrupts are globally disabled prior to main(), the call to Hwi_restore() has no effect.

key = enable/disable state to restore

§ Hwi_create()

Hwi_Handle Hwi_create	(	int	intNum,
		Hwi_FuncPtr	hwiFxn,
		const Hwi_Params *	prms,
		Error_Block *	eb
	)

§ Hwi_construct()

Hwi_Handle Hwi_construct	(	Hwi_Struct *	obj,
		int	intNum,
		Hwi_FuncPtr	hwiFxn,
		const Hwi_Params *	prms,
		Error_Block *	eb
	)

§ Hwi_delete()

void Hwi_delete ( Hwi_Handle * handle )

§ Hwi_destruct()

void Hwi_destruct ( Hwi_Struct * obj )

§ Hwi_getStackInfo()

bool Hwi_getStackInfo	(	Hwi_StackInfo *	stkInfo,
		bool	computeStackDepth
	)

Get Hwi stack usage Info.

getStackInfo returns the Hwi stack usage info to its calling function by filling stack base address, stack size and stack peak fields in the Hwi_StackInfo structure.

getStackInfo accepts two arguments, a pointer to a structure of type Hwi_StackInfo and a boolean. If the boolean is set to true, the function computes the stack depth and fills the stack peak field in the StackInfo structure. If a stack overflow is detected, the stack depth is not computed. If the boolean is set to false, the function only checks for a stack overflow.

The isr stack is always checked for an overflow and a boolean is returned to indicate whether an overflow occured.

Below is an example of calling getStackInfo() API:

#include <ti/sysbios/BIOS.h>
#include <ti/sysbios/family/arm/m3/Hwi.h>
#include <ti/sysbios/knl/Swi.h>
#include <ti/sysbios/knl/Task.h>
Swi_Handle swi0;
volatile bool swiStackOverflow = false;
void swi0Fxn(uintptr_t arg1, uintptr_t arg2)
{
    Hwi_StackInfo stkInfo;
    // Request stack depth
    swiStackOverflow = Hwi_getStackInfo(&stkInfo, true);
    // Alternately, we can omit the request for stack depth and
    // request only the stack base and stack size (the check for
    // stack overflow is always performed):
    //
    swiStackOverflow = Hwi_getStackInfo(&stkInfo, false);
    if (swiStackOverflow) {
        // isr Stack Overflow detected
    }
}
void idleTask()
{
    Swi_post(swi0);
}
int main(int argc, char* argv[])
{
    swi0 = Swi_create(swi0Fxn, NULL, NULL);
    BIOS_start();
    return (0);
}

Parameters

stkInfo	pointer to stack info structure
computeStackDepth	decides whether to compute stack depth

Return values

boolean to indicate a stack overflow

§ Hwi_post()

void Hwi_post ( unsigned int intNum )

Generate an interrupt for test purposes.

Parameters

intNum ID of interrupt to generate

§ Hwi_disableInterrupt()

unsigned int Hwi_disableInterrupt ( unsigned int intNum )

Disable a specific interrupt.

Disable a specific interrupt identified by an interrupt number.

Parameters

intNum interrupt number to disable

Return values

key	to restore previous enable/disable state

§ Hwi_enableInterrupt()

unsigned int Hwi_enableInterrupt ( unsigned int intNum )

Enable a specific interrupt.

Enables a specific interrupt identified by an interrupt number.

Parameters

intNum interrupt number to enable

Return values

key	to restore previous enable/disable state

§ Hwi_restoreInterrupt()

void Hwi_restoreInterrupt	(	unsigned int	intNum,
		unsigned int	key
	)

Restore a specific interrupt's enabled/disabled state.

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

Parameters

intNum	interrupt number to restore
key	key returned from enableInt or disableInt

§ Hwi_clearInterrupt()

void Hwi_clearInterrupt ( unsigned int intNum )

Clear a specific interrupt.

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

Parameters

intNum interrupt number to clear

§ Hwi_getFunc()

Hwi_FuncPtr Hwi_getFunc	(	Hwi_Handle	hwi,
		uintptr_t *	arg
	)

Get Hwi function and arg.

Parameters

hwi	Hwi handle
arg	pointer for returning hwi's ISR function argument

Return values

hwi's ISR function

§ Hwi_setFunc()

void Hwi_setFunc	(	Hwi_Handle	hwi,
		Hwi_FuncPtr	fxn,
		uintptr_t	arg
	)

Overwrite Hwi function and arg.

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

Precondition: Hwi_setFunc() is not thread safe. This means that the new value for for 'fxn' may be temporarily paired with the previous value for 'arg' if pre-emption occurs within the execution of Hwi_setFunc().

To guard against this condition, surround the Hwi_setFunc() call with calls to Hwi_disable() and Hwi_restore():

key = Hwi_disable();
Hwi_setFunc(newFunc, newArg);
Hwi_restore(key);

Parameters

hwi	Hwi handle
fxn	pointer to ISR function
arg	argument to ISR function

§ Hwi_getHookContext()

void* Hwi_getHookContext	(	Hwi_Handle	hwi,
		int	id
	)

Get hook instance's context for a Hwi.

Parameters

hwi	Hwi handle
id	hook id

Return values

hook	instance's context for hwi

§ Hwi_setHookContext()

void Hwi_setHookContext	(	Hwi_Handle	hwi,
		int	id,
		void *	hookContext
	)

Set hook instance's context for a Hwi.

Parameters

hwi	Hwi handle
id	hook id
hookContext	value to write to context

§ Hwi_getIrp()

uintptr_t Hwi_getIrp ( Hwi_Handle hwi )

Get address of interrupted instruction.

Parameters

hwi	Hwi handle

Return values

most	current IRP of a Hwi

§ Hwi_plug()

void Hwi_plug	(	unsigned int	intNum,
		void *	fxn
	)

Plug a non dispatched interrupt vector with an ISR address.

Used internally by Hwi_create() and Hwi_construct().

This API is provided for external use primarily to allow users to plug the NMI vector (interrupt #2) at runtime.

Note: Interrupt vectors plugged using Hwi_plug() are NOT managed by the Hwi interrupt dispatcher. Consequently, it is not safe to call SYS/BIOS APIs from within these ISRs.

Parameters

intNum	interrupt number
fxn	pointer to ISR function

§ Hwi_getHandle()

Hwi_Handle Hwi_getHandle ( unsigned int intNum )

Returns Hwi_handle associated with intNum.

Parameters

intNum interrupt number

Return values

Hwi handle

§ Hwi_setPriority()

void Hwi_setPriority	(	unsigned int	intNum,
		unsigned int	priority
	)

Set an interrupt's relative priority.

Valid priorities are 0 - 255. 0 is highest priority.

Warning: Setting the priority of a dispatched Hwi to a value higher than Hwi_disablePriority will make it become non-maskable by Hwi_disable. The behavior of your application after that will be unpredictable and will likely yield catastrophic results!

Parameters

intNum	ID of interrupt
priority	priority

§ Hwi_excSetBuffers()

void Hwi_excSetBuffers	(	void *	excContextBuffer,
		void *	excStackBuffer
	)

Set the exception context and stack buffer pointers.

Parameters

excContextBuffer	Address to place ExcContext
excStackBuffer	Address to place ExcStack

§ Hwi_reconfig()

void Hwi_reconfig	(	Hwi_Handle	hwi,
		Hwi_FuncPtr	fxn,
		const Hwi_Params *	params
	)

Reconfigure a dispatched interrupt.

Parameters

hwi	Hwi handle
fxn	Hwi function
params	pointer to Hwi params structure

§ Hwi_Params_init()

void Hwi_Params_init ( Hwi_Params * prms )

§ Hwi_Object_first()

Hwi_Handle Hwi_Object_first ( void )

§ Hwi_Object_next()

Hwi_Handle Hwi_Object_next ( Hwi_Object * obj )

Variable Documentation

§ Hwi_nvic

volatile Hwi_NVIC Hwi_nvic

Physical Nested Vectored Interrupt Controller Device. short name is "Hwi_nvic" long name is "ti_sysbios_family_arm_m3_Hwi_nvic".

§ Hwi_NUM_INTERRUPTS

const int Hwi_NUM_INTERRUPTS

The Cortex M3/M4 NVIC supports up to 256 interrupts/exceptions.

The actual number supported is device specific and provided by the catalog device specification.

§ Hwi_NUM_PRIORITIES

const int Hwi_NUM_PRIORITIES

The Cortex M3/M4 NVIC supports up to 256 interrupt priorities.

The actual number supported is device specific and provided by the catalog device specification. For all TI SimpleLink devices, 8 priorities are supported.

§ Hwi_excHookFunc

const Hwi_ExcHookFunc Hwi_excHookFunc

User Exception hook function.

Called just after the exception context has been initialized.

This function will be run on the ISR stack.

This function must run to completion.

It is called without any Task or Swi scheduling protection and therefore can not call any functions that may cause a Swi or Task scheduling operation (Swi_post(), Semaphore_post(), Event_post(), etc).

§ Hwi_disablePriority

const unsigned int Hwi_disablePriority

The priority that BASEPRI is set to by Hwi_disable().

All interrupts configured with equal or less priority (equal or higher number) than disablePriority are disabled by Hwi_disable. Interrupts configured with higher priority (smaller number) than Hwi.disablePriority are non-maskable (ie zero-latency).

The default setting is the second highest interrupt priority defined for the device (typically '0x20' for devices which support 8 priority values). This results in priority 0 (and all other values in the same priority group, ie 0x00 thru 0x1f) being the zero-latency, non-maskable interrupt priority. All other priorities are disabled with Hwi_disable().

The constant Hwi_disablePriority is configured within the app.syscfg file using the following syntax:

const Hwi = scripting.addModule("/family/arm/m3/Hwi");

Hwi.disablePriority = 0x20;

§ Hwi_priGroup

const unsigned int Hwi_priGroup

The PRIGROUP setting. Default is 0.

This value will be written to the PRIGROUP field within the NVIC's Application Interrupt and Reset Control Register (Hwi_nvic.AIRCR). It defines how the 8 bit priority values are interpreted by the hardware.

Valid settings are 0-7.

The default setting of 0 causes bits 7-1 of an interrupt's priority value to be used as pre-emption priority, while bit 0 is used to determine which of two simultaneous interrupts with the same pre-emption priority will be serviced first.

For most TI MCU devices, this means that each of the 8 supported priority values are unique pre-emption priorities and are not subdivided into priority groups.

See the "AIRCR" register description in the Arm "Cortex M4 Devices Generic User Guide" for more details regarding priority groups.

The constant Hwi_priGroup is configured within the app.syscfg file using the following syntax:

const Hwi = scripting.addModule("/family/arm/m3/Hwi");

Hwi.priGroup = 0;

§ Hwi_numSparseInterrupts

const unsigned int Hwi_numSparseInterrupts

If Hwi.dispatchTableSize is initialized by the user then Hwi.numSparseInterrupts is set to the value of Hwi.dispatchTableSize.

If Hwi.dispatchTableSize is NOT set by the user, the normal intNum-indexed Hwi dispatchTable mechanism is used by the dispatcher to find the corresponding Hwi object.

If Hwi.dispatchTableSize is set by the user, then a RAM-based fixed sized interrupt jump table is generated that contains a repeating pattern of the following 3 word assembly code snippets:

hwiX: ldr r3, hwiObjectX ldr pc, ti_sysbios_family_arm_m3_Hwi_dispatch__I hwiObjectX: .word 0 hwiY: ldr r3, hwiObjectY ldr pc, ti_sysbios_family_arm_m3_Hwi_dispatch__I hwiObjectY: .word 0

Each dispatched interrupt vector is then initialized to point to one of these tuples, and the address of the corresponding Hwi object is written into the hwiObjectX field.

The low level assembly code in Hwi_dispatch__I preserves the value of r3 when it calls Hwi_dispatchC(), which results in the Hwi object being passed as the arg3.

Depending on the boolean value of Hwi_numSparseInterrupts, the dispatcher either uses the value passed in arg3 as the Hwi object, or uses intNum to index into the standard dispatchTable to fetch the Hwi object.

Detailed Description

Runtime Hwi Creation

Zero Latency Interrupts

Interrupt Masking Options

Interrupt Priorities

Interrupt Vector Tables

Hook Functions

Calling Context

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

§ Hwi_E_badIntNum

§ Hwi_E_alreadyDefined

§ Hwi_E_hwiLimitExceeded

§ Hwi_E_exception

§ Hwi_E_noIsr

§ Hwi_E_NMI

§ Hwi_E_hardFault

§ Hwi_E_memFault

§ Hwi_E_busFault

§ Hwi_E_usageFault

§ Hwi_E_svCall

§ Hwi_E_debugMon

§ Hwi_E_reserved

§ Hwi_E_stackOverflow

Typedef Documentation

§ Hwi_Struct

§ Hwi_Object

§ Hwi_Handle

§ Hwi_Instance

§ Hwi_HookSet

§ Hwi_Module_State

§ Hwi_Params

§ Hwi_NVIC

§ Hwi_ExcContext

§ Hwi_StackInfo

§ Hwi_FuncPtr

§ Hwi_VectorFuncPtr

§ Hwi_ExceptionHookFuncPtr

§ Hwi_ExcHookFunc

§ Hwi_MaskingOption

§ Hwi_ExcHandlerFuncPtr

Enumeration Type Documentation

§ Hwi_MaskingOption

Function Documentation

§ Hwi_Disable()

§ Hwi_Enable()

§ Hwi_Restore()

§ Hwi_create()

§ Hwi_construct()

§ Hwi_delete()

§ Hwi_destruct()

§ Hwi_getStackInfo()

§ Hwi_post()

§ Hwi_disableInterrupt()

§ Hwi_enableInterrupt()

§ Hwi_restoreInterrupt()

§ Hwi_clearInterrupt()

§ Hwi_getFunc()

§ Hwi_setFunc()

§ Hwi_getHookContext()

§ Hwi_setHookContext()

§ Hwi_getIrp()

§ Hwi_plug()

§ Hwi_getHandle()

§ Hwi_setPriority()

§ Hwi_excSetBuffers()

§ Hwi_reconfig()

§ Hwi_Params_init()

§ Hwi_Object_first()

§ Hwi_Object_next()

Variable Documentation

§ Hwi_nvic

§ Hwi_NUM_INTERRUPTS

§ Hwi_NUM_PRIORITIES

§ Hwi_excHookFunc